core-astrology-engine 1.0.0
A comprehensive Vedic astrology calculation library with developer-friendly API
License: MIT
Requires Python: >=3.8
Keywords: astrology, vedic, horoscope, chart, dasha, panchanga, ephemeris, swiss-ephemeris, planetary-positions, nakshatra

# Core Astrology Engine 🌟

[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![PyPI version](https://badge.fury.io/py/core-astrology-engine.svg)](https://badge.fury.io/py/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

```bash
pip install core-astrology-engine
```

### Simple Usage

```python
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

```python
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

```python
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

```python
# 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

```python
# 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](USAGE_EXAMPLES.md) - Detailed examples for all features
- [Developer Features](DEVELOPER_FEATURES_SUMMARY.md) - Complete feature overview
- [Configuration Guide](docs/configuration.md) - 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

1. **Simplicity First**: Common tasks should be one-liners
2. **Accuracy**: Swiss Ephemeris with proper astronomical calculations
3. **Flexibility**: Support for different input/output formats
4. **Performance**: Optimized for both single and batch calculations
5. **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](CONTRIBUTING.md) for details.

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](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](https://www.astro.com/swisseph/) by Astrodienst AG
- The global astrology and astronomy communities
- Contributors and testers

## 📞 Support

- 🐛 [Report Issues](https://github.com/devsujan24/core-astrology-engine/issues)
- 📖 [Documentation](https://github.com/devsujan24/core-astrology-engine/blob/main/README.md)
- 💬 [Discussions](https://github.com/devsujan24/core-astrology-engine/discussions)

---

**Made with ❤️ for the astrology and developer communities**

---

**Made with ❤️ for the astrology and developer communities**

### Type Checking
```bash
mypy core_astrology_engine/
```

## Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

This project is licensed under the MIT License - see the [LICENSE](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/](https://core-astrology-engine.readthedocs.io/)
- Issues: [https://github.com/yourusername/core-astrology-engine/issues](https://github.com/yourusername/core-astrology-engine/issues)
- Discussions: [https://github.com/yourusername/core-astrology-engine/discussions](https://github.com/yourusername/core-astrology-engine/discussions)