README.md

metadata

title: The Oracle
emoji: 🔮
colorFrom: indigo
colorTo: yellow
sdk: gradio
sdk_version: 6.16.0
python_version: '3.13'
app_file: app.py
pinned: false
license: mit
short_description: Oracle An Akinator-style guessing game
models:
  - bartowski/Llama-3.2-1B-Instruct-GGUF
  - bartowski/Llama-3.2-3B-Instruct-GGUF
tags:
  - build-small-hackathon
  - thousand-token-wood
  - llama
  - llama-cpp
  - gradio
  - game
  - guessing-game
  - offline-first
  - on-device

🔮 The Oracle

Think of an animal, a fruit, or a vegetable. The Oracle asks simple yes/no questions and divines exactly what you're thinking — an Akinator-style mind-reader. Built with Llama 🦙 and designed to run fully offline.

Built for the Build Small Hackathon · An Adventure in Thousand Token Wood.

Model

• Llama 3.2 1B Instruct (Llama-3.2-1B-Instruct-Q4_K_M.gguf) — what the live Space runs — through the llama.cpp runtime (in-process via llama-cpp-python). Just 1B parameters, far under the ≤32B limit and the ≤4B Tiny Titan bar. It's used only to phrase questions and to derive attributes when learning a new item; all deduction is pure deterministic code, so a 1B model is plenty.
• Also supports Llama 3.2 3B Instruct (the default) for slightly richer phrasing — set via ORACLE_LLAMA_REPO / ORACLE_LLAMA_FILE.

Because questions are pre-generated once at boot and cached (persisted in the Storage Bucket), the model size barely affects gameplay — the live cache holds all 42 questions, so each turn is an instant lookup.

Badges & prizes we're targeting

Target	Status	How
🔌 Off the Grid	✅	no cloud APIs; the engine + cached questions run fully offline
🎨 Off-Brand	✅	fully custom crystal-ball UI (art, buttons, reveal), not default Gradio
📓 Field Notes	✅	the design journey above + the two deep-dive docs / this write-up
🦙 Llama Champion	✅	the model runs through the llama.cpp runtime (ORACLE_QUESTION_LLM=1)
🐜 Tiny Titan (special award)	🎯	built on a genuinely tiny ≤4B model (Llama-3.2-3B)
📡 Sharing is Caring	optional	the attribute database is shareable as a dataset
🎯 Well-Tuned	✖️ n/a	deliberately no fine-tuned model — accuracy comes from the engine

Demo

X post

https://x.com/i/status/2064387556376981633

Why it fits the track

The game spends almost no tokens per turn. A deterministic engine does the deduction over a small attribute database, and a tiny Llama 3.2 3B model is used only to phrase questions in natural language (pre-generated at boot, so gameplay is instant). Small model, small token budget, no network required.

Design journey

Attempt 1 — one model did everything (ask and guess). It asked repetitive, elimination-style questions, never narrowed down, and games didn't end.

Attempt 2 — two models: one writes questions, one eliminates items from a list. Questions got better, but elimination was slow and wrong on large lists, and the model's facts couldn't be trusted (it called a tomato a root vegetable).

Final — facts in a JSON attribute database; a deterministic engine does all the elimination; the small model only phrases the questions (generated once at boot and cached, so gameplay is instant). A Teach mode lets it learn new items from Wikipedia, so the database grows on its own.

flowchart TD
    A[Boot] --> B(Model pre-generates natural questions, cached)
    B --> C(Gameplay: deterministic elimination engine)
    C --> D(Learning: model extracts facts from Wikipedia)

How it works

answers so far ─► engine.filter_candidates ─► engine.choose_attribute ─► look up cached question ─► ask
                                            └► 1 left → guess   0 left → discovery/teach

(the cached questions are written by Llama once at boot — see How question generation works)

• engine.py — pure-Python core. Filters candidates by the answers (exact, no model), then picks the attribute that best splits the set (max info gain). Auto-reloads the JSON if it changes on disk.
• data/*.json — the attribute database (animals / fruits / vegetables); the single source of truth. Every item defines every attribute.
• question_maker.py — the only place the LLM is used: turn an attribute into a natural yes/no question. Pre-generated at boot and cached (instant in-game), with built-in phrasing as fallback. Never decides elimination.
• llm.py — runs the model through the llama.cpp runtime (in-process via llama-cpp-python, or an HTTP llama-server for local dev), with thread caps, a timeout, and warmup so it can never hang the game.
• discovery.py — when the Oracle doesn't know an item, the player teaches it; attributes are filled from the player's answers, the LLM, and the existing DB, so the new item is complete and guessable next time. Also explains why a wrong answer threw it off.
• app.py — gradio.Server: @app.api("next") per turn, @app.api("learn") for teaching, serves index.html.
• index.html — a fully custom crystal-ball UI (image art, category pick, image answer buttons, "I'm not sure", dramatic reveal, Teach mode).
• check_db.py — validator: completeness, uniqueness, guessability, balance.

Deep dives

• How question generation works — the engine picks the attribute, the model only phrases it, and questions are pre-generated and cached at boot for instant gameplay.
• How Teach / discovery works — how the Oracle learns a new item (player answers + Llama + Wikipedia + the existing DB) and explains why a wrong answer threw it off.

Run locally

pip install -r requirements.txt
python app.py            # plays immediately, offline (built-in question phrasing)

For natural, model-written questions (runs the 3B model in-process via llama.cpp — the GGUF downloads once from the Hub):

ORACLE_QUESTION_LLM=1 python app.py

(Alternatively, run a local llama-server and set ORACLE_LLAMA_URL.)

Test & validate

pytest -q            # 20 offline tests
python check_db.py   # validate the attribute database

Deploy (Hugging Face Spaces · Gradio)

Push these files to a Space under build-small-hackathon; the Gradio SDK runs app.py on port 7860. The game works offline out of the box. To persist items taught during play and to run the Llama model on the Space (for the Llama Champion badge), see DEPLOY.md — in short: mount a Storage Bucket at /data, set ORACLE_DATA_DIR=/data, and set ORACLE_QUESTION_LLM=1.

Config (env vars)

Var	Default	Purpose
ORACLE_QUESTION_LLM	1	1 = model-written questions via llama.cpp; 0 = built-in phrasing (no model)
ORACLE_REVEAL_LLM	0	1 = model writes the pre-guess reveal line; 0 = instant templated line
ORACLE_DISCOVERY_WEB	1	1 = allow Wikipedia grounding when teaching a new item
ORACLE_DATA_DIR	(bundled data/)	point at a mounted HF Storage Bucket (e.g. /data) to persist learned items; the model also caches in <dir>/models/
ORACLE_MODEL_DIR	(<ORACLE_DATA_DIR>/models)	override where the GGUF model is downloaded/cached
ORACLE_LLAMA_REPO / ORACLE_LLAMA_FILE	Llama-3.2-3B GGUF	swap the model (e.g. the 1B for more speed)
ORACLE_LLAMA_URL	http://localhost:8080/v1/chat/completions	external llama-server endpoint (HTTP fallback)
ORACLE_LLAMA_THREADS	(cores available, capped at 4)	llama.cpp threads — keep small on CPU Spaces
ORACLE_LLM_TIMEOUT	25	seconds before a slow generation gives up and uses built-in phrasing
ORACLE_MAX_QUESTIONS	20	force a guess after this many questions

---

MIT