--- title: The Kintsugi Garden emoji: πŸͺ· colorFrom: yellow colorTo: gray sdk: gradio sdk_version: "6.16.0" python_version: "3.12" app_file: app.py thumbnail: logo.png pinned: false license: mit short_description: A symbolic mirror for dreams and inner transitions. tags: - track:wood - sponsor:modal - achievement:offgrid - achievement:welltuned - achievement:offbrand - achievement:llama - achievement:sharing - achievement:fieldnotes ---

The Kintsugi Garden β€” K and G mended by a gold seam

# The Kintsugi Garden > *A symbolic mirror for dreams, journals, and inner transitions.* **This is not therapy, diagnosis, prediction, or advice. It is a symbolic reflection tool.** --- ## Links - **Try it live:** - **3-minute demo video:** (also embedded in the app, under *About the Garden β†’ Watch the 3-minute demo*) - **Shared agent traces:** - **Write-up (LinkedIn):** - **Social post (X):** - **Track:** Thousand Token Wood (the whimsical / creative track) - **Bonus badges submitted for:** Off Brand, Best Demo - **Sponsor prize:** Modal β€” the model was fine-tuned on Modal (training compute) - Fine-tuned on Modal for training compute β€” see [`scripts/modal_qlora_train.py`](scripts/modal_qlora_train.py). --- ## The idea The Kintsugi Garden is a small-model symbolic reflection app. You give it a dream, a journal entry, an emotional trigger, a relationship pattern, a recurring symbol, or a life transition, and it offers back a *symbolic reading*: a Mirror, Key Symbols, Archetypal Themes, a possible Shadow Pattern, an Individuation Signal, and a Gentle Question β€” plus a session **Soul Map** and a deterministic mandala. Like the Japanese art of *kintsugi* β€” mending broken pottery with gold β€” the app treats the cracks and wounds in our inner stories as places where meaning can gather, never as something to diagnose or fix. --- ## How it was built β€” small model, strong scaffolding The Build Small Hackathon is about doing more with less. The Kintsugi Garden surrounds one small language model with deterministic Python scaffolding so the model only ever has to do what it is genuinely good at β€” composition and tone: - a curated **symbolic lexicon** β€” 42 symbols, each with meanings, archetypes, shadow motifs, and individuation signals (236 aliases for matching); - **symbol extraction** with aliases and plural handling; - a **four-layer safety stack** (see *Safety* below); - **prompt compression** β€” only the current entry and its extracted symbols reach the model; past entries are never sent; - **structured, parsed output** rendered as a calm reading; - a **session Soul Map** that gathers recurring symbols and archetypes; - a **deterministic mandala** drawn with PIL β€” no second model. If the language model cannot be loaded, the scaffolding still composes a meaningful, fully deterministic reading on its own β€” the app never hard-crashes. --- ## The model The live model is **[`ai-sherpa/Qwen3-8B-Kintsugi-GGUF`](https://huggingface.co/ai-sherpa/Qwen3-8B-Kintsugi-GGUF)** β€” a **QLoRA fine-tune of Qwen3-8B** trained on a small seed dataset for the symbolic-reflection voice, quantized to `Q4_K_M` GGUF (~4.7 GB). **Built on Modal.** The fine-tune was trained on a single H100 on **Modal** (QLoRA r=16 / Ξ±=32, ~$3 of compute) via `scripts/modal_qlora_train.py`, which runs the whole pipeline β€” base download, 4-bit quantization, LoRA, SFT, merge, and push-to-Hub β€” as one `modal run`. The live Space then loads the resulting GGUF. *(Modal is used for training/development; runtime inference is in-process llama.cpp, so the Modal claim is on the development arm.)* - **Backend:** in-process **`llama-cpp-python`** (the default). On the Space it runs under `@spaces.GPU` on **ZeroGPU (A10G)** with `n_gpu_layers=-1`, so the whole model offloads to the shared GPU when a worker attaches. First boot downloads the GGUF to the container cache (2–5 min); later calls attach in ~1–3 s. - **Size:** 8B parameters β€” comfortably under the hackathon's 32B cap. - **No second model, no external APIs.** The mandala is PIL; symbol content comes from the lexicon. Generation is invoked with thinking disabled so the output is clean Markdown prose rather than reasoning traces. Two rollback backends remain behind an env var for parity and resilience: `KINTSUGI_BACKEND=transformers` (base `Qwen/Qwen3-8B` via `transformers`) and `KINTSUGI_BACKEND=ollama` (a local `qwen3:8b` tag). The deterministic scaffolding, Soul Map, mandala, and safety check are identical across all three. Conservative generation config: `temperature=0.5`, `top_p=0.9`, `repetition_penalty=1.05`, `max_new_tokens=650` β€” tuned for steady, non-flighty reflections. --- ## The Soul Map and the archetype glossary Write more than once and a **Soul Map** forms: the symbols and archetypes that keep returning across your entries, each row gilded with a gold "kintsugi seam" scaled to how often it has recurred. Every archetype name is a small **glossary** entry β€” a definition, an honest **provenance** badge, and a citation. The provenance is deliberate: only a handful of the labels are genuinely Carl Jung's own (Shadow, Trickster, Mother, Divine Child, Hero, plus the Wise Old Man behind Sage and Magician). The rest come from Carol Pearson's popular twelve-archetype system, later Jungian analysts, or general myth β€” and the badge says so rather than overclaiming. Sources are recorded against Jung's *Collected Works* by volume and essay. The seven genuinely-Jung archetypes each open a short, gold-leaf **video**: the narrative prints top-to-bottom and gilds word-by-word in sync with the narration, the kintsugi seam drawing across as it goes. --- ## Safety boundaries The Kintsugi Garden is **not** a crisis tool. Every entry passes through a four-layer defense before any interpretation: 1. **Deterministic crisis detection** (`safety_check()`) β€” if it detects language around suicide, self-harm, harm to others, abuse, overdose, immediate danger, or being unsafe at home, the app does **not** produce a reading and instead points to emergency support. 2. **Mundane-language suppression** β€” so ordinary words ("dead tired", "killing time") don't trip the gate. 3. **Prompt-level voice rules** β€” the model is constrained to possibilities ("may suggest", "one possible reading is"), never diagnoses, predictions, or instructions. 4. **Post-LLM sanitizers** β€” strip any prescriptive or invented content that slips through. The crisis response shown to the user: > I'm sorry you're carrying this. This tool is not designed for crisis support > or safety situations. Please contact local emergency services now, or reach > out immediately to someone you trust. If you may hurt yourself or someone > else, seek urgent help now. Crisis disclosures are never written to storage. --- ## Why a deterministic mandala instead of image generation The Symbolic Mandala is drawn with PIL: concentric circles, up to eight symbol nodes placed evenly around a ring, connecting lines, glyph labels, a kintsugi-gold palette, and a center emblem. Identical inputs always yield an identical image. It keeps the app light (no second model, no diffusion), is reproducible and explainable, and runs anywhere β€” exactly the "build small" spirit. --- ## The interface The product is a hand-rolled journal UI β€” custom HTML/CSS/JS served via `gradio.Server` β€” at `/` (with `/journal` as an alias). Past readings are stored in the browser's `localStorage` (`kintsugi-journal-v1`); each completed reading persists for re-reading, and crisis disclosures are never written to storage. It carries the gilded Soul Map with the clickable archetype glossary, the embedded demo video, and a set of kintsugi visual treatments: a drop cap, gold BΓ©zier seams between sections, a paper-grain texture overlay, per-section glyphs, and a time-of-day adaptive palette (dawn / day / dusk / night). This custom journal is the basis of the **Off Brand** submission: it goes well past the default Gradio look while remaining a Gradio app. The pipeline behind it: safety gate β†’ symbol extraction β†’ deterministic mandala β†’ fine-tuned-model reading. --- ## Deployment - **SDK:** Gradio `6.16.0` (required for `gradio.Server`). - **Python:** 3.12 (3.13 dropped `audioop`, which this Gradio line's `pydub` dependency still imports). - **Hardware:** ZeroGPU (`zero-a10g`). Runtime config lives entirely in this README front-matter plus `requirements.txt` β€” no `Dockerfile`. ### Running locally ```bash pip install -r requirements.txt python3.10 -u app.py ``` The default `llama-cpp-python` backend downloads `ai-sherpa/Qwen3-8B-Kintsugi-GGUF/Qwen3-8B-Kintsugi-Q4_K_M.gguf` on first run (cached afterward) and binds to the first free port in 7860–7863. --- ## A closing note The Kintsugi Garden keeps you sovereign. Nothing it offers is a verdict β€” only gentle, symbolic possibilities to hold lightly. The gold is already in the cracks. See [WHY.md](WHY.md) for what we believe this tool is for.