astro-skill 1.1.1

Portable Vedic astrology engine, agent skill, and stdio MCP server (kundali, dasha, panchang, PDF reports)

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.

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)

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)

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.

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.

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 for the tool contract and config examples, and verify an install in one shot with:

python scripts/smoke_mcp_client.py

Sample commands

# 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 for build, run, smoke-test, and MCP-client wiring instructions.

Documentation

• docs/operations/install-smoke.md — fresh-clone install, MCP client config, smoke checklist.
• docs/deploy.md — Docker / MCP-client deployment.
• docs/architecture/generic-astro-platform.md — layering and reuse model.
• docs/architecture/astro-skill-roadmap.md — engine roadmap.
• services/astro_mcp/README.md — MCP server contract.
• 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.