SPEC.md

SPEC.md — "First Contact" (working title)

A small-model game for the Hugging Face Build Small hackathon (Adventure track). You teach an alien that knows words but has never experienced human life. It acts in a tiny sandbox world. Over a session it accumulates concepts and begins to generalize them to new situations. The "it finally understood me" moment is the payoff and the shareable artifact.

This document is the contract. Implement against it exactly. Where it says MUST, it is load-bearing for either correctness or the hackathon constraints. Where it says SHOULD, use judgement.

---

0. Non-negotiable platform constraints (READ FIRST)

These come from the hackathon rules and the current ZeroGPU docs. Violating any of them either breaks the deploy or disqualifies the entry.

• The submission IS a Hugging Face Space under the hackathon org. Modal (below) is a development/serving convenience only, never the deliverable.
• ZeroGPU requires the Gradio SDK. Not Streamlit, not Docker. The app MUST be a Gradio app from the first commit. Do not build a Flask/FastAPI prototype to port later.
• Gradio 4+ and PyTorch ≥ 2.8.0 are required by ZeroGPU. Pin accordingly.
• torch.compile is NOT supported on ZeroGPU. Do not use it. (Ahead-of-time compilation exists but is out of scope for this build.)
• Model MUST be loaded onto 'cuda' at module level, NOT lazily inside the GPU function. CUDA transfers are optimized for startup placement. A PyTorch CUDA emulation mode makes module-level .to('cuda') work outside the GPU function.
• The GPU-bound function MUST be decorated with @spaces.GPU. Default GPU runtime is 60 seconds; if a call can exceed that, pass duration= (e.g. @spaces.GPU(duration=120)). Shorter declared durations get better queue priority — keep it tight.
• Model MUST be ≤ 32B parameters (hackathon rule).
• All per-user game state MUST live in gr.State, never module globals. Module globals are shared across all concurrent visitors — the moment the demo link is posted, global state means every player shares one alien. This is the single most common Gradio-on-Spaces bug; do not fall into it.
• No secrets in code. HF token via Space secrets / env var. No API keys anywhere in the repo.
• No localStorage / browser storage. State is server-side in gr.State.

ZeroGPU quota for an org member is 40 min/day of GPU time. This is plenty for dev and demo if we don't waste it — see §6 (the model call MUST be swappable so that ledger/world logic can be developed against a stub with zero GPU spend).

---

1. The core architecture in one paragraph

The model never learns in the weights sense. The alien's growing understanding lives in a concept ledger maintained in plain Python and injected into the prompt every turn. The model is a stateless function: given (the alien's current ledger + the world state + the player's utterance), it returns (an action in the sandbox + an in-character reply + structured notes about what it did and didn't understand). The host code applies the action deterministically, checks the win condition mechanically, and decides whether a new concept was taught. That loop — not the model — is the game.

                 ┌──────────────────────────────────────────┐
                 │              gr.State (per session)        │
                 │   ledger: list[Concept]                    │
                 │   world:  WorldState                       │
                 │   challenge: Challenge                     │
                 │   turn: int                                │
                 └──────────────────────────────────────────┘
                                  │   ▲
   player utterance               │   │  updated state rendered to UI
        │                         ▼   │
        ▼              ┌──────────────────────┐
  build_prompt(...) ──▶│   model_call(prompt) │  ← SWAPPABLE (stub | local | modal)
        ▲              │   @spaces.GPU         │
        │              └──────────────────────┘
        │                         │ strict JSON
   ledger rendered as             ▼
   "things you now      parse + validate (retry once, then safe no-op)
    understand"                   │
                                  ▼
                     apply_action(world, action)  ── deterministic
                                  │
                                  ▼
                     check_win(world, challenge)  ── mechanical, no model
                                  │
                                  ▼
              maybe_learn(ledger, candidate_concept, player_confirm)

---

2. Data model

Implement as dataclasses (or pydantic if you prefer validation; dataclasses are fine). Everything is JSON-serializable so it can live in gr.State.

2.1 Concept (an entry in the ledger)

@dataclass
class Concept:
    id: str               # stable slug, e.g. "hidden_info"
    label: str            # short human label, e.g. "hiding information"
    player_phrase: str    # how the player expressed it when teaching
    understanding: str    # the alien's internal gloss, 1 sentence, in alien framing
    taught_on_turn: int
    times_applied: int = 0

The ledger starts with ONLY raw physical primitives the alien already has. These are NOT social/temporal/abstract. Seed exactly these (tune wording, keep the set small):

• object — "a thing that exists in a place"
• move — "to change where I am"
• give_take — "a thing can pass from one holder to another"
• more_less — "quantities can differ"
• point — "I can direct attention to a thing"

Everything interesting (hidden_info, secret, gift, surprise, trade, promise, lie, ...) MUST be acquired in-session by teaching. Do NOT seed them.

2.2 WorldState (the deterministic sandbox)

Keep it tiny. The world exists so that success is checkable without the model judging semantics. A reasonable starting world:

@dataclass
class Obj:
    id: str
    name: str             # "blue stone", "red stone", "basket"
    location: str         # an Agent id, a Container id, or "ground"
    hidden: bool = False  # concealed from other agents?

@dataclass
class Agent:
    id: str               # "alien", "other"  (the alien, and a second NPC)
    name: str
    holding: list[str]    # obj ids

@dataclass
class WorldState:
    objects: dict[str, Obj]
    agents: dict[str, Agent]
    containers: list[str]      # e.g. ["basket"] — things that can conceal
    log: list[str]             # human-readable record of actions taken

2.3 Action (what the model is allowed to do to the world)

The action space MUST be small, closed, and enumerable. The model picks ONE per turn. This is what makes the system robust — the model can say anything in its reply, but it can only do things from this list, so application is deterministic and unsurprising.

Verbs (starting set — expand only if a challenge needs it):

verb	args	effect
move_to	target: location	alien moves
pick_up	obj_id	alien adds obj to holding, obj.location = "alien"
put_in	obj_id, container_id	obj.location = container; if container conceals, obj.hidden = True
give	obj_id, agent_id	transfer obj to another agent's holding
point_at	`obj_id	agent_id`
wait	—	no-op (the confused/contemplative fallback)

@dataclass
class Action:
    verb: str             # one of the above
    args: dict            # validated against the verb's signature

2.4 Challenge (the current goal, with a MECHANICAL win condition)

@dataclass
class Challenge:
    id: str
    title: str                  # "Teach the alien to hide the stone"
    setup_blurb: str            # shown to the player
    teaches: str | None         # concept id this challenge is designed to introduce (or None if it tests generalization)
    win_predicate: Callable[[WorldState], bool]   # checked after each action
    # generalization challenges set `teaches=None` and rely on a previously
    # learned concept being applied to a NEW situation.

Win is ALWAYS a predicate over WorldState, never a semantic judgement by the model. Example: "hide the blue stone from other" → lambda w: w.objects["blue_stone"].hidden and w.objects["blue_stone"].location == "basket".

---

3. The model contract (strict JSON)

The model MUST return ONLY a JSON object, no prose around it, matching this schema:

{
  "action": { "verb": "put_in", "args": { "obj_id": "blue_stone", "container_id": "basket" } },
  "utterance": "I place the blue-thing inside the holder. The other cannot see it now?",
  "gap": "I do not understand why you want the other to not-see",
  "candidate_concept": {
    "id": "hidden_info",
    "label": "hiding information",
    "understanding": "one mind can hold a thing another mind does not have, on purpose"
  }
}

Field rules:

• action — REQUIRED. verb MUST be in the allowed set; args MUST match the verb. If the model emits an unknown verb or bad args → treated as a parse failure (see §4).
• utterance — REQUIRED. The alien's in-character reply. This is where the voice and the comedy live.
• gap — nullable. The alien naming what it could NOT do/understand. Drives both the humour and the player's sense of what to teach next. null when the alien understood fully.
• candidate_concept — nullable. The alien proposing "I think you just taught me a new primitive." When present and coherent, it becomes a ledger entry (gated — see §5). null on most turns.

Getting a small model to emit clean JSON reliably is the #1 engineering risk. Mitigations, in order of preference, implement at least the first two:

1. Use the model's chat template and a system prompt that ends with the exact JSON schema and the instruction to output nothing else.
2. Constrained / grammar-guided decoding if the serving stack supports it (e.g. outlines, lmformatenforcer, or transformers' JSON mode). This nearly eliminates parse failures and is worth the setup.
3. As a floor: a tolerant parser that extracts the first balanced {...} block from the output before json.loads.

---

4. Robustness (the JSON parse-fail path)

The model WILL occasionally produce malformed output. The system MUST degrade gracefully, never crash, never leak a stack trace to the player.

call model
  └─ parse JSON
       ├─ success + valid action  → proceed
       └─ failure (bad JSON | unknown verb | bad args)
            └─ re-prompt ONCE, appending: "Your previous reply was not valid.
               Error: <msg>. Respond again, JSON only, matching the schema."
                 ├─ success → proceed
                 └─ failure again → SAFE FALLBACK:
                      action = {"verb": "wait"}
                      utterance = "<the alien looks at you, not understanding>"
                      gap = "I could not grasp that"
                      candidate_concept = null

The safe fallback is in-character (the alien being confused is consistent with the fiction), which is why this game tolerates model failure better than most. Budget real time for this path. It is not optional polish; it is what keeps the live demo from dying on stage.

---

5. The learning loop (gating ledger additions)

Do NOT silently append every candidate_concept — that pollutes the ledger and removes the player's sense of agency. Gate it:

• A candidate_concept is added to the ledger only when the player confirms (a lightweight "Yes, it learned that" affordance in the UI) OR when it is clearly coherent and non-duplicative (configurable; start with explicit player confirm so the "it learned!" beat is deliberate and screenshot-worthy).
• On addition: assign taught_on_turn = current turn, set times_applied = 0.
• When a subsequent turn's chosen action depends on an existing concept (heuristic: the prompt-builder injected it and the model's gap is null on a situation that would previously have produced a gap), increment times_applied. This is what powers the "constellation grows / concept lights up when reused" UI moment.

The generalization beat (the emotional core): a Challenge with teaches=None presents a NEW situation that a previously taught concept should cover. Success is the alien spontaneously applying e.g. hidden_info to understand "secret" or "surprise" without being re-taught. Author at least two of these (see §8).

---

6. The swappable model interface (PROTECT YOUR GPU QUOTA)

The model call MUST sit behind a single interface with at least three implementations. This is both good design and the thing that lets the entire ledger/world/challenge logic be built and tested with zero GPU spend.

class Brain(Protocol):
    def respond(self, prompt: str) -> str:        # returns raw model text
        ...

# 1) StubBrain — deterministic, no GPU. Returns canned valid-JSON responses keyed
#    to test scenarios. Develop the ENTIRE loop against this first.
# 2) LocalBrain — transformers model on 'cuda', loaded at module level, called
#    inside @spaces.GPU. The real ZeroGPU path.
# 3) ModalBrain — calls a Modal endpoint (see §7). Optional; for when ZeroGPU
#    queues are bad at peak, or for the fine-tune. NOT the submission path.

Select implementation via env var (BRAIN=stub|local|modal), default stub locally and local on the Space. Day-one development happens almost entirely on StubBrain.

@spaces.GPU wraps only the LocalBrain.respond call. State mutation (ledger/world/win-check) happens OUTSIDE the decorated function so it never holds the GPU.

---

7. Modal (optional, dev/serving only — NEVER the submission)

Reference: github.com/modal-labs/modal-examples, folder 06_gpu_and_ml (LLM fine-tuning + serving), 04_secrets (HF token pattern). The repo's examples are tested on Python 3.11; match that for the Modal side to avoid surprises.

Two legitimate uses, both behind ModalBrain:

1. Serving the model as an HTTP endpoint when ZeroGPU queues are slow during peak hours. The Space's ModalBrain calls it. Keep the Space the deliverable.
2. The optional LoRA fine-tune (badge): use the $250 Modal credits to train a small LoRA that fixes JSON-formatting reliability and locks the alien voice. Do this ONLY if the prompt-only LocalBrain is genuinely struggling on those two axes — do not manufacture the need just because credits exist. If you do it, the resulting adapter loads in LocalBrain for the real submission.

Modal MUST NOT be required for the Space to run. If BRAIN != modal, no Modal dependency should be imported.

---

8. Content: the challenge arc

Authoring is where delight is won, not engineering. Keep the arc SHORT — 5–6 challenges, not 15. Scope creep on content eats the UI/submission time.

Suggested arc (the spine — refine the wording later):

1. Warm-up (teaches object/move are enough): "Put the red stone in the basket." Pure mechanical, teaches the player the interaction model and shows the alien being literal-competent. No new concept.
2. First real teach (hidden_info): "Hide the blue stone from the other one." The alien has put_in but no concept of concealment-as-information-state. The player must teach "you can keep a thing so another mind does not have it."
3. Build on it (gift/give_take+intent): "Give the other a present." The alien has give mechanically but no concept of gift (transfer + positive intent). Teach it.
4. GENERALIZATION (teaches=None, relies on hidden_info): "Make a surprise for the other." Success = the alien combines hiding (concealment) + gift (giving) without being re-taught either — it generalizes hidden_info to "surprise = gift they don't know about yet." THIS is the headline moment.
5. Optional stretch (trade/promise): something that requires composing two learned concepts. Author only if time allows.

Each challenge: setup_blurb for the player, a win_predicate over WorldState, and (for teach challenges) the target concept id.

---

9. UI (Gradio, custom-styled — the "Off-Brand" badge)

Build with gr.Blocks + custom CSS. The aesthetic SHOULD be committed and distinctive (this is a judged "would you show a friend" entry, and there's a badge for not looking like default Gradio). Apply these principles:

• Commit to one strong aesthetic direction. Something that fits "first contact with a strange mind" — e.g. a quiet, alien, almost-archival feel; or a warm field-notes/xenolinguist's-journal feel. Pick one and execute it precisely. Avoid default Gradio greys and avoid generic purple-gradient-on-white "AI" look.
• Distinctive type. A characterful display font for the alien's voice paired with a clean readable body font. Not Inter/Roboto/Arial defaults.
• The three panels:
  1. The world — a simple visual (even CSS/SVG boxes is fine) showing objects/agents/containers and their state. The hidden flag must be visibly represented (e.g. an object inside the basket shown as concealed).
  2. The conversation — player utterances + the alien's replies. The alien's gap SHOULD be shown distinctly (a muted "…did not understand…" line) because it's both funny and instructive.
  3. The ledger — the learned concepts, rendered as a growing set (a constellation, a glossary, a stack of field-notes). When a concept is newly learned or re-applied, it SHOULD visibly light up / animate once. This is the screenshot.
• One well-orchestrated reveal beats scattered micro-animations. Put the polish budget on the "concept learned" / "generalization succeeded" moment.
• The success state (esp. the generalization challenge) MUST be unmistakable and shareable — a clear "it understood you" beat the player will want to screenshot for the required social post.

Keep backgrounds atmospheric, not flat. No browser-storage. Everything reactive via gr.State updates.

---

10. Repo layout

.
├── app.py                  # Gradio Blocks UI + turn loop wiring. Space entrypoint.
├── README.md               # Space card (YAML header: sdk: gradio, sdk_version, hardware) + how-to
├── requirements.txt        # pinned; see §0 for version floors
├── game/
│   ├── __init__.py
│   ├── models.py           # dataclasses: Concept, Obj, Agent, WorldState, Action, Challenge
│   ├── ledger.py           # seed primitives, add/gate, times_applied tracking
│   ├── world.py            # apply_action (deterministic), initial world factory
│   ├── challenges.py       # the 5–6 challenges + win predicates (§8)
│   ├── prompt.py           # build_prompt(ledger, world, challenge, utterance) -> str
│   ├── parsing.py          # tolerant JSON extract + validate + the §4 retry/fallback
│   └── brain.py            # Brain protocol + StubBrain | LocalBrain | ModalBrain (§6)
├── tests/
│   ├── test_world.py       # apply_action correctness, win predicates
│   ├── test_parsing.py     # malformed-output handling, fallback path
│   └── test_loop_stub.py   # full turn loop against StubBrain, zero GPU
└── modal/                  # OPTIONAL, only if §7 is used
    ├── serve.py            # Modal serving endpoint
    └── finetune_lora.py    # optional LoRA training job

---

11. Build order (maps to the two-weekend window)

This is spine-first on purpose. The classic hackathon death is polishing disconnected pieces that never form a loop.

Weekend 1 — make the loop real

• Day 1 (Fri eve / Sat):
  • game/models.py, game/world.py (apply_action + initial world), game/ledger.py (seed primitives).
  • game/parsing.py with the full §4 fallback.
  • StubBrain returning canned valid JSON for challenge #1 and #2.
  • Minimal app.py: one hardcoded challenge, the turn loop wired end-to-end against StubBrain, world + conversation rendering. Ugly is fine.
  • tests/test_world.py, tests/test_loop_stub.py green. All on zero GPU.
  • Stand up the empty Space early and push, to shake out the deploy/secrets/env before there's anything to lose.
• Day 2 (Sun):
  • LocalBrain on the Space: model to 'cuda' at module level, respond inside @spaces.GPU(duration=...). Pick the model by testing 3–4 ≤32B instruct models on the §3 prompt for JSON-formatting reliability first, capability second.
  • Ledger gating + candidate_concept flow + the times_applied increment.
  • Challenge #4 (the generalization beat) authored and working against the real model. If the generalization doesn't feel magical here, the concept design needs adjusting and you still have a week to pivot.

Midweek (evenings) — harden + de-risk

• Tighten the system prompt so the alien voice stays consistently alien and doesn't drift to helpful-assistant. Add constrained decoding (§3.2) if parse failures are common.
• This is the fine-tune decision point (§7): only if prompt-only is fighting you on JSON or voice.
• Catch the hackathon AMA if it lands midweek; ask specifically about ZeroGPU quota behaviour and JSON-mode tricks.

Weekend 2 — content, UI, ship

• Day 1 (Sat): finish the challenge arc (§8), then the custom-styled UI pass (§9) with the polish budget concentrated on the "concept learned" / "generalization succeeded" reveal.
• Day 2 (Sun): the submission is itself graded — Space under the org + demo video + social post. Budget the back half of Sunday for it. Script the demo around the single best generalization moment. Submit with margin, not at the deadline.

---

12. Definition of done

• Runs as a Gradio app on a ZeroGPU Space under the hackathon org, model ≤32B, loaded at module level, inference in @spaces.GPU.
• A fresh visitor gets their own session state (verified: two browsers don't share an alien).
• The full arc is playable: literal warm-up → first concept taught → at least one generalization beat where a learned concept transfers to a new situation unprompted.
• Malformed model output never crashes the app; the alien "looks confused" instead.
• The ledger visibly grows and a concept lights up on learn/re-use.
• Demo video + social post produced, both centred on the generalization moment.
• (Optional badges as time allows: LoRA fine-tune, custom UI — UI is in scope regardless.)

---

13. Things NOT to do

• Do NOT let the model judge whether communication "succeeded" — success is always a WorldState predicate.
• Do NOT seed social/abstract concepts in the ledger — they must be taught.
• Do NOT use module globals for game state.
• Do NOT lazy-load the model inside @spaces.GPU.
• Do NOT use torch.compile (unsupported on ZeroGPU).
• Do NOT make Modal a hard dependency of the Space.
• Do NOT burn ZeroGPU quota developing the loop — that's what StubBrain is for.
• Do NOT expand the challenge arc past ~6 — content scope creep kills the UI/submission time.