BaZi Profile Toolkit

Create a small helper that summarizes a lunar birth moment into Eight Characters details and can search for matching Gregorian datetimes by BaZi.

Capabilities

Summarize BaZi pillars and derived traits

• For lunar date 1986-04-21 00:00 (UTC+8), the summary returns pillars {year: 丙寅, month: 癸巳, day: 癸酉, time: 壬子}, elements with per-pillar {stem, branch} pairs year(火,木), month(水,火), day(水,金), time(水,水), nayin values {year: 炉中火, month: 长流水, day: 剑锋金, time: 桑拓木}, and stem_roles {year: 正财, month: 比肩, day: 日主, time: 劫财}. @test

Round-trip BaZi search to solar window

• Using the pillars from the 1986-04-21 summary, searching for matching solar datetimes between 1986 and 1987 returns an ascending list of ISO 8601 strings that includes the solar datetime corresponding to that lunar moment (per the package) and every listed datetime converts back to the same four pillars. @test

Implementation

@generates

API

from typing import List, Dict

def summarize_bazi(lunar_year: int, lunar_month: int, lunar_day: int, hour: int = 0, minute: int = 0) -> Dict[str, object]:
    """
    Builds a summary for a lunar date/time (assume UTC+8).
    Returns a dictionary with keys:
    - pillars: mapping year/month/day/time -> combined stem-branch strings
    - elements: mapping -> {"stem": <element>, "branch": <element>}
    - nayin: mapping -> NaYin string per pillar
    - stem_roles: mapping -> Ten-God role for each pillar's stem relative to the day stem
    """

def search_solar_by_bazi(year_pillar: str, month_pillar: str, day_pillar: str, time_pillar: str, start_year: int, end_year: int) -> List[str]:
    """
    Finds Gregorian datetimes (ISO 8601, UTC+8) whose BaZi pillars match the provided ones within inclusive year bounds.
    Results are sorted ascending.
    """

Dependencies { .dependencies }

lunar_python { .dependency }

Provides lunar/solar conversion, Eight Characters, NaYin, and reverse BaZi search capabilities.