iztro 0.9.0

Strongly typed Zi Wei Dou Shu chart generation aligned with iztro.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152

# iztro-rs

[![Crates.io Version](https://img.shields.io/crates/v/iztro)](https://crates.io/crates/iztro)
[![Crates.io Downloads](https://img.shields.io/crates/d/iztro)](https://crates.io/crates/iztro)
[![docs.rs](https://docs.rs/iztro/badge.svg)](https://docs.rs/iztro)
[![CI](https://github.com/JinyangWang27/iztro-rs/actions/workflows/ci.yml/badge.svg)](https://github.com/JinyangWang27/iztro-rs/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/JinyangWang27/iztro-rs/branch/main/graph/badge.svg)](https://codecov.io/gh/JinyangWang27/iztro-rs)
[![License](https://img.shields.io/crates/l/iztro)](https://crates.io/crates/iztro)

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

> Status: early design and scaffolding. The project is not yet a complete charting or interpretation engine.

中文说明见 [README.zh-CN.md](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.

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

```rust
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:

```bash
cargo run -p iztro --example plain_text
```

Abbreviated real output excerpt:

```text
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](docs/en/demo.md) and the
[full captured output](docs/examples/plain_text_1990_05_17_chen_female.txt).

## 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 four layers:

1. **Core Chart Layer** — deterministic chart facts and domain models.
2. **Feature Extraction Layer** — structured semantic features derived from a chart.
3. **Rule Engine Layer** — rules map features into structured claims with evidence.
4. **Narrative Layer** — claims are rendered into human-readable reports.

See [docs/en/architecture.md](docs/en/architecture.md) for details.

## Compatibility with iztro

This project is inspired by [`iztro`](https://github.com/SylarLong/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](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](docs/en/project-spec.md)
- [Architecture](docs/en/architecture.md)
- [Core chart generation architecture](docs/architecture/core-chart-generation.md)
- [Roadmap](docs/en/roadmap.md)
- [Compatibility](docs/en/compatibility.md)
- [Terminology](docs/en/terminology.md)
- [Rule engine](docs/en/rule-engine.md)
- [Multilingual documentation](docs/en/i18n.md)

## Acknowledgements

This project is inspired by [`iztro`](https://github.com/SylarLong/iztro), licensed under the MIT License. The early compatibility target of `iztro-rs` is to reproduce compatible chart-generation behavior where applicable.

## License

MIT.