kundali-chart-mcp 0.2.1

package/python/kundali_lib/vedic/doshas.py

@@ -0,0 +1,453 @@
+"""Vedic astrological doshas: Mangal, Kaal Sarp, Sade Sati, and others."""
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+RASHIS = [
+    "Aries",
+    "Taurus",
+    "Gemini",
+    "Cancer",
+    "Leo",
+    "Virgo",
+    "Libra",
+    "Scorpio",
+    "Sagittarius",
+    "Capricorn",
+    "Aquarius",
+    "Pisces",
+]
+
+RASHI_INDEX = {r: i for i, r in enumerate(RASHIS)}
+
+MANGAL_DOSHA_HOUSES = {1, 2, 4, 7, 8, 12}
+
+DOSHA_LEVEL_MAP = {
+    7: "High",
+    8: "High",
+    1: "Medium",
+    4: "Medium",
+    12: "Medium",
+    2: "Low",
+}
+
+KAAL_SARP_NAMES = {
+    "Aries": "Anant",
+    "Taurus": "Kulik",
+    "Gemini": "Vasuki",
+    "Cancer": "Shankhpal",
+    "Leo": "Padma",
+    "Virgo": "Mahapadma",
+    "Libra": "Takshak",
+    "Scorpio": "Karkotak",
+    "Sagittarius": "Shankhnaad",
+    "Capricorn": "Patak",
+    "Aquarius": "Vishakta",
+    "Pisces": "Sheshnag",
+}
+
+# Combustion thresholds in degrees (direct, retrograde)
+COMBUSTION_THRESHOLDS = {
+    "Moon": (12, 12),
+    "Mercury": (14, 12),
+    "Venus": (10, 8),
+    "Mars": (17, 17),
+    "Jupiter": (11, 11),
+    "Saturn": (15, 15),
+}
+
+MAIN_PLANETS = ["Sun", "Moon", "Mars", "Mercury", "Jupiter", "Venus", "Saturn"]
+WAR_PLANETS = ["Mars", "Mercury", "Jupiter", "Venus", "Saturn"]
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _get_planet(positions: list, name: str) -> dict | None:
+    for p in positions:
+        if p.get("name", "").lower() == name.lower():
+            return p
+    return None
+
+
+def _angular_sep(lon_a: float, lon_b: float) -> float:
+    """Shortest angular distance between two longitudes (0-180)."""
+    diff = abs(lon_a - lon_b) % 360
+    return diff if diff <= 180 else 360 - diff
+
+
+def _lon_between_clockwise(lon: float, start: float, end: float) -> bool:
+    """Return True if *lon* lies in the arc from *start* to *end* going clockwise
+    (i.e. increasing longitude modulo 360)."""
+    lon = lon % 360
+    start = start % 360
+    end = end % 360
+    if start <= end:
+        return start <= lon <= end
+    # Arc wraps around 0°
+    return lon >= start or lon <= end
+
+
+def _rashi_from_lon(lon: float) -> str:
+    return RASHIS[int(lon % 360 / 30)]
+
+
+# ---------------------------------------------------------------------------
+# 1. Mangal Dosha
+# ---------------------------------------------------------------------------
+
+
+def check_mangal_dosha(planetary_positions: list, ascendant: dict) -> dict:
+    """Check for Mangal (Kuja) Dosha.
+
+    Parameters
+    ----------
+    planetary_positions : list
+        List of planet dicts from build_chart().
+    ascendant : dict
+        Ascendant dict (must contain at least a ``longitude`` key, or a
+        ``rashi`` key, from build_chart()).
+
+    Returns
+    -------
+    dict
+        has_dosha, mars_house, affected_houses, dosha_level, cancellation_notes,
+        severity.
+    """
+    mars = _get_planet(planetary_positions, "Mars")
+    if mars is None:
+        return {
+            "has_dosha": False,
+            "mars_house": None,
+            "affected_houses": list(MANGAL_DOSHA_HOUSES),
+            "dosha_level": "None",
+            "cancellation_notes": ["Mars not found in chart"],
+            "severity": "None",
+        }
+
+    mars_house = mars.get("house")
+    has_dosha = mars_house in MANGAL_DOSHA_HOUSES
+    dosha_level = DOSHA_LEVEL_MAP.get(mars_house, "None") if has_dosha else "None"
+
+    # --- Cancellation conditions ---
+    cancellation_notes: list[str] = []
+
+    mars_rashi = mars.get("rashi", "")
+    if mars_rashi in ("Aries", "Scorpio"):
+        cancellation_notes.append(
+            f"Mars is in its own sign ({mars_rashi}) — Dosha is cancelled."
+        )
+
+    if mars_rashi == "Capricorn":
+        cancellation_notes.append("Mars is exalted in Capricorn — Dosha is cancelled.")
+
+    # Jupiter aspecting Mars: Jupiter aspects house +5 and +9 (and its own house)
+    jupiter = _get_planet(planetary_positions, "Jupiter")
+    if jupiter is not None:
+        jup_house = jupiter.get("house", 0)
+        # Jupiter's 5th and 9th aspects (full aspect houses)
+        jup_aspects = {
+            jup_house,
+            (jup_house + 4) % 12 or 12,
+            (jup_house + 8) % 12 or 12,
+        }
+        if mars_house in jup_aspects:
+            cancellation_notes.append(
+                f"Jupiter (house {jup_house}) aspects Mars — Dosha is mitigated."
+            )
+
+    moon = _get_planet(planetary_positions, "Moon")
+    if moon is not None and moon.get("house") == mars_house:
+        cancellation_notes.append("Moon is conjunct Mars — Dosha is mitigated.")
+
+    severity: str
+    if cancellation_notes and any("cancelled" in n.lower() for n in cancellation_notes):
+        severity = "Cancelled"
+    elif not has_dosha:
+        severity = "None"
+    else:
+        severity = dosha_level  # "High", "Medium", or "Low"
+
+    return {
+        "has_dosha": has_dosha,
+        "mars_house": mars_house,
+        "affected_houses": sorted(MANGAL_DOSHA_HOUSES),
+        "dosha_level": dosha_level,
+        "cancellation_notes": cancellation_notes,
+        "severity": severity,
+    }
+
+
+# ---------------------------------------------------------------------------
+# 2. Kaal Sarp Dosha
+# ---------------------------------------------------------------------------
+
+
+def check_kaal_sarp_dosha(planetary_positions: list) -> dict:
+    """Check for Kaal Sarp / Kaal Amrit Yoga.
+
+    Parameters
+    ----------
+    planetary_positions : list
+        List of planet dicts from build_chart().
+
+    Returns
+    -------
+    dict
+        has_dosha, dosha_type, rahu_longitude, ketu_longitude,
+        planets_inside, planets_outside, name.
+    """
+    rahu = _get_planet(planetary_positions, "Rahu")
+    if rahu is None:
+        return {
+            "has_dosha": False,
+            "dosha_type": "None",
+            "rahu_longitude": None,
+            "ketu_longitude": None,
+            "planets_inside": [],
+            "planets_outside": list(MAIN_PLANETS),
+            "name": "None",
+        }
+
+    rahu_lon = rahu.get("longitude", 0.0) % 360
+    ketu_lon = (rahu_lon + 180) % 360
+
+    planets_inside: list[str] = []
+    planets_outside: list[str] = []
+
+    for pname in MAIN_PLANETS:
+        p = _get_planet(planetary_positions, pname)
+        if p is None:
+            planets_outside.append(pname)
+            continue
+        plon = p.get("longitude", 0.0) % 360
+        if _lon_between_clockwise(plon, rahu_lon, ketu_lon):
+            planets_inside.append(pname)
+        else:
+            planets_outside.append(pname)
+
+    all_inside_clockwise = len(planets_outside) == 0
+    # Kaal Amrit: all planets in the arc from Ketu → Rahu (counter-clockwise)
+    planets_inside_ccw: list[str] = []
+    planets_outside_ccw: list[str] = []
+    for pname in MAIN_PLANETS:
+        p = _get_planet(planetary_positions, pname)
+        if p is None:
+            planets_outside_ccw.append(pname)
+            continue
+        plon = p.get("longitude", 0.0) % 360
+        if _lon_between_clockwise(plon, ketu_lon, rahu_lon):
+            planets_inside_ccw.append(pname)
+        else:
+            planets_outside_ccw.append(pname)
+
+    all_inside_ccw = len(planets_outside_ccw) == 0
+
+    rahu_rashi = _rashi_from_lon(rahu_lon)
+    ksd_name = KAAL_SARP_NAMES.get(rahu_rashi, "Unknown")
+
+    if all_inside_clockwise:
+        dosha_type = "Kaal Sarp"
+        has_dosha = True
+    elif all_inside_ccw:
+        dosha_type = "Kaal Amrit"
+        has_dosha = True
+        planets_inside = planets_inside_ccw
+        planets_outside = planets_outside_ccw
+    else:
+        dosha_type = "None"
+        has_dosha = False
+
+    return {
+        "has_dosha": has_dosha,
+        "dosha_type": dosha_type,
+        "rahu_longitude": round(rahu_lon, 4),
+        "ketu_longitude": round(ketu_lon, 4),
+        "planets_inside": planets_inside,
+        "planets_outside": planets_outside,
+        "name": ksd_name if has_dosha else "None",
+    }
+
+
+# ---------------------------------------------------------------------------
+# 3. Sade Sati
+# ---------------------------------------------------------------------------
+
+
+def check_sade_sati(natal_moon_rashi: str, current_saturn_rashi: str) -> dict:
+    """Check whether Saturn's transit triggers Sade Sati for the natal Moon sign.
+
+    Parameters
+    ----------
+    natal_moon_rashi : str
+        Rashi of Moon at birth (e.g. "Taurus").
+    current_saturn_rashi : str
+        Rashi Saturn currently occupies (transit chart).
+
+    Returns
+    -------
+    dict
+        is_sade_sati, phase, natal_moon_rashi, current_saturn_rashi, description.
+    """
+    if natal_moon_rashi not in RASHI_INDEX or current_saturn_rashi not in RASHI_INDEX:
+        return {
+            "is_sade_sati": False,
+            "phase": "None",
+            "natal_moon_rashi": natal_moon_rashi,
+            "current_saturn_rashi": current_saturn_rashi,
+            "description": "Invalid rashi name provided.",
+        }
+
+    moon_idx = RASHI_INDEX[natal_moon_rashi]
+    saturn_idx = RASHI_INDEX[current_saturn_rashi]
+
+    rising_rashi = RASHIS[(moon_idx - 1) % 12]
+    peak_rashi = natal_moon_rashi
+    setting_rashi = RASHIS[(moon_idx + 1) % 12]
+
+    if current_saturn_rashi == rising_rashi:
+        phase = "Rising"
+        description = (
+            f"Saturn is transiting {rising_rashi}, the sign before your natal Moon "
+            f"sign ({natal_moon_rashi}). This is the Rising phase of Sade Sati — "
+            "challenges begin to build gradually."
+        )
+        is_sade_sati = True
+    elif current_saturn_rashi == peak_rashi:
+        phase = "Peak"
+        description = (
+            f"Saturn is transiting your natal Moon sign ({natal_moon_rashi}). "
+            "This is the Peak phase of Sade Sati — the most intense period."
+        )
+        is_sade_sati = True
+    elif current_saturn_rashi == setting_rashi:
+        phase = "Setting"
+        description = (
+            f"Saturn is transiting {setting_rashi}, the sign after your natal Moon "
+            f"sign ({natal_moon_rashi}). This is the Setting phase of Sade Sati — "
+            "pressures gradually ease."
+        )
+        is_sade_sati = True
+    else:
+        phase = "None"
+        description = (
+            f"Saturn ({current_saturn_rashi}) is not transiting through any of the "
+            f"three signs of Sade Sati for Moon in {natal_moon_rashi} "
+            f"({rising_rashi}, {peak_rashi}, {setting_rashi})."
+        )
+        is_sade_sati = False
+
+    return {
+        "is_sade_sati": is_sade_sati,
+        "phase": phase,
+        "natal_moon_rashi": natal_moon_rashi,
+        "current_saturn_rashi": current_saturn_rashi,
+        "description": description,
+    }
+
+
+# ---------------------------------------------------------------------------
+# 4. Graha Yuddha (Planetary War)
+# ---------------------------------------------------------------------------
+
+
+def check_graha_yuddha(planetary_positions: list) -> list:
+    """Detect Graha Yuddha (planetary war) between non-luminary planets.
+
+    Two planets are at war when their longitudes are within 1 degree.
+    The planet with the lower longitude wins (or higher latitude, but we use
+    longitude as the primary metric since latitude data may be absent).
+
+    Parameters
+    ----------
+    planetary_positions : list
+        List of planet dicts from build_chart().
+
+    Returns
+    -------
+    list of dict
+        Each entry: planet1, planet2, longitude_diff, winner, loser.
+    """
+    wars: list[dict] = []
+    war_planets = []
+    for pname in WAR_PLANETS:
+        p = _get_planet(planetary_positions, pname)
+        if p is not None:
+            war_planets.append(p)
+
+    for i in range(len(war_planets)):
+        for j in range(i + 1, len(war_planets)):
+            p1 = war_planets[i]
+            p2 = war_planets[j]
+            lon1 = p1.get("longitude", 0.0)
+            lon2 = p2.get("longitude", 0.0)
+            sep = _angular_sep(lon1, lon2)
+            if sep <= 1.0:
+                # Winner = lower longitude (closer to 0° of the sign)
+                if lon1 <= lon2:
+                    winner, loser = p1["name"], p2["name"]
+                else:
+                    winner, loser = p2["name"], p1["name"]
+                wars.append(
+                    {
+                        "planet1": p1["name"],
+                        "planet2": p2["name"],
+                        "longitude_diff": round(sep, 4),
+                        "winner": winner,
+                        "loser": loser,
+                    }
+                )
+
+    return wars
+
+
+# ---------------------------------------------------------------------------
+# 5. Combustion
+# ---------------------------------------------------------------------------
+
+
+def check_combustion(planetary_positions: list) -> list:
+    """Determine which planets are combust (too close to the Sun).
+
+    Parameters
+    ----------
+    planetary_positions : list
+        List of planet dicts from build_chart().
+
+    Returns
+    -------
+    list of dict
+        Each entry: planet, sun_longitude, planet_longitude,
+        angular_separation, threshold, is_combust.
+    """
+    sun = _get_planet(planetary_positions, "Sun")
+    if sun is None:
+        return []
+
+    sun_lon = sun.get("longitude", 0.0)
+    results: list[dict] = []
+
+    for pname, (thresh_direct, thresh_retro) in COMBUSTION_THRESHOLDS.items():
+        p = _get_planet(planetary_positions, pname)
+        if p is None:
+            continue
+        p_lon = p.get("longitude", 0.0)
+        is_retro = bool(p.get("is_retrograde", False))
+        threshold = thresh_retro if is_retro else thresh_direct
+        sep = _angular_sep(sun_lon, p_lon)
+
+        results.append(
+            {
+                "planet": pname,
+                "sun_longitude": round(sun_lon, 4),
+                "planet_longitude": round(p_lon, 4),
+                "angular_separation": round(sep, 4),
+                "threshold": threshold,
+                "is_combust": sep < threshold,
+            }
+        )
+
+    return results

package/python/kundali_lib/vedic/gandanta.py

@@ -0,0 +1,213 @@
+"""Gandanta: Junction points between water and fire signs — highly sensitive degrees."""
+
+# ---------------------------------------------------------------------------
+# Gandanta zone definitions
+# ---------------------------------------------------------------------------
+# Gandanta occurs at the three water→fire sign junctions.
+# The sensitive zone extends GANDANTA_DEGREES on each side of the cusp.
+
+GANDANTA_DEGREES = 3.333  # 3°20' = 1 nakshatra pada
+
+# Each zone stores:
+#   from_sign / to_sign — the water and fire sign names
+#   water_end           — absolute longitude of the water-sign cusp (end)
+#   fire_start          — absolute longitude of the fire-sign cusp (start)
+#   nakshatras          — (last nak of water sign, first nak of fire sign)
+#   description         — brief spiritual significance
+_GANDANTA_ZONES = [
+    {
+        "from_sign": "Cancer",
+        "to_sign": "Leo",
+        "water_end": 120.0,  # end of Cancer  (4 × 30)
+        "fire_start": 120.0,  # start of Leo   (5 × 30 — same cusp)
+        "nakshatras": ("Ashlesha", "Magha"),
+        "description": "Ashlesha–Magha junction: dissolution of ancestral karma and royalty.",
+    },
+    {
+        "from_sign": "Scorpio",
+        "to_sign": "Sagittarius",
+        "water_end": 240.0,  # end of Scorpio  (8 × 30)
+        "fire_start": 240.0,  # start of Sagittarius (9 × 30)
+        "nakshatras": ("Jyeshtha", "Mula"),
+        "description": "Jyeshtha–Mula junction: most intense Gandanta; roots torn and replanted.",
+    },
+    {
+        "from_sign": "Pisces",
+        "to_sign": "Aries",
+        "water_end": 360.0,  # end of Pisces  (12 × 30 = 360 = 0)
+        "fire_start": 0.0,  # start of Aries
+        "nakshatras": ("Revati", "Ashwini"),
+        "description": "Revati–Ashwini junction: end and beginning of the zodiac; liberation and rebirth.",
+    },
+]
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _normalise(lon: float) -> float:
+    return lon % 360
+
+
+def _intensity_label(degrees_from_edge: float) -> str:
+    """Classify intensity based on distance from the exact junction."""
+    if degrees_from_edge < 1.0:
+        return "Severe"
+    if degrees_from_edge < 2.0:
+        return "Moderate"
+    return "Mild"
+
+
+def _check_planet_in_gandanta(name: str, lon: float) -> dict | None:
+    """Return a Gandanta entry dict if *lon* falls in any Gandanta zone, else None."""
+    lon = _normalise(lon)
+    deg_in_sign = lon % 30
+
+    for zone in _GANDANTA_ZONES:
+        cusp = zone["water_end"]  # water_end == fire_start (same longitude)
+
+        # --- Water-sign side: last GANDANTA_DEGREES of the water sign ---
+        # The water sign ends at `cusp`; a planet is in the water-side zone when
+        # its degree within its sign is > (30 - GANDANTA_DEGREES).
+        water_zone_start = cusp - GANDANTA_DEGREES  # absolute
+        # Handle the Pisces→Aries wrap-around
+        if cusp == 360.0 or cusp == 0.0:
+            # water sign is Pisces; zone is 356.667° – 360°
+            in_water = 356.667 <= lon < 360.0
+            dist_water = 360.0 - lon if in_water else None
+        else:
+            in_water = water_zone_start <= lon < cusp
+            dist_water = cusp - lon if in_water else None
+
+        # --- Fire-sign side: first GANDANTA_DEGREES of the fire sign ---
+        if cusp == 360.0 or cusp == 0.0:
+            # fire sign is Aries; zone is 0° – 3.333°
+            fire_zone_end = GANDANTA_DEGREES
+            in_fire = 0.0 <= lon < fire_zone_end
+            dist_fire = lon if in_fire else None
+        else:
+            fire_zone_end = cusp + GANDANTA_DEGREES
+            in_fire = cusp <= lon < fire_zone_end
+            dist_fire = lon - cusp if in_fire else None
+
+        if in_water:
+            dist = dist_water
+            return {
+                "planet": name,
+                "longitude": round(lon, 4),
+                "rashi": zone["from_sign"],
+                "degree_in_sign": round(deg_in_sign, 4),
+                "gandanta_zone": f"{zone['from_sign']}–{zone['to_sign']} junction",
+                "in_water_side": True,
+                "in_fire_side": False,
+                "intensity": _intensity_label(dist),
+                "nakshatras": zone["nakshatras"],
+                "significance": zone["description"],
+            }
+
+        if in_fire:
+            dist = dist_fire
+            # For fire side, rashi is the fire sign
+            rashis = [
+                "Aries",
+                "Taurus",
+                "Gemini",
+                "Cancer",
+                "Leo",
+                "Virgo",
+                "Libra",
+                "Scorpio",
+                "Sagittarius",
+                "Capricorn",
+                "Aquarius",
+                "Pisces",
+            ]
+            rashi = rashis[int(lon / 30) % 12]
+            return {
+                "planet": name,
+                "longitude": round(lon, 4),
+                "rashi": rashi,
+                "degree_in_sign": round(deg_in_sign, 4),
+                "gandanta_zone": f"{zone['from_sign']}–{zone['to_sign']} junction",
+                "in_water_side": False,
+                "in_fire_side": True,
+                "intensity": _intensity_label(dist),
+                "nakshatras": zone["nakshatras"],
+                "significance": zone["description"],
+            }
+
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def check_gandanta(planetary_positions: list, ascendant: dict = None) -> list:
+    """Check which planets (and optionally the ascendant) fall in Gandanta zones.
+
+    Parameters
+    ----------
+    planetary_positions : list
+        Each item is a planet dict with at least ``name`` and ``longitude``.
+    ascendant : dict, optional
+        Ascendant dict with at least ``longitude``.  When supplied it is also
+        checked; it appears in the output as ``name="Ascendant"``.
+
+    Returns
+    -------
+    list of dict
+        One entry per planet/ascendant that lies in a Gandanta zone.
+        Empty list if none are in Gandanta.
+    """
+    results = []
+
+    for planet in planetary_positions:
+        entry = _check_planet_in_gandanta(planet["name"], planet["longitude"])
+        if entry:
+            results.append(entry)
+
+    if ascendant is not None:
+        entry = _check_planet_in_gandanta("Ascendant", ascendant["longitude"])
+        if entry:
+            results.append(entry)
+
+    return results
+
+
+def get_gandanta_info() -> dict:
+    """Return educational information about all three Gandanta zones.
+
+    Returns
+    -------
+    dict
+        Keyed by ``"<WaterSign>-<FireSign>"``, each value holds zone metadata
+        including the boundary nakshatras, degrees affected, and significance.
+    """
+    info = {}
+    for zone in _GANDANTA_ZONES:
+        key = f"{zone['from_sign']}-{zone['to_sign']}"
+        info[key] = {
+            "water_sign": zone["from_sign"],
+            "fire_sign": zone["to_sign"],
+            "junction_longitude": zone["water_end"] % 360,
+            "affected_range": f"Last {GANDANTA_DEGREES}° of {zone['from_sign']} "
+            f"and first {GANDANTA_DEGREES}° of {zone['to_sign']}",
+            "boundary_nakshatras": zone["nakshatras"],
+            "last_nakshatra_water": zone["nakshatras"][0],
+            "first_nakshatra_fire": zone["nakshatras"][1],
+            "significance": zone["description"],
+            "intensity_guide": {
+                "Severe": "< 1° from junction cusp — highly problematic; remedies essential",
+                "Moderate": "1°–2° from junction cusp — notable challenges",
+                "Mild": "2°–3°20' from junction cusp — some instability; monitor",
+            },
+            "general_note": (
+                "Planets in Gandanta operate in a zone of karmic dissolution. "
+                "The native may face deep-rooted instability in the significations of "
+                "that planet unless strong remedies are undertaken."
+            ),
+        }
+    return info