kundali-chart-mcp 0.2.1

package/python/kundali_lib/vedic/lunar_return.py

@@ -0,0 +1,402 @@
+"""Lunar Return (Chandraphal) and Prasna (Horary) charts."""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta
+
+import pytz
+import swisseph as swe
+
+from kundali_lib.vedic.chart import _jd_ut, build_chart
+from kundali_lib.vedic.constants import RASHI_LORDS, RASHIS
+from kundali_lib.vedic.zodiac import get_rashi
+
+# ---------------------------------------------------------------------------
+# Reference data
+# ---------------------------------------------------------------------------
+
+RASHI_LORDS_MAP: dict[str, str] = {r: RASHI_LORDS[i] for i, r in enumerate(RASHIS)}
+
+_SIDEREAL_FLAGS = swe.FLG_SWIEPH | swe.FLG_SIDEREAL
+
+# Approximate days per sidereal month — used to bound the search window.
+_SIDEREAL_MONTH_DAYS = 27.3217
+
+# Moon returns every ~27.3 days; we search up to 32 days ahead from start.
+_SEARCH_DAYS = 32
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _moon_longitude_at_jd(jd: float) -> float:
+    """Sidereal (Lahiri) Moon longitude for a given Julian Day."""
+    swe.set_ephe_path(None)
+    swe.set_sid_mode(swe.SIDM_LAHIRI)
+    xx, _ = swe.calc_ut(jd, swe.MOON, swe.FLG_SWIEPH | swe.FLG_SIDEREAL)
+    return xx[0]
+
+
+def _angular_diff(a: float, b: float) -> float:
+    """Signed difference (a − b) normalised to [−180, 180]."""
+    diff = (a - b) % 360.0
+    if diff > 180.0:
+        diff -= 360.0
+    return diff
+
+
+def _jd_to_utc_datetime(jd: float) -> datetime:
+    """Convert a Julian Day number to a UTC-aware datetime."""
+    year, month, day, hour_frac = swe.revjul(jd, 1)
+    hour = int(hour_frac)
+    minute_frac = (hour_frac - hour) * 60.0
+    minute = int(minute_frac)
+    second_frac = (minute_frac - minute) * 60.0
+    second = min(int(round(second_frac)), 59)
+    return datetime(
+        int(year), int(month), int(day), hour, minute, second, tzinfo=pytz.UTC
+    )
+
+
+def _find_lunar_return(natal_moon_lon: float, start_jd: float) -> float:
+    """Return the JD when the sidereal Moon longitude next equals natal_moon_lon.
+
+    Strategy:
+    1. Coarse scan every 6 hours until a zero-crossing is detected.
+    2. Binary-search the bracketed interval to sub-second precision.
+    """
+    step = 0.25  # 6-hour steps
+    prev_diff = _angular_diff(_moon_longitude_at_jd(start_jd), natal_moon_lon)
+    lo_jd: float | None = None
+    hi_jd: float | None = None
+
+    for i in range(1, int(_SEARCH_DAYS / step) + 2):
+        jd = start_jd + i * step
+        curr_diff = _angular_diff(_moon_longitude_at_jd(jd), natal_moon_lon)
+
+        if abs(curr_diff) < 0.0001:
+            return jd  # landed almost exactly on crossing
+
+        # Moon moves ~0.55°/6h forward; look for negative→positive zero-crossing.
+        if prev_diff < 0.0 and curr_diff >= 0.0:
+            lo_jd = jd - step
+            hi_jd = jd
+            break
+
+        prev_diff = curr_diff
+
+    if lo_jd is None or hi_jd is None:
+        # Fallback: return the point with smallest absolute difference
+        return start_jd
+
+    # Binary search — 60 iterations → microsecond-level precision
+    for _ in range(60):
+        mid = (lo_jd + hi_jd) / 2.0
+        diff = _angular_diff(_moon_longitude_at_jd(mid), natal_moon_lon)
+        if abs(diff) < 0.0001:
+            return mid
+        if diff < 0.0:
+            lo_jd = mid
+        else:
+            hi_jd = mid
+
+    return (lo_jd + hi_jd) / 2.0
+
+
+def _get_planet(positions: list[dict], name: str) -> dict | None:
+    for p in positions:
+        if p["name"] == name:
+            return p
+    return None
+
+
+def _house_of_sign(sign: str, asc_sign: str) -> int:
+    asc_idx = RASHIS.index(asc_sign)
+    sign_idx = RASHIS.index(sign)
+    return (sign_idx - asc_idx) % 12 + 1
+
+
+# ---------------------------------------------------------------------------
+# Lunar Return month-theme interpreter
+# ---------------------------------------------------------------------------
+
+_LAGNA_THEMES: dict[str, str] = {
+    "Aries": "Action, initiation, and personal identity take centre stage.",
+    "Taurus": "Finances, stability, and material comfort are emphasised.",
+    "Gemini": "Communication, learning, and short journeys are prominent.",
+    "Cancer": "Home, emotions, and family matters dominate the month.",
+    "Leo": "Creativity, confidence, and self-expression are highlighted.",
+    "Virgo": "Health, work routines, and analytical thinking are in focus.",
+    "Libra": "Relationships, balance, and negotiations are key themes.",
+    "Scorpio": "Transformation, depth, and hidden matters come to the fore.",
+    "Sagittarius": "Philosophy, travel, and expansion of horizons are active.",
+    "Capricorn": "Career ambitions, discipline, and long-term goals dominate.",
+    "Aquarius": "Social networks, innovation, and humanitarian goals are active.",
+    "Pisces": "Spirituality, imagination, and introspection colour the month.",
+}
+
+
+def _month_theme(lr_asc_sign: str, moon_house: int) -> str:
+    base = _LAGNA_THEMES.get(lr_asc_sign, "A month of reflection and adjustment.")
+    moon_note = f" Moon in house {moon_house} brings focus to "
+    house_keywords = {
+        1: "the self and body",
+        2: "finances and family",
+        3: "communication and siblings",
+        4: "home and mother",
+        5: "creativity and children",
+        6: "health and service",
+        7: "relationships and partners",
+        8: "transformation and shared resources",
+        9: "luck, belief, and long journeys",
+        10: "career and public image",
+        11: "gains and social circles",
+        12: "solitude, losses, and spirituality",
+    }
+    moon_note += house_keywords.get(moon_house, "general matters") + "."
+    return base + moon_note
+
+
+# ---------------------------------------------------------------------------
+# Public API — Lunar Return
+# ---------------------------------------------------------------------------
+
+
+def get_lunar_return(
+    birth_chart: dict,
+    birth_dt: datetime,
+    target_year: int,
+    target_month: int,
+    query_lat: float,
+    query_lon: float,
+    query_timezone: str,
+) -> dict:
+    """Calculate the Lunar Return (Chandraphal) chart for a given month.
+
+    Args:
+        birth_chart:    Output of ``build_chart()`` for the native's birth.
+        birth_dt:       Native's local birth datetime (naive or aware).
+        target_year:    Calendar year of the desired Lunar Return.
+        target_month:   Calendar month (1-12) of the desired Lunar Return.
+        query_lat:      Latitude for the Lunar Return chart.
+        query_lon:      Longitude for the Lunar Return chart.
+        query_timezone: IANA timezone string for the query location.
+
+    Returns:
+        dict with Lunar Return timing, chart, and key highlights.
+    """
+    swe.set_ephe_path(None)
+    swe.set_sid_mode(swe.SIDM_LAHIRI)
+
+    # ── Natal Moon longitude ──────────────────────────────────────────────────
+    birth_timezone = birth_chart.get("birth_details", {}).get("timezone", "UTC")
+    birth_jd = _jd_ut(birth_dt, birth_timezone)
+    xx, _ = swe.calc_ut(birth_jd, swe.MOON, _SIDEREAL_FLAGS)
+    natal_moon_lon: float = xx[0]
+    natal_moon_rashi = get_rashi(natal_moon_lon)
+
+    # ── Search start: 1st of target month ────────────────────────────────────
+    start_jd = swe.julday(target_year, target_month, 1, 0.0)
+
+    # ── Find the Lunar Return JD ──────────────────────────────────────────────
+    lr_jd = _find_lunar_return(natal_moon_lon, start_jd)
+
+    # ── Convert to datetimes ──────────────────────────────────────────────────
+    lr_utc = _jd_to_utc_datetime(lr_jd)
+    query_tz = pytz.timezone(query_timezone)
+    lr_local_aware = lr_utc.astimezone(query_tz)
+    lr_local_naive = lr_local_aware.replace(tzinfo=None)
+
+    # ── Next Lunar Return JD (for days_until_next_return) ────────────────────
+    next_lr_jd = _find_lunar_return(natal_moon_lon, lr_jd + 1.0)
+    days_until_next = round(next_lr_jd - lr_jd, 2)
+
+    # ── Build Lunar Return chart ──────────────────────────────────────────────
+    lr_chart = build_chart(
+        name="Lunar Return",
+        birth_dt=lr_local_naive,
+        lat=query_lat,
+        lon=query_lon,
+        timezone=query_timezone,
+    )
+
+    # ── Key highlights ────────────────────────────────────────────────────────
+    lr_asc_sign = lr_chart["ascendant"]["rashi"]
+    moon_planet = _get_planet(lr_chart["planetary_positions"], "Moon")
+    moon_house_lr = moon_planet.get("house", 0) if moon_planet else 0
+
+    return {
+        "target_year": target_year,
+        "target_month": target_month,
+        "natal_moon_longitude": round(natal_moon_lon, 4),
+        "natal_moon_rashi": natal_moon_rashi,
+        "lunar_return_datetime_utc": lr_utc.isoformat(),
+        "lunar_return_datetime_local": lr_local_aware.isoformat(),
+        "days_until_next_return": days_until_next,
+        "lunar_return_chart": {
+            "planetary_positions": lr_chart["planetary_positions"],
+            "houses": lr_chart["houses"],
+            "ascendant": lr_chart["ascendant"],
+            "moon_sign": lr_chart["moon_sign"],
+            "sun_sign": lr_chart["sun_sign"],
+        },
+        "key_highlights": {
+            "lunar_return_ascendant": lr_asc_sign,
+            "month_theme": _month_theme(lr_asc_sign, moon_house_lr),
+        },
+    }
+
+
+# ---------------------------------------------------------------------------
+# Public API — Prasna (Horary)
+# ---------------------------------------------------------------------------
+
+
+def get_prasna_chart(
+    query_dt_utc: datetime,
+    query_lat: float,
+    query_lon: float,
+    question: str = "",
+) -> dict:
+    """Calculate a Prasna (Horary) chart for the moment a question is asked.
+
+    Args:
+        query_dt_utc: UTC-aware datetime of the question moment.
+        query_lat:    Geographic latitude of the querent.
+        query_lon:    Geographic longitude of the querent.
+        question:     The question being asked (stored verbatim).
+
+    Returns:
+        dict with the Prasna chart and key horary indicators.
+    """
+    if query_dt_utc.tzinfo is None:
+        query_dt_utc = pytz.UTC.localize(query_dt_utc)
+
+    # ── Determine local timezone from coordinates ─────────────────────────────
+    try:
+        from timezonefinder import TimezoneFinder
+
+        tf = TimezoneFinder()
+        tz_name = tf.timezone_at(lat=query_lat, lng=query_lon) or "UTC"
+    except Exception:
+        tz_name = "UTC"
+
+    local_tz = pytz.timezone(tz_name)
+    query_dt_local = query_dt_utc.astimezone(local_tz)
+    query_dt_naive = query_dt_local.replace(tzinfo=None)
+
+    # ── Build chart at question moment ────────────────────────────────────────
+    prasna_chart = build_chart(
+        name="Prasna",
+        birth_dt=query_dt_naive,
+        lat=query_lat,
+        lon=query_lon,
+        timezone=tz_name,
+    )
+
+    positions: list[dict] = prasna_chart["planetary_positions"]
+    asc_info: dict = prasna_chart["ascendant"]
+    asc_sign: str = asc_info.get("rashi", RASHIS[0])
+
+    # ── Lagna and Lagna lord ──────────────────────────────────────────────────
+    lagna_lord_name = RASHI_LORDS_MAP.get(asc_sign, "")
+    lagna_lord_planet = _get_planet(positions, lagna_lord_name)
+    lagna_lord_house = lagna_lord_planet.get("house", 0) if lagna_lord_planet else 0
+
+    # ── Moon ──────────────────────────────────────────────────────────────────
+    moon = _get_planet(positions, "Moon")
+    moon_rashi = moon.get("rashi", "") if moon else ""
+    moon_house = moon.get("house", 0) if moon else 0
+
+    # ── 7th house (the matter asked about) ───────────────────────────────────
+    asc_idx = RASHIS.index(asc_sign)
+    seventh_sign = RASHIS[(asc_idx + 6) % 12]
+    seventh_lord_name = RASHI_LORDS_MAP.get(seventh_sign, "")
+    seventh_lord_planet = _get_planet(positions, seventh_lord_name)
+    seventh_lord_house = (
+        seventh_lord_planet.get("house", 0) if seventh_lord_planet else 0
+    )
+
+    # ── Is Moon approaching Lagna lord? (Ithasala check) ─────────────────────
+    moon_approaching_ll = False
+    if moon and lagna_lord_planet:
+        moon_speed = abs(moon.get("speed_longitude", 13.2))
+        ll_speed = abs(lagna_lord_planet.get("speed_longitude", 1.0))
+        if moon_speed > ll_speed:
+            diff = _angular_diff(lagna_lord_planet["longitude"], moon["longitude"])
+            moon_approaching_ll = 0 < diff <= 13
+
+    # ── Favourable and unfavourable indicators ────────────────────────────────
+    favourable: list[str] = []
+    unfavourable: list[str] = []
+
+    if moon_approaching_ll:
+        favourable.append(
+            "Moon approaching Lagna lord — positive indication for the matter"
+        )
+
+    if lagna_lord_house in {1, 4, 7, 10}:
+        favourable.append(f"Lagna lord in angular house {lagna_lord_house} — strong")
+    elif lagna_lord_house in {6, 8, 12}:
+        unfavourable.append(
+            f"Lagna lord in dusthana (house {lagna_lord_house}) — weakened"
+        )
+
+    if seventh_lord_house in {1, 4, 7, 10}:
+        favourable.append(
+            f"7th lord in angular house {seventh_lord_house} — matter is active"
+        )
+    elif seventh_lord_house in {6, 8, 12}:
+        unfavourable.append(f"7th lord in dusthana — obstacles for the matter")
+
+    if moon_house in {1, 4, 7, 10}:
+        favourable.append(f"Moon in kendra (house {moon_house}) — emotional strength")
+    elif moon_house in {6, 8, 12}:
+        unfavourable.append(f"Moon in dusthana (house {moon_house}) — anxiety or delay")
+
+    jupiter = _get_planet(positions, "Jupiter")
+    if jupiter and jupiter.get("house", 0) in {1, 5, 9}:
+        favourable.append("Jupiter in trikona — divine grace supports the query")
+
+    # ── General reading ───────────────────────────────────────────────────────
+    if len(favourable) > len(unfavourable):
+        outlook = "The chart generally favours a positive outcome."
+    elif len(unfavourable) > len(favourable):
+        outlook = "The chart indicates delays or obstacles; careful action needed."
+    else:
+        outlook = "The chart shows a mixed picture; outcome depends on effort."
+
+    general_reading = (
+        f"Prasna Lagna is {asc_sign}, ruled by {lagna_lord_name} "
+        f"(in house {lagna_lord_house}). "
+        f"Moon is in {moon_rashi} (house {moon_house}). "
+        f"The 7th house (matter asked about) is {seventh_sign}, "
+        f"ruled by {seventh_lord_name} (house {seventh_lord_house}). " + outlook
+    )
+
+    return {
+        "question": question,
+        "datetime_utc": query_dt_utc.isoformat(),
+        "prasna_chart": {
+            "planetary_positions": positions,
+            "houses": prasna_chart["houses"],
+            "ascendant": asc_info,
+            "moon_sign": prasna_chart.get("moon_sign", moon_rashi),
+        },
+        "prasna_indicators": {
+            "lagna": asc_sign,
+            "lagna_lord": lagna_lord_name,
+            "lagna_lord_house": lagna_lord_house,
+            "moon_rashi": moon_rashi,
+            "moon_house": moon_house,
+            "seventh_house_sign": seventh_sign,
+            "seventh_lord": seventh_lord_name,
+            "seventh_lord_house": seventh_lord_house,
+            "moon_approaching_lagna_lord": moon_approaching_ll,
+            "favorable_indicators": favourable,
+            "unfavorable_indicators": unfavourable,
+            "general_reading": general_reading,
+        },
+    }