kundali-chart-mcp 0.2.1

package/python/kundali_lib/vedic/arishta.py

@@ -0,0 +1,465 @@
+"""Arishta Yogas: Longevity assessment and affliction indicators."""
+
+from __future__ import annotations
+
+from kundali_lib.vedic.constants import RASHI_LORDS, RASHIS
+
+# ---------------------------------------------------------------------------
+# Reference data
+# ---------------------------------------------------------------------------
+
+RASHI_LORDS_MAP: dict[str, str] = {r: RASHI_LORDS[i] for i, r in enumerate(RASHIS)}
+
+EXALTATION: dict[str, str] = {
+    "Sun": "Aries",
+    "Moon": "Taurus",
+    "Mars": "Capricorn",
+    "Mercury": "Virgo",
+    "Jupiter": "Cancer",
+    "Venus": "Pisces",
+    "Saturn": "Libra",
+}
+
+DEBILITATION: dict[str, str] = {
+    "Sun": "Libra",
+    "Moon": "Scorpio",
+    "Mars": "Cancer",
+    "Mercury": "Pisces",
+    "Jupiter": "Capricorn",
+    "Venus": "Virgo",
+    "Saturn": "Aries",
+}
+
+OWN_SIGNS: dict[str, list[str]] = {
+    "Sun": ["Leo"],
+    "Moon": ["Cancer"],
+    "Mars": ["Aries", "Scorpio"],
+    "Mercury": ["Gemini", "Virgo"],
+    "Jupiter": ["Sagittarius", "Pisces"],
+    "Venus": ["Taurus", "Libra"],
+    "Saturn": ["Capricorn", "Aquarius"],
+}
+
+FRIENDLY: dict[str, set[str]] = {
+    "Sun": {"Moon", "Mars", "Jupiter"},
+    "Moon": {"Sun", "Mercury"},
+    "Mars": {"Sun", "Moon", "Jupiter"},
+    "Mercury": {"Sun", "Venus"},
+    "Jupiter": {"Sun", "Moon", "Mars"},
+    "Venus": {"Mercury", "Saturn"},
+    "Saturn": {"Mercury", "Venus"},
+}
+
+ENEMY: dict[str, set[str]] = {
+    "Sun": {"Venus", "Saturn"},
+    "Moon": {"Rahu", "Ketu"},
+    "Mars": {"Mercury"},
+    "Mercury": {"Moon"},
+    "Jupiter": {"Mercury", "Venus"},
+    "Venus": {"Sun", "Moon"},
+    "Saturn": {"Sun", "Moon", "Mars"},
+}
+
+MALEFIC_PLANETS = {"Sun", "Mars", "Saturn", "Rahu", "Ketu"}
+BENEFIC_PLANETS = {"Moon", "Mercury", "Jupiter", "Venus"}
+DUSTHANA_HOUSES = {6, 8, 12}
+
+# ---------------------------------------------------------------------------
+# Pindayu years contribution
+# ---------------------------------------------------------------------------
+
+PINDAYU_YEARS: dict[str, dict[str, float]] = {
+    "Sun": {
+        "exalt": 19,
+        "own": 19,
+        "friendly": 15,
+        "neutral": 12,
+        "enemy": 9,
+        "debil": 6,
+    },
+    "Moon": {
+        "exalt": 25,
+        "own": 25,
+        "friendly": 21,
+        "neutral": 16,
+        "enemy": 12,
+        "debil": 8,
+    },
+    "Mars": {
+        "exalt": 15,
+        "own": 15,
+        "friendly": 12,
+        "neutral": 9,
+        "enemy": 7,
+        "debil": 5,
+    },
+    "Mercury": {
+        "exalt": 20,
+        "own": 20,
+        "friendly": 16,
+        "neutral": 12,
+        "enemy": 9,
+        "debil": 7,
+    },
+    "Jupiter": {
+        "exalt": 18,
+        "own": 18,
+        "friendly": 14,
+        "neutral": 11,
+        "enemy": 8,
+        "debil": 6,
+    },
+    "Venus": {
+        "exalt": 20,
+        "own": 20,
+        "friendly": 16,
+        "neutral": 12,
+        "enemy": 9,
+        "debil": 7,
+    },
+    "Saturn": {
+        "exalt": 17,
+        "own": 17,
+        "friendly": 14,
+        "neutral": 11,
+        "enemy": 8,
+        "debil": 5,
+    },
+}
+
+# ---------------------------------------------------------------------------
+# Balarishta conditions
+# ---------------------------------------------------------------------------
+
+BALARISHTA_CONDITIONS: list[dict] = [
+    {
+        "name": "Moon in Papakartari",
+        "check": "Moon hemmed between malefics in 6th/8th from Moon",
+        "severity": "High",
+    },
+    {
+        "name": "Moon with Rahu or Ketu at birth",
+        "check": "Moon conjunct Rahu or Ketu (same house)",
+        "severity": "High",
+    },
+    {
+        "name": "Malefics in 1, 8, 12 without benefic aspect",
+        "check": "Sun/Mars/Saturn/Rahu/Ketu in 1st/8th/12th houses",
+        "severity": "Medium",
+    },
+    {
+        "name": "Moon in dusthana in weak state",
+        "check": "Moon in 6th, 8th, or 12th in debilitation or enemy's sign",
+        "severity": "Medium",
+    },
+    {
+        "name": "Exchange between 1st and 8th lords",
+        "check": "Lord of 8th in 1st or Lord of 1st in 8th",
+        "severity": "High",
+    },
+]
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _get_planet(positions: list[dict], name: str) -> dict | None:
+    for p in positions:
+        if p["name"] == name:
+            return p
+    return None
+
+
+def _planet_sign_relationship(planet_name: str, rashi: str) -> str:
+    """Return 'exalt', 'debil', 'own', 'friendly', 'enemy', or 'neutral'."""
+    if EXALTATION.get(planet_name) == rashi:
+        return "exalt"
+    if DEBILITATION.get(planet_name) == rashi:
+        return "debil"
+    if rashi in OWN_SIGNS.get(planet_name, []):
+        return "own"
+    lord = RASHI_LORDS_MAP.get(rashi)
+    if lord in FRIENDLY.get(planet_name, set()):
+        return "friendly"
+    if lord in ENEMY.get(planet_name, set()):
+        return "enemy"
+    return "neutral"
+
+
+def _pindayu_for(planet: dict) -> float:
+    name = planet["name"]
+    if name not in PINDAYU_YEARS:
+        return 0.0
+    rel = _planet_sign_relationship(name, planet.get("rashi", ""))
+    return float(PINDAYU_YEARS[name].get(rel, PINDAYU_YEARS[name]["neutral"]))
+
+
+def _planets_in_house(positions: list[dict], house: int) -> list[str]:
+    return [p["name"] for p in positions if p.get("house", 0) == house]
+
+
+def _has_benefic_aspect(positions: list[dict], house: int, asc_sign: str) -> bool:
+    """Simplified: check if any benefic planet aspects the given house (7th aspect)."""
+    for p in positions:
+        if p["name"] in BENEFIC_PLANETS:
+            planet_house = p.get("house", 0)
+            if (planet_house - 1) % 12 == (house - 7) % 12:
+                return True
+    return False
+
+
+# ---------------------------------------------------------------------------
+# Balarishta condition evaluators
+# ---------------------------------------------------------------------------
+
+
+def _eval_moon_papakartari(positions: list[dict]) -> bool:
+    """Moon hemmed between malefics (malefic in 6th and 8th from Moon)."""
+    moon = _get_planet(positions, "Moon")
+    if not moon:
+        return False
+    moon_house = moon.get("house", 0)
+    house_6_from_moon = (moon_house + 4) % 12 + 1  # 6th from Moon
+    house_8_from_moon = (moon_house + 6) % 12 + 1  # 8th from Moon
+    planets_6 = _planets_in_house(positions, house_6_from_moon)
+    planets_8 = _planets_in_house(positions, house_8_from_moon)
+    has_malefic_6 = any(n in MALEFIC_PLANETS for n in planets_6)
+    has_malefic_8 = any(n in MALEFIC_PLANETS for n in planets_8)
+    return has_malefic_6 and has_malefic_8
+
+
+def _eval_moon_with_nodes(positions: list[dict]) -> bool:
+    moon = _get_planet(positions, "Moon")
+    if not moon:
+        return False
+    moon_house = moon.get("house", 0)
+    return any(
+        _get_planet(positions, n)
+        and _get_planet(positions, n).get("house", 0) == moon_house
+        for n in ("Rahu", "Ketu")
+    )
+
+
+def _eval_malefics_in_1_8_12(positions: list[dict], asc_sign: str) -> bool:
+    afflicted_houses = set()
+    for p in positions:
+        if p["name"] in MALEFIC_PLANETS and p.get("house", 0) in {1, 8, 12}:
+            if not _has_benefic_aspect(positions, p.get("house", 0), asc_sign):
+                afflicted_houses.add(p.get("house", 0))
+    return len(afflicted_houses) >= 2
+
+
+def _eval_moon_in_dusthana_weak(positions: list[dict]) -> bool:
+    moon = _get_planet(positions, "Moon")
+    if not moon:
+        return False
+    house = moon.get("house", 0)
+    if house not in DUSTHANA_HOUSES:
+        return False
+    rel = _planet_sign_relationship("Moon", moon.get("rashi", ""))
+    return rel in ("debil", "enemy")
+
+
+def _eval_1st_8th_exchange(positions: list[dict], asc_sign: str) -> bool:
+    asc_idx = RASHIS.index(asc_sign)
+    eighth_sign = RASHIS[(asc_idx + 7) % 12]
+    first_lord = RASHI_LORDS_MAP.get(asc_sign)
+    eighth_lord = RASHI_LORDS_MAP.get(eighth_sign)
+    if not first_lord or not eighth_lord:
+        return False
+    first_lord_planet = _get_planet(positions, first_lord)
+    eighth_lord_planet = _get_planet(positions, eighth_lord)
+    if not first_lord_planet or not eighth_lord_planet:
+        return False
+    # Exchange: 1st lord in 8th house or 8th lord in 1st house
+    return (
+        first_lord_planet.get("house", 0) == 8
+        or eighth_lord_planet.get("house", 0) == 1
+    )
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def get_arishta_yogas(base_chart: dict) -> dict:
+    """Assess longevity and Arishta yogas from a birth chart.
+
+    Args:
+        base_chart: Output of ``build_chart()``.
+
+    Returns:
+        dict with Balarishta conditions, longevity category, Pindayu years
+        estimate, 8th house analysis, and overall Arishta assessment.
+    """
+    positions: list[dict] = base_chart.get("planetary_positions", [])
+    asc_info: dict = base_chart.get("ascendant", {})
+    asc_sign: str = asc_info.get("rashi", RASHIS[0])
+    asc_idx = RASHIS.index(asc_sign)
+
+    # ── Balarishta evaluation ─────────────────────────────────────────────────
+    evaluators = [
+        _eval_moon_papakartari,
+        _eval_moon_with_nodes,
+        lambda pos: _eval_malefics_in_1_8_12(pos, asc_sign),
+        _eval_moon_in_dusthana_weak,
+        lambda pos: _eval_1st_8th_exchange(pos, asc_sign),
+    ]
+
+    balarishta_results: list[dict] = []
+    for condition, evaluator in zip(BALARISHTA_CONDITIONS, evaluators):
+        present = evaluator(positions)
+        balarishta_results.append(
+            {
+                "name": condition["name"],
+                "present": present,
+                "description": condition["check"],
+                "severity": condition["severity"],
+            }
+        )
+
+    high_count = sum(
+        1 for b in balarishta_results if b["present"] and b["severity"] == "High"
+    )
+    med_count = sum(
+        1 for b in balarishta_results if b["present"] and b["severity"] == "Medium"
+    )
+    arishta_present = high_count >= 1 or med_count >= 2
+
+    # ── Arishta type ──────────────────────────────────────────────────────────
+    alparishta = False
+    # Alparishta: malefics simultaneously in 1, 8, 12
+    houses_with_malefics = {
+        p.get("house", 0) for p in positions if p["name"] in MALEFIC_PLANETS
+    }
+    if houses_with_malefics.issuperset({1, 8, 12}):
+        alparishta = True
+    # Classic Alparishta: Saturn in Lagna, Moon in 8th, Sun in 7th
+    saturn = _get_planet(positions, "Saturn")
+    moon = _get_planet(positions, "Moon")
+    sun = _get_planet(positions, "Sun")
+    if (
+        saturn
+        and saturn.get("house", 0) == 1
+        and moon
+        and moon.get("house", 0) == 8
+        and sun
+        and sun.get("house", 0) == 7
+    ):
+        alparishta = True
+
+    if arishta_present and alparishta:
+        arishta_type: str | None = "Alparishta (short life threat, 0-32 years)"
+    elif arishta_present and high_count >= 1:
+        arishta_type = "Balarishta (early life affliction)"
+    elif arishta_present:
+        arishta_type = "Madhyarishta (medium life affliction)"
+    else:
+        arishta_type = None
+
+    # ── Pindayu calculation (Sun + Moon + Lagna lord) ─────────────────────────
+    lagna_lord_name = RASHI_LORDS_MAP.get(asc_sign, "")
+    sun_planet = _get_planet(positions, "Sun")
+    moon_planet = _get_planet(positions, "Moon")
+    lagna_lord_planet = _get_planet(positions, lagna_lord_name)
+
+    pindayu_sun = _pindayu_for(sun_planet) if sun_planet else 0.0
+    pindayu_moon = _pindayu_for(moon_planet) if moon_planet else 0.0
+    pindayu_ll = _pindayu_for(lagna_lord_planet) if lagna_lord_planet else 0.0
+    pindayu_total = pindayu_sun + pindayu_moon + pindayu_ll
+
+    # ── Longevity category ────────────────────────────────────────────────────
+    if pindayu_total >= 66 and not arishta_present:
+        longevity_category = "Long (75+ years)"
+    elif pindayu_total >= 36:
+        longevity_category = "Medium (36-75 years)"
+    else:
+        longevity_category = "Short (<36 years)"
+
+    # ── Eighth house analysis ─────────────────────────────────────────────────
+    eighth_sign = RASHIS[(asc_idx + 7) % 12]
+    eighth_lord_name = RASHI_LORDS_MAP[eighth_sign]
+    eighth_lord_planet = _get_planet(positions, eighth_lord_name)
+    eighth_lord_position = (
+        f"House {eighth_lord_planet.get('house', '?')} in {eighth_lord_planet.get('rashi', '?')}"
+        if eighth_lord_planet
+        else "Unknown"
+    )
+    planets_in_8 = _planets_in_house(positions, 8)
+
+    eighth_rel = _planet_sign_relationship(
+        eighth_lord_name,
+        eighth_lord_planet.get("rashi", "") if eighth_lord_planet else "",
+    )
+    eighth_strength = (
+        "Strong"
+        if eighth_rel in ("exalt", "own")
+        else "Weak"
+        if eighth_rel in ("debil", "enemy")
+        else "Moderate"
+    )
+
+    # ── Cancellation factors ──────────────────────────────────────────────────
+    cancellation: list[str] = []
+    jupiter = _get_planet(positions, "Jupiter")
+    if jupiter and jupiter.get("house", 0) in {1, 5, 9}:
+        cancellation.append("Jupiter in trikona mitigates Arishta")
+    if (
+        moon_planet
+        and _planet_sign_relationship("Moon", moon_planet.get("rashi", "")) == "exalt"
+    ):
+        cancellation.append("Exalted Moon reduces early affliction severity")
+    if lagna_lord_planet and lagna_lord_planet.get("house", 0) in {1, 4, 7, 10}:
+        cancellation.append("Lagna lord in kendra provides resilience")
+    if not cancellation and arishta_present:
+        cancellation.append("No strong cancellation factors found")
+    elif not cancellation:
+        cancellation.append("Chart has no significant Arishta; no cancellation needed")
+
+    # ── Summary ───────────────────────────────────────────────────────────────
+    active_balarishta = [b["name"] for b in balarishta_results if b["present"]]
+    summary_parts = [
+        f"Longevity category: {longevity_category}.",
+        f"Pindayu indicator: Sun={pindayu_sun}, Moon={pindayu_moon}, "
+        f"Lagna lord={pindayu_ll} → Total={pindayu_total} years (indicative).",
+    ]
+    if arishta_present:
+        summary_parts.append(
+            f"Arishta type: {arishta_type}. Active conditions: {', '.join(active_balarishta)}."
+        )
+    else:
+        summary_parts.append("No significant Arishta yoga detected.")
+    if cancellation:
+        summary_parts.append(f"Mitigating factors: {'; '.join(cancellation)}.")
+
+    return {
+        "balarishta_conditions": balarishta_results,
+        "longevity_category": longevity_category,
+        "pindayu_years": {
+            "Sun": pindayu_sun,
+            "Moon": pindayu_moon,
+            "Lagna_lord": pindayu_ll,
+            "total_indicator": pindayu_total,
+            "note": (
+                "Pindayu sum for Sun + Moon + Lagna lord only. "
+                "Full Pindayu includes all seven planets with various divisors."
+            ),
+        },
+        "eighth_house_analysis": {
+            "eighth_lord": eighth_lord_name,
+            "eighth_lord_position": eighth_lord_position,
+            "planets_in_eighth": planets_in_8,
+            "strength": eighth_strength,
+        },
+        "arishta_present": arishta_present,
+        "arishta_type": arishta_type,
+        "cancellation_factors": cancellation,
+        "summary": " ".join(summary_parts),
+        "disclaimer": (
+            "Longevity calculation is indicative only. "
+            "Modern Vedic astrologers use this as one of many tools."
+        ),
+    }

package/python/kundali_lib/vedic/ashtakavarga.py

@@ -0,0 +1,213 @@
+"""Ashtakavarga: mathematical benefic point system for transit predictions.
+
+Each of 7 classical planets (Sun through Saturn) receives benefic points (0 or 1)
+contributed by every other planet plus the Lagna, based on traditional Parashari
+tables.  The resulting per-planet scores (Bhinnashtakavarga, BAV) are summed into
+a 12-house total (Sarvashtakavarga, SAV) which guides transit interpretation.
+"""
+
+# ── Parashari contribution tables ────────────────────────────────────────────
+# For each target planet the dict maps contributor → list of house offsets
+# (1-based, measured FROM the contributor) that receive one benefic point.
+
+SUN_CONTRIBUTIONS: dict[str, list[int]] = {
+    "Sun": [1, 2, 4, 7, 8, 9, 10, 11],
+    "Moon": [3, 6, 10, 11],
+    "Mars": [1, 2, 4, 7, 8, 9, 10, 11],
+    "Mercury": [3, 5, 6, 9, 12],
+    "Jupiter": [5, 6, 9, 11],
+    "Venus": [6, 7, 12],
+    "Saturn": [1, 2, 4, 7, 8, 9, 10, 11],
+    "Lagna": [3, 4, 6, 10, 11, 12],
+}
+
+MOON_CONTRIBUTIONS: dict[str, list[int]] = {
+    "Sun": [3, 6, 7, 8, 10, 11],
+    "Moon": [1, 3, 6, 7, 10, 11],
+    "Mars": [2, 3, 5, 6, 9, 10, 11],
+    "Mercury": [1, 3, 4, 5, 7, 8, 10, 11],
+    "Jupiter": [1, 4, 7, 8, 10, 11, 12],
+    "Venus": [3, 4, 5, 7, 9, 10, 11],
+    "Saturn": [3, 5, 6, 11],
+    "Lagna": [3, 6, 10, 11],
+}
+
+MARS_CONTRIBUTIONS: dict[str, list[int]] = {
+    "Sun": [3, 5, 6, 10, 11],
+    "Moon": [3, 6, 11],
+    "Mars": [1, 2, 4, 7, 8, 10, 11],
+    "Mercury": [3, 5, 6],
+    "Jupiter": [6, 10, 11, 12],
+    "Venus": [6, 8, 11, 12],
+    "Saturn": [1, 4, 7, 8, 9, 10, 11],
+    "Lagna": [1, 3, 6, 10, 11],
+}
+
+MERCURY_CONTRIBUTIONS: dict[str, list[int]] = {
+    "Sun": [5, 6, 9, 11, 12],
+    "Moon": [2, 4, 6, 8, 10, 11],
+    "Mars": [1, 2, 4, 7, 8, 9, 10, 11],
+    "Mercury": [1, 3, 5, 6, 9, 10, 11, 12],
+    "Jupiter": [6, 8, 11, 12],
+    "Venus": [1, 2, 3, 4, 5, 8, 9, 11],
+    "Saturn": [1, 2, 4, 7, 8, 9, 10, 11],
+    "Lagna": [1, 2, 4, 6, 8, 10, 11],
+}
+
+JUPITER_CONTRIBUTIONS: dict[str, list[int]] = {
+    "Sun": [1, 2, 3, 4, 7, 8, 9, 10, 11],
+    "Moon": [2, 5, 7, 9, 11],
+    "Mars": [1, 2, 4, 7, 8, 10, 11],
+    "Mercury": [1, 2, 4, 5, 6, 9, 10, 11],
+    "Jupiter": [1, 2, 3, 4, 7, 8, 10, 11],
+    "Venus": [2, 5, 6, 9, 10, 11],
+    "Saturn": [3, 5, 6, 12],
+    "Lagna": [1, 2, 4, 5, 6, 7, 9, 10, 11],
+}
+
+VENUS_CONTRIBUTIONS: dict[str, list[int]] = {
+    "Sun": [8, 11, 12],
+    "Moon": [1, 2, 3, 4, 5, 8, 9, 11, 12],
+    "Mars": [3, 4, 6, 9, 11, 12],
+    "Mercury": [3, 5, 6, 9, 11],
+    "Jupiter": [5, 8, 9, 10, 11],
+    "Venus": [1, 2, 3, 4, 5, 8, 9, 10, 11],
+    "Saturn": [3, 4, 5, 8, 9, 10, 11],
+    "Lagna": [1, 2, 3, 4, 5, 8, 9, 11],
+}
+
+SATURN_CONTRIBUTIONS: dict[str, list[int]] = {
+    "Sun": [1, 2, 4, 7, 8, 10, 11],
+    "Moon": [3, 6, 11],
+    "Mars": [3, 5, 6, 10, 11, 12],
+    "Mercury": [6, 8, 9, 10, 11, 12],
+    "Jupiter": [5, 6, 11, 12],
+    "Venus": [6, 11, 12],
+    "Saturn": [3, 5, 6, 11],
+    "Lagna": [1, 3, 4, 6, 10, 11],
+}
+
+# Ordered list of target planets and their contribution tables
+_TARGET_PLANETS: list[str] = [
+    "Sun",
+    "Moon",
+    "Mars",
+    "Mercury",
+    "Jupiter",
+    "Venus",
+    "Saturn",
+]
+
+_CONTRIBUTIONS: dict[str, dict[str, list[int]]] = {
+    "Sun": SUN_CONTRIBUTIONS,
+    "Moon": MOON_CONTRIBUTIONS,
+    "Mars": MARS_CONTRIBUTIONS,
+    "Mercury": MERCURY_CONTRIBUTIONS,
+    "Jupiter": JUPITER_CONTRIBUTIONS,
+    "Venus": VENUS_CONTRIBUTIONS,
+    "Saturn": SATURN_CONTRIBUTIONS,
+}
+
+# BAV strength thresholds (points out of 8 per house)
+_BAV_STRONG = 5
+_BAV_MODERATE = 4
+# SAV strength thresholds (sum of 7 planets = max ~337 per house)
+_SAV_EXCELLENT = 28
+_SAV_GOOD = 22
+_SAV_AVERAGE = 16
+
+
+# ── Private helpers ───────────────────────────────────────────────────────────
+
+
+def _empty_house_scores() -> dict[str, int]:
+    return {f"House_{h}": 0 for h in range(1, 13)}
+
+
+def _compute_bav(
+    target_planet: str,
+    planet_houses: dict[str, int],
+    lagna_house: int = 1,
+) -> dict[str, int]:
+    """Compute Bhinnashtakavarga (BAV) for one target planet.
+
+    For each contributing planet / Lagna, for each benefic offset in its table,
+    the house that lands at (contributor_house + offset - 1) receives +1 point.
+    """
+    scores = _empty_house_scores()
+    table = _CONTRIBUTIONS[target_planet]
+
+    for contributor, offsets in table.items():
+        if contributor == "Lagna":
+            contrib_house = lagna_house
+        else:
+            contrib_house = planet_houses.get(contributor)
+            if contrib_house is None:
+                continue  # planet absent from chart (e.g. outer planets)
+
+        for offset in offsets:
+            # offset=1 → same house as contributor; offset=2 → next house; etc.
+            target_house = (contrib_house - 1 + offset - 1) % 12 + 1
+            scores[f"House_{target_house}"] += 1
+
+    scores["total"] = sum(scores[f"House_{h}"] for h in range(1, 13))
+    return scores
+
+
+def _sav_interpretation(score: int) -> str:
+    if score >= _SAV_EXCELLENT:
+        return "Excellent (>=28)"
+    if score >= _SAV_GOOD:
+        return "Good (22-27)"
+    if score >= _SAV_AVERAGE:
+        return "Average (16-21)"
+    return "Weak (<16)"
+
+
+# ── Public API ────────────────────────────────────────────────────────────────
+
+
+def get_ashtakavarga(base_chart: dict) -> dict:
+    """Calculate Ashtakavarga from a built chart dict.
+
+    Args:
+        base_chart: Output of ``build_chart()`` — must contain
+                    ``planetary_positions`` (list with ``name`` and ``house`` keys).
+
+    Returns:
+        dict with three keys:
+
+        * ``bhinnashtakavarga``: per-planet 12-house benefic scores + total.
+        * ``sarvashtakavarga``: sum of all 7 planets per house + total.
+        * ``interpretation``: SAV strength label per house.
+    """
+    # Extract house numbers for each planet
+    planet_houses: dict[str, int] = {
+        p["name"]: p["house"] for p in base_chart["planetary_positions"]
+    }
+
+    # Lagna always occupies house 1 by definition
+    lagna_house = 1
+
+    # ── Bhinnashtakavarga (BAV) ──────────────────────────────────────────────
+    bav: dict[str, dict[str, int]] = {}
+    for target_planet in _TARGET_PLANETS:
+        bav[target_planet] = _compute_bav(target_planet, planet_houses, lagna_house)
+
+    # ── Sarvashtakavarga (SAV) ───────────────────────────────────────────────
+    sav = _empty_house_scores()
+    for planet in _TARGET_PLANETS:
+        for h in range(1, 13):
+            sav[f"House_{h}"] += bav[planet][f"House_{h}"]
+    sav["total"] = sum(sav[f"House_{h}"] for h in range(1, 13))
+
+    # ── Interpretation ───────────────────────────────────────────────────────
+    interpretation: dict[str, str] = {
+        f"House_{h}": _sav_interpretation(sav[f"House_{h}"]) for h in range(1, 13)
+    }
+
+    return {
+        "bhinnashtakavarga": bav,
+        "sarvashtakavarga": sav,
+        "interpretation": interpretation,
+    }