kundali-chart-mcp 0.2.1

package/azure-function/python/kundali_lib/vedic/gochara.py

@@ -0,0 +1,277 @@
+"""Gochara: Vedic transit analysis — how transiting planets affect natal houses."""
+
+from kundali_lib.vedic.constants import RASHIS
+
+# ---------------------------------------------------------------------------
+# Gochara effect tables (house counted FROM natal Moon sign)
+# ---------------------------------------------------------------------------
+
+GOCHARA_EFFECTS = {
+    "Sun": {"good": [3, 6, 10, 11], "bad": [1, 2, 4, 5, 7, 8, 9, 12]},
+    "Moon": {"good": [1, 3, 6, 7, 10, 11], "bad": [2, 4, 5, 8, 9, 12]},
+    "Mars": {"good": [3, 6, 11], "bad": [1, 2, 4, 5, 7, 8, 9, 10, 12]},
+    "Mercury": {"good": [2, 4, 6, 8, 10, 11], "bad": [1, 3, 5, 7, 9, 12]},
+    "Jupiter": {"good": [2, 5, 7, 9, 11], "bad": [1, 3, 4, 6, 8, 10, 12]},
+    "Venus": {"good": [1, 2, 3, 4, 5, 8, 9, 11, 12], "bad": [6, 7, 10]},
+    "Saturn": {"good": [3, 6, 11], "bad": [1, 2, 4, 5, 7, 8, 9, 10, 12]},
+    "Rahu": {"good": [3, 6, 11], "bad": [1, 2, 4, 5, 7, 8, 9, 10, 12]},
+    "Ketu": {"good": [3, 6, 11], "bad": [1, 2, 4, 5, 7, 8, 9, 10, 12]},
+}
+
+# Vedha obstruction points: {planet: {good_house: vedha_house}}
+# If a planet is in good_house AND another planet is in vedha_house → good effect cancelled.
+VEDHA_POINTS = {
+    "Sun": {3: 9, 6: 12, 10: 4, 11: 5},
+    "Moon": {1: 5, 3: 9, 6: 12, 7: 2, 10: 4, 11: 8},
+    "Mars": {3: 12, 6: 9, 11: 5},
+    "Mercury": {2: 5, 4: 3, 6: 9, 8: 1, 10: 8, 11: 12},
+    "Jupiter": {2: 12, 5: 4, 7: 3, 9: 10, 11: 8},
+    "Venus": {1: 8, 2: 7, 3: 1, 4: 10, 5: 9, 8: 5, 9: 1, 11: 8, 12: 6},
+    "Saturn": {3: 12, 6: 9, 11: 5},
+    "Rahu": {3: 12, 6: 9, 11: 5},
+    "Ketu": {3: 12, 6: 9, 11: 5},
+}
+
+# Short descriptions for each effect category
+_EFFECT_DESCRIPTIONS = {
+    "Sun": {
+        "good": "Sun in {h}th from Moon: favours authority, health, career visibility.",
+        "bad": "Sun in {h}th from Moon: ego conflicts, health strain, obstacles from officials.",
+    },
+    "Moon": {
+        "good": "Moon in {h}th from Moon: emotional harmony, public success, good relationships.",
+        "bad": "Moon in {h}th from Moon: emotional turbulence, domestic issues, mental stress.",
+    },
+    "Mars": {
+        "good": "Mars in {h}th from Moon: courage, competition success, energy channelled well.",
+        "bad": "Mars in {h}th from Moon: accidents, arguments, impulsiveness, sibling friction.",
+    },
+    "Mercury": {
+        "good": "Mercury in {h}th from Moon: business gains, sharp intellect, communication flows.",
+        "bad": "Mercury in {h}th from Moon: miscommunication, travel problems, nervous tension.",
+    },
+    "Jupiter": {
+        "good": "Jupiter in {h}th from Moon: wisdom, wealth, expansion, spiritual growth.",
+        "bad": "Jupiter in {h}th from Moon: over-expansion, false optimism, financial missteps.",
+    },
+    "Venus": {
+        "good": "Venus in {h}th from Moon: romance, artistic gains, comforts, social pleasure.",
+        "bad": "Venus in {h}th from Moon: relationship strain, extravagance, health of women.",
+    },
+    "Saturn": {
+        "good": "Saturn in {h}th from Moon: disciplined gains through hard work and perseverance.",
+        "bad": "Saturn in {h}th from Moon: delays, burdens, health issues, melancholy.",
+    },
+    "Rahu": {
+        "good": "Rahu in {h}th from Moon: unconventional gains, foreign connections, ambition.",
+        "bad": "Rahu in {h}th from Moon: confusion, deception, hidden enemies, anxiety.",
+    },
+    "Ketu": {
+        "good": "Ketu in {h}th from Moon: spiritual insight, liberation from past karma.",
+        "bad": "Ketu in {h}th from Moon: losses, separations, health issues, disconnection.",
+    },
+}
+
+
+def _house_from_moon(transit_rashi: str, moon_rashi: str) -> int:
+    """Calculate transit house number (1-12) counted from natal Moon sign."""
+    moon_i = RASHIS.index(moon_rashi)
+    transit_i = RASHIS.index(transit_rashi)
+    return (transit_i - moon_i) % 12 + 1
+
+
+def _sade_sati_info(saturn_house_from_moon: int) -> dict | None:
+    """Return Sade Sati / Kantaka Shani details if applicable."""
+    if saturn_house_from_moon == 12:
+        return {
+            "type": "Sade Sati — Rising Phase",
+            "phase": "first",
+            "description": (
+                "Saturn is in the 12th sign from natal Moon, marking the start of the 7.5-year "
+                "Sade Sati. Losses, expenses, sleep issues, and preparation for major life changes. "
+                "Foreign travel or spiritual inclinations may increase."
+            ),
+        }
+    elif saturn_house_from_moon == 1:
+        return {
+            "type": "Sade Sati — Peak Phase",
+            "phase": "second",
+            "description": (
+                "Saturn transits natal Moon sign — the most intense phase of Sade Sati. "
+                "Health, relationships, and career may all be tested simultaneously. "
+                "Strong discipline and introspection are essential. Avoid major irreversible decisions."
+            ),
+        }
+    elif saturn_house_from_moon == 2:
+        return {
+            "type": "Sade Sati — Setting Phase",
+            "phase": "third",
+            "description": (
+                "Saturn moves past the Moon sign — final phase of Sade Sati. Financial pressures "
+                "and family tensions linger. Gradual relief begins but demands continued patience."
+            ),
+        }
+    elif saturn_house_from_moon == 4:
+        return {
+            "type": "Kantaka Shani (4th house from Moon)",
+            "phase": "kantaka",
+            "description": (
+                "Saturn in 4th from natal Moon causes domestic unrest, property disputes, "
+                "mother's health concerns, and career instability. Known as Ardhashtama Shani."
+            ),
+        }
+    elif saturn_house_from_moon == 8:
+        return {
+            "type": "Kantaka Shani (8th house from Moon)",
+            "phase": "kantaka",
+            "description": (
+                "Saturn in 8th from natal Moon — Ashtama Shani. A highly challenging transit "
+                "involving chronic health issues, sudden obstacles, transformation through crisis, "
+                "and karmic reckoning. Requires patience and surrender."
+            ),
+        }
+    return None
+
+
+def get_gochara(natal_chart: dict, transit_positions: list) -> dict:
+    """Analyse Gochara (transit) effects of current planets on the natal chart.
+
+    Args:
+        natal_chart:        Output of ``build_chart()``. Must contain ``moon_sign``
+                            and ``planetary_positions``.
+        transit_positions:  List of current planet position dicts (same shape as
+                            ``planetary_positions`` entries in a built chart).
+
+    Returns:
+        A dict with ``natal_moon_rashi``, ``transit_analysis`` (per planet),
+        ``overall_period``, and optional ``special_conditions``.
+    """
+    moon_rashi: str = natal_chart["moon_sign"]
+
+    # Build quick lookup: {planet_name: house_from_moon} for Vedha checks
+    transit_house_map: dict[str, int] = {}
+    transit_rashi_map: dict[str, str] = {}
+    for tp in transit_positions:
+        name = tp["name"]
+        rashi = tp["rashi"]
+        transit_rashi_map[name] = rashi
+        transit_house_map[name] = _house_from_moon(rashi, moon_rashi)
+
+    transit_analysis: dict[str, dict] = {}
+    benefic_count = 0
+    malefic_count = 0
+    special_conditions: list[dict] = []
+
+    for tp in transit_positions:
+        planet = tp["name"]
+        if planet not in GOCHARA_EFFECTS:
+            continue
+
+        house = transit_house_map[planet]
+        effects = GOCHARA_EFFECTS[planet]
+
+        if house in effects["good"]:
+            base_effect = "Beneficial"
+        elif house in effects["bad"]:
+            base_effect = "Harmful"
+        else:
+            base_effect = "Neutral"
+
+        # --- Vedha check ---
+        vedha_present = False
+        vedha_planet_name = None
+        if base_effect == "Beneficial" and planet in VEDHA_POINTS:
+            vedha_house = VEDHA_POINTS[planet].get(house)
+            if vedha_house is not None:
+                for other_planet, other_house in transit_house_map.items():
+                    if other_planet != planet and other_house == vedha_house:
+                        vedha_present = True
+                        vedha_planet_name = other_planet
+                        break
+
+        if vedha_present:
+            final_effect = "Cancelled"
+        else:
+            final_effect = base_effect
+
+        # Build description
+        desc_tmpl = _EFFECT_DESCRIPTIONS.get(planet, {})
+        key = "good" if base_effect == "Beneficial" else "bad"
+        description = desc_tmpl.get(key, f"{planet} in {house}th from Moon.").format(
+            h=house
+        )
+        if vedha_present:
+            description += (
+                f" However, {vedha_planet_name} in the Vedha house ({VEDHA_POINTS[planet][house]}th) "
+                "cancels this good effect."
+            )
+
+        transit_analysis[planet] = {
+            "transit_rashi": transit_rashi_map[planet],
+            "house_from_moon": house,
+            "effect": base_effect,
+            "vedha_present": vedha_present,
+            "vedha_planet": vedha_planet_name,
+            "final_effect": final_effect,
+            "description": description,
+        }
+
+        if final_effect == "Beneficial":
+            benefic_count += 1
+        elif final_effect in ("Harmful", "Cancelled"):
+            malefic_count += 1
+
+        # Saturn special conditions
+        if planet == "Saturn":
+            sade_sati = _sade_sati_info(house)
+            if sade_sati:
+                special_conditions.append(sade_sati)
+
+    # Overall summary
+    total = benefic_count + malefic_count
+    if total == 0:
+        summary = "No significant Gochara data available."
+        recommendation = "Proceed with caution and mindfulness."
+    elif benefic_count > malefic_count:
+        summary = (
+            f"Predominantly favourable transit period with {benefic_count} benefic "
+            f"and {malefic_count} malefic planetary influences."
+        )
+        recommendation = (
+            "Good time to initiate new ventures, make important decisions, and strengthen "
+            "relationships. Leverage benefic planetary support."
+        )
+    elif malefic_count > benefic_count:
+        summary = (
+            f"Challenging transit period with {malefic_count} malefic "
+            f"and {benefic_count} benefic planetary influences."
+        )
+        recommendation = (
+            "Exercise caution, avoid major irreversible decisions, focus on health and "
+            "consolidation. Perform recommended remedies."
+        )
+    else:
+        summary = (
+            f"Mixed transit period — {benefic_count} benefic and {malefic_count} malefic "
+            "influences balance each other."
+        )
+        recommendation = (
+            "Proceed carefully. Balance opportunities with risks; seek guidance before "
+            "major commitments."
+        )
+
+    result: dict = {
+        "natal_moon_rashi": moon_rashi,
+        "transit_analysis": transit_analysis,
+        "overall_period": {
+            "benefic_count": benefic_count,
+            "malefic_count": malefic_count,
+            "summary": summary,
+            "recommendation": recommendation,
+        },
+    }
+
+    if special_conditions:
+        result["special_conditions"] = special_conditions
+
+    return result

package/azure-function/python/kundali_lib/vedic/hora.py

@@ -0,0 +1,263 @@
+"""Hora: Planetary hours — each hour of the day/night ruled by a planet."""
+
+from datetime import datetime, timedelta, timezone
+
+import swisseph as swe
+
+# ---------------------------------------------------------------------------
+# Chaldean order and weekday mappings
+# ---------------------------------------------------------------------------
+
+CHALDEAN_ORDER = ["Saturn", "Jupiter", "Mars", "Sun", "Venus", "Mercury", "Moon"]
+
+# Index into CHALDEAN_ORDER for the first (day-break) hour of each weekday.
+# weekday() returns 0=Monday … 6=Sunday (Python convention).
+WEEKDAY_FIRST_HOUR: dict[int, int] = {
+    6: 3,  # Sunday → Sun   (index 3)
+    0: 6,  # Monday → Moon  (index 6)
+    1: 2,  # Tuesday → Mars (index 2)
+    2: 5,  # Wednesday → Mercury (index 5)
+    3: 1,  # Thursday → Jupiter (index 1)
+    4: 4,  # Friday → Venus (index 4)
+    5: 0,  # Saturday → Saturn (index 0)
+}
+
+WEEKDAY_NAMES = [
+    "Monday",
+    "Tuesday",
+    "Wednesday",
+    "Thursday",
+    "Friday",
+    "Saturday",
+    "Sunday",
+]
+
+HORA_SIGNIFICANCE: dict[str, str] = {
+    "Sun": "Leadership, government work, father, authority, health",
+    "Moon": "Travel, dealing with public, women, emotions, water matters",
+    "Mars": "Surgery, arguments, sports, enemies, property, courage",
+    "Mercury": "Communication, business, writing, learning, trade",
+    "Jupiter": "Religious work, education, wealth, children, law, spirituality",
+    "Venus": "Love, marriage, arts, luxury, entertainment, beauty",
+    "Saturn": "Hard labor, construction, agriculture, service, old people",
+}
+
+
+# ---------------------------------------------------------------------------
+# Sunrise / Sunset helpers
+# ---------------------------------------------------------------------------
+
+
+def _jd_from_utc(dt: datetime) -> float:
+    """Convert a UTC-aware (or naive-UTC) datetime to Julian Day."""
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    h = dt.hour + dt.minute / 60.0 + dt.second / 3600.0
+    return swe.julday(dt.year, dt.month, dt.day, h)
+
+
+def _get_sunrise_sunset(
+    dt_utc: datetime, lat: float, lon: float
+) -> tuple[float, float]:
+    """Return (sunrise_jd, sunset_jd) for the calendar day of dt_utc at (lat, lon).
+
+    Uses ``swe.rise_trans``.  Falls back to 06:00 / 18:00 local solar noon
+    approximation if the call fails (e.g. extreme latitudes or ephemeris
+    data unavailable).
+    """
+    jd_noon = _jd_from_utc(dt_utc.replace(hour=12, minute=0, second=0, microsecond=0))
+    geopos = (lon, lat, 0.0)  # (longitude, latitude, altitude) – swe convention
+    ephe_flag = swe.FLG_SWIEPH
+
+    try:
+        # Sunrise
+        ret_rise, tret_rise = swe.rise_trans(
+            jd_noon - 0.5, swe.SUN, "", ephe_flag, swe.CALC_RISE, geopos, 0.0, 0.0
+        )
+        sunrise_jd = tret_rise[0]
+
+        # Sunset – search forward from sunrise
+        ret_set, tret_set = swe.rise_trans(
+            sunrise_jd, swe.SUN, "", ephe_flag, swe.CALC_SET, geopos, 0.0, 0.0
+        )
+        sunset_jd = tret_set[0]
+
+        if sunrise_jd < sunset_jd:
+            return sunrise_jd, sunset_jd
+    except Exception:
+        pass
+
+    # Fallback: approximate as 06:00 and 18:00 UTC (naive, ignore timezone)
+    approx_rise = dt_utc.replace(hour=6, minute=0, second=0, microsecond=0)
+    approx_set = dt_utc.replace(hour=18, minute=0, second=0, microsecond=0)
+    return _jd_from_utc(approx_rise), _jd_from_utc(approx_set)
+
+
+def _jd_to_utc(jd: float) -> datetime:
+    """Convert a Julian Day number back to a UTC datetime."""
+    y, m, d, h_frac = swe.revjul(jd)
+    hours = int(h_frac)
+    rem = (h_frac - hours) * 60.0
+    minutes = int(rem)
+    seconds = int((rem - minutes) * 60.0)
+    return datetime(y, m, d, hours, minutes, seconds, tzinfo=timezone.utc)
+
+
+def _next_sunrise(sunset_jd: float, lat: float, lon: float) -> float:
+    """Return the JD of the next sunrise after sunset_jd."""
+    geopos = (lon, lat, 0.0)
+    try:
+        _, tret = swe.rise_trans(
+            sunset_jd, swe.SUN, "", swe.FLG_SWIEPH, swe.CALC_RISE, geopos, 0.0, 0.0
+        )
+        return tret[0]
+    except Exception:
+        return sunset_jd + 0.5  # +12 hours as fallback
+
+
+# ---------------------------------------------------------------------------
+# Hour-slot builders
+# ---------------------------------------------------------------------------
+
+
+def _build_hour_slots(
+    period_start_jd: float,
+    period_end_jd: float,
+    first_planet_index: int,
+    slot_offset: int,
+) -> list[dict]:
+    """Divide a period into 12 equal planetary hours and return slot metadata.
+
+    Args:
+        period_start_jd:   Start of the period (JD).
+        period_end_jd:     End of the period (JD).
+        first_planet_index: Index into CHALDEAN_ORDER for the first hour.
+        slot_offset:       Running offset so night hours continue from daytime's
+                           last planet index.
+    Returns:
+        List of 12 dicts with hour number, start/end times, and ruling planet.
+    """
+    duration_jd = (period_end_jd - period_start_jd) / 12.0
+    slots: list[dict] = []
+    for i in range(12):
+        planet_idx = (first_planet_index + slot_offset + i) % 7
+        start_jd = period_start_jd + i * duration_jd
+        end_jd = period_start_jd + (i + 1) * duration_jd
+        slots.append(
+            {
+                "hour": i + 1,
+                "start_time": _jd_to_utc(start_jd).strftime("%H:%M:%S UTC"),
+                "end_time": _jd_to_utc(end_jd).strftime("%H:%M:%S UTC"),
+                "planet": CHALDEAN_ORDER[planet_idx],
+            }
+        )
+    return slots
+
+
+def _compute_hora(dt_utc: datetime, lat: float, lon: float) -> dict:
+    """Core computation shared by the public API functions."""
+    sunrise_jd, sunset_jd = _get_sunrise_sunset(dt_utc, lat, lon)
+    next_sunrise_jd = _next_sunrise(sunset_jd, lat, lon)
+
+    current_jd = _jd_from_utc(dt_utc)
+    weekday = _jd_to_utc(sunrise_jd).weekday()  # weekday of the sunrise for this day
+    weekday_name = WEEKDAY_NAMES[weekday]
+    day_ruler_idx = WEEKDAY_FIRST_HOUR[weekday]
+    day_ruler = CHALDEAN_ORDER[day_ruler_idx]
+
+    # Build day hours (sunrise → sunset), starting at day_ruler_idx
+    day_hours = _build_hour_slots(sunrise_jd, sunset_jd, day_ruler_idx, slot_offset=0)
+    # Night hours continue from where day hours left off (12 slots consumed = +12)
+    night_hours = _build_hour_slots(
+        sunset_jd, next_sunrise_jd, day_ruler_idx, slot_offset=12
+    )
+
+    # Determine which hour the current moment falls in
+    is_day = sunrise_jd <= current_jd < sunset_jd
+    hour_number = 1
+    planetary_hour_lord = day_ruler
+
+    if is_day:
+        day_slot_jd = (sunset_jd - sunrise_jd) / 12.0
+        slot_i = int((current_jd - sunrise_jd) / day_slot_jd)
+        slot_i = max(0, min(11, slot_i))
+        hour_number = slot_i + 1
+        planetary_hour_lord = day_hours[slot_i]["planet"]
+    else:
+        # Normalise current_jd into night window
+        if current_jd < sunrise_jd:
+            # Pre-sunrise: part of previous day's night — treat as night hour
+            effective_start = sunset_jd - (next_sunrise_jd - sunset_jd)
+            # This is an edge case; fall back to last night slot
+            night_slot_jd = (next_sunrise_jd - sunset_jd) / 12.0
+            elapsed = current_jd - sunset_jd
+            if elapsed < 0:
+                elapsed += next_sunrise_jd - sunset_jd
+        else:
+            night_slot_jd = (next_sunrise_jd - sunset_jd) / 12.0
+            elapsed = current_jd - sunset_jd
+
+        slot_i = int(elapsed / night_slot_jd)
+        slot_i = max(0, min(11, slot_i))
+        hour_number = slot_i + 1
+        planetary_hour_lord = night_hours[slot_i]["planet"]
+
+    return {
+        "datetime_utc": dt_utc.strftime("%Y-%m-%d %H:%M:%S UTC"),
+        "weekday": weekday_name,
+        "sunrise_approx": _jd_to_utc(sunrise_jd).strftime("%H:%M:%S UTC"),
+        "sunset_approx": _jd_to_utc(sunset_jd).strftime("%H:%M:%S UTC"),
+        "is_day": is_day,
+        "hour_number": hour_number,
+        "planetary_hour_lord": planetary_hour_lord,
+        "day_ruler": day_ruler,
+        "all_day_hours": day_hours,
+        "all_night_hours": night_hours,
+        "significance": HORA_SIGNIFICANCE.get(planetary_hour_lord, ""),
+    }
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def get_planetary_hour(dt_utc: datetime, latitude: float, longitude: float) -> dict:
+    """Return the planetary hour ruling the given UTC moment at (latitude, longitude).
+
+    Args:
+        dt_utc:    A datetime object representing the moment of interest (UTC).
+                   May be timezone-naive (treated as UTC) or tz-aware.
+        latitude:  Geographic latitude in decimal degrees (north positive).
+        longitude: Geographic longitude in decimal degrees (east positive).
+
+    Returns:
+        A dict with weekday, sunrise/sunset times, day/night flag, hour number,
+        ruling planet, all 12 day hours, all 12 night hours, and significance text.
+    """
+    swe.set_ephe_path(None)
+    return _compute_hora(dt_utc, latitude, longitude)
+
+
+def get_hora_chart(
+    birth_datetime_utc: datetime,
+    birth_lat: float,
+    birth_lon: float,
+) -> dict:
+    """Return the planetary hour ruling the birth moment.
+
+    Args:
+        birth_datetime_utc: Birth datetime (UTC).
+        birth_lat:          Birth latitude.
+        birth_lon:          Birth longitude.
+
+    Returns:
+        Same structure as ``get_planetary_hour`` — the Hora at the time of birth.
+    """
+    swe.set_ephe_path(None)
+    result = _compute_hora(birth_datetime_utc, birth_lat, birth_lon)
+    result["context"] = (
+        "Hora chart at birth: the planetary hour lord at birth colours the native's "
+        "temperament and early instincts, supplementing the Lagna lord."
+    )
+    return result

package/azure-function/python/kundali_lib/vedic/houses.py

@@ -0,0 +1,30 @@
+"""House cusps (sidereal, configurable house system)."""
+
+import swisseph as swe
+
+from kundali_lib.vedic.ayanamsa import DEFAULT_HOUSE_SYSTEM
+from kundali_lib.vedic.zodiac import get_rashi
+
+
+def calc_houses_sidereal_with_system(
+    julian_day: float, lat: float, lon: float, house_system: str | None = None
+) -> tuple[list[float], list[float]]:
+    """Returns (cusps[12], ascmc[8]).
+
+    house_system: single char code like 'P' (Placidus), 'K' (Koch), 'E' (Equal), etc.
+    """
+    hs = (house_system or DEFAULT_HOUSE_SYSTEM).upper()[:1]
+    cusps, ascmc = swe.houses_ex(
+        julian_day, lat, lon, hs.encode("ascii"), swe.FLG_SIDEREAL
+    )
+    return list(cusps), list(ascmc)
+
+
+def houses_dict_and_degrees(cusps: list[float]) -> tuple[dict[str, str], list[float]]:
+    """From cusps, return ({House_1: rashi, ...}, [deg1, ...])."""
+    houses = {}
+    degrees = []
+    for i, cusp in enumerate(cusps[:12]):
+        houses[f"House_{i + 1}"] = get_rashi(cusp)
+        degrees.append(round(cusp % 30, 4))
+    return houses, degrees