Spaces:
Sleeping
Sleeping
| 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 | |
| ```bash | |
| 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. | |