adopt birth chart

.gitignore

@@ -5,4 +5,7 @@ __pycache__
 .github
 .venv/
 .qodo/
+.agents/
 dist/
+TODO.md
+log/

AGENTS.md

@@ -0,0 +1 @@
+CLAUDE.md

CLAUDE.md

@@ -0,0 +1,95 @@
+# Repository Guidelines
+
+This file provides guidance to coding agent(like claude or codex) when working with code in this repository.
+
+## Project Overview
+
+Divicast is a Chinese metaphysics(玄学) library that provides programmatic chart generation for various traditional divination systems.. Currently supports:
+- **六爻 (Six-line divination)**: Core divination system
+- **八字 (Eight-character birth chart)**: Natal chart analysis including fortune cycles, patterns (格局)
+
+Goal: Provide all mainstream Chinese divination systems as a library, published to PyPI.
+
+## Commands
+
+```bash
+# Install dependencies with uv
+uv sync
+
+# Run python with uv to ensure correct environment
+uv run python ... # run python file or snippets
+
+# Run all tests
+uv run python -m unittest
+
+# Run a specific test file
+uv run python -m unittest tests.test_geju
+
+# Run examples
+uv run python examples/sixline_example.py
+uv run python examples/bazi_example.py
+
+# Build and publish to PyPI
+
+uv cache clean # clean uv cache s
+uv build # build source distribution and wheel, outputs to dist/
+twine upload dist/* # publish to PyPI, requires ~/.pypirc with PyPI credentials
+```
+
+
+
+## Code Architecture
+
+### Source Structure
+
+```
+src/divicast/
+├── base/
+│   └── symbol.py         # Base ValuedMultiton class for enum-like divination symbols
+├── entities/             # Core data models and logic for all divination systems
+│   ├── tiangan.py        # Heavenly Stems (天干), Ten Gods (十神)
+│   ├── ganzhi.py         # Earthly Branches (地支), Nayin (纳音), Twelve Zhangsheng
+│   ├── wuxing.py         # Five Elements (五行), YinYang
+│   ├── trigram.py        # Eight Trigrams (八卦)
+│   ├── daemon.py         # Gods/Deities (神煞)
+│   ├── liushen.py        # Six Gods (六神)
+│   └── relative.py       # Relative terms（六亲）
+├── sixline/              # Six-line divination（六爻排盘）
+│   ├── divinatory_symbol.py  # Divination symbol logic
+│   └── output.py             # Six-line output formatting
+└── birth_chart/              # Eight-character birth chart (八字排盘)
+    ├── birth.py              # BirthChart class with assembly & analysis
+    ├── output.py             # StandardBirthChartOutput schema
+    └── geju.py               # Fortune pattern (格局) calculation
+    └── ...                   # Other files for 八字排盘
+```
+
+### Key Patterns
+
+- **ValuedMultiton**: Base class in `base/symbol.py` for creating enum-like divination symbols with Chinese names
+- **BirthChart.create()DivinatorySymbol.create()/**: Factory method that runs assemble() → analyze()
+
+### Data Models
+
+- `StandardBirthChartOutput`: Main output schema with personal_info, natal_chart, luck_cycles, target_flow, relations
+- Uses Pydantic for validation
+- tyme4py library for calendar calculations
+
+## Key Files
+
+- `base/symbol.py`:  all divination symbols are subclasses of ValuedMultiton, which provides a way to create enum-like classes with Chinese names and values.
+- `birth_chart/birth.py`: birth chart（八字） assembly and analysis logic,
+- `docs/bazi_module.md`: birth chart（八字） module design, capabilities, output structure, test coverage and edge cases.
+- `sixline/divinatory_symbol.py`: six-line（六爻） divination symbol generation and logic
+- `docs/sixline_module.md`: six-line divination module design, capabilities, output structure, test coverage and edge cases.
+
+
+
+## Coding Style & Naming Conventions
+- Python 3.12+; follow standard PEP 8 with 4-space indentation.
+- Use descriptive class names in `CapWords` and module/file names in `snake_case`.
+- Tests follow `tests/test_*.py` naming; test classes are `Test*` and methods are `test_*`.
+
+## Security & Configuration Tips
+- Dependencies are defined in `pyproject.toml`; keep versions compatible with Python 3.12+.
+- Avoid editing schema/data files unless updating corresponding tests.

README.md

@@ -1,13 +1,18 @@
-# 玄学排盘库
+# 玄学排盘库 [![License](https://img.shields.io/badge/license-MIT-4EB1BA.svg?style=flat-square)](https://github.com/wangsquirrel/divicast/blob/main/LICENSE)
 
-本库用于六爻排盘（六爻预测），提供了基础的六爻相关实体、符号、五行、天干地支等数据结构和推演逻辑，适合用于命理、易学、占卜等相关应用的开发。致力于面向未来，面向AI
+本库用于六爻排盘（六爻预测）和八字排盘（八字预测），提供了基础的六爻、八字相关实体、符号、五行、天干地支等数据结构和推演逻辑，适合用于命理、易学、占卜等相关应用的开发。致力于面向未来，面向AI
 
 ## 功能简介
 
+### 六爻排盘
 - 支持六爻排盘的基本流程
 - 内置天干、地支、五行、六神、卦象等基础数据
 - 提供六爻相关实体和符号的操作
-- 易于扩展和集成到其他 Python 项目
+
+### 八字排盘
+- 支持八字排盘的基本流程
+- 提供格局、大运、流年、神煞等分析功能
+- 内置十神、纳音、十二长生等基础数据
 
 ## 安装
 
@@ -41,4 +46,31 @@ rich_draw_divination(d)
 print(to_standard_format(d).model_dump_json(exclude_none=True))
 ```
 
+### 八字
+
+以下是一个简单的八字排盘示例：
+
+更多用法请参考 examples/bazi_example.py。
+
+```python
+import datetime
+from divicast.birth_chart import BirthChart, Gender
+
+# 创建一个八字盘
+chart = BirthChart.create(
+    datetime.datetime(1990, 8, 15, 14, 30, 0),
+    gender=Gender.Male,
+)
+
+# 输出八字标准化json格式
+print(chart.to_standard_output().model_dump_json(exclude_none=True))
+```
+
+## 时间约定
+
+- 本库不处理时区、地点、真太阳时换算。
+- 传入 `BirthChart.create()`、`to_standard_format()`、`DivinatorySymbol.create()` 的时间，必须是调用方已经归一化好的排盘时间。
+- 当前只接受 `naive datetime`。如果传入带 `tzinfo` 的 aware `datetime`，库会直接拒绝。
+- 如果你的业务口径是“当地真太阳时排盘”，请先在调用方完成转换，再把转换后的 `naive datetime` 传入本库。
+
 如有问题或建议，欢迎提交 issue 或 PR