README.md

metadata

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 (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):

   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:

   uv pip install -r requirements-dev.txt
   modal token new
   

2. Create the API-key secret once (pick any long private value):

   modal secret create adpd-llama LLAMA_API_KEY=sk-pick-something-long
   

3. Deploy and copy the printed URL:

   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)

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

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

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:

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