Why this matters
Traditional astrological systems are often locked behind proprietary tools or inconsistent implementations. This project exposes a deterministic, auditable Zi Wei Dou Shu charting engine and an accompanying interpretation dataset so researchers, developers and practitioners can reproduce charts, audit rules, and use the structured readings as training or retrieval data.
What Sets It Apart
- Deterministic engine and rulebase: a TypeScript implementation that computes natal charts, true-solar-time correction, China DST handling, configurable leap-month rules, seven-level star brightness, and 1,100+ pattern rules (e.g., 紫府同宫, 日月并明). The engine yields the same output for the same input—no AI generation in the core pipeline.
- Large, licensed datasets for downstream use: a 518,400-sample v3 release and an expanded v4.0 interpretation dataset (674,976 charts × 13 topics = 8,774,688 readings; ~56.6 GB uncompressed, 161 MB compressed) generated deterministically from the engine and judgment library. Data released under CC BY 4.0 (attribution required); quoted lecture excerpts use a separate non-commercial license.
- Engineering practicalities: demo Next.js frontend, CI with regression tests, JSONL per-year releases (zstd long-window compression), and clear open-vs-closed boundaries—code and datasets are open, the online judgment/断语 library and AI API prompts/backends are not.
Who it’s for and tradeoffs
Great fit if you need a reproducible charting engine, a large labeled interpretation corpus for RAG or model fine-tuning, or a reference implementation of Zi Wei rules in TypeScript. Look elsewhere if you expect an out-of-the-box AI interpretation API—the repository intentionally omits the production judgment database and AI backend; the dataset contains the generated readings but the judgment/断语 source and online commercial front-end remain closed.
Where it fits
Use this repo as the deterministic core of an astrology product, a source of training/augmentation material for ML retrieval or fine-tuning, or as a research-grade implementation for auditing and cross-checking other tools. The project emphasizes transparent algorithms and dataset licensing rather than providing hosted AI services.
