feat: 算命 Divination Suite — 11 traditional systems as a standalone fortune-telling service

Extracted the deterministic divination engines (T25–T35) from the quant monorepo,
stripped all trading/backtest coupling, and rebuilt them around their real purpose:
telling people's fortunes from a 生辰 (birth date + 時辰 + birthplace).

- 11 engine cores synced verbatim from the monorepo via scripts/sync_from_main.sh
  (single source of truth), renamed taskNN_* → real names, cross-engine imports rewritten
- Native product shell: BirthInput, uniform Chart/Reading schema, 11 casting adapters,
  registry, LLM 解讀 layer (anthropic + mock fallback), FastAPI app
- Static 算命 web page (no node build) hitting the API
- 12 passing tests; all 11 systems cast a non-empty 命盤 from one birth

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: ChiShengChen

.env.example

@@ -0,0 +1,16 @@
+# 算命 service config — copy to .env and fill in as needed.
+
+# 解讀 backend. "mock" (default) needs NO API key: every 命盤 still casts
+# deterministically, only the prose interpretation is a stubbed facts digest.
+LLM_BACKEND=mock
+# LLM_BACKEND=anthropic
+ANTHROPIC_API_KEY=
+ANTHROPIC_MODEL=claude-sonnet-4-6
+INTERPRETATION_MAX_TOKENS=900
+
+LOG_LEVEL=INFO
+LOG_FORMAT=text
+
+API_HOST=0.0.0.0
+API_PORT=8000
+CORS_ORIGINS=http://localhost:3000,http://localhost:5500

.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+.env
+.env.*
+!.env.example
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.DS_Store
+node_modules/
+web/.next/
+web/out/

README.md

@@ -0,0 +1,91 @@
+# 算命 · Divination Suite
+
+十一套傳統命理系統，寫成**確定性 Python 排盤引擎**，前面接一層 LLM 解讀，後面只吃一個輸入：**生辰**（出生日期＋時辰＋出生地）。
+
+> 起源：本專案的排盤引擎源自一個更大的量化研究專案，原本是當作「對照組／安慰劑」（把命理當成 date-keyed 訊號，跑無未來函數回測證明它們是雜訊）。這裡把**排盤數學**單獨抽出來，去掉所有交易／回測，還原成它本來的用途——**幫人算命**。排盤數學以 `scripts/sync_from_main.sh` 從母專案同步（單一真相源），算命產品殼（生辰輸入、API、解讀、前端）是本 repo 原生。
+
+## 十一系
+
+| key | 系統 | 引擎核心 | 時辰敏感 | 出生地敏感 |
+|---|---|---|:--:|:--:|
+| `astrology` | 西洋占星 | `ephem` 黃道經度 | 月相 | 規劃中（上升/宮位）|
+| `bazi` | 八字（四柱）| JDN 校準干支 | ✅ 時柱 | — |
+| `ziwei` | 紫微斗數 | 純 Python 排盤 | 規劃中（命宮）| — |
+| `iching` | 梅花易數 | 時間起卦 | — | — |
+| `suimei` | 四柱推命（日）| 十二運星＋天中殺 | ✅ | — |
+| `qizheng` | 七政四餘 | 真實天文經度 | — | 規劃中 |
+| `tieban` | 鐵板神數 | 起命數 | — | — |
+| `qimen` | 奇門遁甲 | 八門九宮起局 | — | — |
+| `liuren` | 大六壬 | 四課三傳 | — | — |
+| `taiyi` | 太乙神數 | 太乙九宮 | — | — |
+| `jyotish` | Jyotiṣa 吠陀占星 | 恆星黃道＋Vimśottarī 大運 | — | 規劃中 |
+
+> **誠實標註**：八字／四柱推命已用 `時辰` 排時柱；占星／紫微／七政等的「時辰/出生地」欄位已在輸入層備好（`BirthInput`），但對應引擎的上升星座、命宮、宮位計算是**規劃中的引擎升級**——升級寫在母專案、再 sync 過來。
+
+## 快速開始
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev,llm]"          # llm 可省略；不裝就用 mock 解讀
+cp .env.example .env
+
+# 後端 API
+uvicorn fortune.api.main:app --reload
+
+# 靜態算命頁（免 node build）：用任意靜態伺服器開 web/index.html
+python -m http.server 5500 --directory web
+# 開 http://localhost:5500/  填生辰 → 選命理系統 → 看命盤＋解讀
+```
+
+不接 LLM 也能跑：每個命盤都會**確定性排出**，只有解讀文字是 mock 的事實摘要。設 `LLM_BACKEND=anthropic` + `ANTHROPIC_API_KEY` 即換成真正的 AI 解讀。
+
+## API
+
+| method | path | 說明 |
+|---|---|---|
+| `GET` | `/systems` | 11 系清單＋哪些可用 |
+| `POST` | `/cast/{system}` | 純命盤（不呼叫 LLM）→ `Chart` |
+| `POST` | `/reading/{system}` | 命盤＋解讀 → `Reading` |
+
+```bash
+curl -s localhost:8000/cast/bazi -H 'content-type: application/json' -d '{
+  "name":"小美","birth_date":"1990-06-15","birth_time":"14:30",
+  "gender":"女","place":"台北","latitude":25.04,"longitude":121.56
+}' | jq .summary
+# "日主 辛金・身弱（喜生扶）・喜用 土、金"
+```
+
+## 架構
+
+```
+fortune/
+  birth.py            生辰輸入（唯一輸入）
+  schemas.py          Chart / Reading 統一封裝
+  shared/             原生：config / logging / llm（mock+anthropic）
+  engines/<system>/   ← sync 自母專案的純排盤數學（勿手改，會被覆蓋）
+  casting/<system>.py 每系 adapter：生辰 → 引擎函式 → Chart
+  casting/__init__.py 11 系註冊表（惰性 import）
+  interpret.py        命盤事實 + 門派 prompt → LLM 解讀
+  api/main.py         FastAPI
+prompts/<system>/     ← sync 自母專案的門派解讀 prompt
+web/                  靜態算命頁 + sync 來的命盤渲染元件
+scripts/sync_from_main.sh   重新同步排盤數學
+```
+
+### 重新同步排盤數學
+
+母專案改了某系的排盤邏輯後：
+
+```bash
+scripts/sync_from_main.sh                 # 預設母專案 ~/Desktop/威鯨面試_LLMEng
+scripts/sync_from_main.sh /path/to/monorepo
+```
+
+只會覆蓋 `fortune/engines/*`、`prompts/*`、`web/app/_charts/*`（排盤數學與命盤視覺）；
+生辰輸入、API、解讀、前端殼是原生的，**不會被動到**。
+
+## 測試
+
+```bash
+pytest -q     # 11 系各自從同一個生辰排出非空命盤 + mock 解讀
+```

fortune/__init__.py

@@ -0,0 +1,70 @@
+"""算命 service — FastAPI. One input (生辰), eleven 命理 systems, deterministic 命盤
+plus optional LLM 解讀.
+
+    GET  /systems                  → the 11 systems + which cast cleanly
+    POST /cast/{system}            → deterministic 命盤 (no LLM)        → Chart
+    POST /reading/{system}         → 命盤 + 解讀 (LLM, mock by default) → Reading
+"""
+
+from __future__ import annotations
+
+from fastapi import FastAPI, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel
+
+from fortune import casting
+from fortune.birth import BirthInput
+from fortune.interpret import interpret
+from fortune.schemas import Chart, Reading
+from fortune.shared.config import get_settings
+from fortune.shared.logging import configure_logging, get_logger
+
+configure_logging()
+log = get_logger("api")
+settings = get_settings()
+
+app = FastAPI(title="算命 · Divination Suite", version="0.1.0")
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.cors_origin_list,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+class ReadingRequest(BaseModel):
+    birth: BirthInput
+    focus: str | None = None      # 命主想問的方向（事業/感情/健康…），可選
+
+
+@app.get("/health")
+def health() -> dict[str, str]:
+    return {"status": "ok"}
+
+
+@app.get("/systems")
+def list_systems() -> list[dict[str, object]]:
+    return casting.systems()
+
+
+@app.post("/cast/{system}", response_model=Chart)
+def cast(system: str, birth: BirthInput) -> Chart:
+    try:
+        return casting.cast(system, birth)
+    except KeyError as e:
+        raise HTTPException(404, str(e)) from e
+    except Exception as e:  # noqa: BLE001
+        log.exception("cast_failed", system=system)
+        raise HTTPException(500, f"{system} 排盤失敗：{e}") from e
+
+
+@app.post("/reading/{system}", response_model=Reading)
+def reading(system: str, req: ReadingRequest) -> Reading:
+    try:
+        chart = casting.cast(system, req.birth)
+    except KeyError as e:
+        raise HTTPException(404, str(e)) from e
+    except Exception as e:  # noqa: BLE001
+        log.exception("cast_failed", system=system)
+        raise HTTPException(500, f"{system} 排盤失敗：{e}") from e
+    return interpret(chart, focus=req.focus)

fortune/api/__init__.py

@@ -0,0 +1,57 @@
+"""生辰輸入 — the one input the whole 算命 service takes.
+
+Replaces the monorepo's "stock listing date": a person's birth moment (date +
+time-of-day + optional birthplace). Time-of-day drives the 時柱 / Moon position;
+birthplace (lat/lon) is what house-/ascendant-based systems (占星, Jyotiṣa) need —
+carried here so engines can use it as they grow into it.
+"""
+
+from __future__ import annotations
+
+from datetime import date, datetime, time
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class BirthInput(BaseModel):
+    name: str | None = Field(default=None, description="稱呼（可選，只用於解讀文案）")
+    birth_date: date = Field(..., description="出生日期")
+    birth_time: time | None = Field(
+        default=None, description="出生時刻（時辰）。未知時 時柱以正午估算"
+    )
+    gender: str | None = Field(default=None, description="性別（部分命理用神不同）")
+
+    # birthplace — optional, needed for ascendant/house systems
+    place: str | None = Field(default=None, description="出生地名（顯示用）")
+    latitude: float | None = Field(default=None, ge=-90, le=90)
+    longitude: float | None = Field(default=None, ge=-180, le=180)
+    tz_offset_hours: float = Field(default=8.0, description="出生地時區（東八區=+8）")
+
+    @field_validator("birth_date")
+    @classmethod
+    def _not_absurd(cls, v: date) -> date:
+        if v.year < 1 or v.year > 9999:
+            raise ValueError("birth_date out of range")
+        return v
+
+    @property
+    def as_date(self) -> date:
+        return self.birth_date
+
+    @property
+    def hour(self) -> int:
+        """Clock hour 0–23; defaults to noon (12) when time-of-day is unknown."""
+        return self.birth_time.hour if self.birth_time else 12
+
+    @property
+    def dt(self) -> datetime:
+        t = self.birth_time or time(12, 0)
+        return datetime.combine(self.birth_date, t)
+
+    def label(self) -> str:
+        who = self.name or "命主"
+        when = self.birth_date.isoformat() + (
+            f" {self.birth_time.strftime('%H:%M')}" if self.birth_time else " (時辰未知)"
+        )
+        where = f" · {self.place}" if self.place else ""
+        return f"{who} · {when}{where}"

fortune/api/main.py

@@ -0,0 +1,51 @@
+"""Registry of the 11 命理 systems → their cast(birth) adapter.
+
+Each value is (中文名, "module:function"). Imports are lazy so a half-wired engine
+never breaks the whole service — `systems()` reports which casters import cleanly.
+"""
+
+from __future__ import annotations
+
+import importlib
+
+from fortune.birth import BirthInput
+from fortune.schemas import Chart
+
+# key : (中文名, dotted "module:func")
+REGISTRY: dict[str, tuple[str, str]] = {
+    "astrology": ("西洋占星", "fortune.casting.astrology:cast"),
+    "bazi": ("八字（四柱）", "fortune.casting.bazi:cast"),
+    "ziwei": ("紫微斗數", "fortune.casting.ziwei:cast"),
+    "iching": ("梅花易數", "fortune.casting.iching:cast"),
+    "suimei": ("四柱推命（日）", "fortune.casting.suimei:cast"),
+    "qizheng": ("七政四餘", "fortune.casting.qizheng:cast"),
+    "tieban": ("鐵板神數", "fortune.casting.tieban:cast"),
+    "qimen": ("奇門遁甲", "fortune.casting.qimen:cast"),
+    "liuren": ("大六壬", "fortune.casting.liuren:cast"),
+    "taiyi": ("太乙神數", "fortune.casting.taiyi:cast"),
+    "jyotish": ("Jyotiṣa（吠陀占星）", "fortune.casting.jyotish:cast"),
+}
+
+
+def _resolve(spec: str):
+    mod, fn = spec.split(":")
+    return getattr(importlib.import_module(mod), fn)
+
+
+def cast(system: str, birth: BirthInput) -> Chart:
+    if system not in REGISTRY:
+        raise KeyError(f"unknown system: {system!r}. known: {', '.join(REGISTRY)}")
+    return _resolve(REGISTRY[system][1])(birth)
+
+
+def systems() -> list[dict[str, object]]:
+    """[{key, zh, available}] for the UI menu."""
+    out: list[dict[str, object]] = []
+    for key, (zh, spec) in REGISTRY.items():
+        try:
+            _resolve(spec)
+            ok = True
+        except Exception:  # noqa: BLE001
+            ok = False
+        out.append({"key": key, "zh": zh, "available": ok})
+    return out

fortune/birth.py

@@ -0,0 +1,38 @@
+"""西洋占星 — cast a natal-style chart from a birth moment.
+
+Adapter over the pure synced engine (fortune/engines/astrology/astro.py). The
+engine computes ecliptic longitudes from the calendar; birth time-of-day refines
+the Moon. (Ascendant/house cusps need lat/lon and are a planned engine upgrade —
+the birthplace is already carried on BirthInput for when it lands.)
+"""
+
+from __future__ import annotations
+
+from fortune.birth import BirthInput
+from fortune.engines.astrology import astro
+from fortune.schemas import Chart
+
+KEY, ZH, ORB = "astrology", "西洋占星", 6.0
+
+
+def cast(birth: BirthInput) -> Chart:
+    d = birth.as_date
+    chart_rows = [
+        {"body": b, "ecliptic_lon": lon, "sign": sign, "sign_zh": astro.sign_zh(lon), "retrograde": retro}
+        for (b, lon, sign, retro) in astro.chart_for(d)
+    ]
+    readings = astro.astro_readings(d, ORB)
+    sun = next((r for r in chart_rows if r["body"] == "Sun"), None)
+    moon = readings.get("moon_phase", "")
+    summary = (
+        f"太陽 {sun['sign_zh'] if sun else ''}座"
+        f"・月相 {moon}"
+        f"・水星{'逆行' if readings.get('mercury_retrograde') == 'yes' else '順行'}"
+    )
+    return Chart(
+        system=KEY, system_zh=ZH, subject=birth.label(), cast_at=birth.dt,
+        chart={"planets": chart_rows, "aspects": astro.aspects_for(d, ORB)},
+        reasoning_chain=astro.reasoning_chain(d, ORB),
+        readings=readings,
+        summary=summary,
+    )

fortune/casting/__init__.py

@@ -0,0 +1,45 @@
+"""八字（四柱）— cast the natal 命盤 from birth date + 時辰.
+
+Adapter over fortune/engines/bazi/bazi.py. Birth hour drives the 時柱 (defaults to
+noon → 午時 when unknown); the engine pins 日柱 to the verified 甲子 anchor.
+"""
+
+from __future__ import annotations
+
+from fortune.birth import BirthInput
+from fortune.engines.bazi import bazi
+from fortune.schemas import Chart
+
+KEY, ZH = "bazi", "八字（四柱）"
+_ORDER = ("year", "month", "day", "hour")
+_ZH = {"year": "年柱", "month": "月柱", "day": "日柱", "hour": "時柱"}
+
+
+def cast(birth: BirthInput) -> Chart:
+    d = birth.as_date
+    pillars = bazi.four_pillars(d, birth.hour)
+    fav = bazi.strength_and_favourable(pillars)
+
+    rows = [{"pillar": _ZH[k], **pillars[k]} for k in _ORDER]
+    chain = [
+        f"{_ZH[k]}：{pillars[k]['gz']}（{pillars[k]['stem_elem']}{pillars[k]['branch_elem']}・{pillars[k]['zodiac']}）"
+        for k in _ORDER
+    ]
+    chain.append(
+        f"日主 {fav['day_master']}（{fav['dm_elem']}）→ {fav['label']}，喜用神：{'、'.join(fav['favourable'])}"
+    )
+    summary = (
+        f"日主 {fav['day_master']}{fav['dm_elem']}・{fav['label']}・"
+        f"喜用 {'、'.join(fav['favourable'])}"
+    )
+    return Chart(
+        system=KEY, system_zh=ZH, subject=birth.label(), cast_at=birth.dt,
+        chart={"pillars": rows},
+        reasoning_chain=chain,
+        readings={
+            "day_master": fav["day_master"], "dm_elem": fav["dm_elem"],
+            "strength": fav["label"], "favourable": fav["favourable"],
+            "current_liunian_elem": bazi.liunian_elem(d),
+        },
+        summary=summary,
+    )