odins-oracle 2.0.0

Python SDK for Odin's Oracle API - cosmic intelligence and Agent Soul Protocol for AI agents

Odin's Oracle Python SDK

"Ancient wisdom meets modern intelligence."

The official Python SDK for Odin's Oracle — 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

# 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

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

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

# 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

# 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

# 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

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

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

License

MIT License — see LICENSE for details.

---

_{Built with ᛟ by Odin's Eye Enterprises}