kundali-chart-mcp 0.2.1

package/python/kundali_lib/vedic/compatibility.py

@@ -0,0 +1,705 @@
+"""Ashtakoot Milan: 36-point Vedic marriage compatibility scoring."""
+
+# ---------------------------------------------------------------------------
+# Reference data
+# ---------------------------------------------------------------------------
+
+RASHIS = [
+    "Aries",
+    "Taurus",
+    "Gemini",
+    "Cancer",
+    "Leo",
+    "Virgo",
+    "Libra",
+    "Scorpio",
+    "Sagittarius",
+    "Capricorn",
+    "Aquarius",
+    "Pisces",
+]
+
+RASHI_LORDS = {
+    "Aries": "Mars",
+    "Taurus": "Venus",
+    "Gemini": "Mercury",
+    "Cancer": "Moon",
+    "Leo": "Sun",
+    "Virgo": "Mercury",
+    "Libra": "Venus",
+    "Scorpio": "Mars",
+    "Sagittarius": "Jupiter",
+    "Capricorn": "Saturn",
+    "Aquarius": "Saturn",
+    "Pisces": "Jupiter",
+}
+
+NAKSHATRAS = [
+    "Ashwini",
+    "Bharani",
+    "Krittika",
+    "Rohini",
+    "Mrigashira",
+    "Ardra",
+    "Punarvasu",
+    "Pushya",
+    "Ashlesha",
+    "Magha",
+    "Purva Phalguni",
+    "Uttara Phalguni",
+    "Hasta",
+    "Chitra",
+    "Swati",
+    "Vishakha",
+    "Anuradha",
+    "Jyeshtha",
+    "Mula",
+    "Purva Ashadha",
+    "Uttara Ashadha",
+    "Shravana",
+    "Dhanishta",
+    "Shatabhisha",
+    "Purva Bhadrapada",
+    "Uttara Bhadrapada",
+    "Revati",
+]
+
+# ---------------------------------------------------------------------------
+# Varna
+# ---------------------------------------------------------------------------
+
+VARNA = {
+    "Cancer": "Brahmin",
+    "Scorpio": "Brahmin",
+    "Pisces": "Brahmin",
+    "Aries": "Kshatriya",
+    "Leo": "Kshatriya",
+    "Sagittarius": "Kshatriya",
+    "Taurus": "Vaishya",
+    "Virgo": "Vaishya",
+    "Capricorn": "Vaishya",
+    "Gemini": "Shudra",
+    "Libra": "Shudra",
+    "Aquarius": "Shudra",
+}
+
+VARNA_RANK = {"Brahmin": 4, "Kshatriya": 3, "Vaishya": 2, "Shudra": 1}
+
+# ---------------------------------------------------------------------------
+# Vashya
+# ---------------------------------------------------------------------------
+
+VASHYA = {
+    "Aries": "Chatushpada",
+    "Taurus": "Chatushpada",
+    "Gemini": "Nara",
+    "Cancer": "Jalachara",
+    "Leo": "Vanachara",
+    "Virgo": "Nara",
+    "Libra": "Nara",
+    "Scorpio": "Keeta",
+    "Sagittarius": "Nara",
+    "Capricorn": "Jalachara",
+    "Aquarius": "Nara",
+    "Pisces": "Jalachara",
+}
+
+# Vashya compatible pairs (one-way control): score 1
+_VASHYA_COMPATIBLE = {
+    ("Chatushpada", "Nara"),
+    ("Nara", "Chatushpada"),
+}
+
+# ---------------------------------------------------------------------------
+# Yoni
+# ---------------------------------------------------------------------------
+
+YONI = {
+    "Ashwini": "Horse",
+    "Bharani": "Elephant",
+    "Krittika": "Sheep",
+    "Rohini": "Serpent",
+    "Mrigashira": "Serpent",
+    "Ardra": "Dog",
+    "Punarvasu": "Cat",
+    "Pushya": "Sheep",
+    "Ashlesha": "Cat",
+    "Magha": "Rat",
+    "Purva Phalguni": "Rat",
+    "Uttara Phalguni": "Cow",
+    "Hasta": "Buffalo",
+    "Chitra": "Tiger",
+    "Swati": "Buffalo",
+    "Vishakha": "Tiger",
+    "Anuradha": "Deer",
+    "Jyeshtha": "Deer",
+    "Mula": "Dog",
+    "Purva Ashadha": "Monkey",
+    "Uttara Ashadha": "Mongoose",
+    "Shravana": "Monkey",
+    "Dhanishta": "Lion",
+    "Shatabhisha": "Horse",
+    "Purva Bhadrapada": "Lion",
+    "Uttara Bhadrapada": "Cow",
+    "Revati": "Elephant",
+}
+
+_ENEMY_YONI_PAIRS = {
+    frozenset({"Horse", "Buffalo"}),
+    frozenset({"Elephant", "Lion"}),
+    frozenset({"Sheep", "Monkey"}),
+    frozenset({"Serpent", "Mongoose"}),
+    frozenset({"Dog", "Deer"}),
+    frozenset({"Cat", "Rat"}),
+    frozenset({"Cow", "Tiger"}),
+}
+
+# ---------------------------------------------------------------------------
+# Graha Maitri
+# ---------------------------------------------------------------------------
+
+PLANET_FRIENDS = {
+    "Sun": {
+        "friends": ["Moon", "Mars", "Jupiter"],
+        "enemies": ["Venus", "Saturn"],
+        "neutral": ["Mercury"],
+    },
+    "Moon": {
+        "friends": ["Sun", "Mercury"],
+        "enemies": [],
+        "neutral": ["Mars", "Jupiter", "Venus", "Saturn"],
+    },
+    "Mars": {
+        "friends": ["Sun", "Moon", "Jupiter"],
+        "enemies": ["Mercury"],
+        "neutral": ["Venus", "Saturn"],
+    },
+    "Mercury": {
+        "friends": ["Sun", "Venus"],
+        "enemies": ["Moon"],
+        "neutral": ["Mars", "Jupiter", "Saturn"],
+    },
+    "Jupiter": {
+        "friends": ["Sun", "Moon", "Mars"],
+        "enemies": ["Mercury", "Venus"],
+        "neutral": ["Saturn"],
+    },
+    "Venus": {
+        "friends": ["Mercury", "Saturn"],
+        "enemies": ["Sun", "Moon"],
+        "neutral": ["Mars", "Jupiter"],
+    },
+    "Saturn": {
+        "friends": ["Mercury", "Venus"],
+        "enemies": ["Sun", "Moon", "Mars"],
+        "neutral": ["Jupiter"],
+    },
+}
+
+
+def _planet_relationship(p1: str, p2: str) -> str:
+    """Return 'friend', 'enemy', or 'neutral' from p1's perspective of p2."""
+    if p1 not in PLANET_FRIENDS:
+        return "neutral"
+    data = PLANET_FRIENDS[p1]
+    if p2 in data["friends"]:
+        return "friend"
+    if p2 in data["enemies"]:
+        return "enemy"
+    return "neutral"
+
+
+# ---------------------------------------------------------------------------
+# Gana
+# ---------------------------------------------------------------------------
+
+GANA = {
+    "Ashwini": "Deva",
+    "Mrigashira": "Deva",
+    "Punarvasu": "Deva",
+    "Pushya": "Deva",
+    "Hasta": "Deva",
+    "Swati": "Deva",
+    "Anuradha": "Deva",
+    "Shravana": "Deva",
+    "Revati": "Deva",
+    "Bharani": "Manushya",
+    "Rohini": "Manushya",
+    "Ardra": "Manushya",
+    "Purva Phalguni": "Manushya",
+    "Uttara Phalguni": "Manushya",
+    "Purva Ashadha": "Manushya",
+    "Uttara Ashadha": "Manushya",
+    "Purva Bhadrapada": "Manushya",
+    "Uttara Bhadrapada": "Manushya",
+    "Krittika": "Rakshasa",
+    "Ashlesha": "Rakshasa",
+    "Magha": "Rakshasa",
+    "Chitra": "Rakshasa",
+    "Vishakha": "Rakshasa",
+    "Jyeshtha": "Rakshasa",
+    "Mula": "Rakshasa",
+    "Dhanishta": "Rakshasa",
+    "Shatabhisha": "Rakshasa",
+}
+
+# Gana score table: (boy_gana, girl_gana) -> score
+_GANA_SCORES = {
+    ("Deva", "Deva"): 6,
+    ("Manushya", "Manushya"): 6,
+    ("Rakshasa", "Rakshasa"): 6,
+    ("Deva", "Manushya"): 5,
+    ("Manushya", "Deva"): 5,
+    ("Deva", "Rakshasa"): 1,
+    ("Rakshasa", "Deva"): 0,
+    ("Manushya", "Rakshasa"): 0,
+    ("Rakshasa", "Manushya"): 3,
+}
+
+# ---------------------------------------------------------------------------
+# Nadi
+# ---------------------------------------------------------------------------
+
+NADI = {
+    "Ashwini": "Aadi",
+    "Ardra": "Aadi",
+    "Punarvasu": "Aadi",
+    "Uttara Phalguni": "Aadi",
+    "Hasta": "Aadi",
+    "Jyeshtha": "Aadi",
+    "Mula": "Aadi",
+    "Shatabhisha": "Aadi",
+    "Purva Bhadrapada": "Aadi",
+    "Bharani": "Madhya",
+    "Mrigashira": "Madhya",
+    "Pushya": "Madhya",
+    "Purva Phalguni": "Madhya",
+    "Chitra": "Madhya",
+    "Anuradha": "Madhya",
+    "Purva Ashadha": "Madhya",
+    "Dhanishta": "Madhya",
+    "Uttara Bhadrapada": "Madhya",
+    "Krittika": "Antya",
+    "Rohini": "Antya",
+    "Ashlesha": "Antya",
+    "Magha": "Antya",
+    "Swati": "Antya",
+    "Vishakha": "Antya",
+    "Uttara Ashadha": "Antya",
+    "Shravana": "Antya",
+    "Revati": "Antya",
+}
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _get_planet(positions: list, name: str) -> dict | None:
+    for p in positions:
+        if p["name"] == name:
+            return p
+    return None
+
+
+def _moon_data(chart: dict) -> tuple:
+    """Return (moon_rashi, moon_nakshatra) from a chart."""
+    positions = chart.get("planetary_positions", [])
+    moon = _get_planet(positions, "Moon")
+    if moon:
+        rashi = moon.get("rashi") or chart.get("moon_sign", "")
+        nakshatra = moon.get("nakshatra", "")
+        return rashi, nakshatra
+    return chart.get("moon_sign", ""), ""
+
+
+def _rashi_index(rashi: str) -> int:
+    try:
+        return RASHIS.index(rashi)
+    except ValueError:
+        return 0
+
+
+def _nakshatra_index(nakshatra: str) -> int:
+    try:
+        return NAKSHATRAS.index(nakshatra)
+    except ValueError:
+        return 0
+
+
+def _rashi_from(base: str, n: int) -> str:
+    """Return the rashi that is n positions from base (1-indexed)."""
+    idx = (_rashi_index(base) + n - 1) % 12
+    return RASHIS[idx]
+
+
+def _count_rashi_from(base: str, target: str) -> int:
+    """Count how many rashis target is from base (1-indexed, 1-12)."""
+    return (_rashi_index(target) - _rashi_index(base)) % 12 + 1
+
+
+# ---------------------------------------------------------------------------
+# Koota scoring functions
+# ---------------------------------------------------------------------------
+
+
+def _score_varna(boy_rashi: str, girl_rashi: str) -> tuple:
+    boy_varna = VARNA.get(boy_rashi, "Shudra")
+    girl_varna = VARNA.get(girl_rashi, "Shudra")
+    boy_rank = VARNA_RANK.get(boy_varna, 1)
+    girl_rank = VARNA_RANK.get(girl_varna, 1)
+    score = 1.0 if boy_rank >= girl_rank else 0.0
+    desc = (
+        f"Boy: {boy_varna} ({boy_rashi}), Girl: {girl_varna} ({girl_rashi}). "
+        f"{'Compatible' if score == 1 else 'Incompatible'}: boy's social class "
+        f"{'matches or exceeds' if score == 1 else 'is lower than'} girl's."
+    )
+    return score, desc
+
+
+def _score_vashya(boy_rashi: str, girl_rashi: str) -> tuple:
+    boy_group = VASHYA.get(boy_rashi, "Nara")
+    girl_group = VASHYA.get(girl_rashi, "Nara")
+    if boy_group == girl_group:
+        score = 2.0
+        compatibility = "same Vashya group — ideal"
+    elif (boy_group, girl_group) in _VASHYA_COMPATIBLE or (
+        girl_group,
+        boy_group,
+    ) in _VASHYA_COMPATIBLE:
+        score = 1.0
+        compatibility = "partially compatible Vashya groups"
+    else:
+        score = 0.0
+        compatibility = "incompatible Vashya groups"
+    desc = (
+        f"Boy: {boy_group} ({boy_rashi}), Girl: {girl_group} ({girl_rashi}). "
+        f"{compatibility.capitalize()}."
+    )
+    return score, desc
+
+
+def _score_tara(boy_nak: str, girl_nak: str) -> tuple:
+    boy_idx = _nakshatra_index(boy_nak)
+    girl_idx = _nakshatra_index(girl_nak)
+
+    def tara_number(from_idx: int, to_idx: int) -> int:
+        count = (to_idx - from_idx) % 27 + 1  # 1-27
+        return ((count - 1) % 9) + 1  # 1-9
+
+    AUSPICIOUS_TARAS = {1, 4, 7}
+    INAUSPICIOUS_TARAS = {3, 6, 9}
+
+    t_boy_to_girl = tara_number(boy_idx, girl_idx)
+    t_girl_to_boy = tara_number(girl_idx, boy_idx)
+
+    def tara_category(t: int) -> str:
+        if t in AUSPICIOUS_TARAS:
+            return "auspicious"
+        if t in INAUSPICIOUS_TARAS:
+            return "inauspicious"
+        return "neutral"
+
+    cat_btg = tara_category(t_boy_to_girl)
+    cat_gtb = tara_category(t_girl_to_boy)
+
+    if cat_btg == "auspicious" and cat_gtb == "auspicious":
+        score = 3.0
+    elif cat_btg == "inauspicious" and cat_gtb == "inauspicious":
+        score = 0.0
+    else:
+        score = 1.5
+
+    desc = (
+        f"Boy→Girl tara: {t_boy_to_girl} ({cat_btg}), "
+        f"Girl→Boy tara: {t_girl_to_boy} ({cat_gtb})."
+    )
+    return score, desc
+
+
+def _score_yoni(boy_nak: str, girl_nak: str) -> tuple:
+    boy_yoni = YONI.get(boy_nak, "")
+    girl_yoni = YONI.get(girl_nak, "")
+
+    if boy_yoni == girl_yoni:
+        score = 4.0
+        compat = "same animal — ideal match"
+    elif frozenset({boy_yoni, girl_yoni}) in _ENEMY_YONI_PAIRS:
+        score = 0.0
+        compat = "enemy animals — incompatible"
+    else:
+        score = 2.0
+        compat = "neutral animal pairing"
+
+    desc = (
+        f"Boy: {boy_yoni} ({boy_nak}), Girl: {girl_yoni} ({girl_nak}). "
+        f"{compat.capitalize()}."
+    )
+    return score, desc
+
+
+def _score_graha_maitri(boy_rashi: str, girl_rashi: str) -> tuple:
+    boy_lord = RASHI_LORDS.get(boy_rashi, "")
+    girl_lord = RASHI_LORDS.get(girl_rashi, "")
+
+    rel_boy_to_girl = _planet_relationship(boy_lord, girl_lord)
+    rel_girl_to_boy = _planet_relationship(girl_lord, boy_lord)
+
+    scoring_map = {
+        ("friend", "friend"): 5.0,
+        ("friend", "neutral"): 4.0,
+        ("neutral", "friend"): 4.0,
+        ("neutral", "neutral"): 3.0,
+        ("friend", "enemy"): 1.0,
+        ("enemy", "friend"): 1.0,
+        ("neutral", "enemy"): 1.0,
+        ("enemy", "neutral"): 1.0,
+        ("enemy", "enemy"): 0.0,
+    }
+    score = scoring_map.get((rel_boy_to_girl, rel_girl_to_boy), 3.0)
+
+    desc = (
+        f"Boy's lord: {boy_lord} ({boy_rashi}), Girl's lord: {girl_lord} ({girl_rashi}). "
+        f"{boy_lord} views {girl_lord} as {rel_boy_to_girl}; "
+        f"{girl_lord} views {boy_lord} as {rel_girl_to_boy}."
+    )
+    return score, desc
+
+
+def _score_gana(boy_nak: str, girl_nak: str) -> tuple:
+    boy_gana = GANA.get(boy_nak, "Manushya")
+    girl_gana = GANA.get(girl_nak, "Manushya")
+    score = float(_GANA_SCORES.get((boy_gana, girl_gana), 0))
+    desc = (
+        f"Boy: {boy_gana} ({boy_nak}), Girl: {girl_gana} ({girl_nak}). "
+        f"Score {int(score)}/6."
+    )
+    return score, desc
+
+
+def _score_bhakoot(boy_rashi: str, girl_rashi: str) -> tuple:
+    girl_from_boy = _count_rashi_from(boy_rashi, girl_rashi)  # 1-12
+    boy_from_girl = _count_rashi_from(girl_rashi, boy_rashi)  # 1-12
+
+    # 6-8 Dosha: one is 6th from the other (the other is always 8th)
+    dosha_68 = girl_from_boy in {6, 8}
+    # 2-12 Dosha: one is 2nd from the other (the other is always 12th)
+    dosha_212 = girl_from_boy in {2, 12}
+
+    if dosha_68 or dosha_212:
+        score = 0.0
+        dosha_name = "6-8 (Shashtashtama)" if dosha_68 else "2-12 (Dvir-Dvadasha)"
+        compat = f"Bhakoot dosha present ({dosha_name}) — inauspicious"
+    else:
+        score = 7.0
+        compat = "No Bhakoot dosha — auspicious"
+
+    desc = (
+        f"Girl's rashi is {girl_from_boy}th from boy's ({boy_rashi}→{girl_rashi}); "
+        f"boy's is {boy_from_girl}th from girl's. {compat}."
+    )
+    return score, desc
+
+
+def _score_nadi(boy_nak: str, girl_nak: str) -> tuple:
+    boy_nadi = NADI.get(boy_nak, "")
+    girl_nadi = NADI.get(girl_nak, "")
+
+    if boy_nadi and girl_nadi and boy_nadi == girl_nadi:
+        score = 0.0
+        desc = (
+            f"Both have {boy_nadi} Nadi ({boy_nak}, {girl_nak}). "
+            "Nadi Dosha present — same nadi is highly inauspicious for health and progeny."
+        )
+    else:
+        score = 8.0
+        desc = (
+            f"Boy: {boy_nadi} Nadi ({boy_nak}), Girl: {girl_nadi} Nadi ({girl_nak}). "
+            "Different nadis — auspicious, no Nadi Dosha."
+        )
+    return score, desc
+
+
+# ---------------------------------------------------------------------------
+# Mangal Dosha
+# ---------------------------------------------------------------------------
+
+
+def _has_mangal_dosha(chart: dict) -> bool:
+    """Mars in houses 1, 2, 4, 7, 8, or 12 from Lagna = Mangal Dosha."""
+    positions = chart.get("planetary_positions", [])
+    for p in positions:
+        if p["name"] == "Mars":
+            return p.get("house") in {1, 2, 4, 7, 8, 12}
+    return False
+
+
+# ---------------------------------------------------------------------------
+# Verdict helpers
+# ---------------------------------------------------------------------------
+
+
+def _verdict(total: float) -> str:
+    if total >= 31:
+        return "Excellent"
+    if total >= 26:
+        return "Good"
+    if total >= 21:
+        return "Average"
+    if total >= 16:
+        return "Below Average"
+    return "Poor"
+
+
+def _recommendation(
+    total: float,
+    nadi_dosha: bool,
+    bhakoot_dosha: bool,
+    boy_mangal: bool,
+    girl_mangal: bool,
+) -> str:
+    parts = []
+
+    if total >= 31:
+        parts.append("This is an excellent match with very strong compatibility.")
+    elif total >= 26:
+        parts.append("This is a good match with solid compatibility.")
+    elif total >= 21:
+        parts.append("This is an average match; the union can work with mutual effort.")
+    elif total >= 16:
+        parts.append(
+            "Compatibility is below average; careful consideration is advised."
+        )
+    else:
+        parts.append(
+            "Compatibility is poor; consultation with a Jyotishi is strongly advised."
+        )
+
+    if nadi_dosha:
+        parts.append(
+            "Nadi Dosha is present, which may affect health and progeny — remedies are recommended."
+        )
+    if bhakoot_dosha:
+        parts.append(
+            "Bhakoot Dosha is present, which may cause emotional friction — remedies can help."
+        )
+    if boy_mangal and girl_mangal:
+        parts.append(
+            "Both partners have Mangal Dosha, which cancels each other out — compatible in this regard."
+        )
+    elif boy_mangal or girl_mangal:
+        parts.append(
+            "One partner has Mangal Dosha while the other does not — remedies or a Mangalik partner are advised."
+        )
+
+    return " ".join(parts)
+
+
+# ---------------------------------------------------------------------------
+# Main public function
+# ---------------------------------------------------------------------------
+
+
+def get_ashtakoot_milan(chart1: dict, chart2: dict) -> dict:
+    """
+    Compute Ashtakoot Milan (36-point) compatibility between two birth charts.
+
+    Args:
+        chart1: Boy's birth chart from build_chart().
+        chart2: Girl's birth chart from build_chart().
+
+    Returns:
+        Full compatibility report dict.
+    """
+    boy_rashi, boy_nak = _moon_data(chart1)
+    girl_rashi, girl_nak = _moon_data(chart2)
+
+    # Score all 8 kootas
+    varna_score, varna_desc = _score_varna(boy_rashi, girl_rashi)
+    vashya_score, vashya_desc = _score_vashya(boy_rashi, girl_rashi)
+    tara_score, tara_desc = _score_tara(boy_nak, girl_nak)
+    yoni_score, yoni_desc = _score_yoni(boy_nak, girl_nak)
+    gm_score, gm_desc = _score_graha_maitri(boy_rashi, girl_rashi)
+    gana_score, gana_desc = _score_gana(boy_nak, girl_nak)
+    bhakoot_score, bhakoot_desc = _score_bhakoot(boy_rashi, girl_rashi)
+    nadi_score, nadi_desc = _score_nadi(boy_nak, girl_nak)
+
+    total = (
+        varna_score
+        + vashya_score
+        + tara_score
+        + yoni_score
+        + gm_score
+        + gana_score
+        + bhakoot_score
+        + nadi_score
+    )
+
+    nadi_dosha = nadi_score == 0.0
+    bhakoot_dosha = bhakoot_score == 0.0
+    boy_mangal = _has_mangal_dosha(chart1)
+    girl_mangal = _has_mangal_dosha(chart2)
+
+    # Mangal Dosha cancels when both have it
+    mangal_compatible = not (boy_mangal ^ girl_mangal)
+
+    return {
+        "total_score": round(total, 1),
+        "max_score": 36,
+        "percentage": round(total / 36 * 100, 1),
+        "verdict": _verdict(total),
+        "recommendation": _recommendation(
+            total, nadi_dosha, bhakoot_dosha, boy_mangal, girl_mangal
+        ),
+        "kootas": {
+            "varna": {
+                "score": varna_score,
+                "max": 1,
+                "description": varna_desc,
+            },
+            "vashya": {
+                "score": vashya_score,
+                "max": 2,
+                "description": vashya_desc,
+            },
+            "tara": {
+                "score": tara_score,
+                "max": 3,
+                "description": tara_desc,
+            },
+            "yoni": {
+                "score": yoni_score,
+                "max": 4,
+                "description": yoni_desc,
+            },
+            "graha_maitri": {
+                "score": gm_score,
+                "max": 5,
+                "description": gm_desc,
+            },
+            "gana": {
+                "score": gana_score,
+                "max": 6,
+                "description": gana_desc,
+            },
+            "bhakoot": {
+                "score": bhakoot_score,
+                "max": 7,
+                "description": bhakoot_desc,
+            },
+            "nadi": {
+                "score": nadi_score,
+                "max": 8,
+                "description": nadi_desc,
+            },
+        },
+        "boy_moon_rashi": boy_rashi,
+        "girl_moon_rashi": girl_rashi,
+        "boy_nakshatra": boy_nak,
+        "girl_nakshatra": girl_nak,
+        "mangal_dosha_check": {
+            "boy": boy_mangal,
+            "girl": girl_mangal,
+            "compatible": mangal_compatible,
+        },
+    }