# Jyotish Vedic Astrology — AI-Native Full-Reading System

> **What makes this different:** This is not a calculator. It is an AI-native Jyotish analysis system that combines calculation engines, interpretive workflows, confidence auditing, and graceful degradation — organized into a reproducible full-reading pipeline.

[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue)](https://www.python.org/)
[![Capabilities](https://img.shields.io/badge/capabilities-89-blueviolet)](references/technique_registry.json)
[![Covered](https://img.shields.io/badge/covered-79-green)](references/technique_registry.json)
[![Complete](https://img.shields.io/badge/complete-10-brightgreen)](references/technique_registry.json)
[![Partial](https://img.shields.io/badge/partial-0-lightgrey)](references/technique_registry.json)

---

## Production service layout

```text
jyotisha.chat
  -> Spaceship DNS
  -> Caddy on Hong Kong VPS (80/443)
     -> Next.js + Mastra web container (3000, private)
        -> Python Jyotish API container (5200, private)
           -> Swiss Ephemeris / local calculation engine
           -> VedAstro gateway with local fallback
  -> Supabase Cloud (Auth, Postgres, profiles, sessions, credits)
  -> external OpenAI-compatible model API
```

Current production infrastructure:

- Domain: `https://jyotisha.chat`
- Server: Hong Kong, Ubuntu 22.04, `103.117.123.53`, SSH port `22000`
- Capacity: 1 vCPU, 2 GB RAM, 40 GB disk, 5 Mbps; intended for demos and low concurrency
- Runtime directory: `/opt/jyotisha-app`
- Compose file: `deploy/docker-compose.server.yml`
- Production environment: `/opt/jyotisha-app/.env.production` (`0600`, never commit)
- Supabase project: `vtvnfqmonbfuxmqkqdlc`
- Primary source repository: `https://git.copse.top/root/Jyotisha.git`; GitHub upstream/mirror: `https://github.com/jesse-ux/Jyotisha.git`

Deployment, recovery, DNS, HTTPS, update and verification commands are documented in [`deploy/README.md`](deploy/README.md). Railway/Vercel remain optional alternatives, not the current production topology.

## Table of Contents

- [What Is This](#what-is-this)
- [Quick Start](#quick-start)
- [Core Workflow](#core-workflow)
- [Technique Coverage](#technique-coverage)
- [Why This Exists (Competitive Context)](#why-this-exists)
- [Honest Assessment](#honest-assessment)
- [Project Status](#project-status)
- [Development](#development)
- [Contributing](#contributing)
- [License](#license)

---

## What Is This

This is a **Vedic (Jyotish) astrology analysis system** designed for deep, auditable full-chart readings. It is NOT a simple ephemeris calculator — it is a multi-stage interpretive pipeline that:

1. **Computes** divisional charts (D1/D9/D10/...) via Swiss Ephemeris
2. **Routes** 89 capability entries as a backend evidence pool (Dashas, Yogas, Shadbala, Ashtakavarga, Transits...)
3. **Routes** the analysis through strict workflow paths depending on question type (career / relationship / wealth / timing)
4. **Audits** every technique used — declaring what was called, what is complete/covered, and which limitations affect confidence
5. **Degrades gracefully** — limitations are labeled, not silently over-promising

### Key Differentiators (vs. PyJHora / VedAstro / Maitreya)

| Feature | This Project | PyJHora | VedAstro | Maitreya |
|---------|-------------|----------|----------|----------|
| Full-reading pipeline (one command) | ✅ | ❌ | ❌ | ❌ |
| Strict workflow router (per-question-type) | ✅ | ❌ | ❌ | ❌ |
| Technique Audit Table (confidence labeling) | ✅ | ❌ | ❌ | ❌ |
| Capability degradation (limits are explicit) | ✅ | ❌ | ❌ | ❌ |
| MEVG external verification gates | ✅ | ❌ | ❌ | ❌ |
| 89 capability entries routed as a backend evidence pool | ✅ | ✅ (50+) | ✅ (200+) | ✅ |
| Traditional algorithm benchmarked | ✅ mixed depth | ✅ | ✅ | ✅ |
| Docker / MCP Server | ✅ | ❌ | ✅ | ❌ |
| English docs / PyPI package | ✅ in progress | ✅ | ✅ | ✅ |

---

## Quick Start

### 用户不知道问什么时

不要让用户自己组织提示词。用户只给出生信息时，AI 应用应默认执行：

1. 调用统一入口：`/api/consultation_workflow` 或 MCP `strict_workflow`。
2. 先生成 `evidence_packet`、`guided_topics`、`Technique Audit Table`。
3. 把 `guided_topics` 里的建议主题展示给用户，按优先级给出可直接点击/复制的问题。
4. 用户选题后再进入 `strict_workflow` 做事业、婚恋、财富、健康或 timing 专题。

默认引导话术：

```text
你不用先想问题。我会先根据出生信息运行统一主链，生成证据包和系统建议主题。
然后我会列出最值得继续看的 3-5 个方向，每个方向附数据依据、置信度和可直接提问的问题。
```

如果 AI 应用只能调用一个入口，优先用：

```bash
python3 scripts/vedastro_user_entrypoint.py --year YYYY --month MM --day DD --hour HH --minute mm --lat LAT --lon LON --tz TZ --question "请先生成 guided_topics 并推荐我最值得看的问题" --themes career,marriage,wealth --format markdown
```

普通用户 / AI 应用从云端仓库加载后，先跑这一条验收：

```bash
python3 scripts/user_invocation_acceptance_check.py
```

只有输出 `"status": "pass"` 且外部引擎状态被明确标为 `available` / `partial` / `missing_dependency` 时，才继续做高严谨解盘。`VedAstro` 没有官方 `raw_response` 或 API key 时，必须保留 `official_blocked` / `local_fallback` 边界。
```

### 本地 Python 环境（首次一次）

本地 API 需要 **Python 3.11 或 3.12**，并且必须从项目自己的虚拟环境启动；`pyswisseph` 安装在该环境中。不要使用 macOS/Xcode 自带的 Python 3.9，否则会因不兼容的类型语法或缺少 `swisseph` 导致服务降级或启动失败。

在仓库根目录执行：

```bash
# 将 python3.12 替换为本机可用的 Python 3.11 / 3.12
python3.12 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
```

之后所有需要计算星盘的本地 API，均使用 `.venv/bin/python` 启动；不要混用系统 `python3`。服务启动后可用 `curl http://127.0.0.1:5200/api/health` 验证 `swisseph_available` 是否为 `true`。

若看到 `No module named swisseph`，说明 API 没有使用这个虚拟环境；重新执行上面的安装命令，再用 `.venv/bin/python` 启动。脚本入口已支持其内部 `scripts.*` 包导入，不需要通过修改 `PYTHONPATH` 绕过错误。

### 本地开发启动路径

本地开发使用当前生产链的 Next.js 前端：

1. 先启动本地 API 服务：`.venv/bin/python scripts/jyotish_api_server.py --host 127.0.0.1 --port 5200`
2. 安装并启动网页服务：`npm ci --prefix frontend && npm run dev --prefix frontend`
3. 打开 `http://127.0.0.1:3000`；Next.js 通过服务端 API 路由访问 Python 服务。
4. 开发者做完整自检时运行：`.venv/bin/python scripts/run_quality_gate.py --profile quick`。

### VedAstro：聊天产品推荐配置

项目当前固定使用官方 Python SDK `vedastro==1.23.25`。首次安装依赖时必须安装到项目虚拟环境，并用同一个解释器启动后端，避免子进程落到系统 Python 后出现 `No module named vedastro`：

```bash
.venv/bin/pip install -r requirements.txt
.venv/bin/python scripts/jyotish_api_server.py --host 127.0.0.1 --port 5200
```

在仓库根目录创建本机私有配置文件 `.env.local`。聊天场景推荐先使用下面的快速官方证据模式：

```dotenv
VEDASTRO_API_ENDPOINT=https://api.vedastro.org/api
VEDASTRO_ENABLE_NETWORK=1
VEDASTRO_TIMEOUT_SECONDS=20
VEDASTRO_GATEWAY_REQUIRE_OFFICIAL_RAW_RESPONSE=1

# 聊天快速模式：保留 Dasha / Chara Dasha / Shadbala / Ashtakavarga，
# 不执行 10 行星 + 12 宫位的逐项 fan-out。
VEDASTRO_FULL_SNAPSHOT_FANOUT_ENABLED=0

# 免费公共模式下 SearchEvents 范围扫描耗时长且容易限流，
# 聊天请求中默认关闭，避免同步阻塞流式回复。
VEDASTRO_RANGE_SCAN_NETWORK_ENABLED=0

VEDASTRO_CACHE_TTL_SECONDS=604800
VEDASTRO_OFFICIAL_FULL_SNAPSHOT_CACHE_TTL_SECONDS=604800
VEDASTRO_GATEWAY_QUEUE_ENABLED=1
VEDASTRO_FREE_TIER_QUEUE=1
VEDASTRO_FAIL_OPEN_LOCAL=1
VEDASTRO_FULL_CATALOG_SAMPLE_LIMIT=0

# 没有 key 时可先使用官方公共/免费模式；不要把 key 放到前端。
# VEDASTRO_API_KEY=your_vedastro_key
```

该文件已被 `.gitignore` 忽略；`scripts/jyotish_api_server.py`、`scripts/vedastro_service_adapter.py`、`scripts/run_quality_gate.py` 会自动加载它。VedAstro 子进程默认复用启动后端的 `sys.executable`；如需指定独立解释器，可设置 `VEDASTRO_PYTHON_BIN=/absolute/path/to/python`。

快速模式仍会取得 VedAstro 官方原始响应，并让 Gateway 在存在 `official_raw_response` 时闭合为 `official_verified`；D1/D9 等基础盘继续由本地 Swiss Ephemeris 负责。它只关闭高延迟 fan-out 与 `SearchEvents` 范围扫描，不等于关闭 VedAstro。

获得稳定 API key，或把 Gateway 指向自建 VedAstro 服务后，可开启完整模式：

```dotenv
VEDASTRO_API_KEY=your_vedastro_key
VEDASTRO_FULL_SNAPSHOT_FANOUT_ENABLED=1
VEDASTRO_RANGE_SCAN_NETWORK_ENABLED=1
```

完整模式会增加外部请求数量和首包等待时间，更适合后台任务、预计算或非实时专业解盘，不建议直接放在聊天首轮的同步关键路径。运行 `.venv/bin/python scripts/diagnose_vedastro_mode.py` 可检查当前模式；通过 `/api/vedastro_gateway/status` 查看 Gateway 的实际配置和 readiness。

AI/vibe coding 推荐入口：Cline 接本仓 MCP，Aider 负责低成本小改，Dyad 只做前端原型。运行 `python3 scripts/print_cline_mcp_config.py` 生成 Cline MCP 配置；详情见 `docs/vibe_coding_setup.md`。

### 中国大陆用户：VedAstro Gateway 模式

普通中国大陆用户不需要、也不应该让浏览器直连 VedAstro。推荐部署方式是：网页只访问你自己的本地或云端后端；后端通过 `VedAstro Gateway` 统一管理 self-host、official upstream、TTL/cache、free-tier queue 和 local fallback。

最短配置：

```bash
cp .env.cn.example .env.local
.venv/bin/python scripts/jyotish_api_server.py --host 127.0.0.1 --port 5200
npm ci --prefix frontend
npm run dev --prefix frontend
```

网页侧使用：

- `Trust Center -> Web Professional Reading v1`
- `/api/vedastro_gateway/status` 查看当前后端策略
- `/api/vedastro_gateway/run` 生成 VedAstro-compatible evidence packet
- `/api/professional_reading` 生成网页专业解盘包

关键边界：

- 不要让浏览器直连 VedAstro，也不要把 `VEDASTRO_API_KEY` 放进前端。
- `VEDASTRO_CACHE_TTL_SECONDS` 和 `VEDASTRO_OFFICIAL_FULL_SNAPSHOT_CACHE_TTL_SECONDS` 用于缓存官方或自建服务结果。
- `VEDASTRO_GATEWAY_QUEUE_ENABLED=1` / `VEDASTRO_FREE_TIER_QUEUE=1` 用于把昂贵或被限流的外部请求排队。
- 如果 VedAstro 官方或自建服务不可达，`VEDASTRO_FAIL_OPEN_LOCAL=1` 会保持本地 Jyotish 引擎继续输出，并在 Technique Audit Table 里降级标注。
- Gateway 不会默认声称跑完 641 项；它只把 capability catalog、dynamic selection、cache/queue/fallback 状态作为证据边界交给 strict workflow。

### Codex 用户级 VedAstro + strict workflow 入口

如果用户在 Codex 窗口从云端 Git 仓库拉取本项目，推荐先走这一条稳定入口，而不是手动拼多个底层脚本：

```bash
python3 scripts/vedastro_user_entrypoint.py \
  --year YYYY --month MM --day DD --hour HH --minute mm \
  --lat LAT --lon LON --tz TZ \
  --question "事业机会什么时候出现" \
  --themes career,marriage,wealth \
  --reference-date 2026-07-02 \
  --format markdown
```

机器读取或交给后续 agent 处理时使用 JSON：

```bash
python3 scripts/vedastro_user_entrypoint.py \
  --year YYYY --month MM --day DD --hour HH --minute mm \
  --lat LAT --lon LON --tz TZ \
  --question "事业机会什么时候出现" \
  --themes career,health,education,property,children,migration,prashna \
  --reference-date 2026-07-02 \
  --format json
```

这个入口会自动做四件事：

1. 读取 `.env.local` 并诊断当前是 `official_extended` 还是 `fast_local_fallback`。
2. 启动 `official_full_capability_catalog`，给 VedAstro 官方能力目录生成 `domain / execution_policy / adjudicator_use / confidence_role / blocked_reason`。
3. 按 `--themes` 做动态选择，避免把健康、教育、房产、子女、迁移、Prashna 等非三大主题塞进 `general`。
4. 触发 strict workflow 合同摘要，输出 primary route、可用 route、cache/TTL/free-tier queue 策略和 honesty boundary。

边界必须保留：这个入口**不会把 641 项全部当作已执行**。它先做官方能力目录分类和主题选择；能自动执行的进入证据层，需要第二人资料、用户文本、校时画像或官方网络预算的方法会保持 `needs_user_context`、`needs_user_text`、`needs_rectification_profile` 或 `blocked`。

#### 作为 Codex 本地插件安装

本仓现在带了最小插件包装：`.codex-plugin/plugin.json`。它复用现有 `skills/` 与根目录 `mcp_server.py`，适合你把当前仓直接装进 Codex 本机环境。

1. 先把本仓登记到个人 marketplace：

```bash
python3 <home>/.codex/skills/.system/plugin-creator/scripts/create_basic_plugin.py \
  jyotish-vedic-astrology \
  --path ~/.codex/plugins \
  --marketplace-path ~/.agents/plugins/marketplace.json \
  --marketplace-name personal \
  --with-marketplace
```

上面是 Codex 官方脚本的标准 marketplace 流。如果你要让 **当前仓本身** 被安装，关键不是用 scaffold 目录跑能力，而是让 `~/.agents/plugins/marketplace.json` 里的 `jyotish-vedic-astrology` 条目最终指向当前仓路径。

最少要确认这一条存在：

```json
{
  "name": "jyotish-vedic-astrology",
  "source": {
    "source": "local",
    "path": "<repo>"
  }
}
```

2. 若本机还没把 personal marketplace 接进 Codex：

```bash
codex plugin marketplace add ~/.agents/plugins/marketplace.json
```

3. 安装插件：

```bash
codex plugin add jyotish-vedic-astrology@personal
```

4. 检查是否已被识别：

```bash
codex plugin list
```

5. 开一个**新线程**再测试。Codex 只会在新线程里重新拾取新装的 skills / MCP。

#### 本地更新 / 重装

当你改了 `.codex-plugin/plugin.json`、`skills/` 或 `mcp_server.py`：

```bash
python3 <home>/.codex/skills/.system/plugin-creator/scripts/update_plugin_cachebuster.py \
  <repo>

codex plugin add jyotish-vedic-astrology@personal
```

然后重新开新线程验证。

推荐的 official extended `.env.local` 示例：

```bash
VEDASTRO_API_ENDPOINT=https://api.vedastro.org/api
VEDASTRO_ENABLE_NETWORK=1
VEDASTRO_TIMEOUT_SECONDS=20
VEDASTRO_CACHE_TTL_SECONDS=600
VEDASTRO_OFFICIAL_FULL_SNAPSHOT_CACHE_TTL_SECONDS=600
VEDASTRO_FREE_TIER_QUEUE=1
# 可选
# VEDASTRO_API_KEY=sk_live_xxx
```

先运行：

```bash
python3 scripts/diagnose_vedastro_mode.py
```

若仍显示 `fast_local_fallback`，用户级入口仍可运行，但解盘必须把 VedAstro official 证据写成 blocked/降级，不能声称 official extended 已闭环。

### 普通用户交付形态

| 形态 | 入口 | 命令 | 能力边界 |
|------|------|------|----------|
| Local dev | `http://127.0.0.1:3000` | `.venv/bin/python scripts/jyotish_api_server.py --host 127.0.0.1 --port 5200` + `npm run dev --prefix frontend` | Next.js 用户端与本地 Python API。 |
| Production | `https://jyotisha.chat` | `docker compose --env-file .env.production -f deploy/docker-compose.server.yml up -d --build` | Caddy 是唯一公网入口；Next.js `3000` 与 Python `5200` 仅在 Docker 网络内开放。 |
| Railway（可选） | 平台分配 URL | `deploy/railway-web.Dockerfile` + `deploy/railway-api.Dockerfile` | API 使用私有服务地址，不直接暴露 `5200`。 |

生产部署与验收以 `deploy/README.md` 和 `deploy/docker-compose.server.yml` 为准；不要使用仓库根目录的 Compose 文件或直接映射 Python API 端口。

### 质量门分层

- quick：快速开发守门，适合普通代码/文案修改后先跑：`python3 scripts/run_quality_gate.py --profile quick`
- browser：Web 产品守门，覆盖 Next.js 测试、lint 与生产构建：`python3 scripts/run_quality_gate.py --profile browser`
- release：发布前守门，包含关键产品文件未跟踪检查、慢速 golden cases、真实案例复验与 Yoga 逻辑报告：`python3 scripts/run_quality_gate.py --profile release`
- accuracy：本地准确率守门，跳过浏览器点击重活，但强制运行真实案例复验、Dasha/Oracle 审计、Yoga 逻辑对照和本地准确率总报告：`python3 scripts/run_quality_gate.py --profile accuracy`
- vedastro-live：外部 VedAstro 雷达守门，只跑可选 live smoke，默认不依赖网络；只有配置 `VEDASTRO_API_ENDPOINT` 与 `VEDASTRO_ENABLE_NETWORK=1` 时才真正出网：`python3 scripts/run_quality_gate.py --profile vedastro-live`

### 真实案例复验与准确率边界

一条命令查看本机当前技能覆盖与准确率基线：

```bash
python3 scripts/local_accuracy_report.py --format markdown
```

如需给副手、CI 或后续自动化读取，使用 JSON：

```bash
python3 scripts/local_accuracy_report.py --format json
```

当前总控报告会聚合 technique registry、BPHS invariants、公开人物真实案例复验、Yoga precision/recall/F1、Dasha/Shadbala oracle readiness、Ashtakoot API parity。它用于回答“本机现在能跑什么、哪些指标已经可测、哪些能力还缺外部 oracle 证据”；它不把本地回归测试包装成最终人生事件预测准确率。

公开人物样本复验命令：`python3 tests/run_real_case_revalidation.py`。

当前复验口径是公开人物样本的出生盘星座级一致率，并对部分带有来源矛盾、时区争议或边界度数的参考行标记为 controversial_reference。这个指标用于验证排盘计算是否稳定，不等同于人生事件预测准确率，也不应被当作个人命运判断的命中率。

### Dasha 参考差异审计

对照外部 PDF 或第三方软件时，先运行 Dasha 参考差异审计，而不是直接改生产常数：

```bash
python3 scripts/dasha_reference_audit.py \
  --year YYYY --month MM --day DD \
  --hour HH --minute mm --second ss \
  --lat LAT --lon LON --tz TZ \
  --target-start-date 1986-05-18 \
  --target-source third_party_chart.pdf
```

该工具会输出当前 Vimshottari 起点、秒级出生时间敏感性、年长常数敏感性，以及对齐目标日期所需的 Moon sidereal longitude 偏移量。不要为单份 PDF 直接调生产常数；应先建立更大的 oracle 样本集，比较 ayanamsa、Moon sidereal longitude、Nakshatra 边界与 Vimshottari 起算口径。

也可以运行合并版外部 oracle 边界审计，同时查看 Dasha、外部黄经与 Shadbala 的校准状态：

```bash
python3 scripts/oracle_boundary_audit.py \
  --oracle-file references/oracle/dasha_shadbala_oracle_cases.json
```

该报告会明确标出 `production_tuning_recommended: false`：当前目标集已有外部验证行，但差异审计仍会拒绝单样本或全局倍率调参；VedAstro SDK 黄经样本已纳入 `longitude_cases`，用户盘最大差异约 26.23 角秒、D1/D9 落点一致，但这只能说明基础黄经接近，不能把当前目标集闭合夸大成生产级全局校准。

三方官方/外部 oracle sanity 总控命令：

```bash
python3 scripts/external_oracle_sanity_closure.py --format markdown
```

该报告同时检查 VedAstro official precision sanity、PyJHora black-box artifacts、jyotishganit MIT reference layer。默认命令为非阻塞 sanity，总控质量门可运行；需要真实触发 VedAstro official full snapshot 细算时，加 `--live-official-full-snapshot`。当前允许声明的是“高严谨带 blocked 行”：PyJHora 黑盒证据与 jyotishganit 参考层可审计；VedAstro 黄经 sanity 通过但 official full snapshot 细算仍需显式 live probe 且可能因前台预算或官方快照合同 blocked，不能声称三方 fully closed。

外部真值采集队列用于把缺失目标值拆成可执行任务，而不是直接调生产参数：

```bash
python3 scripts/oracle_collection_queue.py \
  --oracle-file references/oracle/dasha_shadbala_oracle_cases.json \
  --format markdown
```

如需给自动化或副手读取，可改用 JSON 输出：

```bash
python3 scripts/oracle_collection_queue.py \
  --oracle-file references/oracle/dasha_shadbala_oracle_cases.json \
  --format json
```

如需让真人或 Antigravity AI 副手直接填写证据包，可一次性导出每个 case 的 draft JSON：

```bash
python3 scripts/prepare_oracle_capture_packets.py \
  --oracle-file references/oracle/dasha_shadbala_oracle_cases.json \
  --output-dir references/oracle/artifacts/pending_packets
```

该命令会生成 `capture_manifest.json`、`OPERATOR_NEXT_STEPS.md` 和 5 个 `external_*.json`。这些导出包只是人工复核/再采集入口；当前主 oracle 文件的目标集状态以 closure dashboard 和 validator 输出为准。

如果只想优先准备当前最短闭环链路的三条首包，而不是一次性导出整批 pending packets，可直接生成统一 blank kit：

```bash
python3 scripts/generate_blank_oracle.py \
  --output-dir references/oracle/artifacts/first_packet_blank_kit
```

该命令会按当前推荐顺序导出 `dasha`、`tajika_sahams`、`shadbala` 三条 front 的首包草稿、`blank_oracle_kit_manifest.json` 和 `BLANK_ORACLE_KIT_NEXT_STEPS.md`。它只复制当前首包模板，不会猜测真值，也不会把本地引擎输出伪装成 external oracle。

填完某个 `external_*.json` 后，必须把 `status` 改为 `external_verified`，补齐 metadata、具体 `source_artifact` 文件路径以及所有 `target_placeholders`。再把该包合并回 oracle 文件：

```bash
python3 scripts/oracle_collection_queue.py \
  --oracle-file references/oracle/dasha_shadbala_oracle_cases.json \
  --apply-packet references/oracle/artifacts/pending_packets/external_template_steve_jobs_dasha_lahiri.json \
  --format json
```

这一步只负责把人工填写的外部证据写回 `template_cases`；它不会自动认可证据，也不会允许生产调参。合并后仍必须重新生成 queue 并运行 validator。

该 JSON 的 scope 是 `external_oracle_collection_queue`。当前目标集可以出现 `external_verified` 与 `ready_for_calibration` 已闭合的状态，但 `production_tuning_allowed` 仍保持 `false`；这表示只能把外部黑盒目标值作为审计证据，不能直接用这些样本做 Dasha/Shadbala 生产调参。

Ashtakoot 外部合婚 oracle 使用同一个队列生成器，但独立样本文件是 `references/oracle/ashtakoot_oracle_cases.json`：

```bash
python3 scripts/oracle_collection_queue.py \
  --oracle-file references/oracle/ashtakoot_oracle_cases.json \
  --format json
```

该队列同样保持 `ready_for_calibration: 0`，用于采集 `ashtakoot_36_point` 外部合婚目标值，而不是重写现有 `scripts/ashtakoot.py` 算法。每条样本要补齐 `target.total_score`、`target.varna`、`target.vashya`、`target.tara`、`target.yoni`、`target.graha_maitri`、`target.gana`、`target.bhakoot`、`target.nadi`、`target.kuja_status`，并保留 JHora/VedAstro/AstroSage 等外部截图或 API artifact。

每个队列任务还包含 `evidence_packet.capture_id` 草稿证据包。人工或副手录入外部真值时，必须至少填写 `tool_name`、`tool_version_or_url`、`capture_date`、`source_artifact`、`ayanamsa`、`node_mode`、`timezone`、`operator_note`，并保留截图、API 响应或 stdout 等外部 artifact；不得把本仓库本地计算输出当作 `source_artifact`。

外部截图和 stdout 片段统一存入 `references/oracle/artifacts/`，证据包里的 `source_artifact` 必须使用该目录下的 repo-relative 路径或明确标注的外部审阅位置。所有私人截图必须打码；不得提交私人 PDF 原件、不得提交完整出生报告，也不得提交浏览器 scratch 目录或含账号会话/cookie/token/桌面通知的截图。

第一条 JHora/PyJHora 黑盒证据采集按 `docs/user_jhora_capture_guide.md` 执行：优先使用 Steve Jobs 或合成样本，采集 Moon sidereal longitude、Vimshottari start date 与 Shadbala 七曜六分量，保存到 `references/oracle/artifacts/` 后再运行 evidence validator。

外部目标字段采用 `target_fields` + `target_placeholders` 双层结构：`target_fields` 固定记录该案例需要校验的目标，例如 `target.moon_sidereal_longitude_deg`、`target.vimshottari_start_date`、`target.shadbala_components`；当这些字段被真实外部来源填入并且证据包状态升为 `external_verified` 后，队列生成器会保留这些值，不会再把它们降级成 `draft`。这保证了“人工/JHora/PyJHora/VedAstro 采集 → JSON 填写 → 队列生成 → validator 复核”的路径可复验。

当外部证据包被填写回队列 JSON 后，用证据验证器做第二层防线：

```bash
python3 scripts/oracle_evidence_validator.py \
  --queue-file /path/to/filled_external_oracle_collection_queue.json
```

该验证器输出 `external_oracle_evidence_validation`，会检查 `evidence_packet` 必填元数据、`target_placeholders` 是否已填、是否覆盖 `target_fields`、是否包含外部 artifact，以及是否错误使用本仓库本地引擎输出。只有状态为 `external_verified` 且证据完整的包才会进入可复核状态；通过 validator 不等于允许生产调参。

证据包通过 validator 之后，再运行边界差异审计，比较本地引擎与外部 Dasha/Shadbala 目标值：

```bash
python3 scripts/oracle_boundary_audit.py \
  --oracle-file references/oracle/dasha_shadbala_oracle_cases.json
```

审计报告中的 `template_comparisons` 会列出 external-verified template 的 Dasha 起点差异、Shadbala 七曜分量/总分差异、每个分量的 Rupa 容差、单位说明和 `global_scaling_check.recommendation: reject_global_scaling`，并继续保持 `production_tuning_recommended: false`，防止用单个样本或全局倍率调生产常数。

公开 benchmark 看板用于长期展示能力状态、oracle readiness 和“是否可宣称全球第一”的诚实边界：

```bash
python3 scripts/public_benchmark_dashboard.py \
  --oracle-file references/oracle/dasha_shadbala_oracle_cases.json \
  --format markdown \
  --output docs/benchmark/public_jyotish_benchmark_dashboard.md
```

当前看板固定输出 `can_claim_global_first: false`，直到外部 oracle 样本、差异审计和长期公开 benchmark 都达到生产调参标准。

外部 oracle 总控 closure 看板会合并 Dasha、Shadbala 与 Tajika/Sahams 三条硬闭环战线，给出总任务数、已验证数、第一优先级和下一条执行命令：

```bash
python3 scripts/oracle_closure_master_dashboard.py \
  --dasha-oracle-file references/oracle/dasha_shadbala_oracle_cases.json \
  --tajika-oracle-file references/oracle/tajika_annual_oracle_cases.json \
  --format markdown \
  --output docs/benchmark/jyotish_external_oracle_closure_master_dashboard.md
```

当前总控看板输出 `total_tasks: 12`、`external_verified_tasks: 12`、`can_claim_current_target_set_closure: true`，但 `can_claim_global_oracle_closure: false` 与 `production_tuning_allowed: false` 仍保持锁定。含义是当前目标集已闭合，不能夸大成全球 oracle、预测准确率或生产调参闭环。

Dasha 外部 oracle 最短闭环状态板用于把“大运外部真值”从 Shadbala 绝对值大包中拆出来，优先推进第一条可验证边界日期：

```bash
python3 scripts/dasha_oracle_closure_status.py \
  --oracle-file references/oracle/dasha_shadbala_oracle_cases.json \
  --format markdown \
  --output docs/benchmark/dasha_external_oracle_closure_status.md
```

当前第一优先级是 `external_template_steve_jobs_dasha_lahiri`。该状态板只要求 `target.vimshottari_start_date` 和外部证据 metadata，不要求同时填完 Shadbala 七曜六分量；这样可以先完成 Dasha oracle 的第一条闭环，再单独推进 Shadbala 绝对值闭环。

第一条外部证据包的交互辅助命令：

```bash
python3 scripts/first_oracle_packet_assistant.py \
  --front dasha \
  --format markdown \
  --output docs/benchmark/first_dasha_oracle_packet_assistant.md
```

同一个助手也支持：

```bash
python3 scripts/first_oracle_packet_assistant.py --front tajika_sahams --format markdown --output docs/benchmark/first_tajika_oracle_packet_assistant.md
python3 scripts/first_oracle_packet_assistant.py --front shadbala --format markdown --output docs/benchmark/first_shadbala_oracle_packet_assistant.md
```

该助手不会生成或猜测 JHora/PyJHora 真值，只会列出当前 packet 还缺哪些字段、可用外部来源、apply 命令和 validator 命令。

如需先看三条硬闭环 front 的统一排序入口，而不是分别运行三个助手：

```bash
python3 scripts/oracle_packet_assistant_index.py \
  --format markdown \
  --output docs/benchmark/first_oracle_packet_assistant_index.md
```

该索引会固定列出 `dasha`、`tajika_sahams`、`shadbala` 三条 front 的首包 case、缺失字段数、operator card 与推荐执行顺序，方便直接判断当前最短闭环路径。

Shadbala 外部绝对值闭环使用独立状态板，专门追踪七曜的六分量与总 Rupa：

```bash
python3 scripts/shadbala_oracle_closure_status.py \
  --oracle-file references/oracle/dasha_shadbala_oracle_cases.json \
  --format markdown \
  --output docs/benchmark/shadbala_external_absolute_value_closure_status.md
```

当前第一优先级是 `external_template_synthetic_north_china_shadbala_raman`。除了同一 oracle 行里的 `target.moon_sidereal_longitude_deg`，还必须填写 Sun/Moon/Mars/Mercury/Jupiter/Venus/Saturn 的 `sthana`、`dig`、`kala`、`chesta`、`naisargika`、`drik`、`total_rupa`；验证器会检查分量和总分，不允许用一个全局倍率把本地输出硬缩放成外部值。

Tajika/Sahams 年运系统使用独立的外部 oracle 队列，专门追踪 Varshaphala、太阳回归、Muntha、Year Lord、Mudda Dasha、Sahams 与 Tajika Yogas 的外部验证状态：

```bash
python3 scripts/tajika_annual_oracle_queue.py \
  --oracle-file references/oracle/tajika_annual_oracle_cases.json \
  --format markdown
```

公开年运看板可这样生成：

```bash
python3 scripts/tajika_annual_benchmark_dashboard.py \
  --oracle-file references/oracle/tajika_annual_oracle_cases.json \
  --format markdown \
  --output docs/benchmark/tajika_sahams_annual_benchmark_dashboard.md
```

当前 Tajika/Sahams 看板固定输出 `can_claim_tajika_sahams_closure: false`：本地 skill 已有年运计算与解释骨架，但太阳回归精确时刻、Varsha Lagna、Muntha、Mudda Dasha、Punya/Rajya/Vivah Saham 和 Tajika Yogas 仍需 JHora/PyJHora/书例级外部证据后，才能宣称年运闭环。

年运第一条最短闭环状态板：

```bash
python3 scripts/tajika_annual_closure_status.py \
  --oracle-file references/oracle/tajika_annual_oracle_cases.json \
  --format markdown \
  --output docs/benchmark/tajika_sahams_annual_closure_status.md
```

如需导出可填写的年运证据包：

```bash
python3 scripts/tajika_annual_oracle_queue.py \
  --oracle-file references/oracle/tajika_annual_oracle_cases.json \
  --write-packet-dir references/oracle/artifacts/pending_packets \
  --format json
```

填完 `external_template_steve_jobs_varshaphala_1984_lahiri.json` 后，可合并回年运 oracle：

```bash
python3 scripts/tajika_annual_oracle_queue.py \
  --oracle-file references/oracle/tajika_annual_oracle_cases.json \
  --apply-packet references/oracle/artifacts/pending_packets/external_template_steve_jobs_varshaphala_1984_lahiri.json \
  --format json
```

`full-reading` 也会输出 `ai_prompt_pack`：这是给网页/app、skill 或后端 AI 代理使用的结构化 Prompt/RAG 上下文包。它不会硬编码断语，而是携带 D1/D9/Dasha/Shadbala/Ashtakavarga 的证据快照、推荐检索文档和边界提示，要求大模型基于计算证据交叉验证，避免单一配置下结论。

### Prerequisites

- Python 3.11+
- Swiss Ephemeris (`pyswisseph` or `ephem`)
- Optional: `pypdf`, `pdfplumber` (for PDF chart input)

### Install

```bash
# Clone the repository
git clone https://github.com/732642856/yinduzhanxing.git
cd yinduzhanxing

# Install Python dependencies
pip install -r requirements.txt

# Verify installation
python3 scripts/audit_capabilities.py --mode validate
# Expected: valid=true, problem_count=0
```

### Minimal Full Reading (5 minutes)

```bash
python3 scripts/jyotish_engine.py full-reading \
  --year 1990 --month 6 --day 15 \
  --hour 10 --minute 30 \
  --lat 28.6139 --lon 77.2090 --tz 5.5 \
  --age 36 \
  --transit-date 2026-06-04
```

**Output:** ~45 computed modules, zero errors, complete structured reading with technique audit table.

### Sample Output (abbreviated)

```
═══ FULL READING ═══
Birth Data: 1990-06-15 10:30  (+5.5) 28.61°N 77.21°E
Lagna: Gemini   Sun: Taurus   Moon: Leo

── Static Analysis ──
[✓] D1 Rashi Chart
[✓] D9 Navamsa
[✓] D10 Dasamsa
[✓] Vimshottari Dasha (120 years)
[✓] Ashtakavarga (8-point system)
[✓] Shadbala (covered — absolute Rupa totals, component invariants verified)
[✓] Yogas & Doshas
[✓] Argala (planetary interventions)
[✓] Nakshatra Advanced (Chandra Bala / Tara Bala)

── Dynamic Timing ──
[✓] Vimshottari Dasha breakdown
[✓] Dasha Sandhi detection
[✓] Transit (true positions)
[✓] Double Transit analysis
[✓] Narayana Dasha
[✓] Solar Return / Varshaphala
[✓] Nakshatra Dasha (Ashtottari)

── Technique Audit Table ──
✓ Vimshottari Dasha        covered      high confidence
✓ Ashtakavarga             covered      high confidence
✓ Shadbala                covered      absolute Rupa output; total_virupas component invariant passed
✓ Chara Dasha             covered      KN Rao benchmark 95.83% overall match
✓ KP Sub-Lord             covered      SubLord/SubSubLord + ABCD significator workflow
```

---

## Core Workflow

### Three Input Paths

| Path | Input | Behavior |
|------|-------|----------|
| **A: Precise birth data** | Date + time + coordinates | Full `full-reading` engine |
| **B: PDF / text chart** | Scanned chart or description | Extract → Quality Gate → route to A |
| **C: Uncertain birth time** | "Don't know my birth time" | Interactive birth time rectification |

### Eight-Stage Pipeline

```
Stage -1: Question-type routing (career / relationship / wealth / timing)
Stage 0:  Input routing (A / B / C)
Stage 1:  (B only) PDF extraction + Quality Gate
Stage 2:  Intent recognition → target house routing
Stage 3:  Static analysis (10 steps)
Stage 4:  Dynamic timing (7 steps)
Stage 5:  Timing output (5-layer verification)
Stage 6:  Remedial measures (optional)
Stage 7:  Modern language packaging
Stage 8:  Technique Audit Table (mandatory)
```

**Strict Workflow Router** (`references/strict-workflow-router.md`):
- Career questions → `career-timing-strict`
- Relationship questions → `relationship-timing-strict`
- Wealth questions → `wealth-timing-strict`
- Event timing → `event-timing-strict`
- Historical verification → `event-verification-strict`

The AI does NOT require the user to name techniques (e.g., "Chara Dasha"). It auto-selects based on question type.

---

## Technique Coverage

Current registry count: **89 capability entries** (79 covered, 10 complete, 0 partial, 0 missing).

These entries are a **backend evidence pool**, not a flat list of 89 user-facing
prediction sources. Ordinary users see topic-level conclusions and evidence
summaries. The question-domain router selects a small primary chain, then uses
supporting indicators only to raise/lower confidence. Audit-only and alias
entries cannot affect astrological conclusions.

The table below lists representative high-value entries. Treat
`references/technique_registry.json` as the source of truth for the full
machine-readable registry.

| Technique | Status | Notes |
|-----------|--------|-------|
| D1 Rashi Chart | ✅ covered | Swiss Eph base |
| D9 Navamsa | ✅ covered | |
| D10 Dasamsa | ✅ covered | |
| Vimshottari Dasha | ✅ covered | |
| Dasha Sandhi | ✅ covered | |
| Ashtakavarga | ✅ covered | BPHS/PVR calibrated |
| Argala | ✅ covered | |
| Vargottama | ✅ covered | |
| Pushkara | ✅ covered | |
| A10 / Karma Pada | ✅ covered | |
| UL / Upapada | ✅ covered | |
| Transit (true positions) | ✅ covered | |
| Double Transit | ✅ covered | |
| Nakshatra Advanced | ✅ covered | Tara Bala / Chandra Bala / Sub-Lord workflow |
| Narayana Dasha | ✅ covered | CLI and full-reading integration |
| Solar Return / Varshaphala | ✅ covered | Tajika annual-chart workflow |
| **Shadbala** | ✅ covered | **absolute Rupa component-sum output; internal invariants pass; external absolute-value oracle expansion remains open** |
| **Chara Dasha** | ✅ covered | **KN Rao benchmark: sign 100%, duration 91.67%, overall 95.83%** |
| KP Sub-Lord | ✅ covered | SubLord/SubSubLord + ABCD significator workflow |
| Bhava Chalit | ✅ covered | Sripati/Porphyry/Equal/Whole Sign/Placidus/Koch |
| Sudarshana Chakra | ✅ covered | Asc/Moon/Sun reference charts + convergence scoring |
| Tajika Yogas | ✅ complete | Annual-chart yoga set |
| Raj Yoga | ✅ covered | Rule-based detection |
| Dhana Yoga | ✅ covered | Rule-based detection |
| Pancha Mahapurusha | ✅ covered | Complete detection |
| Neecha Bhanga | ✅ complete | Debilitation cancellation workflow |
| Sade Sati | ✅ covered | Saturn pressure timing |
| Tithi Lord | ✅ complete | Lunar-day ruler workflow |
| Pancha Pakshi | ✅ complete | Five-bird system |
| Rashi Tulya Navamsa | ✅ covered | D1/D9 mapping |
| Trimshamsa D30 | ✅ covered | D30 varga support |
| Marriage Counting | ✅ complete | Bhrigu Pada marriage-counting method |
| Prashna Integration | ✅ complete | Prashna workflow integrated |
| Bhrigu Pada Dasha | ✅ complete | Pada progression workflow |
| Muhurta | ✅ covered | Panchanga / auspicious timing workflow |

**Legend:**
- ✅ `covered` — implemented and benchmarked against authoritative sources
- ✅ `complete` — implemented with integrated workflow and validation hooks
- ✅ `covered` — implemented and available in the engine, sometimes with explicit confidence caps
- 🔶 `partial` — reserved for implemented-but-insufficiently-integrated techniques; current registry count is 0
- ❌ `missing` — not currently present in the registry; current registry count is 0

---

## Why This Exists (Competitive Context)

### The Landscape

| Project | Type | Strength | Weakness |
|---------|------|----------|-----------|
| **PyJHora** | Calculation library | Strongest traditional algorithm coverage (50+ Dashas, 284 Yogas) | No interpretive pipeline; user must interpret results themselves |
| **VedAstro** | API / Web platform | 200+ endpoints, Docker, MCP Server, MIT license | Interpretive audit & confidence labeling weaker |
| **Maitreya** | Desktop software | Mature cross-platform GUI | Jyotish depth not as deep as specialized projects |
| **jyotisha** | Panchanga / calendar | Excellent Panchanga accuracy | Not a full reading system |
| **This project** | AI-native analysis system | Full pipeline + audit + degradation | Pure calculation accuracy still being benchmarked |

### Our Position

> **PyJHora is the calculator. VedAstro is the API platform. Maitreya is the desktop software. This project is the "AI-native Jyotish research analyst."**

We are NOT trying to out-calculate PyJHora (it has years of lead). Our value is in:
1. Organizing calculations into a **reproducible interpretive workflow**
2. **Auditing** every technique used and declaring confidence
3. **Degrading gracefully** — confidence caps and limitations are labeled, not silently over-promising
4. Being **AI-native** — designed for integration with LLM-based analysis

---

## Honest Assessment

We believe in transparency about limitations. This is NOT a "99% accurate" system, and anyone claiming that about Jyotish is over-selling.

### Current Accuracy Estimates (self-evaluated)

| Dimension | Score | Notes |
|-----------|-------|-------|
| Astronomical foundation (Swiss Eph) | 8.5/10 | Depends on ayanamsa, node mode, house system |
| Traditional algorithm accuracy | 8.4/10 | Chara Dasha benchmark passed; Shadbala absolute Rupa invariants now pass; Dasha oracle expansion remains open |
| Technique coverage breadth | 9.1/10 | 65 registered techniques; broad and increasingly benchmarked |
| Reading detail depth | 9.6/10 | Possibly best among open-source projects |
| Prediction workflow rigor | 8.8/10 | Strict routing + audit table |
| Verification system | 8.2/10 | Has registry, benchmark, degradation; some verification still internal |
| Engineering maturity | 7.6/10 | Docker, PyPI config and CI exist; release artifacts still need cleanup |
| Open-source influence | 5.5/10 | Currently more of a "private high-density toolkit" |

### What Confidence Caps Mean (Important)

Even when a technique is labeled `covered`, it may carry a confidence or validation boundary:
- It CAN produce output
- Some components may still need broader external oracle expansion against PyJHora / JHora / canonical texts
- It should be interpreted together with cross-technique evidence
- It must NOT be the sole basis for high-confidence predictions when its limitation says so

Examples:
- `Shadbala` (covered): absolute Rupa totals are reported directly from six component sums; internal component invariants pass and `total_rupas = total_virupas / 60`, while external absolute-value oracle expansion remains open.
- `Chara Dasha` (covered): KN Rao benchmark passes at 95.83% overall; remaining differences are documented around Aquarius/Scorpio co-lord strength arbitration.

---

## Project Status

**Current version:** `v6.9.14`

### Recently Completed

- `v6.9.14` — Sudarshana Chakra complete + 475 pytest cases + 65-technique registry audit PASS.
- `v6.9.13` — Bhava Chalit complete + transit trigger output normalization + Nakshatra test calibration.
- `v6.9.12` — Shadbala precision upgrade + Ashtakoot 36-point compatibility + expanded subcommands.
- `v6.9.6` — Field mapping fixes (degree→degree_in_sign + toFixed null safety); PyPI publishing config.
- `v6.9.5` — birth_info null safety + API field mapping fixes.
- `v6.9.4` — AI interpretation integration; current browser build disables direct model API keys and routes AI through server-side `/api/chat` or a backend proxy.
- `v6.9.3` — 35 Dasha systems, 405+ Yoga rules, KP complete system, Prashna, 16-factor synastry, Remedies, Sahams 36, Sudarshana, PMC, Tajika.
- `v6.1.12` — Chara Dasha KN Rao Method rewrite, PyJHora benchmark 95.83% PASS.
- `v6.1.10` — Darakaraka deep reader wired into `full-reading.modules.jaimini.darakaraka`; thematic reports now consume real DK and Rashi Tulya Navamsa evidence.
- `v6.1.9` — Public/sanitized benchmark suite, competitive research, coverage roadmap and PDF validation methodology added.
- `v6.1.8` — Yoga validation reached F1=95.22% (FP=36, FN=63); thematic reports consume real `full-reading.modules` evidence.
- `v6.1.6` — Five-system Dasha convergence wired into full-reading (Vimshottari + Chara + Yogini + Ashtottari + Kalachakra).
- `v6.0.11` — Shadbala 1200/1200 internal invariants pass; later upgraded to absolute Rupa component-sum output.

### Actively Working On (P0)

1. **Release hygiene** — run the release profile, keep product-critical files tracked, rebuild wheel/sdist, and align GitHub tags with source version
2. **README / package metadata sync** — keep public docs, registry counts and distribution artifacts consistent
3. **Dasha oracle expansion** — add external cases for Vimshottari start/end boundaries and configurable year-length/ayanamsa comparisons
4. **Benchmark expansion** — add more oracle cases for Shadbala, KP and annual-chart modules
5. **Frontend verification** — keep the Next.js API contracts aligned with the Python engine output

### Next (P1)

- Production image publishing and smoke-test docs
- English documentation examples and API tutorials
- Multi-Ayanamsa UX polish and benchmark examples（计算层已可验证切换；网页设置展示和更多外部样本仍需补齐）

---

## Development

### Running the Test Suite

```bash
# Syntax check all scripts
python3 -m py_compile scripts/*.py

# Capability audit (must pass with 0 problems, 0 warnings)
python3 scripts/audit_capabilities.py --mode validate

# Next.js unit tests, lint, and production build
npm test --prefix frontend
npm run lint --prefix frontend
npm run build --prefix frontend

# Full-reading regression test (use FICTIONAL data only)
python3 scripts/jyotish_engine.py full-reading \
  --year 1990 --month 6 --day 15 \
  --hour 10 --minute 30 \
  --lat 39.9042 --lon 116.4074 --tz 8 \
  --age 36 \
  --transit-date 2026-06-04
```

### Important Rules

1. **NEVER** put real user birth data into skill files, tests, CHANGELOG, or public repos
2. Use only: (a) public AA-rated celebrity data, (b) explicitly fictional smoke tests, (c) current-session data (never persisted)
3. Always run `git status --short --branch` before starting work
4. Always run `py_compile` + `audit_capabilities.py` + full-reading regression after modifications
5. Do NOT remove a confidence or validation boundary without external benchmark evidence
6. Do NOT refactor arbitrarily; make minimal verifiable changes

### Directory Structure

```
jyotish-vedic-astrology/
├── SKILL.md                          # Core entry point (Chinese)
├── README.md                         # This file (English)
├── CHANGELOG.md                     # Version history
├── requirements.txt                  # Python dependencies
├── references/
│   ├── technique_registry.json      # Machine-readable technique registry
│   ├── strict-workflow-router.md   # Question-type routing rules
│   ├── quick-reference-guide.md    # Quick reference
│   └── ...                         # Knowledge reference docs
├── scripts/
│   ├── jyotish_engine.py           # Main engine entry point
│   ├── audit_capabilities.py       # Capability audit tool
│   ├── shadbala.py                # Shadbala implementation
│   ├── dasha_calculator.py        # Dasha calculations
│   └── ...                        # 90+ technique and orchestration scripts
└── tests/                          # Test cases
```

---

## Contributing

We welcome contributions, especially:

1. **Benchmark data** — PyJHora / JHora output comparisons for specific techniques
2. **Traditional text verification** — checking technique implementations against BPHS, PVN Rao, BV Raman
3. **Documentation** — English docs, tutorials, example outputs
4. **Engineering** — Docker, CI, MCP Server, API layer
5. **Test cases** — fictional birth data with expected outputs

### How to Contribute

1. Fork the repository
2. Create a feature branch (`git checkout -b fix/chara-dasha-benchmark`)
3. Make your changes (follow the development rules above)
4. Run the full test suite
5. Commit with a clear message
6. Push and create a Pull Request

### Philosophy

We prioritize **truth over coverage**. It is better to have 10 well-benchmarked techniques than 50 poorly-implemented ones. If you contribute a technique, please include:
- The source text / authority it is based on
- Benchmark comparison data (if available)
- Honest assessment of limitations

---

## License

MIT License — see [LICENSE](LICENSE) for details.

---

## Acknowledgments

- **Swiss Ephemeris** — astronomical calculation foundation
- **PyJHora** (`naturalstupid/PyJHora`) — benchmark reference for traditional algorithms
- **VedAstro** (`VedAstro/VedAstro`) — engineering and productization reference
- **BPHS (Brihat Parashara Hora Shastra)** — canonical text
- **PVN Rao / KN Rao** — traditional Jyotish teaching lineage

---

## Contact & Support

- **Issues:** [GitHub Issues](https://github.com/732642856/yinduzhanxing/issues)
- **Discussions:** [GitHub Discussions](https://github.com/732642856/yinduzhanxing/discussions)

---

> **Final note:** This system is a research tool. It should NOT be used for making life-altering decisions without consulting qualified human astrologers. The techniques implemented here are complex and context-dependent; software output always benefits from human judgment.