# Acharavidya (आचारविद्या)

**Indian Dharmic Knowledge Platform** — Accurate Panchanga, Daily Almanac & More

> Built with **Kaalavidya (कालविद्या)** — The Science of Time

---

## What is this?

Acharavidya is a platform for Indian traditional time-keeping and dharmic knowledge. The first module — **Kaalavidya** — is a fully functional Vedic Panchanga (almanac) that computes:

- **Pancha Anga**: Tithi, Vara, Nakshatra (with pada), Yoga, Karana — all with transition times
- **Calendar**: Samvatsara, Masa (Amanta + Purnimanta), Paksha, Ritu, Ayana, Era Years
- **Sun/Moon**: Vedic & Drik sunrise/sunset, moonrise/moonset, day/night durations
- **Auspicious**: Brahma Muhurta, Abhijit, Amrit Kalam, Vijaya, Godhuli
- **Inauspicious**: Rahu Kala, Yamagandam, Gulika Kala, Durmuhurta, Varjyam
- **Muhurtas**: 15 Dina + 15 Ratri muhurtas with names and auspiciousness
- **Charts**: Sunrise Rashi chart (South & North Indian), Planetary Orrery
- **Planetary**: Tarabalam, Chandrabalam, Combustion (Maudhya), Hora table
- **Eclipses**: Solar & Lunar with local visibility
- **Surya Siddhanta**: Traditional calculation engine as alternative to modern astronomy
- **7 Languages**: English, Sanskrit, Hindi, Telugu, Tamil, Kannada, Malayalam

---

## Quick Start

### Prerequisites

- **Python 3.9+** (tested on 3.9, 3.10, 3.11)
- **pip** (Python package manager)

### Setup

```bash
# Clone the repo
git clone https://github.com/vikranthkorata/acharavidya.git
cd acharavidya

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # Linux/macOS
# venv\Scripts\activate   # Windows

# Install dependencies
pip install -r requirements.txt

# Run the app
PYTHONPATH=. uvicorn app:app --reload --host 0.0.0.0 --port 8000
```

### Open in Browser

Navigate to **http://localhost:8000**

---

## Project Structure

```
acharavidya/
├── app.py                          # FastAPI application (API + static serving)
├── requirements.txt                # Python dependencies
├── kaalavidya/                     # Core Panchanga engine (also pip library)
│   ├── __init__.py                 # Public API exports
│   ├── constants.py                # Names, mappings, adhipati data, tables
│   ├── models.py                   # Data structures (dataclasses)
│   ├── panchanga.py                # Main Panchanga class (Drik engine)
│   ├── surya.py                    # Sun/Moon times, muhurtas, hora
│   ├── chandra.py                  # Tithi, nakshatra, yoga, karana, masa
│   ├── lagna.py                    # Ascendant/Lagna table
│   ├── chart.py                    # Rashi chart + planetary orrery
│   ├── grahana.py                  # Eclipse detection
│   ├── sankalpa.py                 # Sankalpa generator (desha-kala)
│   ├── vrata.py                    # Festival/Vrata engine (skeleton)
│   └── surya_siddhanta/            # Traditional Indian astronomy
│       ├── ganita.py               # SS longitude formulas
│       ├── sunrise.py              # SS sunrise/sunset
│       └── panchanga_ss.py         # Full SS panchanga
├── static/                         # Web frontend
│   ├── index.html                  # Main page
│   ├── style.css                   # Styling
│   ├── app.js                      # Main JS (rendering, i18n)
│   ├── chart.js                    # SVG chart renderer
│   └── orrery.js                   # SVG planetary orrery
├── data/
│   └── cities.json                 # Indian cities database
├── tests/                          # Test files
│   ├── test_panchanga.py
│   └── test_surya_siddhanta.py
└── docs/
    └── PRD.md                      # Product Requirements Document
```

---

## API Usage

### REST API

```bash
# Full daily panchanga
curl "http://localhost:8000/api/panchanga?year=2026&month=2&day=19&lat=16.5062&lon=80.648&lang=en&method=drik"

# Chart at specific time
curl "http://localhost:8000/api/chart?year=2026&month=2&day=19&hour=12&minute=0&lat=16.5062&lon=80.648&lang=en"

# City search
curl "http://localhost:8000/api/cities?q=Vijayawada"
```

### Python Library

```python
from kaalavidya import Panchanga

# Full panchanga for a date and location
p = Panchanga(
    year=2026, month=2, day=19,
    latitude=16.5062, longitude=80.648,
    timezone="Asia/Kolkata",
    city="Vijayawada",
    lang="en",
    method="drik",  # or "siddhantic"
)
result = p.compute()
print(result.summary())

# Access individual fields
print(f"Tithi: {result.tithi[0].name}")
print(f"Nakshatra: {result.nakshatra[0].name} (Pada {result.nakshatra[0].pada})")
print(f"Samvatsara: {result.samvatsara}")

# Modular access — compute only what you need
from kaalavidya import compute_tithi, compute_sun_times
from datetime import datetime
from zoneinfo import ZoneInfo

sunrise = datetime(2026, 2, 19, 6, 30, tzinfo=ZoneInfo("Asia/Kolkata"))
next_sunrise = datetime(2026, 2, 20, 6, 30, tzinfo=ZoneInfo("Asia/Kolkata"))
tithis = compute_tithi(sunrise, next_sunrise, "en")
for t in tithis:
    print(f"  {t.name} — Devata: {t.devata}, Group: {t.group}")
```

---

## Dependencies

| Package | Version | Purpose |
|---------|---------|---------|
| fastapi | ≥0.100 | Web framework & API |
| uvicorn | ≥0.23 | ASGI server |
| pyswisseph | ≥2.10 | Swiss Ephemeris (NASA JPL DE431 ephemeris) |
| astral | ≥3.2 | Sunrise/sunset/twilight calculations |

All dependencies are listed in `requirements.txt`.

---

## Calculation Methods

### Drik Ganita (Default)
- Uses Swiss Ephemeris (pyswisseph) backed by NASA JPL DE431 ephemeris
- Extremely precise modern astronomical positions
- Lahiri Ayanamsha for sidereal corrections
- Full feature support (Lagna, Maudhya, Eclipses, Charts, Orrery)

### Surya Siddhanta
- Traditional Indian astronomical text (~400 CE)
- Mean + manda-corrected longitudes
- Kali Yuga epoch-based calculations
- Most features supported; Lagna/Eclipses/Maudhya require Swiss Eph

---

## Languages

| Code | Language | How it works |
|------|----------|-------------|
| `en` | English | Transliterated Sanskrit names (Surya, Mesha, Tithi) |
| `sa` | संस्कृतम् | Full Sanskrit — every label and data point |
| `hi` | हिन्दी | Sanskrit words in Devanagari script |
| `te` | తెలుగు | Sanskrit words in Telugu script |
| `ta` | தமிழ் | Sanskrit words in Tamil script |
| `kn` | ಕನ್ನಡ | Sanskrit words in Kannada script |
| `ml` | മലയാളം | Sanskrit words in Malayalam script |

---

## Running Tests

```bash
cd acharavidya
source venv/bin/activate
PYTHONPATH=. python -m pytest tests/ -v
```

---

## Contributing

This project draws from traditional Indian texts including:
- Surya Siddhanta
- Brihat Parashara Hora Shastra
- Dharmasindhu
- Nirnayasindhu
- Tattvadipika

Contributions welcome — especially for Vrata rules, regional variations, and translations.

---

## Install as Python Library

```bash
pip install kaalavidya
```

Or install from source:
```bash
cd acharavidya
pip install .
```

With web server dependencies:
```bash
pip install kaalavidya[server]
```

## License

MIT License — see [LICENSE](https://github.com/vikranthkorata/acharavidya/blob/main/LICENSE) for details.

---

*आचारविद्या — Built with love for Sanatana Dharma*
