---
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.