byte-vortex commited on
Commit
faf2dff
ยท
verified ยท
1 Parent(s): f082410

Deploy Myco from CI

Browse files
Files changed (1) hide show
  1. README.md +43 -37
README.md CHANGED
@@ -9,76 +9,82 @@ app_file: app.py
9
  pinned: false
10
  ---
11
 
12
- # ๐Ÿ„ Myco
13
 
14
- 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.
15
 
16
  **Live Space:** https://huggingface.co/spaces/byte-vortex/Myco
17
 
 
18
 
19
- ## Hackathon Direction
20
 
21
- 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.
22
-
23
- Design decisions should prioritize:
24
-
25
- - **Delight:** create a 10-second hook that makes the player smile.
26
- - **AI as the experience:** Myco's companion voice should feel central, not like a generic chatbot wrapper.
27
  - **Originality:** keep the mushroom-companion game strange, cozy, and memorable.
28
- - **Polish:** maintain a smooth Gradio Space with clear onboarding, responsive UI, and a strong visual identity.
29
- - **Small scope:** prefer one unforgettable loop over many unfinished mechanics.
 
 
 
 
30
 
31
- ## First Play Loop
32
 
33
- 1. Click **Start Exploring**.
34
- 2. Discover a mushroom.
35
- 3. Ask Myco about it.
36
- 4. Choose **Study**, **Collect**, or **Eat**.
37
- 5. Build your **MycoDex** and unlock forest progress.
 
 
38
 
39
- ## What is included
40
 
41
  - Gradio app entrypoint: `app.py`
42
- - UI code: `ui/`
43
- - Game logic: `game/`
44
- - Mushroom model: `models/`
45
- - Mushroom catalog: `data/mushrooms.json`
46
- - Regression tests: `tests/test_myco_core.py`
47
- - Runtime dependency: `requirements.txt`
 
48
 
49
- ## Hugging Face AI companion
50
 
51
- 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:
52
 
53
- - `HF_TOKEN=<your Hugging Face access token>`
54
- - Optional: `MYCO_HF_MODEL_ID=openai/gpt-oss-20b`
 
55
 
56
- 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.
 
 
57
 
58
  ## Local development
59
 
60
  ```bash
61
  pip install -r requirements.txt
62
- python -m unittest discover -v
63
  python app.py
64
  ```
65
 
66
- Run tests before launching, then open the local Gradio URL printed in the terminal.
67
 
68
  ## Hugging Face Space
69
 
70
- 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`.
71
-
72
- No GitHub Actions deployment workflow is required. To deploy manually:
73
 
 
74
  1. Create or open the Space at https://huggingface.co/spaces/byte-vortex/Myco.
75
  2. Make sure the Space SDK is **Gradio**.
76
- 3. Upload or push this repository's files to the Space repository.
77
- 4. The Space should install `gradio==6.16.0` from `requirements.txt` and start from `app.py`.
 
78
 
79
  The required runtime files are `README.md`, `app.py`, `requirements.txt`, `data/`, `game/`, `models/`, and `ui/`.
80
 
81
-
82
  ## Optional deploy helper
83
 
84
  `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.
 
9
  pinned: false
10
  ---
11
 
12
+ # ๐Ÿ„ Myco โ€” Tiny AI Mushroom Companion
13
 
14
+ Myco is a small Gradio game built for Hugging Face's **Build Small Hackathon**, entering **Chapter Two โ€” "An Adventure in Thousand Token Wood."** Wander a glowing forest with Myco, a tiny sentient mushroom companion. Discover strange mushrooms, chat with Myco about them, study and collect them, and watch Myco's live thoughts stream across the screen in real time as a small on-device AI model reacts to everything that happens.
15
 
16
  **Live Space:** https://huggingface.co/spaces/byte-vortex/Myco
17
 
18
+ ## Hackathon direction
19
 
20
+ This project targets Chapter Two of the Build Small Hackathon: *"Build something delightful that wouldn't exist without AI. Wander somewhere weirder... Strange is good. Joyful is the bar."* Myco optimizes for one polished, memorable mechanic rather than a long feature list โ€” a whimsical AI companion whose narration, in-game reactions, and chat replies are all generated live and visibly, the entire time you play.
21
 
22
+ Design decisions prioritize:
23
+ - **Delight:** a 10-second hook that makes the player smile.
24
+ - **AI as the experience:** every reaction โ€” narrative, in-game action, and chat โ€” is generated live by Myco's model and streamed to a visible live log, so the AI is never hidden behind the scenes.
 
 
 
25
  - **Originality:** keep the mushroom-companion game strange, cozy, and memorable.
26
+ - **Polish:** a smooth Gradio Space with clear onboarding, responsive UI, and a strong visual identity.
27
+ - **Small scope:** one unforgettable loop over many unfinished mechanics.
28
+
29
+ Bonus quests this project aims for:
30
+ - ๐Ÿœ **Tiny Titan** โ€” Myco runs on `google/gemma-3-1b-it`, a genuinely tiny (1B-parameter) model.
31
+ - ๐Ÿ”Œ **Off the Grid** โ€” the model runs locally via `transformers`, with no cloud inference API calls.
32
 
33
+ ## First play loop
34
 
35
+ 1. Open the **Play** tab and click **๐ŸŽฎ Search Clearing** โ€” mushrooms sprout across the forest grid.
36
+ 2. Move Myco with the arrow buttons, or let Myco roam the clearing on its own every few seconds.
37
+ 3. Walk Myco onto a mushroom to collect it automatically, or use **๐Ÿ” Study**, **๐Ÿงบ Collect**, **๐Ÿ„ Pick**, or **๐ŸŒŒ Follow Whisper** on the current discovery.
38
+ 4. **๐Ÿฝ๏ธ Eat?** is always refused โ€” Myco panics (in character) and tells you to study an unidentified mushroom before trying anything like that.
39
+ 5. Watch the live log at the bottom of the page โ€” it streams Myco's narration, in-game reactions, and chat replies as the model generates them, tagged `[NARRATIVE]`, `[ACTION]`, and `[CHAT]`.
40
+ 6. Build your **MycoDex**, unlock new areas on the **Map**, check the **Guide** for the full rundown, and visit the **๐Ÿ„ Myco** tab for the Magic Mushroom Garden.
41
+ 7. Step on (or pick) a poisonous mushroom and it's Game Over โ€” the scene fades to red until you search a new clearing.
42
 
43
+ ## What's included
44
 
45
  - Gradio app entrypoint: `app.py`
46
+ - Game engine + AI: `game/engine.py`
47
+ - Mushroom catalog & progression state: `game/`
48
+ - Mushroom data model: `models/`
49
+ - Mushroom catalog data: `data/mushrooms.json`
50
+ - UI rendering: `ui/renderers.py` (forest scene, status panels, MycoDex, world map)
51
+ - Magic Mushroom Garden tab: `ui/interface.py`
52
+ - Runtime dependencies: `requirements.txt`
53
 
54
+ ## Myco's AI companion
55
 
56
+ Myco's mind is **`google/gemma-3-1b-it`** (Gemma 3 1B Instruct), loaded **locally** via `transformers` โ€” there are no Hugging Face Inference API calls. The model runs on GPU if one is available, otherwise CPU.
57
 
58
+ Environment variables:
59
+ - `MYCO_MODEL_ID` โ€” override the model (default: `google/gemma-3-1b-it`).
60
+ - `HF_BUILD_SMALL_HACKATHON_TOKEN` โ€” Hugging Face access token used when downloading the model weights, needed if the chosen model is gated.
61
 
62
+ If the model fails to load, or a generation call errors, Myco falls back to hand-written, in-character responses for every action โ€” discovering, picking, studying, collecting, whisper-following, eating, and chatting โ€” so the game never crashes or goes silent.
63
+
64
+ Every successful generation (narrative, in-game action, or chat) is also appended to a running, tagged log that streams to the live log panel via a polling timer, so you can watch Myco "think" as it happens.
65
 
66
  ## Local development
67
 
68
  ```bash
69
  pip install -r requirements.txt
 
70
  python app.py
71
  ```
72
 
73
+ The first run downloads and loads `google/gemma-3-1b-it`, which can take a little while on CPU. Open the local Gradio URL printed in the terminal once it's ready.
74
 
75
  ## Hugging Face Space
76
 
77
+ This repo runs directly as a Gradio Space. Hugging Face Spaces reads the metadata at the top of this README, installs `requirements.txt`, and runs `app.py`.
 
 
78
 
79
+ To deploy manually:
80
  1. Create or open the Space at https://huggingface.co/spaces/byte-vortex/Myco.
81
  2. Make sure the Space SDK is **Gradio**.
82
+ 3. Set the `HF_BUILD_SMALL_HACKATHON_TOKEN` secret if `google/gemma-3-1b-it` requires accepting Gemma's license on your account.
83
+ 4. Upload or push this repository's files to the Space repository.
84
+ 5. The Space installs `gradio==6.16.0` plus `transformers`/`torch` from `requirements.txt` and starts from `app.py`.
85
 
86
  The required runtime files are `README.md`, `app.py`, `requirements.txt`, `data/`, `game/`, `models/`, and `ui/`.
87
 
 
88
  ## Optional deploy helper
89
 
90
  `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.