Spaces:
Sleeping
A newer version of the Gradio SDK is available: 6.19.0
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.
Genuinely tiny: Myco's brain is google/gemma-3-1b-it — a 1B-parameter open-weight model, well under the 4B bar.
Local-first: No cloud APIs. google/gemma-3-1b-it loads via transformers and runs entirely local on the host environment.
Custom UI: A hand-built forest scene, status panels, and live AI log — well past default Gradio styling.
Best Use of Codex: Developed and structured using Codex for workspace orchestration and environment testing.
Open trace: Shared comprehensive agent execution traces on the Hub for open community learning.
🌐 Community Links
- 📺 Video Walkthrough: Watch the Myco Demo on YouTube
- 🔗 Read the LinkedIn post: Read the full project post on LinkedIn
🍄 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
- Open the Play tab and click 🎮 Search Clearing — mushrooms sprout across the forest grid.
- Move Myco with the arrow buttons, or let Myco roam the clearing on its own every few seconds.
- Walk Myco onto a mushroom to collect it automatically, or use 🔍 Study, 🧺 Collect, 🍄 Pick, or 🌌 Follow Whisper on the current discovery.
- 🍽️ Eat? is always refused — Myco panics (in character) and tells you to study an unidentified mushroom before trying anything like that.
- 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]. - 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.
- 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.