Hugging Face's logo

Spaces:
byte-vortex
/
Myco
Sleeping

App Files Community
Myco / README.md
byte-vortex's picture
byte-vortex
Deploy Myco from CI
1dc5d66 verified
preview code
|
Raw
History Blame
3.3 kB
metadata 
title: Myco
emoji: 🍄
colorFrom: pink
colorTo: green
sdk: gradio
sdk_version: 6.16.0
app_file: app.py
pinned: false

🍄 Myco

Myco is a small Gradio game for Hugging Face Spaces. Explore a cozy forest with Myco, discover strange mushrooms, ask about them, study them, and collect them in your MycoDex.

Live Space: https://huggingface.co/spaces/byte-vortex/Myco

Hackathon Direction

Myco is built for Hugging Face's Build Small hackathon and the OpenAI Codex prize track. The project optimizes for one polished, memorable mechanic instead of a large feature list: a whimsical AI mushroom companion that makes each forest discovery feel playful, personal, and shareable.

Design decisions should prioritize:

  • Delight: create a 10-second hook that makes the player smile.
  • AI as the experience: Myco's companion voice should feel central, not like a generic chatbot wrapper.
  • Originality: keep the mushroom-companion game strange, cozy, and memorable.
  • Polish: maintain a smooth Gradio Space with clear onboarding, responsive UI, and a strong visual identity.
  • Small scope: prefer one unforgettable loop over many unfinished mechanics.

First Play Loop

  1. Click Start Exploring.
  2. Discover a mushroom.
  3. Ask Myco about it.
  4. Choose Study, Collect, or Eat.
  5. Build your MycoDex and unlock forest progress.

What is included

  • Gradio app entrypoint: app.py
  • UI code: ui/
  • Game logic: game/
  • Mushroom model: models/
  • Mushroom catalog: data/mushrooms.json
  • Regression tests: tests/test_myco_core.py
  • Runtime dependency: requirements.txt

Hugging Face AI companion

Myco uses the Hugging Face Inference API for both first-discovery reactions and chat replies when a token is configured in the Space. Add these Space variables/secrets:

  • HF_TOKEN=<your Hugging Face access token>
  • Optional: MYCO_HF_MODEL_ID=openai/gpt-oss-20b

The default model is set in code as DEFAULT_HF_MODEL_ID = "openai/gpt-oss-20b". The app still has a local safety fallback for development and outage protection: if the token is missing or the selected model errors, Myco answers with the built-in cautious companion response instead of crashing.

Local development 

pip install -r requirements.txt
python -m unittest discover -v
python app.py

Run tests before launching, then open the local Gradio URL printed in the terminal.

Hugging Face Space

This repo is intended to run directly as a Gradio Space. Hugging Face Spaces reads the metadata at the top of this README, installs requirements.txt, and runs app.py.

No GitHub Actions deployment workflow is required. To deploy manually:

  1. Create or open the Space at https://huggingface.co/spaces/byte-vortex/Myco.
  2. Make sure the Space SDK is Gradio.
  3. Upload or push this repository's files to the Space repository.
  4. The Space should install gradio==6.16.0 from requirements.txt and start from app.py.

The required runtime files are README.md, app.py, requirements.txt, data/, game/, models/, and ui/.

Optional deploy helper

scripts/deploy_space.py is optional. It skips safely when HF_BUILD_SMALL_HACKATHON_TOKEN is not configured, and uploads to byte-vortex/Myco only when that token is present.