README.md

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