title	Tabras
emoji	🃏
colorFrom	purple
colorTo	indigo
sdk	gradio
sdk_version	6.17.3
app_file	app_hf.py
pinned	false
license	mit
tags	thousand-token-wood off-brand tiny-titan minicpm nemotron
models	openbmb/MiniCPM-V-4 nvidia/Nemotron-Mini-4B-Instruct stabilityai/sdxl-turbo

Tabras

Tabras is a small-model roguelite card duel built for the Build Small Hackathon's An Adventure in Thousand Token Wood track.

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.

The engine keeps the game fair. The model invents the card identity; deterministic Python code prices and resolves the card mechanics.

What Makes It AI-Native

• MiniCPM authors draft cards. It proposes card concepts, names, flavor text, and effect shapes for the current deck.
• Nemotron plays the boss. The boss reads the public board state and chooses from its hidden hand.
• SDXL-Turbo illustrates cards. Card art is generated lazily so the draft can remain playable while images arrive.
• The rules engine owns the numbers. Damage, block, burn, ward, and tempo values are assigned by deterministic budget code rather than raw model output.

That split is the core design: AI provides surprise and taste, while the engine preserves balance.

How To Play

1. Click Play Now.
2. Enter your name.
3. Choose a background world: Dark Fantasy, Cyberpunk, or Anime.
4. Choose a school of magic: Fire, Ice, or Earth.
5. Read the short rules page while the first draft pack starts loading.
6. Draft 9 generated cards onto a 6-card starter backbone.
7. Duel the boss.

Schools

• Fire is pressure: direct damage, burn, bombs, and fast finishers.
• Ice is tempo: initiative, vulnerable windows, multi-hit pressure, and burst timing.
• Earth is control: block, ward, shield charge, and delayed counterpunches.

Model Stack

All listed models are under the hackathon's 32B parameter limit.

Role	Default model	Use
Card author	openbmb/MiniCPM-V-4	Draft pack text and card concepts
Boss AI	nvidia/Nemotron-Mini-4B-Instruct	Enemy play decisions
Art	stabilityai/sdxl-turbo	Fast card illustration

The Hugging Face Space entry point is app_hf.py. It defaults to Transformers/Diffusers backends so it can run on a CUDA Space without requiring a local llama.cpp server.

Running Locally

Install dependencies:

python3 -m pip install -r requirements.txt

Run the Gradio app without local model servers:

python3 app.py

For the local AI path, start Tabras through:

python3 launch_ai.py

launch_ai.py expects the MiniCPM GGUF at:

models/minicpm-v-4.6-gguf/MiniCPM-V-4.6-Q4_K_M.gguf

You can also configure backends with environment variables:

TABRAS_CARD_BACKEND=transformers
TABRAS_CARD_MODEL=openbmb/MiniCPM-V-4
TABRAS_AI_BOSS=1
TABRAS_BOSS_BACKEND=transformers
TABRAS_BOSS_MODEL=nvidia/Nemotron-Mini-4B-Instruct
TABRAS_ART_BACKEND=diffusers
TABRAS_ART_MODEL=stabilityai/sdxl-turbo
python3 app_hf.py

Project Structure

File	Purpose
app.py	Gradio UI and interaction flow
app_hf.py	Hugging Face Space entry point
primitives.py	Fixed vocabulary of card effects
budget.py	Deterministic card costing
generator.py	Card authoring and model payload handling
game.py	Deterministic combat engine
boss.py	Boss decision layer
ui.py	Draft and battle rendering helpers
art.py	Art generation client
forge.py	Background generation queue