Documentation

A Zi Wei Dou Shu chart engine, field-for-field identical to JS iztro, plus pattern judgement, knowledge packs and reverse birth-date lookup — with LLM-ready text output. A Rust core, callable from Rust, Python and Go.

Zi Wei Dou Shu — Chinese "Purple Star" astrology — charts a life from a birth date and hour. This library turns that birth moment into a complete chart, and into text a language model can read in one call — let the library get the chart right; let the AI do the reading.

One call produces the text below — the full basic info and the first palace, with the other eleven palaces following in the same shape. Paste it into any language model and start asking questions:

=== Basic Info ===
Gender: female
Solar Date: 2000-8-16
Lunar Date: 二〇〇〇年七月十七
Chinese Date: geng chen - jia shen - bing woo - geng yin
Time: Tiger hour (03:00~05:00)
Zodiac Sign: leo
Zodiac Animal: dragon
Soul Palace Branch: woo
Body Palace Branch: xu
Soul Star: rebel
Body Star: scholar
Five Elements Class: wood 3rd
Birth-Year Mutagen: sunA, generalB, moonC, fortunateD

=== Palaces ===

--- wealth ---
Stem-Branch: wuyin
Decadal: 43-52
Age Fortune Years: 9, 21, 33, 45, 57, 69, 81, 93, 105, 117
Twelve Gods: dissipated, gossip, sorrowing, varied
Major Stars: general([+1])[B], minister([+3])
Minor Stars: horse
Adjective Stars: considery, senior, ageless, psychic, gourmet, gloomy, upset

… (the other eleven palaces)

Reading the sample

Lunar Date is the only field that stays in Chinese in an English chart — the lunar date is rendered with Chinese numerals (二〇〇〇年七月十七 = the 17th day of the 7th lunar month, 2000). Chinese Date is the four pillars in iztro's own romanization — close to pinyin, but note 午 renders as woo to avoid clashing with 戊 wu. Bracket notation: ([+3]) is brightness on a -3…+3 scale, [A]/[B]/[C]/[D] are the four mutagens.

Whether a chart is correct has one hard standard here: zero field-level divergence from JS iztro v2.5.8, held by 716,314 golden test cases — see Accuracy. Defaults match iztro exactly; the Zhongzhou school and every boundary convention are switchable, because parity with iztro is an engineering standard, not a claim that any one school is the only correct one.

Where to start

x-iztro Guide

Installation, your first chart, Zi Wei concepts, configuration and data model. Applies to all three bindings.

Using it without writing code

What it can do, where it fits, and what to hand your engineers.

Rust API

The core library. Both the Python and Go bindings call into it.

Python API

A typed API built from dataclasses and StrEnums, with no external dependencies.

Go API

Embedded WebAssembly on a pure Go runtime, no cgo.

Semantic text (to_text)

How the text above is produced, its format, and how to wire it into a model.

Three things iztro doesn't have

These are the semantic layers above the raw chart — the part an AI pipeline actually consumes — and upstream iztro has no equivalent API for any of them:

Pattern judgement (64 rules)

One rule set shared by natal charts and horoscopes; every hit names its palace, variant and evidencing stars.

Knowledge packs

Reading texts and school attributes in swappable JSON, default pack included — doubles as RAG corpus.

Reverse lookup

From BaZi pillars or chart features back to candidate birth dates, each verified by re-charting.

Find your path

A practitioner, not a programmer → Using it without writing code
Backend / AI application engineer → Getting started, then the LLM guide
New to Zi Wei Dou Shu → the concepts, starting from stems, branches and the twelve palaces

Three programming languages, one result

All three bindings call the same Rust core, so charts come out identical field for field. The predicate methods are built on language-independent keys, so one analysis rule — written in Rust, Python or Go — yields the same answer on a chart rendered in any output language.

use x_iztro::*;

let chart = by_solar("2000-8-16", 2, Gender::Female, true, Language::EnUS, Config::default())?;
let soul = chart.palace(Palace::Soul).unwrap();

println!("{}", soul.has(&[StarKey::ZiweiMaj]));

All three report the same answer — the Soul palace of this chart holds Ziwei, the Emperor star (Python prints True; Rust and Go print true). All three use the language-independent key ziweiMaj: render the same chart in English or Japanese and the answer doesn't change.