life-chart-engine 1.1.0

Deterministic offline engine computing Western natal, Human Design, and Zi Wei Dou Shu (紫微斗數) charts from one birth record — CLI + JSON for humans and AI agents.

🌐 English · 繁體中文 · 简体中文 · 日本語 · 한국어 · Español · Français · Deutsch · Português · Русский · العربية · हिन्दी · Bahasa Indonesia · Tiếng Việt · ไทย · Italiano · Türkçe · Nederlands · Polski

life-chart-engine

Deterministic native computation of three life-chart systems — Western natal astrology, 人類圖 (Human Design), and 紫微斗數 (Zi Wei Dou Shu) — from a single birth record.

life-chart-engine is a small, offline command-line tool. You give it one person's birth data — date, time, timezone, and place coordinates — and it computes three independent chart systems in one pass, then emits either a human-readable Markdown report or a structured JSON object for programs and AI agents to consume.

It is built for people who want reproducible, verifiable chart calculations rather than a black-box web app: practitioners, developers building self-awareness tools, and AI agents that need a pure compute step. Every number comes from real astronomical computation and a real 紫微斗數 library (iztro) — not from a remote service, not from cached lookups, and never over the network.

---

What it computes

The engine runs three systems against the same birth moment, so their outputs can corroborate one another. Each system answers a different kind of question:

System	What it is (plain English)	What the engine yields
Western natal (Tropical / Placidus)	Classical Western astrology — where the planets sat against the zodiac at your birth, divided into 12 houses.	Ascendant + Midheaven, 12 planets/points (太陽 → 南交點) with sign, degree, house and retrograde flag, all 12 house cusps, and every detected aspect (合相/六分/四分/三分/對分) sorted by tightness.
人類圖 Human Design	A modern synthesis of astrology, the I-Ching, and the chakra system. Describes how your energy is "wired" via gates, channels, and centers.	Type, Authority, Profile, Definition, Incarnation Cross, the 88°-earlier Design date, defined/open centers, defined channels, and per-planet gate.line activations for both the Personality and Design charts.
紫微斗數 Zi Wei Dou Shu	A traditional Chinese astrology system that maps fate onto a 12-palace board, populated by named stars.	五行局 (Five Elements Class), 命主 (soul) / 身主 (body), the 時辰 hour index, and per-palace data — ganzhi, 命/身 flags, decadal age range, and major/minor/adjective stars (with brightness and 四化). Plus a 大限/流年/小限 horoscope — its 四化 are a bare star-name array (mutagen) plus an additive typed {star, type} view (mutagenTyped), and the 大限 carries an age range.

Type, Authority, and Definition in Human Design are not hardcoded — they are derived from the connectivity graph of the defined centers.

---

Why native calculation

This engine does the real math instead of approximating or calling out to a service. That choice buys three properties that matter for any serious chart tool:

• Deterministic. The same birth input always produces the same output, byte-for-byte. There is no randomness, no model, no rounding drift between runs.
• Reproducible. Anyone with the repo and the same inputs can regenerate your exact chart. Calculations use astronomy-engine for the sky and iztro for 紫微斗數 — both deterministic.
• Cross-verifiable. Because three independent systems are computed from one birth moment, you can triangulate. When all three systems point at the same signal, treat it as high confidence. When only one system shows a detail, treat it as a reference point, not a conclusion. This is the engine's core design principle — it produces facts to cross-read, not a single verdict.

---

Quick start

One-line install (recommended)

curl -fsSL https://raw.githubusercontent.com/zhenheco/life-chart-engine/main/install.sh | bash

Installs into ~/.life-chart-engine (override with LIFE_CHART_DIR). No sudo, no system-wide changes — it only clones the repo, builds an isolated CPython 3.12 venv, and uses the checked-in iztro Node bundle. Requires git, uv, and Node.js ≥ 18 (supported/tested on 18 and 24 — 紫微斗數 runs via a Node sidecar; without it every chart request fails loudly rather than silently dropping the third system). Re-run any time to update to the latest version.

Try without cloning (PyPI)

uvx life-chart-engine --example --json

Available from v1.1.0 on PyPI. If the package isn't published yet, use the installer above. uv provisions CPython 3.12 automatically; Node.js ≥ 18 still required. pip install life-chart-engine also works but needs CPython 3.12 specifically.

From source

git clone https://github.com/zhenheco/life-chart-engine.git
cd life-chart-engine
bash setup.sh

Development note: pip install -e . is not supported (the build maps scripts/ → the life_chart_engine package, which hatchling's dev mode can't rewrite). Use the setup.sh venv for development.

What setup.sh does

It runs under set -euo pipefail and performs five steps:

1. Resolves the venv location — ${LIFE_VENV:-<repo>/.venv}. Set the LIFE_VENV env var to override; the default .venv/ is git-ignored.
2. Preflight: requires uv — if uv is not on PATH it exits 1 and prints the install hint:

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

3. Creates a CPython 3.12 venv — uv venv --python 3.12 "$VENV" (see Why CPython 3.12).
4. Installs pinned dependencies — uv pip install --python "$VENV/bin/python" -r requirements.txt.
5. Checks the Zi Wei Node sidecar bundle — verifies Node.js is available and vendor/iztro.cjs exists.
6. Runs a smoke test — executes the engine once with fixed sample inputs (discarding stdout) and prints OK — engine runs. on success. It also prints usage hints for both modes.

Manual uv steps (no setup.sh)

# 1. Create CPython 3.12 venv (default <repo>/.venv; override with LIFE_VENV)
uv venv --python 3.12 .venv

# 2. Install pinned deps
uv pip install --python .venv/bin/python -r requirements.txt

# 3. (Optional) smoke test
.venv/bin/python scripts/chart_engine.py --json \
  --name "Setup Test" --gender 女 --date 1990-06-15 --time 08:30 \
  --tz 8 --lat 25.0 --lon 121.5 --target 2025-01-01 >/dev/null

Python direct dependencies are pinned in requirements.txt:

astronomy-engine>=2.1.19
fastapi==0.128.8
uvicorn==0.39.0
httpx==0.28.1

Zi Wei uses the checked-in vendor/iztro.cjs bundle. Maintainers regenerate it with scripts/build-iztro-bundle.sh, which uses npm ci from the committed vendor/package-lock.json:

iztro@2.5.8
esbuild@0.28.1

---

Hosted version

Don't want to install anything? life.aicycle.cc is a separate, maintained hosted product built on this engine — enter one birth record in the browser and read all three systems. The engine repo itself stays a pure offline compute core (no accounts, no analytics, no network); everything product-side lives in the hosted service.

---

Why CPython 3.12 specifically

The engine currently runs on the verified CPython 3.12 runtime. The reason is stated identically in requirements.txt and setup.sh:

CPython 3.12 remains locked for this change. The old Python Zi Wei native dependency constraint is gone, so this can be revisited after checking the remaining dependencies and deployment image.

In short: 3.12 is still the tested runtime for this release. The Zi Wei dependency no longer forces that lock, so a Python-version bump is a follow-up compatibility check rather than part of this refactor.

---

Usage

The engine has two modes, selected by the presence of the --json flag.

Human mode (Markdown)

Omit --json to get a readable console report. After install.sh, the short command is:

life-chart \
  --name "Sample" --gender 女 \
  --date 1990-06-15 --time 08:30 \
  --tz 8 --lat 25.033 --lon 121.5654 \
  --target 2025-01-01

If life-chart is not on your PATH, use:

~/.life-chart-engine/.venv/bin/python ~/.life-chart-engine/scripts/chart_engine.py \
  --name "Sample" --gender 女 \
  --date 1990-06-15 --time 08:30 \
  --tz 8 --lat 25.033 --lon 121.5654 \
  --target 2025-01-01

Trimmed real sample (aspects are capped at top-10 in Markdown mode):

### Sample｜女｜1990-06-15 08:30 (UTC+8)

【西洋星盤 Tropical/Placidus】
上升 獅子 08°29' ｜ 天頂 金牛 04°22'
  太陽   雙子 23°40'  11宮
  月亮   雙魚 09°00'  8宮
  ...
  主要相位: 北交點-南交點對分(0.0°)；北交點-上升對分(0.4°)；南交點-上升合相(0.4°)；木星-冥王星三分(0.4°)；月亮-天王星六分(0.8°)…

【人類圖 Human Design】
類型 投射者 ｜ 權威 自我投射型權威 ｜ 角色 1/3 ｜ 定義 一分人(單一定義)
輪迴交叉 右角度交叉（12/11 | 36/6）
定義中心 G,喉 ｜ 開放中心 情緒,意志,根,脾,薦骨,邏輯,頭
設計日期 1990-03-16
通道 ['13-33']

【紫微斗數 iztro】
五行局 土五局 ｜ 命主 祿存 ｜ 身主 火星
  命宮   戊寅  (5-14): 七殺(廟)｜天廚 蜚廉
  父母   己卯  (115-124): 天同(平)[忌]｜地劫 天喜 咸池 恩光 天德
  ...

Agent mode (JSON)

Add --json to get one JSON object on stdout and nothing else — ideal for programs and AI agents:

life-chart --json \
  --name "小明" --gender 女 \
  --date 1990-06-15 --time 08:30 \
  --tz 8 --lat 25.033 --lon 121.5654 \
  --target 2025-01-01

If life-chart is not on your PATH, use:

~/.life-chart-engine/.venv/bin/python ~/.life-chart-engine/scripts/chart_engine.py --json \
  --name "小明" --gender 女 \
  --date 1990-06-15 --time 08:30 \
  --tz 8 --lat 25.033 --lon 121.5654 \
  --target 2025-01-01

Trimmed real sample (arrays truncated to 1–2 entries; values verbatim):

{
  "ok": true,
  "schema_version": "1.1",
  "input": {
    "name": "小明", "gender": "女",
    "date": "1990-06-15", "time": "08:30",
    "tz_offset": 8.0, "lat": 25.033, "lon": 121.5654,
    "target": "2025-01-01"
  },
  "western": {
    "system": "Tropical / Placidus / astronomy-engine",
    "ascendant": { "lon": 128.483, "sign": "獅子", "deg": 8, "min": 29, "label": "獅子 08°29'" },
    "midheaven": { "lon": 34.3665, "sign": "金牛", "deg": 4, "min": 22, "label": "金牛 04°22'" },
    "planets": [
      { "name": "太陽", "retrograde": false, "house": 11, "lon": 83.6719, "sign": "雙子", "deg": 23, "min": 40, "label": "雙子 23°40'" }
    ],
    "houses": [
      { "house": 1, "lon": 128.483, "label": "獅子 08°29'" }
    ],
    "aspects": [
      { "a": "北交點", "b": "南交點", "type": "對分", "orb": 0.0 },
      { "a": "木星", "b": "冥王星", "type": "三分", "orb": 0.3744 }
    ]
  },
  "human_design": {
    "type": "投射者",
    "authority": "自我投射型權威",
    "profile": "1/3",
    "definition": "一分人(單一定義)",
    "incarnation_cross": "右角度交叉（12/11 | 36/6）",
    "design_date": "1990-03-16",
    "defined_centers": ["G", "喉"],
    "open_centers": ["情緒", "意志", "根", "脾", "薦骨", "邏輯", "頭"],
    "channels": ["13-33"],
    "gates": [
      { "planet": "☉", "personality": { "gate": 12, "line": 1 }, "design": { "gate": 36, "line": 3 } }
    ]
  },
  "ziwei": {
    "five_elements_class": "土五局",
    "soul": "祿存",
    "body": "火星",
    "hour_index": 4,
    "palaces": [
      {
        "name": "命宮", "ganzhi": "戊寅", "flags": "", "decadal_range": "5-14",
        "major_stars": ["七殺(廟)"], "minor_stars": [], "adjective_stars": ["天廚", "蜚廉"]
      }
    ],
    "horoscope": {
      "decadal": {
        "name": "大限", "heavenlyStem": "丁", "earthlyBranch": "亥",
        "ageRange": [33, 42],
        "palaceNames": ["...12..."],
        "mutagen": ["太陰", "天同", "天機", "巨門"],
        "mutagenTyped": [
          { "star": "太陰", "type": "祿" }, { "star": "天同", "type": "權" },
          { "star": "天機", "type": "科" }, { "star": "巨門", "type": "忌" }
        ]
      },
      "yearly": {
        "name": "流年",
        "mutagen": ["...4, fixed 祿/權/科/忌 order..."],
        "mutagenTyped": [{ "star": "...", "type": "祿|權|科|忌" }, "...4..."]
      },
      "age": {
        "name": "小限", "nominalAge": 26,
        "mutagen": ["...4..."],
        "mutagenTyped": [{ "star": "...", "type": "祿|權|科|忌" }, "...4..."]
      }
    }
  },
  "meta": { "engine": "life-chart-engine", "version": "1.0", "ephemeris": "astronomy-engine" }
}

---

HTTP service

The optional FastAPI wrapper exposes the same JSON contract over HTTP. It runs from a source checkout (bash setup.sh installs FastAPI/Uvicorn); the PyPI wheel ships only the CLI and MCP entry points, not server.py:

uvicorn server:app --host 0.0.0.0 --port 8000

• GET /health returns {"ok": true}.
• POST /chart accepts JSON keys matching the CLI flags: date, time, tz, lat, lon, gender, optional name, optional target, optional ziwei_day_divide.
• Auth is fail-closed: with ENGINE_API_KEY set, /chart requests must include X-Engine-Key: <value> or they return 401; without it every /chart request returns 503 unless ENGINE_ALLOW_OPEN=1 is set (local/dev only). GET /health is always open.

For Hetzner Docker+Caddy deployment, see DEPLOY-HETZNER.md.

---

Windows quick start

The Unix install.sh / setup.sh assume a POSIX layout (.venv/bin/python) and pin CPython 3.12. The bundled setup.ps1 uses the same CPython 3.12 runtime and the astronomy-engine dependency path, so native astronomy-library compilation is no longer part of Windows setup.

# prerequisites: git, and uv
irm https://astral.sh/uv/install.ps1 | iex      # if uv is not installed

git clone https://github.com/zhenheco/life-chart-engine.git
cd life-chart-engine
./setup.ps1            # CPython 3.12 venv + pinned deps
./life-chart.ps1 --help

life-chart.ps1 is the Windows equivalent of the life-chart wrapper (the venv lives at .venv\Scripts\python.exe, not .venv/bin/python). For the Markdown report, set $env:PYTHONUTF8 = "1" so the console doesn't choke on the ℞ retrograde glyph under legacy code pages — setup.ps1 / the launchers already do this.

---

Local web UI (optional)

webapp.py is a small, dependency-free (Python stdlib only) browser form for people who'd rather not type CLI flags. It is localhost-only (127.0.0.1) — birth data never leaves the machine — and is a thin front-end that subprocesses the same engine, distinct from the production FastAPI server.py.

python webapp.py            # or ./start-web.ps1 on Windows → http://127.0.0.1:8765

It renders all three systems on one page and adds three conveniences:

• Export — one-click JSON / Markdown / PDF. Markdown is the engine's native report; PDF is printed via headless Edge/Chrome (full CJK fonts, no extra Python deps).
• Boundary comparison (±30 min) — recomputes the entered time at −30/−15/0/+15/+30 minutes and highlights which fields change, making birth-time sensitivity visible at a glance (紫微 flips across 2-hour 時辰 boundaries; Western/HD stay stable).
• City quick-fill for a few common coordinates (with a reminder to verify historical DST).

---

CLI flags reference

All six birth flags are required — a missing flag exits 2 with usage on stderr and nothing on stdout, so you can never mistake the example person's chart for your own. To see the built-in example person (範例, born 2000-01-01 12:00, UTC+8, Taipei 101), pass --example explicitly.

Breaking change (v1.1.0): the old silent fallback to the example person on missing flags has been removed. Scripts that relied on it should pass --example.

Flag	Type	Required	Format / rule
--date	string	Yes	YYYY-M-D (zero-padding optional, e.g. 1990-6-15). Real calendar date, year within the supported window 1900–2100.
--time	string	Yes	H:M, 24-hour local clock time (zero-padding optional, e.g. 8:30).
--tz	float	Yes	UTC offset including DST (Taiwan = 8), within [-12, 14], finite. Written to input key tz_offset.
--lat	float	Yes	Latitude in decimal degrees, within [-90, 90], finite.
--lon	float	Yes	Longitude in decimal degrees, within [-180, 180], finite.
--gender	string	Yes	Must be exactly 男 or 女 (affects 紫微; anything else → exit 2).
--example	flag	No	Compute the built-in example person. Mutually exclusive with all six birth flags (combining → exit 2); may combine with --name, --target, --ziwei-day-divide, --json.
--name	string	No	Free text; echoed into output only. Default "範例".
--target	string	No	YYYY-M-D; 紫微 luck-period reference date (運限參考日), same 1900–2100 window. Default "2025-01-01".
--ziwei-day-divide	string	No	晚子時 rule: forward (default) counts 23:00-23:59 as next day; current counts it as current day.
--json	flag	No	Presence → JSON mode; absence → Markdown. Takes no value.

Install-path note (Linux/macOS): pip install --user life-chart-engine and the git install.sh both place a life-chart executable at ~/.local/bin/life-chart — installing both means the later one silently overwrites the symlink/script. Pick one method (or use uvx, which is unaffected). On Windows, pip user-installs go to the Python Scripts\ directory instead and do not collide with install.sh (which is POSIX-only).

The engine does not geocode places or look up time zones. The caller must convert place → lat/lon/tz themselves — and timezone/DST is the most common source of error, so verify the UTC offset that applied at the birth place and birth date.

---

Output reference

The --json envelope has seven top-level keys, in this order:

ok · schema_version · input · western · human_design · ziwei · meta

Block	Summary
ok	true on success (false in the error envelope).
schema_version	"1.1".
input	Echo of normalized inputs: name, gender, date, time, tz_offset, lat, lon, target (note tz_offset, not tz).
western	system string, ascendant/midheaven position objects, planets[], houses[] (×12), aspects[].
human_design	type, authority, profile, definition, incarnation_cross, design_date, defined_centers[], open_centers[], channels[], gates[].
ziwei	five_elements_class, soul, body, hour_index, palaces[], horoscope (always { decadal, yearly, age } on success — a horoscope failure fails the whole request loudly).
meta	{ engine, version, ephemeris } — all literals (ephemeris: "astronomy-engine").

For the full field contract — every key, type, and the agent invocation protocol — see AGENTS.md.

Field quirks worth knowing

• aspects are NOT capped in JSON. The JSON path returns every detected aspect, sorted ascending by orb (tightest first). The 10-item cap exists only in the Markdown report.
• ziwei.horoscope is all-or-nothing. On success it is always { decadal, yearly, age }; a sidecar/horoscope failure fails the whole request loudly (exit 1 / HTTP 500) — a partial or null horoscope is never emitted in an "ok": true response. stars appears only under decadal/yearly (never age); yearlyDecStar only under yearly. mutagen is a bare star-name array [str, …4] in fixed 祿/權/科/忌 order — unchanged since schema_version 1.0. schema_version 1.1 is an additive, backward-compatible bump: alongside the unchanged mutagen it adds mutagenTyped (a typed view [{ "star", "type" }, …4] in the same order) on decadal/yearly/age, decadal.ageRange [startAge, endAge], and the age sub-object (the 小限 / annual minor limit, may be null). The positional 祿/權/科/忌 mapping in mutagenTyped is invariant across all 10 天干. (Those sub-objects also expose extra internal structure — index, palaceNames[], heavenlyStem/earthlyBranch, etc. — beyond the documented placeholder.)
• Star strings encode brightness + 四化. Format is name(brightness)[mutagen], with each part optional — e.g. 紫微(廟)[祿], 紫微(廟), 天機[祿], or plain 天機. adjective_stars are plain names only (no brightness/mutagen).

---

Accuracy tiers

Not every output carries the same confidence. Read each tier accordingly:

Tier	What it covers	Confidence
Highest	Planetary longitudes, signs, retrograde, plus 紫微 star placement / 命宮·身宮 / 五行局 — pure ephemeris and calendar math.	Astronomically/calendrically exact.
High, time-dependent	Ascendant, Midheaven, all 12 house cusps, the house each planet falls in, Human Design lines, and the 紫微 時辰 index.	Exact given an accurate birth time; sensitive to minutes.
Verified	紫微斗數 star brightness — aligned to iztro's outputs.	Verified against the library.
Flag boundary ±0.3°	Any planet / gate / line sitting within ±0.3° of a boundary.	Treat as provisional and note the impact — ±0.3° can flip it across the line.

---

Known limitations

• No Chiron / minor bodies. The adapter exposes only the 10 classical planets plus the lunar nodes.
• 紫微斗數 uses one default school. iztro is called with its default star-placement school and 四化; only the late 子 hour day boundary is exposed (--ziwei-day-divide, default forward). If you normally use 飛星 or another school, the main structure is unchanged but some details may differ.
• Approximate birth time degrades the time-dependent tier. If the birth time is uncertain, the Ascendant/MC/house assignments, Human Design lines, and 時辰 — and anything derived from them — become unreliable. In that case, treat the time-dependent fields as provisional and consider event-based rectification (matching known life events to chart timing) before relying on them.

---

Use it as an MCP server (Claude Desktop / Claude Code)

pip install 'life-chart-engine[mcp]'

// Claude Desktop config → mcpServers
{ "life-chart-engine": { "command": "life-chart-mcp" } }

One tool — compute_chart — same inputs as the CLI flags, returns the full JSON envelope as text. Deterministic, offline, stdio-only. See AGENTS.md §6 for the exact schema.

Use it from an AI agent / Hermes

The intended integration model is self-install, not SaaS.

A user copies this repo's URL, and their own agent or CLI (Claude Code, Hermes, a script, etc.) clones it and runs it locally on the user's machine. The compute happens on the user's side. This repo exposes no hosted endpoint, needs no account, and requires no SaaS integration — the engine is a stateless, deterministic, offline subprocess. (A separate hosted product built on this engine exists for people who prefer a browser — it is a distinct service, not part of this repo.)

This repo itself is not operated as a network service. Under MIT, local use, modification, distribution, and hosted use are allowed under the terms in LICENSE.

For agents, the contract is simple: dispatch the installed life-chart --json wrapper when available, or fall back to the venv Python command in the repo workdir, parse stdout as JSON, branch on ok (and the exit code), then hand off the structured object. No cleanup needed — it is stateless. The full CLI + JSON contract lives in AGENTS.md.

Copy-paste setup for your AI agent

Paste this block straight into Claude Code, ChatGPT, or any coding agent — it tells the agent how to install and call the tool:

Set up and use "life-chart-engine" — a CLI that computes a Western natal chart +
Human Design + Zi Wei Dou Shu (紫微斗數) from birth data.

1. Install (needs `git`, `uv`, and Node.js; if uv is missing: curl -LsSf https://astral.sh/uv/install.sh | sh):
   curl -fsSL https://raw.githubusercontent.com/zhenheco/life-chart-engine/main/install.sh | bash

2. Compute a chart and read stdout as JSON:
   life-chart --json \
     --name "<label>" --gender <男|女> \
     --date <YYYY-MM-DD> --time <HH:MM> \
     --tz <utc_offset_including_DST> --lat <latitude> --lon <longitude> \
     --target <YYYY-MM-DD>
   If life-chart is not on your PATH, use:
   ~/.life-chart-engine/.venv/bin/python ~/.life-chart-engine/scripts/chart_engine.py --json \
     --name "<label>" --gender <男|女> \
     --date <YYYY-MM-DD> --time <HH:MM> \
     --tz <utc_offset_including_DST> --lat <latitude> --lon <longitude> \
     --target <YYYY-MM-DD>

3. Rules:
   - YOU resolve the birth city to --lat/--lon and the correct historical UTC
     offset (DST-aware). The tool does not geocode.
   - Confirm whether the birth time is exact before trusting the ascendant,
     houses, Human Design lines, or the Zi Wei hour pillar.
   - Never fabricate chart values — always call the tool.
   - Full output schema, exit codes, and the agent contract: ~/.life-chart-engine/AGENTS.md

---

Licensing

This repository is licensed under MIT.

The engine uses astronomy-engine (MIT) for astronomical calculations and iztro (MIT) for Zi Wei Dou Shu. Placidus house formulas are credited in CREDITS.md with the Meeus reference.

You may use, copy, modify, distribute, sublicense, and sell copies under the MIT terms. Keep the copyright and permission notice with substantial portions of the software.

See CREDITS.md for full attribution and dependency licenses.

---

FAQ

Can I enter a lunar date? No. Inputs are a Gregorian solar date (--date YYYY-MM-DD) and clock time (--time HH:MM). If you only have a lunar date, convert it first. 紫微斗數 is computed via iztro's solar entry point (bySolar).

My birth time is only approximate — is that a problem? The planetary positions are fine, but the Ascendant, Midheaven, house cusps, the house each planet sits in, Human Design lines, and the 時辰 are all time-sensitive. Treat those as provisional and consider event-based rectification before relying on them.

Where's Chiron / asteroids / minor bodies? Not included. The adapter exposes only the 10 classical planets and the lunar nodes.

Which 紫微斗數 school does it use? The default school as implemented by iztro. The school is not user-selectable; only the late 子 hour day boundary is configurable with --ziwei-day-divide.

Does it phone home / use the network? No. The engine is fully offline — no telemetry, no network calls, no side effects. It is a stateless, deterministic one-shot subprocess.

Can I use it inside a closed-source product? Yes. The repository is MIT-licensed. Keep the copyright and permission notice with substantial portions of the software.

---

Disclaimer

life-chart-engine is an interpretive self-awareness framework, not prediction or fatalism. The outputs are structured reference points for reflection — they do not foretell events and do not determine outcomes. Use them as calibration, with your own lived experience as the final authority. Nothing here is medical, legal, psychological, or financial advice. For decisions in those domains, consult a qualified professional.

---

Credits & License

• astronomy-engine — Don Cross, MIT; astronomical calculations.
• Meeus, Astronomical Algorithms — reference for Placidus house formulas.
• iztro — MIT, for Zi Wei Dou Shu.
• Full attribution: CREDITS.md.
• License: MIT.
• Agent / JSON contract: AGENTS.md.