core-astrology-engine

Core Astrology Engine 🌟

A comprehensive, production-ready Vedic astrology calculation library with a developer-friendly API. Built for accuracy, simplicity, and performance.

✨ Key Features

• 🎯 Accurate Calculations: Swiss Ephemeris integration with verified precision
• 🚀 Developer-Friendly: One-line functions for common tasks
• ⚡ High Performance: Batch processing with parallel computation
• 🌍 Smart Timezone Detection: Automatic handling for Nepal/India regions
• 📦 Zero Configuration: Works out of the box with sensible defaults
• 🔧 Highly Configurable: Advanced options when you need them

🚀 Quick Start

Installation

pip install core-astrology-engine

Simple Usage

from core_astrology_engine import get_birth_chart, get_current_dasha

# Get a birth chart with one line
chart = get_birth_chart("1997-10-24T06:30:00", 27.7172, 85.3240)
print(f"Moon at: {chart['planets']['Moon']['longitude']:.1f}° {chart['planets']['Moon']['sign']}")

# Get current dasha periods
dasha = get_current_dasha("1997-10-24T06:30:00", 27.7172, 85.3240)
print(f"Current Mahadasha: {dasha['current_mahadasha']['planet']}")

Comprehensive API

from core_astrology_engine import SimpleAstrology
from datetime import datetime

# Initialize the API
astro = SimpleAstrology()

# Birth details
birth_datetime = datetime(1997, 10, 24, 6, 30)
latitude, longitude = 27.7172, 85.3240  # Kathmandu

# Get complete birth information
info = astro.quick_birth_info(birth_datetime, latitude, longitude)

# Individual calculations
chart = astro.get_chart(birth_datetime, latitude, longitude)
dashas = astro.get_current_dashas(birth_datetime, latitude, longitude)
panchanga = astro.get_panchanga(birth_datetime, latitude, longitude)

📊 What You Can Calculate

Birth Charts

• Complete Vedic charts with planetary positions
• House placements and signs
• Ascendant and planetary dignities
• Retrograde status

Dasha Systems

• Vimshottari Mahadasha periods
• Current and future dasha periods
• High-precision timing calculations
• Sub-period (Antardasha) support

Panchanga

• Daily Panchanga elements
• Nakshatra and Pada
• Tithi, Vara, Yoga, Karana
• Auspicious timing information

Planetary Positions

• Current planetary positions
• Transit calculations
• Specific planet filtering
• Multiple coordinate systems

⚡ Batch Processing

from core_astrology_engine import BatchProcessor, BatchRequest

# Process multiple charts efficiently
batch = BatchProcessor(max_workers=4)

requests = [
    BatchRequest("person1", datetime(1997, 10, 24, 6, 30), 27.7172, 85.3240),
    BatchRequest("person2", datetime(1985, 5, 15, 14, 20), 28.6139, 77.2090),
]

results = batch.process_charts(requests)
batch.export_results(results, "charts.json")

🎛️ Output Formats

# Dictionary format (default)
chart = astro.get_chart(birth_datetime, lat, lon, format='dict')

# JSON string
chart_json = astro.get_chart(birth_datetime, lat, lon, format='json')

# Raw objects (for advanced usage)
chart_obj = astro.get_chart(birth_datetime, lat, lon, format='object')

🌍 Automatic Timezone Detection

# Automatically detects timezone for Nepal/India
chart = astro.get_chart(birth_datetime, latitude, longitude)

# Manual timezone specification
chart = astro.get_chart(birth_datetime, latitude, longitude, timezone_offset=5.75)

📚 Comprehensive Documentation

• Usage Examples - Detailed examples for all features
• Developer Features - Complete feature overview
• Configuration Guide - Advanced configuration options

🔬 Verified Accuracy

This library has been extensively tested with real birth data:

Test Case: October 24, 1997, 6:30 AM, Kathmandu

• Expected: Moon at ~16° Cancer, Venus Dasha 2022-2042
• Results: Moon at 16.14° Cancer ✓, Venus Dasha 2022-2042 ✓

🏗️ Architecture

core_astrology_engine/
├── api/              # Simple API layer
├── services/         # Core calculation services
├── models/           # Data models
├── utils/            # Utility functions
├── config/           # Configuration management
└── data/             # Ephemeris data

🎯 Design Philosophy

• Simplicity First: Common tasks should be one-liners
• Accuracy: Swiss Ephemeris with proper astronomical calculations
• Flexibility: Support for different input/output formats
• Performance: Optimized for both single and batch calculations
• Developer Experience: Clear APIs, helpful errors, comprehensive docs

🔧 Requirements

• Python >=3.8
• Minimal dependencies
• Swiss Ephemeris (included)
• Cross-platform compatibility

🚀 Performance

• Single Chart: ~10-50ms
• Batch Processing: 100+ charts/second with parallel processing
• Memory Efficient: Optimized for large-scale calculations
• Caching: Optional caching for repeated calculations

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Note: This software uses the Swiss Ephemeris, which has its own licensing terms for commercial use. See the LICENSE file for details.

🙏 Acknowledgments

• Swiss Ephemeris by Astrodienst AG
• The global astrology and astronomy communities
• Contributors and testers

📞 Support

• 🐛 Report Issues
• 📖 Documentation
• 💬 Discussions

Made with ❤️ for the astrology and developer communities

Made with ❤️ for the astrology and developer communities

Type Checking

mypy core_astrology_engine/

Contributing

• Fork the repository
• Create a feature branch (git checkout -b feature/amazing-feature)
• Commit your changes (git commit -m 'Add amazing feature')
• Push to the branch (git push origin feature/amazing-feature)
• Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Swiss Ephemeris for accurate planetary calculations
• Ancient Vedic astrology traditions and texts
• The global astrology development community

Support

• Documentation: https://core-astrology-engine.readthedocs.io/
• Issues: https://github.com/yourusername/core-astrology-engine/issues
• Discussions: https://github.com/yourusername/core-astrology-engine/discussions