Spaces:
Sleeping
Sleeping
| title: Myco - Tiny AI Mushroom Companion | |
| emoji: 🍄 | |
| colorFrom: red | |
| colorTo: green | |
| sdk: gradio | |
| sdk_version: 6.16.0 | |
| app_file: app.py | |
| pinned: false | |
| license: mit | |
| short_description: Build Small Hackathon | |
| tags: | |
| - thousand-token-wood | |
| - track:wood | |
| - sponsor:openai | |
| - achievement:offgrid | |
| - achievement:offbrand | |
| - achievement:sharing | |
| - achievement:fieldnotes | |
| datasets: | |
| - build-small-hackathon/Myco | |
| # ❋ Thousand Token Wood Submission | |
| *The Whimsical Track: Whimsical, delightful, AI-native apps that push the boundaries of fun. Wander somewhere stranger and show off what small models can dream up.* | |
| --- | |
| ## 🎖️ Achieved Merit Badges | |
| *Stack 'em on your sash! Hover a patch to see it lift.* | |
| <div style="display: flex; flex-wrap: wrap; gap: 15px; margin: 20px 0;"> | |
| <div style="flex: 1; min-width: 200px; padding: 15px; border: 1px solid #e5e7eb; border-radius: 12px; transition: transform 0.2s ease, box-shadow 0.2s ease; cursor: pointer; background: #fff;" onmouseover="this.style.transform='translateY(-5px)'; this.style.boxShadow='0 10px 15px -3px rgba(0,0,0,0.1)'" onmouseout="this.style.transform='translateY(0)'; this.style.boxShadow='none'"> | |
| <div style="font-size: 24px; margin-bottom: 5px;">🐜</div> | |
| <strong>Tiny Titan</strong> | |
| <p style="font-size: 12px; color: #6b7280; margin: 5px 0 0 0;"><strong>Genuinely tiny:</strong> Myco's brain is <code>google/gemma-3-1b-it</code> — a 1B-parameter open-weight model, well under the 4B bar.</p> | |
| </div> | |
| <div style="flex: 1; min-width: 200px; padding: 15px; border: 1px solid #e5e7eb; border-radius: 12px; transition: transform 0.2s ease, box-shadow 0.2s ease; cursor: pointer; background: #fff;" onmouseover="this.style.transform='translateY(-5px)'; this.style.boxShadow='0 10px 15px -3px rgba(0,0,0,0.1)'" onmouseout="this.style.transform='translateY(0)'; this.style.boxShadow='none'"> | |
| <div style="font-size: 24px; margin-bottom: 5px;">🎯</div> | |
| <strong>Off the Grid</strong> | |
| <p style="font-size: 12px; color: #6b7280; margin: 5px 0 0 0;"><strong>Local-first:</strong> No cloud APIs. <code>google/gemma-3-1b-it</code> loads via <code>transformers</code> and runs entirely local on the host environment.</p> | |
| </div> | |
| <div style="flex: 1; min-width: 200px; padding: 15px; border: 1px solid #e5e7eb; border-radius: 12px; transition: transform 0.2s ease, box-shadow 0.2s ease; cursor: pointer; background: #fff;" onmouseover="this.style.transform='translateY(-5px)'; this.style.boxShadow='0 10px 15px -3px rgba(0,0,0,0.1)'" onmouseout="this.style.transform='translateY(0)'; this.style.boxShadow='none'"> | |
| <div style="font-size: 24px; margin-bottom: 5px;">🎨</div> | |
| <strong>Off-Brand</strong> | |
| <p style="font-size: 12px; color: #6b7280; margin: 5px 0 0 0;"><strong>Custom UI:</strong> A hand-built forest scene, status panels, and live AI log — well past default Gradio styling.</p> | |
| </div> | |
| <div style="flex: 1; min-width: 200px; padding: 15px; border: 1px solid #e5e7eb; border-radius: 12px; transition: transform 0.2s ease, box-shadow 0.2s ease; cursor: pointer; background: #fff;" onmouseover="this.style.transform='translateY(-5px)'; this.style.boxShadow='0 10px 15px -3px rgba(0,0,0,0.1)'" onmouseout="this.style.transform='translateY(0)'; this.style.boxShadow='none'"> | |
| <div style="font-size: 24px; margin-bottom: 5px;">🧠</div> | |
| <strong>Codex Co-Author</strong> | |
| <p style="font-size: 12px; color: #6b7280; margin: 5px 0 0 0;"><strong>Best Use of Codex:</strong> Developed and structured using Codex for workspace orchestration and environment testing.</p> | |
| </div> | |
| <div style="flex: 1; min-width: 200px; padding: 15px; border: 1px solid #e5e7eb; border-radius: 12px; transition: transform 0.2s ease, box-shadow 0.2s ease; cursor: pointer; background: #fff;" onmouseover="this.style.transform='translateY(-5px)'; this.style.boxShadow='0 10px 15px -3px rgba(0,0,0,0.1)'" onmouseout="this.style.transform='translateY(0)'; this.style.boxShadow='none'"> | |
| <div style="font-size: 24px; margin-bottom: 5px;">📡</div> | |
| <strong>Sharing is Caring</strong> | |
| <p style="font-size: 12px; color: #6b7280; margin: 5px 0 0 0;"><strong>Open trace:</strong> Shared comprehensive agent execution traces on the Hub for open community learning.</p> | |
| </div> | |
| </div> | |
| --- | |
| ## 🌐 Community Links | |
| * **📺 Video Walkthrough:** [Watch the Myco Demo on YouTube](https://youtu.be/uTlIWqJA9RQ) | |
| * **🔗 Read the LinkedIn post:** [Read the full project post on LinkedIn](https://www.linkedin.com/posts/noriko-kono_huggingface-gradio-gemma3-share-7472374564023427072-C64t/?utm_source=share&utm_medium=member_desktop&rcm=ACoAADV81lIBHfqnWPcrqTwi8q3nrm4-wpvkldE) | |
| --- | |
| # 🍄 Myco — Tiny AI Mushroom Companion | |
| Myco is a small Gradio AI Companion 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. | |
| **Live Space:** https://huggingface.co/spaces/build-small-hackathon/Myco | |
| ## Hackathon direction | |
| 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. | |
| Design decisions prioritize: | |
| - **Delight:** a 10-second hook that makes the player smile. | |
| - **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. | |
| - **Originality:** keep the mushroom-companion game strange, cozy, and memorable. | |
| - **Polish:** a smooth Gradio Space with clear onboarding, responsive UI, and a strong visual identity. | |
| - **Small scope:** one unforgettable loop over many unfinished mechanics. | |
| Bonus quests this project aims for: | |
| - 🐜 **Tiny Titan** — Myco runs on `google/gemma-3-1b-it`, a genuinely tiny (1B-parameter) model. | |
| - 🔌 **Off the Grid** — the model runs locally via `transformers`, with no cloud inference API calls. | |
| ## First play loop | |
| 1. Open the **Play** tab and click **🎮 Search Clearing** — mushrooms sprout across the forest grid. | |
| 2. Move Myco with the arrow buttons, or let Myco roam the clearing on its own every few seconds. | |
| 3. Walk Myco onto a mushroom to collect it automatically, or use **🔍 Study**, **🧺 Collect**, **🍄 Pick**, or **🌌 Follow Whisper** on the current discovery. | |
| 4. **🍽️ Eat?** is always refused — Myco panics (in character) and tells you to study an unidentified mushroom before trying anything like that. | |
| 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]`. | |
| 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. | |
| 7. Step on (or pick) a poisonous mushroom and it's Game Over — the scene fades to red until you search a new clearing. | |
| ## What's included | |
| - Gradio app entrypoint: `app.py` | |
| - Game engine + AI: `game/engine.py` | |
| - Mushroom catalog & progression state: `game/` | |
| - Mushroom data model: `models/` | |
| - Mushroom catalog data: `data/mushrooms.json` | |
| - UI rendering: `ui/renderers.py` (forest scene, status panels, MycoDex, world map) | |
| - Magic Mushroom Garden tab: `ui/interface.py` | |
| - Runtime dependencies: `requirements.txt` | |
| ## Myco's AI companion | |
| 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. | |
| 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. | |
| ## 🤖 AI-Assisted Development & Codex Attribution | |
| This repository was developed using **OpenAI Codex** and other assistant AI agents to co-author core Python scripts, streamline state routing, and manage structured code execution. Full logs and interactive context are structurally documented in our `CODEx_USAGE.md` file. | |