README.md

metadata

title: Arcana
emoji: 🔮
colorFrom: purple
colorTo: indigo
sdk: gradio
sdk_version: 6.14.0
app_file: app.py
pinned: false
license: mit
tags:
  - track:wood
  - achievement:offgrid
  - achievement:offbrand
  - achievement:llama
  - achievement:sharing
  - achievement:fieldnotes

🔮 Arcana — a themed concept-tarot generator & reader

Name any domain or theme — thermodynamics, Lord of the Rings, breakfast foods, the French Revolution — and Arcana invents a whole tarot deck for it, paints the 22 cards, and reads your fortune in them.

Built for the HF / Gradio Build Small Hackathon — track Adventure in Thousand Token Wood.

Submission

• 🎥 Demo video: https://youtu.be/j-yLxVL9WPY
• 📝 Blog post (the build, in depth): https://huggingface.co/blog/build-small-hackathon/arcana-blog
• 📣 Social post: https://www.linkedin.com/posts/jeremy-e-b-guntoro-8406a5174_huggingface-buildsmallhackathon-ai-share-7472048547522134016-2LBD/
• 🔍 Agent traces (Hub dataset): https://huggingface.co/datasets/build-small-hackathon/arcana-deliverables

Badges claimed: Off the Grid (no cloud APIs), Off-Brand (custom UI), Llama Champion (llama.cpp), Sharing is Caring (open agent traces), Field Notes (write-up).

How it works — invent the meanings, then reason over them

The load-bearing AI move is not the art (plenty of tools draw tarot cards). It's the semantic invention — deciding what each domain concept means archetypally — and then the progressive reasoning over a spread of those concepts in combination. Both are language tasks, so a small ≤32B text model is the right core.

theme + visual style
      │
      ▼
 Deck Designer (Qwen3-14B)     maps the 22 Major Arcana → in-theme concepts (+ why)
      │
      ▼
 Scribe (Qwen3-14B)            invents each card's meaning + art brief from the concept
      │                        (fanned across the GPU slots — many cards at once)
      ├─► image model (FLUX.2-klein) → 22 central arts + one deck-back (parallel)
      │        │
      │        ▼
      │   Compositor (Pillow)  art + reusable gold frame + crisp title/numeral
      ▼
 Reader / Oracle (Qwen3-14B)   draws a spread and turns the cards one at a time —
                               a partial read as each lands, the synthesis held to the end

For example, mapping thermodynamics: Entropy → Death, Absolute Zero → The Hermit, The Critical Point → The Tower. The fit has to feel clever-but-right, never arbitrary — that quality is the whole point.

Off the grid — open models, ≤32B, running on the model in front of you

No closed/frontier models, and no cloud inference APIs. Everything runs locally on the Space's own GPU (Hugging Face ZeroGPU):

• Language — Qwen3-14B (Apache-2.0, ~14.8B), one model for all three roles (mapping, scribe, reading), served in-process via llama.cpp (a Q4_K_M GGUF).
• Image — FLUX.2-klein (~9B, distilled, 4 steps), served in-process via diffusers.

The scribe and the painter are each fanned out across the ZeroGPU slots so the 22 cards' meanings and images are produced in parallel.

Using it

• Generate New Deck — type a theme, pick a visual style (Rider-Waite-Smith, Thoth, Marseille, Playful, or your own Custom look), conjure the deck. The deck view fills in card-by-card; download it as a self-contained .zip.
• View Deck / Read from Existing Deck — upload a deck .zip you downloaded earlier; it's reconstructed and opened (portable, no server-side storage).
• A reading turns the cards face-up one at a time with a partial interpretation each, then weaves them into one synthesis.

Configuration (Space defaults to fully local)

env var	value on the Space	meaning
LLM_BACKEND	local	run the LLM in-process on the GPU (llama.cpp)
IMAGE_BACKEND	local	run the image model in-process on the GPU (diffusers)
LOCAL_IMAGE_MODEL	black-forest-labs/FLUX.2-klein-9B	the image model
HF_TOKEN	—	Hub access for the model weights (Space secret)

The LLM defaults to unsloth/Qwen3-14B-GGUF. There is no cloud-inference path — every model runs in-process on the Space's own GPU. It's "off the grid".

Assets & licensing

App code is MIT. Text is generated by Qwen3-14B (Apache-2.0). Card art is generated by FLUX.2-klein-9B — "This FLUX Model is licensed by Black Forest Labs Inc. under the FLUX.2 Non-Commercial License" — so generated decks are for non-commercial use. Title/numeral type is Cinzel (OFL).