kpastro — KP Astrology (Krishnamurti Paddhati) Engine for Python

A precise Krishnamurti Paddhati (KP) Vedic astrology engine in pure Python, powered by the Swiss Ephemeris for arc-second accuracy.

---

What is KP Astrology?

Krishnamurti Paddhati (KP) is a stellar system of Vedic astrology developed by Prof. K. S. Krishnamurti that refines the 27 nakshatras into smaller sub-lord and sub-sub-lord divisions, so every chart point carries a precise ruling chain: star-lord, sub-lord, sub-sub-lord. Because a birth Moon sits inside one of 249 narrow zodiacal divisions, KP timing (Vimshottari dasha) and event judgment (significators, horary) reach a granularity classical jyotish does not.

Why Swiss Ephemeris precision — the engine computes every planet and house cusp with the industry-standard Swiss Ephemeris (arc-second accurate), then converts to the sidereal zodiac with a configurable ayanamsa. A silent Moshier fallback keeps the package working even with no data files installed; downloading the official ephemeris files unlocks full JPL/VSOP87 precision.

Key features

• Ayanamsa — Lahiri (Chitrapaksha, KP default), KP (SE_SIDM_KRISHNAMURTI_VP291) and KP-old (Krishnamurti's table).
• Nakshatra subdivision — star-lord, sub-lord and sub-sub-lord chains for every planet and house cusp.
• Placidus cusps — computed sidereally from the Swiss Ephemeris, with full KP lord chains on each cusp.
• Vimshottari dasha — mahadasha / antardasha / pratyantar-dasha with birth balances computed at all three levels (MD/AD/PD).
• Significators — Grah and Bhaav Nirdeshan: house and planet significators with 4-tier ranking.
• Ruling planets — day-lord, ascendant-lord and Moon-lord for the moment.
• KP horary — the 1-249 division number system with the horary ascendant taken as the division midpoint.
• Birth-time rectification — recover an unknown/approximate birth time from dated life events judged to fall in specific KP houses; each candidate minute is scored by lagna sub-lord + dasha + optional ruling-planet and a weak sibling hint, with a posterior-band range (75% mass, NOT a statistical credible interval) and a Jupiter/Saturn transit cross-check.
• CLI + Python API — everything available as a typed library and as a kpastro command-line tool.

Install

Requires Python 3.9+.

# editable install for development
pip install -e .

# with the dev/test extras
pip install -e .[dev]

pyswisseph is the only runtime dependency. On very new CPython releases a source build may be needed; ensure a C compiler is available (or install a pre-built wheel) if the binary wheel is not yet published.

Why choose kpastro?

Feature	kpastro	Generalist Libraries	API-only Tools
KP Specialization	High (249-Division)	Low/None	Variable
Precision	Arc-second (Swiss Ephemeris)	Variable	High
Deployment	Offline-first (No API)	Varies	Requires Internet
Integrability	Designed as an engine	Complex/Bloated	Locked to Cloud

kpastro is built as an offline-first computational engine. It is designed for developers who need high-precision, sub-second KP system calculations (star-lord, sub-lord, sub-sub-lord) without the overhead of cloud APIs or the bloat of general-purpose astrological frameworks.

---

Integrating kpastro into your project

kpastro is designed to be easily embeddable. If you are building a larger astrological system and need high-precision KP-system subdivision math (star-lord, sub-lord, sub-sub-lord) without reinventing the wheel, simply import the engine:

from kpastro.vedic import point_info

# Pass any sidereal longitude (0-360°) to get the full KP breakdown
data = point_info(150.5) 
print(f\"Sub-lord: {data.sub_lord}\")
print(f\"Sub-sub-lord: {data.sub_sub_lord}\")

This makes kpastro an ideal high-precision subsystem for larger libraries.

---

Quick start (CLI)

# Complete KP birth chart (New Delhi)
python -m kpastro natal --date 1990-01-15 --time 14:30 --tz 5.5 \
    --lat 28.6139 --lon 77.2090 --place "New Delhi"

# KP horary (Prashna) from number 45
python -m kpastro horary --number 45 --date 2026-08-20 --time 10:30 \
    --tz 5.5 --lat 28.61 --lon 77.20

# Ayanamsa value on a date
python -m kpastro ayanamsa --date 2026-08-20

# Download the Swiss Ephemeris data files for full precision
python -m kpastro download-ephemeris

# Birth-time rectification (BTR) from a JSON file of life events
kpastro-btr events.json --date 1990-01-15 --time 14:30 --tz 5.5 \
    --lat 28.6139 --lon 77.2090 --place "New Delhi" --window 30

Other subcommands: dasha, rulings, btr. Run python -m kpastro --help or kpastro-btr --help for all options.

Python API

from datetime import date, time
from kpastro import BirthInfo, compute_chart, render_chart, ascendant_from_kp_number

birth = BirthInfo(
    date=date(1990, 1, 15), time=time(14, 30),
    latitude=28.6139, longitude=77.2090,
    tz_hours=5.5, place="New Delhi",
)
chart = compute_chart(birth, ayanamsa="lahiri")
print(render_chart(chart))

# KP horary: all 249 divisions, or the ascendant for one number
divs = kp_divisions()                 # list of 249 HoraryDiv
q = ascendant_from_kp_number(45)      # dict with ascendant + lord chain

chart.planets, chart.cusps, chart.balance, chart.mahadashas, chart.current, chart.planet_significators and chart.ruling give typed access to every KP layer.

Birth-time rectification

When only an approximate birth time is known, dated life events mapped to KP houses can recover it:

from datetime import date, time
from kpastro import BirthInfo, LifeEvent, rectify, render_rectification

# Birth info approximate time
birth = BirthInfo(date(1990, 1, 15), time(14, 30),
                  28.6139, 77.2090, 5.5, 'New Delhi')
events = [
    LifeEvent(date(1995, 9, 3),  2, (), 'School admission'),
    LifeEvent(date(2007, 4, 1),  4, (), 'Joined college'),
    LifeEvent(date(2013, 2, 14), 4, (), 'First job'),
    LifeEvent(date(2018, 1, 20), 7, (), 'Marriage'),
]
# Scans +/-60 min at 1-min steps
result = rectify(birth, time(14, 30), events)
print(render_rectification(result, birth))

---

Citation

If you use kpastro in your research or application, please cite us:

@software{majumdar2026kpastro,
  author = {Rituparno Majumdar},
  title = {kpastro: A Precise Krishnamurti Paddhati (KP) Astrology Engine},
  year = {2026},
  url = {https://github.com/Rituparno-Majumdar/kp-astrology},
  license = {MIT}
}

The mathematics

Ayanamsa — the sidereal zodiac is the tropical zodiac minus the ayanamsa:

sidereal longitude = tropical longitude - ayanamsa

The Chitrapaksha (Lahiri) zero point anchors the sidereal origin to the star Spica (Chitra) at 0° Libra. Lahiri and KP modes differ only in the exact reference and precession model used; around 2026 the Lahiri ayanamsa is approximately 24.22° (the KP/VP291 value is ~24.14°).

Nakshatra — the zodiac is divided into 27 nakshatras of 13°20' = 800' each.

Sub-lords — each nakshatra is split into 9 sub-lords whose spans are proportional to the Vimshottari years:

sub span (arcmin) = (lord's years / 120) * 800'

The sub-lord sequence starts at the star-lord and cycles through the Vimshottari order; the sub-sub-lord divides the sub again with the same proportions.

Vimshottari years — the total cycle is 120 years:

Planet	Years
Ketu	7
Venus	20
Sun	6
Moon	10
Mars	7
Rahu	18
Jupiter	16
Saturn	19
Mercury	17

Nakshatra lord mapping — the star-lord of nakshatra i (0-26) is:

star_lord(i) = VIMSHOTTARI_ORDER[i % 9]

so the 9-planet Vimshottari cycle repeats every 9 nakshatras: Ketu, Venus, Sun, Moon, Mars, Rahu, Jupiter, Saturn, Mercury, then repeats.

Dasha balance at birth — anchored to the birth Moon's nakshatra (span star = 13°20'), with 1 year = 365.25 days:

MD_bal  = (star_end   - Moon) / star * Y_star * 365.25   # mahadasha balance
AD_bal  = (sub_end    - Moon) / star * Y_star * 365.25   # antardasha balance
PD_bal  = (subsub_end - Moon) / star * Y_star * 365.25   # pratyantar-dasha balance

where star_end is the end of the Moon's nakshatra, sub_end / subsub_end the ends of the Moon's sub / sub-sub, and Y_star the mahadasha years of the star-lord. Every subsequent sub-period is Y_parent * Y_child / 120 years.

Why 249 divisions for horary — 27 nakshatras × 9 sub-lords = 243 subs. Six of the twelve sign boundaries fall inside a sub and split it in two (the sub-lord is unchanged but the sign changes), giving exactly 249 numbered KP divisions from 0° Aries. A querent's number 1-249 selects division n; the horary ascendant is that division's midpoint.

Accuracy & data files

• Moshier fallback (default, no downloads) — planets to about 1 arc-second, Moon about 0.5". More than adequate for KP sub-lord work.
• Full Swiss Ephemeris precision — run python -m kpastro download-ephemeris (or download_ephemeris()), which places sepl_18.se1, semo_18.se1 and seas_18.se1 into ~/.kpastro/ephe. The engine then uses the compressed VSOP87 / JPL DE431 ephemeris at full precision. The files are also picked up from SE_EPHE_PATH.

Project layout

src/kpastro/
  __init__.py       public API surface + version
  __main__.py       python -m kpastro entry point
  constants.py      Vimshottari tables, signs, nakshatras, sign-lords
  vedic.py          pure-Python KP subdivision math (star / sub / sub-sub)
  ephemeris.py      Swiss Ephemeris wrapper, ayanamsa, houses, downloads
  chart.py          BirthInfo, compute_chart, render_chart
  dasha.py          Vimshottari balances, timelines, sub-periods
  significators.py  Grah & Bhaav Nirdeshan, ruling planets
  rectification.py  birth-time rectification (KP "time of birth" method)
  horary.py         the 249-division KP number system
  cli.py            argparse CLI (natal / horary / dasha / ayanamsa / ...)

Roadmap

• Full dasha view with all 120 sub-periods and transit overlays.
• Navamsa and other vargas in the KP scheme.
• KP year (KPY) and Saturn-return timing helpers.
• CLI subcommand for birth-time rectification.
• Western-style event chart export (JSON / CSV).
• Optional TinyDB/Pandas output and Jupyter notebooks.
• Contribution-driven: more ayanamsa modes, house systems, node options.

Contributing

See CONTRIBUTING.md for setup, tests and style. Feedback and pull requests are welcome — file issues at the issue tracker.

License

MIT — see LICENSE. Copyright (c) 2026 Rituparno Majumdar.

Disclaimer

This software is provided for educational and scientific purposes only. Astrological interpretations are not scientific predictions, and nothing here should be used to make financial, medical or legal decisions.