kundali-chart-mcp 0.2.1

package/python/kundali_lib/vedic/muhurta.py

@@ -0,0 +1,414 @@
+"""Muhurta: auspicious timing selection using Panchanga and planetary conditions."""
+
+import math
+from datetime import datetime, timedelta, timezone
+
+import swisseph as swe
+
+from kundali_lib.vedic.panchanga import get_panchanga
+
+# ---------------------------------------------------------------------------
+# Scoring tables
+# ---------------------------------------------------------------------------
+
+# Tithi numbers considered auspicious / inauspicious (1-indexed, 30-tithi cycle)
+AUSPICIOUS_TITHIS = {2, 3, 5, 7, 10, 11, 13}
+INAUSPICIOUS_TITHIS = {4, 8, 9, 12, 14, 30}
+
+VARA_SCORES: dict[str, dict[str, float]] = {
+    "marriage": {
+        "Sunday": 6,
+        "Monday": 10,
+        "Tuesday": 2,
+        "Wednesday": 8,
+        "Thursday": 10,
+        "Friday": 10,
+        "Saturday": 4,
+    },
+    "business": {
+        "Sunday": 8,
+        "Monday": 6,
+        "Tuesday": 4,
+        "Wednesday": 10,
+        "Thursday": 10,
+        "Friday": 8,
+        "Saturday": 2,
+    },
+    "travel": {
+        "Sunday": 8,
+        "Monday": 8,
+        "Tuesday": 4,
+        "Wednesday": 10,
+        "Thursday": 8,
+        "Friday": 6,
+        "Saturday": 2,
+    },
+    "housewarming": {
+        "Sunday": 6,
+        "Monday": 10,
+        "Tuesday": 2,
+        "Wednesday": 8,
+        "Thursday": 10,
+        "Friday": 8,
+        "Saturday": 4,
+    },
+    "education": {
+        "Sunday": 6,
+        "Monday": 8,
+        "Tuesday": 4,
+        "Wednesday": 10,
+        "Thursday": 10,
+        "Friday": 6,
+        "Saturday": 4,
+    },
+    "general": {
+        "Sunday": 6,
+        "Monday": 8,
+        "Tuesday": 4,
+        "Wednesday": 10,
+        "Thursday": 10,
+        "Friday": 8,
+        "Saturday": 4,
+    },
+}
+
+NAKSHATRA_NATURE: dict[str, str] = {
+    "Ashwini": "Fixed",
+    "Bharani": "Fierce",
+    "Krittika": "Mixed",
+    "Rohini": "Fixed",
+    "Mrigashira": "Soft",
+    "Ardra": "Fierce",
+    "Punarvasu": "Movable",
+    "Pushya": "Fixed",
+    "Ashlesha": "Fierce",
+    "Magha": "Fierce",
+    "Purva Phalguni": "Fierce",
+    "Uttara Phalguni": "Fixed",
+    "Hasta": "Movable",
+    "Chitra": "Soft",
+    "Swati": "Movable",
+    "Vishakha": "Mixed",
+    "Anuradha": "Soft",
+    "Jyeshtha": "Fierce",
+    "Mula": "Fierce",
+    "Purva Ashadha": "Fierce",
+    "Uttara Ashadha": "Fixed",
+    "Shravana": "Movable",
+    "Dhanishta": "Movable",
+    "Shatabhisha": "Movable",
+    "Purva Bhadrapada": "Fierce",
+    "Uttara Bhadrapada": "Fixed",
+    "Revati": "Soft",
+}
+
+# Best nakshatra natures per event type
+_NAKSHATRA_BEST: dict[str, list[str]] = {
+    "marriage": ["Fixed", "Soft"],
+    "business": ["Fixed", "Movable"],
+    "travel": ["Movable"],
+    "housewarming": ["Fixed"],
+    "education": ["Fixed", "Soft", "Movable"],
+    "general": ["Fixed", "Soft", "Movable"],
+}
+
+# Inauspicious Yoga names (to be avoided)
+INAUSPICIOUS_YOGAS = {
+    "Vishkumbha",
+    "Atiganda",
+    "Shoola",
+    "Ganda",
+    "Vyaghata",
+    "Vajra",
+    "Vyatipata",
+    "Parigha",
+    "Vaidhriti",
+}
+
+# Auspicious movable Karanas
+AUSPICIOUS_KARANAS = {"Bava", "Balava", "Kaulava", "Taitila", "Garija", "Vanija"}
+INAUSPICIOUS_KARANAS = {"Vishti"}  # Bhadra Karana
+
+# Scoring weights (sum = 1.0)
+WEIGHTS = {
+    "nakshatra": 0.30,
+    "vara": 0.25,
+    "tithi": 0.25,
+    "yoga": 0.10,
+    "karana": 0.10,
+}
+
+# Ayanamsa constant for sidereal computation
+_AYANAMSA_MODE = swe.SIDM_LAHIRI
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _score_tithi(
+    tithi_number: int, event_type: str
+) -> tuple[float, list[str], list[str]]:
+    """Return (score 0-10, auspicious_factors, inauspicious_factors)."""
+    auspicious: list[str] = []
+    inauspicious: list[str] = []
+    if tithi_number in AUSPICIOUS_TITHIS:
+        auspicious.append(f"Tithi {tithi_number} is auspicious for most events.")
+        score = 9.0
+    elif tithi_number in INAUSPICIOUS_TITHIS:
+        inauspicious.append(
+            f"Tithi {tithi_number} is inauspicious — avoid for {event_type}."
+        )
+        score = 2.0
+    else:
+        score = 6.0  # neutral
+    return score, auspicious, inauspicious
+
+
+def _score_vara(vara_name: str, event_type: str) -> tuple[float, list[str], list[str]]:
+    """Return (score 0-10, auspicious_factors, inauspicious_factors)."""
+    auspicious: list[str] = []
+    inauspicious: list[str] = []
+    table = VARA_SCORES.get(event_type, VARA_SCORES["general"])
+    raw = table.get(vara_name, 5)
+    if raw >= 8:
+        auspicious.append(f"{vara_name} is a favorable day for {event_type}.")
+    elif raw <= 4:
+        inauspicious.append(f"{vara_name} is not recommended for {event_type}.")
+    return float(raw), auspicious, inauspicious
+
+
+def _score_nakshatra(
+    nakshatra_name: str, event_type: str
+) -> tuple[float, list[str], list[str]]:
+    """Return (score 0-10, auspicious_factors, inauspicious_factors)."""
+    auspicious: list[str] = []
+    inauspicious: list[str] = []
+    nature = NAKSHATRA_NATURE.get(nakshatra_name, "Mixed")
+    best = _NAKSHATRA_BEST.get(event_type, ["Fixed", "Soft", "Movable"])
+    if nature == "Fierce":
+        inauspicious.append(
+            f"{nakshatra_name} (Fierce nakshatra) should be avoided for {event_type}."
+        )
+        score = 2.0
+    elif nature in best:
+        auspicious.append(
+            f"{nakshatra_name} ({nature} nakshatra) is well-suited for {event_type}."
+        )
+        score = 9.0
+    else:
+        score = 6.0
+    return score, auspicious, inauspicious
+
+
+def _score_yoga(yoga_name: str) -> tuple[float, list[str], list[str]]:
+    """Return (score 0-10, auspicious_factors, inauspicious_factors)."""
+    auspicious: list[str] = []
+    inauspicious: list[str] = []
+    if yoga_name in INAUSPICIOUS_YOGAS:
+        inauspicious.append(
+            f"{yoga_name} yoga is inauspicious — avoid important events."
+        )
+        score = 1.0
+    else:
+        auspicious.append(f"{yoga_name} yoga is auspicious.")
+        score = 8.0
+    return score, auspicious, inauspicious
+
+
+def _score_karana(karana_name: str) -> tuple[float, list[str], list[str]]:
+    """Return (score 0-10, auspicious_factors, inauspicious_factors)."""
+    auspicious: list[str] = []
+    inauspicious: list[str] = []
+    if karana_name in AUSPICIOUS_KARANAS:
+        auspicious.append(f"{karana_name} karana is auspicious.")
+        score = 9.0
+    elif karana_name in INAUSPICIOUS_KARANAS:
+        inauspicious.append(
+            f"{karana_name} (Bhadra/Vishti) karana — avoid auspicious events."
+        )
+        score = 1.0
+    else:
+        score = 5.0
+    return score, auspicious, inauspicious
+
+
+def _grade(score: float) -> str:
+    if score >= 80:
+        return "Excellent"
+    if score >= 60:
+        return "Good"
+    if score >= 40:
+        return "Average"
+    return "Avoid"
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def get_muhurta_score(
+    panchanga: dict,
+    planetary_positions: list,
+    event_type: str,
+) -> dict:
+    """
+    Score a given Panchanga moment for a specific type of event.
+
+    Parameters
+    ----------
+    panchanga : dict
+        Output of ``get_panchanga()``.
+    planetary_positions : list
+        Planet dicts from ``build_chart()`` (used for future planetary
+        condition checks; reserved for extensibility).
+    event_type : str
+        One of: "marriage", "business", "travel", "housewarming",
+        "education", "general".
+
+    Returns
+    -------
+    dict
+        Detailed scores, grade, and recommendation.
+    """
+    if event_type not in VARA_SCORES:
+        event_type = "general"
+
+    tithi_num = panchanga["tithi"]["number"]
+    vara_name = panchanga["vara"]["name"]
+    nak_name = panchanga["nakshatra"]["name"]
+    yoga_name = panchanga["yoga"]["name"]
+    kar_name = panchanga["karana"]["name"]
+
+    t_score, t_aus, t_in = _score_tithi(tithi_num, event_type)
+    v_score, v_aus, v_in = _score_vara(vara_name, event_type)
+    n_score, n_aus, n_in = _score_nakshatra(nak_name, event_type)
+    y_score, y_aus, y_in = _score_yoga(yoga_name)
+    k_score, k_aus, k_in = _score_karana(kar_name)
+
+    # Weighted overall score (each component is 0-10; normalise to 0-100)
+    overall = (
+        n_score * WEIGHTS["nakshatra"]
+        + v_score * WEIGHTS["vara"]
+        + t_score * WEIGHTS["tithi"]
+        + y_score * WEIGHTS["yoga"]
+        + k_score * WEIGHTS["karana"]
+    ) * 10.0  # scale 0-10 → 0-100
+
+    overall = round(min(100.0, max(0.0, overall)), 2)
+    grade = _grade(overall)
+
+    auspicious_factors = t_aus + v_aus + n_aus + y_aus + k_aus
+    inauspicious_factors = t_in + v_in + n_in + y_in + k_in
+
+    if grade in ("Excellent", "Good"):
+        rec = (
+            f"This is a {grade.lower()} time for {event_type}. "
+            f"{nak_name} nakshatra on {vara_name} during Tithi {tithi_num} "
+            f"under {yoga_name} yoga is supportive."
+        )
+    elif grade == "Average":
+        rec = (
+            f"This time is average for {event_type}. Proceed with awareness of "
+            f"the inauspicious factors: {'; '.join(inauspicious_factors) if inauspicious_factors else 'none critical'}."
+        )
+    else:
+        rec = (
+            f"Avoid scheduling {event_type} at this time. "
+            f"Key concerns: {'; '.join(inauspicious_factors) if inauspicious_factors else 'multiple weak factors'}."
+        )
+
+    return {
+        "event_type": event_type,
+        "overall_score": overall,
+        "grade": grade,
+        "tithi_score": round(t_score * 10, 2),
+        "vara_score": round(v_score * 10, 2),
+        "nakshatra_score": round(n_score * 10, 2),
+        "yoga_score": round(y_score * 10, 2),
+        "karana_score": round(k_score * 10, 2),
+        "auspicious_factors": auspicious_factors,
+        "inauspicious_factors": inauspicious_factors,
+        "recommendation": rec,
+    }
+
+
+def get_best_muhurta_in_range(
+    start_dt: datetime,
+    end_dt: datetime,
+    location_lat: float,
+    location_lon: float,
+    event_type: str,
+) -> list:
+    """
+    Scan every hour between start_dt and end_dt and return the top-5
+    most auspicious windows for the given event type.
+
+    Parameters
+    ----------
+    start_dt : datetime
+        Range start (timezone-aware or naive UTC).
+    end_dt : datetime
+        Range end (timezone-aware or naive UTC).
+    location_lat : float
+        Geographic latitude (degrees).
+    location_lon : float
+        Geographic longitude (degrees).
+    event_type : str
+        One of the supported event types.
+
+    Returns
+    -------
+    list
+        Up to 5 dicts, each with datetime (ISO), score, grade,
+        tithi, nakshatra, vara, and yoga.
+    """
+    # Ensure datetimes are UTC-aware
+    if start_dt.tzinfo is None:
+        start_dt = start_dt.replace(tzinfo=timezone.utc)
+    if end_dt.tzinfo is None:
+        end_dt = end_dt.replace(tzinfo=timezone.utc)
+
+    swe.set_sid_mode(_AYANAMSA_MODE)
+
+    candidates: list[dict] = []
+    current = start_dt
+
+    while current <= end_dt:
+        # Convert to Julian Day (UT)
+        h = current.hour + current.minute / 60.0 + current.second / 3600.0
+        jd = swe.julday(current.year, current.month, current.day, h)
+
+        try:
+            # Sun sidereal longitude
+            sun_flags = swe.FLG_SIDEREAL | swe.FLG_SPEED
+            sun_result = swe.calc_ut(jd, swe.SUN, sun_flags)
+            sun_lon = sun_result[0][0] % 360
+
+            # Moon sidereal longitude
+            moon_result = swe.calc_ut(jd, swe.MOON, sun_flags)
+            moon_lon = moon_result[0][0] % 360
+
+            panchanga = get_panchanga(sun_lon, moon_lon, jd)
+            score_data = get_muhurta_score(panchanga, [], event_type)
+
+            candidates.append(
+                {
+                    "datetime": current.isoformat(),
+                    "score": score_data["overall_score"],
+                    "grade": score_data["grade"],
+                    "tithi": panchanga["tithi"]["name"],
+                    "nakshatra": panchanga["nakshatra"]["name"],
+                    "vara": panchanga["vara"]["name"],
+                    "yoga": panchanga["yoga"]["name"],
+                }
+            )
+        except Exception:
+            pass  # skip hours where ephemeris data is unavailable
+
+        current += timedelta(hours=1)
+
+    # Sort descending by score, return top 5
+    candidates.sort(key=lambda x: x["score"], reverse=True)
+    return candidates[:5]