kundali-chart-mcp 0.2.1

package/python/kundali_lib/vedic/kartari.py

@@ -0,0 +1,243 @@
+"""Kartari Yoga: planets hemmed between benefics (Subha) or malefics (Papa)."""
+
+# ---------------------------------------------------------------------------
+# Reference data
+# ---------------------------------------------------------------------------
+
+_NATURAL_BENEFICS = {"Moon", "Mercury", "Jupiter", "Venus"}
+_NATURAL_MALEFICS = {"Sun", "Mars", "Saturn", "Rahu", "Ketu"}
+
+
+def _planet_type(name: str) -> str:
+    """Return 'benefic', 'malefic', or 'neutral' for a planet name."""
+    if name in _NATURAL_BENEFICS:
+        return "benefic"
+    if name in _NATURAL_MALEFICS:
+        return "malefic"
+    return "neutral"
+
+
+def _dominant_type(planet_names: list) -> str:
+    """Return the dominant type among a list of planet names."""
+    if not planet_names:
+        return "empty"
+    types = [_planet_type(n) for n in planet_names]
+    benefic_count = types.count("benefic")
+    malefic_count = types.count("malefic")
+    if benefic_count > 0 and malefic_count == 0:
+        return "benefic"
+    if malefic_count > 0 and benefic_count == 0:
+        return "malefic"
+    if benefic_count > 0 and malefic_count > 0:
+        return "mixed"
+    return "neutral"
+
+
+def _adjacent_houses(house: int) -> tuple:
+    """Return the (preceding, following) house numbers (1–12, wrapping)."""
+    preceding = ((house - 2) % 12) + 1
+    following = (house % 12) + 1
+    return preceding, following
+
+
+# ---------------------------------------------------------------------------
+# Main function
+# ---------------------------------------------------------------------------
+
+
+def check_kartari_yoga(planetary_positions: list, houses: dict) -> list:
+    """Detect Kartari Yoga for every occupied house and every planet.
+
+    Parameters
+    ----------
+    planetary_positions : list
+        Each item is a planet dict with at least ``name`` and ``house``.
+    houses : dict
+        Maps house number (int) to a list of planet name strings
+        present in that house.  E.g. ``{1: ["Sun"], 7: ["Mars", "Venus"]}``.
+        Houses with no planets should either be absent or map to ``[]``.
+
+    Returns
+    -------
+    list of dict
+        One entry per planet/point that is hemmed between two occupied houses.
+        Includes special Paapa Kartari on Lagna and Subha Kartari on Moon
+        annotations.
+    """
+    results = []
+    seen_houses = set()  # avoid duplicating house checks
+
+    # ----------------------------------------------------------------
+    # Per-planet analysis
+    # ----------------------------------------------------------------
+    for planet in planetary_positions:
+        name = planet["name"]
+        house = planet["house"]
+
+        pre_house, fol_house = _adjacent_houses(house)
+        pre_planets = houses.get(pre_house, [])
+        fol_planets = houses.get(fol_house, [])
+
+        pre_type = _dominant_type(pre_planets)
+        fol_type = _dominant_type(fol_planets)
+
+        # A Kartari Yoga requires at least one planet on each side
+        if not pre_planets or not fol_planets:
+            continue
+
+        if pre_type in ("benefic", "malefic") and pre_type == fol_type:
+            yoga_type = "Subha Kartari" if pre_type == "benefic" else "Papa Kartari"
+        elif pre_type == "mixed" or fol_type == "mixed":
+            yoga_type = "Mixed Kartari"
+        elif pre_type in ("benefic", "malefic") and fol_type in ("benefic", "malefic"):
+            yoga_type = "Mixed Kartari"
+        else:
+            continue  # neutral/empty — no Kartari
+
+        effect = (
+            "Highly beneficial — planet's significations are enhanced"
+            if yoga_type == "Subha Kartari"
+            else (
+                "Harmful — planet's significations are suppressed/afflicted"
+                if yoga_type == "Papa Kartari"
+                else "Mixed results — conflicting influences on either side"
+            )
+        )
+
+        results.append(
+            {
+                "planet_or_house": name,
+                "house_number": house,
+                "yoga_type": yoga_type,
+                "preceding_house": pre_house,
+                "following_house": fol_house,
+                "preceding_planets": list(pre_planets),
+                "following_planets": list(fol_planets),
+                "effect": effect,
+                "strength": "Strong",
+            }
+        )
+        seen_houses.add(house)
+
+    # ----------------------------------------------------------------
+    # Per-occupied-house analysis (catches houses with planets that
+    # might be hemmed even if individual planets were already checked,
+    # but primarily adds house-level entries not covered above)
+    # ----------------------------------------------------------------
+    all_occupied = set(h for h, plist in houses.items() if plist)
+
+    for house in sorted(all_occupied):
+        if house in seen_houses:
+            continue  # already handled via a planet entry
+
+        pre_house, fol_house = _adjacent_houses(house)
+        pre_planets = houses.get(pre_house, [])
+        fol_planets = houses.get(fol_house, [])
+
+        if not pre_planets or not fol_planets:
+            continue
+
+        pre_type = _dominant_type(pre_planets)
+        fol_type = _dominant_type(fol_planets)
+
+        if pre_type in ("benefic", "malefic") and pre_type == fol_type:
+            yoga_type = "Subha Kartari" if pre_type == "benefic" else "Papa Kartari"
+        elif pre_type in ("benefic", "malefic") and fol_type in ("benefic", "malefic"):
+            yoga_type = "Mixed Kartari"
+        else:
+            continue
+
+        effect = (
+            "Highly beneficial — house significations are protected and enhanced"
+            if yoga_type == "Subha Kartari"
+            else (
+                "Harmful — house significations are hemmed and afflicted"
+                if yoga_type == "Papa Kartari"
+                else "Mixed results — conflicting influences on either side"
+            )
+        )
+
+        results.append(
+            {
+                "planet_or_house": f"House_{house}",
+                "house_number": house,
+                "yoga_type": yoga_type,
+                "preceding_house": pre_house,
+                "following_house": fol_house,
+                "preceding_planets": list(pre_planets),
+                "following_planets": list(fol_planets),
+                "effect": effect,
+                "strength": "Strong",
+            }
+        )
+
+    # ----------------------------------------------------------------
+    # Special checks
+    # ----------------------------------------------------------------
+    _check_paapa_kartari_lagna(houses, results)
+    _check_subha_kartari_moon(planetary_positions, houses, results)
+
+    return results
+
+
+def _check_paapa_kartari_lagna(houses: dict, results: list) -> None:
+    """Annotate if both 2nd and 12th houses from Lagna are occupied by malefics."""
+    h2 = houses.get(2, [])
+    h12 = houses.get(12, [])
+    if not h2 or not h12:
+        return
+    if _dominant_type(h2) == "malefic" and _dominant_type(h12) == "malefic":
+        results.append(
+            {
+                "planet_or_house": "Lagna (Special — Paapa Kartari)",
+                "house_number": 1,
+                "yoga_type": "Papa Kartari",
+                "preceding_house": 12,
+                "following_house": 2,
+                "preceding_planets": list(h12),
+                "following_planets": list(h2),
+                "effect": (
+                    "Very harmful — Lagna hemmed between malefics. "
+                    "Physical constitution and self-expression are strongly afflicted."
+                ),
+                "strength": "Strong",
+            }
+        )
+
+
+def _check_subha_kartari_moon(
+    planetary_positions: list, houses: dict, results: list
+) -> None:
+    """Annotate if Moon is hemmed by benefics on both sides (Durudhura Yoga)."""
+    moon = next((p for p in planetary_positions if p["name"] == "Moon"), None)
+    if moon is None:
+        return
+
+    moon_house = moon["house"]
+    pre_house, fol_house = _adjacent_houses(moon_house)
+    pre_planets = houses.get(pre_house, [])
+    fol_planets = houses.get(fol_house, [])
+
+    if not pre_planets or not fol_planets:
+        return
+
+    if (
+        _dominant_type(pre_planets) == "benefic"
+        and _dominant_type(fol_planets) == "benefic"
+    ):
+        results.append(
+            {
+                "planet_or_house": "Moon (Special — Durudhura Yoga)",
+                "house_number": moon_house,
+                "yoga_type": "Subha Kartari",
+                "preceding_house": pre_house,
+                "following_house": fol_house,
+                "preceding_planets": list(pre_planets),
+                "following_planets": list(fol_planets),
+                "effect": (
+                    "Very auspicious — Moon flanked by benefics (Durudhura Yoga). "
+                    "Prosperity, fame, and good fortune throughout life."
+                ),
+                "strength": "Strong",
+            }
+        )

package/python/kundali_lib/vedic/kurmachakra.py

@@ -0,0 +1,383 @@
+"""Kurmachakra: geographical direction system for auspicious travel and construction Muhurta.
+
+The Kurmachakra (Tortoise Wheel) maps the 27 Nakshatras to the 8 cardinal directions
+plus a centre/upward direction. It is used to determine:
+  1. Auspicious travel directions based on birth nakshatra (avoid the bad direction)
+  2. Current Moon nakshatra direction (avoid travelling in that direction on that day)
+  3. Auspicious directions for construction, marriage, and major events
+  4. Monthly/daily directional strength using the Moon's nakshatra
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+# ── Core mapping ───────────────────────────────────────────────────────────────
+
+# The 27 Nakshatras mapped to 8 directions + Centre (9 slots × 3 nakshatras each)
+NAKSHATRA_DIRECTION: dict[str, str] = {
+    # East (Purva)
+    "Ashwini": "East",
+    "Bharani": "East",
+    "Krittika": "East",
+    # South-East (Agneya)
+    "Rohini": "South-East",
+    "Mrigashira": "South-East",
+    "Ardra": "South-East",
+    # South (Dakshina)
+    "Punarvasu": "South",
+    "Pushya": "South",
+    "Ashlesha": "South",
+    # South-West (Nairutya)
+    "Magha": "South-West",
+    "Purva Phalguni": "South-West",
+    "Uttara Phalguni": "South-West",
+    # West (Pashchima)
+    "Hasta": "West",
+    "Chitra": "West",
+    "Swati": "West",
+    # North-West (Vayavya)
+    "Vishakha": "North-West",
+    "Anuradha": "North-West",
+    "Jyeshtha": "North-West",
+    # North (Uttara)
+    "Mula": "North",
+    "Purva Ashadha": "North",
+    "Uttara Ashadha": "North",
+    # North-East (Ishanya)
+    "Shravana": "North-East",
+    "Dhanishta": "North-East",
+    "Shatabhisha": "North-East",
+    # Centre / Upward (Urdhva / Brahma)
+    "Purva Bhadrapada": "Centre",
+    "Uttara Bhadrapada": "Centre",
+    "Revati": "Centre",
+}
+
+DIRECTIONS_ORDER = [
+    "East",
+    "South-East",
+    "South",
+    "South-West",
+    "West",
+    "North-West",
+    "North",
+    "North-East",
+    "Centre",
+]
+
+# Sanskrit names
+DIRECTION_SANSKRIT: dict[str, str] = {
+    "East": "Purva",
+    "South-East": "Agneya",
+    "South": "Dakshina",
+    "South-West": "Nairutya",
+    "West": "Pashchima",
+    "North-West": "Vayavya",
+    "North": "Uttara",
+    "North-East": "Ishanya",
+    "Centre": "Urdhva (Brahma)",
+}
+
+# General auspiciousness for travel by direction (contextual — depends on event)
+DIRECTION_GENERAL: dict[str, dict[str, str]] = {
+    "East": {
+        "nature": "Highly auspicious",
+        "good_for": "Education, jobs, seeking blessings from elders",
+        "avoid": "Nothing specific",
+    },
+    "South-East": {
+        "nature": "Mixed",
+        "good_for": "Trade, cooking, fire-related activities",
+        "avoid": "Long journeys",
+    },
+    "South": {
+        "nature": "Inauspicious",
+        "good_for": "War, competition, debt collection",
+        "avoid": "General travel, marriage, new ventures",
+    },
+    "South-West": {
+        "nature": "Inauspicious",
+        "good_for": "Endings, wrapping up matters",
+        "avoid": "New beginnings, travel, construction",
+    },
+    "West": {
+        "nature": "Neutral to auspicious",
+        "good_for": "Business, trade, water activities",
+        "avoid": "Aggressive activities",
+    },
+    "North-West": {
+        "nature": "Mixed",
+        "good_for": "Quick travel, messages, communication",
+        "avoid": "Long-term ventures",
+    },
+    "North": {
+        "nature": "Auspicious",
+        "good_for": "Wealth, new ventures, prosperity",
+        "avoid": "Nothing specific",
+    },
+    "North-East": {
+        "nature": "Highly auspicious",
+        "good_for": "Worship, spiritual activities, education, divine matters",
+        "avoid": "Nothing specific",
+    },
+    "Centre": {
+        "nature": "Upward / Special",
+        "good_for": "Spiritual elevation, liberation, meditation",
+        "avoid": "Mundane worldly activities",
+    },
+}
+
+# Nakshatras by direction for quick lookup
+DIRECTION_NAKSHATRAS: dict[str, list[str]] = {}
+for nak, direction in NAKSHATRA_DIRECTION.items():
+    DIRECTION_NAKSHATRAS.setdefault(direction, []).append(nak)
+
+
+# ── Kurmachakra for Muhurta ───────────────────────────────────────────────────
+
+
+# Which directions are auspicious to travel when the Moon is in a specific direction
+# (Avoid travelling in the same direction as Moon's nakshatra direction on that day)
+def _directions_to_avoid_for_moon(moon_direction: str) -> list[str]:
+    """Directions to avoid when Moon is in the given direction."""
+    # Standard rule: avoid Moon's direction and its immediate flanking directions
+    idx = DIRECTIONS_ORDER.index(moon_direction)
+    avoid = [moon_direction]
+    # Also avoid the two opposite quadrant (simplified traditional rule)
+    opp_idx = (idx + 4) % 8 if idx < 8 else idx
+    avoid.append(DIRECTIONS_ORDER[opp_idx])
+    return avoid
+
+
+# ── Public API ─────────────────────────────────────────────────────────────────
+
+
+def get_kurmachakra(
+    birth_nakshatra: str,
+    current_moon_nakshatra: str | None = None,
+    event_type: str = "travel",
+) -> dict[str, Any]:
+    """Get Kurmachakra directional analysis.
+
+    Parameters
+    ----------
+    birth_nakshatra       : person's birth nakshatra (Janma Nakshatra)
+    current_moon_nakshatra: today's Moon nakshatra (for daily Muhurta)
+    event_type            : "travel", "construction", "marriage", "general"
+    """
+    birth_direction = NAKSHATRA_DIRECTION.get(birth_nakshatra, "Unknown")
+
+    result: dict[str, Any] = {
+        "event_type": event_type,
+        "birth_nakshatra": birth_nakshatra,
+        "birth_direction": birth_direction,
+        "birth_direction_sanskrit": DIRECTION_SANSKRIT.get(birth_direction, ""),
+        "birth_direction_analysis": DIRECTION_GENERAL.get(birth_direction, {}),
+        "direction_map": {
+            direction: {
+                "sanskrit": DIRECTION_SANSKRIT[direction],
+                "nakshatras": DIRECTION_NAKSHATRAS[direction],
+                "nature": DIRECTION_GENERAL[direction]["nature"],
+                "good_for": DIRECTION_GENERAL[direction]["good_for"],
+            }
+            for direction in DIRECTIONS_ORDER
+        },
+        "auspicious_directions": [],
+        "inauspicious_directions": [],
+        "best_direction": "",
+        "direction_to_avoid": birth_direction,
+    }
+
+    # Auspicious vs inauspicious directions for the birth nakshatra holder
+    auspicious = []
+    inauspicious = []
+    for direction in DIRECTIONS_ORDER:
+        nature = DIRECTION_GENERAL[direction]["nature"].lower()
+        if direction == birth_direction:
+            continue  # own direction — special rules apply
+        if "highly auspicious" in nature or "auspicious" in nature:
+            auspicious.append(direction)
+        elif "inauspicious" in nature:
+            inauspicious.append(direction)
+        else:
+            auspicious.append(direction)  # neutral counts as ok
+
+    result["auspicious_directions"] = auspicious
+    result["inauspicious_directions"] = inauspicious
+    result["best_direction"] = (
+        "North-East"
+        if "North-East" in auspicious
+        else (auspicious[0] if auspicious else "North")
+    )
+
+    # If current Moon nakshatra is given, add daily guidance
+    if current_moon_nakshatra:
+        moon_direction = NAKSHATRA_DIRECTION.get(current_moon_nakshatra, "Unknown")
+        avoid_today = (
+            _directions_to_avoid_for_moon(moon_direction)
+            if moon_direction in DIRECTIONS_ORDER
+            else [moon_direction]
+        )
+        good_today = [d for d in DIRECTIONS_ORDER if d not in avoid_today]
+        result["daily_analysis"] = {
+            "current_moon_nakshatra": current_moon_nakshatra,
+            "moon_direction": moon_direction,
+            "moon_direction_sanskrit": DIRECTION_SANSKRIT.get(moon_direction, ""),
+            "avoid_today": avoid_today,
+            "good_directions_today": good_today,
+            "note": f"Avoid travelling towards {', '.join(avoid_today)} today as Moon is in that direction.",
+        }
+
+    # Event-specific recommendations
+    event_notes: dict[str, str] = {
+        "travel": (
+            f"Best direction for travel from birth nakshatra: {result['best_direction']}. "
+            f"Avoid: {birth_direction} (birth direction). "
+            "Never travel South on Tuesday, or South-West at night."
+        ),
+        "construction": (
+            "North or North-East is ideal for main entrance. "
+            "South-West for master bedroom/safe room. "
+            "Avoid South-West for main gate."
+        ),
+        "marriage": (
+            "North-East is ideal for sacred fire direction. "
+            "East is best for bride's entry. "
+            "Avoid South and South-West for ceremony timing."
+        ),
+        "general": (
+            "North-East for spiritual and auspicious activities. "
+            "East for new beginnings. "
+            "Avoid South and South-West when possible."
+        ),
+    }
+    result["recommendation"] = event_notes.get(event_type, event_notes["general"])
+
+    return result
+
+
+def get_travel_direction_score(
+    birth_nakshatra: str,
+    intended_direction: str,
+    current_moon_nakshatra: str | None = None,
+    weekday: str | None = None,
+) -> dict[str, Any]:
+    """Score a specific intended travel direction for auspiciousness.
+
+    Parameters
+    ----------
+    birth_nakshatra     : person's birth nakshatra
+    intended_direction  : direction of travel ("North", "South", "East", etc.)
+    current_moon_nakshatra: current Moon's nakshatra
+    weekday             : "Monday", "Tuesday", etc.
+    """
+    birth_direction = NAKSHATRA_DIRECTION.get(birth_nakshatra, "Unknown")
+    moon_direction = (
+        NAKSHATRA_DIRECTION.get(current_moon_nakshatra, "")
+        if current_moon_nakshatra
+        else ""
+    )
+
+    score = 100.0
+    warnings = []
+    positives = []
+
+    nature = DIRECTION_GENERAL.get(intended_direction, {}).get("nature", "")
+    if "highly auspicious" in nature.lower():
+        positives.append(f"{intended_direction} is highly auspicious in general")
+        score += 10
+    elif "inauspicious" in nature.lower():
+        warnings.append(f"{intended_direction} is generally inauspicious for travel")
+        score -= 30
+
+    if intended_direction == birth_direction:
+        warnings.append(
+            f"Travelling in birth nakshatra direction ({birth_direction}) is generally avoided"
+        )
+        score -= 20
+
+    if moon_direction and intended_direction == moon_direction:
+        warnings.append(
+            f"Avoid travelling in Moon's current direction ({moon_direction})"
+        )
+        score -= 25
+
+    # Weekday-direction restrictions
+    BAD_WEEKDAY_DIRECTIONS: dict[str, list[str]] = {
+        "Sunday": ["West"],
+        "Monday": ["North-West"],
+        "Tuesday": ["South"],
+        "Wednesday": ["North"],
+        "Thursday": ["South-East"],
+        "Friday": ["South-West"],
+        "Saturday": ["East"],
+    }
+    if weekday and intended_direction in BAD_WEEKDAY_DIRECTIONS.get(weekday, []):
+        warnings.append(f"Avoid {intended_direction} on {weekday} (traditional rule)")
+        score -= 20
+
+    if not warnings:
+        positives.append("No directional conflicts found")
+
+    score = max(0.0, min(100.0, score))
+    grade = (
+        "Excellent"
+        if score >= 80
+        else "Good"
+        if score >= 60
+        else "Caution"
+        if score >= 40
+        else "Avoid"
+    )
+
+    return {
+        "intended_direction": intended_direction,
+        "score": round(score, 1),
+        "grade": grade,
+        "birth_nakshatra": birth_nakshatra,
+        "birth_direction": birth_direction,
+        "moon_direction": moon_direction or "Not specified",
+        "warnings": warnings,
+        "positives": positives,
+        "good_for": DIRECTION_GENERAL.get(intended_direction, {}).get("good_for", ""),
+        "recommendation": f"Direction is {grade} for travel."
+        + (" " + "; ".join(warnings) if warnings else ""),
+    }
+
+
+def get_full_kurmachakra_chart() -> dict[str, Any]:
+    """Return the complete Kurmachakra chart — all 9 directions with all 27 nakshatras."""
+    return {
+        "description": (
+            "Kurmachakra (Tortoise Wheel): maps the 27 Nakshatras to 8 cardinal directions "
+            "+ Centre (Brahma/Urdhva). Used in Muhurta for travel, construction, and auspicious activities."
+        ),
+        "directions": {
+            direction: {
+                "sanskrit": DIRECTION_SANSKRIT[direction],
+                "nakshatras": DIRECTION_NAKSHATRAS[direction],
+                "nature": DIRECTION_GENERAL[direction]["nature"],
+                "good_for": DIRECTION_GENERAL[direction]["good_for"],
+                "avoid": DIRECTION_GENERAL[direction]["avoid"],
+            }
+            for direction in DIRECTIONS_ORDER
+        },
+        "weekday_avoid_directions": {
+            "Sunday": "West",
+            "Monday": "North-West",
+            "Tuesday": "South",
+            "Wednesday": "North",
+            "Thursday": "South-East",
+            "Friday": "South-West",
+            "Saturday": "East",
+        },
+        "travel_rules": [
+            "Never travel in the direction of your birth nakshatra (Janma Nakshatra direction) for long journeys",
+            "Avoid the direction occupied by Moon's current nakshatra on that day",
+            "South and South-West are generally inauspicious for new ventures",
+            "North-East and North are generally auspicious",
+            "East is good for education and spiritual journeys",
+            "Check weekday-specific direction restrictions",
+        ],
+    }