x-iztro

中文文档：README.zh-CN.md

Give it a birth date and hour; get back a complete Zi Wei Dou Shu (紫微斗数, Purple Star Astrology) chart — twelve palaces, every star with its brightness and transformation, decadal and annual horoscopes — as typed objects in Rust, Python, or Go, plus a single call that renders the whole chart as text you can hand straight to an LLM.

What the LLM-ready output looks like

from x_iztro import Astro

astro = Astro()
chart = astro.by_solar("2000-8-16", 2, "female")
print(astro.astrolabe_to_prompt(chart))

=== 基本信息 ===
性别: 女
阳历: 2000-8-16
农历: 二〇〇〇年七月十七
干支: 庚辰 甲申 丙午 庚寅
时辰: 寅时 (03:00~05:00)
星座: 狮子座
生肖: 龙
命宫地支: 午
身宫地支: 戌
命主: 破军
身主: 文昌
五行局: 木三局
生年四化: 太阳禄, 武曲权, 太阴科, 天同忌

=== 十二宫 ===

--- 财帛 ---
天干地支: 戊寅
大限: 43-52
小限虚岁: 9, 21, 33, 45, 57, 69, 81, 93, 105, 117
十二神: 绝, 飞廉, 吊客, 岁驿
主星: 武曲(得)[权], 天相(庙)
辅星: 天马
杂耀: 解神, 三台, 天寿, 天巫, 天厨, 阴煞, 天哭

--- 夫妻 [来因] ---
天干地支: 庚辰
大限: 23-32
小限虚岁: 7, 19, 31, 43, 55, 67, 79, 91, 103, 115
十二神: 死, 将军, 岁建, 华盖
主星: 七杀(庙)
辅星: 右弼, 火星(陷)
杂耀: 封诰, 华盖

... (all twelve palaces)

The same text is available in six languages — pass language="en-US" and the stars, palaces and brightness levels come out as general([+1])[B], wealth, Tiger hour, Twelve Gods: dissipated, gossip, … and so on. horoscope_to_prompt does the same for a horoscope at a given date.

Why not just ask the LLM to cast the chart?

Casting a chart is arithmetic, not interpretation: lunar/solar conversion, leap month handling, sexagenary cycle, the placement rules for ~100 stars, and the 四化 transformation table. A language model gets some of it right and quietly gets the rest wrong, and you cannot tell which from the output. This library does the arithmetic deterministically and verifiably, then hands the LLM the part it is actually good at — reading the chart.

Install

Rust

[dependencies]
x-iztro = "0.2"

Python — requires 3.10+, ships as an abi3 wheel with zero runtime dependencies.

pip install x-iztro

Go — the core library is embedded as WebAssembly and driven by the pure-Go wazero runtime: no cgo, no Rust toolchain, cross-compilation works as usual.

go get github.com/x-haose/x-iztro/go/iztro

Quick start

Rust

use x_iztro::{by_solar, IztroError};
use x_iztro::data::types::*;

fn main() -> Result<(), IztroError> {
    let chart = by_solar(
        "2000-8-16",        // solar birth date
        2,                  // hour index: 0 = early Rat hour … 12 = late Rat hour
        Gender::Female,
        true,               // fix_leap: split leap months at the midpoint
        Language::ZhCN,
        Config::default(),  // boundaries and school; defaults match JS iztro
    )?;

    // Translated strings; `soul` and `five_elements_class` are language-independent
    // keys (`StarKey::PojunMaj`, `FiveElementsClass::Wood3rd`).
    println!("{} / {}", chart.lunar_date, chart.chinese_date);
    println!("{:?} {:?}", chart.soul, chart.five_elements_class);

    // `horoscope` derefs to the data, so the six levels are plain fields.
    let horoscope = chart.horoscope("2024-1-1", 0)?;
    println!("{:?}", horoscope.yearly.base.mutagen);

    // Bad input is an error, never a panic.
    assert!(by_solar("2000-13-1", 2, Gender::Male, true, Language::ZhCN, Config::default()).is_err());
    Ok(())
}

Python

from x_iztro import Astro, IztroError
from x_iztro.enums import MajorStar, Mutagen, PalaceName

chart = Astro().by_solar("2000-8-16", 2, "female")
print(chart.chinese_date, chart.soul, chart.five_elements_class)

# Enums are language-independent keys, so these checks give the same answer
# no matter which language the chart was rendered in.
soul = chart.palace(PalaceName.SOUL)
print(soul.has([MajorStar.ZIWEI]), soul.has_mutagen(Mutagen.LU))

horoscope = chart.horoscope("2024-1-1", 0)
print(horoscope.yearly.heavenly_stem, horoscope.yearly.earthly_branch)

# IztroError subclasses ValueError; .code is a machine-readable category.
try:
    Astro().by_solar("2000-13-1", 2, "male")
except IztroError as e:
    print(e.code)  # invalid_date

Go

package main

import (
    "errors"
    "fmt"
    "log"

    "github.com/x-haose/x-iztro/go/iztro"
)

func main() {
    chart, err := iztro.BySolar("2000-8-16", 2, iztro.GenderFemale, true, iztro.LanguageZhCN, nil)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(chart.ChineseDate, chart.Soul, chart.FiveElementsClass)

    soul := chart.Palace(iztro.PalaceSoul)
    fmt.Println(soul.Has(iztro.StarZiweiMaj), soul.HasMutagen(iztro.MutagenLu))

    horoscope, err := chart.Horoscope("2024-1-1", 0)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(horoscope.Yearly.HeavenlyStem, horoscope.Yearly.EarthlyBranch)

    // Errors carry a category you can match with errors.Is.
    _, err = iztro.BySolar("2000-13-1", 2, iztro.GenderMale, true, iztro.LanguageZhCN, nil)
    fmt.Println(errors.Is(err, iztro.ErrInvalidDate)) // true
}

Features

• Full chart — twelve palaces, body palace, soul/body stars, five elements class, major/minor/adjective stars with brightness and 四化 transformations.
• Six horoscope levels — decadal, yearly, monthly, daily, hourly and the childhood limit, each with its own palaces and transformations.
• Chart queries — locate a palace by name, branch or index; test stars, transformations and empty palaces; the 三方四正 surrounded-palace group; and the flying-star (飞星) family.
• Two schools — the default school and 中州派 (Zhongzhou), selected per chart.
• Six languages — zh-CN, zh-TW, en-US, ja-JP, ko-KR, vi-VN, with language-independent key constants so your logic never depends on the display language.
• LLM output — astrolabe_to_prompt / horoscope_to_prompt render a whole chart as structured text.
• Validated input — date format and existence, solar years 1583–9999, hour index 0–12. Invalid input returns Err(IztroError) in Rust, raises x_iztro.IztroError (a ValueError) in Python, returns an error matchable with errors.Is in Go, and yields {"error":"..."} JSON over the C FFI. Every failure carries a machine-readable category. Nothing panics.

Accuracy

Every number is checked field-by-field against the JavaScript iztro v2.5.8 (version-pinned), with zero tolerance for differences. Roughly 710,000 golden cases in eight layers:

On top of that: the serialization contract is compared key-by-key against JS JSON.stringify, and the three bindings are cross-checked so that the same birth data yields the same answers in Rust, Python and Go.

cargo test                                               # regular layers, ~15s
cargo test --release --test golden_tier3 -- --ignored    # Tier 3 in full, ~20s

Configuration

Six switches, passed explicitly per chart — there is no global state.

Custom 四化 and brightness tables can be supplied alongside them.

Documentation

https://ziwei.x-hoase.com — the documentation site, in Chinese and English: a guide that starts from zero, the Zi Wei concepts behind the data model, and per-language API references where every function, type and method has its own entry with real output and edge-case notes. LLM-friendly endpoints: /llms.txt, /llms-full.txt, and any page with .md appended.

The site lives in docs/ (cd docs && npm ci && npm run dev to run it locally). Rust API docs are also published at docs.rs/x-iztro. Runnable projects for all three languages are under examples/.

Building from source

Only needed when changing the Rust core.

cargo build --release

# Python bindings
PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1 maturin develop --features python

# Go bindings: rebuild and refresh the embedded wasm
cargo build --release --target wasm32-wasip1
cp target/wasm32-wasip1/release/x_iztro.wasm go/iztro/

Golden test data is generated from the JS iztro package:

cd tests/golden && npm install && node generate_tier1.mjs   # …and the other generators

Credits

Ported from iztro by SylarLong. New to Zi Wei Dou Shu? Its author maintains an introduction at iztro.com.

License

MIT