Metadata-Version: 2.4
Name: life-chart-engine
Version: 1.1.0
Summary: 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.
Project-URL: Repository, https://github.com/zhenheco/life-chart-engine
Author: ZHENHEAI LLC
License-Expression: MIT
License-File: LICENSE
Keywords: ai-agents,astrology,deterministic,human-design,natal-chart,ziwei
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Utilities
Requires-Python: <3.13,>=3.12
Requires-Dist: astronomy-engine==2.1.19
Provides-Extra: mcp
Requires-Dist: mcp==1.28.1; extra == 'mcp'
Description-Content-Type: text/markdown

> 🌐 **English** · [繁體中文](./README.zh-TW.md) · [简体中文](./README.zh-CN.md) · [日本語](./README.ja.md) · [한국어](./README.ko.md) · [Español](./README.es.md) · [Français](./README.fr.md) · [Deutsch](./README.de.md) · [Português](./README.pt.md) · [Русский](./README.ru.md) · [العربية](./README.ar.md) · [हिन्दी](./README.hi.md) · [Bahasa Indonesia](./README.id.md) · [Tiếng Việt](./README.vi.md) · [ไทย](./README.th.md) · [Italiano](./README.it.md) · [Türkçe](./README.tr.md) · [Nederlands](./README.nl.md) · [Polski](./README.pl.md)

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

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
[![Python 3.12](https://img.shields.io/badge/Python-3.12-3776AB.svg)](#why-cpython-312-specifically)
[![No telemetry · offline](https://img.shields.io/badge/no%20telemetry-offline-green.svg)](#faq)
[![QA Gate](https://github.com/zhenheco/life-chart-engine/actions/workflows/qa-gate.yml/badge.svg?branch=main)](https://github.com/zhenheco/life-chart-engine/actions/workflows/qa-gate.yml)

![life-chart-engine demo](./docs/demo.gif)

`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)

```bash
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`](https://docs.astral.sh/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)

```bash
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

```bash
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`](https://docs.astral.sh/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](#why-cpython-312-specifically)).
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`)

```bash
# 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](https://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:

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

```bash
~/.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:

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

```bash
~/.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):

```json
{
  "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`:

```bash
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](./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.

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

```bash
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](./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)

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

```jsonc
// 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`](./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](https://life.aicycle.cc) 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](./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:

```text
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](./LICENSE)**.

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](./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](./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](./CREDITS.md)**.
- **License:** [MIT](./LICENSE).
- **Agent / JSON contract:** [AGENTS.md](./AGENTS.md).
