🌟 Stellium

<!-- Documentation (if you have docs) -->

A modern, extensible Python library for computational astrology

Built on Swiss Ephemeris for NASA-grade astronomical accuracy, Stellium brings professional astrological calculations to Python with a clean, composable architecture that works for everyone, from quick scripts to production applications.

Read the extensive documentation and API autodocs at Read The Docs.

Try out some quick examples immediately, no installation needed:

✨ Stellium The Webapp is live! Visit it here! ✨ It represents about 50-60% of the functionality of the full package, but is great for testing out the core capabilities and getting quick chart outputs.

Star the repo if you find it useful! ⭐

---

✨ Why Stellium?

For Python Developers

• Fully typed with modern type hints for excellent IDE support
• Protocol-driven architecture - extend with custom engines, no inheritance required
• Fluent builder pattern - chainable, readable, intuitive API
• Flexible input formats - accepts datetime strings, city names, or precise coordinates
• Modular & composable - mix and match components as needed
• Production-ready with comprehensive test coverage

For Astrologers

Western:

• Large-scale data analysis with pandas DataFrames, batch calculation, and statistical tools
• 23+ house systems including Placidus, Whole Sign, Koch, Equal, Regiomontanus, and more (see the full list).
• Multiple house systems in a single chart for comparison of traditions and meta-analysis
• Declination calculations with out-of-bounds planet detection and parallel/contraparallel aspects
• Bi-, tri- and quad-wheel charts for synastry, transits, progressions, returns, arc directions, and composite analysis
• Sect-aware calculations with proper day/night chart handling
• 25+ Arabic Parts with traditional formulas (see the full list)
• Essential & accidental dignity scoring for both traditional and modern rulerships
• Chart rulership and profections for traditional astrology
• Dispositor graphs for planets and (experimentally) houses in reports
• Aspect pattern detection - Grand Trines, T-Squares, Yods, Stelliums, and more
• Zodiacal Releasing for 25+ lots (including Fortune and Spirit) and optional "fractal" calculation mode
• Uranian astrology including Trans-Neptunian Planets and 45/90/360-degree dials with pointers.
• Primary and Zodiacal directions with 3D modeling and and distribution across bounds
• Draconic Charts and Void of Course Moon
• Transit timeline analysis - Calculate transit-to-natal aspect periods with orb entry/exit windows, retrograde multi-pass detection, plain-text list output, and SVG Gantt chart visualization
• Prompt-friendly text export - chart.to_prompt_text() generates clean markdown from any chart type, ready for LLM prompts. Handles single charts, synastry, composites, unknown-time charts, multiple house systems, and all components
• Electional astrology - Find auspicious times with 30+ predicates, interval optimization, and planetary hours
• Heliocentric positions
• Antiscia and contra-antiscia with a dedicated report section
• Beautiful visualizations with professional SVG chart rendering and 13 themes
• Beautiful Composable PDF or CLI reports to show nitty-gritty details of the chart (see this example for a subset of what's available)
• Notable births database for quick exploration and learning. Check out the current list

Vedic:

• Both tropical and sidereal zodiacs with 9 ayanamsa systems for Vedic astrology
• North Indian and South Indian chart rendering — traditional Vedic/Jyotish chart formats with 3 themes, 4 label styles, degree display, and full native info

Chinese:

• Ba Zi system with Ten Gods and Hidden Stems

Visual Chart Example

Synastry

Report Sample Pages

Vedic Charts (North Indian & South Indian)

Transit Timeline (Gantt Chart)

Graphic Ephemeris Example

What Makes Stellium Different

Unlike other Python astrology libraries, Stellium is designed for extensibility:

# Other libraries: rigid, hard-coded calculations
chart = AstrologyLibrary(date, location)  # That's all you can do

# Stellium: composable, configurable, extensible
chart = (ChartBuilder.from_details("2000-01-06 12:00", "Seattle, WA")
    .with_house_systems([PlacidusHouses(), WholeSignHouses()])  # Multiple systems!
    .with_sidereal("lahiri")                                    # Sidereal zodiac option
    .with_aspects(ModernAspectEngine())                         # Swap aspect engines
    .with_orbs(LuminariesOrbEngine())                          # Custom orb rules
    .add_component(ArabicPartsCalculator())                    # Plugin-style components
    .add_component(MidpointCalculator())                       # Stack as many as you want
    .calculate())                                              # Lazy evaluation

• Performance - Advanced caching system makes repeated calculations fast
• Flexibility - Calculate multiple house systems simultaneously
• Accuracy - Swiss Ephemeris provides planetary positions accurate to fractions of an arc-second
• Modern Python - Takes full advantage of Python 3.11+ features

---

Installation

pip install stellium

Requirements

• Python 3.11 or higher
• All dependencies installed automatically (pyswisseph, pytz, geopy, rich, svgwrite)

Optional Dependencies

# For data analysis with pandas DataFrames
pip install stellium[analysis]

---

Quick Start

Your First Chart (2 Lines of Code)

from stellium import ChartBuilder

chart = ChartBuilder.from_notable("Albert Einstein").calculate()
chart.draw("einstein.svg").save()

That's it! You now have a beautiful natal chart SVG for Einstein.

The from_notable() factory method uses our curated database of famous births. Other notables include: "Carl Jung", "Frida Kahlo", "Marie Curie", and more. Check out the current list.

Beautiful Visualizations, Zero Config

Want to customize your chart? The fluent .draw() API makes it effortless:

# Apply a preset for instant results
chart.draw("detailed.svg").preset_detailed().save()

# Choose a theme
chart.draw("midnight.svg").with_theme("midnight").save()

# Full customization
chart.draw("custom.svg") \
    .with_theme("celestial") \
    .with_zodiac_palette("rainbow_celestial") \
    .with_moon_phase(position="bottom-left", show_label=True) \
    .with_chart_info(position="top-left") \
    .save()

Discover features through autocomplete! Type chart.draw(). and your IDE will show you everything available.

📚 See the Visualization Guide for complete documentation, theme gallery, and examples.

Your Own Chart

from stellium import ChartBuilder

# Quick method: just pass datetime string and location
chart = ChartBuilder.from_details(
    "2000-01-06 12:00",  # ISO format, US format, or European format
    "Seattle, WA"        # City name or (lat, lon) tuple
).calculate()

# Access planetary positions
sun = chart.get_object("Sun")
print(sun)

moon = chart.get_object("Moon")
print(moon)
print(moon.phase)

Sun: 0°0' Libra (180°)
Moon: 0°0' Aries (0°)
Phase: Full (100% illuminated)

Key Features:

• Flexible datetime parsing: ISO 8601, US format, European format, or date-only
• Automatic geocoding: City name → coordinates
• Automatic timezone handling: Naive datetimes converted to UTC
• Smart defaults: Placidus houses, major (Ptolemaic) aspects, tropical zodiac

---

Progressive Examples

Level 1: Exploring Chart Data

from stellium import ChartBuilder

# Modern convenience method - accepts datetime strings!
chart = Char