八字排盘 (BaZi Chart Calculator)
Professional Four Pillars of Destiny calculator with astronomical precision.
Setup
cd <skill_dir>
python3 -m venv venv && source venv/bin/activate
pip install -r scripts/requirements.txt
Only dependency: ephem (astronomy library for solar term calculation).
Usage
# Text output (default)
python scripts/bazi.py --date 1990-08-18 --time 06:00 --city 上海 --gender male
# JSON output
python scripts/bazi.py --date 1990-08-18 --time 06:00 --city 上海 --gender male --format json
# With coordinates instead of city
python scripts/bazi.py --date 1990-08-18 --time 06:00 --lat 31.23 --lon 121.47 --gender male
# Disable true solar time correction
python scripts/bazi.py --date 1990-08-18 --time 06:00 --city 上海 --gender male --no-solar-correction
# Include annual luck (流年) for specific year
python scripts/bazi.py --date 1990-08-18 --time 06:00 --city 上海 --gender male --year 2026
What It Calculates
| Feature | Description |
|---|---|
| Four Pillars | Year, Month, Day, Hour stems and branches |
| Solar Terms | Precise astronomical calculation for month pillar boundaries |
| True Solar Time | Longitude + equation of time correction (critical for western China) |
| Hidden Stems | 本气/中气/余气 for each branch |
| Ten Gods | All stem relationships relative to Day Master |
| Five Elements | Weighted distribution (hidden stems: 60%/30%/10%) + Day Master strength |
| Major Luck | Forward/reverse periods based on gender + year stem polarity |
| Relationships | 六合, 三合, 六冲, 三刑, 六害, 天干五合, 天干冲 |
Built-in Cities
50+ Chinese cities with latitude/longitude. Pass --city 城市名 directly.
Agent Integration
When a user provides birth info in conversation, extract date/time/city/gender and run the CLI. Format the text output as a message. For deeper analysis questions, use JSON output and interpret the data.
Module Structure
bazi/
├── scripts/bazi.py # CLI entry point
├── lib/
│ ├── pillars.py # Four pillar calculation
│ ├── solar_terms.py # Solar term astronomy (ephem)
│ ├── true_solar_time.py # True solar time correction
│ ├── hidden_stems.py # Hidden stems table
│ ├── ten_gods.py # Ten gods derivation
│ ├── five_elements.py # Five elements analysis
│ ├── major_luck.py # Major luck periods
│ ├── relationships.py # Clash/combine/harm
│ ├── cities.py # City coordinate lookup
│ └── constants.py # Stems, branches, mappings
└── data/cities.json # City database