Daily Auspiciousness Advisory

Provides directional deities, clash warnings, and activity guidance for a given solar date/time using traditional almanac data.

Capabilities

Directional Guardians

• For a solar date (e.g., 2023-04-11), returns Tai Sui direction/description and grouped Joy, Noble (yang/yin), Fortune, and Wealth deity directions for that day. @test

Clash Warnings

• Reports the day's clash target (stem-branch and zodiac) and harmful Sha direction for the provided moment. @test

Activity Guidance

• Lists auspicious (yi) and inauspicious (ji) activities for the day, and when a time is supplied includes time-specific yi/ji entries. @test

Implementation

@generates

API

from datetime import date, time
from typing import Optional, Dict, List, Any

def build_auspiciousness(solar_date: date, moment: Optional[time] = None) -> Dict[str, Any]:
    """
    Builds auspiciousness guidance for a solar date and optional time of day.

    Args:
        solar_date: Gregorian date to evaluate.
        moment: Optional time-of-day for time-specific recommendations.

    Returns:
        A dictionary with:
        - 'tai_sui': {'direction': str, 'description': str}
        - 'deities': {'joy': str, 'yang_gui': str, 'yin_gui': str, 'fortune': str, 'wealth': str}
        - 'conflict': {'target': str, 'zodiac': str, 'sha': str}
        - 'activities': {'yi': List[str], 'ji': List[str], 'time_yi': List[str], 'time_ji': List[str]}
    """
    ...

Dependencies { .dependencies }

lunar_python { .dependency }

Chinese lunar calendar library providing deity directions, clash info, and almanac activity lookups.