README.md

---
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](https://huggingface.co/bartowski/Llama-3.2-1B-Instruct-GGUF)**
  (`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](https://huggingface.co/bartowski/Llama-3.2-3B-Instruct-GGUF)**
  (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

[![Demo Video - Youtube](https://img.youtube.com/vi/U5UNzHBfJ1k/maxresdefault.jpg)](https://youtu.be/U5UNzHBfJ1k)

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

```mermaid
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](./docs/QUESTION_GENERATION.md)**)
- **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](./docs/QUESTION_GENERATION.md)** — 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](./docs/TEACH_MODE.md)** — 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

```bash
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):

```bash
ORACLE_QUESTION_LLM=1 python app.py
```

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

## Test & validate

```bash
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](./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**