kundali-chart-mcp 0.2.1

package/python/kundali_lib/vedic/nakshatra_details.py

@@ -0,0 +1,945 @@
+"""Complete Nakshatra database with all attributes for each of the 27 Nakshatras."""
+
+# ---------------------------------------------------------------------------
+# Navamsa pada sign sequence
+# ---------------------------------------------------------------------------
+# 108 padas cycle through all 12 signs in order starting from Aries.
+# Every group of 9 nakshatras restarts the 12-sign cycle (9 nak × 4 padas = 36 padas; 36/3 = 12).
+# Within each group of 9, nakshatra N (0-indexed) has padas starting at navamsa sign index (N*4 % 12).
+
+_NAVAMSA_SIGNS = [
+    "Aries",
+    "Taurus",
+    "Gemini",
+    "Cancer",
+    "Leo",
+    "Virgo",
+    "Libra",
+    "Scorpio",
+    "Sagittarius",
+    "Capricorn",
+    "Aquarius",
+    "Pisces",
+]
+
+_NAVAMSA_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",
+}
+
+
+def _build_padas(nakshatra_index_0: int) -> list:
+    """Return the 4-pada list for a nakshatra given its 0-based index (0=Ashwini)."""
+    start = (nakshatra_index_0 * 4) % 12
+    padas = []
+    for i in range(4):
+        sign = _NAVAMSA_SIGNS[(start + i) % 12]
+        padas.append(
+            {
+                "pada": i + 1,
+                "sign": sign,
+                "lord": _NAVAMSA_LORDS[sign],
+            }
+        )
+    return padas
+
+
+# ---------------------------------------------------------------------------
+# Complete Nakshatra database
+# ---------------------------------------------------------------------------
+
+NAKSHATRA_DATABASE = {
+    "Ashwini": {
+        "number": 1,
+        "name": "Ashwini",
+        "lord": "Ketu",
+        "deity": "Ashwini Kumaras (divine physicians)",
+        "symbol": "Horse's head",
+        "gana": "Deva",
+        "gender": "Male",
+        "nature": "Movable (Chara)",
+        "body_part": "Head, upper brain",
+        "quality": "Sattvic",
+        "direction": "East",
+        "element": "Ether",
+        "start_degree": 0.0,
+        "end_degree": 13.333,
+        "padas": _build_padas(0),
+        "keywords": ["speed", "healing", "initiation", "courage", "enthusiasm"],
+        "general_nature": (
+            "Quick, pioneering, and healing in nature. Bestows vitality and the ability "
+            "to initiate new ventures swiftly. Associated with divine healing powers."
+        ),
+    },
+    "Bharani": {
+        "number": 2,
+        "name": "Bharani",
+        "lord": "Venus",
+        "deity": "Yama (god of death and dharma)",
+        "symbol": "Yoni (female reproductive organ)",
+        "gana": "Manushya",
+        "gender": "Female",
+        "nature": "Fierce (Ugra)",
+        "body_part": "Head, forehead",
+        "quality": "Rajasic",
+        "direction": "East",
+        "element": "Ether",
+        "start_degree": 13.333,
+        "end_degree": 26.667,
+        "padas": _build_padas(1),
+        "keywords": ["restraint", "sacrifice", "transformation", "creativity", "karma"],
+        "general_nature": (
+            "Deals with cycles of creation and destruction. Strongly disciplined, "
+            "capable of bearing great burdens. Associated with karmic debts and sexuality."
+        ),
+    },
+    "Krittika": {
+        "number": 3,
+        "name": "Krittika",
+        "lord": "Sun",
+        "deity": "Agni (fire god)",
+        "symbol": "Razor / flame",
+        "gana": "Rakshasa",
+        "gender": "Female",
+        "nature": "Mixed (Mishra)",
+        "body_part": "Eyes, head, neck",
+        "quality": "Tamasic",
+        "direction": "East",
+        "element": "Ether",
+        "start_degree": 26.667,
+        "end_degree": 40.0,
+        "padas": _build_padas(2),
+        "keywords": ["power", "fire", "cutting", "purification", "ambition"],
+        "general_nature": (
+            "Sharp, penetrating, and purifying. Like a blade, it cuts away impurity. "
+            "Gives military prowess, sharp intellect, and tendency toward extremes."
+        ),
+    },
+    "Rohini": {
+        "number": 4,
+        "name": "Rohini",
+        "lord": "Moon",
+        "deity": "Brahma (creator)",
+        "symbol": "Ox cart / chariot",
+        "gana": "Manushya",
+        "gender": "Male",
+        "nature": "Fixed (Sthira)",
+        "body_part": "Forehead, eyes, face",
+        "quality": "Rajasic",
+        "direction": "South",
+        "element": "Air",
+        "start_degree": 40.0,
+        "end_degree": 53.333,
+        "padas": _build_padas(3),
+        "keywords": ["growth", "beauty", "fertility", "sensuality", "creativity"],
+        "general_nature": (
+            "Most fertile and creative of all nakshatras. Nurturing, beautiful, and "
+            "abundant. Associated with the arts, agriculture, and material prosperity."
+        ),
+    },
+    "Mrigashira": {
+        "number": 5,
+        "name": "Mrigashira",
+        "lord": "Mars",
+        "deity": "Soma / Chandra (Moon god)",
+        "symbol": "Deer's head",
+        "gana": "Deva",
+        "gender": "Neutral",
+        "nature": "Soft (Mridu)",
+        "body_part": "Eyes, eyebrows",
+        "quality": "Sattvic",
+        "direction": "South",
+        "element": "Air",
+        "start_degree": 53.333,
+        "end_degree": 66.667,
+        "padas": _build_padas(4),
+        "keywords": ["searching", "curiosity", "gentleness", "wandering", "seeking"],
+        "general_nature": (
+            "Eternally seeking and curious. Gentle yet restless, the native is always "
+            "searching for something better. Bestows intelligence and sensitivity."
+        ),
+    },
+    "Ardra": {
+        "number": 6,
+        "name": "Ardra",
+        "lord": "Rahu",
+        "deity": "Rudra (storm god)",
+        "symbol": "Teardrop / diamond",
+        "gana": "Manushya",
+        "gender": "Female",
+        "nature": "Fierce (Ugra)",
+        "body_part": "Eyes, nose",
+        "quality": "Rajasic",
+        "direction": "South",
+        "element": "Air",
+        "start_degree": 66.667,
+        "end_degree": 80.0,
+        "padas": _build_padas(5),
+        "keywords": ["storm", "transformation", "grief", "effort", "breakthrough"],
+        "general_nature": (
+            "Intense and transformative. Like a storm that clears the air, Ardra breaks "
+            "down old structures to make way for new growth. Associated with deep emotional experiences."
+        ),
+    },
+    "Punarvasu": {
+        "number": 7,
+        "name": "Punarvasu",
+        "lord": "Jupiter",
+        "deity": "Aditi (mother of the gods)",
+        "symbol": "Quiver of arrows",
+        "gana": "Deva",
+        "gender": "Male",
+        "nature": "Movable (Chara)",
+        "body_part": "Nose, ears, fingers",
+        "quality": "Sattvic",
+        "direction": "South",
+        "element": "Air",
+        "start_degree": 80.0,
+        "end_degree": 93.333,
+        "padas": _build_padas(6),
+        "keywords": ["renewal", "return", "wisdom", "expansion", "optimism"],
+        "general_nature": (
+            "Renewal and return after hardship. Philosophical and optimistic, with a "
+            "capacity for repeated fresh starts. Associated with abundance and divine protection."
+        ),
+    },
+    "Pushya": {
+        "number": 8,
+        "name": "Pushya",
+        "lord": "Saturn",
+        "deity": "Brihaspati (preceptor of the gods)",
+        "symbol": "Flower / udder of a cow",
+        "gana": "Deva",
+        "gender": "Male",
+        "nature": "Fixed (Sthira)",
+        "body_part": "Face, mouth",
+        "quality": "Sattvic",
+        "direction": "West",
+        "element": "Fire",
+        "start_degree": 93.333,
+        "end_degree": 106.667,
+        "padas": _build_padas(7),
+        "keywords": [
+            "nourishment",
+            "protection",
+            "spirituality",
+            "dharma",
+            "abundance",
+        ],
+        "general_nature": (
+            "Most auspicious for religious and spiritual activities. Nourishing, protective, "
+            "and devoted to dharma. Called the 'best of nakshatras' by Sage Parashara."
+        ),
+    },
+    "Ashlesha": {
+        "number": 9,
+        "name": "Ashlesha",
+        "lord": "Mercury",
+        "deity": "Naga / Sarpa (serpent deities)",
+        "symbol": "Coiled serpent",
+        "gana": "Rakshasa",
+        "gender": "Female",
+        "nature": "Fierce (Ugra)",
+        "body_part": "Ears, chin, nails",
+        "quality": "Tamasic",
+        "direction": "West",
+        "element": "Fire",
+        "start_degree": 106.667,
+        "end_degree": 120.0,
+        "padas": _build_padas(8),
+        "keywords": ["cunning", "occult", "clinging", "hypnosis", "depth"],
+        "general_nature": (
+            "Mysterious and penetrating. Associated with kundalini energy, occult powers, "
+            "and psychic abilities. Can indicate deception or deep spiritual insight depending on chart."
+        ),
+    },
+    "Magha": {
+        "number": 10,
+        "name": "Magha",
+        "lord": "Ketu",
+        "deity": "Pitrs (ancestral spirits)",
+        "symbol": "Palanquin / royal throne",
+        "gana": "Rakshasa",
+        "gender": "Female",
+        "nature": "Fierce (Ugra)",
+        "body_part": "Nose, lips, chin",
+        "quality": "Tamasic",
+        "direction": "North",
+        "element": "Water",
+        "start_degree": 120.0,
+        "end_degree": 133.333,
+        "padas": _build_padas(9),
+        "keywords": ["royalty", "ancestors", "authority", "pride", "legacy"],
+        "general_nature": (
+            "Regal and authoritative. Strongly connected to ancestral lineage and past-life karma. "
+            "Confers leadership ability, dignity, and pride in one's heritage."
+        ),
+    },
+    "Purva Phalguni": {
+        "number": 11,
+        "name": "Purva Phalguni",
+        "lord": "Venus",
+        "deity": "Bhaga (god of marital bliss and prosperity)",
+        "symbol": "Front legs of a bed / hammock",
+        "gana": "Manushya",
+        "gender": "Female",
+        "nature": "Fierce (Ugra)",
+        "body_part": "Lips, right hand",
+        "quality": "Rajasic",
+        "direction": "North",
+        "element": "Water",
+        "start_degree": 133.333,
+        "end_degree": 146.667,
+        "padas": _build_padas(10),
+        "keywords": ["pleasure", "creativity", "romance", "relaxation", "indulgence"],
+        "general_nature": (
+            "Playful, creative, and pleasure-seeking. Associated with enjoyment of the senses, "
+            "romance, arts, and the sweet aspects of life. A time for rest and enjoyment."
+        ),
+    },
+    "Uttara Phalguni": {
+        "number": 12,
+        "name": "Uttara Phalguni",
+        "lord": "Sun",
+        "deity": "Aryaman (deity of patronage and contracts)",
+        "symbol": "Back legs of a bed",
+        "gana": "Manushya",
+        "gender": "Female",
+        "nature": "Fixed (Sthira)",
+        "body_part": "Left hand, spine",
+        "quality": "Rajasic",
+        "direction": "North",
+        "element": "Water",
+        "start_degree": 146.667,
+        "end_degree": 160.0,
+        "padas": _build_padas(11),
+        "keywords": ["patronage", "contracts", "generosity", "service", "steadiness"],
+        "general_nature": (
+            "Reliable and generous in service. Focused on forming enduring agreements and alliances. "
+            "Gives loyalty, friendliness, and success through persistent effort."
+        ),
+    },
+    "Hasta": {
+        "number": 13,
+        "name": "Hasta",
+        "lord": "Moon",
+        "deity": "Savitar (the Sun as creative power)",
+        "symbol": "Hand / fist",
+        "gana": "Deva",
+        "gender": "Male",
+        "nature": "Movable (Chara)",
+        "body_part": "Hands, fingers",
+        "quality": "Sattvic",
+        "direction": "East",
+        "element": "Earth",
+        "start_degree": 160.0,
+        "end_degree": 173.333,
+        "padas": _build_padas(12),
+        "keywords": ["skill", "dexterity", "cleverness", "craftsmanship", "wit"],
+        "general_nature": (
+            "Skillful and clever, with great dexterity of hand and mind. Excellent craftspeople, "
+            "healers, and artisans. Quick to grasp opportunities; friendly and charming."
+        ),
+    },
+    "Chitra": {
+        "number": 14,
+        "name": "Chitra",
+        "lord": "Mars",
+        "deity": "Vishwakarma (celestial architect)",
+        "symbol": "Bright pearl / jewel",
+        "gana": "Rakshasa",
+        "gender": "Female",
+        "nature": "Soft (Mridu)",
+        "body_part": "Forehead, neck",
+        "quality": "Tamasic",
+        "direction": "East",
+        "element": "Earth",
+        "start_degree": 173.333,
+        "end_degree": 186.667,
+        "padas": _build_padas(13),
+        "keywords": ["beauty", "artistry", "brilliance", "design", "attraction"],
+        "general_nature": (
+            "Artistically brilliant and visually gifted. Chitra natives are drawn to beauty in "
+            "all its forms — architecture, fashion, and the decorative arts. Magnetic personality."
+        ),
+    },
+    "Swati": {
+        "number": 15,
+        "name": "Swati",
+        "lord": "Rahu",
+        "deity": "Vayu (wind god)",
+        "symbol": "Young sprout / coral / sword",
+        "gana": "Deva",
+        "gender": "Female",
+        "nature": "Movable (Chara)",
+        "body_part": "Chest, teeth, skin",
+        "quality": "Sattvic",
+        "direction": "South",
+        "element": "Earth",
+        "start_degree": 186.667,
+        "end_degree": 200.0,
+        "padas": _build_padas(14),
+        "keywords": [
+            "independence",
+            "flexibility",
+            "trade",
+            "diplomacy",
+            "adaptability",
+        ],
+        "general_nature": (
+            "Independent like the wind, yet adaptable. Gifted in trade, commerce, and diplomacy. "
+            "Can bend without breaking. Spiritual aspiration is often present."
+        ),
+    },
+    "Vishakha": {
+        "number": 16,
+        "name": "Vishakha",
+        "lord": "Jupiter",
+        "deity": "Indra-Agni (Indra and Agni jointly)",
+        "symbol": "Triumphal arch / potter's wheel",
+        "gana": "Rakshasa",
+        "gender": "Female",
+        "nature": "Mixed (Mishra)",
+        "body_part": "Arms, breasts",
+        "quality": "Tamasic",
+        "direction": "South",
+        "element": "Earth",
+        "start_degree": 200.0,
+        "end_degree": 213.333,
+        "padas": _build_padas(15),
+        "keywords": ["ambition", "focus", "triumph", "passion", "rivalry"],
+        "general_nature": (
+            "Intensely goal-oriented. Like the triumphal arch, marks victory after persistent effort. "
+            "Can oscillate between extremes. Dual rulership reflects inner conflict resolved through determination."
+        ),
+    },
+    "Anuradha": {
+        "number": 17,
+        "name": "Anuradha",
+        "lord": "Saturn",
+        "deity": "Mitra (god of friendship and contracts)",
+        "symbol": "Lotus / umbrella",
+        "gana": "Deva",
+        "gender": "Male",
+        "nature": "Soft (Mridu)",
+        "body_part": "Breasts, stomach",
+        "quality": "Sattvic",
+        "direction": "South",
+        "element": "Ether",
+        "start_degree": 213.333,
+        "end_degree": 226.667,
+        "padas": _build_padas(16),
+        "keywords": ["friendship", "devotion", "organisation", "occult", "balance"],
+        "general_nature": (
+            "Devoted and organisational. Forms loyal friendships and alliances. "
+            "Can balance spiritual and material worlds gracefully. Strong occult inclinations."
+        ),
+    },
+    "Jyeshtha": {
+        "number": 18,
+        "name": "Jyeshtha",
+        "lord": "Mercury",
+        "deity": "Indra (king of the gods)",
+        "symbol": "Earring / circular amulet / umbrella",
+        "gana": "Rakshasa",
+        "gender": "Female",
+        "nature": "Fierce (Ugra)",
+        "body_part": "Tongue, right side",
+        "quality": "Tamasic",
+        "direction": "West",
+        "element": "Ether",
+        "start_degree": 226.667,
+        "end_degree": 240.0,
+        "padas": _build_padas(17),
+        "keywords": ["seniority", "protection", "authority", "occult", "jealousy"],
+        "general_nature": (
+            "The eldest and most powerful. Bears great responsibility as protector of others. "
+            "Gifted with occult knowledge and leadership, but can harbour jealousy or pride."
+        ),
+    },
+    "Mula": {
+        "number": 19,
+        "name": "Mula",
+        "lord": "Ketu",
+        "deity": "Nirriti / Alakshmi (goddess of dissolution and misfortune)",
+        "symbol": "Bunch of roots / lion's tail",
+        "gana": "Rakshasa",
+        "gender": "Neutral",
+        "nature": "Fierce (Ugra)",
+        "body_part": "Feet, left side",
+        "quality": "Tamasic",
+        "direction": "West",
+        "element": "Air",
+        "start_degree": 240.0,
+        "end_degree": 253.333,
+        "padas": _build_padas(18),
+        "keywords": ["roots", "investigation", "uprooting", "liberation", "depth"],
+        "general_nature": (
+            "Gets to the very root of things. Mula natives are investigators, philosophers, "
+            "and spiritual seekers. Associated with uprooting — both destructive and liberating."
+        ),
+    },
+    "Purva Ashadha": {
+        "number": 20,
+        "name": "Purva Ashadha",
+        "lord": "Venus",
+        "deity": "Apah (water goddesses)",
+        "symbol": "Elephant tusk / fan / winnowing basket",
+        "gana": "Manushya",
+        "gender": "Female",
+        "nature": "Fierce (Ugra)",
+        "body_part": "Back, thighs",
+        "quality": "Rajasic",
+        "direction": "West",
+        "element": "Air",
+        "start_degree": 253.333,
+        "end_degree": 266.667,
+        "padas": _build_padas(19),
+        "keywords": [
+            "invincibility",
+            "purification",
+            "pride",
+            "philosophy",
+            "expansion",
+        ],
+        "general_nature": (
+            "Energetic and invincible in pursuit of goals. Associated with purification through "
+            "water and wind. Natives are proud, philosophical, and hard to defeat."
+        ),
+    },
+    "Uttara Ashadha": {
+        "number": 21,
+        "name": "Uttara Ashadha",
+        "lord": "Sun",
+        "deity": "Vishwadevas (ten universal gods)",
+        "symbol": "Elephant tusk / planks of bed",
+        "gana": "Manushya",
+        "gender": "Female",
+        "nature": "Fixed (Sthira)",
+        "body_part": "Thighs, knees",
+        "quality": "Rajasic",
+        "direction": "West",
+        "element": "Air",
+        "start_degree": 266.667,
+        "end_degree": 280.0,
+        "padas": _build_padas(20),
+        "keywords": [
+            "victory",
+            "righteousness",
+            "leadership",
+            "endurance",
+            "universality",
+        ],
+        "general_nature": (
+            "The universal victor. Permanent, just, and widely recognized victories. "
+            "Natives are righteous, responsible leaders with enduring achievements."
+        ),
+    },
+    "Shravana": {
+        "number": 22,
+        "name": "Shravana",
+        "lord": "Moon",
+        "deity": "Vishnu (preserver of the universe)",
+        "symbol": "Ear / three footprints",
+        "gana": "Deva",
+        "gender": "Male",
+        "nature": "Movable (Chara)",
+        "body_part": "Ears, knees",
+        "quality": "Sattvic",
+        "direction": "North",
+        "element": "Fire",
+        "start_degree": 280.0,
+        "end_degree": 293.333,
+        "padas": _build_padas(21),
+        "keywords": ["listening", "learning", "connection", "Vishnu", "travel"],
+        "general_nature": (
+            "The listener and learner. Associated with acquiring knowledge through hearing. "
+            "Blessed by Vishnu; brings preservation, connection, and wide networks."
+        ),
+    },
+    "Dhanishta": {
+        "number": 23,
+        "name": "Dhanishta",
+        "lord": "Mars",
+        "deity": "Eight Vasus (gods of abundance)",
+        "symbol": "Drum / flute",
+        "gana": "Rakshasa",
+        "gender": "Female",
+        "nature": "Movable (Chara)",
+        "body_part": "Back, ankles",
+        "quality": "Tamasic",
+        "direction": "North",
+        "element": "Fire",
+        "start_degree": 293.333,
+        "end_degree": 306.667,
+        "padas": _build_padas(22),
+        "keywords": ["wealth", "music", "rhythm", "ambition", "adaptability"],
+        "general_nature": (
+            "Rhythmic and ambitious. Strongly connected to wealth and musical talent. "
+            "The drum symbolises the pulse of life — natives are energetic and achievement-oriented."
+        ),
+    },
+    "Shatabhisha": {
+        "number": 24,
+        "name": "Shatabhisha",
+        "lord": "Rahu",
+        "deity": "Varuna (god of cosmic order and water)",
+        "symbol": "Empty circle / thousand flowers",
+        "gana": "Rakshasa",
+        "gender": "Neutral",
+        "nature": "Movable (Chara)",
+        "body_part": "Chin, lower leg",
+        "quality": "Tamasic",
+        "direction": "North",
+        "element": "Ether",
+        "start_degree": 306.667,
+        "end_degree": 320.0,
+        "padas": _build_padas(23),
+        "keywords": ["healing", "mystery", "solitude", "research", "secrecy"],
+        "general_nature": (
+            "The hundred healers. Deeply mysterious and introspective. Gifted in medicine, "
+            "astrology, and esoteric sciences. Needs solitude to recharge."
+        ),
+    },
+    "Purva Bhadrapada": {
+        "number": 25,
+        "name": "Purva Bhadrapada",
+        "lord": "Jupiter",
+        "deity": "Aja Ekapada (one-footed serpent / fire dragon)",
+        "symbol": "Swords / two-faced man",
+        "gana": "Manushya",
+        "gender": "Male",
+        "nature": "Fierce (Ugra)",
+        "body_part": "Sides, feet",
+        "quality": "Rajasic",
+        "direction": "East",
+        "element": "Ether",
+        "start_degree": 320.0,
+        "end_degree": 333.333,
+        "padas": _build_padas(24),
+        "keywords": [
+            "renunciation",
+            "fire",
+            "passion",
+            "transformation",
+            "two-sidedness",
+        ],
+        "general_nature": (
+            "Intense and transformative. Natives wrestle with opposing inner forces. "
+            "Capable of great renunciation or passionate attachment. Linked to fiery spiritual purification."
+        ),
+    },
+    "Uttara Bhadrapada": {
+        "number": 26,
+        "name": "Uttara Bhadrapada",
+        "lord": "Saturn",
+        "deity": "Ahir Budhnya (serpent of the deep sea)",
+        "symbol": "Twins / back legs of funeral cot",
+        "gana": "Manushya",
+        "gender": "Male",
+        "nature": "Fixed (Sthira)",
+        "body_part": "Feet, sides",
+        "quality": "Rajasic",
+        "direction": "East",
+        "element": "Ether",
+        "start_degree": 333.333,
+        "end_degree": 346.667,
+        "padas": _build_padas(25),
+        "keywords": ["depth", "wisdom", "compassion", "restraint", "serpentine"],
+        "general_nature": (
+            "Deep, wise, and compassionate. Like the ocean floor — vast, still, and powerful. "
+            "Blesses with a profound philosophical mind and patient, enduring nature."
+        ),
+    },
+    "Revati": {
+        "number": 27,
+        "name": "Revati",
+        "lord": "Mercury",
+        "deity": "Pushan (nurturer, guide of souls)",
+        "symbol": "Fish / drum",
+        "gana": "Deva",
+        "gender": "Female",
+        "nature": "Soft (Mridu)",
+        "body_part": "Abdomen, feet",
+        "quality": "Sattvic",
+        "direction": "East",
+        "element": "Ether",
+        "start_degree": 346.667,
+        "end_degree": 360.0,
+        "padas": _build_padas(26),
+        "keywords": [
+            "completion",
+            "nourishment",
+            "spiritual journey",
+            "gentleness",
+            "guidance",
+        ],
+        "general_nature": (
+            "The final nakshatra — completion, closure, and liberation. Nurturing and spiritually "
+            "inclined. Guides souls on their journey. Gentle, compassionate, and deeply intuitive."
+        ),
+    },
+}
+
+# ---------------------------------------------------------------------------
+# Compatibility reference data (mirrors compatibility.py)
+# ---------------------------------------------------------------------------
+
+_NAKSHATRAS_LIST = [
+    "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",
+]
+
+_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"}),
+}
+
+# Tara categories (1-9 mapped to type)
+_TARA_NAMES = {
+    1: "Janma",
+    2: "Sampat",
+    3: "Vipat",
+    4: "Kshema",
+    5: "Pratyak",
+    6: "Sadhana",
+    7: "Naidhana",
+    8: "Mitra",
+    9: "Ati-Mitra",
+}
+_AUSPICIOUS_TARAS = {1, 4, 7}  # Note: Janma is used differently in some traditions
+_INAUSPICIOUS_TARAS = {
+    3,
+    6,
+    9,
+}  # Vipat, Sadhana, Naidhana vary by school; Vipat/Naidhana standard
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def get_nakshatra_details(nakshatra_name: str) -> dict:
+    """Return the complete data dict for a nakshatra by name.
+
+    Parameters
+    ----------
+    nakshatra_name : str
+        Exact name as stored in NAKSHATRA_DATABASE (e.g. "Purva Phalguni").
+
+    Returns
+    -------
+    dict
+        Full nakshatra entry, or an empty dict if the name is not found.
+    """
+    return NAKSHATRA_DATABASE.get(nakshatra_name, {})
+
+
+def get_planet_nakshatra_analysis(planetary_positions: list) -> list:
+    """Return nakshatra analysis for each planet in a chart.
+
+    Parameters
+    ----------
+    planetary_positions : list
+        Each item must have at least ``name``, ``nakshatra``, ``longitude``,
+        and ``house``.
+
+    Returns
+    -------
+    list of dict
+        One entry per planet, merging the planet fields with the full
+        nakshatra metadata (deity, symbol, gana, quality, keywords, etc.).
+    """
+    results = []
+    for planet in planetary_positions:
+        nak_name = planet.get("nakshatra", "")
+        nak_data = NAKSHATRA_DATABASE.get(nak_name, {})
+
+        results.append(
+            {
+                "planet": planet["name"],
+                "longitude": planet.get("longitude"),
+                "house": planet.get("house"),
+                "nakshatra": nak_name,
+                "nakshatra_lord": nak_data.get("lord", ""),
+                "nakshatra_pada": planet.get("pada"),
+                "deity": nak_data.get("deity", ""),
+                "symbol": nak_data.get("symbol", ""),
+                "gana": nak_data.get("gana", ""),
+                "gender": nak_data.get("gender", ""),
+                "nature": nak_data.get("nature", ""),
+                "quality": nak_data.get("quality", ""),
+                "element": nak_data.get("element", ""),
+                "body_part": nak_data.get("body_part", ""),
+                "keywords": nak_data.get("keywords", []),
+                "general_nature": nak_data.get("general_nature", ""),
+            }
+        )
+    return results
+
+
+def get_nakshatra_compatibility(nakshatra1: str, nakshatra2: str) -> dict:
+    """Return Tara and Yoni compatibility scores between two nakshatras.
+
+    Uses the same logic as compatibility.py's ``_score_tara`` and
+    ``_score_yoni`` functions for consistency.
+
+    Parameters
+    ----------
+    nakshatra1 : str
+        First nakshatra name (reference perspective).
+    nakshatra2 : str
+        Second nakshatra name.
+
+    Returns
+    -------
+    dict with keys:
+        tara_score (float 0–3), tara_from_1_to_2 (int), tara_name_1_to_2 (str),
+        tara_from_2_to_1 (int), tara_name_2_to_1 (str), tara_description (str),
+        yoni_score (float 0–4), yoni_animal_1 (str), yoni_animal_2 (str),
+        yoni_description (str), total_score (float), max_score (float),
+        compatibility_percent (float).
+    """
+
+    def _nak_index(name: str) -> int:
+        try:
+            return _NAKSHATRAS_LIST.index(name)
+        except ValueError:
+            return 0
+
+    def _tara_number(from_idx: int, to_idx: int) -> int:
+        count = (to_idx - from_idx) % 27 + 1
+        return ((count - 1) % 9) + 1
+
+    def _tara_category(t: int) -> str:
+        if t in _AUSPICIOUS_TARAS:
+            return "auspicious"
+        if t in _INAUSPICIOUS_TARAS:
+            return "inauspicious"
+        return "neutral"
+
+    idx1 = _nak_index(nakshatra1)
+    idx2 = _nak_index(nakshatra2)
+
+    t1_to_2 = _tara_number(idx1, idx2)
+    t2_to_1 = _tara_number(idx2, idx1)
+    cat1 = _tara_category(t1_to_2)
+    cat2 = _tara_category(t2_to_1)
+
+    if cat1 == "auspicious" and cat2 == "auspicious":
+        tara_score = 3.0
+    elif cat1 == "inauspicious" and cat2 == "inauspicious":
+        tara_score = 0.0
+    else:
+        tara_score = 1.5
+
+    tara_desc = (
+        f"{nakshatra1}→{nakshatra2}: tara {t1_to_2} ({_TARA_NAMES.get(t1_to_2, '')}, {cat1}); "
+        f"{nakshatra2}→{nakshatra1}: tara {t2_to_1} ({_TARA_NAMES.get(t2_to_1, '')}, {cat2})."
+    )
+
+    # Yoni
+    yoni1 = _YONI.get(nakshatra1, "")
+    yoni2 = _YONI.get(nakshatra2, "")
+
+    if yoni1 == yoni2:
+        yoni_score = 4.0
+        yoni_compat = "same animal — ideal"
+    elif frozenset({yoni1, yoni2}) in _ENEMY_YONI_PAIRS:
+        yoni_score = 0.0
+        yoni_compat = "enemy animals — incompatible"
+    else:
+        yoni_score = 2.0
+        yoni_compat = "neutral animal pairing"
+
+    yoni_desc = f"{nakshatra1} ({yoni1}) — {nakshatra2} ({yoni2}): {yoni_compat}."
+
+    total = tara_score + yoni_score
+    max_pts = 7.0  # 3 (tara) + 4 (yoni)
+
+    return {
+        "tara_score": tara_score,
+        "tara_from_1_to_2": t1_to_2,
+        "tara_name_1_to_2": _TARA_NAMES.get(t1_to_2, ""),
+        "tara_from_2_to_1": t2_to_1,
+        "tara_name_2_to_1": _TARA_NAMES.get(t2_to_1, ""),
+        "tara_description": tara_desc,
+        "yoni_score": yoni_score,
+        "yoni_animal_1": yoni1,
+        "yoni_animal_2": yoni2,
+        "yoni_description": yoni_desc,
+        "total_score": round(total, 2),
+        "max_score": max_pts,
+        "compatibility_percent": round(total / max_pts * 100, 1),
+    }