| --- |
| 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). |
|
|
