README.md

metadata

title: Tianwen
emoji: 🔮
colorFrom: indigo
colorTo: pink
sdk: gradio
sdk_version: 6.17.3
python_version: '3.12'
app_file: app.py
pinned: false
license: mit
tags:
  - track:wood
  - sponsor:openbmb
  - sponsor:modal
  - achievement:offgrid
  - achievement:welltuned
  - achievement:sharing
  - achievement:fieldnotes
  - badge:tiny
  - minicpm
  - llama-cpp
  - on-device

天问 · Tianwen

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. 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: 简体 / 繁體 / English. Themes: Ru-kiln White / Xuanwu Black. Installable PWA.

The idea & the tech (write-up)

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

We didn't prompt our way to the voice — we taught it. See the Fine-Tuning Field Notes for the full distillation → LoRA → GGUF → deployment story (and every bug we hit).

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.

Tracks & badges we're going for

• Track — 🌲 Thousand Token Wood: an esoteric professional domain made playful and self-reflective with a tiny model.
• 🏅 Off the Grid — fully local, zero external network requests, installable offline PWA.
• 🏅 Well-Tuned — custom distilled dataset + LoRA fine-tune of MiniCPM5-1B, healthy loss curve.
• 🏅 Sharing is Caring — open dataset, open training/distillation scripts, and a textbook-grade build log.
• 🏅 Field Notes — a detailed, honest construction log with the full bug chain.
• 🏆 OpenBMB — built on MiniCPM5-1B.
• 🏆 Modal — distillation/training pipeline ran on Modal A100.
• 🏆 Tiny Titan — a 1B model doing what you'd expect a 4B+ to do.

How it meets the requirements

#	Requirement	How Tianwen meets it
REQ-01	Under 32B	MiniCPM5-1B (and the rules fallback uses no model at all).
REQ-02	Gradio app on the org	Deployed as a Gradio Space (app_file: app.py) under build-small-hackathon.
REQ-03	Demo video	Linked at the top of this README.
REQ-04	Social post	Linked at the top of this README.
REQ-05	≤10 ZeroGPU apps	One app Space + one ZeroGPU model Space.
REQ-06	Tagged README	Track + badge tags in the frontmatter; write-up above.

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 (Off the Grid).

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)

License

MIT. Charts via lunar-python (MIT); cities via GeoNames (CC BY 4.0). For reflection and entertainment only — not a substitute for professional medical, psychological, or financial advice.