| --- |
| title: AmazingDigitalPetDentures |
| emoji: 🔥 |
| colorFrom: pink |
| colorTo: gray |
| sdk: gradio |
| sdk_version: 6.16.0 |
| python_version: '3.12' |
| app_file: app.py |
| pinned: false |
| short_description: The Amazing Digital Pet Dentures feeds on your Adventures |
| --- |
| |
| # 🦷 Amazing Digital Pet Dentures |
|
|
| A circus-themed **game generator**. You chat a vibe or an idea, and a single AI agent |
| (NVIDIA **Nemotron**, served through an OpenAI-compatible **llama.cpp** endpoint) writes a |
| complete, **fully playable 2D/3D HTML game** that renders live in the app — right next to |
| the chat. |
|
|
| Built for the **Build Small Hackathon**. |
|
|
| > ℹ️ **Hugging Face note:** the `---` block at the very top of this file is the Space |
| > config. **Do not delete it** — it tells the Space how to run. Everything below it is just |
| > this page. |
|
|
| --- |
|
|
| ## How it works (architecture) |
|
|
| | File | Role | |
| |---|---| |
| | `app.py` | Gradio UI: chat + the adventure window (renders games in an `<iframe>`), per-browser history | |
| | `agents.py` | The single **Adventure Engineer** agent + its model + a SQLite history db | |
| | `instructions/adventure_engineer.py` | The agent's system prompt (build original, playable worlds) | |
| | `skills/game-engine/` | An Agno **skill** (game-dev references/templates) the agent must consult every turn | |
| | `modal_app.py` | Serves Nemotron on a Modal GPU via `llama-server` (the cloud backend) | |
|
|
| The model backend is chosen by **one env var** (`LLAMACPP_BASE_URL`) — point it at a local |
| `llama-server` or at a Modal URL, no code change. |
|
|
| --- |
|
|
| ## Prerequisites |
|
|
| - **git** |
| - **Python 3.13** |
| - **[uv](https://docs.astral.sh/uv/)** (fast Python package manager) |
|
|
| --- |
|
|
| ## Step 1 — Pick your model backend |
|
|
| Choose based on your hardware: |
|
|
| ### Option A — Run it locally (powerful machine) |
|
|
| Use this if you have a **Mac with ≥ 32 GB unified RAM**, **or** a GPU with **≥ 24 GB VRAM** |
| (e.g. RTX 4090 / 5090). The model weights are ~23 GB. |
|
|
| 1. **Install llama.cpp** — follow the official guide: |
| 👉 https://github.com/ggml-org/llama.cpp |
| (macOS: `brew install llama.cpp`. Windows/Linux: see the repo's install/build docs.) |
|
|
| 2. **Start the model server** (first run downloads the GGUF automatically): |
| ```bash |
| llama-server -hf unsloth/Nemotron-3-Nano-30B-A3B-GGUF:UD-Q4_K_XL \ |
| --jinja --temp 0.6 --top-p 0.95 --min-p 0.01 -c 16384 -ngl 99 --port 8080 |
| ``` |
|
|
| 3. In your `.env` (see Step 3): |
| ``` |
| LLAMACPP_BASE_URL=http://localhost:8080/v1 |
| LLAMACPP_API_KEY=sk-no-key |
| LLM_MODEL_ID=nemotron |
| ``` |
|
|
| ### Option B — Use Modal (everyone else) |
|
|
| No big GPU? Serve the **same** Nemotron on a cloud GPU using Modal's **free hackathon |
| credits**. Full details are documented in the header of `modal_app.py`; the short version: |
|
|
| 1. Install the dev deps (adds `modal`) and log in: |
| ```bash |
| uv pip install -r requirements-dev.txt |
| modal token new |
| ``` |
| 2. Create the API-key secret once (pick any long private value): |
| ```bash |
| modal secret create adpd-llama LLAMA_API_KEY=sk-pick-something-long |
| ``` |
| 3. Deploy and copy the printed URL: |
| ```bash |
| modal deploy modal_app.py |
| ``` |
| 4. In your `.env`: |
| ``` |
| LLAMACPP_BASE_URL=https://<your-workspace>--adpd-llama-serve.modal.run/v1 |
| LLAMACPP_API_KEY=sk-pick-something-long |
| LLM_MODEL_ID=nemotron |
| ``` |
| > The first request cold-starts the GPU and downloads ~23 GB (≈10–15 min). After that |
| > it's fast, and it scales to **$0** when idle. |
|
|
| --- |
|
|
| ## Step 2 — Set up the environment (uv) |
|
|
| ```bash |
| uv venv --python 3.13 |
| # Activate it: |
| # Windows (PowerShell): .venv\Scripts\activate |
| # macOS / Linux: source .venv/bin/activate |
| |
| uv pip install -r requirements.txt # use requirements-dev.txt if you're deploying Modal |
| ``` |
|
|
| ## Step 3 — Configure `.env` |
|
|
| ```bash |
| cp .env.example .env # Windows: copy .env.example .env |
| ``` |
| Fill it in with the values from the backend you chose in Step 1. |
|
|
| ## Step 4 — Run it |
|
|
| ```bash |
| python app.py |
| ``` |
| Open the local URL it prints (usually http://127.0.0.1:7860), type a game idea into the |
| chat, and watch the adventure window build and render your game. |
|
|
| --- |
|
|
| ## For the team (remotes & deploy) |
|
|
| This repo has two remotes: |
|
|
| - **`origin`** → GitHub (source of truth — commit/push here, GitHub Desktop works on this). |
| - **`hf`** → the Hugging Face Space. Deploy the app with: |
| ```bash |
| git push hf main |
| ``` |
| - **Modal** hosts the GPU model backend (`modal deploy modal_app.py`), separate from the app. |
|
|
| Secrets live in `.env` locally (gitignored) and in **Space Settings → Secrets** on HF — |
| never commit them. |
|
|
| ### Troubleshooting |
|
|
| - **Modal first call is slow** — that's the one-time cold-start download; later calls are fast. |
| - **Games come out broken / repetitive** — use a higher-precision backend (the local Nano, |
| or a stronger Nemotron); aggressive quantization hurts code quality. |
| - **History "forgets" on the Space** — Space disk is ephemeral, so `adpd.db` resets on |
| restart. Fine locally; for durable Space persistence, move the db to a Volume/Dataset. |
|
|
| --- |
|
|
| ## Credits & Inspiration |
|
|
| The talking-dentures mascot is a loving **fan tribute to Caine**, the ringmaster from |
| **[*The Amazing Digital Circus*](https://www.youtube.com/@GlitchProductions)** by **Glitch |
| Productions**. This is an independent, non-commercial fan project — it is **not** affiliated |
| with, endorsed by, or sponsored by Glitch Productions or the show's creators, and is **not** |
| intended to copy, plagiarize, or infringe on their work. All rights to *The Amazing Digital |
| Circus* and its characters belong to their respective owners. 💛 |
|
|
