Spaces:

build-small-hackathon
/

Kintsugi-Garden

Paused

App Files Files Community

Kintsugi-Garden / README.md

ai-sherpa

docs(readme): add Modal training-compute sub-bullet linking the training script

93f105f verified about 1 month ago

preview code

Raw

History Blame Contribute Delete

9.57 kB

A newer version of the Gradio SDK is available: 6.20.0

Upgrade

metadata

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

A symbolic mirror for dreams, journals, and inner transitions.

This is not therapy, diagnosis, prediction, or advice. It is a symbolic reflection tool.

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

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.
Mundane-language suppression — so ordinary words ("dead tired", "killing time") don't trip the gate.
Prompt-level voice rules — the model is constrained to possibilities ("may suggest", "one possible reading is"), never diagnoses, predictions, or instructions.
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

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 for what we believe this tool is for.