Skip to content

v1.1.0 - BaZi (Four Pillars of Destiny) Feature

Choose a tag to compare

View all tags
@AngusHsu AngusHsu released this 03 Nov 04:06
· 28 commits to main since this release
v1.1.0
246a68c

🎉 BaZi (八字) Four Pillars of Destiny - Major Feature Release

New Features

BaZi Calculator System

This release introduces comprehensive BaZi (八字) or Four Pillars of Destiny calculation capabilities, a traditional Chinese fortune-telling method that analyzes cosmic energies present at birth.

New MCP Tools (20 Total, +2)

1. calculate_bazi

Calculates complete BaZi chart including:

  • Four Pillars: Year (年柱), Month (月柱), Day (日柱), Hour (时柱)
  • Eight Characters (八字): The eight Chinese characters forming your destiny
  • Day Master (日主): Your core elemental nature
  • Elemental Analysis: Distribution of Wood, Fire, Earth, Metal, Water
  • Life Stage Influences: How each pillar affects different life periods
  • Personalized Recommendations: Favorable colors, directions, career paths

2. calculate_bazi_compatibility

Analyzes relationship compatibility between two BaZi charts:

  • Compatibility Score: 0-10 numerical rating
  • Compatibility Level: Excellent/Good/Fair/Challenging
  • Element Relationship: How the two destinies interact
  • Strengths & Challenges: Detailed relationship insights
  • Recommendations: How to harmonize the relationship

Technical Highlights

BaZi Calculation Engine

  • Sexagenary Cycle: Accurate 60-year/day cycle calculations
  • Solar Terms: Precise month pillar based on 24 solar terms
  • Timezone Support: Adjusts to China Standard Time for traditional accuracy
  • Heavenly Stems (天干): 10 stems with element and polarity
  • Earthly Branches (地支): 12 branches with zodiac animals

Five Elements System

  • Element Distribution: Counts and analyzes all 5 elements
  • Balance Analysis: Identifies strongest and weakest elements
  • Generation Cycle (生): Wood→Fire→Earth→Metal→Water→Wood
  • Control Cycle (克): Wood克Earth, Fire克Metal, etc.
  • Recommendations: Colors, directions, careers based on your elements

Life Stages Mapping

  • Early Life (0-15 years): Year Pillar influence
  • Youth (16-30 years): Month Pillar influence
  • Middle Age (31-45 years): Day Pillar influence
  • Later Life (46+ years): Hour Pillar influence

Quality & Testing

  • ✅ 162 tests passing (+52 new BaZi tests)
  • ✅ 77% code coverage (+20% improvement)
  • ✅ 100% CI/CD passing: black, isort, ruff, mypy
  • ✅ 52 comprehensive BaZi test cases
  • ✅ Integration tests: All 20 MCP tools validated

Installation

# Using pip
pip install --upgrade lunar-mcp-server

# Using uvx (recommended)
uvx lunar-mcp-server

# Claude Desktop integration
# Update your claude_desktop_config.json:
{
  "mcpServers": {
    "lunar-calendar": {
      "command": "uvx",
      "args": ["lunar-mcp-server"]
    }
  }
}

Usage Examples

Calculate Your BaZi

# Basic BaZi calculation
result = await calculate_bazi(
    birth_datetime="1990-05-15 14:30",
    timezone_offset=8  # China Standard Time
)

# Returns:
# - Eight characters (八字)
# - Four pillars with stems and branches
# - Day master element and polarity
# - Element distribution and balance
# - Favorable colors, directions, careers
# - Life stage influences

Check Relationship Compatibility

# BaZi compatibility analysis
compatibility = await calculate_bazi_compatibility(
    birth_datetime1="1990-05-15 10:00",
    birth_datetime2="1992-08-20 14:00",
    timezone_offset=8
)

# Returns:
# - Compatibility score (0-10)
# - Compatibility level
# - Element relationship analysis
# - Relationship strengths and challenges

Documentation

  • BaZi Implementation Guide: Detailed technical documentation
  • Test Coverage: 52 comprehensive test cases
  • API Reference: Complete tool descriptions
  • Cultural Background: Traditional Chinese metaphysics

What's Changed

Added

  • BaZi calculator module (bazi.py, 720 lines)
  • 2 new MCP tools for BaZi analysis
  • 52 comprehensive BaZi test cases
  • Sexagenary cycle calculation system
  • Solar term-based month pillar calculation
  • Timezone-aware BaZi analysis
  • Five Elements balance analysis
  • Elemental compatibility scoring
  • Day master personality descriptions
  • Life stage influence mapping

Improved

  • Total test count: 110 → 162 (+47%)
  • Code coverage: 57% → 77% (+20%)
  • MCP tools: 18 → 20
  • Documentation: Added implementation guide

Technical Details

  • Reference Date: 1984-02-04 (甲子 Jia-Zi day)
  • Spring Begins: ~February 4 (year pillar boundary)
  • Time Periods: 12 two-hour periods (12 地支)
  • Elements: Complete generation and control cycles
  • Compatibility: Element relationship scoring

Breaking Changes

None - fully backward compatible with v1.0.x

Full Changelog

See CHANGELOG.md

Contributors

Thanks to all contributors who made this release possible!

Previous Release: v1.0.1
Full Changelog: v1.0.1...v1.1.0

Assets 2
Loading