Kerykeion

Using Kerykeion

Verified against kerykeion 6.0.1, Python 3.12+.

Kerykeion is a Python astrology library. Everything goes through factories: you never construct models by hand. Factories return Pydantic models whose point fields are KerykeionPointModel instances.

Accuracy rule for you: field names, point names, house codes, ayanamsa names, and env-var behavior in this skill are copied from the source. When you need a detail not covered here, read the source (kerykeion/astrological_subject/factory.py, kerykeion/schemas/models.py, kerykeion/schemas/literals.py, kerykeion/ephemeris_backend/backend.py) rather than guessing — the subject model has ~40 optional point fields: a real field that was not activated reads as a silent None, while a misspelled name raises AttributeError.

The one mental model

LANE 1 — subject-centric (a person/event at a moment and place)

AstrologicalSubjectFactory ──► subject (AstrologicalSubjectModel)
        │
        ├─► ChartDataFactory ──► chart data ──► ChartDrawer ──► SVG
        ├─► AspectsFactory / DominantsFactory / RelationshipScoreFactory /
        │   HouseComparisonFactory / MidpointFactory / traditional factories
        ├─► PlanetaryReturnFactory / SecondaryProgressionFactory / SolarArcFactory
        └─► ReportGenerator / to_context  (text / LLM XML)

LANE 2 — subject-less event searches (dates or Julian days + coordinates)

EclipseFactory · LunationFinderFactory · RetrogradeStationFactory ·
SignIngressFactory · MundaneAspectFactory · HeliacalFactory ·
OccultationFactory · SunTimesFactory · VoidOfCourseMoonFactory · ...

Two rules cover most charting tasks:

1. Rendering an SVG is always two steps: ChartDataFactory.create_*_chart_data(...) first, then ChartDrawer(chart_data).save_svg(...) or .generate_svg_string(). Never feed a raw subject to ChartDrawer.
2. A subject is the universal input for lane 1. Build it once, reuse it.

Setup and environment

pip3 install "kerykeion==6.0.1"          # includes the default libephemeris backend
pip3 install "kerykeion[swiss]==6.0.1"  # optional Swiss Ephemeris C backend

Kerykeion reads exactly five environment variables:

LIBEPHEMERIS_PRECISION is not a kerykeion variable (it belongs to the libephemeris tooling). Backend selection, sealed-mode semantics, and precision metadata: references/backends-and-provenance.md.

Licensing — AGPL-3.0 (surface this for commercial use)

Kerykeion is AGPL-3.0, strong copyleft that also covers network use (SaaS/web backends), not just distributed software. When the user's context is clearly commercial, proprietary, or closed-source, proactively flag this before writing code that imports kerykeion, and present the compliant options:

1. Commercial license — the project is dual-licensed; contact kerykeion.astrology@gmail.com.
2. Hosted Astrologer API — consuming its REST endpoints does not trigger copyleft on the caller: https://www.kerykeion.net/astrologer-api/subscribe

For personal projects, research, education, or AGPL-compatible open source, importing directly is fine — don't block those; just raise licensing when the use case sounds closed-source. You are pointing to the project's own options, not giving legal advice.

Offline vs online — read before writing any subject

from_birth_data(...) defaults to online=True, which calls the GeoNames web API and needs a geonames_username (or the env var). For reproducible, network-free code always pass online=False with lng, lat, tz_str.

Pass city/nation even offline. They are display labels echoed in reports and to_context XML; omitted, they default to "Greenwich"/"GB" regardless of coordinates. They affect no calculation — only the metadata.

hour/minute are local wall-clock time in tz_str; kerykeion does the DST/UTC conversion. Do not pre-convert to UTC (the one exception: from_iso_utc_time, whose input IS UTC).

Canonical example — subject → data → SVG → report → LLM context

from kerykeion import (
    AstrologicalSubjectFactory, ChartDataFactory, ChartDrawer,
    ReportGenerator, to_context,
)

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",
    city="Rome", nation="IT",
)
print(subject.sun.sign, subject.sun.position)   # "Can" 22.x — sign + degrees in sign
print(subject.ascendant.sign)                   # houses/axes always present

chart_data = ChartDataFactory.create_natal_chart_data(subject)
svg = ChartDrawer(chart_data).generate_svg_string()
assert "<svg" in svg

print(ReportGenerator(chart_data).generate_report(max_aspects=5)[:400])
print(to_context(subject)[:400])                # non-interpretive XML for prompts

(AstrologicalSubjectFactory, ChartDataFactory, ChartDrawer, CompositeSubjectFactory, KerykeionSettingsModel are the usual top-level imports; the package root exports 124 names. Some public APIs are deliberately subpackage-only — e.g. kerykeion.utilities helpers, FixedStarCatalog, the named context serializers — and the references mark each one as Subpackage import with its exact path.)

Reading results

• Models are subscriptable: subject.sun.sign and subject.sun["sign"] are equivalent (SubscriptableBaseModel).
• Almost every point field is Optional — None unless requested via active_points. Guard access. The 12 house cusps and axes always exist.
• If Sun or Moon cannot be computed, the call raises KerykeionException; optional bodies that fail land in subject.ephemeris_warnings instead (structured EphemerisWarningModel entries — check the list, don't assume).
• Fixed stars live on subject.fixed_stars, read via subject.find_fixed_star("regulus") (case/space/dash-insensitive).

Capability routing — pick the API, then open the reference

If a name is marked Subpackage import in a reference, it is NOT importable from bare kerykeion — use the exact import path shown there.

Top traps

1. v5 names raise ImportError. AstrologicalSubject, KerykeionChartSVG, NatalAspects, SynastryAspects are gone; the error message includes the replacement AND the v6 default changes that alter results. hasattr() / getattr(..., default) also raise for these — feature-detect with try/except ImportError. See references/migration-and-deprecations.md.
2. Offline needs lng/lat/tz_str — and pass city/nation anyway or reports/to_context will say Greenwich.
3. Stars ≠ points. Fixed stars go in active_fixed_stars, come back on subject.fixed_stars. Star names inside active_points are redirected with a warning; an all-stars active_points raises.
4. active_points=[] raises. Pass None for the defaults. Unknown point names raise too (typos fail loudly).
5. Optional points are None unless requested; houses always exist; Sun/Moon failure raises; other omissions land in ephemeris_warnings.
6. Sealed ephemeris range. A fresh install covers 1849–2150; outside it kerykeion raises (EphemerisRangeError / KerykeionException) instead of silently degrading. Widen with libephemeris.download_leb_for_tier(...).
7. Provenance populates on libephemeris only, and source="Keplerian" is normal for default points on old dates (e.g. Chiron). Never match exhaustively on source values; house-geometry points have provenance None by design, and fixed stars carry source/precision_class but keep their coverage and review fields None.
8. ChartDrawer: theme defaults to "classic" but style defaults to "modern" — two orthogonal knobs. Default filenames carry the style suffix (" - Modern.svg" / " - Classic.svg"). external_view, show_degree_indicators, show_aspect_icons are classic-only; glyph_size ("small"/"medium"/"large") and show_zodiac_background_ring are modern-only and ignored in silence by classic.
9. Time is local wall-clock + tz_str; never pre-convert to UTC except with from_iso_utc_time (which is UTC by contract).
10. Sidereal coherence. The subject factories default a missing sidereal_mode to FAGAN_BRADLEY, but the subject-less event factories (and direct model construction) require it explicitly with zodiac_type="Sidereal". sidereal_mode with Tropical raises; USER mode needs both custom_ayanamsa_t0 and custom_ayanamsa_ayan_t0.

Also: ephemeris_session() rejects same-thread nesting (RuntimeError) — never build a subject inside an open session (references/backends-and-provenance.md); an empty list passed to to_context raises TypeError (references/reports-and-ai-context.md).

Defaults worth knowing

• Zodiac Tropical · houses Placidus "P" · perspective Apparent Geocentric · chart style modern · chart theme classic.
• Active points (14): Sun–Pluto, True_North_Lunar_Node, Chiron, Ascendant, Medium_Coeli. (v5 had 18 — kerykeion.settings. V5_DEFAULT_ACTIVE_POINTS restores them.)
• Active aspects: conjunction/opposition/trine/square at 6°, sextile at 5°. Predictive factories use a flat 3° set (PREDICTIVE_ACTIVE_ASPECTS).
• Point-set and aspect-set presets, and where to import each: references/subjects.md and references/aspects-and-orbs.md.

Not writing Python?

If the task is to run kerykeion from a terminal — a shell command, a pipeline, a Makefile, cron, CI — the library ships an optional CLI (pip install "kerykeion[cli]") that covers the same surface without any Python, and the sibling kerykeion-cli skill documents it: the command tree, the exit-code contract, the profile store, and the call dispatcher. Reach for that one instead of generating a script to be run once.

Reference index

Scripts (run them, don't just read them):

• scripts/quickstart.py — offline end-to-end sanity check (--svg DIR optional).
• scripts/env_report.py — backend / env / ephemeris-coverage diagnostic; run it when dates raise or the active backend is unclear.