Types & Schemas #

This section documents the core data structures, Pydantic models, and type definitions used throughout the Kerykeion library to ensure type safety and data consistency.

Overview #

The kerykeion.schemas package contains all the data definitions:

• models: Pydantic models for astrological subjects, charts, and points.
• literals: String literals for strict type hinting (Zodiac signs, Planets, Houses, etc.).
• settings_models: Configuration models for library settings.
• chart_template_model: Models for SVG chart generation.
• exceptions: Standard exception class for the library.

Subscriptable Models #

All Kerykeion models inherit from SubscriptableBaseModel, allowing dictionary-like access to fields in addition to dot notation.

subject = AstrologicalSubjectFactory.from_birth_data(
    "Alice", 1990, 6, 15, 12, 0,
    lng=-0.1276, lat=51.5074, tz_str="Europe/London", online=False
)
# Access as object
print(subject.name)
# Access as dict
print(subject["name"])

Core Models (models) #

Import from: kerykeion.schemas.models

AstrologicalSubjectModel #

Represents a person or event to be analyzed.

KerykeionPointModel #

Detailed information about a celestial body or house cusp.

Provenance fields. Every point records where its numbers came from:

Fixed-star discovery fields. Populated on the points returned by FixedStarDiscoveryFactory and left None everywhere else:

SingleChartDataModel #

The complete data structure for a calculated single chart (Natal, Return, etc.).

DualChartDataModel #

Data structure for comparing two charts (Synastry, Transits).

AngularityModel #

A classical planet conjunct one of the four chart angles.

StelliumModel #

A concentration of classical planets in one house.

AspectModel #

Represents an astrological aspect between two points.

CompositeSubjectModel #

Represents a composite chart derived from two subjects.

Inherits all celestial point fields from AstrologicalBaseModel.

PlanetReturnModel #

Represents a planetary return chart.

Inherits all celestial point fields from AstrologicalBaseModel.

AstrologicalBaseModel #

Base model for all astrological subjects. Contains common fields for location, time, and all celestial points.

Key fields: name, city, nation, lng, lat, altitude, tz_str, zodiac_type, houses_system_identifier, perspective_type, sun, moon, mercury…, first_house…, ascendant, polar_house_fallbacks, effective_houses_system_identifier, effective_houses_system_name, etc. altitude is the observer height in meters retained for Topocentric calculations.

houses_system_identifier (and its houses_system_name) always report the requested system, even when the cusps did not come from it. Inside the polar circle a quadrant system is undefined and the cusps are recomputed with a system that is defined everywhere; the request survives untouched so that a relocation or a re-cast starts from what the caller asked for rather than inheriting the substitute.

• polar_house_fallbacks (list[PolarHouseFallbackModel], empty when nothing was substituted) records each substitution: the requested and used systems, the real latitude, the latitude the successful call ran at, the epoch’s polar threshold and obliquity, and which chart products changed.
• effective_houses_system_identifier / effective_houses_system_name are derived from that list and report the division the cusps really came from. With no fallback they equal the requested pair.

ayanamsa_value (float | None) – the computed ayanamsa offset in degrees for sidereal charts (None for tropical).

nakshatra_ayanamsa (SiderealMode | None) and nakshatra_ayanamsa_value (float | None) – the ayanamsa a non-sidereal chart rotated its longitudes by to derive the nakshatras, and the offset in degrees it actually subtracted. Both are None on a sidereal chart (its own sidereal_mode/ayanamsa_value apply), on a chart that computed no nakshatras, and when nakshatra_ayanamsa=None selected the legacy uncorrected behaviour.

EphemerisDictModel #

Snapshot of planetary positions for a specific date.

LunarPhaseModel #

Compact lunar phase information attached to every AstrologicalSubjectModel (via the lunar_phase field).

The name comes from the separation, through eight windows centred on the events: New and Full Moon span 12.857° each (±6.4286° around 0° and 180°), the two quarters 38.571° each (±19.2857° around 90° and 270°), and the four intermediate names fill the rest. So a minute either side of an exact syzygy reads the same, and agrees with the illumination percentage. The lunation day is a different partition of the same circle — its bins begin at the conjunction rather than straddling it — and it is deliberately unchanged.

subject = AstrologicalSubjectFactory.from_birth_data(
    "Alice", 1990, 6, 15, 12, 0,
    lng=-0.1276, lat=51.5074, tz_str="Europe/London", online=False
)
print(subject.lunar_phase.moon_phase_name)   # e.g. "Waxing Gibbous"
print(subject.lunar_phase.moon_emoji)         # e.g. "🌔"
print(subject.lunar_phase.degrees_between_s_m)  # e.g. 135.7
print(subject.lunar_phase.major_phase)        # e.g. "First Quarter"
print(subject.lunar_phase.stage)              # e.g. "waxing"

MoonPhaseOverviewModel #

Top-level model returned by MoonPhaseDetailsFactory. Groups timestamp, Sun summary, Moon summary, and location data into a single structure suitable for API responses or serialization.

Nested models (all fields optional unless noted):

ZodiacSignModel #

Metadata for a zodiac sign.

RelationshipScoreModel #

Complete compatibility scoring result.

RelationshipScoreAspectModel #

Aspect contributing to relationship score.

ScoreBreakdownItemModel #

Explains a single scoring rule.

ActiveAspect #

TypedDict for configuring aspect orbs.

TransitMomentModel #

Snapshot of transits at a specific time.

TransitsTimeRangeModel #

Time series of transit snapshots.

PointInHouseModel #

A point from one chart placed in another chart’s house system.

HouseComparisonModel #

Bidirectional house comparison between two subjects.

ElementDistributionModel #

Element distribution in a chart.

QualityDistributionModel #

Quality/modality distribution in a chart.

SingleChartAspectsModel #

Aspects within a single chart (Natal, Composite, Return).

DualChartAspectsModel #

Aspects between two charts (Synastry, Transit).

ChartDataModel (Union) #

Type alias: Union[SingleChartDataModel, DualChartDataModel]. Represents any chart data output from ChartDataFactory.

---

V6 Advanced Models #

These models are returned by the v6 advanced calculation factories. Each factory’s documentation page has the full field reference.

Predictive Models #

Astronomical Models #

Traditional / Hellenistic Models #

Calendar / Event Models #

Returned by the factories that scan a date range for discrete moments. Every collection carries the requested start_jd / end_jd alongside its results, and every instant is a timezone-aware UTC datetime unless the field name says Julian Day.

Chart Analysis Models #

---

Literals & Constants (literals) #

Import from: kerykeion.schemas.literals

These Literal types define the allowed string values for various model fields, providing strict type checking and autocompletion in your IDE.

---

MotionState #

Classification of a celestial body’s speed relative to its mean daily motion. Populated on KerykeionPointModel.motion_state for the ten planets in Earth-centred perspectives; None elsewhere.

The band brackets zero on both sides and is tested before the sign of the speed, so a body creeping backwards at a hundredth of its mean motion reports a station rather than a plain "retrograde". The two stations are read differently and the sign of the speed cannot separate them — both are approached from one side of zero and left on the other — so they are told apart by the trend: a second speed sample a day later, falling or rising through the band. Without a usable second sample the generic "stationary" stands, which is an absence of a claim rather than a guess.

Downstream matching. "stationary_retrograde" and "stationary_direct" are new values on this literal. Code that matches motion_state exhaustively — a match statement, a dict keyed by every value, a TypeScript union mirrored from the schema — must be extended before it sees a chart cast at a station.

---

ZodiacType #

Defines the zodiac system to use for calculations.

---

Sign #

The 12 zodiac signs, using abbreviated 3-character names.

---

SignNumbers #

Integer indices for zodiac signs, from 0 (Aries) to 11 (Pisces).

---

Element #

The four classical elements.

---

Quality #

The three modalities (also called “modes” or “quadruplicities”).

---

AstrologicalPoint #

Comprehensive literal for all supported celestial points.

Main Planets: "Sun", "Moon", "Mercury", "Venus", "Mars", "Jupiter", "Saturn", "Uranus", "Neptune", "Pluto"

Lunar Nodes: "Mean_North_Lunar_Node", "True_North_Lunar_Node", "Mean_South_Lunar_Node", "True_South_Lunar_Node"

Special Points: "Chiron", "Mean_Lilith", "True_Lilith", "Interpolated_Lilith", "Mean_Priapus", "True_Priapus", "Earth", "Pholus", "Vertex", "Anti_Vertex", "Interpolated_Perigee", "White_Moon"

Uranian / Hamburg School: "Cupido", "Hades", "Zeus", "Kronos", "Apollon", "Admetos", "Vulkanus", "Poseidon"

Asteroids: "Ceres", "Pallas", "Juno", "Vesta"

Trans-Neptunian Objects (TNOs): "Eris", "Sedna", "Haumea", "Makemake", "Ixion", "Orcus", "Quaoar"

Fixed Stars: "Regulus", "Spica", "Aldebaran", "Antares", "Sirius", "Fomalhaut", "Algol", "Betelgeuse", "Canopus", "Procyon", "Arcturus", "Pollux", "Deneb", "Altair", "Rigel", "Achernar", "Capella", "Vega", "Alcyone", "Alphecca", "Algorab", "Deneb_Algedi", "Alkaid"

Arabic Parts (Lots): "Pars_Fortunae" (Part of Fortune), "Pars_Spiritus" (Part of Spirit), "Pars_Amoris" (Part of Love), "Pars_Fidei" (Part of Faith)

Axial Cusps (Angles): "Ascendant", "Medium_Coeli" (MC/Midheaven), "Descendant", "Imum_Coeli" (IC)

---

Houses #

The 12 astrological houses.

---

HouseNumbers #

Integers 1 through 12 representing the house numbers.

---

ChartType #

Defines the type of chart being generated.

---

AspectName #

The names of all supported aspects.

---

AspectMovementType #

Describes the phase of an aspect between two points.

---

SiderealMode #

The Ayanamsa (precession mode) used for Sidereal calculations.

48 modes total: 47 named + USER for custom ayanamsa definitions.

Classic modes:

Extended modes:

---

HousesSystemIdentifier #

Single-character identifiers for different house systems.

---

PerspectiveType #

Defines the viewpoint for calculations.

---

LunarPhaseName #

The eight traditional names for the Moon’s phases.

---

LunarPhaseEmoji #

Emojis corresponding to the lunar phases.

---

SolarPhase #

How near the Sun a body is, named as a condition of visibility. Set on every PlanetaryPhenomenaModel.

The three cut-offs that separate them are conventions, not constants of nature, and the schools disagree on all three. They live in SolarPhaseThresholdsModel (cazimi_deg 0.2833, combust_deg 8.5, under_beams_deg 17.0), which every phenomena collection echoes back and any caller may replace. The quantity compared is the true angular separation from the Sun (latitude included), not the difference in ecliptic longitude.

---

ApsisKind #

Which body the apsides of an orbit are measured against. Set on every PlanetaryNodeModel.

The generic periapsis/apoapsis fields are correct under either reading; this literal says which one is in force. The older perihelion/aphelion name the Sun and are deprecated for that reason.

---

KerykeionChartTheme #

Available visual themes for chart rendering.

---

KerykeionChartLanguage #

Supported language codes for chart labels.

---

ReturnType #

Types of planetary returns supported.

---

CompositeChartType #

Types of composite charts.

---

PointType #

Distinguishes between celestial bodies, house cusps, and midpoints.

---

SignsEmoji #

Zodiac sign symbols.

---

HouseNumbers #

Integer identifiers for houses (1-12).

---

RelationshipScoreDescription #

Categorical descriptions for compatibility scores.

"Minimal", "Medium", "Important", "Very Important", "Exceptional", "Rare Exceptional"

---

Settings (settings_models) #

Import from: kerykeion.schemas.settings_models

KerykeionSettingsModel #

Global configuration for the library, primarily handling internationalization.

• language_settings: A dictionary mapping language codes (e.g., “EN”, “IT”) to KerykeionLanguageModel.

KerykeionLanguageModel #

Defines all the string labels used in chart generation and reports. Planet/point names are accessed via the nested celestial_points field (KerykeionLanguageCelestialPointModel), not directly on the model.

• celestial_points: KerykeionLanguageCelestialPointModel — localized names for Sun, Moon, Mercury, etc.
• fire, earth, air, water (Element names, lowercase keys)
• Additional layout/formatting strings used in chart rendering.

---

Exceptions (exceptions) #

Import from: kerykeion.schemas.exceptions

KerykeionException #

The base exception class for all library-specific errors.

from kerykeion.schemas import KerykeionException
from kerykeion import AstrologicalSubjectFactory

try:
    subject = AstrologicalSubjectFactory.from_birth_data(
        "Example", 1990, 1, 1, 12, 0,
        city="UnknownCity", nation="XX",
        online=True
    )
except KerykeionException as e:
    print(f"Error calculating chart: {e}")

Internal Schemas (chart_template_model) #

These models are used internally for SVG generation but exposed for advanced customization.

ChartTemplateModel #

Variables passed to the XML string.Template for rendering the SVG.

(And many more styling variables)

Detailed Settings Models #

KerykeionLanguageCelestialPointModel #

Used within KerykeionLanguageModel to define localized names for specific bodies.

---