README.md

---
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](https://huggingface.co/spaces/liuyd-dev/tianwen/resolve/main/video/Tianwen%20Demo%20Video%208min.mp4) ·
🔗 **Social post:** [r/huggingface](https://www.reddit.com/r/huggingface/comments/1u6x7ui/i_finetuned_minicpm51b_to_turn_chinese_astrology/) ·
🤗 **Model:** `build-small-hackathon/tianwen-minicpm5-1b` ·
🤗 **Dataset:** `build-small-hackathon/tianwen-distill`

<video controls src="https://huggingface.co/spaces/liuyd-dev/tianwen/resolve/main/video/Tianwen%20Demo%20Video%208min.mp4" title="Tianwen — 8-min demo"></video>

---

## 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](docs/FINETUNE_REPORT.md)** 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

```bash
# 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.