Kerykeion

Kerykeion is a comprehensive Python astrology library for calculations and SVG chart generation. It supports most major astrological traditions and techniques, from modern Western and traditional astrology to Vedic, Uranian, predictive, locational, and mundane work.

It is highly configurable, with sensible defaults optimized for modern astrology. Results are typed, serializable, and ready for Python applications, APIs, LLMs, and AI agents.

Hosted API

Building a commercial, SaaS, or closed-source product? Use the hosted Astrologer API on RapidAPI. Your app calls Kerykeion as an external service, with no Python or ephemeris infrastructure and no AGPL library in your codebase.

Get JSON calculations, ready-to-display SVG charts, and AI-ready context endpoints. A dedicated Astrologer API Agent Skill gives AI coding agents the authentication pattern, endpoint routing, schemas, and integration examples they need to build with the service.

Get Started on RapidAPI  ·  Full API Documentation  ·  AI Agent Skill

Subscriptions directly support Kerykeion's continued development.

Chart Styles and Themes

Kerykeion includes two complete SVG chart styles, Modern and Classic, and three built-in themes. Every combination below is generated by the library:

	Classic theme	Dark theme	Black & white
Modern style
Classic style

Choose a style with style="modern" or style="classic", and a theme with theme="classic", theme="dark", or theme="black-and-white". See Chart Rendering, Modern Charts, and Theming.

Table of Contents

• Hosted API
• Chart Styles and Themes
• Installation
• Quick Start
• How Kerykeion Is Organized
• Feature Overview
  • Subjects and Chart Types
  • Zodiacs, Houses, Perspectives, and Points
  • Aspects and Chart Analysis
  • Predictive and Locational Techniques
  • Sky Events and Time Calculations
  • Traditional Techniques
  • Rendering, Data, Reports, and AI
• Core Workflows
  • Build and Inspect a Subject
  • Generate an SVG Chart
  • Synastry and Transits
  • Solar and Lunar Returns
  • Composite and Davison Charts
  • Aspects and Chart Analysis
  • Reports and AI Context
• Calculation Configuration
  • Active Points
  • Fixed Stars
  • Sidereal Modes and Custom Ayanamsa
  • House Systems and Polar Latitudes
  • Observer Perspectives
  • Timezones, LMT, and Calendars
  • Precision, Coverage, and Provenance
• Chart Rendering
• Command-Line Interface
• Documentation
• Swiss Ephemeris Backend
• AI Agent Skill
• Development
• License and Commercial Use
• Astrologer Studio
• Contributing and Citation

Installation

Kerykeion requires Python 3.12 or newer.

This branch documents 6.0.0rc1, the first v6 release candidate. Select the prerelease explicitly:

# Library only
pip install --upgrade "kerykeion==6.0.0rc1"

# Library plus the command-line interface
pip install --upgrade --pre "kerykeion[cli]==6.0.0rc1"

# Library, CLI, and optional Swiss Ephemeris backend
pip install --upgrade --pre "kerykeion[all]==6.0.0rc1"

An unqualified pip install kerykeion selects the latest stable release. Before upgrading from v4 or v5, read the v6 release notes and the migration guide.

A plain library installation intentionally provides no shell command. The kerykeion command belongs to the separate kerykeion-cli distribution, installed by the cli extra.

Supported date ranges

The default reviewed ephemeris tier uses JPL DE440s and covers 1850–2150. The upper bound is exclusive. Dates outside the active kernel raise KerykeionException rather than silently changing source.

Install a wider reviewed core through libephemeris:

# doc-snippet: no-run - downloads ephemeris kernels
import libephemeris

libephemeris.download_leb_for_tier("medium")    # 1550–2650
libephemeris.download_leb_for_tier("extended")  # DE441, including BCE dates

The core tier controls the date range of the core bodies. Asteroids, exotics, and lunar apsides use separate data groups or runtime models and can have different coverage. See Ephemeris Backend and Backend Precision Comparison.

Quick Start

This offline example creates a subject, derives chart data, and saves a natal SVG:

from pathlib import Path

from kerykeion import AstrologicalSubjectFactory, ChartDataFactory, ChartDrawer

subject = AstrologicalSubjectFactory.from_birth_data(
    name="Example Person",
    year=1990,
    month=7,
    day=15,
    hour=10,
    minute=30,
    lng=12.4964,
    lat=41.9028,
    tz_str="Europe/Rome",
    online=False,
)

chart_data = ChartDataFactory.create_natal_chart_data(subject)
drawer = ChartDrawer(chart_data)

output_dir = Path("charts_output")
output_dir.mkdir(exist_ok=True)
drawer.save_svg(output_path=output_dir, filename="example-natal")

print(subject.sun.sign, subject.sun.position)
print((output_dir / "example-natal.svg").resolve())

The recommended offline contract is explicit: set online=False and provide longitude, latitude, and an IANA timezone. For automatic location lookup, set online=True, provide city and nation, and configure a GeoNames username through geonames_username or KERYKEION_GEONAMES_USERNAME.

• Getting Started
• Birth Data
• Astrological Subject Factory
• Birth Chart Example

How Kerykeion Is Organized

Kerykeion separates calculations from presentation:

Birth/event data
      |
      v
AstrologicalSubjectFactory  ->  AstrologicalSubjectModel
      |
      v
ChartDataFactory            ->  ChartDataModel
      |
      +--> ChartDrawer       ->  SVG
      +--> ReportGenerator   ->  text
      +--> to_context        ->  XML for LLMs
      +--> model_dump_json   ->  JSON

• AstrologicalSubjectFactory computes the sky, houses, points, configuration, and provenance through from_birth_data(), from_iso_utc_time(), or from_current_time().
• ChartDataFactory adds aspects, distributions, angularities, stelliums, relationship scores, and house comparisons where appropriate.
• ChartDrawer only renders already-computed chart data.
• Every public result is a Pydantic model with attribute access, dictionary-style compatibility, and JSON serialization.

This design lets applications use the calculations without SVG, replace the presentation layer, or send structured results directly to another service.

Feature Overview

Every public calculation factory is named below. Features that share a factory or are configured as point families, rendering options, or output formats are listed separately so the README remains a complete map of the library.

Subjects and Chart Types

Zodiacs, Houses, Perspectives, and Points

Aspects and Chart Analysis

Predictive and Locational Techniques

Secondary-progressed houses follow the Q2 / daily houses convention: they are the real angles at the progressed ephemeris instant, not solar-arc-directed angles. Planetary progressions are unaffected by this choice. See Secondary Progressions.

Sky Events and Time Calculations

Sunrise and subject.is_diurnal intentionally answer different questions. Sunrise uses the apparent upper limb and standard refraction; diurnality uses the Sun's geometric center against the true horizon. See Sun Times.

Traditional Techniques

Rendering, Data, Reports, and AI

Core Workflows

Build and Inspect a Subject

from kerykeion import AstrologicalSubjectFactory

john = AstrologicalSubjectFactory.from_birth_data(
    "John Lennon",
    1940,
    10,
    9,
    18,
    30,
    lng=-2.9833,
    lat=53.4,
    tz_str="Europe/London",
    online=False,
)

print(john.sun.sign, john.sun.position, john.sun.house)
print(john["moon"]["abs_pos"])
print(john.is_diurnal)
print(john.model_dump_json(indent=2))

Each KerykeionPointModel can carry sign, absolute and within-sign longitude, speed, retrograde state, motion state, house, declination, ecliptic latitude, source, precision class, and optional enrichment data. Fields that do not apply remain None rather than receiving fabricated values.

Generate an SVG Chart

from pathlib import Path

from kerykeion import ChartDataFactory, ChartDrawer

natal_data = ChartDataFactory.create_natal_chart_data(john)
natal_drawer = ChartDrawer(natal_data)

chart_dir = Path("charts_output")
chart_dir.mkdir(exist_ok=True)
natal_drawer.save_svg(
    output_path=chart_dir,
    filename="john-lennon-natal",
    style="modern",
)

Use generate_svg_string() when the SVG should stay in memory. Wheel-only and aspect-grid-only methods are available for custom layouts. See Charts.

Synastry and Transits

from kerykeion import AstrologicalSubjectFactory, ChartDataFactory

paul = AstrologicalSubjectFactory.from_birth_data(
    "Paul McCartney",
    1942,
    6,
    18,
    15,
    30,
    lng=-2.9833,
    lat=53.4,
    tz_str="Europe/London",
    online=False,
)

synastry_data = ChartDataFactory.create_synastry_chart_data(john, paul)
print(len(synastry_data.aspects))
print(synastry_data.relationship_score.score_value)

transit_data = ChartDataFactory.create_transit_chart_data(john, paul)
print(transit_data.chart_type)

A transit chart accepts any event subject as its moving side. For sampled transit timelines and refined exact events, use EphemerisDataFactory with TransitsTimeRangeFactory.

Solar and Lunar Returns

from kerykeion import ChartDataFactory, PlanetaryReturnFactory

return_factory = PlanetaryReturnFactory(
    john,
    lng=-2.9833,
    lat=53.4,
    tz_str="Europe/London",
    online=False,
)
solar_return = return_factory.next_return_from_date(
    2026,
    1,
    1,
    return_type="Solar",
)

single_return_data = ChartDataFactory.create_single_wheel_return_chart_data(solar_return)
dual_return_data = ChartDataFactory.create_return_chart_data(john, solar_return)

print(solar_return.iso_formatted_utc_datetime)
print(single_return_data.chart_type, dual_return_data.chart_type)

Return instants are reported to the whole second. Feeding a reported instant back to the ISO entry point advances to the following return; backwards=True finds the preceding one. Topocentric returns use the requested return location and altitude consistently for both the crossing search and the returned chart.

Composite and Davison Charts

from kerykeion import CompositeSubjectFactory

composite_factory = CompositeSubjectFactory(john, paul, house_anchor="auto")
midpoint_composite = composite_factory.get_midpoint_composite_subject_model()
davison_composite = composite_factory.get_davison_composite_subject_model()

print(midpoint_composite.house_frame)
print(davison_composite.sun.abs_pos)

The midpoint composite is a symbolic midpoint model. The Davison result is a real ephemeris chart cast at the pair's midpoint time and place. See Composite Subject Factory.

Aspects and Chart Analysis

from kerykeion import AspectsFactory, ChartDataFactory

aspect_result = AspectsFactory.single_chart_aspects(
    john,
    point_orb_adjustments={"Sun": 1.5, "Moon": 1.5},
)
analysis = ChartDataFactory.create_natal_chart_data(
    john,
    distribution_method="weighted",
)

for aspect in aspect_result.aspects[:5]:
    print(aspect.p1_name, aspect.aspect, aspect.p2_name, aspect.orbit)

print(analysis.element_distribution)
print(analysis.angularities[:2])
print(analysis.stelliums)

Use single_chart_declination_aspects() or dual_chart_declination_aspects() for parallels and contra-parallels. See Aspects.

Reports and AI Context

from kerykeion import ReportGenerator, to_context

report = ReportGenerator(natal_data).generate_report(max_aspects=10)
xml_context = to_context(natal_data)

print(report[:500])
print(xml_context[:500])

ReportGenerator creates human-readable text. to_context() creates neutral XML intended as factual input to an LLM; it does not generate an astrological interpretation. See Reports and Context Serializer.

Calculation Configuration

Active Points

active_points is a calculation choice, not only a drawing filter. Request optional points when the subject is created. ChartDataFactory can filter points that already exist, but it does not go back and calculate omitted bodies.

This example correctly includes both Mean and True lunar nodes and their opposites:

from kerykeion import AstrologicalSubjectFactory, ChartDataFactory
from kerykeion.settings.config_constants import DEFAULT_ACTIVE_POINTS

requested_nodes = [
    "Mean_North_Lunar_Node",
    "Mean_South_Lunar_Node",
    "True_North_Lunar_Node",
    "True_South_Lunar_Node",
]
all_requested_points = list(dict.fromkeys([*DEFAULT_ACTIVE_POINTS, *requested_nodes]))

node_subject = AstrologicalSubjectFactory.from_birth_data(
    "Node Example",
    1990,
    7,
    15,
    10,
    30,
    lng=12.4964,
    lat=41.9028,
    tz_str="Europe/Rome",
    online=False,
    active_points=all_requested_points,
)
node_data = ChartDataFactory.create_natal_chart_data(node_subject)

assert node_subject.mean_north_lunar_node is not None
assert node_subject.mean_south_lunar_node is not None
assert set(requested_nodes) <= set(node_data.active_points)

Presets for core, all, Uranian, and other point groups are documented in Active Points and Active Points Examples.

Fixed Stars

Fixed stars use a separate open-name channel because they come from a catalog rather than the closed chart-point vocabulary:

from kerykeion import AstrologicalSubjectFactory, ChartDataFactory

star_subject = AstrologicalSubjectFactory.from_birth_data(
    "Star Example",
    1990,
    7,
    15,
    10,
    30,
    lng=12.4964,
    lat=41.9028,
    tz_str="Europe/Rome",
    online=False,
    active_fixed_stars=["Sirius", "Regulus", "Aldebaran", "Antares", "Fomalhaut"],
)

sirius = star_subject.find_fixed_star("Sirius")
assert sirius is not None
print(sirius.abs_pos, sirius.declination, sirius.magnitude)

star_chart_data = ChartDataFactory.create_natal_chart_data(star_subject)

Requested stars participate automatically in chart rendering and aspects. Discover catalog names through FixedStarCatalog or FixedStarDiscoveryFactory. See Fixed Star Discovery.

Sidereal Modes and Custom Ayanamsa

from kerykeion import AstrologicalSubjectFactory

sidereal_subject = AstrologicalSubjectFactory.from_birth_data(
    "Sidereal Example",
    1990,
    7,
    15,
    10,
    30,
    lng=12.4964,
    lat=41.9028,
    tz_str="Europe/Rome",
    online=False,
    zodiac_type="Sidereal",
    sidereal_mode="LAHIRI",
)
print(sidereal_subject.ayanamsa_value)

For a custom ayanamsa, use sidereal_mode="USER" and provide both custom_ayanamsa_t0 and custom_ayanamsa_ayan_t0. Nakshatras on a tropical chart use nakshatra_ayanamsa="LAHIRI" by default for the lunar-mansion division only; the chart's tropical longitudes remain unchanged.

See Sidereal Modes and Schemas.

House Systems and Polar Latitudes

Pass a one-character houses_system_identifier; Placidus ("P") is the default. See House Systems for the supported list.

Some quadrant systems are mathematically undefined inside the polar circle. Kerykeion records any substitution in subject.polar_house_fallbacks; houses_system_identifier remains what was requested and effective_houses_system_identifier states what produced the cusps. Systems that legitimately place several cusps at one longitude expose those zero-width groups through coincident_house_cusps.

ChartDrawer(..., show_polar_fallback_note=True) can print the substitution on the chart.

Observer Perspectives

The default is "Apparent Geocentric". Available alternatives include "True Geocentric", "Topocentric", "Heliocentric", "Barycentric", "Selenocentric", and supported planetocentric frames.

Frame-specific rules matter:

• a center body has no position as seen from itself and is excluded;
• lunar nodes and lunar apogee variants are geocentric-only;
• Local Space, Gauquelin sectors, and OOB classification are only populated in frames where they are meaningful;
• two-chart operations require compatible frames;
• a Topocentric subject cannot be relocated by keeping its original planetary positions, because their parallax belongs to the original observer.

See Perspective Types.

Timezones, LMT, and Calendars

• Use an IANA zone such as Europe/Rome; a modern fixed UTC offset cannot reproduce historical or DST rules.
• If a modern wall time is repeated or skipped by a transition, is_dst=True selects the larger UTC offset and is_dst=False the smaller one. Leaving it unset raises instead of guessing.
• Before a zone has a recorded civil clock, a synthetic IANA LMT record is replaced by Local Mean Time at the supplied longitude. Named historical records such as RMT, BMT, KMT, and MMT remain authoritative.
• Naive daily EphemerisDataFactory inputs advance by local calendar days. Hourly and minutely series advance uniformly in UTC.
• CE birth-data components use the proleptic Gregorian calendar. BCE birth input uses astronomical year numbering (0 = 1 BCE) and the Julian-calendar birth path.
• ISO event timestamps use the proleptic Gregorian calendar required by ISO 8601.

See Astrological Subject Factory, Ephemeris Data, and Utilities.

Precision, Coverage, and Provenance

High precision depends on body, date, active data tier, and source. A successful chart can contain points from different producers; applications should inspect the public metadata instead of assuming every optional body came from the core JPL kernel:

• subject.ephemeris_warnings lists optional points that no permitted source could produce;
• point.source identifies sources such as LEB, Derived, Analytical, or Keplerian;
• point.precision_class states the backend's classification;
• point.ephemeris_coverage_start_jd and point.ephemeris_coverage_end_jd expose the applicable window;
• point.source_reviewed reports whether that coverage record is reviewed.

source="Keplerian" is an approximation and is not ephemeris-grade. Geometrically derived points say source="Derived". Uranian points are runtime analytical models and say source="Analytical"; they are not LEB data.

Sun or Moon calculation failure raises because a subject without either luminary is not a usable chart. Optional-body failures can return a valid subject with a machine-readable warning. See Backend Precision Comparison.

Chart Rendering

The modern concentric-ring renderer is the default; the classic wheel remains fully supported. All chart types can use the three built-in themes-"classic", "dark", and "black-and-white"-or theme=None for unthemed CSS variables.

from pathlib import Path

from kerykeion import ChartDrawer

styled_drawer = ChartDrawer(
    natal_data,
    theme="dark",
    chart_language="IT",
    glyph_size="large",
    show_motion_state=True,
    show_out_of_bounds=True,
    show_aspect_movement=True,
)
styled_drawer.save_svg(
    output_path=Path("charts_output"),
    filename="john-dark-marked",
    minify=True,
)

The complete visual comparison is shown in Chart Styles and Themes near the top of this README.

Output controls

Optional marks-show_motion_state, show_out_of_bounds, show_aspect_movement, show_relationship_score, show_ayanamsa_value, and show_polar_fallback_note-default to False. A mark is silent when its source data has no applicable value.

See Charts, Theming, Chart Language, Glyph Sizes, Chart Marks, and Minimalist Charts.

Command-Line Interface

The CLI is a separate distribution, kerykeion-cli. It uses only the Python standard library beyond Kerykeion itself.

pip install --pre "kerykeion[cli]==6.0.0rc1"
# Or install it as an isolated tool:
uv tool install --prerelease=allow "kerykeion-cli==6.0.0rc1"

Save a subject profile and reuse it:

$ kerykeion subject save john --name "John Lennon" --date 1940-10-09 --time 18:30 \
      --lat 53.4 --lng -2.9833 --tz Europe/London --offline
$ kerykeion natal -s john
$ kerykeion natal -s john -f svg -o /tmp/john.svg --theme dark

A terminal defaults to a text report. A pipeline defaults to JSON:

$ kerykeion natal -s john | jq -r .sun.sign
Lib

The command tree covers charts, aspects, dominants, Moon context, relationship scores, predictive and traditional techniques, astronomical events, ephemeris data, transit timelines, stored subject profiles, and a guarded dispatcher for public factories:

$ kerykeion call ProfectionsFactory.from_subject -s john -f json
$ kerykeion call --list
$ kerykeion info literals SiderealMode
$ kerykeion status --check

call dispatches only to names exported by kerykeion.__all__; arbitrary Python names are refused. See the complete CLI reference.

The CLI wheel also ships a Unix man page, kerykeion(1), generated from the same command tree behind --help: after a pip install into a system prefix (/usr/local, Homebrew), man kerykeion works with no further step. Isolated installs (uv tool, a venv) keep the page inside their own prefix; point MANPATH at it once, e.g. man -M "$(uv tool dir)/kerykeion-cli/share/man" kerykeion.

For a commercial product that should not install Python, manage ephemeris data, or import the AGPL library, use the hosted Astrologer API instead.

Documentation

• Getting Started: kerykeion.net/content/docs
• Examples Gallery: kerykeion.net/content/examples
• Python API Reference: kerykeion.net/pydocs
• Migration Guide: v4/v5 to v6
• Cookbook: Practical recipes
• Schemas: Models and literals
• FAQ: Troubleshooting and conventions
• Hosted API: Full API Documentation

Swiss Ephemeris Backend

Kerykeion uses libephemeris 3.2.1 by default. To use the optional Swiss Ephemeris backend:

pip install --pre "kerykeion[swiss]==6.0.0rc1"
python -m kerykeion.swisseph_setup
export KERYKEION_BACKEND=swisseph
export KERYKEION_EPHE_PATH=~/.kerykeion/sweph

Swiss Ephemeris needs its .se1 data files for full precision and sefstars.txt for fixed-star features. Without complete files, body and date availability can be narrower. See Swiss Ephemeris Configuration.

Backend selection happens once at import. KERYKEION_BACKEND selects the engine, KERYKEION_LEB_MODE controls the libephemeris calculation mode, and LIBEPHEMERIS_PRECISION selects the active data tier. See Ephemeris Backend.

AI Agent Skill

Kerykeion includes a cross-platform Agent Skill that teaches coding agents the real v6 factories, models, configuration, and examples. During the v6 prerelease cycle, copy it from the current v6 branch:

git clone --branch v6 --depth 1 https://github.com/g-battaglia/kerykeion.git
cd kerykeion

# Claude Code
cp -r skills/kerykeion /path/to/project/.claude/skills/kerykeion

# Codex
cp -r skills/kerykeion /path/to/project/.agents/skills/kerykeion

# Generic agentskills.io layout
cp -r skills/kerykeion /path/to/project/skills/kerykeion

Once v6 is the default branch, skills-aware tools can install it with:

npx skills add g-battaglia/kerykeion

The library wheel also includes kerykeion/llms.txt, a self-contained API guide. For runtime chart context, use to_context().

Development

Kerykeion uses uv, pytest, Ruff, MyPy, Pyright, and poethepoet. All project gates run locally; the repository intentionally has no GitHub Actions workflows.

git clone --branch v6 https://github.com/g-battaglia/kerykeion.git
cd kerykeion
uv sync --dev

uv run poe test:core
uv run poe check
uv run poe docs:check
uv run poe docs:snippets
uv run poe build:smoke

Test tiers correspond to installed ephemeris coverage. To run the full-range suite, install the extended kernel and select it explicitly:

LIBEPHEMERIS_PRECISION=extended uv run poe test:extended

• Development Guide
• Test Guide
• Contributing Guide
• Changelog

License and Commercial Use

Kerykeion and the default libephemeris backend are distributed under AGPL-3.0. If your software imports or operates the library, review the AGPL's requirements for distribution and network use. See LICENSE and LICENSING.md.

For commercial applications, SaaS products, mobile apps, or closed-source codebases, the recommended route is the hosted Astrologer API:

• Subscribe on RapidAPI
• Read the Full API Documentation

Your product calls an external service rather than importing Kerykeion directly. Subscription revenue directly funds the maintenance and continued development of this repository.

A direct commercial license for embedding Kerykeion can also be discussed with the copyright holder. The intended model is described in COMMERCIAL-LICENSE.md; that document is currently marked as a draft. Contact kerykeion.astrology@gmail.com.

This section is a practical project summary, not legal advice. Consult qualified counsel for your specific use case.

Astrologer Studio

Astrologer Studio is a cloud astrology application powered by Kerykeion and the hosted Astrologer API. It brings professional astrological calculations and chart generation into a ready-to-use online workspace-without requiring a local Python installation or ephemeris setup.

Open Astrologer Studio

Contributing and Citation

Contributions are welcome. Open an issue or discussion before substantial work and follow the local gates in CONTRIBUTING.md. Contributions are accepted under the copyright-assignment terms documented there; authorship remains visible in project history and release notes.

For academic or published work, cite:

Battaglia, G. (2025). Kerykeion: A Python Library for Astrological Calculations and Chart Generation.
https://github.com/g-battaglia/kerykeion

Questions and integration requests: kerykeion.astrology@gmail.com.