Metadata-Version: 2.4
Name: openjyotish
Version: 1.9.0
Summary: Free, open-source, cross-platform Vedic astrology toolkit with AI-powered chart readings.
Author: Jhora Contributors
License: GPL-3.0-only
Project-URL: Homepage, https://github.com/velteyn/OpenJyotish
Project-URL: Repository, https://github.com/velteyn/OpenJyotish.git
Project-URL: Issues, https://github.com/velteyn/OpenJyotish/issues
Keywords: vedic,astrology,jyotish,hora,dasa,yoga
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Astronomy
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyQt6>=6.11.0
Requires-Dist: pyswisseph>=2.10.3.2
Requires-Dist: typer>=0.27.2
Requires-Dist: rich>=15.0.0
Requires-Dist: requests>=2.34.2
Requires-Dist: prompt_toolkit>=3.0.53
Requires-Dist: numpy>=2.4.6
Requires-Dist: tzdata>=2026.4; platform_system == "Windows"
Provides-Extra: test
Requires-Dist: pytest>=9.1.1; extra == "test"
Dynamic: license-file

# OpenJyotish — Free Vedic Astrology Toolkit

Free, open-source, cross-platform Vedic astrology software.  
**CLI** + **GUI** (PyQt6) + **TUI** (terminal). AI-powered readings via local LLMs.

```
56 CLI commands  |  10 GUI categories + sub-tabs  |  9 TUI menus + sub-menus
31-section JSON API for AI agents (+ JSON-LD)  |  1749 tests  |  GPL v3.0
```

<img src="docs/images/wheel.png" width="600" alt="Circular natal + transit bi-wheel with drishti lines">

> **Showcase: [the Gandhi retrospective](docs/gandhi-retrospective.md)** —
> a pre-registered validation study. Fixed chart, seven datable life events,
> dashas/transits/yogas checked in the open, miss included.

## Quick Install

### Option 1: Release (Windows — no Python needed)
Download the latest `openjyotish-v*-windows.zip` from [Releases](https://github.com/velteyn/OpenJyotish/releases).  
Extract, double-click `OpenJyotish.bat`. Includes ephemeris data.

### Option 2: From source (Linux / Mac / Windows with Python)

```bash
# Linux / Mac
git clone https://github.com/velteyn/OpenJyotish.git
cd OpenJyotish
./install.sh
./run.sh

# Windows
git clone https://github.com/velteyn/OpenJyotish.git
cd OpenJyotish
install.bat
run.bat
```

**Requires**: Python 3.11+

Ephemeris data is auto-downloaded by `install.sh` / `install.bat` (2 files, ~1MB).
pip installs: the app offers the one-time download on first Calculate
(or Tools → Ephemeris → Download, or `openjyotish download-ephe`). Your own
textbook `.txt` files go in the books folder inside your per-user data
directory (Knowledge tab → "Import books…" or `openjyotish knowledge-import
f.txt`), then Build/Rebuild the Vector DB. The public repo ships a clean
database (schema + city atlas, no book texts): your library stays yours.
Out of the box you still get a working library: our 10-chapter OpenJyotish
Primer plus four public-domain classics (Iyer's Brihat Jataka 1885 and
Brihat Samhita 1884, Burgess's Surya Siddhanta 1860, Sastri's Siddhanta
Siromani 1861 — provenance in src/jhora/data/books/SOURCES-PD.md). The
vector build loads them automatically on first run, so the Guru and Learn
cite real textbooks with zero setup.

### No-Python downloads (Windows & macOS)

Each [release](https://github.com/velteyn/OpenJyotish/releases) ships
ready-to-run binaries — no Python, pip or terminal needed:

| Platform | Files |
|----------|-------|
| Windows | `OpenJyotish-<ver>-Windows-Setup.exe` (installer: wizard, Start menu, uninstaller) |
| Linux | `OpenJyotish-<ver>-Linux-amd64.deb` (`sudo dpkg -i`, menu entry + `openjyotish` CLI) or `-Linux-x86_64.tar.gz` |

Notes: the apps are unsigned, so Windows SmartScreen will ask once
("More info" → Run). Your charts live per-user (`%APPDATA%\OpenJyotish`
on Windows).

## One-Minute Examples

```bash
# Get your chart
openjyotish chart "1973-03-14 14:55 +0100 45.41 11.88"

# Everything at a glance (AI-friendly JSON)
openjyotish analyze "1973-03-14 14:55 +0100 45.41 11.88"

# Current dasa period
openjyotish dasa-timeline "1973-03-14 14:55 +0100 45.41 11.88"

# Choghadiya — auspicious/inauspicious time slots for today
openjyotish choghadiya --lat 28.61 --lon 77.21 --tz 5.5

# Strengths
openjyotish shadbala --bhava --vimsopaka "birthdata"

# Prediction (Tithi Pravesha)
openjyotish tithi-pravesha "birthdata"

# Matchmaking
openjyotish kuta "girl_birthdata" "boy_birthdata"

# AI interpretation (needs Ollama)
# Full guide: https://github.com/velteyn/OpenJyotish/wiki/AI-Complete-Guide
openjyotish ai "birthdata"
openjyotish teach "How do I read my 7th house?" --chart "birthdata"

# Launch desktop app
./run.sh
```

## Birth Data Format

All commands accept birth data as: `"YYYY-MM-DD HH:MM TZ LAT LON"`

```
"1973-03-14 14:55 +0100 45.41 11.88"
  │         │     │     │      └─ Longitude (E positive)
  │         │     │     └─ Latitude (N positive)  
  │         │     └─ Timezone (+0100 = UTC+1, +0530 = India, -0500 = EST)
  │         └─ Local time (24h)
  └─ Date
```

## GUI

`openjyotish gui` or `./run.sh` — 10 main categories with sub-tabs:

| Category | Contains |
|----------|----------|
| **Birth Data** | Birth form + confirmation chart (Calculate lands on Chart View) |
| **Dashboard** | Current dasa, transits, strengths, upcoming |
| **Chart & Varga** | Chart View (Planets & Data, Ashtakavarga), Compare, Planets, Houses & Chalit, Varga Charts, Yogas |
| **Strengths** | Shadbala, Arudha & Karaka, Ashtakavarga |
| **Dasas** | Dasa Periods with interactive bar chart |
| **Transits & Tajaka** | Transits, Tajaka & TP, Mundane, Chakras |
| **Special** | Matchmaking, Prasna, Muhurta (incl. Choghadiya), Calendar, KP, Remedies, Points & Maitri (incl. Marana, Vaiseshikamsa) |
| **AI & Learn** | AI Chat, AI Teacher, Knowledge, Reading |
| **Tools** | Ephemeris |
| **Wheel** | Circular natal + transit bi-wheel (Lagna-left, glyphs, drishti) |

**Getting started**: Fill form → "Find" city → "Now" button → "Calculate"

### Supported AI Models

Prompt templates, thinking behavior and context needs differ per model, so
only this slate is verified (eval harness) and guaranteed:

| Pick | Model (LM Studio key) | For |
|------|----------------------|-----|
| Quality | `mistralai/ministral-3-14b-reasoning` | Best entities/faithfulness; slow on small GPUs |
| Speed/VRAM | `qwen/qwen3.5-9b` (clean instruct release) | Fits 8GB VRAM, fast; weaker entity tracking |

Set it in the AI tab's **Prefer** field (or CLI `--preferred-model`); the app
auto-loads it with a VRAM-safe context and never unloads your own models.
Roleplay/abliterated merges and ultra-low quants (IQ1_S) confabulate lore —
avoid them for readings. Anything outside the slate may work but is **not
guaranteed**.

Full audit trail, per-model scorecards and setup laws: `docs/AI_LESSONS.md`.

### Astrologer adapter (optional)

A domain LoRA — `openjyotish-astrologer-lora-vN` — is published with each
release to cut verifier flags on readings. It assists wording only; the engine
still owns every fact and verify-repair stays on. Dataset generation, the
Unsloth recipe, the eval harness and the LM Studio / Ollama / Unsloth Studio
loader steps (plus the `--provider`/`--model`/`--url` setting) are in
`tools/train/README.md`.

## TUI

`openjyotish tui` — interactive terminal app with the same 9-category structure.  
Arrow keys ↑↓ to navigate, letters to jump, Enter to select, `b` to go back, `q` to quit.

```
Main Menu:
  1  Birth Data Input          d  Dashboard
  c  Chart & Varga             s  Strengths
  a  Dasas & Timing            t  Transits & Tajaka
  x  Special                   i  AI & Knowledge
  u  Tools                     q  Quit
```

## AI Tool-Calling (JSON API)

One command, everything computed. Pipe to AI agents, `jq`, or Python:

```bash
openjyotish analyze "birthdata"
# → 10KB JSON — 21 sections, every calculation

# Pipe it around
openjyotish analyze "..." | jq '.planets.Su.house'
openjyotish analyze "..." | jq '.dasa.mahadashas[] | select(.current)'
openjyotish analyze "..." | jq '.dasa.systems'   # current MD in every dasa system
openjyotish analyze "..." | jq '.choghadiya.current'   # current Choghadiya slot
openjyotish analyze "..." | jq '.muhurta_adjuncts.chandra_bala'   # daily adjunct grades
```

```python
import json, subprocess
data = json.loads(subprocess.run(
    ["openjyotish", "analyze", birthdata], capture_output=True, text=True
).stdout)
```

## All CLI Commands (42)

| Command | What it does |
|---------|-------------|
| `chart` | Rasi chart + planets (combustion, gandanta, avastha) + upagrahas + outer planets (`--nodes` mean/true, `--chalit` + `--bhava-method` default/sripati) |
| `analyze` | AI-friendly JSON dump (31 sections, incl. omens, Sade Sati timeline, dasa entry) |
| `shadbala` | Six-fold planetary strength (+ --bhava + --vimsopaka) |
| `kuja-dosha` | Kuja Dosha (Mangal Dosha) Mars affliction |
| `yogas` | Detect 200+ planetary combinations (incl. 32 Naabhasa) |
| `ashtakavarga` | BAV, SAV, Sodhya Pinda, Kakshya bindu, Bala reduction stages (`--bala`) |
| `dasa` | Dasa periods for any system: vimsottari/ashtottari/yogini/sudasa/chara/narayana/kalachakra/brahma/karaka/shoola/trikona/varnada/sthira/navamsa/yogardha/niryana-shoola/lagna-kendradi/drig/sudarshana/moola/tara/buddhi-gati/lagnamsaka/padanaathaamsa/rasi-bhukta-vimsottari (MD/AD; system positional, `--karaka-role` for karaka, `--house` for shoola, `--buddhi-gati-varga` for buddhi-gati) |
| `dasa-timeline` | Text bar chart with now-marker |
| `dasa-chart` | Period tree around the running period (MD → AD → PD; `--at`, `--depth`) |
| `dasa-entry` | Entry chart — sky at a period's opening (`PATH` like `Jupiter/Saturn`; `--system`) |
| `conditional-dasas` | List additional dasa systems that apply |
| `transit` | Current transits with SAV scores and gochara vedha (obstruction) |
| `sade-sati` | Sade Sati phase dates (12th/peak/2nd) + Kantaka/Ashtama Shani timeline |
| `special-points` | Baadhaka sthana, Pushkara navamsa/bhaga, Mrityu bhaga, 64th navamsa, 22nd drekkana |
| `maitri` | Graha Maitri — natural, temporal and compound (Panchadha) friendship tables |
| `argala` | Planetary intervention on the bhavas (Jaimini 1-1-5/10; `--house`) |
| `avakahada` | Birth identity — rasi, nakshatra, pada, nama syllable, gana, yoni, nadi |
| `asta-udaya` | Venus/Jupiter combust + rising windows for a year (marriage blockers) |
| `dasa-sandhi` | MD junctions (10% rule) + `--chidra` final bhukti (`--system`) |
| `drishti` | Parashara aspects — houses from lagna each planet aspects |
| `tajaka` | Tajaka return charts — annual/monthly/2.5-day/5-hr/25-min/2-min (`--level`, `--index`, `--sunrise`, `--vimshottari` sesham/full from the return Moon) + Tajaka yogas on CLI/GUI |
| `tithi-pravesha` | Annual solar-tithi ingress |
| `progression` | Secondary progressions (1 day = 1 year) |
| `kuta` | Marriage compatibility (Porutham + Ashta Koota) |
| `prasna` | Horary (108/249/Nadi modes) |
| `muhurta` | Electional — 11 task types (+ `--adjuncts` daily table, `--janma-nakshatra` Bala grades) |
| `choghadiya` | 8 day + 8 night auspicious/inauspicious time slots |
| `hora` | Planetary hours — 24 horas (12 day + 12 night) in Chaldean order |
| `mundane` | World events, eclipses, ingresses |
| `compare` | Natal vs transit or two-chart comparison |
| `interpret` | Rule-based chart reading |
| `traditional-report` | Formatted traditional-style chart report |
| `knowledge` | Search Vedic textbooks provided by you in txt format |
| `ai` | LLM chart reading (Ollama/LM Studio/Unsloth) |
| `teach` | AI Teacher — learn Vedic astrology |
| `export` | HTML report — positions, strengths (incl. per-varga), ashtakavarga, yogas, sahamas, special lagnas, arudhas, karakas, KP, chalit, dasa, transits, Sade Sati timeline |
| `ephemeris` | Daily planet table |
| `varga` | Any divisional chart (D-1 to D-150) |
| `navamsa` | D-9 Navamsa |
| `vargottama` | Planets/lagna holding the same rasi in D-1 and each varga (D-9 classical) |
| `panchanga` | Monthly calendar (paksha/tithi/nakshatra/yoga/karana, sunrise/sunset, rahu kalam; `--adjuncts` adds Durmuhurta/Varjya) |
| `chakras` | Sarvatobhadra + Kota chakras |
| `lagnas` | All special lagnas with meanings |
| `kp` | Krishnamurti Paddhati — Placidus cusp/planet lord chains, Ruling Planets, bhava significators, and the KP view of the Vimsottari dasa (`--ayanamsa krishnamurti`, `--when`) |
| `sphutas` | Prasna Marga auspicious points (Tri/Chatus/Pancha/Prana/Deha/Mrityu/Beeja/Kshetra/Yoga) |
| `upagrahas` | Solar + temporal (Gulika/Mandi) sub-planets |
| `remedies` | Rule-based remedies — Ishta/Palana devata, gemstone, mantra, yantra, charity, dasha-lord, doshas; `--partner` adds marriage doshas (sourced) |
| `learning` | Marana karaka, KP sub-lords, vaiseshikamsas |
| `tui` | Launch interactive terminal UI |
| `gui` | Launch desktop GUI |

## Features

### Calculation Engine
Rasi chart (D-1) with South/North/East styles · 23 varga charts (D-2 to D-150) ·
32 dasa systems (incl. Moola + Tara + Narayana variants) · 8 conditional dasas · Shadbala · Bhava Bala (per-varga) · Vimsopaka Bala (5 schemes incl. Dwadasa Vargeeya) ·
200+ yogas · 36 Sahamas · Rule-based remedies · Ashtakavarga (BAV/SAV/Kakshya) · Arudha Padas · Chara Karakas ·
36 Sahamas · 20 ayanamsa modes (Lahiri/Raman/KP/Fagan/Tropical/etc.) ·
Outer planets (Uranus/Neptune/Pluto) · Upagrahas (5 solar + Gulika/Mandi) ·
Special lagnas (Bhrigu Bindu/Indu/Varnada/Pranapada/Vighati) ·
KP mode — Placidus cusp/planet lord chains, Ruling Planets, sub-lords (5 levels) · Chalit/Bhava charts (any varga)
Tattva dignities · Jaimini rasi strength · Graha-drishti API (give/receive) · JSON-LD export (`analyze --jsonld`)

### Forecasting
Transits with SAV scores · Tajaka solar return · Tithi Pravesha ·
Progressions · Dasa timeline · Mundane (ingresses/eclipses/conjunctions) ·
Matchmaking (10 Porutham + Ashta Koota 36pt) · Muhurta · Monthly calendar · Choghadiya · Hora · Prasna

### AI & Data
Local LLM (Ollama/LM Studio/Unsloth) · RAG pipeline with textbook citations ·
AI Teacher mode · 8 AI topic templates · Context budgeting for small models ·
LM Studio setup guard (preferred model auto-load with VRAM-safe context) ·
Mechanical answer verification (every reading checked against computed data) ·
Unified SQLite DB (atlas 34K cities + knowledge + charts) · HTML export ·
JHD import/export · Chart browser · JSON API for AI agents

## Architecture

```
src/jhora/
├── types/          Enums: Graha, Rasi, Nakshatra, Varga, Bhava, Dasa
├── ephemeris/      Swiss Ephemeris wrapper (18 API functions)
├── charts/         ChartBuilder, ChartData (frozen), VargaChartComputer
├── calc/           29 modules: strengths, yogas, dasas, transits, chakras...
├── dasas/          32 dasa systems (+ shared Jaimini core)
├── ai/             AI engine, RAG pipeline, JSON export, teacher
├── interpreter/    Chart reading, knowledge base
├── export/         HTML report generator
├── io/             Atlas (SQLite/FTS5), JHD parser
├── core/           Unified database
├── cli/            Typer CLI (42 commands)
├── tui/            prompt_toolkit menu system
└── ui/             PyQt6 GUI (8-category tabs, chart widget, dasa timeline)
```

### 💬 Community & Support
If you want to discuss the project, ask questions, or share your own astrology software tools, join our official community on Reddit: [r/AstrologySoftware](https://www.reddit.com/r/AstrologySoftware/).

## Traditions & Lineage

No single sampradaya — like the classical compendium tradition itself, this toolkit follows an eclectic
school with a clear backbone:

- **Parashara core** (Brihat Parashara Hora Shastra): Lahiri ayanamsa,
  whole-sign Rasi houses, Vimsottari dasa, Shadbala, Ashtakavarga —
  the mainstream North-Indian practice most software implements.
- **Jaimini integration** (SJC / Sanjay Rath lineage, via P.V.R. Narasimha
  Rao's integrated approach): Arudha Padas, Chara Karakas, Rasi dasas
  (Chara, Narayana, Sudasa).
- **Karnataka muhurta** (B.V. Raman): electional rules, Panchaka-Rahita,
  Durmuhurta/Varjya.
- **Krishnamurti elements**: KP sub-lords for stellar precision.
- **Tajaka annual horoscopy**: Indo-Persian Varshaphala (solar returns,
  Muntha, Mudda/Patyayini dasas).

Purists of any single tradition will find foreign bodies here; that mixing
*is* the school this project continues.

## Credits

Methodology follows the PVR Narasimha Rao / Sri Jagannath Centre tradition; classical texts are cited per module.  
Atlas data: GeoNames.org (CC BY 4.0).  

## License

**GNU GENERAL PUBLIC LICENSE v3.0** — free forever.  
Modifications must remain open. Network use counts as distribution.
