---
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](https://huggingface.co/Qwen/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](https://huggingface.co/black-forest-labs/FLUX.2-klein-9B)**
  (~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](https://fonts.google.com/specimen/Cinzel) (OFL).