bazi-ziwei-engine

BaZi (Four Pillars) and Zi Wei Dou Shu in one engine — zero dependencies, a calendar computed from astronomy, and a reading that grades itself against your real life.

English | 简体中文

The card is generated from whatever events you enter — it is not a template. Run it on your own life and the numbers change, including the miss.

Why this one

Most open-source Chinese astrology projects do either BaZi or Zi Wei, and stop at drawing the chart. This one is built around five ideas the others skip:

1. No lookup tables for the calendar. Solar terms come from a truncated VSOP87 series with nutation, aberration and FK5 correction, solved by Newton iteration; new moons come from Meeus ch. 49. A 200-year table is a copy of somebody else's decisions — a computed ephemeris is an argument you can check.

2. Two systems, one reading. BaZi gives the element structure, Zi Wei gives the twelve palaces. They are scored separately and then combined, so a claim has to survive both.

3. Back-testing against your own life. Every other tool tells you what will happen. This one asks what did, compares its own past scores against your report, prints the hit rate and correlation, and refits the component weights if they disagree.

4. Grade and strength are separate numbers. A chart's rank is judged by the classical test — does the structure hold, what breaks it, what rescues it — not by averaging seven dimensions. A "following" structure can be physically weak and still upper-grade; a strong chart can be structurally low. Averaging the two is the most common mistake in this space.

5. Every term is explained in place. 126 terms (stems, ten gods, structures, all 45 stars, the twelve palaces, 64 hexagram vocabulary) carry a hover/click definition in both languages, annotated automatically across the whole page.

Related MCP server: Chinese Fortune Analysis System (BaZi)

Quick start

git clone https://github.com/WEIWEI0614/bazi-ziwei-engine.git
cd bazi-ziwei-engine

python -m mingli chart --date 1993-06-14 --time 17:31 --gender male --lon 116.65
python -m mingli year  2027 --date 1993-06-14 --time 17:31 --gender male
python -m mingli month 2027 --date 1993-06-14 --time 17:31 --gender male
python -m mingli md    --date 1993-06-14 --time 17:31 --gender male -o report.md
python -m mingli serve            # http://127.0.0.1:8788

No pip install, no virtualenv, no network. Python 3.9+ standard library only.

Browser version (same engine, ported 1:1):

cd docs && python3 -m http.server 8000     # http://127.0.0.1:8000

or just open the hosted demo: https://weiwei0614.github.io/bazi-ziwei-engine/

Use it as an agent skill, or over MCP

The engine is packaged twice so an assistant can call it directly instead of re-deriving the chart.

As an agent skill. SKILL.md at the repo root follows the Agent Skills convention, so cloning it into a skills directory is enough:

git clone https://github.com/WEIWEI0614/bazi-ziwei-engine.git ~/.claude/skills/bazi-ziwei

The skill instructs the model to run the back-test before interpreting, and to cite a stem, a god or a palace for every claim it makes.

As an MCP server. mcp_server.py speaks JSON-RPC over stdio, standard library only:

{"mcpServers": {"bazi-ziwei": {
  "command": "python",
  "args": ["/absolute/path/to/bazi-ziwei-engine/mcp_server.py"]}}}

The two systems are cross-validated rather than averaged: BaZi judges the structure, Zi Wei judges the palace, and the report says so when they disagree.

What it computes

Accuracy: what was actually verified

Nothing here is asserted from memory. Two independent libraries were used as oracles and every disagreement was chased down.

Two bugs found this way and worth recording, because both are common in other projects:

• Month length must be decided at day granularity, not at the instant. In 2025 the new moon falls at 14:06 on Aug 23 and 处暑 at 04:33 the same day. Comparing instants makes 处暑 belong to the previous month, which pushes the leap month one slot late. The standard (GB/T 33661-2017) compares civil days.

• 起紫微訣 is not "always step backwards". The mnemonic is: advance by the quotient, then move forward by the borrow if the borrow is even, backward if it is odd. Getting this wrong shifts half of all charts by four palaces and looks plausible.

Run them yourself:

python -m unittest discover -s tests -v      # 19 tests, zero dependencies
node tools/parity.js cases.json out.json     # optional JS/Python parity harness

Schools covered

A single "correct" answer does not exist in this field. Where schools disagree, the difference is exposed as an option and documented, never silently averaged.

The back-test, and why it matters

Every fortune-telling tool is unfalsifiable by construction. This one is not, at least locally:

cat > events.json <<'JSON'
[
  {"year": 2016, "kind": "study",  "impact":  2, "note": "left for grad school"},
  {"year": 2020, "kind": "career", "impact": -1},
  {"year": 2023, "kind": "career", "impact": -2, "note": "hardest year"},
  {"year": 2025, "kind": "career", "impact":  1}
]
JSON
python -m mingli chart --date 1993-06-14 --time 17:31 --gender male --events events.json

The engine re-scores those years blind, then reports:

• hit rate — did the sign of the score match the sign of your report,

• Pearson r — does the magnitude track too,

• refitted weights — ridge least squares on the four score components (用神 / 冲合 / 神煞 / 大运),

• disagreements — the specific years it got wrong, with the interaction it relied on.

If the hit rate is low the tool says so, and tells you the three things to check first (birth time, 立春 vs lunar-new-year year boundary, non-astrological variables). A model that can lose is worth more than one that cannot.

Architecture

mingli/
  calendar/astro.py     Julian day, ΔT, nutation, VSOP87 sun, solar terms, new moons, EoT
  calendar/lunar.py     sui-based lunisolar calendar, five pillars
  calendar/ganzhi.py    all classical lookup tables (hidden stems, nayin, shensha, ...)
  bazi/chart.py         chart + element weighting + structure + climate + interactions
  bazi/luck.py          ten-year cycles, annual and monthly scoring
  ziwei/chart.py        full star placement (verified against iztro)
  ziwei/analysis.py     trine-and-opposite, patterns, decades, annual palace
  reading.py            overall score, life areas, back-test + calibration
  cli.py                chart / year / month / md / json / serve
web/                    index.html + app.js + engine.js + data.js   (browser build)
docs/                   published copy of web/ for GitHub Pages
tools/gen_js_data.py    emits data.js from the Python tables  <- keeps both engines honest
tools/parity.js         JS/Python field-by-field comparison
tests/                  19 unit tests, no third-party dependencies

web/data.js is generated, never hand-written: every table (VSOP terms, hidden stems, nayin, 調候, brightness grades, sihua) is dumped from the Python modules by tools/gen_js_data.py. That is why the two engines cannot drift apart.

Limitations (read before trusting a number)

1. ΔT after ~2050 is a prediction; solar terms in the far future may move by tens of seconds.

2. If a new moon falls within seconds of local midnight the lunar day can be off by one (≈ once per 30 years; two such cases exist in 1900-2100).

3. The weighting scheme is heuristic. It is declared and testable, not derived — which is exactly why the back-test exists.

4. This is a structural model of tendencies, not a prediction of events. Nothing here is medical, financial or legal advice.

5. Zi Wei years use the lunar-year stem (正月初一), the classical convention; some software uses 立春 instead, which shifts charts born between the two dates.

Contributing

The most useful contributions are counter-examples: a chart where a classical rule gives a different structure, a school whose tables differ, a date where the calendar disagrees with an official almanac. Open an issue with the input, the expected output and the source. Please do not add stars or rules without a citation — the point of this project is that every claim traces back to a text or an algorithm.

License

MIT. Traditional texts referenced (《淵海子平》《窮通寶鑑》《紫微斗數全書》) are public domain.