README.md

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

<p align="center">
  <img src="logo.svg" alt="The Kintsugi Garden — K and G mended by a gold seam" width="220">
</p>

# 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:** <https://huggingface.co/spaces/build-small-hackathon/Kintsugi-Garden>
- **3-minute demo video:** <https://huggingface.co/spaces/build-small-hackathon/Kintsugi-Garden/resolve/main/video/render/kintsugi-garden-demo.mp4>
  (also embedded in the app, under *About the Garden → Watch the 3-minute demo*)
- **Shared agent traces:** <https://huggingface.co/datasets/build-small-hackathon/Kintsugi-Garden-traces>
- **Write-up (LinkedIn):** <https://www.linkedin.com/pulse/small-model-challenge-ai-sherpa-035cc/>
- **Social post (X):** <https://x.com/aisherpa_org/status/2065672879212257770>
- **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.