Tianwen (天问) is an entirely on-device Eastern self-reflection app — a 1B model that translates 3,000 years of Chinese metaphysical language into one small, doable step for today. Built for the Build Small Hackathon, it is named after Qu Yuan's ancient poem Tianwen ("Questions to Heaven") — a reminder that the most worthwhile questions are the ones we ask ourselves.
- Demo video: 8-min walkthrough
- Social post: r/huggingface
- Model:
build-small-hackathon/tianwen-minicpm5-1b - Dataset:
build-small-hackathon/tianwen-distill
What it is
Tianwen takes a deeply esoteric domain — Chinese BaZi (八字) astrology and I-Ching (六爻) divination — and turns it into a gentle, gamified instrument for self-reflection. It never tells fortunes; it reframes ancient symbols as everyday psychological language and always ends with one concrete action.
Four readings, from the widest lens to the closest moment:
- 命盘 Chart — your whole-life portrait (BaZi four pillars)
- 年运 Year — this year's tone, plus twelve months one at a time
- 日盘 Today — today's energy + a daily sigil wallpaper + a 30-day mood trend
- 请事 Oracle — toss three coins six times for an I-Ching reading on a question you hold
Languages: Simplified Chinese / Traditional Chinese / English. Themes: Ru-kiln White / Xuanwu Black. Installable PWA.
The idea and the tech
The hackathon's thesis is "the future of AI doesn't have to live in someone else's data center." Tianwen is a full app where everything that matters runs on your own machine:
| Layer | How |
|---|---|
| Charting | Deterministic — lunar-python computes BaZi / liunian / liuyue / hexagrams locally. No model guesses dates. |
| Interpretation | A fine-tuned MiniCPM5-1B (1B params) served via llama.cpp, OpenAI-compatible. Distilled from a teacher model into the project's house voice (plain, second-person, anti-doom). |
| Safety | A deterministic guardrail (safety/intercept) — crisis words trip an instant circuit-breaker to hotlines; ominous symbols are re-mapped to growth language. Never left to a 1B model's probabilities. |
| Fallback | If the LLM is unreachable, a rules engine still produces a full reading — so it works offline. |
The voice wasn't prompted into existence — it was taught. The Fine-Tuning Field Notes (docs/FINETUNE_REPORT.md) cover the full distillation → LoRA → GGUF → deployment story, and every bug along the way.
Stack: MiniCPM5-1B · LLaMA-Factory (LoRA, bf16) · Modal (A100 training) · llama.cpp (GGUF Q4_K_M) · HF ZeroGPU (inference) · FastAPI + Gradio (backend) · React + shadcn/ui + Tailwind (frontend) · lunar-python.
Highlights
- Fully local: zero external network requests, installable offline PWA.
- Fine-tuned: a custom distilled dataset plus a LoRA fine-tune of MiniCPM5-1B, with a healthy loss curve.
- Open: open dataset, open training/distillation scripts, and a textbook-grade build log.
- Tiny but capable: a 1B model doing what you'd expect a 4B+ model to do; the distillation/training pipeline ran on Modal A100.
Run locally
# 1) Build the React frontend (the backend serves this build)
cd frontend && pnpm install && pnpm build && cd ..
# 2) Start the backend
python app.py # → http://127.0.0.1:7860/
# 3) (optional) Serve the fine-tuned model for real LLM readings
llama-server -m finetune/data/tianwen-minicpm1b-q4_k_m.gguf --port 8888 -c 4096
Without a running LLM, Tianwen still works via the deterministic rules engine.
Repo map
app.py FastAPI + Gradio backend (serves frontend/dist, SSE streaming readings)
bazi/ divination/ Deterministic charting & I-Ching engines (lunar-python)
prompts/ System prompts, templates, OpenAI-compatible LLM client
safety/ Crisis circuit-breaker + symbol re-mapping
finetune/ Distillation (gen_distill.py) + Modal training (train_modal.py) + deploy
frontend/ React + shadcn UI (build → frontend/dist)
docs/FINETUNE_REPORT.md The build log (Field Notes)
Notes
Charts via lunar-python; cities via GeoNames (CC BY 4.0). For reflection and entertainment only — not a substitute for professional medical, psychological, or financial advice.
Links
- Hugging Face Space: build-small-hackathon/Tianwen
- Demo video: 8-min walkthrough