iztro-rs

A Rust implementation for Zi Wei Dou Shu (紫微斗数) chart generation, feature extraction, and eventually rule-based interpretation.

Status: pre-1.0. Chart generation is implemented and fixture-backed against iztro@2.5.8, with a renderer-neutral snapshot, a desktop GUI prototype, and runtime i18n. Feature extraction, the classical rule engine, and narrative interpretation are partial and still evolving. APIs may change before 1.0.

中文说明见 README.zh-CN.md.

Installation

The public API ships as a single crate:

cargo add iztro

The crate keeps clear internal domain boundaries as modules — core, features, rules, reading, and render — while the stable user-facing core API is also re-exported from the crate root.

Desktop GUI downloads and install

GitHub Releases can provide downloadable builds of the current iztro-gui desktop prototype. This is a GUI artifact for local chart exploration, not a claim that the application surface is production-stable.

GUI release artifacts are published only for tags named iztro-v*, for example iztro-v0.9.0. Merging PRs does not create a GitHub Release, and generic crate or library tags such as v0.9.0 do not publish GUI artifacts.

For normal use, download the archive matching your platform from the latest iztro-v* GUI GitHub Release:

• iztro-gui-x86_64-pc-windows-msvc.zip
• iztro-gui-aarch64-apple-darwin.tar.gz
• iztro-gui-x86_64-apple-darwin.tar.gz
• iztro-gui-x86_64-unknown-linux-gnu.tar.gz

Each archive includes the iztro-gui binary, README.md, license files, and a SHA-256 checksum file next to the archive. These early artifacts contain raw GUI executables rather than native installers.

Terminal users can install the Unix/macOS build with the small installer script:

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/JinyangWang27/iztro-rs/releases/latest/download/iztro-gui-installer.sh | sh

The one-line command executes the downloaded installer directly. For an auditable install, download the installer and its .sha256 file first, verify the checksum, then run the script:

curl --proto '=https' --tlsv1.2 -LsSfO https://github.com/JinyangWang27/iztro-rs/releases/latest/download/iztro-gui-installer.sh
curl --proto '=https' --tlsv1.2 -LsSfO https://github.com/JinyangWang27/iztro-rs/releases/latest/download/iztro-gui-installer.sh.sha256
if command -v sha256sum >/dev/null 2>&1; then
  sha256sum -c iztro-gui-installer.sh.sha256
else
  shasum -a 256 -c iztro-gui-installer.sh.sha256
fi
sh iztro-gui-installer.sh

The Unix installer uses ${XDG_BIN_HOME:-$HOME/.local/bin}.

Windows users can install with the PowerShell installer script. Run this in a PowerShell terminal (Windows x64 only):

irm https://github.com/JinyangWang27/iztro-rs/releases/latest/download/iztro-gui-installer.ps1 | iex

The one-line command executes the downloaded installer directly. For an auditable install, download the installer and its .sha256 file first, verify the checksum, then execute the script:

Invoke-WebRequest -Uri https://github.com/JinyangWang27/iztro-rs/releases/latest/download/iztro-gui-installer.ps1     -OutFile iztro-gui-installer.ps1     -UseBasicParsing
Invoke-WebRequest -Uri https://github.com/JinyangWang27/iztro-rs/releases/latest/download/iztro-gui-installer.ps1.sha256 -OutFile iztro-gui-installer.ps1.sha256 -UseBasicParsing
$expected = ((Get-Content iztro-gui-installer.ps1.sha256 -Raw).Trim() -split '\s+')[0].ToLowerInvariant()
$actual   = (Get-FileHash -Algorithm SHA256 iztro-gui-installer.ps1).Hash.ToLowerInvariant()
if ($expected -ne $actual) { Write-Error "Checksum mismatch"; exit 1 }
.\iztro-gui-installer.ps1

The Windows installer installs to %LOCALAPPDATA%\Programs\iztro-gui\.

Command-line/JSON export, package manager distribution, MCP, bindings, signed native installers, .dmg, .msi, and AppImage packages are future work and are not included in this release-artifact step.

Quick demo

The current supported natal chart fact surface can flow from a typed solar input through by_solar into a renderer-neutral stack snapshot, then into the iztro::render plain text demo. The excerpt below is from fixture-backed supported fields.

use iztro::render::render_chart_stack_text;
use iztro::{
    ChartAlgorithmKind, EarthlyBranch, Gender, MethodProfile, SolarChartRequest, SolarDay,
    SolarMonth, by_solar,
};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let request = SolarChartRequest::builder()
        .solar_year(1990)
        .solar_month(SolarMonth::new(5)?)
        .solar_day(SolarDay::new(17)?)
        .birth_time(EarthlyBranch::Chen)
        .gender(Gender::Female)
        .method_profile(MethodProfile::new(
            "readme_demo",
            ChartAlgorithmKind::QuanShu,
            "README plain text demo",
        ))
        .build()?;

    let chart = by_solar(request)?;
    let snapshot = chart.stack_snapshot();

    println!("{}", render_chart_stack_text(&snapshot));
    Ok(())
}

Run the example with:

cargo run -p iztro --example plain_text

Abbreviated real output excerpt:

Chart Stack
birth: Lunar 1990-4-23, time Chen, gender Female
method: readme_demo / QuanShu
life_palace_branch: Chou
body_palace_branch: You
five_element_bureau: Fire6

Layer 0: Natal
[Si] Career / Xin
roles: NatalPalace(Career)
typed: TianLiang, HuoXing, SanTai, TianGui, PoSui
decorative: Jue, XiaoHaoBoshi, BingFuSuiqian, WangShen
...
[Chou] Life / Ji
roles: NatalPalace(Life)
typed: TaiYang, TaiYin, TianKui
decorative: MuYu, XiShenBoshi, LongDeSuiqian, TianSha
...

See the demo page and the full captured output.

Goals

iztro-rs aims to provide:

• a strongly typed Rust core for Zi Wei Dou Shu chart data;
• chart-generation compatibility with iztro where applicable;
• a feature extraction layer for palaces, stars, mutagens, relations, patterns, and temporal activations;
• a rule engine that emits structured claims rather than prose;
• deterministic report generation with optional future LLM-assisted narrative rendering;
• future bindings for CLI, Python, and WebAssembly use cases.

Non-goals for early versions

Early versions will not attempt to be:

• a fortune-telling SaaS product;
• an LLM-first interpretation system;
• a complete multi-school Zi Wei Dou Shu interpretation engine;
• a drop-in clone of every public iztro API;
• a replacement for human judgement in classical or modern metaphysical interpretation.

Initial architecture

The project is designed around layered boundaries:

1. Core Chart Layer — deterministic chart facts and domain models.
2. Snapshot / Read Model Layer — renderer-neutral chart and GUI/API read models.
3. Runtime Localization Layer — presentation-boundary i18n for labels and UI text.
4. Render / Application Layer — text, GUI, future TUI/MCP/3D consumers.
5. Feature / Rule / Narrative Layers — interpretation-facing layers that consume structured facts rather than parsing rendered text.

See docs/en/architecture.md for the layer model and ADR 0009 for the domain model first principles.

Compatibility with iztro

This project is inspired by iztro, a lightweight Zi Wei Dou Shu astrolabe generation library. Early chart-generation behavior should be validated against iztro where applicable, while internal Rust APIs may diverge to favor stronger typing and long-term extensibility.

See docs/en/compatibility.md.

Documentation

English documentation is canonical for engineering specifications. Chinese documentation is maintained as a first-class translation and is canonical for Zi Wei Dou Shu terminology.

• Project specification
• Architecture
• Domain model first principles
• Core chart generation architecture
• Roadmap
• Compatibility
• Terminology
• Rule engine overview
• Classical rule engine
• Multilingual documentation

Acknowledgements

This project is inspired by iztro, licensed under the MIT License. The early compatibility target of iztro-rs is to reproduce compatible chart-generation behavior where applicable.

License

MIT.