FIELD_NOTES.md

Field Notes — Building Tabras

What I learned building a small-model card duel for the Build Small hackathon.

1. ZeroGPU is a GPU-sharing mechanism, not a hosted GPU provider

This was my biggest wall, and I hit it late. I built Tabras assuming a Hugging Face ZeroGPU Space would behave like a hosted GPU I could just run my models on. It does not. ZeroGPU time-slices a shared GPU and only grants it inside @spaces.GPU functions — and it ships args/returns between processes by pickling them. That breaks the moment you try to hand it a trust_remote_code model (MiniCPM) or a diffusers pipeline: they aren't picklable, and low-level CUDA init isn't allowed in the main process at all. I burned real time learning this through a wall of PicklingError and "CUDA init reached" tracebacks.

The last-minute fix was to re-architect: make the Space a thin HTTP client and move every model onto Modal GPU endpoints (MiniCPM for cards, Nemotron for the boss, SDXL-Turbo for art), each autoscaled on its own dedicated GPU. The Space just POSTs prompts and renders the results. Lesson: understand the execution model of your compute before you design around it, not after.

Crucially, Tabras still runs fully local / off-grid — a MODE switch flips between LOCAL (in-process Transformers/Diffusers, or a local llama.cpp server for MiniCPM) and MODAL (the hosted endpoints). The README has the local instructions. Small and local was always the point, and keeping that path alive mattered to me.

2. Small models: surprisingly powerful, with sharp edges

• Image models punch way above their size. SDXL-Turbo, in ~4 denoising steps, produced genuinely striking card art and theme backgrounds. The visual identity of the whole game is carried by a tiny, fast diffusion model.
• Nemotron was the standout for agentic / tool-calling work. Giving it the public board state and a constrained JSON action schema, it reliably reads the situation and returns valid, sensible plays. A 4B model running a competent opponent was the part I expected to be flaky and wasn't.
• The text model owns meaning, not structure. MiniCPM writes evocative names and flavor, but it leans on lazy patterns ("Fire Card"), leaks prompt vocabulary, and truncates its own JSON. The single highest-leverage fix was reordering the requested JSON so effects and name come first — they survive a token cutoff that used to silently collapse a whole card to a fallback. Design around what the model is bad at.

3. Perceived latency beats raw latency

Small/local inference isn't instant, and the variance (some packs fast, some slow) looked worse than a consistent wait. The fixes that made the demo feel good were mostly UX, not compute:

• A minimum loading window on each draft transition, so every pick shows the same deliberate "forging" beat — that uniform pause hides the slow ones behind the same animation the fast ones use.
• Prefetching every branch of the draft during idle time (the reveal/rules screens, and while you read the current pack), so whichever card you pick, its next pack is already generating.
• Pre-baking static art for the fixed backbone cards once and bundling it, so they never spend a live generation or shimmer.

A consistent 2s always beats an unpredictable 0–8s.

4. Card-game design is hard — and a ton of fun

Balancing a generative card game is genuinely difficult. The core principle that made it tractable: the LLM owns meaning, the engine owns math. The model picks which effects a card has and writes its identity; deterministic Python prices every number against a point budget, so cards are balanced-by-construction no matter what the model invents. The draft is deck-aware — it reads the build you're assembling and shapes packs toward it, sometimes dangling a tempting off-archetype card. Getting that loop to feel fair and surprising was the most fun part of the whole project.

5. Ambition under a deadline

This was an ambitious build for the time window — three small models, a custom UI, a last-minute compute re-architecture, and a real game loop. The thing that saved me was treating the demo video as the deliverable and optimizing the local recording surface hard, rather than betting everything on a flawless live Space. I'm proud of how much of it came together, and I had a lot of fun doing it.