README.md

metadata

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.

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)

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

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

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

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