# x-iztro Docs

- [Documentation](/en/docs): 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.
- x-iztro: A Zi Wei Dou Shu charting library: a Rust core with three language bindings
  - [Introduction](/en/docs/guide): Turn a birth date and hour into a complete Zi Wei Dou Shu chart, and into text a language model can read. A Rust core, callable from Rust, Python and Go, matching JS iztro field for field.

  - **Get started**
  - Getting started
    - [Overview](/en/docs/guide/getting-started): The inputs a chart needs, what each parameter accepts, and how to install for each of the three programming languages.
    - [Rust](/en/docs/guide/getting-started/rust): Install the x-iztro crate, produce your first chart, and see how enums and translation functions divide the work.
    - [Python](/en/docs/guide/getting-started/python): Install with pip, use the typed dataclass API, and write chart-language-independent checks with enums.
    - [Go](/en/docs/guide/getting-started/go): go get and go — embedded WebAssembly, no cgo, cross-compilation preserved.

  - **Zi Wei Dou Shu**
  - Zi Wei concepts
    - [What a chart is made of](/en/docs/guide/concepts): The minimum Zi Wei Dou Shu you need, readable without code — what a chart is, what parts it has, and what each part decides.
    - [Stems, branches and elements](/en/docs/guide/concepts/stems-branches): What heavenly stems, earthly branches, the five elements and yin/yang each decide, where palace stems come from, and how soul and body stars are looked up.
    - [The twelve palaces](/en/docs/guide/concepts/palaces): What each of the twelve palace names covers, how the Body palace and Original palace are decided, what palace stems are for, and how decadals and age fortune hang off palaces.
    - [Stars](/en/docs/guide/concepts/stars): What each of the three star groups holds, the eight star types, how to read brightness and mutagen marks, the four groups of twelve gods, and a star-name table.
    - [Mutagens and flying stars](/en/docs/guide/concepts/mutagen): Where the four mutagens come from, the full ten-stem mutagen table, and how self-mutagens and flying predicates work.
    - [Surrounded palaces](/en/docs/guide/concepts/surrounded): Why a palace is never read alone, which four palaces make up the surrounded set, and how to get them in each of the three programming languages.
    - [Horoscopes](/en/docs/guide/concepts/horoscope): What each of the six time scopes computes, why the palace name on a cell changes, how the childhood scope is derived, and where flowing stars and yearly twelve gods come from.
    - [Patterns](/en/docs/guide/concepts/patterns): What a pattern is, the principles x-iztro judges by, how the natal and horoscope views differ, and the complete table of all 64 patterns.
    - [How charting works](/en/docs/guide/concepts/how-it-works): Nine steps from birth data to a complete natal chart — what each step does and what it works from.

  - **Guides**
  - Guides
    - [Overview](/en/docs/guide/guides): Guides for AI readings, configuration and schools, cross-language predicates, multilingual output, error handling and extension.
    - [Using it without writing code](/en/docs/guide/guides/for-non-developers): What x-iztro does, where it is typically used, what to hand your engineers, and how accurate it is.
    - [Semantic text (to_text)](/en/docs/guide/guides/to-text): Project a chart, a horoscope or a palace into natural-language text — for a language model, or for a person to read.
    - [Letting an AI read the chart](/en/docs/guide/guides/llm): Charting to the library, reading to the model — how to wire x-iztro into an AI application, plus a few traps already hit.
    - [Knowledge packs](/en/docs/guide/guides/knowledge-pack): How reading texts and school-specific attributes are kept out of the core, what the bundled default pack contains, how to write an overlay, and how to read one from each language.
    - [Reverse lookup](/en/docs/guide/guides/reverse): Recover candidate birth dates from four BaZi pillars or from chart features - what each entry point means, how pillars follow the Config boundaries, the 60-year cycle, and truncation semantics.
    - [Config in depth](/en/docs/guide/guides/config): What each of the six switches changes, how to pass custom mutagen and brightness tables, and when you would actually notice a difference.
    - [The language-independent key contract](/en/docs/guide/guides/keys): Why star names must not drive predicates, what the key fields are, and how each of the three programming languages uses them.
    - [Multilingual output](/en/docs/guide/guides/i18n): Six chart languages, which fields get translated, what switching language does to the result, and two-way conversion between keys and names.
    - [Error handling](/en/docs/guide/guides/errors): What is validated, at which layer, what the four error categories mean, and why the core refuses to panic.
    - [Extending the astrolabe](/en/docs/guide/guides/plugins): Hanging your own analysis rules off a chart — the extension point in each of the three programming languages.
    - [The API behind the nine charting steps](/en/docs/guide/guides/step-api): Which public function corresponds to each of the nine charting steps, and which steps the configuration switches change.
    - [Documentation endpoints for AI](/en/docs/guide/guides/llms-txt): The llms.txt, llms-full.txt, per-page Markdown and Accept-header negotiation this site provides.

  - **Data model**
  - [Data model](/en/docs/guide/data-model): The type and meaning of every field on Astrolabe, Palace, Star and Horoscope.

  - **About**
  - About
    - [Overview](/en/docs/guide/about): Accuracy guarantees, documentation endpoints for AI, and notes on the port and the architecture.
    - [Accuracy](/en/docs/guide/about/accuracy): How 716,314 golden test cases hold x-iztro to zero divergence from JS iztro, and where that claim stops.
    - [Architecture](/en/docs/guide/about/architecture): The layering of the core and the three bindings, the trade-offs behind each, and the no-panic design constraint.
    - [Migrating from iztro: API mapping](/en/docs/guide/about/iztro-parity): Where each public iztro API lands in the three x-iztro bindings, the few that changed shape and why, and the ones not provided.
- Rust: Rust API reference
  - [Overview](/en/docs/rust): The crate layout, the type system, and how to read this reference.

  - **Charting**
  - [Charting entries](/en/docs/rust/astro): by_solar, by_lunar, rearranged and the JSON convenience variants.
  - [Astrolabe object](/en/docs/rust/astrolabe): The fields of Astrolabe, its lookup methods, and the surrounded-palace predicates.

  - **Object methods**
  - [Palace object](/en/docs/rust/palace): The fields of PalaceData plus every star predicate, empty-palace check and flying-star method.
  - [Star object](/en/docs/rust/star-object): The fields of Star, its brightness and mutagen predicates, and the back-references StarRef adds.
  - [Surrounded palaces](/en/docs/rust/surpalaces): The four palaces of SurroundedPalaces and its five predicates.
  - [Horoscope object](/en/docs/rust/horoscope): The data structures of the six scopes, plus palace lookups that need not be handed the astrolabe again.
  - [Patterns](/en/docs/rust/patterns): Pattern hits on natal and horoscope charts, the reading switches, pattern keys, and the serialisation DTO.

  - **Module functions**
  - [Lightweight queries](/en/docs/rust/query): The Chinese zodiac animal, zodiac sign and Soul palace major stars, without charting the whole thing.
  - [Utilities](/en/docs/rust/util): Index arithmetic, brightness and mutagen lookups, Soul and body palace derivation, and the four-pillar display string.
  - [Star placement](/en/docs/rust/star): Where a group of stars lands given birth data, plus the low-level building blocks of the charting pipeline.
  - [Data tables](/en/docs/rust/data): The enums and their methods, the charting configuration, star information, stem and branch information, and the ordering constants.
  - [Translation](/en/docs/rust/i18n): Two-way lookup between keys and translations, plus the per-category translation functions.
  - [Knowledge packs](/en/docs/rust/knowledge): KnowledgePack and its entry types, the bundled default pack, JSON parsing and serialization, overlay merging.
  - [Reverse lookup](/en/docs/rust/reverse): solar_dates_by_bazi and reverse_chart - the functions and types for recovering candidate birth dates from BaZi pillars or chart features.

  - **Advanced**
  - [Extending the astrolabe](/en/docs/rust/extend): Adding your own analysis methods to Astrolabe and PalaceRef with extension traits.
  - [Error handling](/en/docs/rust/errors): The four variants of IztroError, the code() classifier, BridgeError, and how to diagnose.
- Python: Python API reference
  - [Overview](/en/docs/python): The package layout, the type system, and how to read this reference.

  - **Charting**
  - [Charting entries](/en/docs/python/astro): The charting methods of the Astro class, re-anchoring, and the semantic text projection.
  - [Astrolabe object](/en/docs/python/astrolabe): The fields of Astrolabe, its lookup methods, and the surrounded-palace predicates.

  - **Object methods**
  - [Palace object](/en/docs/python/palace): The fields of Palace plus every star predicate, empty-palace check and flying-star method.
  - [Star object](/en/docs/python/star-object): The fields of Star, its brightness and mutagen predicates, and tracing back to its palace.
  - [Surrounded palaces](/en/docs/python/surpalaces): The four palaces of SurroundedPalaces and its five predicates.
  - [Horoscope object](/en/docs/python/horoscope): The data structures of the six scopes, plus palace lookups that need not be handed the astrolabe again.
  - [Patterns](/en/docs/python/patterns): Pattern hits on natal and horoscope charts, the PatternConfig readings, the PatternKey enum, and the predicate methods.

  - **Module functions**
  - [Lightweight queries](/en/docs/python/query): The Chinese zodiac animal, zodiac sign and Soul palace major stars, without charting the whole thing.
  - [Utilities](/en/docs/python/util): Index arithmetic, brightness and mutagen lookups, Soul and body palace derivation, decadal and age scopes, and the four-pillar display string.
  - [Star placement](/en/docs/python/star): Where a group of stars lands given birth data.
  - [Data tables](/en/docs/python/data): Star information, stem and branch information, ordering constants and all the enums.
  - [Translation](/en/docs/python/i18n): Two-way lookup between keys and translations.
  - [Knowledge packs](/en/docs/python/knowledge): KnowledgePack and its entry dataclasses, the bundled default pack, dict/JSON conversion, overlay merging.
  - [Reverse lookup](/en/docs/python/reverse): solar_dates_by_bazi and reverse_chart - the functions and dataclasses for recovering candidate birth dates from BaZi pillars or chart features.

  - **Advanced**
  - [Extending the astrolabe](/en/docs/python/extend): Attaching custom analysis methods to the Astrolabe class with plugins.
  - [Error handling](/en/docs/python/errors): The code classification of IztroError, what triggers it, the message format, and handling patterns.
- Go: Go API reference
  - [Overview](/en/docs/go): The package layout, the type system, and how to read this reference.

  - **Charting**
  - [Charting entries](/en/docs/go/astro): BySolar, ByLunar, Rearranged and the semantic text projection.
  - [Astrolabe object](/en/docs/go/astrolabe): The fields of Astrolabe, its lookup methods, and the surrounded-palace predicates.

  - **Object methods**
  - [Palace object](/en/docs/go/palace): The fields of Palace plus every star predicate, empty-palace check and flying-star method.
  - [Star object](/en/docs/go/star-object): The fields of Star, its brightness and mutagen predicates, and tracing back to its palace.
  - [Surrounded palaces](/en/docs/go/surpalaces): The four palaces of SurroundedPalaces and its five predicates.
  - [Horoscope object](/en/docs/go/horoscope): The data structures of the six scopes, plus palace lookups that need not be handed the astrolabe again.
  - [Patterns](/en/docs/go/patterns): Pattern hits on natal and horoscope charts, the PatternConfig readings, the Pattern constants, and error handling.

  - **Module functions**
  - [Lightweight queries](/en/docs/go/query): The Chinese zodiac animal, zodiac sign and Soul palace major stars, without charting the whole thing.
  - [Utilities](/en/docs/go/util): Index arithmetic, brightness and mutagen lookups, Soul and body palace derivation, decadal and age scopes, and the four-pillar display string.
  - [Star placement](/en/docs/go/star): Where a group of stars lands given birth data.
  - [Data tables](/en/docs/go/data): Star information, stem and branch information, ordering constants and all the key constants.
  - [Translation](/en/docs/go/i18n): Two-way lookup between keys and translations.
  - [Knowledge packs](/en/docs/go/knowledge): KnowledgePack and its entry structs, the bundled default pack, JSON parsing, overlay merging and error handling.
  - [Reverse lookup](/en/docs/go/reverse): SolarDatesByBazi and ReverseChart - the functions and types for recovering candidate birth dates from BaZi pillars or chart features.

  - **Advanced**
  - [Extending the astrolabe](/en/docs/go/extend): Adding custom analysis methods to a chart through struct embedding.
  - [Error handling](/en/docs/go/errors): The Code categories of *Error, the four sentinels, what triggers them, and handling patterns.

## Full text and other languages

- [English full text](/en/llms-full.txt)
- [中文索引 (Chinese index)](/zh/llms.txt)
- [中文全文 (Chinese full text)](/zh/llms-full.txt)