README.md

---
title: DAYDREAM
emoji: 🌙
colorFrom: indigo
colorTo: purple
sdk: gradio
sdk_version: 6.16.0
app_file: app/app.py
pinned: true
license: mit
short_description: "Small models, big dreams: a dream game with your tiger"
tags:
  - track:thousand-token-wood
  - sponsor:openbmb-minicpm
  - sponsor:modal
  - badge:best-agent
  - badge:off-brand
  - badge:best-demo
---

# 🌙 DAYDREAM — *Press Your Luck, Keep Your Tiger*

A bedtime dream you **play** — a real, goal-driven story, dreamed in real time by a
**fleet of small models**, none bigger than fits on one GPU. Each world gives you a
**quest**; you pursue it by taking **gambits** (safe / bold / reckless) through surreal
scenes with your stuffed tiger **Hobbes**, who grows brave because of the bets you take
*together*. Code rolls the dice; the little models supply the soul. Reach the goal to
wake with the prize — or run out of lucidity and dissolve.

> **The thesis — small models, big dreams.** You don't own one giant brain; you command
> a *fleet of scrappy small minds*. In a dream, a small model's fuzziness isn't a bug —
> it's the aesthetic. **The constraint is the art.** Every model ≤32B, by design.

---

## 🏆 Submission tags
- **Track:** *An Adventure in Thousand Token Wood* (whimsical) — there's even a `Thousand Token Wood` world inside.
- **Sponsor prizes:** **OpenBMB / Best MiniCPM** (MiniCPM5-1B is our Keeper) · **Modal / Best Use** (4 services + a cost-guardian).
- **Bonus badges:** **Best Agent** (a coordinated multi-agent fleet) · **Off Brand** (custom dream-deck UI + live generated visuals) · **Best Demo**.

## ✨ What makes it different

1. **A real story, not a chat.** Every world is a quest with a visible goal; the Dreamweaver weaves *one coherent tale* that moves toward it each turn (forward on success, setback on failure) and resolves in a genuine climax — reach the prize, or the dream collapses.
2. **A fleet, not a chatbot.** Five small models — 🌌 Dreamweaver, 👁 Nightmare, 🐯 Hobbes, 🗺 Keeper, 🎨 Painter — each with one job, coordinated per turn. Every model ≤32B.
3. **Code owns the dice, models own the words.** Pass/fail and every reward is computed by a seeded, model-free resolver. The models *never* decide outcomes — so it's a **fair game**, not a story that flatters you. This is the heart of the design.
4. **Hobbes grows brave because of you.** A COURAGE meter rises when you survive bets made *with* him; his voice shifts cowering → steady → "I've got you." The "aww" is earned.
5. **The dream paints itself — fast.** A FLUX image renders each beat on-GPU in **~0.5s**; a pre-generated hero greets you the instant you arrive, then live per-beat images shift the scene. Choices and state run async, so a warm turn is **~5s** with narration streaming in under a second.
6. **Engineered for real Modal deployment.** Multi-backend (vLLM MoE + llama.cpp + FLUX) plus a **cloud cost-guardian** we built after a runaway-GPU lesson — scale-to-zero, hard container caps, a lease-based dead-man's-switch, and robustness so a cold/failed backend degrades gracefully instead of hanging a turn.
7. **Deterministic & shareable.** Same dream seed replays the same dice *and* the same images → *"beat my run, seed `abc123`."* Download your full run as a keepsake.

---

## 🧠 Architecture

DAYDREAM is a **fleet of small models refereed by code**: a deterministic Python core
owns the truth and the dice, while a handful of sub-32B models — each on its own Modal
GPU — supply only words and pixels. Three views:

### 1 · System — three layers, one rule

> **The rule:** outcomes flow *down* from code; only language flows *up* from models.

```mermaid
flowchart TB
    P([👤 Player])

    subgraph CODE["⚙️ Orchestration — Python · owns the truth"]
        direction LR
        ENGINE["DreamEngine<br/><i>turn loop</i>"]
        RESOLVER{{"🎲 Resolver<br/><i>seeded dice + rewards</i>"}}
        STATE[("🗺️ WorldState<br/><i>externalized memory</i>")]
    end

    subgraph FLEET["🤖 The Fleet — Modal serverless GPUs · every model ≤ 32B"]
        direction LR
        SPEC["🌌 Dreamweaver · 👁 Nightmare · 🐯 Hobbes<br/><b>Qwen3-30B-A3B</b> MoE on vLLM<br/><i>30B total · only 3B active/token</i>"]
        ROUTER["🗺 Keeper<br/><b>MiniCPM-1B</b> · llama.cpp"]
        VISION["🎨 Painter<br/><b>FLUX.1-schnell</b>"]
    end

    P -- "gambit (safe/bold/reckless)" --> ENGINE
    ENGINE --> RESOLVER -- "verdict" --> ENGINE
    ENGINE <-. "context slice ↔ patch" .-> STATE
    ENGINE == "narrate · react" ==> SPEC
    ENGINE -. "async" .-> ROUTER
    ENGINE -. "async" .-> VISION
    SPEC == "prose + 3 choices" ==> P
    VISION -. "image" .-> P
    ROUTER -. "state patch" .-> STATE

    classDef code fill:#1b1640,stroke:#7c5cff,color:#fff;
    classDef fleet fill:#241a4d,stroke:#9d7bff,color:#fff;
    classDef dice fill:#2a1022,stroke:#ff5c7c,color:#fff;
    classDef player fill:#0b0a1c,stroke:#cdbcff,color:#fff;
    class ENGINE,STATE code; class SPEC,ROUTER,VISION fleet; class RESOLVER dice; class P player;
```

### 2 · One turn — critical path vs. async (why it feels instant)

```mermaid
sequenceDiagram
    autonumber
    actor P as 👤 Player
    participant C as ⚙️ Resolver
    participant D as 🌌 Dreamweaver
    participant H as 🐯 Hobbes
    participant K as 🗺 Keeper
    participant F as 🎨 FLUX

    P->>C: pick gambit
    C->>C: roll seeded dice → verdict
    Note over C: the outcome is FIXED before any model speaks — the game is fair

    C->>D: narrate this verdict
    D-->>P: streams prose · first words in ~0.4s

    par off the critical path (async)
        C-)K: patch world-state (background)
        C-)F: paint the beat (~0.5s on GPU)
    end

    D->>H: finished scene
    H-->>P: reaction + 3 fresh gambits · ~5s
    F--)P: dream image fades in
    Note over P,F: you wait only for narration + choices (~5s) —<br/>state and image never block the turn
```

### 3 · The fairness spine — code owns the dice

```mermaid
flowchart LR
    G["gambit + seed + turn"] --> R{{"🎲 resolve()<br/>pure · deterministic"}}
    R --> V["verdict<br/>success / partial / fail<br/>+ reward magnitudes"]
    V --> A["apply()<br/>move LUCIDITY · PROGRESS<br/>· COURAGE · MENACE"]
    V --> N["🌌 model narrates<br/><i>the words, not the outcome</i>"]
    A --> S[("WorldState")]
    classDef c fill:#2a1022,stroke:#ff5c7c,color:#fff;
    classDef m fill:#241a4d,stroke:#9d7bff,color:#fff;
    class R,V,A c; class N m;
```
*Same `(seed, turn)` → same dice → **"beat my run, seed `abc123`"** is honest. A model can never decide whether you succeed.*

---

## 🎮 How it plays

1. Pick a world (Candy Desert, Sunken City, Rain Street, Red Planet, Thousand Token Wood) and a seed. A hero image and your **quest** greet you instantly.
2. Pursue the quest: take a **gambit** — 🟢 safe / 🟡 bold / 🔴 reckless (each shows its odds + reward) — or type your own action. Hobbes' three options are concrete, scene-specific steps toward the goal.
3. The **Dreamweaver** narrates the outcome the dice already decided, moving the story toward the goal; the **Nightmare** presses when menace climbs; **Hobbes** reacts in his current mood and offers the next steps; the **Keeper** updates world-state; the **Painter** repaints the scene.
4. Climb **PROGRESS** to 100 to wake with the prize, or run out of **LUCIDITY** and dissolve — both end in a climactic beat. Watch **COURAGE** turn Hobbes brave along the way. Win or lose, the run freezes into a shareable Dream Journal you can download.

## 🤖 The fleet
*Full design + diagrams: **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)**.*

| Agent | Role | Backend (≤32B each) | Job |
|---|---|---|---|
| 🌌 Dreamweaver | specialist | Modal vLLM · Qwen3-30B-A3B (MoE, 3B active) | narrate the pre-decided outcome |
| 👁 Nightmare | specialist | Modal vLLM · Qwen3-30B-A3B (MoE, 3B active) | press the dread when menace is high |
| 🐯 Hobbes | specialist | Modal vLLM · Qwen3-30B-A3B (MoE, 3B active) | companion; voice keyed to COURAGE; offer gambits |
| 🗺 Keeper | router | Modal llama.cpp · **MiniCPM5-1B** | structured world-state (location, items, memory) |
| 🎨 dream image | vision | Modal · FLUX.1-schnell | paint each beat, in parallel under the narration |

Backends are OpenAI-compatible → swap models or run "off the grid" via one env var, no code change.

## 🧠 Why it stays coherent on small models
The **world-state lives in code**, outside the models (`agents/world.py`). Each turn the engine
feeds each agent a compact slice of truth, so a 1B router can keep a consistent world that a
single small context never could. The **resolver** (`agents/resolver.py`) owns all game math,
seeded by `(seed, turn)` — fair, replayable, and impossible for a model to fudge.

## ☁️ Best Use of Modal — and a cost story
DAYDREAM runs **four Modal services** (vLLM, llama.cpp, FLUX, and a guardian). After a
keep-warm GPU once cold-looped and burned real money, we made cost control *structural*:
- **Scale-to-zero + `max_containers=1`** on every GPU app — $0 idle, no fan-out.
- A **cloud guardian**: a cheap cron that warm-pings endpoints **only while a time-boxed lease is active** — so warmth is a *pull*, not a pin. Forget to tear down? The lease expires and everything scales to zero on its own, independent of your laptop.
- A `make` control surface: `make status` (apps + lease + live spend tracker), `make stop` (panic), `make demo-up/down`.

All endpoint URLs derive from one `MODAL_WORKSPACE` slug, so moving workspaces is a one-line change.

## 🚀 Run it
**Offline (no backend, fully playable):**
```bash
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
DAYDREAM_MOCK=1 python app/app.py
```
**Against Modal inference:** set `MODAL_WORKSPACE` + keys in `.env` (see `.env.example`), then `make deploy && python app/app.py`.

## 🗂 Layout
| Path | What |
|---|---|
| `agents/dream.py` | the fleet engine (Dreamweaver · Nightmare · Hobbes · Keeper) |
| `agents/resolver.py` | seeded, model-free dice + reward math (code owns the game) |
| `agents/world.py` | environments + externalized `WorldState` |
| `agents/vision.py` | per-beat dream-image prompts + FLUX client |
| `agents/base.py` | tiny streaming/JSON Agent + `DAYDREAM_MOCK` offline mode |
| `app/app.py` | Gradio dream-deck UI |
| `modal_app/*.py` | Modal vLLM · llama.cpp · FLUX · guardian |

*Small models, big dreams.* 🌙