i18n: bilingual (English + 中文) content throughout

- add system_en (English name) to Chart schema + registry + all 11 adapters
- bilingual LLM reading: interpret.py system prompt asks for EN then 中文 section
- bilingual mock stub, README, web UI labels, API docstrings, field descriptions
- divination terms (干支/卦名/宮名…) kept in original form as proper nouns
- 12 tests pass; all 11 systems cast with EN + 中文 names

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

Author: ChiShengChen

.env.example

@@ -1,7 +1,7 @@
-# 算命 service config — copy to .env and fill in as needed.
+# Bazaar of Fates config — copy to .env and fill in as needed. / 複製成 .env 後填入。
 
-# 解讀 backend. "mock" (default) needs NO API key: every 命盤 still casts
-# deterministically, only the prose interpretation is a stubbed facts digest.
+# Reading backend / 解讀後端. "mock" (default) needs NO API key: every chart still
+# casts deterministically, only the prose reading is a stubbed facts digest.
 LLM_BACKEND=mock
 # LLM_BACKEND=anthropic
 ANTHROPIC_API_KEY=

README.md

@@ -1,91 +1,100 @@
-# 算命 · Divination Suite
+# Bazaar of Fates · 算命 Divination Suite
 
-十一套傳統命理系統，寫成**確定性 Python 排盤引擎**，前面接一層 LLM 解讀，後面只吃一個輸入：**生辰**（出生日期＋時辰＋出生地）。
+**Eleven traditional divination systems as deterministic Python engines**, behind one input — your **birth moment** (date + time + place) — each producing a reproducible chart plus an optional bilingual AI reading.
 
-> 起源：本專案的排盤引擎源自一個更大的量化研究專案，原本是當作「對照組／安慰劑」（把命理當成 date-keyed 訊號，跑無未來函數回測證明它們是雜訊）。這裡把**排盤數學**單獨抽出來，去掉所有交易／回測，還原成它本來的用途——**幫人算命**。排盤數學以 `scripts/sync_from_main.sh` 從母專案同步（單一真相源），算命產品殼（生辰輸入、API、解讀、前端）是本 repo 原生。
+**十一套傳統命理系統**，寫成確定性 Python 排盤引擎，只吃一個輸入：**生辰**（出生日期＋時辰＋出生地），各自排出可重現的命盤＋可選的雙語 AI 解讀。
 
-## 十一系
+> **Origin / 起源.** These engines began life as *placebo controls* in a larger quant project — divination cast as date-keyed trading signals, run through a lookahead-free backtest to prove they were noise. Here the **chart math is lifted out**, all trading/backtest stripped, and restored to its real purpose: **telling fortunes**. The 排盤 math is synced from the parent monorepo (single source of truth) via `scripts/sync_from_main.sh`; the product shell (birth input, API, readings, web) is native to this repo.
+> 這些引擎原本是某量化專案裡的「對照組／安慰劑」（把命理當訊號跑無未來函數回測，證明它們是雜訊）。這裡把排盤數學抽出、去掉交易回測，還原它本來的用途——算命。
 
-| key | 系統 | 引擎核心 | 時辰敏感 | 出生地敏感 |
-|---|---|---|:--:|:--:|
-| `astrology` | 西洋占星 | `ephem` 黃道經度 | 月相 | 規劃中（上升/宮位）|
-| `bazi` | 八字（四柱）| JDN 校準干支 | ✅ 時柱 | — |
-| `ziwei` | 紫微斗數 | 純 Python 排盤 | 規劃中（命宮）| — |
-| `iching` | 梅花易數 | 時間起卦 | — | — |
-| `suimei` | 四柱推命（日）| 十二運星＋天中殺 | ✅ | — |
-| `qizheng` | 七政四餘 | 真實天文經度 | — | 規劃中 |
-| `tieban` | 鐵板神數 | 起命數 | — | — |
-| `qimen` | 奇門遁甲 | 八門九宮起局 | — | — |
-| `liuren` | 大六壬 | 四課三傳 | — | — |
-| `taiyi` | 太乙神數 | 太乙九宮 | — | — |
-| `jyotish` | Jyotiṣa 吠陀占星 | 恆星黃道＋Vimśottarī 大運 | — | 規劃中 |
+## The eleven systems / 十一系
 
-> **誠實標註**：八字／四柱推命已用 `時辰` 排時柱；占星／紫微／七政等的「時辰/出生地」欄位已在輸入層備好（`BirthInput`），但對應引擎的上升星座、命宮、宮位計算是**規劃中的引擎升級**——升級寫在母專案、再 sync 過來。
+| key | System | 系統 | engine core | time-aware 時辰 | place-aware 出生地 |
+|---|---|---|---|:--:|:--:|
+| `astrology` | Western Astrology | 西洋占星 | `ephem` ecliptic longitudes | moon phase | planned 規劃中 |
+| `bazi` | BaZi · Four Pillars | 八字（四柱）| JDN-anchored 干支 | ✅ hour pillar | — |
+| `ziwei` | Zi Wei Dou Shu | 紫微斗數 | pure-Python 排盤 | planned 規劃中 | — |
+| `iching` | Plum-Blossom I Ching | 梅花易數 | time-cast hexagram | — | — |
+| `suimei` | Shichū-Suimei (JP) | 四柱推命（日）| 十二運星 + 天中殺 | ✅ | — |
+| `qizheng` | Seven Luminaries | 七政四餘 | real astronomical longitudes | — | planned 規劃中 |
+| `tieban` | Iron Plate | 鐵板神數 | 起命數 | — | — |
+| `qimen` | Qi Men Dun Jia | 奇門遁甲 | 八門九宮起局 | — | — |
+| `liuren` | Da Liu Ren | 大六壬 | 四課三傳 | — | — |
+| `taiyi` | Tai Yi Shen Shu | 太乙神數 | 太乙九宮 | — | — |
+| `jyotish` | Jyotiṣa (Vedic) | 吠陀占星 | sidereal + Vimśottarī daśā | — | planned 規劃中 |
 
-## 快速開始
+> **Honest note / 誠實標註.** BaZi and Suimei already use `time` for the hour pillar; the time/place fields are carried on `BirthInput` for every system, but ascendant/house/命宮 computation in astrology · ziwei · qizheng · jyotish is a **planned engine upgrade** — to be written in the parent monorepo and synced over, not hand-patched here.
+
+## Quickstart / 快速開始
 
 ```bash
 python -m venv .venv && source .venv/bin/activate
-pip install -e ".[dev,llm]"          # llm 可省略；不裝就用 mock 解讀
+pip install -e ".[dev,llm]"          # drop "llm" to stay on the mock reader / 省略 llm 即用 mock
 cp .env.example .env
 
-# 後端 API
+# Backend API / 後端
 uvicorn fortune.api.main:app --reload
 
-# 靜態算命頁（免 node build）：用任意靜態伺服器開 web/index.html
+# Static fortune page, no node build / 靜態算命頁，免 node build
 python -m http.server 5500 --directory web
-# 開 http://localhost:5500/  填生辰 → 選命理系統 → 看命盤＋解讀
+# open http://localhost:5500/ → fill birth → pick a system → see chart + reading
 ```
 
-不接 LLM 也能跑：每個命盤都會**確定性排出**，只有解讀文字是 mock 的事實摘要。設 `LLM_BACKEND=anthropic` + `ANTHROPIC_API_KEY` 即換成真正的 AI 解讀。
+Runs with **no LLM key**: every chart casts deterministically; only the prose reading is a mocked facts digest. Set `LLM_BACKEND=anthropic` + `ANTHROPIC_API_KEY` for a real **bilingual (English + 中文)** AI reading.
+不接 LLM 也能跑：命盤照排，只有解讀走 mock。設金鑰後即得真正的雙語 AI 解讀。
 
 ## API
 
-| method | path | 說明 |
+| method | path | |
 |---|---|---|
-| `GET` | `/systems` | 11 系清單＋哪些可用 |
-| `POST` | `/cast/{system}` | 純命盤（不呼叫 LLM）→ `Chart` |
-| `POST` | `/reading/{system}` | 命盤＋解讀 → `Reading` |
+| `GET` | `/systems` | the 11 systems + which cast cleanly / 11 系清單＋可用狀態 |
+| `POST` | `/cast/{system}` | deterministic chart, no LLM → `Chart` / 純命盤 |
+| `POST` | `/reading/{system}` | chart + bilingual reading → `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
+  "name":"Mei","birth_date":"1990-06-15","birth_time":"14:30",
+  "gender":"female","place":"Taipei","latitude":25.04,"longitude":121.56
 }' | jq .summary
 # "日主 辛金・身弱（喜生扶）・喜用 土、金"
 ```
 
-## 架構
+## Architecture / 架構
 
 ```
 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 解讀
+  birth.py            BirthInput — the single input / 生辰輸入
+  schemas.py          Chart / Reading envelope
+  shared/             native: config / logging / llm (mock + anthropic)
+  engines/<system>/   ← synced 排盤 math from the monorepo (do NOT hand-edit)
+  casting/<system>.py per-system adapter: birth → engine fns → Chart
+  casting/__init__.py registry of the 11 systems (lazy import)
+  interpret.py        chart facts + tradition prompt → bilingual reading
   api/main.py         FastAPI
-prompts/<system>/     ← sync 自母專案的門派解讀 prompt
-web/                  靜態算命頁 + sync 來的命盤渲染元件
-scripts/sync_from_main.sh   重新同步排盤數學
+prompts/<system>/     ← synced reading prompts from the monorepo
+web/index.html        static fortune page + synced chart renderers
+scripts/sync_from_main.sh   re-sync the 排盤 math
 ```
 
-### 重新同步排盤數學
+### Re-syncing the engine math / 重新同步排盤數學
 
-母專案改了某系的排盤邏輯後：
+After the parent monorepo changes a system's casting logic:
 
 ```bash
-scripts/sync_from_main.sh                 # 預設母專案 ~/Desktop/威鯨面試_LLMEng
+scripts/sync_from_main.sh                 # default monorepo ~/Desktop/威鯨面試_LLMEng
 scripts/sync_from_main.sh /path/to/monorepo
 ```
 
-只會覆蓋 `fortune/engines/*`、`prompts/*`、`web/app/_charts/*`（排盤數學與命盤視覺）；
-生辰輸入、API、解讀、前端殼是原生的，**不會被動到**。
+Only `fortune/engines/*`, `prompts/*`, `web/app/_charts/*` are overwritten (the 排盤 math + chart visuals). The birth input, API, readings, and web shell are native and **untouched**.
+只覆蓋排盤數學與命盤視覺；生辰輸入、API、解讀、前端殼不會被動到。
 
-## 測試
+## Tests / 測試
 
 ```bash
-pytest -q     # 11 系各自從同一個生辰排出非空命盤 + mock 解讀
+pytest -q     # all 11 systems cast a non-empty chart from one birth + a mock reading
 ```
+
+## License
+
+For cultural, educational, and entertainment purposes. Divination is not a basis for financial, medical, or legal decisions.
+僅供文化、教育與娛樂用途；命理不應作為財務、醫療或法律決策的依據。

fortune/api/main.py

@@ -1,9 +1,9 @@
-"""算命 service — FastAPI. One input (生辰), eleven 命理 systems, deterministic 命盤
-plus optional LLM 解讀.
+"""Bazaar of Fates — FastAPI 算命 service. One input (birth / 生辰), eleven divination
+systems, a deterministic chart (命盤) plus an optional bilingual LLM reading (解讀).
 
     GET  /systems                  → the 11 systems + which cast cleanly
-    POST /cast/{system}            → deterministic 命盤 (no LLM)        → Chart
-    POST /reading/{system}         → 命盤 + 解讀 (LLM, mock by default) → Reading
+    POST /cast/{system}            → deterministic chart, no LLM            → Chart
+    POST /reading/{system}         → chart + reading (LLM, mock by default) → Reading
 """
 
 from __future__ import annotations
@@ -23,7 +23,7 @@
 log = get_logger("api")
 settings = get_settings()
 
-app = FastAPI(title="算命 · Divination Suite", version="0.1.0")
+app = FastAPI(title="Bazaar of Fates · 算命 Divination Suite", version="0.1.0")
 app.add_middleware(
     CORSMiddleware,
     allow_origins=settings.cors_origin_list,
@@ -34,7 +34,7 @@
 
 class ReadingRequest(BaseModel):
     birth: BirthInput
-    focus: str | None = None      # 命主想問的方向（事業/感情/健康…），可選
+    focus: str | None = None      # optional topic / 命主想問的方向（career, love, health…）
 
 
 @app.get("/health")
@@ -55,7 +55,7 @@ def cast(system: str, birth: BirthInput) -> Chart:
         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
+        raise HTTPException(500, f"{system} cast failed / 排盤失敗：{e}") from e
 
 
 @app.post("/reading/{system}", response_model=Reading)
@@ -66,5 +66,5 @@ def reading(system: str, req: ReadingRequest) -> Reading:
         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
+        raise HTTPException(500, f"{system} cast failed / 排盤失敗：{e}") from e
     return interpret(chart, focus=req.focus)

fortune/birth.py

@@ -1,9 +1,10 @@
-"""生辰輸入 — the one input the whole 算命 service takes.
+"""Birth input / 生辰輸入 — 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.
+birthplace (lat/lon) is what house-/ascendant-based systems (astrology, Jyotiṣa)
+need — carried here so engines can use it as they grow into it.
+取代母專案的「股票上市日」：一個人的出生時刻（日期＋時辰＋出生地）。
 """
 
 from __future__ import annotations
@@ -14,18 +15,18 @@
 
 
 class BirthInput(BaseModel):
-    name: str | None = Field(default=None, description="稱呼（可選，只用於解讀文案）")
-    birth_date: date = Field(..., description="出生日期")
+    name: str | None = Field(default=None, description="Name, display only / 稱呼（可選）")
+    birth_date: date = Field(..., description="Birth date / 出生日期")
     birth_time: time | None = Field(
-        default=None, description="出生時刻（時辰）。未知時 時柱以正午估算"
+        default=None, description="Birth time / 出生時刻（時辰）；unknown → noon 時柱以正午估算"
     )
-    gender: str | None = Field(default=None, description="性別（部分命理用神不同）")
+    gender: str | None = Field(default=None, description="Gender / 性別（部分命理用神不同）")
 
-    # birthplace — optional, needed for ascendant/house systems
-    place: str | None = Field(default=None, description="出生地名（顯示用）")
+    # birthplace — optional, needed for ascendant/house systems / 出生地，宮位系統需要
+    place: str | None = Field(default=None, description="Birthplace name / 出生地名（顯示用）")
     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）")
+    tz_offset_hours: float = Field(default=8.0, description="Timezone offset / 出生地時區（東八區=+8）")
 
     @field_validator("birth_date")
     @classmethod
@@ -49,9 +50,9 @@ def dt(self) -> datetime:
         return datetime.combine(self.birth_date, t)
 
     def label(self) -> str:
-        who = self.name or "命主"
+        who = self.name or "Querent 命主"
         when = self.birth_date.isoformat() + (
-            f" {self.birth_time.strftime('%H:%M')}" if self.birth_time else " (時辰未知)"
+            f" {self.birth_time.strftime('%H:%M')}" if self.birth_time else " (time unknown 時辰未知)"
         )
         where = f" · {self.place}" if self.place else ""
         return f"{who} · {when}{where}"

fortune/casting/__init__.py

@@ -1,7 +1,9 @@
 """Registry of the 11 命理 systems → their cast(birth) adapter.
+十一套命理系統 → 各自的 cast(birth) 轉接器。
 
-Each value is (中文名, "module:function"). Imports are lazy so a half-wired engine
-never breaks the whole service — `systems()` reports which casters import cleanly.
+Each value is (English name, 中文名, "module:function"). Imports are lazy so a
+half-wired engine never breaks the whole service — `systems()` reports which
+casters import cleanly. / 惰性 import，未接好的引擎不會拖垮整個服務。
 """
 
 from __future__ import annotations
@@ -11,19 +13,19 @@
 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"),
+# key : (English name, 中文名, dotted "module:func")
+REGISTRY: dict[str, tuple[str, str, str]] = {
+    "astrology": ("Western Astrology", "西洋占星", "fortune.casting.astrology:cast"),
+    "bazi": ("BaZi · Four Pillars", "八字（四柱）", "fortune.casting.bazi:cast"),
+    "ziwei": ("Zi Wei Dou Shu · Purple Star", "紫微斗數", "fortune.casting.ziwei:cast"),
+    "iching": ("Plum-Blossom I Ching", "梅花易數", "fortune.casting.iching:cast"),
+    "suimei": ("Shichū-Suimei · JP Four Pillars", "四柱推命（日）", "fortune.casting.suimei:cast"),
+    "qizheng": ("Qi Zheng Si Yu · Seven Luminaries", "七政四餘", "fortune.casting.qizheng:cast"),
+    "tieban": ("Tie Ban Shen Shu · Iron Plate", "鐵板神數", "fortune.casting.tieban:cast"),
+    "qimen": ("Qi Men Dun Jia", "奇門遁甲", "fortune.casting.qimen:cast"),
+    "liuren": ("Da Liu Ren", "大六壬", "fortune.casting.liuren:cast"),
+    "taiyi": ("Tai Yi Shen Shu", "太乙神數", "fortune.casting.taiyi:cast"),
+    "jyotish": ("Jyotiṣa · Vedic Astrology", "Jyotiṣa（吠陀占星）", "fortune.casting.jyotish:cast"),
 }
 
 
@@ -35,17 +37,17 @@ def _resolve(spec: str):
 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)
+    return _resolve(REGISTRY[system][2])(birth)
 
 
 def systems() -> list[dict[str, object]]:
-    """[{key, zh, available}] for the UI menu."""
+    """[{key, en, zh, available}] for the UI menu. / 給前端選單用。"""
     out: list[dict[str, object]] = []
-    for key, (zh, spec) in REGISTRY.items():
+    for key, (en, zh, spec) in REGISTRY.items():
         try:
             _resolve(spec)
             ok = True
         except Exception:  # noqa: BLE001
             ok = False
-        out.append({"key": key, "zh": zh, "available": ok})
+        out.append({"key": key, "en": en, "zh": zh, "available": ok})
     return out

fortune/casting/astrology.py

@@ -12,7 +12,7 @@
 from fortune.engines.astrology import astro
 from fortune.schemas import Chart
 
-KEY, ZH, ORB = "astrology", "西洋占星", 6.0
+KEY, ZH, EN, ORB = "astrology", "西洋占星", "Western Astrology", 6.0
 
 
 def cast(birth: BirthInput) -> Chart:
@@ -30,7 +30,7 @@ def cast(birth: BirthInput) -> Chart:
         f"・水星{'逆行' if readings.get('mercury_retrograde') == 'yes' else '順行'}"
     )
     return Chart(
-        system=KEY, system_zh=ZH, subject=birth.label(), cast_at=birth.dt,
+        system=KEY, system_en=EN, 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,