# 🌌 Astro Skill

<p align="center">
  <strong>High-precision, deterministic Vedic astrology engine, portable agent skill, and stdio MCP server.</strong><br>
  <em>Swiss Ephemeris SWIEPH precision • 100% Offline & Zero API Keys • In-process ReportLab PDF • 11 MCP Tools</em>
</p>

<p align="center">
  <a href="https://github.com/adityarya24/astro-skill/actions/workflows/ci.yml"><img src="https://github.com/adityarya24/astro-skill/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://pypi.org/project/astro-skill/"><img src="https://img.shields.io/pypi/v/astro-skill.svg?color=blue" alt="PyPI version"></a>
  <a href="https://pypi.org/project/astro-skill/"><img src="https://img.shields.io/pypi/pyversions/astro-skill.svg" alt="Python versions"></a>
  <a href="https://glama.ai/mcp/servers/adityarya24/astro-skill"><img src="https://glama.ai/mcp/servers/adityarya24/astro-skill/badges/score.svg" alt="Glama Score"></a>
  <a href="https://m8ven.ai/mcp/adityarya24/astro-skill"><img src="https://m8ven.ai/badge/mcp/adityarya24/astro-skill?variant=verified" alt="M8ven Verified"></a>
  <img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License">
</p>

<p align="center">
  <img src="docs/images/sample-lagna-chart.png" alt="North Indian Lagna Kundali Chart" width="330">
  <br>
  <img src="docs/images/sample-dasha-strip.png" alt="Vimshottari Dasha Timeline" width="680">
</p>

---

## 🎯 Overview

**Astro Skill** is a production-grade, deterministic Vedic astrology engine that converts birth details and celestial coordinates into structured mathematical charts, timelines, and factual reports.

- **🔬 Zero Hallucinations**: 100% calculation-backed using bundled Swiss Ephemeris data (`.se1` SWIEPH via `pyswisseph`) and Lahiri (Chitrapaksha) ayanamsa.
- **🔌 3 Plug-and-Play Surfaces**:
  1. **Stdio MCP Server** (`astro-mcp`): 11 stable tools for Claude Desktop, Cursor, Codex, OpenClaw, and any Model Context Protocol client.
  2. **Python Library & CLI**: Import directly in Python or run standalone CLI calculator scripts with `--json` outputs.
  3. **Agent Skill**: Portable `SKILL.md` ready to equip autonomous coding agents and orchestrators.
- **📄 In-Process PDF Generator**: Generates bilingual (Hindi & English) Kundali and Panchang charts via ReportLab with bundled Noto Sans Devanagari font — **zero headless browser or Chrome dependencies**.
- **🔒 100% Offline & Private**: Zero external API keys, zero rate-limits, and zero network calls required for astrological calculations.

---

## 🏛️ Architecture & Layering

```
                     [ Client / Agent Request ]
                                 │
                 ┌───────────────┼───────────────┐
                 ▼               ▼               ▼
          Stdio MCP Server   Python CLI     Agent Skill
          (11 Tools/JSON)   (Scripts/Lib)   (SKILL.md)
                 │               │               │
                 └───────────────┬───────────────┘
                                 │
                                 ▼
                     ┌───────────────────────┐
                     │   Astro Core Engine   │
                     │  (Swiss Ephemeris     │
                     │   + Lahiri Ayanamsa)  │
                     └───────────┬───────────┘
                                 │
                 ┌───────────────┴───────────────┐
                 ▼                               ▼
       [ Structured JSON ]            [ In-Process ReportLab PDF ]
       - 12 Bhavas, Grahas, Yogas     - Lagna & Navamsa (D1/D9)
       - Vimshottari Timeline         - Devanagari Hindi/English
       - Gochar & Guna Milan          - Dasha Strips & Panchang
```

---

## ✨ Core Capabilities

| Category | Features & Astrological Foundations |
| :--- | :--- |
| **Kundali (D1 & D9)** | Lagna, Rashi, Nakshatra + Pada, 9 Grahas with true retrograde flags, whole-sign houses, and high-precision Navamsa (D9) divisional chart. |
| **Planetary Strengths** | Classical dignity, Digbala, Vargottama, Combustion (Asta), Graha Yuddha, and Lagna-specific functional benefic / malefic classifications. |
| **Classical Yogas** | Gajakesari, Budhaditya, Pancha Mahapurusha, Raja Yogas, Neechabhanga, Vipreet (Harsha/Sarala/Vimala), Kaal Sarp (full/partial), Parivartana (Maha/Khala/Dainya) — with classical cancellation checks. |
| **12-House Bhava Analysis** | House lords with placement & strength, occupants, Parashari planetary aspects (Drishti), and Bhava Karakas. |
| **Vimshottari Dasha** | Mahadasha, Antardasha, and Pratyantardasha timelines with true astronomical birth-balance handling. |
| **Daily Panchang** | Sunrise-anchored Tithi, Vara, Nakshatra, Yoga, Karana, Sunrise/Sunset, auspicious Muhurtas, and Anandadi/Amrit yogas. |
| **Gochar (Transits)** | Real-time planetary transits mapped against natal Moon and Lagna, with retrograde indicators and Saturn Sade Sati tracking. |
| **Guna Milan (Matchmaking)** | Complete 36-point Ashtakoot compatibility scoring with Nadi, Bhakoot, Gana, and Mangalik Dosha analysis. |
| **Classical Remedies** | Prioritized mantras, gemstones, fasting days, daan (charity), and rituals in bilingual Hindi/English. |

---

## 🚀 Quick Start

### 1. Install from PyPI

```bash
pip install astro-skill
```

Requires **Python 3.11+**.

### 2. Run the Stdio MCP Server

```bash
astro-mcp
# or: python -m services.astro_mcp
```

### 3. CLI Command Examples

```bash
# Calculate Birth Kundali (JSON output)
python -m astro.scripts.kundali_calculator --dob 26/12/2019 --tob 09:15 \
  --place Delhi --lat 28.6139 --lon 77.2090 --timezone Asia/Kolkata --json

# Calculate Vimshottari Dasha Timeline
python -m astro.scripts.dasha_calculator --kundali-json chart.json --json

# Daily Panchang
python -m astro.scripts.panchang_calculator --date 2026-05-21 \
  --place Delhi --lat 28.6139 --lon 77.209 --timezone Asia/Kolkata --json

# Ashtakoot Guna Milan (Compatibility)
python -m astro.scripts.guna_milan --kundali-a-json person_a.json --kundali-b-json person_b.json --json

# Generate Factual Bilingual PDF Report
python -m astro.scripts.pdf_report --kundali-json chart.json --dasha-json dasha.json \
  --panchang-json panchang.json --output report.pdf --language hi
```

### 4. Python Library Usage

```python
from astro.scripts.kundali_calculator import calculate_kundali

kundali = calculate_kundali(
    dob="15/08/1990",
    tob="14:30",
    place="Mumbai",
    lat=19.0760,
    lon=72.8777,
    tz_str="Asia/Kolkata"
)

print(f"Lagna: {kundali['lagna']['sign_name']}, Nakshatra: {kundali['nakshatra']['name']}")
```

---

## 🤖 MCP Server Setup

The built-in MCP server exposes 11 tools over `stdio`. It includes SQLite client profile management and report generation out of the box.

### 📋 Available MCP Tools (11)

| Tool Name | Description |
| :--- | :--- |
| `parse_birth_details` | Parse conversational birth-detail strings into structured ISO date/time and coordinates. |
| `save_client_profile` | Upsert client profile and birth parameters into local SQLite database. |
| `find_client_profile` | Search client by `client_id` or name substring. |
| `list_client_reports` | Retrieve previously generated reports for a client. |
| `calculate_kundali` | Compute complete Lahiri/whole-sign Kundali, Navamsa (D9), yogas, and bhava data. |
| `calculate_dasha` | Compute Vimshottari Mahadasha + Antardasha timeline with exact birth balance. |
| `calculate_gochar` | Compute transit chart and Sade Sati status for any target date. |
| `calculate_compatibility` | 36-point Ashtakoot Guna Milan compatibility score between two charts. |
| `calculate_panchang` | Daily sunrise-anchored Panchang (Tithi, Vara, Nakshatra, Yoga, Karana). |
| `generate_report_json` | Compile an all-in-one structured astrology draft JSON. |
| `generate_pdf_report` | Render a clean, printable PDF report using in-process ReportLab. |

### ⚙️ Client Configurations

#### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "astro": {
      "command": "astro-mcp"
    }
  }
}
```

#### Cursor (`settings.json` / MCP Config)

```json
{
  "mcpServers": {
    "astro": {
      "command": "python",
      "args": ["-m", "services.astro_mcp"],
      "cwd": "C:/path/to/astro-skill"
    }
  }
}
```

---

## 👑 Pro Report Tier

This repository contains the **open-core deterministic engine** — mathematical calculations, structured JSON schemas, and factual ReportLab PDFs.

For astrologers, consultancies, and consumer apps seeking client-ready, beautifully designed Janma Patrikas, a **Pro Report Tier** is available:
- 📖 **Pandit-Grade LLM Synthesis**: Deep house-by-house, dasha-by-dasha, and transit narrative analysis in Hindi, English, or Hinglish.
- 🎨 **Premium Print-Ready Layout**: Multi-page styled Janma Patrika with rich cover pages, divisional charts, and branded styling.
- ⚡ **Prioritized Actionable Remedies**: Context-aware Gemstone, Mantra, Yantra, and Daan suggestions tailored to running dasha periods.

📩 **Interested in licensing the Pro Tier or API?** Contact: **[adityaryawork@gmail.com](mailto:adityaryawork@gmail.com)**

---

## 🛠️ Development & Testing

```bash
git clone https://github.com/adityarya24/astro-skill.git
cd astro-skill
python -m venv .venv
source .venv/bin/activate  # Windows: .\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"

# Run full test suite (154 tests)
pytest -q

# Linter & format check
ruff check astro services scripts
```

---

## 🛡️ Safety Boundaries

1. **Calculation-Backed Drafts**: Reports are mathematical baselines intended for review by an astrologer or operator before sharing.
2. **Missing Birth Details**: Never guess or synthesize birth times or locations; prompt the user if inputs are missing.
3. **Ethical Guardrails**: Strictly prohibits generating fatalistic claims, death timing, medical diagnoses, or unavoidable harm predictions.

---

## 📜 License

MIT License © 2026 [Aditya Arya](https://github.com/adityarya24)