Initial commit — The Apprentice for Build Small

.env.example

@@ -0,0 +1,16 @@
+# Copy to .env.local and fill in. Without these, the app runs in mock mode.
+
+# Modal-hosted OpenAI-compatible endpoint (vLLM serving Qwen2.5-32B or similar).
+# Leave empty to force mock mode for the LLM calls.
+MODAL_URL=
+
+# Modal proxy auth (optional, only if the endpoint requires headers).
+MODAL_KEY=
+MODAL_SECRET=
+
+# Force mock mode for the LLM even if MODAL_URL is set.
+ORACLES_FORCE_MOCK=0
+
+# Klein-4B image generation endpoint (separate from the LLM URL).
+# Leave empty to disable live image gen; mock SVG cards are used.
+KLEIN_URL=

.gitattributes

@@ -0,0 +1 @@
+*.png filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,78 @@
+# ---------------------------------------------------------------------------
+# Local secrets — NEVER push to HF Space.
+# ---------------------------------------------------------------------------
+.env
+.env.local
+.env.production
+
+# ---------------------------------------------------------------------------
+# Python build artifacts
+# ---------------------------------------------------------------------------
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+*.egg-info/
+.pytest_cache/
+
+# ---------------------------------------------------------------------------
+# OS junk
+# ---------------------------------------------------------------------------
+.DS_Store
+Thumbs.db
+.vscode/
+.idea/
+
+# ---------------------------------------------------------------------------
+# Dev-only directories — they live on the local machine but never need to
+# ship to the HF Space. The Space only runs app.py + the oracles/ package
+# + prompts/ + assets/sprites.
+# ---------------------------------------------------------------------------
+
+# Klein sprite generator scripts — only used at build time
+modal_backend/
+scripts/
+
+# Training + distillation — produced the LoRA weights, not needed at runtime
+training/
+
+# Smoke / unit tests — not part of the served app
+tests/
+
+# Local LoRA adapter weights — published to HF Hub separately
+lora-out/
+lora-out-v2/
+lora-out-tiny/
+
+# Pre-chroma-key raw PNGs — *.png is what the app uses
+assets/sprites/*_raw.png
+assets/sprites/v1_backup/
+
+# GGUF artifacts for the local llama-cpp backend
+gguf-out/
+*.gguf
+
+# Captured LLM traces — submit separately to HF Datasets for the
+# Sharing-is-Caring badge, not for the Space repo
+traces/
+.llama_cpp_cache/
+/tmp/oracles_local_llama.log
+
+# ---------------------------------------------------------------------------
+# Project pivot logs + planning docs — useful to the developer, noise to
+# the Space reader. Keep on disk, don't ship.
+# ---------------------------------------------------------------------------
+PIVOT_LOG.md
+IMPLEMENTATION_PLAN.md
+CONTRACTS.md
+
+# Mocked / debug output dirs
+mock_out/
+debug_out/
+
+# Runtime-generated mock SVG scene images — produced by the
+# image-fallback code in oracles/images.py when Klein output is
+# unavailable. These accumulate over self-test runs and should
+# never ship to the Space.
+assets/generated/

README.md

@@ -0,0 +1,112 @@
+---
+title: The Apprentice
+emoji: 🌲
+colorFrom: indigo
+colorTo: yellow
+sdk: gradio
+sdk_version: 4.44.1
+python_version: "3.10"
+suggested_hardware: cpu-basic
+app_file: app.py
+pinned: false
+license: mit
+short_description: A pixel-art branching-narrative game powered by a custom 14B LoRA — the mentor inscribes the wisdom, the apprentice has to make it save his life.
+tags:
+  - thousand-token-wood
+  - off-brand
+  - well-tuned
+  - field-notes
+  - tiny-titan
+  - branching-narrative
+  - game
+  - pixel-art
+  - gradio
+  - vllm
+  - lora
+  - qwen
+  - bilingual
+models:
+  - Qwen/Qwen2.5-14B-Instruct
+  - Qwen/Qwen2.5-1.5B-Instruct
+  - AndrewRqy/oracles-wizard-14b-lora
+  - AndrewRqy/oracles-wizard-1.5b-lora
+---
+
+# The Apprentice — Build Small Hackathon
+
+> A pixel-art branching fairy-tale game. You inscribe five short oracles before the journey begins; an apprentice has to make every one of them save his life across five trials in a branching graph that converges on one of five distinct endings.
+
+**Track**: Thousand Token Wood
+**Stack**: Gradio + Modal-hosted vLLM + Qwen2.5-14B + custom humor LoRA
+**Languages**: English + Simplified Chinese
+**Demo video**: _(to be added by submitter)_
+**Social post**: _(to be added by submitter)_
+
+---
+
+## What's in the box
+
+| Component | Detail |
+|---|---|
+| **Frontend** | Single-file Gradio app (~5000 lines) with a hand-authored pixel-art aesthetic — Press Start 2P + VT323 fonts, NES-style sharp corners, layered animated scene composition, custom theme that suppresses every visible piece of Gradio chrome. |
+| **Backend** | Qwen2.5-14B-Instruct + custom humor LoRA (`AndrewRqy/oracles-wizard-14b-lora`) served via vLLM on Modal. OpenAI-compatible API; the frontend talks to it through the OpenAI SDK. |
+| **Tiny Titan path** | Qwen2.5-1.5B-Instruct + LoRA, also trained on the same 23k humor corpus (`AndrewRqy/oracles-wizard-1.5b-lora`). Eligible for the ≤4B prize. |
+| **Branching narrative** | Hand-authored 15-node story graph with 5 distinct endings. Each fork at trials 2–4 is picked by an LLM call seeded with the player's inscribed oracle, so the path the apprentice walks is shaped by what wisdom was inscribed. |
+| **6 themes × 2 languages** | Fantasy, Space-Cowboy, Galactic-Light, Black-Land, Mistgate, Quiet-Years — each with its own sprite set, finale boss, themed obstacle scenes (finale / arena / passage / trap), localized banner + oracle artifact + apprentice role title. All authored for both English and Chinese. |
+| **Klein-4B sprites** | All in-game art (~105 pixel-art sprites + 4 environment backdrops per theme) was generated locally via Klein-4B on a Modal H100, then chroma-keyed offline. No FLUX, no commercial generators. |
+
+## How to play
+
+1. **Inscribe** — pick a language, then a theme, then write five short oracles (any words, gibberish, emoji — whatever you want).
+2. **Send-off** — the mentor seals the parchments and the apprentice leaves.
+3. **Five trials** — at each obstacle, the apprentice draws ONE oracle. The model takes the obstacle + the oracle and writes a 200-word resolution in one of three humor modes (wild imagination / accidental trip / last-minute revelation).
+4. **Boss** — trial 5 is the world's finale (the dragon for fantasy; the warlord-king for space-cowboy; etc.). Different paths through the tree lead to different bosses.
+5. **Ending** — one of 5 distinct endings plays, each with its own preset framing (Why the boss behaved as it did + What the apprentice carried home) and an LLM-expanded 3-paragraph epilogue.
+6. **Summary** — clicking through reveals the story tree with the path you took lit gold and the four endings you didn't reach blurred behind "???" for replay motivation.
+
+## Badge claims
+
+| Badge | Why we claim it |
+|---|---|
+| **🎯 Well-Tuned** | Qwen2.5-14B + a hand-distilled 23k-example humor LoRA (rank 16, ~6.5 h on H100). The fine-tune visibly steers all three humor modes; the field-notes write-up below details the distillation pipeline. |
+| **🎨 Off-Brand** | ~2000 lines of bespoke CSS, Press Start 2P + VT323 fonts, hand-painted pixel-art sprites, sharp-corner theme that overrides every visible Gradio token, custom story-tree visualization, custom ending banner with five-pip "endings discovered" strip. No stock Gradio chrome reaches the rendered page. |
+| **📓 Field Notes** | See `docs/FIELD_NOTES_distillation.md` — a ~950-word blog post on the schema-locked Claude-Sonnet-4.5 → Qwen distillation pipeline, the three humor modes, the JSON enforcement layers, and what 98.4% reject-sampling acceptance got us. |
+| **⚡ Tiny Titan (prize)** | Same 23k corpus also trained into a Qwen2.5-1.5B LoRA on H100 (~$5.50, ~1.5 h). Eligible for the ≤4B prize. |
+
+## Running it (locally or on Space)
+
+Three environment variables need to be set as **secrets** (HF Space Settings → Variables and secrets):
+
+```
+MODAL_URL     = https://<modal-workspace>--<app-name>-serve.modal.run
+MODAL_KEY     = wk-…  (Modal proxy auth key)
+MODAL_SECRET  = ws-…  (Modal proxy auth secret)
+```
+
+Once those are set, the Space spins up the Gradio app and the player can immediately walk a trial. No GPU is needed on the Space side — the LLM call streams in from Modal over HTTPS.
+
+If `MODAL_URL` is unset OR `ORACLES_FORCE_MOCK=1`, the app runs in **mock mode** — every LLM call returns a hand-written placeholder, the visuals still play, but the humor is dead. Useful for offline demos.
+
+## Repository layout
+
+```
+oracles_app/
+├── app.py                    main Gradio file (~5000 lines)
+├── README.md                 this file (HF Space metadata + write-up)
+├── requirements.txt          gradio + openai + Pillow
+├── .gitignore                excludes dev artifacts from the Space upload
+├── oracles/                  pure-Python package (state, LLM client, story graph, themes, i18n)
+├── prompts/                  LLM prompt templates (resolution / epilogue / interludes / obstacles)
+└── assets/sprites/           ~105 chroma-keyed pixel-art PNGs
+```
+
+The dev-only directories (`modal_backend/`, `scripts/`, `training/`, `tests/`, `lora-out/`, `*_raw.png`) live in this folder on local disk but are excluded from the HF Space upload by `.gitignore`.
+
+## Credits
+
+- Base model — Qwen2.5-14B-Instruct + Qwen2.5-1.5B-Instruct (Alibaba)
+- Distillation teacher — Claude Sonnet 4.5 (Anthropic) via OpenRouter
+- Sprite generator — Klein-4B (Anthropic) on Modal H100
+- Pixel-art fonts — Press Start 2P + VT323 (Google Fonts)
+
+Built for the **Build Small Hackathon — Thousand Token Wood track** (2026-06-15).