Metadata-Version: 2.4
Name: odins-oracle
Version: 2.0.0
Summary: Python SDK for Odin's Oracle API - cosmic intelligence and Agent Soul Protocol for AI agents
Project-URL: Homepage, https://odins-oracle.com
Project-URL: Documentation, https://odins-oracle.com/docs/python
Project-URL: Repository, https://github.com/odins-oracle/python-sdk
Project-URL: Issues, https://github.com/odins-oracle/python-sdk/issues
Author-email: Odin's Eye Enterprises <dev@odinseyeenterprises.com>
License: MIT
Keywords: agent-soul,ai-agent-identity,api,astrology,cosmic,natal-chart,sdk,transits
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Provides-Extra: all
Requires-Dist: httpx>=0.24.0; extra == 'all'
Requires-Dist: requests>=2.25.0; extra == 'all'
Provides-Extra: async
Requires-Dist: httpx>=0.24.0; extra == 'async'
Provides-Extra: dev
Requires-Dist: black; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Provides-Extra: sync
Requires-Dist: requests>=2.25.0; extra == 'sync'
Description-Content-Type: text/markdown

# Odin's Oracle Python SDK

[![PyPI version](https://badge.fury.io/py/odins-oracle.svg)](https://badge.fury.io/py/odins-oracle)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

> *"Ancient wisdom meets modern intelligence."*

The official Python SDK for [Odin's Oracle](https://odins-oracle.com) — integrate astrological wisdom into your applications with ease.

## Features

- ✨ **Complete Natal Charts** — Calculate full natal charts with planetary positions, houses, and aspects
- 🌙 **Transit Analysis** — Analyze current planetary transits against any natal chart
- 🔮 **Rune Glyphs** — Generate unique sigils derived from chart data
- ⚡ **Async Support** — Full async/await support for high-performance applications
- 📝 **Type Hints** — Complete type annotations for excellent IDE support
- 🛡️ **Error Handling** — Comprehensive exceptions for all error cases

## Installation

```bash
# Sync client only (uses requests)
pip install odins-oracle[sync]

# Async client only (uses httpx)
pip install odins-oracle[async]

# Both sync and async
pip install odins-oracle[all]
```

## Quick Start

```python
from odins_oracle import OracleClient

# Initialize client
client = OracleClient(api_key="your_api_key")

# Calculate natal chart
chart = client.natal_chart(
    birth_date="1990-06-15",
    birth_time="14:30",
    latitude=41.8781,
    longitude=-87.6298
)

# Access chart data
print(f"Sun: {chart.sun.sign}")           # Gemini
print(f"Moon: {chart.moon.sign}")         # Virgo
print(f"Rising: {chart.rising.sign}")     # Libra
print(f"Rune Glyph: {chart.rune_glyph}")  # ᚠᚢᚦᚨ

# Get all planets
for planet in chart.planets:
    print(f"{planet.glyph} {planet.sign} {planet.degree}°")

# Find aspects
for aspect in chart.aspects[:5]:
    print(f"{aspect.planet1} {aspect.aspect_type} {aspect.planet2}")
```

## Async Usage

```python
import asyncio
from odins_oracle import OracleClient

async def main():
    async with OracleClient(api_key="your_api_key") as client:
        chart = await client.anatal_chart(
            birth_date="1990-06-15",
            birth_time="14:30",
            latitude=41.8781,
            longitude=-87.6298
        )
        print(chart.chart_signature)

asyncio.run(main())
```

## Transit Analysis

```python
# Calculate transits for today
transits = client.transits(natal_chart_id=chart_id)

# Get significant transits
for transit in transits.significant_transits:
    print(f"{transit.transiting_planet} {transit.aspect_type} your {transit.natal_planet}")

# Check transits to specific planet
moon_transits = transits.get_transits_to("moon")
```

## Advanced Usage

### Working with Houses

```python
# Get planets in a specific house
first_house_planets = chart.get_planets_in_house(1)

# Get house cusp
second_house = chart.get_house(2)
print(f"2nd House: {second_house.sign} {second_house.degree}°")
```

### Finding Aspects

```python
# Get all aspects involving the Sun
sun_aspects = chart.get_aspects_to("sun")

# Filter by aspect type
squares = [a for a in chart.aspects if a.aspect_type == "Square"]
```

## Error Handling

```python
from odins_oracle import (
    OracleClient,
    AuthenticationError,
    RateLimitError,
    ValidationError,
)

try:
    chart = client.natal_chart(
        birth_date="invalid-date",  # Will raise ValidationError
        birth_time="14:30",
        latitude=41.8781,
        longitude=-87.6298
    )
except ValidationError as e:
    print(f"Validation failed: {e.message}")
    print(f"Errors: {e.errors}")
except AuthenticationError:
    print("Invalid API key")
except RateLimitError:
    print("Rate limit exceeded - try again later")
```

## API Reference

### OracleClient

The main client class for interacting with the API.

#### Constructor

```python
OracleClient(
    api_key: str,
    base_url: Optional[str] = None,
    timeout: float = 30.0
)
```

#### Methods

- `natal_chart(...)` — Calculate a complete natal chart
- `transits(natal_chart_id, date=None)` — Calculate transits
- `planets()` — List all supported planets
- `anatal_chart(...)` — Async version of natal_chart
- `atransits(...)` — Async version of transits
- `aplanets()` — Async version of planets

### Models

- `NatalChart` — Complete chart with planets, houses, aspects
- `PlanetPosition` — Individual planet position data
- `ChartSignature` — Quick reference (Sun, Moon, Rising, MC)
- `Aspect` — Planetary aspect data
- `Transit` — Transit analysis results

## Documentation

Full documentation is available at [odins-oracle.com/docs/python](https://odins-oracle.com/docs/python)

## License

MIT License — see [LICENSE](LICENSE) for details.

---

<p align="center">
  <sub>Built with ᛟ by <a href="https://odinseyeenterprises.com">Odin's Eye Enterprises</a></sub>
</p>