kundali-chart-mcp 0.2.1

package/python/kundali_lib/vedic/jaimini.py

@@ -0,0 +1,361 @@
+"""Jaimini astrology: Chara Karakas, Jaimini aspects, and Atmakaraka analysis."""
+
+# ---------------------------------------------------------------------------
+# Constant tables
+# ---------------------------------------------------------------------------
+
+KARAKA_NAMES = [
+    "Atmakaraka",
+    "Amatyakaraka",
+    "Bhratrukaraka",
+    "Matrukaraka",
+    "Putrakaraka",
+    "Gnatikaraka",
+    "Darakaraka",
+]
+
+# Planets used for Chara Karaka calculation (7-karaka system)
+KARAKA_PLANETS = [
+    "Sun",
+    "Moon",
+    "Mars",
+    "Mercury",
+    "Jupiter",
+    "Venus",
+    "Saturn",
+    "Rahu",
+]
+
+# Sign type classification
+MOVABLE_SIGNS = ["Aries", "Cancer", "Libra", "Capricorn"]
+FIXED_SIGNS = ["Taurus", "Leo", "Scorpio", "Aquarius"]
+DUAL_SIGNS = ["Gemini", "Virgo", "Sagittarius", "Pisces"]
+
+# Jaimini aspects: each sign's aspect list (all signs it aspects)
+# Movable aspects Fixed (except adjacent); Fixed aspects Movable (except adjacent);
+# Dual aspects all other Dual signs.
+_JAIMINI_ASPECTS: dict = {
+    "Aries": ["Leo", "Scorpio", "Aquarius"],
+    "Taurus": ["Cancer", "Libra", "Capricorn"],
+    "Gemini": ["Virgo", "Sagittarius", "Pisces"],
+    "Cancer": ["Taurus", "Leo", "Scorpio"],
+    "Leo": ["Aries", "Cancer", "Libra"],
+    "Virgo": ["Gemini", "Sagittarius", "Pisces"],
+    "Libra": ["Taurus", "Leo", "Scorpio"],
+    "Scorpio": ["Aries", "Cancer", "Libra"],
+    "Sagittarius": ["Gemini", "Virgo", "Pisces"],
+    "Capricorn": ["Taurus", "Leo", "Scorpio"],
+    "Aquarius": ["Aries", "Cancer", "Libra"],
+    "Pisces": ["Gemini", "Virgo", "Sagittarius"],
+}
+
+# Navamsha (D9) start rashi for each D1 sign index (0=Aries…11=Pisces)
+# Fire signs (Aries=0, Leo=4, Sagittarius=8) start from Aries (0)
+# Earth signs (Taurus=1, Virgo=5, Capricorn=9) start from Capricorn (9)
+# Air signs  (Gemini=2, Libra=6, Aquarius=10) start from Libra (6)
+# Water signs(Cancer=3, Scorpio=7, Pisces=11) start from Cancer (3)
+_NAVAMSHA_START = {
+    0: 0,
+    1: 9,
+    2: 6,
+    3: 3,
+    4: 0,
+    5: 9,
+    6: 6,
+    7: 3,
+    8: 0,
+    9: 9,
+    10: 6,
+    11: 3,
+}
+
+RASHIS = [
+    "Aries",
+    "Taurus",
+    "Gemini",
+    "Cancer",
+    "Leo",
+    "Virgo",
+    "Libra",
+    "Scorpio",
+    "Sagittarius",
+    "Capricorn",
+    "Aquarius",
+    "Pisces",
+]
+
+# Atmakaraka interpretations keyed by planet
+_AK_INTERPRETATIONS = {
+    "Sun": (
+        "Sun as Atmakaraka indicates a soul driven by authority, recognition, and leadership. "
+        "The native is here to cultivate ego-transcendence through positions of power. "
+        "Lessons around pride, father figures, and governance are central to the life path."
+    ),
+    "Moon": (
+        "Moon as Atmakaraka points to a soul whose deepest lessons revolve around the mind, "
+        "emotions, and nurturing. The native is drawn to healing, home, and the cycles of life. "
+        "Emotional mastery and compassion are the primary spiritual aims."
+    ),
+    "Mars": (
+        "Mars as Atmakaraka signifies a warrior soul whose journey involves courage, discipline, "
+        "and the right use of energy. Past-life themes of conflict and protection emerge. "
+        "The native must channel ambition into dharmic action."
+    ),
+    "Mercury": (
+        "Mercury as Atmakaraka indicates an intellectual soul whose path centers on communication, "
+        "discernment, and adaptability. The native is here to master the spoken and written word "
+        "and to use intelligence in service of truth."
+    ),
+    "Jupiter": (
+        "Jupiter as Atmakaraka reflects a soul with strong dharmic inclinations toward wisdom, "
+        "teaching, and spiritual guidance. The native is here to expand consciousness, share "
+        "knowledge, and uphold righteousness."
+    ),
+    "Venus": (
+        "Venus as Atmakaraka suggests a soul whose evolution is tied to relationships, beauty, "
+        "and creative expression. Themes of love, pleasure, and aesthetic refinement recur. "
+        "The lesson is learning to love without attachment."
+    ),
+    "Saturn": (
+        "Saturn as Atmakaraka is the mark of a soul undergoing deep purification through "
+        "discipline, hardship, and service. The native must cultivate patience, humility, "
+        "and endurance to fulfill a karmic contract of dutiful responsibility."
+    ),
+    "Rahu": (
+        "Rahu as Atmakaraka (rare) indicates an intensely karmic soul carrying unfulfilled "
+        "desires across lifetimes. The native's path involves confronting obsessions and "
+        "illusions in order to achieve liberation through transcending material cravings."
+    ),
+}
+
+_DK_INTERPRETATIONS = {
+    "Sun": "Sun as Darakaraka suggests a partner who is authoritative, proud, and leadership-oriented.",
+    "Moon": "Moon as Darakaraka indicates a partner who is nurturing, emotional, and family-focused.",
+    "Mars": "Mars as Darakaraka points to a partner who is energetic, assertive, and action-driven.",
+    "Mercury": "Mercury as Darakaraka suggests a communicative, intellectual, and versatile partner.",
+    "Jupiter": "Jupiter as Darakaraka indicates a wise, generous, and dharmic partner.",
+    "Venus": "Venus as Darakaraka (uncommon) points to a highly artistic, charming partner.",
+    "Saturn": "Saturn as Darakaraka suggests a disciplined, serious, or much older/younger partner.",
+    "Rahu": "Rahu as Darakaraka indicates an unconventional, foreign, or karmic partner relationship.",
+}
+
+
+# ---------------------------------------------------------------------------
+# Helper: navamsha sign from absolute sidereal longitude
+# ---------------------------------------------------------------------------
+
+
+def _navamsha_rashi(lon: float) -> str:
+    lon = lon % 360
+    rashi_idx = int(lon / 30)
+    degree_in_sign = lon - rashi_idx * 30
+    nav_num = min(int(degree_in_sign / (10.0 / 3.0)), 8)
+    d9_idx = (_NAVAMSHA_START[rashi_idx] + nav_num) % 12
+    return RASHIS[d9_idx]
+
+
+def _sign_type(sign: str) -> str:
+    if sign in MOVABLE_SIGNS:
+        return "Movable"
+    if sign in FIXED_SIGNS:
+        return "Fixed"
+    if sign in DUAL_SIGNS:
+        return "Dual"
+    return "Unknown"
+
+
+# ---------------------------------------------------------------------------
+# Chara Karakas
+# ---------------------------------------------------------------------------
+
+
+def get_jaimini_karakas(planetary_positions: list) -> dict:
+    """
+    Determine the seven Chara Karakas using the Jaimini 7-karaka system.
+
+    Parameters
+    ----------
+    planetary_positions : list
+        List of planet dicts from ``build_chart()``.
+
+    Returns
+    -------
+    dict
+        ``karakas`` mapping karaka name → planet details,
+        ``atmakaraka_analysis``, and ``darakaraka_analysis``.
+    """
+    # Collect degree-in-sign for each karaka planet
+    planet_degrees: list[tuple[str, float, str, int]] = []
+
+    pos_map = {p["name"]: p for p in planetary_positions}
+
+    for planet in KARAKA_PLANETS:
+        p = pos_map.get(planet)
+        if p is None:
+            continue
+
+        degree_in_sign = p["degree"] % 30  # degree within the sign
+
+        # Rahu moves backwards → invert degree for ranking
+        if planet == "Rahu":
+            degree_in_sign = 30.0 - degree_in_sign
+
+        planet_degrees.append(
+            (planet, degree_in_sign, p.get("rashi", ""), p.get("house", 0))
+        )
+
+    # Sort descending by degree_in_sign
+    planet_degrees.sort(key=lambda x: x[1], reverse=True)
+
+    # Assign karakas
+    karakas: dict = {}
+    for i, karaka_name in enumerate(KARAKA_NAMES):
+        if i >= len(planet_degrees):
+            break
+        planet_name, deg, rashi, house = planet_degrees[i]
+        karakas[karaka_name] = {
+            "karaka": karaka_name,
+            "planet": planet_name,
+            "degree_in_sign": round(deg, 3),
+            "rashi": rashi,
+            "house": house,
+        }
+
+    # Interpretations
+    ak_planet = karakas.get("Atmakaraka", {}).get("planet", "Sun")
+    dk_planet = karakas.get("Darakaraka", {}).get("planet", "Venus")
+
+    ak_analysis = _AK_INTERPRETATIONS.get(
+        ak_planet,
+        f"{ak_planet} as Atmakaraka shapes the soul's core lessons in this lifetime.",
+    )
+    dk_analysis = _DK_INTERPRETATIONS.get(
+        dk_planet,
+        f"{dk_planet} as Darakaraka describes the nature of the destined partner.",
+    )
+
+    return {
+        "karakas": karakas,
+        "atmakaraka_analysis": ak_analysis,
+        "darakaraka_analysis": dk_analysis,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Jaimini Aspects
+# ---------------------------------------------------------------------------
+
+
+def get_jaimini_aspects(base_chart: dict) -> dict:
+    """
+    Calculate Jaimini sign-based aspects for each planet.
+
+    Parameters
+    ----------
+    base_chart : dict
+        Output of ``build_chart()``.
+
+    Returns
+    -------
+    dict
+        Keyed by planet name; each value contains sign, sign_type,
+        aspected_signs, and aspected_by.
+    """
+    positions: list = base_chart.get("planetary_positions", [])
+
+    # Build rashi → planets mapping
+    sign_to_planets: dict[str, list[str]] = {}
+    planet_sign: dict[str, str] = {}
+
+    for p in positions:
+        rashi = p.get("rashi", "")
+        name = p["name"]
+        planet_sign[name] = rashi
+        sign_to_planets.setdefault(rashi, []).append(name)
+
+    result: dict = {}
+
+    for p in positions:
+        name = p["name"]
+        sign = p.get("rashi", "")
+        aspected_signs = _JAIMINI_ASPECTS.get(sign, [])
+
+        # Which planets aspect this planet's sign?
+        aspected_by: list[str] = []
+        for other_sign, aspects in _JAIMINI_ASPECTS.items():
+            if sign in aspects:
+                aspected_by.extend(sign_to_planets.get(other_sign, []))
+
+        result[name] = {
+            "planet": name,
+            "sign": sign,
+            "sign_type": _sign_type(sign),
+            "aspected_signs": aspected_signs,
+            "aspected_by": [x for x in aspected_by if x != name],
+        }
+
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Karakamsha
+# ---------------------------------------------------------------------------
+
+
+def get_karakamsha(planetary_positions: list, d9_positions: list) -> dict:
+    """
+    Find the Karakamsha — the sign occupied by the Atmakaraka in the Navamsha (D9).
+
+    Parameters
+    ----------
+    planetary_positions : list
+        D1 (birth chart) planet list from ``build_chart()``.
+    d9_positions : list
+        D9 (Navamsha) planet list. If not available, D9 sign is computed
+        from the Atmakaraka's D1 longitude.
+
+    Returns
+    -------
+    dict
+        Atmakaraka details, Karakamsha sign, Swamsha flag, and interpretation.
+    """
+    karaka_data = get_jaimini_karakas(planetary_positions)
+    ak_info = karaka_data["karakas"].get("Atmakaraka", {})
+    ak_planet = ak_info.get("planet", "Sun")
+    ak_d1_sign = ak_info.get("rashi", "")
+
+    # Try to get D9 sign from d9_positions if provided
+    ak_d9_sign = ""
+    if d9_positions:
+        d9_map = {p["name"]: p for p in d9_positions}
+        ak_d9_sign = d9_map.get(ak_planet, {}).get("rashi", "")
+
+    # Fallback: compute D9 sign from D1 longitude
+    if not ak_d9_sign:
+        pos_map = {p["name"]: p for p in planetary_positions}
+        ak_lon = pos_map.get(ak_planet, {}).get("longitude", 0.0)
+        ak_d9_sign = _navamsha_rashi(ak_lon)
+
+    swamsha = ak_d1_sign == ak_d9_sign
+
+    if swamsha:
+        interp = (
+            f"Swamsha — {ak_planet} occupies the same sign ({ak_d1_sign}) in both D1 and D9. "
+            "This is exceptionally powerful, conferring spiritual depth, self-mastery, and "
+            "heightened manifestation of the Atmakaraka's qualities throughout the life."
+        )
+    else:
+        interp = (
+            f"Karakamsha falls in {ak_d9_sign}. This sign and its lord become a supplementary "
+            f"Lagna for predicting career, spirituality, and the fruits of past-life deeds. "
+            f"The {ak_d9_sign} energy colors how the soul's purpose ({ak_planet} as AK) "
+            "expresses in the outer world."
+        )
+
+    return {
+        "atmakaraka": ak_planet,
+        "atmakaraka_d1_sign": ak_d1_sign,
+        "atmakaraka_d9_sign": ak_d9_sign,
+        "swamsha": swamsha,
+        "interpretation": interp,
+    }

package/python/kundali_lib/vedic/kalachakra.py

@@ -0,0 +1,226 @@
+"""Kalachakra Dasha: the 9-cycle, 112-year sign-based dasha system.
+
+One of the most powerful and complex dasha systems in Vedic astrology.
+Based on birth nakshatra pada position within the 9-group Kalachakra wheel.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta
+from typing import Any
+
+# ── Constants ─────────────────────────────────────────────────────────────────
+
+RASHIS = [
+    "Aries",
+    "Taurus",
+    "Gemini",
+    "Cancer",
+    "Leo",
+    "Virgo",
+    "Libra",
+    "Scorpio",
+    "Sagittarius",
+    "Capricorn",
+    "Aquarius",
+    "Pisces",
+]
+
+# Standard Kalachakra dasha years per sign
+KALACHAKRA_YEARS: dict[str, int] = {
+    "Aries": 7,
+    "Taurus": 16,
+    "Gemini": 9,
+    "Cancer": 21,
+    "Leo": 5,
+    "Virgo": 9,
+    "Libra": 16,
+    "Scorpio": 7,
+    "Sagittarius": 10,
+    "Capricorn": 4,
+    "Aquarius": 4,
+    "Pisces": 4,
+}
+KALACHAKRA_TOTAL = 112  # years per full cycle
+
+# Savya (forward) sign sequence
+_SAVYA = RASHIS[:]  # Aries → Pisces
+
+# Apasavya (reverse) sign sequence
+_APASAVYA = list(reversed(RASHIS))  # Pisces → Aries
+
+# The 9 groups, each containing 12 sign slots mapped by pada index 1-12 within group.
+# Groups alternate Savya / Apasavya.
+# Pada index within group (1-based) selects the sign.
+_GROUPS: list[list[str]] = [
+    _SAVYA,  # Group 1 (padas 1-12)   : Aries…Pisces
+    _APASAVYA,  # Group 2 (padas 13-24)  : Pisces…Aries
+    _SAVYA,  # Group 3 (padas 25-36)
+    _APASAVYA,  # Group 4 (padas 37-48)
+    _SAVYA,  # Group 5 (padas 49-60)
+    _APASAVYA,  # Group 6 (padas 61-72)
+    _SAVYA,  # Group 7 (padas 73-84)
+    _APASAVYA,  # Group 8 (padas 85-96)
+    _SAVYA,  # Group 9 (padas 97-108)
+]
+
+# 27 nakshatras in order
+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",
+]
+
+
+def _pada_global_index(moon_lon: float) -> tuple[int, int, float]:
+    """Return (global_pada 1-108, pada_within_nakshatra 1-4, fraction_elapsed 0-1)."""
+    nakshatra_span = 360.0 / 27
+    pada_span = nakshatra_span / 4
+
+    nak_idx = int(moon_lon / nakshatra_span)  # 0-26
+    pos_in_nak = moon_lon % nakshatra_span
+    pada_in_nak = int(pos_in_nak / pada_span)  # 0-3 within nakshatra
+    fraction = (pos_in_nak % pada_span) / pada_span  # 0-1 elapsed within current pada
+
+    global_pada = nak_idx * 4 + pada_in_nak + 1  # 1-108
+    return global_pada, pada_in_nak + 1, fraction
+
+
+def _starting_sign_and_sequence(global_pada: int) -> tuple[str, list[str]]:
+    """Return (starting_sign, full_sequence_of_12_signs_for_this_group)."""
+    group_idx = (global_pada - 1) // 12  # 0-8
+    pos_in_group = (global_pada - 1) % 12  # 0-11
+
+    group_sequence = _GROUPS[group_idx]
+    starting_sign = group_sequence[pos_in_group]
+
+    # Dasha sequence from starting_sign wraps within the group sequence
+    sequence = group_sequence[pos_in_group:] + group_sequence[:pos_in_group]
+    return starting_sign, sequence
+
+
+def _fmt(dt: datetime) -> str:
+    return dt.strftime("%d-%m-%Y")
+
+
+def _days(years: float) -> float:
+    return years * 365.25
+
+
+# ── Public API ─────────────────────────────────────────────────────────────────
+
+
+def get_kalachakra_dasha(
+    birth_dt: datetime, moon_longitude: float, moon_nakshatra: str
+) -> dict[str, Any]:
+    """Calculate Kalachakra Dasha for a birth chart.
+
+    Parameters
+    ----------
+    birth_dt      : timezone-aware birth datetime
+    moon_longitude: sidereal Moon longitude (0-360)
+    moon_nakshatra: Moon's nakshatra name string
+    """
+    global_pada, pada_in_nak, fraction_elapsed = _pada_global_index(moon_longitude)
+    starting_sign, sign_sequence = _starting_sign_and_sequence(global_pada)
+
+    # Remaining time in birth (starting) sign's dasha
+    birth_sign_years = KALACHAKRA_YEARS[starting_sign]
+    remaining_years = (1.0 - fraction_elapsed) * birth_sign_years
+    remaining_days = _days(remaining_years)
+
+    # First MD ends at birth + remaining days
+    current_end = birth_dt + timedelta(days=remaining_days)
+
+    mahadashas: dict[str, Any] = {}
+    current_start = birth_dt
+
+    for i, sign in enumerate(sign_sequence):
+        years = KALACHAKRA_YEARS[sign]
+        if i == 0:
+            # birth sign — only remaining portion
+            md_days = remaining_days
+        else:
+            md_days = _days(years)
+
+        md_end = current_start + timedelta(days=md_days)
+
+        # ── Antardashas within this MD ────────────────────────────────────
+        # Sub-signs rotate starting from the same sign, same direction as group
+        # Duration: (ad_sign_years / KALACHAKRA_TOTAL) * md_duration_years
+        antardashas: dict[str, Any] = {}
+        ad_start = current_start
+        for j, ad_sign in enumerate(sign_sequence):
+            ad_years_full = KALACHAKRA_YEARS[ad_sign]
+            if i == 0 and j == 0:
+                # first sub within first MD — only remaining fraction of AD too
+                ad_proportion = 1.0 - fraction_elapsed
+                ad_days = _days(
+                    (ad_proportion * ad_years_full * remaining_years) / birth_sign_years
+                )
+            else:
+                ad_days = _days(
+                    (ad_years_full / KALACHAKRA_TOTAL)
+                    * (years if i > 0 else remaining_years)
+                )
+            ad_end = ad_start + timedelta(days=ad_days)
+            antardashas[ad_sign] = {
+                "start": _fmt(ad_start),
+                "end": _fmt(ad_end),
+                "duration_days": round(ad_days, 1),
+            }
+            ad_start = ad_end
+
+        mahadashas[sign] = {
+            "start": _fmt(current_start),
+            "end": _fmt(md_end),
+            "duration_years": round(remaining_years if i == 0 else years, 2),
+            "antardashas": antardashas,
+        }
+        current_start = md_end
+
+    # After one full 112-year cycle, it repeats — annotate
+    second_cycle_start = current_start
+    second_cycle_note = (
+        f"Second cycle starts {_fmt(second_cycle_start)} (repeats from {starting_sign})"
+    )
+
+    return {
+        "system": "Kalachakra Dasha",
+        "total_years_per_cycle": KALACHAKRA_TOTAL,
+        "birth_nakshatra": moon_nakshatra,
+        "birth_pada": pada_in_nak,
+        "global_pada_number": global_pada,
+        "kalachakra_group": ((global_pada - 1) // 12) + 1,
+        "group_direction": "Savya (forward)"
+        if ((global_pada - 1) // 12) % 2 == 0
+        else "Apasavya (reverse)",
+        "starting_sign": starting_sign,
+        "sign_sequence": sign_sequence,
+        "mahadashas": mahadashas,
+        "second_cycle_note": second_cycle_note,
+    }