Kerykeion: astrological calculation as a typed data pipeline

Charts are the output, but the data model is the product

Kerykeion describes itself as a Python library for astrological calculations and SVG charts, and it calculates planetary positions, houses, aspects, returns, progressions and other techniques listed in a feature overview.

The interesting part is the order of that sentence. Many charting libraries treat the drawing as the deliverable and the numbers as an implementation detail. Kerykeion treats the numbers as the deliverable. Results are Pydantic models that you can inspect in Python, export as JSON, or serialize as XML for LLM context. The SVG is one consumer of that model rather than the only one.

That choice is what makes the library interesting to a programmer rather than only to an astrologer. If you want a chart as a picture, this is heavier than you need. If you want to compute a chart, feed the fields into a report, store them in a database, compare thousands of subjects, or hand them to a model as context, then a typed, serialisable result is the thing you actually needed, and the drawing is incidental.

The audience is therefore developers building astrology products: report generators, comparison tools, chatbots, scheduling features, or research pipelines over birth data. The homepage is kerykeion.net and the documentation for the current major version lives under its python-library docs path.

The defaults decide every answer, so read them first

The README states the defaults in one sentence, and it is the sentence to memorise before using the library: tropical zodiac, Placidus houses, and apparent geocentric positions.

Each of those three choices changes the output. The zodiac decides the sign boundaries, the house system decides where the twelve houses begin, and apparent versus true position decides whether light-time and aberration corrections are applied to the computed coordinates. Two practitioners can disagree about a chart because of exactly these settings, and a library that silently picked one would make that disagreement invisible.

Kerykeion does not stop at the defaults. The table of contents lists a configuration section covering zodiacs, houses, perspectives and points, and another for active points, which is the mechanism for choosing which bodies the chart includes. The feature overview also lists separate sections for subjects and chart types, aspects and chart analysis, predictive and locational techniques, sky events and time calculations, and traditional techniques.

That breadth is the second thing to understand. The v6 feature set is not limited to natal charts: the workflow section covers synastry and transits, solar and lunar returns, composite and Davison charts, plus reports and AI context. The examples directory at the repository root makes the same point concretely, with files for aspects and synastry, composite reports, context serialization, current time reports, dignities and nakshatra motion, dual return reports, eclipses, Firdaria, glyph size, horary, house comparison, midpoints, mutual receptions, natal reports, planetary return, primary directions, profections, quickstart natal chart, relocated and ACG, retrograde periods and secondary progressions.

That directory listing is the most useful single piece of documentation in the repository, because it maps the feature surface to runnable programs.

Two chart styles, three themes, selected by string

Rendering is deliberately narrow in scope. Kerykeion has two SVG chart styles, Modern and Classic, and three built-in themes: classic, dark and black-and-white. The README shows a preview grid with the two styles crossed with the three themes, each preview linking to a full-size PNG.

The selection is by keyword argument, with style="modern" or style="classic" and theme="classic", theme="dark" or theme="black-and-white". The documentation covers chart rendering, modern chart examples and theming in separate pages under the v6 documentation path.

Two things follow from this design. The first is that the chart appearance is a parameter of the calculation, not a separate rendering pipeline, which means a caller can produce the same subject twice with different styling and get consistent geometry. The second is that the theme system is fixed at three options in the built-in set. If your product needs a house-specific palette, an arbitrary typeface or a layout that matches an existing brand, the SVG is an intermediate artefact to post-process rather than a finished page, and the README does not describe a custom theme API, only the three built-ins.

There is also a CLI directory at the repository root, so the library also has a command line surface, and the scripts/ directory suggests repository maintenance tasks are scripted as well.

Serialising for a model context, not only for a person

The XML serialisation for LLM context is the feature that distinguishes this from a chart drawing library, and the repository is built around it.

The reasoning is straightforward once stated. A language model cannot read an SVG chart, but it can read a structured description of one: which bodies sit in which houses and signs, which aspects are tight, what the returned Saturn means for the date in question. Kerykeion's models serialise to JSON and to XML, and the examples directory includes dedicated files for context serialization, house comparison context, and reports.

The examples list also shows how wide the report surface is: natal report, composite report, current time report, dual return report, moon phase report, and a moon phase JSON example. That mix suggests the intended downstream use is text generation from chart data, not charting for its own sake.

The project supports that direction with tooling aimed at coding agents. The README mentions an Astrologer API Agent Skill provided for development with coding agents, hosted in a separate repository, and the repository itself contains a skills/ directory at the top level alongside the cli/ and site/ directories.

The commercial arrangement follows the same logic. For commercial closed source projects, including SaaS products and mobile apps, the maintainer offers a hosted API, distributed through RapidAPI, with subscriptions stated to support the development of the library. The open source project is therefore the free tier of a two tier distribution.

Python 3.12 and above, with the backend pinned

The packaging metadata is explicit and modern. The project name is kerykeion, the version in the pyproject.toml is 6.0.5, the author is listed as Giacomo Battaglia, and the description calls it a Python library for astrological calculations including natal charts, houses, planetary aspects and SVG chart generation.

[project]
name = "kerykeion"
version = "6.0.5"
requires-python = ">=3.12"

The classifiers confirm the supported range, listing Python 3.12, 3.13 and 3.14, and the package is marked as typed, operating system independent and Python 3 only. The dependency list carries a comment block that is unusual and revealing: it says to keep the exact backend version verified for v6, that golden fixtures and source and coverage contracts are verified against that release, that the dependency pin gives PyPI installs the same backend as the lockfile, and that a backend upgrade requires rechecking those fixtures.

In plain terms, the underlying astronomical backend is pinned because the test suite compares against golden outputs. That is a good sign for reproducibility and a constraint for maintenance: upgrading the backend is a deliberate act with revalidation attached, not a routine dependency bump.

The repository carries a uv.lock for reproducible installs, a pyrightconfig.json for type checking, a pyproject.toml, a cli/ directory, a site/ directory for the documentation site, a docs/ directory, a CHANGELOG.md, release_notes/, a NOTICE file, an AUTHORS file, a TEST.md and a DEVELOPMENT.md, and a .clabot configuration for the CLA bot.

AGPL-3.0 is the decision that shapes the adoption

The licence is AGPL-3.0, stated in the pyproject.toml, in the classifier list and in the README badge. For a library whose output is data rather than a running service, that is a significant choice, and the project is explicit about the consequence: for commercial closed source projects, including SaaS products and mobile apps, the maintainer offers a hosted API instead.

The repository makes the licensing structure legible rather than hiding it. There is a LICENSE file, a separate COMMERCIAL-LICENSE.md, a LICENSING.md, a NOTICE file, and a licenses/ directory, so the terms for the open source path and for the commercial path are both present in the tree. The AGPL terms reach networked use, which is why a service that exposes the library over an API is a different situation from a local tool, and the hosted API on RapidAPI is positioned as the path for that case.

Read COMMERCIAL-LICENSE.md and LICENSING.md before deciding, since the exact obligations for your distribution model are a question of facts about your product rather than something this review can answer. Nothing here is legal advice.

The version history also bears on adoption risk. The recent releases are v6.0.5 from 2026-10-05, v6.0.0 from 2026-09-29, and a v6.0.0 alpha from 2026-06-05 that was labelled for retrograde stations and sign ingresses. A v6 major line that has already had at least one point release within a week of the major tag is still settling, and the documentation lives under a v6 path, so expect the API to be in flux if you adopt it now.

An astrological domain library versus general astronomy code

The alternative to Kerykeion is to compute planetary positions yourself with a general purpose astronomy library and implement the astrological layer yourself: house division, aspect calculation with orbs, dignities, return dates, progressions, and the chart layout.

The difference in approach is the size of the domain you take on. A general astronomy library gives you coordinates and ephemeris data, and stops there. Everything an astrologer actually reads from a chart is the layer above it, and that layer is where most of the work sits, because it is where the conventions live. House systems disagree, aspect orbs are a matter of school, and a return is defined by a specific rule about when a body reaches its previous longitude. Kerykeion encodes those choices, with a table of contents that names them: subjects and chart types, zodiacs, houses, perspectives and points, aspects and chart analysis, predictive and locational techniques, sky events and time calculations, traditional techniques.

What you gain is a domain model, a rendering path and a serialisation format, plus the fixed defaults that make results reproducible between runs. What you give up is control over the conventions themselves, and the AGPL terms if you ship it closed.

The pragmatic middle path is what the examples directory implies: use the library to produce the chart data, then apply your own house system, orbs and output format on top of the Pydantic models. The models are inspectable, so overriding a convention is a data operation rather than a rewrite.

Editorial conclusion

Adopt Kerykeion when you need astrological calculations as structured data rather than pictures, so that chart results can be serialised into JSON or XML and handed to another program, including a language model context. Do not adopt it for a closed source commercial product without reading COMMERCIAL-LICENSE.md and LICENSING.md first, since the project is AGPL-3.0 and the maintainer points commercial users to a hosted API, and do not expect a specific house system or zodiac without configuring it, because the defaults are tropical with Placidus houses. Verify first by running one of the files in the examples/ directory and checking the returned model in Python, then confirm the licence terms that apply to your distribution.

Frequently asked questions

Official sources

1. g-battaglia/kerykeion on GitHub
2. License: AGPL-3.0
3. Project website
4. README
5. Releases