Metadata-Version: 2.4
Name: astro-skill
Version: 1.1.1
Summary: Portable Vedic astrology engine, agent skill, and stdio MCP server (kundali, dasha, panchang, PDF reports)
Author-email: Aditya Arya <adityarya24@users.noreply.github.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/adityarya24/astro-skill
Project-URL: Documentation, https://github.com/adityarya24/astro-skill#readme
Project-URL: Repository, https://github.com/adityarya24/astro-skill
Project-URL: Issues, https://github.com/adityarya24/astro-skill/issues
Project-URL: Changelog, https://github.com/adityarya24/astro-skill/blob/main/CHANGELOG.md
Keywords: vedic,astrology,kundali,dasha,panchang,mcp,jyotish,swiss-ephemeris
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Religion
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.27.0
Requires-Dist: playwright>=1.40
Requires-Dist: pyswisseph>=2.10.3.2
Requires-Dist: python-dateutil>=2.9.0
Requires-Dist: reportlab>=4.5.1
Requires-Dist: tzdata>=2025.2
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: pypdf>=6.12.2; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: pyyaml>=6.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Requires-Dist: setuptools>=77.0.0; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: wheel; extra == "dev"
Dynamic: license-file

# Astro Skill

[![CI](https://github.com/adityarya24/astro-skill/actions/workflows/ci.yml/badge.svg)](https://github.com/adityarya24/astro-skill/actions/workflows/ci.yml)
[![PyPI version](https://img.shields.io/pypi/v/astro-skill.svg)](https://pypi.org/project/astro-skill/)
[![Python versions](https://img.shields.io/pypi/pyversions/astro-skill.svg)](https://pypi.org/project/astro-skill/)
[![Astro Skill MCP server score](https://glama.ai/mcp/servers/adityarya24/astro-skill/badges/score.svg)](https://glama.ai/mcp/servers/adityarya24/astro-skill)

Portable Vedic astrology engine, agent skill, and MCP server. Deterministic
kundali, dasha, panchang, and yoga calculations with JSON and Hindi/English PDF
reports — reusable by any agent or MCP-compatible client.

<p align="center">
  <img src="docs/images/sample-cover-hi.png" alt="Hindi PDF report cover" width="330">
  <img src="docs/images/sample-lagna-chart.png" alt="North Indian lagna kundali chart" width="330">
</p>
<p align="center">
  <img src="docs/images/sample-dasha-strip.png" alt="Vimshottari dasha timeline" width="670">
</p>

The repo is split so each layer can be reused on its own:

- **`astro/`** — the portable skill: calculator scripts, reference data, bundled
  Swiss Ephemeris + Devanagari font, and tests. Drop it into any agent or call
  the scripts directly from Python.
- **`services/astro_mcp/`** — a generic stdio MCP server exposing the same
  calculations plus SQLite storage as 11 stable tools.
- **`apps/`** — optional products built on top (e.g. a web panel scaffold).
- **`docs/`** — architecture, roadmap, deployment, and operations docs.

## Features

- **Kundali** — lagna, rashi, nakshatra + pada, nine grahas (with retrograde),
  whole-sign houses, and dosha flags (e.g. Mangalik with classical cancellation
  rules).
- **Planetary strength flags** — dignity, digbala, vargottama, combustion,
  graha yuddha, functional benefic/malefic per lagna, and a composite
  per-planet strength verdict.
- **Yogas** — Gajakesari, Budhaditya, Pancha Mahapurusha, Raja, Neechabhanga,
  Vipreet (Harsha/Sarala/Vimala), Kaal Sarp (full/partial), Parivartana
  (maha/khala/dainya), and more — with cancellation checks where classical.
- **Full 12-house bhava data** — house lords with placement + strength,
  occupants, Parashari aspects received, and bhava karakas, surfaced in the
  report JSON for downstream analysis.
- **Gochar narrative** — month-by-month (quarterly for long windows) transit
  sampling across the current antardasha window, with true per-date ephemeris
  recomputation.
- **Remedies data** — per-planet mantra/gemstone/fasting/daan/ritual reference
  (Hindi + English) with prioritization by planetary weakness and running dasha.
- **Optional LLM synthesis** — provider-pluggable prose layer (executive
  summary, per-house analysis, dasha deep-dive, life-area forecasts, remedies)
  generated strictly from the computed chart JSON; the pipeline degrades
  gracefully to a factual report when no provider is configured.
- **Navamsa (D9)** divisional chart in both JSON and the PDF report.
- **Vimshottari dasha** — mahadasha + antardasha timeline with correct
  birth-balance handling (the sub-period actually running at birth, not a fresh
  lord/lord cycle).
- **Daily Panchang** — tithi, vara, nakshatra, yoga, karana, sunrise/sunset —
  anchored at sunrise (classical convention), with muhurta and yoga detection.
- **Lahiri (Chitrapaksha) sidereal** positions, whole-sign houses.
- **High precision** — bundled Swiss Ephemeris `.se1` data (SWIEPH) with an
  automatic Moshier fallback; each output records the tier used in
  `calculation.ephemeris`.
- **Reports** — structured JSON, and PDF via a preferred HTML/Chromium renderer
  (polished Devanagari) or a legacy in-process ReportLab fallback. Hindi/English,
  with a bundled Noto Sans Devanagari font. The HTML renderer also supports a
  `pandit_v1` premium template for pitch-ready operator reports.
- **MCP server** — 11 tools over stdio, with SQLite-backed client/report storage,
  input validation, and traversal-safe report filenames.

## Install (PyPI)

```bash
pip install astro-skill

# Optional: Chromium for the preferred HTML PDF renderer
python -m playwright install chromium

# Run the stdio MCP server
astro-mcp
# or: python -m services.astro_mcp
```

Requires Python 3.11+. For development from source, use the editable install below.

## Quick start (from source)

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

# Optional: Chromium for the preferred HTML PDF renderer
python -m playwright install chromium

# Checks
python -m pytest -q
python -m ruff check astro services scripts
```

All tests pass; the HTML/Chromium PDF render test skips automatically until
Chromium is installed. For OS-specific venv details and MCP client config
examples, see [`docs/operations/install-smoke.md`](docs/operations/install-smoke.md).

## LLM synthesis (optional)

The premium report sections can carry LLM-written prose (bilingual hi/en),
generated strictly from the computed chart JSON — prompts forbid inventing any
placement, yoga, or date. Configure via environment variables:

| Env var | Default | Meaning |
| --- | --- | --- |
| `ASTRO_LLM_PROVIDER` | `gemini` | `gemini`, `openai` (OpenAI-compatible), or `cli` |
| `ASTRO_LLM_API_KEY` | *(empty)* | API key for the chosen provider |
| `ASTRO_LLM_MODEL` | provider default | Model name |
| `ASTRO_LLM_CLI_ARGS` | — | For `cli` provider: JSON argv with a `{prompt}` token |

With no key configured, every section falls back to a compact factual digest —
the pipeline never fails because a provider is down. Calls have timeouts and
log provider failures to stderr.

## MCP server

`services/astro_mcp/` is an importable package and a runnable **stdio MCP
server**. The same `TOOLS` registry powers the unit tests and the wire protocol
— no duplicated logic, and no environment variables required.

Tools (11): `parse_birth_details`, `save_client_profile`, `find_client_profile`,
`list_client_reports`, `calculate_kundali`, `calculate_dasha`,
`calculate_gochar`, `calculate_compatibility`, `calculate_panchang`,
`generate_report_json`, `generate_pdf_report`.

```bash
python -m services.astro_mcp        # or `astro-mcp` after `pip install -e .`
```

Wire it into any MCP client (Claude Desktop, a Codex agent, or your own) by
pointing the client's MCP config at that command with `cwd` set to the repo
root. See [`services/astro_mcp/README.md`](services/astro_mcp/README.md) for the
tool contract and config examples, and verify an install in one shot with:

```bash
python scripts/smoke_mcp_client.py
```

## Sample commands

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

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

# Hindi PDF (default HTML/Chromium renderer; add --renderer reportlab for the
# no-browser fallback)
python astro/scripts/pdf_report.py --kundali-json chart.json --dasha-json dasha.json \
  --panchang-json panchang.json --output report.pdf --language hi

# Pandit-style report
python astro/scripts/pdf_report.py --kundali-json chart.json --dasha-json dasha.json \
  --panchang-json panchang.json --output pandit-v1.pdf --language hi \
  --template pandit_v1 --client-name "Client Name"
```

## Deployment

Run it as a Docker MCP server or straight from Python. The default `Dockerfile`
builds a slim image (Python, dependencies, Devanagari font, ephemeris data);
`Dockerfile.full` adds Chromium for the HTML PDF renderer. See
[`docs/deploy.md`](docs/deploy.md) for build, run, smoke-test, and MCP-client
wiring instructions.

## Documentation

- [`docs/operations/install-smoke.md`](docs/operations/install-smoke.md) — fresh-clone install, MCP client config, smoke checklist.
- [`docs/deploy.md`](docs/deploy.md) — Docker / MCP-client deployment.
- [`docs/architecture/generic-astro-platform.md`](docs/architecture/generic-astro-platform.md) — layering and reuse model.
- [`docs/architecture/astro-skill-roadmap.md`](docs/architecture/astro-skill-roadmap.md) — engine roadmap.
- [`services/astro_mcp/README.md`](services/astro_mcp/README.md) — MCP server contract.
- [`astro/SKILL.md`](astro/SKILL.md) — agent skill instructions.

## Production notes

- Positions use the bundled high-precision Swiss Ephemeris (SWIEPH) out of the
  box, not the lower-precision Moshier fallback.
- The default PDF path is HTML/Chromium for production Hindi rendering; ReportLab
  stays as a no-browser fallback.
- Generated runtime data lives under an ignored `data/` directory (or a
  caller-provided output directory).
- MCP tools validate their JSON schemas and keep generated filenames detached
  from caller-controlled identifiers.
- GitHub Actions runs install, Chromium setup, tests, ruff, and skill validation
  on push and pull requests.

## Safety boundaries

These rules apply across every layer and downstream product:

- Reports are calculation-backed drafts, intended for review by an astrologer or
  operator before any final reading is shared.
- Missing birth details must be requested rather than guessed.
- Approximate or partial inputs must be marked clearly in any output.
- Do not generate death, accident, medical, or unavoidable-harm certainty
  predictions.

## License

MIT — see [LICENSE](LICENSE).
