OpenJyotish — Free Vedic Astrology Toolkit

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

51 CLI commands  |  8 GUI categories + sub-tabs  |  9 TUI menus + sub-menus
28-section JSON API for AI agents (+ JSON-LD)  |  1631 tests  |  GPL v3.0

Showcase: the Gandhi retrospective — 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.
Extract, double-click OpenJyotish.bat. Includes ephemeris data.

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

# 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 ships ready-to-run binaries — no Python, pip or terminal needed:

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

# 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 — 8 main categories with sub-tabs:

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:

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:

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

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

All CLI Commands (42)

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 · 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.

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.