Codex commited on
Commit
fe0b867
·
1 Parent(s): a8afc36

Update public README

Browse files
Files changed (1) hide show
  1. README.md +93 -165
README.md CHANGED
@@ -1,210 +1,138 @@
1
- # Tabras
2
-
3
- An AI-driven roguelite deckbuilder duel. The player and an AI-controlled enemy wizard each draft a 15-card deck from freshly-generated cards, then duel over three rounds. Every drafted card's effect-shape, name, flavor, and art is generated per run — no two runs share a deck. After a run, the cards are gone for good.
4
-
5
- Built for the **Build Small Hackathon** (Gradio + Hugging Face), track: *An Adventure in Thousand Token Wood*. Constraint: every model ≤32B params, local-first, deployed as a Gradio app on a HF Space.
6
-
7
  ---
8
-
9
- ## Core invariant (do not violate)
10
-
11
- **The LLM owns meaning; the engine owns math.**
12
-
13
- The model chooses *which* effects a card has (from the fixed primitive vocabulary below, via tool call) and writes its name, flavor, and art prompt — in service of a coherent fantasy, aware of the deck being built. The **engine** assigns every numeric magnitude against a point budget.
14
-
15
- The model NEVER sets final power values. This is what makes generated cards balanced-by-construction. Any code path where model output directly determines a damage/block/heal number is a bug. (The one bounded exception: "miracle" cards, where the engine rolls a wide but hard-capped budget multiplier.)
16
-
17
- ---
18
-
19
- ## Game rules (locked)
20
-
21
- - **20 HP** per player.
22
- - **Energy** ramps each turn (1 → up to 5). Regenerating pool, no lands.
23
- - **Paired-round turns:** each round both players act; a flip decides order within the round. Knowing/manipulating order is a mechanic (Ice's Initiative).
24
- - **15-card deck:** 6 standardized backbone cards (same for all schools) + 9 LLM-generated synergy picks (drafted, deck-aware).
25
- - **Deck-out:** no reshuffle. Drawing from an empty deck deals escalating fatigue damage (1, 2, 3, …) — a finishing clock, not a managed resource. Decks are damage-dense; you're expected to win before decking out.
26
- - **Win:** reduce the opponent to 0 across a three-phase duel.
27
-
28
- ### Damage anchor
29
- `1 budget point = 2 damage` for a vanilla attack. All other primitive costs are relative to this.
30
-
31
  ---
32
 
33
- ## The 13 primitives (the spine — `primitives.py`)
34
 
35
- The LLM composes cards by selecting from these and writing flavor; the engine assigns N against the card's budget. Costs below are STARTING values — linear primitives are set; multipliers are marked TUNE (overcost on first pass, tighten in playtest).
36
 
37
- ### Damage / win-condition
38
- 1. **Deal** — direct damage. `1 pt = 2 damage`. The anchor.
39
- 2. **Burn** — deferred damage, X/turn for N turns (decaying or flat). Roughly on-rate; in a short game needs a slight premium to justify the delay. *Deferred-timer effect.*
40
- 3. **Bomb** — big delayed burst: deal X in N turns, telegraphed. High-variance. TUNE. *Deferred-timer effect.* (Fire signature pick: 4 energy → 9 damage in 3 turns.)
41
 
42
- ### Defense / survival (a first-class, flexible axis — defense enables real strategic options, not just a tax)
43
- 4. **Block** — temporary shield until your next turn. **Stacks.** `1 pt ≈ 3 block` (defense priced slightly cheaper than damage).
44
- 5. **Ward** — persistent shield. **Stacks. Expensive: `1 pt = 1 block`.** All-or-nothing: a ward can only be removed early by a *single hit meeting its threshold* — chip/multi-hit damage bounces off. The breaking hit is **fully absorbed** (a bubble that eats one decisive blow, then vanishes — excess does NOT carry to HP). [DEFAULT — override if you want break-through.] *Deferred/persistent-timer effect.*
45
- 6. **Weak** — opponent deals Y less damage until your next turn. Defensive (damage-prevention). Prices like Block (linear). Mirror of Vulnerable.
46
 
47
- > Heal is intentionally NOT a primitive (cut for pace — healing prolongs fights against the short-aggressive goal). Defensive flexibility comes from Block + Ward + Weak instead. Revisit only if playtest shows fights ending too fast.
48
 
49
- ### Tempo / resource (do NOT price off the damage rate — price by what they enable; TUNE-ish)
50
- 7. **Draw** — draw N cards. Price so it costs a tempo turn (backbone: 3 energy → draw 2). Net card advantage but you skip board impact.
51
- 8. **Energy** — gain X energy this turn (enables combo turns). Dangerous primitive; price slightly net-negative immediately so it's only worth it in combo decks. TUNE.
52
- 9. **Initiative** — manipulate round order (opponent goes second next round). Bounded to one round. Prices as tempo, not damage. (Ice signature: 3 energy → deal 2 + opponent second next round.) TUNE.
53
 
54
- ### Multipliers & combo-glue (the depth — ALL TUNE, overcost on first pass; this is where broken combos live)
55
- 10. **Multi-hit** — apply an effect N times. *Multiplies* the cost of what it hits. The single most dangerous primitive (multi-hit × Deal or × Burn). Overcost hard. Note: multi-hit chip CANNOT break a Ward (each hit is below threshold) — built-in school counterplay.
56
- 11. **Vulnerable** — enemy takes X more damage for N turns. Offensive *multiplier* — combos with Deal/Multi-hit. Prices as a multiplier, not flat. TUNE.
57
- 12. **Conditional** — "if [state], then bonus" (e.g., if enemy below half HP, +damage). Depth via sequencing; prices by how often the condition is live. TUNE.
58
- 13. **Scaling** — effect grows with a counter (cards played this turn, banked shield charge, turns elapsed). Snowball primitive — overcost, runaway games start here. TUNE. Earth scaling spends banked shield charge.
59
 
60
- ### Vulnerable / Weak pair
61
- Vulnerable (enemy *takes* X more — affects damage you deal) and Weak (enemy *deals* Y less — affects damage you take) are mirrored levers. Despite the symmetry they price differently: Vulnerable is a multiplier (TUNE), Weak is flat damage-prevention (linear, like Block).
62
 
63
- ### Deferred-effect machinery
64
- Burn, Bomb, and Ward all run on ONE shared deferred/persistent-effect timer system (one mechanism, three flavors — a build simplification). [DEFAULT — confirm.] These effects only ever DO things on a schedule; they are never targetable entities. If a deferred effect ever needs to be attacked/blocked/killed, that's the board-state trap — reject it.
 
 
 
 
 
65
 
66
- ---
67
 
68
- ## The 6-card standardized backbone (same for every school)
 
 
69
 
70
- | Card | Cost | Effect |
71
- |------|------|--------|
72
- | Attack (weak) | 1 | deal 2 |
73
- | Attack (medium) | 3 | deal 4 |
74
- | Attack (strong) | 5 | deal 6 |
75
- | Block (weak) | 2 | block 3 |
76
- | Block (medium) | 3 | block 4 |
77
- | Draw (small) | 2 | draw 1 |
78
 
79
- Identical across all schools. Only art/flavor reskins per run's theme. School identity lives entirely in the **draft pool**, not the backbone.
80
 
81
- ---
 
 
 
 
82
 
83
- ## Schools (v1: three)
84
 
85
- School biases which primitives your 9 synergy picks draw from (a synergizable archetype), not your backbone. Theme = aesthetics only.
86
 
87
- Schools map to **player temperaments**, not just primitive bundles — the choice signals how you want to play:
88
 
89
- - **Fire — traditional burn (classic aggression).** The straightforward, immediately-legible school: deal damage, stack burns, race them down. Primitives: Deal, Burn, Bomb, Scaling.
90
- Anchor (decaying burn): `4 energy: 3 now, 2 next turn, 1 turn after`.
91
- Signature pick (bomb): `4 energy: 9 damage, detonates in 3 turns`.
92
- - **Ice — speed (fast tempo).** For players who race: strike first, amplify, burst. NOT defensive — Ice outruns rather than turtles, so it carries no Block. Primitives: Initiative, Vulnerable, Multi-hit, Conditional.
93
- Anchor: `3 energy: deal 2, opponent goes second next round`.
94
- - **Earth — slow (durable control).** For players who outlast: grind, stack defense, win late. Half of damage absorbed by Block, rounded down, banks as shield charge; Ward does not bank charge. Earth Scaling releases that banked charge as burst damage, then empties it. Defense concentrates HERE deliberately — this is the school's identity, not a tax. Primitives: Ward, Block, Scaling, Conditional.
95
- Anchor (refreshing ward): `4 energy: block 3 per turn for the next 2 turns`.
96
-
97
- Defense is deliberately NOT spread evenly: it concentrates in Earth (the slow school), is absent from Ice (speed doesn't block, it races), and is incidental in Fire (burn just out-damages). This makes the three schools feel different to *play*, not just to read.
98
 
99
- v1 themes (3): pick from Dark Fantasy / Cyberpunk / Wuxia / etc. — aesthetic skin only.
100
 
101
- ---
 
 
102
 
103
- ## Models (all ≤32B, per-model rule — multiple ≤32B models allowed)
104
 
105
- Three models; two satisfy the Nemotron + MiniCPM sponsor requirement:
 
 
106
 
107
- - **Boss / enemy AI:** Nemotron 3 Nano (4B dense, or 30B-A3B if VRAM allows — stronger reasoning, heavier footprint). Picks which pre-costed cards to play, reactively, given board state + visible player deck.
108
- - **Picker / card author:** MiniCPM-V 4.6 (1.3B). Tool-call generation of synergy picks. Llama.cpp-compatible (badge).
109
- - **Image:** SDXL-Turbo class, fine-tuned to one card-art style (LoRA — Well-Tuned badge).
110
 
111
- **Real constraint is VRAM on the Space GPU, not the 32B rule.** A 30B-A3B boss needs full weights resident even though MoE keeps active params ~3B. Picker and boss can share one base model in two isolated contexts if VRAM is tight; the boss context must NOT see card-authoring history.
 
 
112
 
113
- Local model wiring supports three modes:
114
 
115
  ```bash
116
- # MiniCPM through an OpenAI-compatible local chat server.
117
- TABRAS_CARD_ENDPOINT=http://localhost:8080/v1/chat/completions
118
- TABRAS_CARD_MODEL=minicpm-v-4.6
119
-
120
- # MiniCPM direct Transformers model.chat path.
121
  TABRAS_CARD_BACKEND=transformers
122
  TABRAS_CARD_MODEL=openbmb/MiniCPM-V-4
123
-
124
- # Nemotron through an OpenAI-compatible chat server.
125
- TABRAS_AI_BOSS=1
126
- TABRAS_BOSS_ENDPOINT=http://localhost:8081/v1/chat/completions
127
- TABRAS_BOSS_MODEL=nvidia/Nemotron-Mini-4B-Instruct
128
-
129
- # Nemotron through a completion server with the documented <extra_id_*> prompt markers.
130
- TABRAS_AI_BOSS=1
131
- TABRAS_BOSS_BACKEND=completion
132
- TABRAS_BOSS_ENDPOINT=http://localhost:8081/v1/completions
133
-
134
- # Nemotron direct Transformers path using tokenizer.apply_chat_template.
135
  TABRAS_AI_BOSS=1
136
  TABRAS_BOSS_BACKEND=transformers
137
  TABRAS_BOSS_MODEL=nvidia/Nemotron-Mini-4B-Instruct
 
 
 
138
  ```
139
 
140
- ---
141
-
142
- ## Components
143
-
144
- ### `primitives.py` — THE SPINE, build first
145
- The 13 primitives above. Each: id, tool-call signature, point cost, templated display string. Nothing else works until this exists.
146
-
147
- ### `budget.py`
148
- card cost (energy) → point budget → spends budget assigning N to the LLM's chosen primitives → returns a fully-costed, balanced card. Miracle variant: wide but HARD-CAPPED budget multiplier (the only high-variance path).
149
-
150
- ### `generator.py`
151
- LLM tool call: `(school, theme, current_deck) → effect IDs + counts + name + flavor + art_prompt`. **`current_deck` is mandatory** — deck-awareness is the load-bearing AI. Passes effects to `budget.py`. Schools bias the primitive subset.
152
-
153
- ### `game.py`
154
- Deterministic. Paired-round turn loop, energy ramp, initiative flip, card resolution (incl. the Ward threshold/bubble rule), Block/Ward stacking, fatigue/deck-out, win/loss. Deferred effects fire on schedule, never targetable. **All rules and numbers live here, never in a model.**
155
 
156
- ### `boss.py`
157
- Boss drafts its own deck from `generator.py` (synergy-biased) and the boss LLM plays it — picks pre-costed cards reactively. Boss cards capped at generation → play is inherently damage-bounded. 3 phases = 3 escalating drafted wizards (rising budget/energy). Phase N+1's deck generates during phase N combat.
 
 
 
 
 
 
 
 
 
 
158
 
159
- ### `draft.py`
160
- 6 backbone + 9 deck-aware synergy picks = 15. Draft UI structure is a thin swappable layer — finalize after core playtests.
161
 
162
- ### `app.py`
163
- Gradio Space. Cards = styled containers in rows. No engine, no animations. Core state (both HP, enemy intent, energy, card costs/effects) ALWAYS visible — never behind hover. Effect text TEMPLATED from the primitive schema (fixed per-primitive format), never free prose — parses in ~1s. Custom themed frames (Custom UI badge). Landing/menu loads model-free; generation fires on "Start," not page load (protects compute + cold-start UX).
164
 
165
- ---
166
-
167
- ## Generation scheduling (latency)
168
- - Synergy-pick art generates during the draft; cards choosable on mechanical text while art streams in.
169
- - Backbone art backfills (mechanics instant).
170
- - Boss deck + art generate during player activity. Boss art lowest priority (seen when played, not drafted).
171
- - Lazy-load by need. Text instant, art progressive.
172
-
173
- ---
174
-
175
- ## Build order (timeline-driven)
176
- 1. `primitives.py` (the 13)
177
- 2. `budget.py`
178
- 3. `generator.py` + `game.py` — **spell-only, text-only, NO ART YET**
179
- 4. **Playtest for fun on a real human** — the one risk no architecture fixes is whether reading fresh cards every game is fun. Answer this before investing downstream.
180
- 5. `boss.py`
181
- 6. `draft.py` + backbone wiring + Ward threshold rule
182
- 7. Art generation (base SDXL first)
183
- 8. Fine-tune art LoRA + UI polish
184
-
185
- Art, fine-tuning, polish come LAST. A playable, fun, text-only core is submittable; an unfinished ambitious build is not. Time is the binding constraint, not compute.
186
-
187
- ---
188
-
189
- ## Hard rules
190
- - The model never sets numbers (except the engine-bounded, hard-capped miracle roll).
191
- - No board-state entities. Burn/Bomb/Ward/summons are deferred *effects*, never targetable units.
192
- - v1 scope is fixed: spell-only, 3 schools (Fire/Ice/Earth) × 3 themes, one art style. "If time permits" features stay deferred until the core ships and is tuned.
193
- - The 9 synergy picks must be generated **deck-aware** — picks that ignore the current deck reduce the generator to a random table.
194
 
195
- ---
196
 
197
- ## Open decisions (resolve before/at the relevant build step)
198
- - **Multiplier costs (primitives 10–13):** all TUNE — set conservative overcosted guesses, tighten in playtest. Multi-hit and Scaling are the highest-risk.
199
- - **Ward break rule:** full-absorb bubble (default) vs. break-through. Affects `game.py` resolution.
200
- - **Deferred-timer unification:** Burn/Bomb/Ward on one system (default/recommended).
201
- - **The 3 specific themes** (concept locked, the three not chosen).
202
 
203
- ---
204
 
205
- ## Compute
206
- - $250 Modal (training/serving GPU) — primary budget, mostly art fine-tune + batch art gen.
207
- - $20 HF (ZeroGPU/Space hosting) + 40 min/day free ZeroGPU. Thin for live three-model serving — test in focused sessions, gate generation behind intent, don't leave the Space running.
208
 
209
- ## Deliverables (due June 15)
210
- Space under the `build-small-hackathon` org + demo video + social post.
 
 
 
 
 
 
 
1
  ---
2
+ title: Tabras
3
+ emoji: 🃏
4
+ colorFrom: purple
5
+ colorTo: indigo
6
+ sdk: gradio
7
+ sdk_version: 6.17.3
8
+ app_file: app_hf.py
9
+ pinned: false
10
+ license: mit
11
+ tags:
12
+ - thousand-token-wood
13
+ - off-brand
14
+ - tiny-titan
15
+ - minicpm
16
+ - nemotron
17
+ models:
18
+ - openbmb/MiniCPM-V-4
19
+ - nvidia/Nemotron-Mini-4B-Instruct
20
+ - stabilityai/sdxl-turbo
 
 
 
 
21
  ---
22
 
23
+ # Tabras
24
 
25
+ Tabras is a small-model roguelite card duel built for the Build Small Hackathon's **An Adventure in Thousand Token Wood** track.
26
 
27
+ You name a challenger, choose a world, choose a school of magic, draft a 15-card deck, and fight an AI boss across a short tactical duel. The fun part is that the draft is not a static card list: each run asks a small model to author new card names, flavor, effects, and art direction around your chosen theme and the deck you are already building.
 
 
 
28
 
29
+ The engine keeps the game fair. The model invents the card identity; deterministic Python code prices and resolves the card mechanics.
 
 
 
30
 
31
+ ## What Makes It AI-Native
32
 
33
+ - **MiniCPM authors draft cards.** It proposes card concepts, names, flavor text, and effect shapes for the current deck.
34
+ - **Nemotron plays the boss.** The boss reads the public board state and chooses from its hidden hand.
35
+ - **SDXL-Turbo illustrates cards.** Card art is generated lazily so the draft can remain playable while images arrive.
36
+ - **The rules engine owns the numbers.** Damage, block, burn, ward, and tempo values are assigned by deterministic budget code rather than raw model output.
37
 
38
+ That split is the core design: AI provides surprise and taste, while the engine preserves balance.
 
 
 
 
39
 
40
+ ## How To Play
 
41
 
42
+ 1. Click **Play Now**.
43
+ 2. Enter your name.
44
+ 3. Choose a background world: Dark Fantasy, Cyberpunk, or Anime.
45
+ 4. Choose a school of magic: Fire, Ice, or Earth.
46
+ 5. Read the short rules page while the first draft pack starts loading.
47
+ 6. Draft 9 generated cards onto a 6-card starter backbone.
48
+ 7. Duel the boss.
49
 
50
+ ### Schools
51
 
52
+ - **Fire** is pressure: direct damage, burn, bombs, and fast finishers.
53
+ - **Ice** is tempo: initiative, vulnerable windows, multi-hit pressure, and burst timing.
54
+ - **Earth** is control: block, ward, shield charge, and delayed counterpunches.
55
 
56
+ ## Model Stack
 
 
 
 
 
 
 
57
 
58
+ All listed models are under the hackathon's 32B parameter limit.
59
 
60
+ | Role | Default model | Use |
61
+ | --- | --- | --- |
62
+ | Card author | `openbmb/MiniCPM-V-4` | Draft pack text and card concepts |
63
+ | Boss AI | `nvidia/Nemotron-Mini-4B-Instruct` | Enemy play decisions |
64
+ | Art | `stabilityai/sdxl-turbo` | Fast card illustration |
65
 
66
+ The Hugging Face Space entry point is [app_hf.py](app_hf.py). It defaults to Transformers/Diffusers backends so it can run on a CUDA Space without requiring a local llama.cpp server.
67
 
68
+ ## Running Locally
69
 
70
+ Install dependencies:
71
 
72
+ ```bash
73
+ python3 -m pip install -r requirements.txt
74
+ ```
 
 
 
 
 
 
75
 
76
+ Run the Gradio app without local model servers:
77
 
78
+ ```bash
79
+ python3 app.py
80
+ ```
81
 
82
+ For the local AI path, start Tabras through:
83
 
84
+ ```bash
85
+ python3 launch_ai.py
86
+ ```
87
 
88
+ `launch_ai.py` expects the MiniCPM GGUF at:
 
 
89
 
90
+ ```text
91
+ models/minicpm-v-4.6-gguf/MiniCPM-V-4.6-Q4_K_M.gguf
92
+ ```
93
 
94
+ You can also configure backends with environment variables:
95
 
96
  ```bash
 
 
 
 
 
97
  TABRAS_CARD_BACKEND=transformers
98
  TABRAS_CARD_MODEL=openbmb/MiniCPM-V-4
 
 
 
 
 
 
 
 
 
 
 
 
99
  TABRAS_AI_BOSS=1
100
  TABRAS_BOSS_BACKEND=transformers
101
  TABRAS_BOSS_MODEL=nvidia/Nemotron-Mini-4B-Instruct
102
+ TABRAS_ART_BACKEND=diffusers
103
+ TABRAS_ART_MODEL=stabilityai/sdxl-turbo
104
+ python3 app_hf.py
105
  ```
106
 
107
+ ## Project Structure
 
 
 
 
 
 
 
 
 
 
 
 
 
 
108
 
109
+ | File | Purpose |
110
+ | --- | --- |
111
+ | `app.py` | Gradio UI and interaction flow |
112
+ | `app_hf.py` | Hugging Face Space entry point |
113
+ | `primitives.py` | Fixed vocabulary of card effects |
114
+ | `budget.py` | Deterministic card costing |
115
+ | `generator.py` | Card authoring and model payload handling |
116
+ | `game.py` | Deterministic combat engine |
117
+ | `boss.py` | Boss decision layer |
118
+ | `ui.py` | Draft and battle rendering helpers |
119
+ | `art.py` | Art generation client |
120
+ | `forge.py` | Background generation queue |
121
 
122
+ ## Development
 
123
 
124
+ Run tests:
 
125
 
126
+ ```bash
127
+ python3 -m pytest -q
128
+ ```
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
129
 
130
+ The deterministic game core is intentionally heavily tested. Model-dependent paths should be tested with mocked clients so tests stay fast and repeatable.
131
 
132
+ ## Status
 
 
 
 
133
 
134
+ Tabras is a hackathon prototype. The current build focuses on the full playable loop: setup, generated drafting, lazy art, boss play, and a custom Gradio UI. Balance, card variety, and image quality are still active tuning areas.
135
 
136
+ ## License
 
 
137
 
138
+ MIT