{
  "components": {
    "schemas": {
      "ACGAsteroidGroup": {
        "description": "Categorical asteroid groups explicitly permitted for AstroCartography.",
        "enum": [
          "major",
          "centaur",
          "tno",
          "muse"
        ],
        "title": "ACGAsteroidGroup",
        "type": "string"
      },
      "ACGCCGRequestPayload": {
        "additionalProperties": false,
        "description": "Payload for Cyclocartography time-series calculations.",
        "example": {
          "epoch": "1990-06-15T14:30:00Z",
          "natal": {
            "birthplace_lat": 34.05,
            "birthplace_lon": -118.24
          },
          "options": {
            "asteroid_groups": [
              "centaur",
              "muse"
            ]
          }
        },
        "properties": {
          "bodies": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              }
            ],
            "description": "Explicit body name selection. Supported: Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto, Chiron, MeanNode, SouthNode, TrueNode, TrueSouthNode, MeanLilith, OscuLilith, Ceres. Aliases: NorthNode/Rahu/Node -\u003e MeanNode; TrueNorthNode/TrueRahu -\u003e TrueNode; Ketu -\u003e SouthNode.",
            "title": "Bodies"
          },
          "end_epoch": {
            "description": "End of analysis window (ISO 8601)",
            "title": "End Epoch",
            "type": "string"
          },
          "epoch": {
            "description": "ISO 8601 datetime of birth or event",
            "title": "Epoch",
            "type": "string"
          },
          "jd": {
            "anyOf": [
              {
                "format": "double",
                "type": "number"
              }
            ],
            "description": "Julian Day (alternative to epoch)",
            "title": "Jd"
          },
          "mode": {
            "default": "transit",
            "description": "Calculation mode. 'transit' (default): all bodies use live transiting positions. 'ccg_hybrid': inner planets (Sun, Moon, Mercury, Venus, Mars) and lunar nodes use secondary progressions from the natal epoch; outer planets (Jupiter+) remain transits.",
            "enum": [
              "transit",
              "ccg_hybrid"
            ],
            "nullable": true,
            "title": "Mode",
            "type": "string"
          },
          "natal": {
            "$ref": "#/components/schemas/ACGNatalRequest",
            "description": "Natal origin points"
          },
          "options": {
            "$ref": "#/components/schemas/ACGOptionsRequest",
            "description": "Calculation behavior options"
          },
          "scoring": {
            "description": "Scoring mode. Default (null/omitted): geographic proximity only in 'scores'. 'natal_weighted': adds a 'natal_scores' map to each snapshot showing how strongly each transiting body aspects natal chart positions (0-1 scale, based on conjunction/opposition/trine/square/sextile within standard orbs).",
            "enum": [
              "natal_weighted"
            ],
            "nullable": true,
            "title": "Scoring",
            "type": "string"
          },
          "start_epoch": {
            "description": "Start of analysis window (ISO 8601)",
            "title": "Start Epoch",
            "type": "string"
          },
          "step_days": {
            "default": 1,
            "description": "Time step in days",
            "title": "Step Days",
            "type": "number"
          },
          "target_lat": {
            "description": "Analysis target latitude",
            "title": "Target Lat",
            "type": "number"
          },
          "target_lon": {
            "description": "Analysis target longitude",
            "title": "Target Lon",
            "type": "number"
          }
        },
        "required": [
          "epoch",
          "target_lat",
          "target_lon",
          "start_epoch",
          "end_epoch"
        ],
        "title": "ACGCCGRequestPayload",
        "type": "object"
      },
      "ACGLocalSpaceRequestPayload": {
        "additionalProperties": false,
        "description": "Payload for local space azimuth calculations.",
        "example": {
          "epoch": "1990-06-15T14:30:00Z",
          "natal": {
            "birthplace_lat": 34.05,
            "birthplace_lon": -118.24
          },
          "options": {
            "asteroid_groups": [
              "centaur",
              "muse"
            ]
          }
        },
        "properties": {
          "bodies": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              }
            ],
            "description": "Explicit body name selection. Supported: Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto, Chiron, MeanNode, SouthNode, TrueNode, TrueSouthNode, MeanLilith, OscuLilith, Ceres. Aliases: NorthNode/Rahu/Node -\u003e MeanNode; TrueNorthNode/TrueRahu -\u003e TrueNode; Ketu -\u003e SouthNode.",
            "title": "Bodies"
          },
          "epoch": {
            "description": "ISO 8601 datetime of birth or event",
            "title": "Epoch",
            "type": "string"
          },
          "jd": {
            "anyOf": [
              {
                "format": "double",
                "type": "number"
              }
            ],
            "description": "Julian Day (alternative to epoch)",
            "title": "Jd"
          },
          "lat": {
            "description": "Target latitude",
            "title": "Lat",
            "type": "number"
          },
          "line_distance_km": {
            "description": "Distance to project local space lines in kilometers. Defaults to approximately 5550km (50 degrees).",
            "nullable": true,
            "title": "Line Distance Km",
            "type": "number"
          },
          "lon": {
            "description": "Target longitude",
            "title": "Lon",
            "type": "number"
          },
          "natal": {
            "$ref": "#/components/schemas/ACGNatalRequest",
            "description": "Natal origin points"
          },
          "options": {
            "$ref": "#/components/schemas/ACGOptionsRequest",
            "description": "Calculation behavior options"
          },
          "query_lat": {
            "description": "Latitude of the query point. When supplied with query_lon, each local-space line is annotated with its great-circle min distance.",
            "nullable": true,
            "title": "Query Lat",
            "type": "number"
          },
          "query_lon": {
            "description": "Longitude of the query point. When supplied with query_lat, each local-space line is annotated with its great-circle min distance.",
            "nullable": true,
            "title": "Query Lon",
            "type": "number"
          },
          "response_format": {
            "default": "json",
            "description": "Response format ('json' or 'geojson'). Defaults to 'json'.",
            "enum": [
              "json",
              "geojson"
            ],
            "nullable": true,
            "title": "Response Format",
            "type": "string"
          }
        },
        "required": [
          "epoch",
          "lat",
          "lon"
        ],
        "title": "ACGLocalSpaceRequestPayload",
        "type": "object"
      },
      "ACGNatalRequest": {
        "additionalProperties": false,
        "description": "Natal geographical data for ACG offset calculation.",
        "properties": {
          "birthplace_alt_m": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "title": "Birthplace Alt M"
          },
          "birthplace_lat": {
            "title": "Birthplace Lat",
            "type": "number"
          },
          "birthplace_lon": {
            "title": "Birthplace Lon",
            "type": "number"
          },
          "houses_system": {
            "default": "W",
            "title": "Houses System",
            "type": "string"
          }
        },
        "required": [
          "birthplace_lat",
          "birthplace_lon"
        ],
        "title": "ACGNatalRequest",
        "type": "object"
      },
      "ACGOptionsRequest": {
        "additionalProperties": false,
        "description": "Configuration options for AstroCartography calculations.",
        "properties": {
          "angle_epoch": {
            "description": "Decouple the rotational frame from the position epoch: body positions come from epoch/jd as usual, but ACG line angles are projected against this epoch's GMST. Accepts an ISO-8601 UTC datetime or a bare Julian Day. Empty/omitted = angles use the position epoch (default, unchanged). Use to overlay a secondary chart on a base frame — e.g. Human Design Design-register lines on the natal map (positions at the Design epoch, angles at the natal epoch), matching the hd_expression heatmap convention; also progressed/return overlays. Positions and obliquity stay on the position epoch, so every line is rigidly translated in longitude by the GMST difference.",
            "title": "Angle Epoch",
            "type": "string"
          },
          "aspect_angles": {
            "anyOf": [
              {
                "items": {
                  "type": "number"
                },
                "type": "array"
              }
            ],
            "description": "Angles to compute aspects for",
            "title": "Aspect Angles"
          },
          "asteroid_groups": {
            "anyOf": [
              {
                "items": {
                  "$ref": "#/components/schemas/ACGAsteroidGroup"
                },
                "type": "array"
              }
            ],
            "description": "Filter by asteroid group. Main belt and fixed stars are explicitly prohibited.",
            "title": "Asteroid Groups"
          },
          "include_aspects": {
            "anyOf": [
              {
                "type": "boolean"
              }
            ],
            "description": "Include aspect lines",
            "title": "Include Aspects"
          },
          "include_hd_gate": {
            "anyOf": [
              {
                "type": "boolean"
              }
            ],
            "description": "Enrich every emitted line feature with the Human Design gate its body's ecliptic longitude carries (properties.hd_gate: gate/line/color/tone/base). Purely additive — does not change the body set or geometry. Default false. Combine with bodies:[\"Earth\"] or group:\"hd\" for the HD-13 body set.",
            "title": "Include HD Gate"
          },
          "include_lines": {
            "anyOf": [
              {
                "type": "boolean"
              }
            ],
            "description": "CCG only: emit MC/IC/AC/DC GeoJSON line geometry per snapshot (identical to /acg/power-lines, with ccg_hybrid progression applied per body). Default false. No effect on /acg/natal-lines.",
            "title": "Include Lines"
          },
          "include_midpoints": {
            "anyOf": [
              {
                "type": "boolean"
              }
            ],
            "description": "Include planetary midpoint lines",
            "title": "Include Midpoints"
          },
          "include_parans": {
            "anyOf": [
              {
                "type": "boolean"
              }
            ],
            "description": "Include parans (latitude crossings)",
            "title": "Include Parans"
          },
          "line_types": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              }
            ],
            "description": "Line types to include. Supported: MC, IC, AC, DC, ASP. Aliases: POWER -\u003e MC+IC+AC+DC; ASPECT/SPECT -\u003e ASP.",
            "title": "Line Types"
          },
          "paran_lat_cutoff": {
            "anyOf": [
              {
                "format": "double",
                "type": "number"
              }
            ],
            "description": "Maximum absolute latitude (in degrees) for paran crossing points. Crossings whose intersection latitude exceeds this value (north or south) are excluded from the response. When null or omitted, no cutoff is applied (current behavior preserved). Range: 0-90.",
            "title": "Paran Latitude Cutoff"
          },
          "refraction_correction": {
            "anyOf": [
              {
                "type": "boolean"
              }
            ],
            "description": "Apply atmospheric refraction to AC/DC",
            "title": "Refraction Correction"
          },
          "resolution": {
            "anyOf": [
              {
                "type": "integer"
              }
            ],
            "description": "Resolution slices for mapping",
            "title": "Resolution"
          }
        },
        "title": "ACGOptionsRequest",
        "type": "object"
      },
      "ACGRequestPayload": {
        "additionalProperties": false,
        "description": "Primary payload structure for ACG global line calculation requests.",
        "example": {
          "epoch": "1990-06-15T14:30:00Z",
          "natal": {
            "birthplace_lat": 34.05,
            "birthplace_lon": -118.24
          },
          "options": {
            "asteroid_groups": [
              "centaur",
              "muse"
            ]
          }
        },
        "properties": {
          "bodies": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              }
            ],
            "description": "Explicit body name selection. Supported: Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto, Chiron, MeanNode, SouthNode, TrueNode, TrueSouthNode, MeanLilith, OscuLilith, Ceres. Aliases: NorthNode/Rahu/Node -\u003e MeanNode; TrueNorthNode/TrueRahu -\u003e TrueNode; Ketu -\u003e SouthNode.",
            "title": "Bodies"
          },
          "epoch": {
            "description": "ISO 8601 datetime of birth or event",
            "title": "Epoch",
            "type": "string"
          },
          "format": {
            "default": "json",
            "description": "Response format. `llm` returns compact rows + schema in metadata; only honored by /acg/hits.",
            "title": "Format",
            "type": "string"
          },
          "group": {
            "description": "Body group selector. `standard` (default) = planets + asteroids; `hermetic` = Hermetic Lot lines (Fortune, Spirit, etc.); `all` = both; `hd` = the Human Design 13 (Sun, Earth, Moon, Mercury–Pluto, Mean Node, South Node) — pair with options.include_hd_gate for gate-labelled lines. On /acg/hits, `hermetic`/`all` require the Scale tier or above. Hermetic lots require natal birthplace data.",
            "nullable": true,
            "title": "Group",
            "type": "string"
          },
          "jd": {
            "anyOf": [
              {
                "format": "double",
                "type": "number"
              }
            ],
            "description": "Julian Day (alternative to epoch)",
            "title": "Jd"
          },
          "natal": {
            "$ref": "#/components/schemas/ACGNatalRequest",
            "description": "Natal origin points"
          },
          "options": {
            "$ref": "#/components/schemas/ACGOptionsRequest",
            "description": "Calculation behavior options"
          },
          "query_lat": {
            "description": "Latitude of the query point",
            "nullable": true,
            "title": "Query Lat",
            "type": "number"
          },
          "query_lon": {
            "description": "Longitude of the query point",
            "nullable": true,
            "title": "Query Lon",
            "type": "number"
          },
          "radius_deg": {
            "description": "Proximity radius in degrees",
            "nullable": true,
            "title": "Radius Deg",
            "type": "number"
          }
        },
        "required": [
          "epoch"
        ],
        "title": "ACGRequestPayload",
        "type": "object"
      },
      "APIKeyMetadata": {
        "description": "Public metadata for an API key (never includes plaintext key).",
        "properties": {
          "created_at": {
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "expires_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              }
            ],
            "title": "Expires At"
          },
          "is_active": {
            "description": "True if not revoked and not expired",
            "title": "Is Active",
            "type": "boolean"
          },
          "key_id": {
            "title": "Key Id",
            "type": "string"
          },
          "key_prefix": {
            "description": "First 14 chars (e.g., 'opene-Xd3EGwKu')",
            "title": "Key Prefix",
            "type": "string"
          },
          "key_suffix": {
            "description": "Last 4 chars (e.g., 'dpSY')",
            "title": "Key Suffix",
            "type": "string"
          },
          "last_used_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              }
            ],
            "title": "Last Used At"
          },
          "name": {
            "title": "Name",
            "type": "string"
          },
          "revoked_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              }
            ],
            "title": "Revoked At"
          }
        },
        "required": [
          "key_id",
          "key_prefix",
          "key_suffix",
          "name",
          "created_at",
          "is_active"
        ],
        "title": "APIKeyMetadata",
        "type": "object"
      },
      "AccidentalDignityInfo": {
        "additionalProperties": false,
        "description": "Accidental dignity information for a body (tags-only).",
        "properties": {
          "tags": {
            "description": "Accidental dignity tags (planets-only).",
            "example": [
              "angular"
            ],
            "items": {
              "type": "string"
            },
            "title": "Tags",
            "type": "array"
          }
        },
        "title": "AccidentalDignityInfo",
        "type": "object"
      },
      "AgroCalendarDay": {
        "description": "One day's compact entry in the calendar.",
        "properties": {
          "ascending": {
            "description": "True if Moon latitude is increasing",
            "title": "Ascending",
            "type": "boolean"
          },
          "date": {
            "description": "Date in YYYY-MM-DD format",
            "title": "Date",
            "type": "string"
          },
          "day_type": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "root | leaf | flower | fruit",
            "title": "Day Type"
          },
          "error": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Error message if calculation failed",
            "title": "Error"
          },
          "illumination_pct": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "description": "Illumination percentage",
            "title": "Illumination Pct"
          },
          "phase_name": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Current moon phase name",
            "title": "Phase Name"
          },
          "quality_score": {
            "anyOf": [
              {
                "type": "integer"
              }
            ],
            "description": "Quality score from 0 to 100",
            "title": "Quality Score"
          },
          "spring_neap_index": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "description": "Spring-neap index",
            "title": "Spring Neap Index"
          },
          "total_forcing": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "description": "Total tidal forcing score",
            "title": "Total Forcing"
          },
          "void_active": {
            "description": "True if Void of Course is active during the day",
            "title": "Void Active",
            "type": "boolean"
          }
        },
        "required": [
          "date",
          "ascending",
          "void_active"
        ],
        "title": "AgroCalendarDay",
        "type": "object"
      },
      "AgroCalendarResponse": {
        "description": "Multi-day calendar summary.",
        "properties": {
          "_meta": {
            "description": "Calculation metadata",
            "title": " Meta",
            "type": "object"
          },
          "days": {
            "description": "Daily biodynamic summaries",
            "items": {
              "$ref": "#/components/schemas/AgroCalendarDay"
            },
            "title": "Days",
            "type": "array"
          },
          "observer": {
            "description": "Observer location details",
            "title": "Observer",
            "type": "object"
          },
          "range": {
            "additionalProperties": {
              "type": "string"
            },
            "description": "Start and end dates of the calendar",
            "title": "Range",
            "type": "object"
          }
        },
        "required": [
          "range",
          "observer",
          "days",
          "_meta"
        ],
        "title": "AgroCalendarResponse",
        "type": "object"
      },
      "AgroDailyResponse": {
        "description": "Full biodynamic daily profile.",
        "properties": {
          "_meta": {
            "description": "Calculation metadata",
            "title": " Meta",
            "type": "object"
          },
          "date": {
            "description": "Date in YYYY-MM-DD format",
            "title": "Date",
            "type": "string"
          },
          "horizon": {
            "allOf": [
              {
                "$ref": "#/components/schemas/HorizonEvents"
              }
            ],
            "description": "Sunrise/sunset and moonrise/moonset events"
          },
          "lunar": {
            "allOf": [
              {
                "$ref": "#/components/schemas/AgroLunarData"
              }
            ],
            "description": "Lunar data summary"
          },
          "observer": {
            "description": "Observer location details",
            "title": "Observer",
            "type": "object"
          },
          "thun": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ThunAnalysis"
              }
            ],
            "description": "Thun biodynamic analysis"
          },
          "tidal_forcing": {
            "$ref": "#/components/schemas/AgroTidalData",
            "description": "Tidal forcing metrics"
          },
          "void_of_course": {
            "allOf": [
              {
                "$ref": "#/components/schemas/VoCData"
              }
            ],
            "description": "Void of course Moon data"
          }
        },
        "required": [
          "date",
          "observer",
          "lunar",
          "thun",
          "void_of_course",
          "horizon",
          "_meta"
        ],
        "title": "AgroDailyResponse",
        "type": "object"
      },
      "AgroLunarData": {
        "properties": {
          "ascending": {
            "description": "True if ascending",
            "title": "Ascending",
            "type": "boolean"
          },
          "distance_km": {
            "description": "Distance from Earth in km",
            "title": "Distance Km",
            "type": "number"
          },
          "illumination_pct": {
            "description": "Illumination percentage 0-100",
            "title": "Illumination Pct",
            "type": "number"
          },
          "lat_velocity": {
            "description": "Latitude velocity",
            "title": "Lat Velocity",
            "type": "number"
          },
          "latitude": {
            "description": "Ecliptic latitude",
            "title": "Latitude",
            "type": "number"
          },
          "node_lon": {
            "description": "True node longitude",
            "title": "Node Lon",
            "type": "number"
          },
          "phase_name": {
            "description": "Current moon phase name",
            "title": "Phase Name",
            "type": "string"
          },
          "sign_longitude": {
            "description": "Longitude within the current sign (0-30)",
            "title": "Sign Longitude",
            "type": "number"
          },
          "waxing": {
            "description": "True if waxing",
            "title": "Waxing",
            "type": "boolean"
          }
        },
        "required": [
          "sign_longitude",
          "latitude",
          "distance_km",
          "ascending",
          "lat_velocity",
          "node_lon",
          "phase_name",
          "illumination_pct",
          "waxing"
        ],
        "title": "AgroLunarData",
        "type": "object"
      },
      "AgroTidalData": {
        "properties": {
          "diurnal_inequality": {
            "description": "Diurnal inequality value",
            "title": "Diurnal Inequality",
            "type": "number"
          },
          "king_tide_risk": {
            "description": "King tide risk score (0 to 1)",
            "title": "King Tide Risk",
            "type": "number"
          },
          "perigee_proximity": {
            "description": "Perigee proximity score (0 to 1)",
            "title": "Perigee Proximity",
            "type": "number"
          },
          "spring_neap_index": {
            "description": "Spring-neap index (-1 to +1)",
            "title": "Spring Neap Index",
            "type": "number"
          },
          "syzygy_status": {
            "description": "Syzygy status (e.g., 'spring', 'neap')",
            "title": "Syzygy Status",
            "type": "string"
          },
          "total_forcing": {
            "description": "Total tidal forcing score",
            "title": "Total Forcing",
            "type": "number"
          }
        },
        "required": [
          "spring_neap_index",
          "syzygy_status",
          "diurnal_inequality",
          "total_forcing",
          "perigee_proximity",
          "king_tide_risk"
        ],
        "title": "AgroTidalData",
        "type": "object"
      },
      "AnglesPointsRequest": {
        "additionalProperties": false,
        "description": "Request for angles + points (granular endpoint).",
        "example": {
          "date_time": {
            "iso": "2025-12-11T12:00:00Z"
          },
          "house_system": "P",
          "latitude": 40.7128,
          "longitude": -74.006
        },
        "properties": {
          "date_time": {
            "allOf": [
              {
                "$ref": "#/components/schemas/DateTimeInput"
              }
            ],
            "description": "Calculation datetime"
          },
          "house_system": {
            "default": "P",
            "description": "House system code used to derive angles/vertex",
            "example": "P",
            "title": "House System",
            "type": "string"
          },
          "latitude": {
            "description": "Observer latitude in decimal degrees",
            "maximum": 90,
            "minimum": -90,
            "title": "Latitude",
            "type": "number"
          },
          "longitude": {
            "description": "Observer longitude in decimal degrees",
            "maximum": 180,
            "minimum": -180,
            "title": "Longitude",
            "type": "number"
          }
        },
        "required": [
          "date_time",
          "latitude",
          "longitude"
        ],
        "title": "AnglesPointsRequest",
        "type": "object"
      },
      "AnglesPointsResponse": {
        "additionalProperties": false,
        "description": "Response for angles + points granular endpoint.",
        "properties": {
          "angles": {
            "additionalProperties": {
              "type": "number"
            },
            "description": "Angles and points (degrees 0-360)",
            "title": "Angles",
            "type": "object"
          },
          "metadata": {
            "description": "Calculation metadata",
            "title": "Metadata",
            "type": "object"
          },
          "success": {
            "default": true,
            "description": "Calculation success status",
            "title": "Success",
            "type": "boolean"
          }
        },
        "required": [
          "angles",
          "metadata"
        ],
        "title": "AnglesPointsResponse",
        "type": "object"
      },
      "AnglesResponse": {
        "additionalProperties": true,
        "description": "Chart angles data in response.",
        "properties": {
          "ascendant": {
            "description": "Ascendant longitude in degrees",
            "title": "Ascendant",
            "type": "number"
          },
          "descendant": {
            "description": "Descendant longitude in degrees",
            "title": "Descendant",
            "type": "number"
          },
          "imum_coeli": {
            "description": "Imum Coeli longitude in degrees",
            "title": "Imum Coeli",
            "type": "number"
          },
          "midheaven": {
            "description": "Midheaven longitude in degrees",
            "title": "Midheaven",
            "type": "number"
          }
        },
        "required": [
          "ascendant",
          "midheaven",
          "descendant",
          "imum_coeli"
        ],
        "title": "AnglesResponse",
        "type": "object"
      },
      "AntisciaBodyInput": {
        "additionalProperties": false,
        "description": "A body ID and ecliptic longitude pair for antiscia calculation.",
        "properties": {
          "id": {
            "description": "Planet/body identifier (0=Sun, 1=Moon, 2=Mercury, etc.)",
            "title": "Body ID",
            "type": "integer"
          },
          "longitude": {
            "description": "Ecliptic longitude in degrees [0, 360)",
            "maximum": 360,
            "minimum": 0,
            "title": "Longitude",
            "type": "number"
          }
        },
        "required": [
          "id",
          "longitude"
        ],
        "title": "AntisciaBodyInput",
        "type": "object"
      },
      "AntisciaContact": {
        "additionalProperties": false,
        "description": "A detected antiscia or contra-antiscia conjunction between two bodies.",
        "properties": {
          "orb": {
            "description": "Angular separation in degrees",
            "title": "Orb",
            "type": "number"
          },
          "planet1": {
            "description": "ID of the planet whose antiscion / contra-antiscion is involved",
            "title": "Planet 1",
            "type": "integer"
          },
          "planet1_name": {
            "title": "Planet 1 Name",
            "type": "string"
          },
          "planet2": {
            "description": "ID of the planet whose natal longitude is conjunct",
            "title": "Planet 2",
            "type": "integer"
          },
          "planet2_name": {
            "title": "Planet 2 Name",
            "type": "string"
          },
          "type": {
            "description": "Type of antiscia contact",
            "enum": [
              "antiscion_conjunction",
              "contra_antiscion_conjunction"
            ],
            "title": "Contact Type",
            "type": "string"
          }
        },
        "required": [
          "planet1",
          "planet1_name",
          "planet2",
          "planet2_name",
          "type",
          "orb"
        ],
        "title": "AntisciaContact",
        "type": "object"
      },
      "AntisciaPoint": {
        "additionalProperties": false,
        "description": "Antiscion and contra-antiscion for a single body.",
        "properties": {
          "antiscion_longitude": {
            "description": "Mirror longitude across the Cancer/Capricorn axis",
            "title": "Antiscion Longitude",
            "type": "number"
          },
          "antiscion_sign": {
            "title": "Antiscion Sign",
            "type": "string"
          },
          "contra_antiscion_longitude": {
            "description": "Opposition point of the antiscion (mirror across Aries/Libra axis)",
            "title": "Contra-Antiscion Longitude",
            "type": "number"
          },
          "contra_antiscion_sign": {
            "title": "Contra-Antiscion Sign",
            "type": "string"
          },
          "natal_longitude": {
            "description": "Original ecliptic longitude",
            "title": "Natal Longitude",
            "type": "number"
          },
          "natal_sign": {
            "title": "Natal Sign",
            "type": "string"
          },
          "planet_id": {
            "title": "Planet ID",
            "type": "integer"
          },
          "planet_name": {
            "title": "Planet Name",
            "type": "string"
          }
        },
        "required": [
          "planet_id",
          "planet_name",
          "natal_longitude",
          "natal_sign",
          "antiscion_longitude",
          "antiscion_sign",
          "contra_antiscion_longitude",
          "contra_antiscion_sign"
        ],
        "title": "AntisciaPoint",
        "type": "object"
      },
      "AntisciaRequest": {
        "additionalProperties": false,
        "description": "Request body for antiscia / contra-antiscia calculation.",
        "example": {
          "bodies": [
            {
              "id": 0,
              "longitude": 15
            },
            {
              "id": 1,
              "longitude": 165
            },
            {
              "id": 4,
              "longitude": 225
            }
          ],
          "orb": 2
        },
        "properties": {
          "bodies": {
            "description": "Array of body ID + longitude pairs",
            "items": {
              "$ref": "#/components/schemas/AntisciaBodyInput"
            },
            "title": "Bodies",
            "type": "array"
          },
          "orb": {
            "default": 2,
            "description": "Orb in degrees for contact detection (default 2.0)",
            "maximum": 10,
            "minimum": 0,
            "title": "Orb",
            "type": "number"
          }
        },
        "required": [
          "bodies"
        ],
        "title": "AntisciaRequest",
        "type": "object"
      },
      "AntisciaResponse": {
        "additionalProperties": false,
        "description": "Response from antiscia calculation endpoint.",
        "properties": {
          "antiscia_points": {
            "description": "Antiscion and contra-antiscion for each input body",
            "items": {
              "$ref": "#/components/schemas/AntisciaPoint"
            },
            "title": "Antiscia Points",
            "type": "array"
          },
          "calculation_metadata": {
            "description": "Metadata about the calculation",
            "title": "Calculation Metadata",
            "type": "object"
          },
          "contacts": {
            "description": "Detected antiscia and contra-antiscia conjunctions between bodies",
            "items": {
              "$ref": "#/components/schemas/AntisciaContact"
            },
            "title": "Contacts",
            "type": "array"
          },
          "success": {
            "default": true,
            "description": "Calculation success status",
            "title": "Success",
            "type": "boolean"
          }
        },
        "required": [
          "antiscia_points",
          "contacts",
          "calculation_metadata"
        ],
        "title": "AntisciaResponse",
        "type": "object"
      },
      "ApiKeyNotificationStateResponse": {
        "description": "Notification state for a given API key + month.",
        "properties": {
          "api_key_id": {
            "title": "Api Key Id",
            "type": "string"
          },
          "included_80_sent_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              }
            ],
            "title": "Included 80 Sent At"
          },
          "month": {
            "title": "Month",
            "type": "string"
          },
          "overage_cap_80_sent_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              }
            ],
            "title": "Overage Cap 80 Sent At"
          }
        },
        "required": [
          "api_key_id",
          "month"
        ],
        "title": "ApiKeyNotificationStateResponse",
        "type": "object"
      },
      "ApiKeyOverageSettingsResponse": {
        "description": "Overage configuration stored per API key (dashboard only for now).",
        "properties": {
          "api_key_id": {
            "title": "Api Key Id",
            "type": "string"
          },
          "currency": {
            "default": "USD",
            "title": "Currency",
            "type": "string"
          },
          "hard_stop_on_cap": {
            "default": true,
            "title": "Hard Stop On Cap",
            "type": "boolean"
          },
          "monthly_overage_cap_cents": {
            "default": 0,
            "title": "Monthly Overage Cap Cents",
            "type": "integer"
          },
          "overages_enabled": {
            "default": false,
            "title": "Overages Enabled",
            "type": "boolean"
          }
        },
        "required": [
          "api_key_id"
        ],
        "title": "ApiKeyOverageSettingsResponse",
        "type": "object"
      },
      "ApiKeyOverageStatusResponse": {
        "description": "Monthly usage status for a specific API key.",
        "properties": {
          "api_key_id": {
            "title": "Api Key Id",
            "type": "string"
          },
          "calculation_metadata": {
            "$ref": "#/components/schemas/CalculationMetadata",
            "description": "Metadata describing the status calculation context"
          },
          "included_calls": {
            "title": "Included Calls",
            "type": "integer"
          },
          "included_units": {
            "default": 0,
            "title": "Included Units",
            "type": "integer"
          },
          "month": {
            "title": "Month",
            "type": "string"
          },
          "notification_state": {
            "$ref": "#/components/schemas/ApiKeyNotificationStateResponse"
          },
          "overage_calls": {
            "title": "Overage Calls",
            "type": "integer"
          },
          "overage_settings": {
            "$ref": "#/components/schemas/ApiKeyOverageSettingsResponse"
          },
          "overage_spend_cap_cents": {
            "anyOf": [
              {
                "type": "integer"
              }
            ],
            "title": "Overage Spend Cap Cents"
          },
          "overage_spend_remaining_cents": {
            "anyOf": [
              {
                "type": "integer"
              }
            ],
            "title": "Overage Spend Remaining Cents"
          },
          "overage_spend_used_cents": {
            "default": 0,
            "title": "Overage Spend Used Cents",
            "type": "integer"
          },
          "overage_unit_price_cents_per_1000": {
            "default": 0,
            "title": "Overage Unit Price Cents Per 1000",
            "type": "integer"
          },
          "overage_units": {
            "default": 0,
            "title": "Overage Units",
            "type": "integer"
          },
          "owner_user_id": {
            "title": "Owner User Id",
            "type": "string"
          },
          "percent_calls_used": {
            "title": "Percent Calls Used",
            "type": "number"
          },
          "percent_units_used": {
            "default": 0,
            "title": "Percent Units Used",
            "type": "number"
          },
          "tier": {
            "title": "Tier",
            "type": "string"
          },
          "total_calls": {
            "title": "Total Calls",
            "type": "integer"
          },
          "total_units": {
            "default": 0,
            "title": "Total Units",
            "type": "integer"
          },
          "warning": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "title": "Warning"
          }
        },
        "required": [
          "api_key_id",
          "month",
          "owner_user_id",
          "tier",
          "included_calls",
          "total_calls",
          "overage_calls",
          "percent_calls_used",
          "overage_settings"
        ],
        "title": "ApiKeyOverageStatusResponse",
        "type": "object"
      },
      "ArabicPartResponse": {
        "description": "Individual Arabic part calculation.",
        "properties": {
          "canonical_name": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Original Arabic part identifier (without lot_ prefix)",
            "title": "Canonical Name"
          },
          "degree_symbol": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Degree display",
            "title": "Degree Symbol"
          },
          "display_name": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Human-friendly display name",
            "title": "Display Name"
          },
          "formula_used": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Which formula variation was executed",
            "title": "Formula Used"
          },
          "house": {
            "anyOf": [
              {
                "type": "integer"
              }
            ],
            "description": "House position (1-12)",
            "title": "House"
          },
          "longitude": {
            "description": "Longitude in degrees",
            "title": "Longitude",
            "type": "number"
          },
          "name": {
            "description": "Arabic part registry key",
            "title": "Name",
            "type": "string"
          },
          "sign": {
            "description": "Zodiac sign",
            "title": "Sign",
            "type": "string"
          },
          "sign_longitude": {
            "description": "Longitude within sign",
            "title": "Sign Longitude",
            "type": "number"
          },
          "symbol": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Traditional symbol",
            "title": "Symbol"
          }
        },
        "required": [
          "name",
          "longitude",
          "sign",
          "sign_longitude"
        ],
        "title": "ArabicPartResponse",
        "type": "object"
      },
      "ArabicPartsResponse": {
        "additionalProperties": false,
        "description": "Canonical Arabic parts payload for enhanced responses.",
        "properties": {
          "arabic_parts": {
            "additionalProperties": {
              "$ref": "#/components/schemas/ArabicPartResponse"
            },
            "description": "Arabic parts keyed by registry name",
            "title": "Arabic Parts",
            "type": "object"
          },
          "calculation_time_ms": {
            "description": "Computation time in milliseconds",
            "title": "Calculation Time Ms",
            "type": "number"
          },
          "formulas_used": {
            "description": "Ordered list of formulas executed",
            "items": {
              "type": "string"
            },
            "title": "Formulas Used",
            "type": "array"
          },
          "hermetic_lot_names": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              }
            ],
            "description": "Sorted subset of arabic part keys that map to canonical Hermetic lots",
            "title": "Hermetic Lot Names"
          },
          "sect_determination": {
            "description": "Sect analysis metadata used for formula selection",
            "title": "Sect Determination",
            "type": "object"
          },
          "total_parts_calculated": {
            "description": "Number of parts returned",
            "title": "Total Parts Calculated",
            "type": "integer"
          }
        },
        "required": [
          "arabic_parts",
          "sect_determination",
          "formulas_used",
          "calculation_time_ms",
          "total_parts_calculated"
        ],
        "title": "ArabicPartsResponse",
        "type": "object"
      },
      "AspectCheckRequest": {
        "additionalProperties": false,
        "description": "Request for aspect calculation between two points.",
        "example": {
          "aspect_types": [
            "conjunction",
            "opposition",
            "square",
            "trine"
          ],
          "longitude1": 120,
          "longitude2": 180,
          "max_orb": 6
        },
        "properties": {
          "aspect_types": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              }
            ],
            "description": "Filter aspects by type (omit for all types). Valid: conjunction, opposition, trine, square, sextile, quintile, semi_sextile, quincunx, semi_square, sesquiquadrate",
            "example": [
              "conjunction",
              "opposition"
            ],
            "title": "Aspect Types"
          },
          "longitude1": {
            "description": "First point ecliptic longitude in degrees (0-360)",
            "example": 120,
            "maximum": 360,
            "minimum": 0,
            "title": "Longitude1",
            "type": "number"
          },
          "longitude2": {
            "description": "Second point ecliptic longitude in degrees (0-360)",
            "example": 180,
            "maximum": 360,
            "minimum": 0,
            "title": "Longitude2",
            "type": "number"
          },
          "max_orb": {
            "anyOf": [
              {
                "maximum": 20,
                "minimum": 0,
                "type": "number"
              }
            ],
            "default": 6,
            "description": "Maximum orb allowance in degrees (default: 6.0)",
            "example": 6,
            "title": "Max Orb"
          }
        },
        "required": [
          "longitude1",
          "longitude2"
        ],
        "title": "AspectCheckRequest",
        "type": "object"
      },
      "AspectCheckResponse": {
        "additionalProperties": false,
        "description": "The angular relationship between two celestial points, including the closest aspect and all aspects formed within the specified orb.",
        "properties": {
          "angular_separation": {
            "description": "Angular separation between points in degrees (0-180)",
            "title": "Angular Separation",
            "type": "number"
          },
          "aspects": {
            "description": "All aspects found within orb tolerance",
            "items": {
              "$ref": "#/components/schemas/AspectResponse"
            },
            "title": "Aspects",
            "type": "array"
          },
          "closest_aspect": {
            "$ref": "#/components/schemas/AspectResponse",
            "description": "Closest aspect by orb (if any aspects found)"
          },
          "success": {
            "default": true,
            "description": "Calculation success status",
            "title": "Success",
            "type": "boolean"
          }
        },
        "required": [
          "angular_separation"
        ],
        "title": "AspectCheckResponse",
        "type": "object"
      },
      "AspectConfig": {
        "additionalProperties": false,
        "description": "Configuration for aspect calculations in chart requests.",
        "example": {
          "include_midpoints": false,
          "include_patterns": false,
          "orb_system": "standard",
          "preset": "traditional_7",
          "scope": "planets_and_angles"
        },
        "properties": {
          "applying_only": {
            "default": false,
            "description": "Include only applying aspects",
            "title": "Applying Only",
            "type": "boolean"
          },
          "body_list": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              }
            ],
            "description": "Custom body list (required if scope='custom')",
            "title": "Body List"
          },
          "harmonic_numbers": {
            "anyOf": [
              {
                "items": {
                  "type": "integer"
                },
                "type": "array"
              }
            ],
            "description": "Harmonic numbers to calculate (e.g., [4, 7, 9]). Defaults to [4, 5, 7, 9] if include_harmonics=true",
            "title": "Harmonic Numbers"
          },
          "include_harmonics": {
            "default": false,
            "description": "Include harmonic chart positions",
            "title": "Include Harmonics",
            "type": "boolean"
          },
          "include_midpoints": {
            "default": false,
            "description": "Calculate and include midpoints",
            "title": "Include Midpoints",
            "type": "boolean"
          },
          "include_patterns": {
            "default": false,
            "description": "Detect and include aspect patterns",
            "title": "Include Patterns",
            "type": "boolean"
          },
          "major_only": {
            "default": false,
            "description": "Include only major aspects (overrides preset)",
            "title": "Major Only",
            "type": "boolean"
          },
          "maximum_orb": {
            "anyOf": [
              {
                "maximum": 15,
                "minimum": 0,
                "type": "number"
              }
            ],
            "description": "Maximum orb for aspect inclusion (degrees)",
            "title": "Maximum Orb"
          },
          "minimum_orb": {
            "anyOf": [
              {
                "maximum": 15,
                "minimum": 0,
                "type": "number"
              }
            ],
            "description": "Minimum orb for aspect inclusion (degrees)",
            "title": "Minimum Orb"
          },
          "orb_system": {
            "allOf": [
              {
                "$ref": "#/components/schemas/OrbSystemEnum"
              }
            ],
            "default": "standard",
            "description": "Orb system preset to use"
          },
          "orb_table": {
            "anyOf": [
              {
                "additionalProperties": {
                  "type": "number"
                },
                "type": "object"
              }
            ],
            "description": "Custom orb table (required if orb_system='custom'). Keys are normalized aspect names (e.g., 'conjunction', 'square')",
            "title": "Orb Table"
          },
          "preset": {
            "allOf": [
              {
                "$ref": "#/components/schemas/AspectPresetEnum"
              }
            ],
            "default": "traditional_7",
            "description": "Predefined aspect set to calculate"
          },
          "scope": {
            "allOf": [
              {
                "$ref": "#/components/schemas/AspectScopeEnum"
              }
            ],
            "default": "planets_and_angles",
            "description": "Which bodies to include in aspect calculations"
          }
        },
        "title": "AspectConfig",
        "type": "object"
      },
      "AspectMatrixResponse": {
        "additionalProperties": true,
        "description": "Complete aspect matrix for all planetary pairs.\n\nRelaxed to allow additional performance fields provided by enhanced calculator.",
        "properties": {
          "aspect_counts": {
            "anyOf": [
              {
                "additionalProperties": {
                  "type": "integer"
                },
                "type": "object"
              }
            ],
            "description": "Count by aspect type",
            "title": "Aspect Counts"
          },
          "aspects": {
            "anyOf": [
              {
                "items": {
                  "$ref": "#/components/schemas/AspectResponse"
                },
                "type": "array"
              }
            ],
            "description": "All aspects found",
            "title": "Aspects"
          },
          "calculation_time_ms": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "description": "Calculation time in ms",
            "title": "Calculation Time Ms"
          },
          "major_aspects": {
            "anyOf": [
              {
                "type": "integer"
              }
            ],
            "description": "Major aspect count",
            "title": "Major Aspects"
          },
          "matrix": {
            "anyOf": [
              {
                "additionalProperties": {
                  "additionalProperties": {
                    "$ref": "#/components/schemas/AspectResponse"
                  },
                  "type": "object"
                },
                "type": "object"
              }
            ],
            "description": "Matrix format of aspects",
            "title": "Matrix"
          },
          "minor_aspects": {
            "anyOf": [
              {
                "type": "integer"
              }
            ],
            "description": "Minor aspect count",
            "title": "Minor Aspects"
          },
          "orb_config_used": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Orb configuration used",
            "title": "Orb Config Used"
          },
          "patterns": {
            "anyOf": [
              {
                "items": {
                  "$ref": "#/components/schemas/AspectPattern"
                },
                "type": "array"
              }
            ],
            "description": "Identified aspect patterns",
            "title": "Patterns"
          },
          "total_aspects": {
            "anyOf": [
              {
                "type": "integer"
              }
            ],
            "description": "Total number of aspects",
            "title": "Total Aspects"
          }
        },
        "title": "AspectMatrixResponse",
        "type": "object"
      },
      "AspectPattern": {
        "additionalProperties": false,
        "description": "Identified aspect pattern.",
        "properties": {
          "aspects": {
            "description": "Aspects forming the pattern",
            "items": {
              "type": "string"
            },
            "title": "Aspects",
            "type": "array"
          },
          "complete": {
            "description": "Is pattern complete",
            "title": "Complete",
            "type": "boolean"
          },
          "orb_tolerance": {
            "description": "Maximum orb in pattern",
            "title": "Orb Tolerance",
            "type": "number"
          },
          "pattern_type": {
            "description": "Pattern type (T-square, Grand Trine, etc.)",
            "title": "Pattern Type",
            "type": "string"
          },
          "planets": {
            "description": "Planets involved",
            "items": {
              "type": "string"
            },
            "title": "Planets",
            "type": "array"
          },
          "strength": {
            "description": "Pattern strength (0-1)",
            "title": "Strength",
            "type": "number"
          }
        },
        "required": [
          "pattern_type",
          "planets",
          "aspects",
          "strength",
          "orb_tolerance",
          "complete"
        ],
        "title": "AspectPattern",
        "type": "object"
      },
      "AspectPresetEnum": {
        "description": "Predefined aspect configuration presets.",
        "enum": [
          "traditional_5",
          "traditional_7",
          "modern_9",
          "all",
          "major_only",
          "minor_only"
        ],
        "title": "AspectPresetEnum",
        "type": "string"
      },
      "AspectResponse": {
        "additionalProperties": true,
        "description": "Individual aspect information (legacy format).",
        "properties": {
          "angle": {
            "description": "Aspect angle in degrees",
            "title": "Angle",
            "type": "number"
          },
          "applying": {
            "description": "Is aspect applying",
            "title": "Applying",
            "type": "boolean"
          },
          "aspect": {
            "description": "Aspect name",
            "title": "Aspect",
            "type": "string"
          },
          "object1": {
            "description": "First object name",
            "title": "Object1",
            "type": "string"
          },
          "object2": {
            "description": "Second object name",
            "title": "Object2",
            "type": "string"
          },
          "orb": {
            "description": "Orb in degrees",
            "title": "Orb",
            "type": "number"
          }
        },
        "required": [
          "object1",
          "object2",
          "aspect",
          "angle",
          "orb",
          "applying"
        ],
        "title": "AspectResponse",
        "type": "object"
      },
      "AspectScopeEnum": {
        "description": "Aspect calculation scope - which bodies to consider.",
        "enum": [
          "planets_only",
          "planets_and_angles",
          "planets_and_nodes",
          "extended",
          "complete",
          "custom"
        ],
        "title": "AspectScopeEnum",
        "type": "string"
      },
      "AspectStrengthFilterEnum": {
        "description": "Filter events by strength/importance.\n\nMaps to orb tolerance: strong (tight), moderate (standard), weak (loose).",
        "enum": [
          "strong",
          "moderate",
          "weak",
          "all"
        ],
        "title": "AspectStrengthFilterEnum",
        "type": "string"
      },
      "AsteroidGroupEnum": {
        "description": "Predefined categories of asteroids and minor planets.",
        "enum": [
          "major",
          "centaur",
          "tno",
          "muse",
          "main_belt"
        ],
        "title": "AsteroidGroupEnum",
        "type": "string"
      },
      "AuthSetSessionResponse": {
        "properties": {
          "entitlement": {
            "$ref": "#/components/schemas/EntitlementPayload"
          },
          "ok": {
            "default": true,
            "description": "True when the session payload was resolved.",
            "title": "Ok",
            "type": "boolean"
          }
        },
        "required": [
          "entitlement"
        ],
        "title": "AuthSetSessionResponse",
        "type": "object"
      },
      "AyanamsaEnum": {
        "description": "Supported sidereal ayanamsa options.",
        "enum": [
          "lahiri",
          "fagan_bradley",
          "krishnamurti"
        ],
        "title": "AyanamsaEnum",
        "type": "string"
      },
      "BaZiAnnualPillarRequest": {
        "properties": {
          "year": {
            "description": "Gregorian year for the Liu Nian calculation.",
            "maximum": 9999,
            "minimum": 1,
            "type": "integer"
          }
        },
        "required": [
          "year"
        ],
        "title": "BaZiAnnualPillarRequest",
        "type": "object"
      },
      "BaZiAnnualPillarResponse": {
        "properties": {
          "animal": {
            "type": "string"
          },
          "branch": {
            "type": "string"
          },
          "branch_chinese": {
            "type": "string"
          },
          "element": {
            "type": "string"
          },
          "nayin": {
            "properties": {
              "element": {
                "type": "string"
              },
              "image": {
                "type": "string"
              },
              "image_chinese": {
                "type": "string"
              }
            },
            "type": "object"
          },
          "polarity": {
            "enum": [
              "Yang",
              "Yin"
            ],
            "type": "string"
          },
          "sexagenary_index": {
            "maximum": 59,
            "minimum": 0,
            "type": "integer"
          },
          "stem": {
            "type": "string"
          },
          "stem_chinese": {
            "type": "string"
          },
          "success": {
            "default": true,
            "type": "boolean"
          },
          "year": {
            "type": "integer"
          }
        },
        "required": [
          "year",
          "stem",
          "stem_chinese",
          "branch",
          "branch_chinese",
          "animal",
          "element",
          "polarity",
          "sexagenary_index",
          "nayin"
        ],
        "title": "BaZiAnnualPillarResponse",
        "type": "object"
      },
      "BaZiCompatibilityFactor": {
        "properties": {
          "description": {
            "type": "string"
          },
          "pillar_a": {
            "type": "string"
          },
          "pillar_b": {
            "type": "string"
          },
          "score_delta": {
            "type": "integer"
          },
          "type": {
            "enum": [
              "six_harmony",
              "three_harmony",
              "six_clash",
              "six_harm",
              "element_clash",
              "element_harmony"
            ],
            "type": "string"
          }
        },
        "required": [
          "type",
          "description",
          "score_delta",
          "pillar_a",
          "pillar_b"
        ],
        "title": "BaZiCompatibilityFactor",
        "type": "object"
      },
      "BaZiCompatibilityRequest": {
        "properties": {
          "chart_a": {
            "$ref": "#/components/schemas/BaZiRequest",
            "description": "First BaZi chart (person A)."
          },
          "chart_b": {
            "$ref": "#/components/schemas/BaZiRequest",
            "description": "Second BaZi chart (person B)."
          }
        },
        "required": [
          "chart_a",
          "chart_b"
        ],
        "title": "BaZiCompatibilityRequest",
        "type": "object"
      },
      "BaZiCompatibilityResponse": {
        "properties": {
          "assessment": {
            "enum": [
              "excellent",
              "good",
              "moderate",
              "challenging"
            ],
            "type": "string"
          },
          "factors": {
            "items": {
              "$ref": "#/components/schemas/BaZiCompatibilityFactor"
            },
            "type": "array"
          },
          "score": {
            "maximum": 100,
            "minimum": 0,
            "type": "integer"
          },
          "success": {
            "default": true,
            "type": "boolean"
          },
          "summary_note": {
            "type": "string"
          }
        },
        "required": [
          "score",
          "assessment",
          "summary_note",
          "factors"
        ],
        "title": "BaZiCompatibilityResponse",
        "type": "object"
      },
      "BaZiElementBalanceResponse": {
        "properties": {
          "day_master_element": {
            "type": "string"
          },
          "day_master_strength": {
            "enum": [
              "strong",
              "weak",
              "neutral"
            ],
            "type": "string"
          },
          "elements": {
            "items": {
              "$ref": "#/components/schemas/BaZiElementScore"
            },
            "maxItems": 5,
            "minItems": 5,
            "type": "array"
          },
          "success": {
            "default": true,
            "type": "boolean"
          },
          "total_score": {
            "type": "number"
          },
          "yong_shen_element": {
            "description": "Recommended favourable element (用神 Yòng Shén).",
            "type": "string"
          }
        },
        "required": [
          "elements",
          "total_score",
          "day_master_element",
          "day_master_strength",
          "yong_shen_element"
        ],
        "title": "BaZiElementBalanceResponse",
        "type": "object"
      },
      "BaZiElementScore": {
        "properties": {
          "element": {
            "enum": [
              "Wood",
              "Fire",
              "Earth",
              "Metal",
              "Water"
            ],
            "type": "string"
          },
          "percentage": {
            "format": "double",
            "type": "number"
          },
          "score": {
            "format": "double",
            "type": "number"
          },
          "sources": {
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "required": [
          "element",
          "score",
          "percentage",
          "sources"
        ],
        "title": "BaZiElementScore",
        "type": "object"
      },
      "BaZiHiddenStemEntry": {
        "properties": {
          "chinese": {
            "description": "Chinese character, e.g. '癸'",
            "type": "string"
          },
          "element": {
            "enum": [
              "Wood",
              "Fire",
              "Earth",
              "Metal",
              "Water"
            ],
            "type": "string"
          },
          "name": {
            "description": "Romanised stem name, e.g. 'Gui'",
            "type": "string"
          },
          "polarity": {
            "enum": [
              "Yang",
              "Yin"
            ],
            "type": "string"
          },
          "strength": {
            "enum": [
              "main",
              "secondary",
              "residual"
            ],
            "type": "string"
          },
          "weight": {
            "format": "double",
            "type": "number"
          }
        },
        "required": [
          "name",
          "chinese",
          "element",
          "polarity",
          "strength",
          "weight"
        ],
        "title": "BaZiHiddenStemEntry",
        "type": "object"
      },
      "BaZiLuckPillar": {
        "properties": {
          "branch": {
            "type": "string"
          },
          "branch_chinese": {
            "type": "string"
          },
          "element": {
            "enum": [
              "Wood",
              "Fire",
              "Earth",
              "Metal",
              "Water"
            ],
            "type": "string"
          },
          "end_age": {
            "format": "double",
            "type": "number"
          },
          "number": {
            "description": "Ordinal position (1 = first luck pillar)",
            "type": "integer"
          },
          "start_age": {
            "format": "double",
            "type": "number"
          },
          "stem": {
            "type": "string"
          },
          "stem_chinese": {
            "type": "string"
          }
        },
        "required": [
          "number",
          "start_age",
          "end_age",
          "stem",
          "stem_chinese",
          "branch",
          "branch_chinese",
          "element"
        ],
        "title": "BaZiLuckPillar",
        "type": "object"
      },
      "BaZiLuckPillarsRequest": {
        "description": "Request for Da Yun (大运) luck pillar calculation. Requires either year/month/day or datetime, plus gender.",
        "properties": {
          "datetime": {
            "description": "ISO 8601 alternative to year/month/day/hour.",
            "format": "date-time",
            "type": "string"
          },
          "day": {
            "maximum": 31,
            "minimum": 1,
            "type": "integer"
          },
          "format": {
            "description": "Response format: json | llm.",
            "enum": [
              "json",
              "llm"
            ],
            "type": "string"
          },
          "gender": {
            "description": "Required: determines direction (forward/backward) of Da Yun progression.",
            "enum": [
              "male",
              "female"
            ],
            "type": "string"
          },
          "hour": {
            "default": 12,
            "maximum": 23,
            "minimum": 0,
            "type": "integer"
          },
          "month": {
            "maximum": 12,
            "minimum": 1,
            "type": "integer"
          },
          "year": {
            "description": "Birth year (Gregorian)",
            "type": "integer"
          }
        },
        "required": [
          "gender"
        ],
        "title": "BaZiLuckPillarsRequest",
        "type": "object"
      },
      "BaZiLuckPillarsResponse": {
        "properties": {
          "calculation_metadata": {
            "additionalProperties": true,
            "description": "Optional calculation provenance metadata (timing, engine flags, ayanamsa, etc.). Free-form; present when the handler attaches it.",
            "type": "object"
          },
          "direction": {
            "enum": [
              "forward",
              "backward"
            ],
            "type": "string"
          },
          "direction_reason": {
            "type": "string"
          },
          "pillars": {
            "items": {
              "$ref": "#/components/schemas/BaZiLuckPillar"
            },
            "maxItems": 8,
            "minItems": 8,
            "type": "array"
          },
          "starting_age": {
            "format": "double",
            "type": "number"
          },
          "success": {
            "default": true,
            "type": "boolean"
          }
        },
        "required": [
          "starting_age",
          "direction",
          "direction_reason",
          "pillars"
        ],
        "title": "BaZiLuckPillarsResponse",
        "type": "object"
      },
      "BaZiPillarTenGods": {
        "properties": {
          "hidden_ten_gods": {
            "items": {
              "properties": {
                "hidden_stem": {
                  "$ref": "#/components/schemas/BaZiHiddenStemEntry"
                },
                "ten_god": {
                  "$ref": "#/components/schemas/BaZiTenGodEntry"
                }
              },
              "required": [
                "hidden_stem",
                "ten_god"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "pillar": {
            "enum": [
              "year",
              "month",
              "day",
              "hour"
            ],
            "type": "string"
          },
          "visible_ten_god": {
            "$ref": "#/components/schemas/BaZiTenGodEntry",
            "description": "Ten God of the visible Heavenly Stem (null for the Day pillar — the Day Master has no God relative to itself)."
          }
        },
        "required": [
          "pillar",
          "hidden_ten_gods"
        ],
        "title": "BaZiPillarTenGods",
        "type": "object"
      },
      "BaZiRequest": {
        "description": "Request body for a BaZi (Four Pillars) calculation.",
        "properties": {
          "day": {
            "description": "Birth day of month (1–31).",
            "example": 15,
            "maximum": 31,
            "minimum": 1,
            "title": "Day",
            "type": "integer"
          },
          "format": {
            "description": "Response format: json | llm.",
            "enum": [
              "json",
              "llm"
            ],
            "type": "string"
          },
          "hour": {
            "anyOf": [
              {
                "maximum": 23,
                "minimum": 0,
                "type": "integer"
              }
            ],
            "default": 12,
            "description": "Birth hour (0–23). Defaults to 12 (noon). Chinese hours (shí) are 2-hour blocks, so precision within a 2-hour window is sufficient.",
            "example": 8,
            "title": "Hour"
          },
          "month": {
            "description": "Birth month (1–12).",
            "example": 1,
            "maximum": 12,
            "minimum": 1,
            "title": "Month",
            "type": "integer"
          },
          "year": {
            "description": "Gregorian birth year.",
            "example": 1990,
            "maximum": 9999,
            "minimum": 1,
            "title": "Year",
            "type": "integer"
          }
        },
        "required": [
          "year",
          "month",
          "day"
        ],
        "title": "BaZiRequest",
        "type": "object"
      },
      "BaZiResponse": {
        "description": "Full Four Pillars response.",
        "properties": {
          "day": {
            "$ref": "#/components/schemas/StemBranchPair"
          },
          "day_master": {
            "additionalProperties": {
              "type": "string"
            },
            "description": "The Day Master (日主): the Day Stem's element, representing the self in BaZi interpretation.",
            "title": "Day Master",
            "type": "object"
          },
          "hour": {
            "$ref": "#/components/schemas/StemBranchPair"
          },
          "metadata": {
            "title": "Metadata",
            "type": "object"
          },
          "month": {
            "$ref": "#/components/schemas/StemBranchPair"
          },
          "success": {
            "default": true,
            "title": "Success",
            "type": "boolean"
          },
          "year": {
            "$ref": "#/components/schemas/StemBranchPair"
          }
        },
        "required": [
          "year",
          "month",
          "day",
          "hour",
          "day_master",
          "metadata"
        ],
        "title": "BaZiResponse",
        "type": "object"
      },
      "BaZiSolarTermEntry": {
        "properties": {
          "chinese": {
            "type": "string"
          },
          "datetime_utc": {
            "format": "date-time",
            "type": "string"
          },
          "julian_day": {
            "format": "double",
            "type": "number"
          },
          "kind": {
            "description": "'jie' = month-starting term (used in BaZi month calculation); 'qi' = mid-month term.",
            "enum": [
              "jie",
              "qi"
            ],
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "solar_longitude": {
            "description": "Sun's ecliptic longitude at which this term begins (degrees).",
            "format": "double",
            "type": "number"
          }
        },
        "required": [
          "name",
          "chinese",
          "kind",
          "solar_longitude",
          "datetime_utc",
          "julian_day"
        ],
        "title": "BaZiSolarTermEntry",
        "type": "object"
      },
      "BaZiSolarTermsRequest": {
        "properties": {
          "year": {
            "description": "Gregorian year for which to compute all 24 solar terms.",
            "maximum": 2200,
            "minimum": 1800,
            "type": "integer"
          }
        },
        "required": [
          "year"
        ],
        "title": "BaZiSolarTermsRequest",
        "type": "object"
      },
      "BaZiSolarTermsResponse": {
        "properties": {
          "success": {
            "default": true,
            "type": "boolean"
          },
          "terms": {
            "items": {
              "$ref": "#/components/schemas/BaZiSolarTermEntry"
            },
            "maxItems": 24,
            "minItems": 24,
            "type": "array"
          },
          "year": {
            "type": "integer"
          }
        },
        "required": [
          "year",
          "terms"
        ],
        "title": "BaZiSolarTermsResponse",
        "type": "object"
      },
      "BaZiTenGodEntry": {
        "properties": {
          "category": {
            "enum": [
              "companion",
              "output",
              "wealth",
              "power",
              "resource"
            ],
            "type": "string"
          },
          "chinese": {
            "description": "Chinese characters, e.g. '正官'",
            "type": "string"
          },
          "name": {
            "description": "English name, e.g. 'Direct Officer'",
            "type": "string"
          },
          "pinyin": {
            "type": "string"
          }
        },
        "required": [
          "name",
          "chinese",
          "pinyin",
          "category"
        ],
        "title": "BaZiTenGodEntry",
        "type": "object"
      },
      "BaZiTenGodsResponse": {
        "properties": {
          "calculation_metadata": {
            "additionalProperties": true,
            "description": "Optional calculation provenance metadata (timing, engine flags, ayanamsa, etc.). Free-form; present when the handler attaches it.",
            "type": "object"
          },
          "day_master": {
            "properties": {
              "element": {
                "type": "string"
              },
              "polarity": {
                "type": "string"
              },
              "stem": {
                "type": "string"
              }
            },
            "type": "object"
          },
          "pillars": {
            "items": {
              "$ref": "#/components/schemas/BaZiPillarTenGods"
            },
            "maxItems": 4,
            "minItems": 4,
            "type": "array"
          },
          "success": {
            "default": true,
            "type": "boolean"
          }
        },
        "required": [
          "day_master",
          "pillars"
        ],
        "title": "BaZiTenGodsResponse",
        "type": "object"
      },
      "BesselianElements": {
        "properties": {
          "X": {
            "description": "Shadow axis x in fundamental plane",
            "title": "X",
            "type": "number"
          },
          "Xdot": {
            "default": 0,
            "title": "Xdot",
            "type": "number"
          },
          "Y": {
            "description": "Shadow axis y in fundamental plane",
            "title": "Y",
            "type": "number"
          },
          "Ydot": {
            "default": 0,
            "title": "Ydot",
            "type": "number"
          },
          "d": {
            "description": "Declination of shadow axis (degrees)",
            "title": "D",
            "type": "number"
          },
          "ddot": {
            "default": 0,
            "title": "Ddot",
            "type": "number"
          },
          "f1": {
            "description": "Penumbral cone half-angle (radians)",
            "title": "F1",
            "type": "number"
          },
          "f2": {
            "description": "Umbral cone half-angle (radians)",
            "title": "F2",
            "type": "number"
          },
          "l1": {
            "description": "Penumbral shadow radius",
            "title": "L1",
            "type": "number"
          },
          "l2": {
            "description": "Umbral shadow radius",
            "title": "L2",
            "type": "number"
          },
          "mu": {
            "description": "Hour angle of shadow axis (degrees)",
            "title": "Mu",
            "type": "number"
          },
          "mudot": {
            "default": 0,
            "title": "Mudot",
            "type": "number"
          },
          "reference_jd": {
            "format": "double",
            "title": "Reference Jd",
            "type": "number"
          },
          "reference_time_utc": {
            "title": "Reference Time Utc",
            "type": "string"
          }
        },
        "required": [
          "reference_time_utc",
          "reference_jd",
          "X",
          "Y",
          "d",
          "mu",
          "l1",
          "l2",
          "f1",
          "f2"
        ],
        "title": "BesselianElements",
        "type": "object"
      },
      "BesselianElementsResponse": {
        "properties": {
          "elements": {
            "$ref": "#/components/schemas/BesselianElements"
          },
          "meta": {
            "$ref": "#/components/schemas/CalculationMeta"
          }
        },
        "required": [
          "meta",
          "elements"
        ],
        "title": "BesselianElementsResponse",
        "type": "object"
      },
      "BiWheelRequest": {
        "additionalProperties": false,
        "description": "Bi-wheel visualization request. Each subject may carry birth params OR precomputed positions.",
        "properties": {
          "configuration": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ChartConfiguration"
              }
            ],
            "description": "Chart calculation settings (house system, orientation)."
          },
          "subject_a": {
            "allOf": [
              {
                "$ref": "#/components/schemas/WheelSubject"
              }
            ],
            "description": "Inner ring subject."
          },
          "subject_b": {
            "allOf": [
              {
                "$ref": "#/components/schemas/WheelSubject"
              }
            ],
            "description": "Outer ring subject."
          }
        },
        "required": [
          "subject_a",
          "subject_b"
        ],
        "title": "BiWheelRequest",
        "type": "object"
      },
      "BillingInvoiceSummary": {
        "properties": {
          "amount_cents": {
            "title": "Amount Cents",
            "type": "integer"
          },
          "date": {
            "format": "date-time",
            "title": "Date",
            "type": "string"
          },
          "id": {
            "title": "Id",
            "type": "string"
          },
          "pdf_url": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "title": "Pdf Url"
          },
          "status": {
            "title": "Status",
            "type": "string"
          }
        },
        "required": [
          "id",
          "date",
          "amount_cents",
          "status"
        ],
        "title": "BillingInvoiceSummary",
        "type": "object"
      },
      "BillingInvoicesResponse": {
        "properties": {
          "invoices": {
            "items": {
              "$ref": "#/components/schemas/BillingInvoiceSummary"
            },
            "title": "Invoices",
            "type": "array"
          }
        },
        "title": "BillingInvoicesResponse",
        "type": "object"
      },
      "BillingMeResponse": {
        "properties": {
          "billing_state": {
            "anyOf": [
              {
                "enum": [
                  "pending",
                  "active"
                ],
                "type": "string"
              }
            ],
            "description": "Lightweight subscription state signal for post-checkout settle UX.",
            "example": "pending",
            "title": "Billing State"
          },
          "cancel_at_period_end": {
            "anyOf": [
              {
                "type": "boolean"
              }
            ],
            "description": "True if set to cancel at end of period.",
            "title": "Cancel At Period End"
          },
          "canceled_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              }
            ],
            "description": "Cancellation timestamp (UTC) if known.",
            "title": "Canceled At"
          },
          "current_period_end": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              }
            ],
            "description": "Subscription current period end (UTC).",
            "title": "Current Period End"
          },
          "current_period_start": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              }
            ],
            "description": "Subscription current period start (UTC).",
            "title": "Current Period Start"
          },
          "price_id": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Stripe price id associated with current tier.",
            "title": "Price Id"
          },
          "status": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Stripe subscription status (if known).",
            "example": "active",
            "title": "Status"
          },
          "stripe_customer_id": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Stripe customer id (if mapped).",
            "title": "Stripe Customer Id"
          },
          "stripe_subscription_id": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Stripe subscription id (if known).",
            "title": "Stripe Subscription Id"
          },
          "tier": {
            "description": "Effective tier resolved from DB projection.",
            "enum": [
              "anonymous",
              "explorer",
              "developer",
              "pro",
              "scale",
              "service"
            ],
            "title": "Tier",
            "type": "string"
          },
          "user_id": {
            "description": "Supabase Auth user id (JWT sub).",
            "title": "User Id",
            "type": "string"
          }
        },
        "required": [
          "user_id",
          "tier"
        ],
        "title": "BillingMeResponse",
        "type": "object"
      },
      "BillingOveragesResponse": {
        "properties": {
          "currency": {
            "default": "USD",
            "title": "Currency",
            "type": "string"
          },
          "hard_stop_on_cap": {
            "default": true,
            "title": "Hard Stop On Cap",
            "type": "boolean"
          },
          "overage_spend_cap_cents": {
            "anyOf": [
              {
                "type": "integer"
              }
            ],
            "title": "Overage Spend Cap Cents"
          },
          "overages_enabled": {
            "title": "Overages Enabled",
            "type": "boolean"
          }
        },
        "required": [
          "overages_enabled"
        ],
        "title": "BillingOveragesResponse",
        "type": "object"
      },
      "BillingUsageMeResponse": {
        "properties": {
          "billing_period_end": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              }
            ],
            "title": "Billing Period End"
          },
          "billing_period_start": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              }
            ],
            "title": "Billing Period Start"
          },
          "burst_limit": {
            "anyOf": [
              {
                "type": "integer"
              }
            ],
            "title": "Burst Limit"
          },
          "concurrency_limit": {
            "anyOf": [
              {
                "type": "integer"
              }
            ],
            "title": "Concurrency Limit"
          },
          "current_period_end": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              }
            ],
            "title": "Current Period End"
          },
          "current_period_start": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              }
            ],
            "title": "Current Period Start"
          },
          "included_usage_units": {
            "title": "Included Usage Units",
            "type": "integer"
          },
          "limit_state": {
            "default": "ok",
            "enum": [
              "ok",
              "nearing_included",
              "included_exceeded",
              "nearing_cap",
              "cap_reached"
            ],
            "title": "Limit State",
            "type": "string"
          },
          "month": {
            "title": "Month",
            "type": "string"
          },
          "notes": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "title": "Notes"
          },
          "overage_spend_cap_cents": {
            "anyOf": [
              {
                "type": "integer"
              }
            ],
            "title": "Overage Spend Cap Cents"
          },
          "overage_spend_used_cents": {
            "anyOf": [
              {
                "type": "integer"
              }
            ],
            "title": "Overage Spend Used Cents"
          },
          "overage_unit_price_cents_per_1000": {
            "default": 0,
            "title": "Overage Unit Price Cents Per 1000",
            "type": "integer"
          },
          "overages_enabled": {
            "default": false,
            "title": "Overages Enabled",
            "type": "boolean"
          },
          "reset_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              }
            ],
            "title": "Reset At"
          },
          "rpm_limit": {
            "default": 0,
            "title": "Rpm Limit",
            "type": "integer"
          },
          "rpm_remaining": {
            "anyOf": [
              {
                "type": "integer"
              }
            ],
            "title": "Rpm Remaining"
          },
          "tier": {
            "enum": [
              "anonymous",
              "explorer",
              "developer",
              "pro",
              "scale",
              "service"
            ],
            "title": "Tier",
            "type": "string"
          },
          "usage_units_by_category": {
            "additionalProperties": {
              "type": "integer"
            },
            "title": "Usage Units By Category",
            "type": "object"
          },
          "usage_units_used": {
            "title": "Usage Units Used",
            "type": "integer"
          },
          "used_usage_units": {
            "title": "Used Usage Units",
            "type": "integer"
          },
          "user_id": {
            "title": "User Id",
            "type": "string"
          }
        },
        "required": [
          "user_id",
          "tier",
          "month",
          "included_usage_units",
          "usage_units_used",
          "used_usage_units"
        ],
        "title": "BillingUsageMeResponse",
        "type": "object"
      },
      "BirthLocation": {
        "additionalProperties": false,
        "description": "Location context for birth data: coordinates plus timezone.",
        "example": {
          "city": "New York",
          "country": "USA",
          "latitude": {
            "decimal": 40.7128
          },
          "longitude": {
            "decimal": -74.006
          },
          "timezone": {
            "iana_name": "America/New_York"
          }
        },
        "properties": {
          "city": {
            "anyOf": [
              {
                "maxLength": 120,
                "type": "string"
              }
            ],
            "description": "City name",
            "title": "City"
          },
          "country": {
            "anyOf": [
              {
                "maxLength": 120,
                "type": "string"
              }
            ],
            "description": "Country",
            "title": "Country"
          },
          "elevation": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "description": "Elevation in meters",
            "title": "Elevation"
          },
          "latitude": {
            "allOf": [
              {
                "$ref": "#/components/schemas/CoordinateInput"
              }
            ],
            "description": "Latitude coordinate"
          },
          "location_name": {
            "anyOf": [
              {
                "maxLength": 200,
                "type": "string"
              }
            ],
            "description": "Legacy location display name",
            "title": "Location Name"
          },
          "longitude": {
            "allOf": [
              {
                "$ref": "#/components/schemas/CoordinateInput"
              }
            ],
            "description": "Longitude coordinate"
          },
          "region": {
            "anyOf": [
              {
                "maxLength": 120,
                "type": "string"
              }
            ],
            "description": "State/region",
            "title": "Region"
          },
          "timezone": {
            "allOf": [
              {
                "$ref": "#/components/schemas/TimezoneInput"
              }
            ],
            "description": "Timezone information"
          }
        },
        "required": [
          "latitude",
          "longitude",
          "timezone"
        ],
        "title": "BirthLocation",
        "type": "object"
      },
      "CalculationMeta": {
        "properties": {
          "calculation_precision": {
            "default": "sub_kilometer",
            "title": "Calculation Precision",
            "type": "string"
          },
          "delta_t_model": {
            "title": "Delta T Model",
            "type": "string"
          },
          "delta_t_seconds": {
            "title": "Delta T Seconds",
            "type": "number"
          },
          "delta_t_uncertainty": {
            "title": "Delta T Uncertainty",
            "type": "number"
          },
          "ephemeris": {
            "title": "Ephemeris",
            "type": "string"
          },
          "julian_day": {
            "format": "double",
            "title": "Julian Day",
            "type": "number"
          }
        },
        "required": [
          "ephemeris",
          "julian_day",
          "delta_t_seconds",
          "delta_t_model",
          "delta_t_uncertainty"
        ],
        "title": "CalculationMeta",
        "type": "object"
      },
      "CalculationMetadata": {
        "additionalProperties": true,
        "description": "Metadata about chart calculations.\n\nRelaxed to allow minimal fields used by tests while remaining forward-compatible.",
        "properties": {
          "ascendant_on_left": {
            "default": true,
            "description": "When true (default), the Ascendant is placed at the 9 o'clock (West/left) position � matching the convention used by Astro.com, Solar Fire, and all major astrology software. Set to false to use the ecliptic-fixed (Aries-pinned) orientation instead.",
            "nullable": true,
            "title": "Ascendant on Left",
            "type": "boolean"
          },
          "aspect_calculation_time_ms": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "description": "Time spent calculating aspects in milliseconds",
            "title": "Aspect Calculation Time Ms"
          },
          "ayanamsa": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/AyanamsaEnum"
              },
              {
                "type": "string"
              }
            ],
            "description": "Sidereal ayanamsa selection",
            "title": "Ayanamsa"
          },
          "ayanamsa_used": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Deprecated alias for ayanamsa",
            "title": "Ayanamsa Used"
          },
          "cache_hit": {
            "anyOf": [
              {
                "type": "boolean"
              }
            ],
            "description": "Whether the result was served from cache",
            "title": "Cache Hit"
          },
          "calculation_flags": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              }
            ],
            "description": "Computation engine flags used during computation",
            "title": "Calculation Flags"
          },
          "calculation_time": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "description": "Legacy calculation time in seconds",
            "title": "Calculation Time"
          },
          "calculation_time_ms": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "description": "Processing time at the orchestrator layer in milliseconds",
            "title": "Calculation Time Ms"
          },
          "calculation_time_utc": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              }
            ],
            "description": "UTC timestamp when the calculation executed",
            "title": "Calculation Time Utc"
          },
          "coordinate_reference_frame": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Legacy coordinate frame identifier (e.g., geocentric_ecliptic_J2000)",
            "title": "Coordinate Reference Frame"
          },
          "coordinate_system": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/CoordinateSystemEnum"
              },
              {
                "type": "string"
              }
            ],
            "description": "Coordinate system used (geocentric/topocentric)",
            "title": "Coordinate System"
          },
          "delta_t_profile": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/DeltaTProfileEnum"
              },
              {
                "type": "string"
              }
            ],
            "description": "ΔT curve profile applied (Swiss default, Espenak \u0026 Meeus, Morrison \u0026 Stephenson)",
            "title": "Delta T Profile"
          },
          "delta_t_seconds": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "description": "Delta T (TT - UT1) applied during calculation, in seconds",
            "title": "Delta T Seconds"
          },
          "delta_t_source": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/DeltaTSourceEnum"
              },
              {
                "type": "string"
              }
            ],
            "description": "Source of Delta T values (computation engine, IERS, approximation)",
            "title": "Delta T Source"
          },
          "derived_from": {
            "anyOf": [
              {
                "items": {
                  "type": "object"
                },
                "type": "array"
              }
            ],
            "description": "Minimal provenance descriptors for the source subjects used to derive this chart. Typically includes name + UTC datetime + lat/lon, and may include roles.",
            "title": "Derived From"
          },
          "ephemeris_path": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Filesystem path(s) to the ephemeris files",
            "title": "Ephemeris Path"
          },
          "ephemeris_source": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Primary ephemeris source (e.g., SuperNOVAS / Calceph)",
            "title": "Ephemeris Source"
          },
          "ephemeris_version": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Version of the ephemeris data files",
            "title": "Ephemeris Version"
          },
          "features_denied": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              }
            ],
            "description": "Optional list of feature flags that were requested but not included in the response due to subscription tier gating.",
            "example": [
              "fixed_stars",
              "hermetic_lots",
              "midpoints"
            ],
            "title": "Features Denied"
          },
          "features_included": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              }
            ],
            "description": "Feature flags present in the response",
            "title": "Features Included"
          },
          "fixed_star_catalog": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/FixedStarCatalogEnum"
              },
              {
                "type": "string"
              }
            ],
            "description": "Fixed star catalog or subset identifier",
            "title": "Fixed Star Catalog"
          },
          "house_system": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/HouseSystemEnum"
              },
              {
                "type": "string"
              }
            ],
            "description": "House system actually used during calculation",
            "title": "House System"
          },
          "house_system_used": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Deprecated alias for house_system",
            "title": "House System Used"
          },
          "include_fixed_stars": {
            "anyOf": [
              {
                "type": "boolean"
              }
            ],
            "description": "Whether fixed stars were included",
            "title": "Include Fixed Stars"
          },
          "julian_day": {
            "anyOf": [
              {
                "format": "double",
                "type": "number"
              }
            ],
            "description": "Julian Day Number representing the calculation instant",
            "title": "Julian Day"
          },
          "missing_objects": {
            "anyOf": [
              {
                "additionalProperties": {
                  "items": {
                    "type": "object"
                  },
                  "type": "array"
                },
                "type": "object"
              }
            ],
            "description": "Objects that could not be calculated along with reasons",
            "title": "Missing Objects"
          },
          "node_source": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/NodeSourceEnum"
              },
              {
                "type": "string"
              }
            ],
            "description": "Lunar node/apsides mode requested (true osculating, mean, apsides)",
            "title": "Node Source"
          },
          "object_set": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ObjectSetEnum"
              },
              {
                "type": "string"
              }
            ],
            "description": "Named object set or preset powering the calculation",
            "title": "Object Set"
          },
          "orb_system_used": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Aspect orb system applied",
            "title": "Orb System Used"
          },
          "precision_level": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Legacy precision descriptor",
            "title": "Precision Level"
          },
          "precision_summary": {
            "$ref": "#/components/schemas/PrecisionSummary",
            "description": "Structured precision summary aligned with validation results"
          },
          "processing_time_ms": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "description": "End-to-end processing time in milliseconds",
            "title": "Processing Time Ms"
          },
          "sidereal_time": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "description": "Local sidereal time in hours",
            "title": "Sidereal Time"
          },
          "swiss_ephemeris_version": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Legacy alias for ephemeris_version",
            "title": "Ephemeris Engine Version"
          },
          "technique_id": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "High-level technique identifier (e.g., natal, synastry, composite, overlay)",
            "example": "natal",
            "title": "Technique Id"
          },
          "technique_label": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Human-readable technique label",
            "example": "Composite (Davison)",
            "title": "Technique Label"
          },
          "technique_method": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Method name within a technique (e.g., davidson, midpoint)",
            "example": "davidson",
            "title": "Technique Method"
          },
          "technique_version": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Technique implementation version (for future-proofing)",
            "example": "v1",
            "title": "Technique Version"
          },
          "time_scale": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/TimeScaleEnum"
              },
              {
                "type": "string"
              }
            ],
            "description": "Time scale used for internal calculations (UTC, TT, TDB)",
            "title": "Time Scale"
          },
          "validation_profile": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ValidationProfileEnum"
              },
              {
                "type": "string"
              }
            ],
            "description": "Validation profile describing accuracy/performance trade-offs",
            "title": "Validation Profile"
          },
          "zodiac_type": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ZodiacTypeEnum"
              },
              {
                "type": "string"
              }
            ],
            "description": "Zodiac framework applied (tropical/sidereal)",
            "title": "Zodiac Type"
          }
        },
        "title": "CalculationMetadata",
        "type": "object"
      },
      "CatalogBodiesResponse": {
        "additionalProperties": false,
        "description": "Response with celestial bodies catalog.",
        "properties": {
          "bodies": {
            "description": "Catalog entries",
            "items": {
              "$ref": "#/components/schemas/CatalogBodyItem"
            },
            "title": "Bodies",
            "type": "array"
          },
          "calculation_metadata": {
            "$ref": "#/components/schemas/CalculationMetadata",
            "description": "Canonical calculation metadata describing the catalog source"
          },
          "calculation_support": {
            "additionalProperties": {
              "type": "integer"
            },
            "description": "Calculation availability",
            "title": "Calculation Support",
            "type": "object"
          },
          "catalog_version": {
            "description": "Catalog version",
            "title": "Catalog Version",
            "type": "string"
          },
          "categories": {
            "additionalProperties": {
              "type": "integer"
            },
            "description": "Count by category",
            "title": "Categories",
            "type": "object"
          },
          "filters_applied": {
            "description": "Applied filters",
            "title": "Filters Applied",
            "type": "object"
          },
          "last_updated": {
            "description": "Last update timestamp",
            "format": "date-time",
            "title": "Last Updated",
            "type": "string"
          },
          "total_count": {
            "description": "Total number of bodies",
            "title": "Total Count",
            "type": "integer"
          }
        },
        "required": [
          "bodies",
          "total_count",
          "filters_applied",
          "categories",
          "calculation_support",
          "catalog_version",
          "last_updated"
        ],
        "title": "CatalogBodiesResponse",
        "type": "object"
      },
      "CatalogBodyItem": {
        "additionalProperties": false,
        "description": "Individual celestial body catalog entry.",
        "properties": {
          "aliases": {
            "description": "Alternative names",
            "items": {
              "type": "string"
            },
            "title": "Aliases",
            "type": "array"
          },
          "average_distance_au": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "description": "Average distance from Sun",
            "title": "Average Distance Au"
          },
          "calculation_accuracy": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Calculation accuracy level",
            "title": "Calculation Accuracy"
          },
          "category": {
            "description": "Body category (planet, asteroid, etc.)",
            "title": "Category",
            "type": "string"
          },
          "diameter_km": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "description": "Diameter in kilometers",
            "title": "Diameter Km"
          },
          "discoverer": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Discoverer name",
            "title": "Discoverer"
          },
          "discovery_date": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              }
            ],
            "description": "Discovery date",
            "title": "Discovery Date"
          },
          "ephemeris_available": {
            "description": "Can be calculated",
            "title": "Ephemeris Available",
            "type": "boolean"
          },
          "id": {
            "description": "Canonical identifier for the body (stable). Typically lowercase/underscore, aligned with interpretation/feature-id conventions (e.g., 'sun', 'north_node_mean').",
            "title": "Id",
            "type": "string"
          },
          "keywords": {
            "description": "Astrological keywords",
            "items": {
              "type": "string"
            },
            "title": "Keywords",
            "type": "array"
          },
          "magnitude": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "description": "Apparent magnitude",
            "title": "Magnitude"
          },
          "mass_kg": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "description": "Mass in kilograms",
            "title": "Mass Kg"
          },
          "mythology": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Mythological associations",
            "title": "Mythology"
          },
          "name": {
            "description": "Body name",
            "title": "Name",
            "type": "string"
          },
          "orbital_period_days": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "description": "Orbital period",
            "title": "Orbital Period Days"
          },
          "subcategory": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Subcategory",
            "title": "Subcategory"
          },
          "swiss_ephemeris_id": {
            "anyOf": [
              {
                "type": "integer"
              }
            ],
            "description": "Optional SE-compatible numeric id when applicable (e.g., 0=Sun). Use this for endpoints that accept numeric planet ids.",
            "title": "SE-compatible Body Id"
          },
          "symbol": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Astrological symbol",
            "title": "Symbol"
          },
          "traditional_rulership": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Traditional sign rulership",
            "title": "Traditional Rulership"
          }
        },
        "required": [
          "id",
          "name",
          "category",
          "ephemeris_available"
        ],
        "title": "CatalogBodyItem",
        "type": "object"
      },
      "CatalogFixedStarGroupItem": {
        "additionalProperties": false,
        "description": "Single fixed star group descriptor.",
        "properties": {
          "description": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Short description",
            "title": "Description"
          },
          "id": {
            "description": "Stable group identifier (e.g., 'royal_stars')",
            "title": "Id",
            "type": "string"
          },
          "name": {
            "description": "Human-friendly name",
            "title": "Name",
            "type": "string"
          },
          "star_count": {
            "description": "Number of stars in the group",
            "title": "Star Count",
            "type": "integer"
          }
        },
        "required": [
          "id",
          "name",
          "star_count"
        ],
        "title": "CatalogFixedStarGroupItem",
        "type": "object"
      },
      "CatalogFixedStarGroupsResponse": {
        "additionalProperties": false,
        "description": "Response with available fixed star group identifiers.",
        "properties": {
          "calculation_metadata": {
            "$ref": "#/components/schemas/CalculationMetadata",
            "description": "Canonical calculation metadata describing the catalog source"
          },
          "catalog_version": {
            "description": "Catalog version",
            "title": "Catalog Version",
            "type": "string"
          },
          "groups": {
            "description": "Available groups",
            "items": {
              "$ref": "#/components/schemas/CatalogFixedStarGroupItem"
            },
            "title": "Groups",
            "type": "array"
          },
          "last_updated": {
            "description": "Last update timestamp",
            "format": "date-time",
            "title": "Last Updated",
            "type": "string"
          },
          "total_count": {
            "description": "Total group count",
            "title": "Total Count",
            "type": "integer"
          }
        },
        "required": [
          "groups",
          "total_count",
          "catalog_version",
          "last_updated"
        ],
        "title": "CatalogFixedStarGroupsResponse",
        "type": "object"
      },
      "CatalogFixedStarItem": {
        "additionalProperties": false,
        "description": "Single fixed star catalog entry.",
        "properties": {
          "constellation": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Constellation",
            "title": "Constellation"
          },
          "feature_id": {
            "description": "Interpretation feature_id (e.g., 'fixedstar_regulus')",
            "title": "Feature Id",
            "type": "string"
          },
          "id": {
            "description": "Canonical fixed star id (e.g., 'regulus', 'deneb_adige')",
            "title": "Id",
            "type": "string"
          },
          "magnitude": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "description": "Visual magnitude",
            "title": "Magnitude"
          },
          "name": {
            "description": "Display name (catalog/fallback name)",
            "title": "Name",
            "type": "string"
          },
          "traditional_name": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Traditional/alternative name",
            "title": "Traditional Name"
          }
        },
        "required": [
          "id",
          "name",
          "feature_id"
        ],
        "title": "CatalogFixedStarItem",
        "type": "object"
      },
      "CatalogFixedStarsResponse": {
        "additionalProperties": false,
        "description": "Paginated response for fixed stars catalog.",
        "properties": {
          "calculation_metadata": {
            "$ref": "#/components/schemas/CalculationMetadata",
            "description": "Canonical calculation metadata describing the catalog source"
          },
          "catalog_version": {
            "description": "Catalog version",
            "title": "Catalog Version",
            "type": "string"
          },
          "last_updated": {
            "description": "Last update timestamp",
            "format": "date-time",
            "title": "Last Updated",
            "type": "string"
          },
          "limit": {
            "description": "Page size",
            "title": "Limit",
            "type": "integer"
          },
          "offset": {
            "description": "Offset into the full list",
            "title": "Offset",
            "type": "integer"
          },
          "stars": {
            "description": "Fixed star catalog entries",
            "items": {
              "$ref": "#/components/schemas/CatalogFixedStarItem"
            },
            "title": "Stars",
            "type": "array"
          },
          "total_count": {
            "description": "Total number of stars available",
            "title": "Total Count",
            "type": "integer"
          }
        },
        "required": [
          "stars",
          "total_count",
          "limit",
          "offset",
          "catalog_version",
          "last_updated"
        ],
        "title": "CatalogFixedStarsResponse",
        "type": "object"
      },
      "ChartConfiguration": {
        "additionalProperties": false,
        "description": "Legacy configuration model. New integrations should use NatalConfig with object_set and node_source instead of include_* booleans.",
        "example": {
          "house_system": "P",
          "sidereal": false
        },
        "properties": {
          "ascendant_on_left": {
            "default": true,
            "description": "When true (default), the Ascendant is placed at the 9 o'clock (West/left) position � matching the convention used by Astro.com, Solar Fire, and all major astrology software. Set to false to use the ecliptic-fixed (Aries-pinned) orientation instead.",
            "title": "Ascendant on Left",
            "type": "boolean"
          },
          "aspect_orbs": {
            "anyOf": [
              {
                "additionalProperties": {
                  "type": "number"
                },
                "type": "object"
              }
            ],
            "description": "Custom aspect orbs in degrees",
            "title": "Aspect Orbs"
          },
          "ayanamsa": {
            "anyOf": [
              {
                "maxLength": 64,
                "type": "string"
              }
            ],
            "description": "Ayanamsa for sidereal calculations",
            "title": "Ayanamsa"
          },
          "calculation_flags": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              }
            ],
            "description": "Computation engine calculation flags",
            "title": "Calculation Flags"
          },
          "house_system": {
            "allOf": [
              {
                "$ref": "#/components/schemas/HouseSystemEnum"
              }
            ],
            "default": "P",
            "description": "House system to use for calculations"
          },
          "include_asteroids": {
            "default": false,
            "description": "Include main asteroids",
            "title": "Include Asteroids",
            "type": "boolean"
          },
          "include_chiron": {
            "default": true,
            "description": "Include Chiron in calculations",
            "title": "Include Chiron",
            "type": "boolean"
          },
          "include_lilith": {
            "default": false,
            "description": "Include Black Moon Lilith",
            "title": "Include Lilith",
            "type": "boolean"
          },
          "include_nodes": {
            "default": true,
            "description": "Include lunar nodes (Rahu/Ketu)",
            "title": "Include Nodes",
            "type": "boolean"
          },
          "sidereal": {
            "default": false,
            "description": "Use sidereal zodiac",
            "title": "Sidereal",
            "type": "boolean"
          }
        },
        "title": "ChartConfiguration",
        "type": "object"
      },
      "ChartWheelRequest": {
        "additionalProperties": false,
        "description": "Chart-wheel visualization request. The subject may carry birth params OR precomputed positions.",
        "properties": {
          "configuration": {
            "allOf": [
              {
                "$ref": "#/components/schemas/NatalConfig"
              }
            ],
            "description": "Engine-referenced natal configuration (house system, orientation)."
          },
          "subject": {
            "allOf": [
              {
                "$ref": "#/components/schemas/WheelSubject"
              }
            ],
            "description": "Chart subject."
          }
        },
        "required": [
          "subject"
        ],
        "title": "ChartWheelRequest",
        "type": "object"
      },
      "CompositeHeatmapRequestPayload": {
        "properties": {
          "resolution": {
            "description": "Grid resolution step in degrees (e.g., 2 for 2x2 deg grid). Default is 2.",
            "type": "number"
          },
          "subjects": {
            "description": "Array of exactly two subjects for the composite chart calculation.",
            "items": {
              "properties": {
                "epoch": {
                  "description": "ISO-8601 birth date/time",
                  "type": "string"
                },
                "jd": {
                  "description": "Julian Day",
                  "type": "number"
                }
              },
              "required": [
                "epoch"
              ],
              "type": "object"
            },
            "maxItems": 2,
            "minItems": 2,
            "type": "array"
          },
          "theme": {
            "description": "The objective/theme for the heatmap scoring.",
            "enum": [
              "love",
              "career",
              "wealth",
              "healing",
              "intensity"
            ],
            "type": "string"
          }
        },
        "required": [
          "theme",
          "subjects"
        ],
        "type": "object"
      },
      "CompositeMethodEnum": {
        "enum": [
          "davidson",
          "midpoint"
        ],
        "title": "CompositeMethodEnum",
        "type": "string"
      },
      "CompositeRequest": {
        "additionalProperties": false,
        "description": "Composite chart request built from 2–10 subjects.",
        "example": {
          "method": "davidson",
          "subjects": [
            {
              "birth_datetime": {
                "iso": "1990-06-15T14:30:00"
              },
              "birth_location": {
                "latitude": {
                  "decimal": 40.7128
                },
                "longitude": {
                  "decimal": -74.006
                },
                "timezone": {
                  "iana_name": "America/New_York"
                }
              },
              "name": "Alice"
            },
            {
              "birth_datetime": {
                "iso": "1992-02-10T09:15:00"
              },
              "birth_location": {
                "latitude": {
                  "decimal": 34.0522
                },
                "longitude": {
                  "decimal": -118.2437
                },
                "timezone": {
                  "iana_name": "America/Los_Angeles"
                }
              },
              "name": "Bob"
            }
          ]
        },
        "properties": {
          "configuration": {
            "$ref": "#/components/schemas/ChartConfiguration",
            "description": "Chart calculation settings"
          },
          "enhanced_options": {
            "$ref": "#/components/schemas/EnhancedCalculationOptions",
            "description": "Optional enhanced calculation flags applied to the derived composite chart. Use this to enable interpretive math layers like patterns/midpoints/harmonics/HD gates where supported."
          },
          "include_visual": {
            "default": false,
            "description": "If true, a full visual SVG or PNG output will be rendered and returned alongside the chart data. Note: Visuals incur a +2 credit surcharge.",
            "title": "Include Visual",
            "type": "boolean"
          },
          "method": {
            "allOf": [
              {
                "$ref": "#/components/schemas/CompositeMethodEnum"
              }
            ],
            "default": "davidson",
            "description": "Calculation method"
          },
          "relocation": {
            "$ref": "#/components/schemas/RelocationInput",
            "description": "Optional location override"
          },
          "subjects": {
            "description": "List of subjects (2-10)",
            "items": {
              "$ref": "#/components/schemas/SubjectRequest"
            },
            "maxItems": 10,
            "minItems": 2,
            "title": "Subjects",
            "type": "array"
          },
          "visual_config": {
            "$ref": "#/components/schemas/VisualRenderConfig"
          }
        },
        "required": [
          "subjects"
        ],
        "title": "CompositeRequest",
        "type": "object"
      },
      "ConfidenceLevel": {
        "enum": [
          "high",
          "medium",
          "low",
          "historical"
        ],
        "title": "ConfidenceLevel",
        "type": "string"
      },
      "ConjunctionEvent": {
        "description": "Details of a Venus-Sun conjunction event (Venus Star Point).",
        "properties": {
          "combust": {
            "description": "True if Venus is combust the Sun",
            "title": "Combust",
            "type": "boolean"
          },
          "decan": {
            "description": "Decan (1-3) of the zodiac sign",
            "title": "Decan",
            "type": "integer"
          },
          "element": {
            "description": "Zodiac element (Fire, Earth, Air, Water)",
            "title": "Element",
            "type": "string"
          },
          "exact": {
            "description": "True if orb is within the exact threshold (usually \u003c 1 arc minute)",
            "title": "Exact",
            "type": "boolean"
          },
          "julian_day": {
            "description": "Julian Day of the exact conjunction",
            "format": "double",
            "title": "Julian Day",
            "type": "number"
          },
          "modality": {
            "description": "Zodiac modality (Cardinal, Fixed, Mutable)",
            "title": "Modality",
            "type": "string"
          },
          "orb": {
            "description": "Degree separation between Venus and Sun",
            "title": "Orb",
            "type": "number"
          },
          "planet_longitude": {
            "description": "Longitude of Venus at the time of conjunction",
            "title": "Planet Longitude",
            "type": "number"
          },
          "sign": {
            "description": "Zodiac sign name",
            "title": "Sign",
            "type": "string"
          },
          "star_longitude": {
            "description": "Longitude of the Star Point (Sun position)",
            "title": "Star Longitude",
            "type": "number"
          },
          "sun_dignity": {
            "description": "Sun's essential dignity at this position",
            "title": "Sun Dignity",
            "type": "string"
          },
          "timestamp": {
            "description": "ISO-8601 timestamp of the conjunction",
            "title": "Timestamp",
            "type": "string"
          },
          "under_beams": {
            "description": "True if Venus is under the Sun's beams",
            "title": "Under Beams",
            "type": "boolean"
          },
          "venus_dignity": {
            "description": "Venus's essential dignity at this position",
            "title": "Venus Dignity",
            "type": "string"
          },
          "visibility": {
            "description": "Phase of Venus visibility",
            "enum": [
              "morning_star",
              "evening_star"
            ],
            "title": "Visibility",
            "type": "string"
          }
        },
        "required": [
          "star_longitude",
          "planet_longitude",
          "orb",
          "exact",
          "julian_day",
          "timestamp",
          "sign",
          "element",
          "modality",
          "decan",
          "venus_dignity",
          "sun_dignity",
          "visibility",
          "combust",
          "under_beams"
        ],
        "title": "ConjunctionEvent",
        "type": "object"
      },
      "CoordinateFrameEnum": {
        "description": "Reference frame for reported coordinates.",
        "enum": [
          "ecliptic",
          "equatorial",
          "horizontal"
        ],
        "title": "CoordinateFrameEnum",
        "type": "string"
      },
      "CoordinateInput": {
        "additionalProperties": false,
        "description": "Flexible coordinate input supporting multiple formats.",
        "example": {
          "decimal": 40.7128
        },
        "properties": {
          "components": {
            "anyOf": [
              {
                "additionalProperties": {
                  "anyOf": [
                    {
                      "type": "integer"
                    },
                    {
                      "type": "number"
                    },
                    {
                      "type": "string"
                    }
                  ]
                },
                "type": "object"
              }
            ],
            "description": "Separate degree components with direction",
            "title": "Components"
          },
          "decimal": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "description": "Decimal degrees (-90 to 90 for lat, -180 to 180 for lon)",
            "title": "Decimal"
          },
          "dms": {
            "anyOf": [
              {
                "maxLength": 64,
                "type": "string"
              }
            ],
            "description": "Degrees, minutes, seconds string (e.g., '40°42'46\"N')",
            "title": "Dms"
          }
        },
        "title": "CoordinateInput",
        "type": "object"
      },
      "CoordinateSystemEnum": {
        "description": "Coordinate system used for calculations.",
        "enum": [
          "geocentric",
          "topocentric",
          "heliocentric",
          "barycentric"
        ],
        "title": "CoordinateSystemEnum",
        "type": "string"
      },
      "CreateAPIKeyRequest": {
        "description": "Request to create a new API key.",
        "properties": {
          "expires_in_days": {
            "anyOf": [
              {
                "maximum": 3650,
                "minimum": 1,
                "type": "integer"
              }
            ],
            "description": "Days until expiration (null = never expires). Recommend 90-365 days for security.",
            "example": 90,
            "title": "Expires In Days"
          },
          "name": {
            "description": "Descriptive name for the key (e.g., 'Production App', 'Mobile iOS')",
            "example": "Production API",
            "maxLength": 100,
            "minLength": 1,
            "title": "Name",
            "type": "string"
          }
        },
        "required": [
          "name"
        ],
        "title": "CreateAPIKeyRequest",
        "type": "object"
      },
      "CreateAPIKeyResponse": {
        "description": "Response after creating a new API key.\n\n⚠️ CRITICAL: api_key is shown ONCE and never stored plaintext.\nFrontend should display copy-to-clipboard UI with prominent warning.",
        "properties": {
          "api_key": {
            "description": "Full API key (save this now! It will never be shown again)",
            "example": "opene-Xd3EGwKuwrhu8S1_KH5_P3dEnNLPp4ZGQXoKxUqdpSY",
            "title": "Api Key",
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "expires_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              }
            ],
            "title": "Expires At"
          },
          "key_id": {
            "description": "UUID of the key record",
            "title": "Key Id",
            "type": "string"
          },
          "key_prefix": {
            "description": "First 14 chars for display",
            "example": "opene-Xd3EGwKu",
            "title": "Key Prefix",
            "type": "string"
          },
          "key_suffix": {
            "description": "Last 4 chars for identification",
            "example": "dpSY",
            "title": "Key Suffix",
            "type": "string"
          },
          "name": {
            "title": "Name",
            "type": "string"
          }
        },
        "required": [
          "api_key",
          "key_id",
          "key_prefix",
          "key_suffix",
          "name",
          "created_at"
        ],
        "title": "CreateAPIKeyResponse",
        "type": "object"
      },
      "CrossQuarterEvent": {
        "properties": {
          "declination": {
            "description": "Sun's declination at the time of the event",
            "title": "Declination",
            "type": "number"
          },
          "distance_au": {
            "description": "Sun's distance in AU",
            "title": "Distance Au",
            "type": "number"
          },
          "name": {
            "description": "Event name (e.g., Vernal Equinox)",
            "title": "Name",
            "type": "string"
          },
          "time": {
            "description": "ISO 8601 UTC timestamp of exactly when the event occurs",
            "title": "Time",
            "type": "string"
          },
          "type": {
            "description": "'equinox', 'solstice', or 'cross-quarter'",
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "name",
          "type",
          "time",
          "declination",
          "distance_au"
        ],
        "title": "CrossQuarterEvent",
        "type": "object"
      },
      "CrossQuarterResponse": {
        "description": "Solar events and cross-quarter days.",
        "properties": {
          "_meta": {
            "description": "Calculation metadata",
            "title": " Meta",
            "type": "object"
          },
          "events": {
            "description": "List of solar events in chronological order",
            "items": {
              "$ref": "#/components/schemas/CrossQuarterEvent"
            },
            "title": "Events",
            "type": "array"
          },
          "year": {
            "description": "Year of the events",
            "title": "Year",
            "type": "integer"
          }
        },
        "required": [
          "year",
          "events",
          "_meta"
        ],
        "title": "CrossQuarterResponse",
        "type": "object"
      },
      "DateTimeInput": {
        "additionalProperties": false,
        "description": "Date/time input in ISO-8601, component, or Julian day form.",
        "example": {
          "iso": "2023-12-07T15:30:00Z"
        },
        "properties": {
          "components": {
            "anyOf": [
              {
                "additionalProperties": {
                  "type": "integer"
                },
                "type": "object"
              }
            ],
            "description": "Date/time components",
            "title": "Components"
          },
          "iso": {
            "anyOf": [
              {
                "maxLength": 64,
                "type": "string"
              }
            ],
            "description": "ISO 8601 datetime string (year -13000–17000 CE)",
            "title": "Iso"
          },
          "julian_day": {
            "anyOf": [
              {
                "format": "double",
                "type": "number"
              }
            ],
            "description": "Julian Day Number",
            "title": "Julian Day"
          }
        },
        "title": "DateTimeInput",
        "type": "object"
      },
      "DeclinationAnalysisRequest": {
        "description": "Input for out-of-bounds declination analysis. Provide ecliptic coordinates for each body.",
        "properties": {
          "bodies": {
            "description": "Array of celestial bodies with ecliptic coordinates.",
            "items": {
              "properties": {
                "id": {
                  "description": "Celestial body identifier (e.g. 0=Sun, 1=Moon, 2=Mercury…)",
                  "type": "integer"
                },
                "latitude": {
                  "description": "Ecliptic latitude in degrees (typically ±8°)",
                  "format": "double",
                  "type": "number"
                },
                "longitude": {
                  "description": "Ecliptic longitude in degrees [0, 360)",
                  "format": "double",
                  "type": "number"
                }
              },
              "required": [
                "id",
                "longitude",
                "latitude"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "obliquity": {
            "default": 23.4393,
            "description": "Obliquity of the ecliptic in degrees. Defaults to J2000 mean obliquity (23.4393°).",
            "format": "double",
            "type": "number"
          },
          "parallel_orb": {
            "default": 1,
            "description": "Orb in degrees for detecting parallels and contraparallels. Default 1.0°.",
            "format": "double",
            "type": "number"
          }
        },
        "required": [
          "bodies"
        ],
        "title": "DeclinationAnalysisRequest",
        "type": "object"
      },
      "DeclinationAnalysisResponse": {
        "description": "Out-of-bounds declination analysis results.",
        "properties": {
          "bodies": {
            "description": "Per-body declination data.",
            "items": {
              "properties": {
                "declination": {
                  "format": "double",
                  "type": "number"
                },
                "direction": {
                  "enum": [
                    "north",
                    "south"
                  ],
                  "type": "string"
                },
                "id": {
                  "type": "integer"
                },
                "is_oob": {
                  "type": "boolean"
                },
                "latitude": {
                  "format": "double",
                  "type": "number"
                },
                "longitude": {
                  "format": "double",
                  "type": "number"
                },
                "name": {
                  "type": "string"
                },
                "oob_excess": {
                  "format": "double",
                  "type": "number"
                }
              },
              "type": "object"
            },
            "type": "array"
          },
          "calculation_metadata": {
            "description": "Processing metadata.",
            "properties": {
              "output_mode": {
                "type": "string"
              },
              "processing_time_ms": {
                "type": "number"
              }
            },
            "type": "object"
          },
          "max_declination": {
            "description": "Most extreme absolute declination across all bodies.",
            "format": "double",
            "type": "number"
          },
          "obliquity": {
            "description": "Obliquity value used for the analysis.",
            "format": "double",
            "type": "number"
          },
          "oob_count": {
            "description": "Number of bodies that are out of bounds.",
            "type": "integer"
          },
          "parallels": {
            "description": "Declination aspects: parallels and contraparallels.",
            "items": {
              "properties": {
                "body1": {
                  "type": "integer"
                },
                "body2": {
                  "type": "integer"
                },
                "dec1": {
                  "format": "double",
                  "type": "number"
                },
                "dec2": {
                  "format": "double",
                  "type": "number"
                },
                "orb": {
                  "format": "double",
                  "type": "number"
                },
                "type": {
                  "enum": [
                    "parallel",
                    "contraparallel"
                  ],
                  "type": "string"
                }
              },
              "type": "object"
            },
            "type": "array"
          },
          "success": {
            "type": "boolean"
          }
        },
        "title": "DeclinationAnalysisResponse",
        "type": "object"
      },
      "DeclinationAspect": {
        "additionalProperties": false,
        "description": "Declination-based aspect between two bodies.",
        "properties": {
          "applying": {
            "description": "Whether aspect is applying",
            "title": "Applying",
            "type": "boolean"
          },
          "body1": {
            "description": "First body name",
            "title": "Body1",
            "type": "string"
          },
          "body2": {
            "description": "Second body name",
            "title": "Body2",
            "type": "string"
          },
          "declination1": {
            "description": "First body declination",
            "title": "Declination1",
            "type": "number"
          },
          "declination2": {
            "description": "Second body declination",
            "title": "Declination2",
            "type": "number"
          },
          "orb": {
            "description": "Orb difference in degrees",
            "title": "Orb",
            "type": "number"
          },
          "type": {
            "description": "Aspect type",
            "pattern": "^(parallel|contraparallel)$",
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "body1",
          "body2",
          "type",
          "declination1",
          "declination2",
          "orb",
          "applying"
        ],
        "title": "DeclinationAspect",
        "type": "object"
      },
      "DeltaTProfileEnum": {
        "description": "Selectable ΔT curve profiles (SE §7).",
        "enum": [
          "swiss_default",
          "espenak_meeus",
          "morrison_stephenson"
        ],
        "title": "DeltaTProfileEnum",
        "type": "string"
      },
      "DeltaTResponse": {
        "properties": {
          "date": {
            "description": "Date string used for calculation",
            "title": "Date",
            "type": "string"
          },
          "delta_t": {
            "additionalProperties": {
              "type": "number"
            },
            "description": "Delta T value (seconds) and its components",
            "title": "Delta T",
            "type": "object"
          },
          "julian_day": {
            "description": "Julian Day for which Delta T was calculated",
            "format": "double",
            "title": "Julian Day",
            "type": "number"
          },
          "model": {
            "description": "The mathematical model used (e.g., Stephenson 2021)",
            "title": "Model",
            "type": "string"
          },
          "uncertainty": {
            "description": "Estimated uncertainty in the Delta T value",
            "title": "Uncertainty",
            "type": "object"
          }
        },
        "required": [
          "date",
          "julian_day",
          "delta_t",
          "model",
          "uncertainty"
        ],
        "title": "DeltaTResponse",
        "type": "object"
      },
      "DeltaTSourceEnum": {
        "description": "Source of ΔT values used in calculations.",
        "enum": [
          "nasa_jpl",
          "iers",
          "approximation_model"
        ],
        "title": "DeltaTSourceEnum",
        "type": "string"
      },
      "DignitiesRequest": {
        "additionalProperties": false,
        "description": "Request for essential dignity scoring (granular endpoint).",
        "example": {
          "date_time": {
            "iso": "2025-12-11T12:00:00Z"
          },
          "latitude": 40.7128,
          "longitude": -74.006
        },
        "properties": {
          "date_time": {
            "allOf": [
              {
                "$ref": "#/components/schemas/DateTimeInput"
              }
            ],
            "description": "Calculation datetime"
          },
          "house_system": {
            "default": "P",
            "description": "House system code used for day/night derivation when lat/lon provided",
            "example": "P",
            "title": "House System",
            "type": "string"
          },
          "latitude": {
            "anyOf": [
              {
                "maximum": 90,
                "minimum": -90,
                "type": "number"
              }
            ],
            "description": "Optional latitude used to derive day/night for triplicity (omit to default to day chart)",
            "title": "Latitude"
          },
          "longitude": {
            "anyOf": [
              {
                "maximum": 180,
                "minimum": -180,
                "type": "number"
              }
            ],
            "description": "Optional longitude used to derive day/night for triplicity (omit to default to day chart)",
            "title": "Longitude"
          }
        },
        "required": [
          "date_time"
        ],
        "title": "DignitiesRequest",
        "type": "object"
      },
      "DignitiesResponse": {
        "additionalProperties": false,
        "description": "Response from essential dignities granular endpoint.",
        "properties": {
          "dignities": {
            "description": "Dignity scoring results",
            "items": {
              "$ref": "#/components/schemas/DignityResult"
            },
            "title": "Dignities",
            "type": "array"
          },
          "is_day_chart": {
            "description": "Day/night flag used for triplicity scoring",
            "title": "Is Day Chart",
            "type": "boolean"
          },
          "metadata": {
            "description": "Calculation metadata",
            "title": "Metadata",
            "type": "object"
          },
          "success": {
            "default": true,
            "description": "Calculation success status",
            "title": "Success",
            "type": "boolean"
          }
        },
        "required": [
          "is_day_chart",
          "dignities",
          "metadata"
        ],
        "title": "DignitiesResponse",
        "type": "object"
      },
      "DignityConfig": {
        "additionalProperties": false,
        "description": "Essential/accidental dignity settings.",
        "properties": {
          "include_accidental": {
            "default": false,
            "description": "Include accidental dignity scoring",
            "title": "Include Accidental",
            "type": "boolean"
          },
          "include_essential": {
            "default": true,
            "description": "Include essential dignity scoring",
            "title": "Include Essential",
            "type": "boolean"
          },
          "system": {
            "allOf": [
              {
                "$ref": "#/components/schemas/DignitySystemEnum"
              }
            ],
            "default": "lilly_like_standard",
            "description": "Dignity scoring tables to use"
          }
        },
        "title": "DignityConfig",
        "type": "object"
      },
      "DignityResult": {
        "additionalProperties": false,
        "description": "Essential dignity scoring result for one body.",
        "properties": {
          "accidental_dignities": {
            "$ref": "#/components/schemas/AccidentalDignityInfo",
            "description": "Accidental dignities (tags-only). Included when house placement is available."
          },
          "debilities_held": {
            "description": "List of debilities present",
            "items": {
              "type": "string"
            },
            "title": "Debilities Held",
            "type": "array"
          },
          "dignities_held": {
            "description": "List of dignities present",
            "items": {
              "type": "string"
            },
            "title": "Dignities Held",
            "type": "array"
          },
          "exaltation_score": {
            "description": "Score contribution from exaltation",
            "title": "Exaltation Score",
            "type": "integer"
          },
          "face_score": {
            "description": "Score contribution from faces",
            "title": "Face Score",
            "type": "integer"
          },
          "longitude": {
            "description": "Ecliptic longitude in degrees",
            "title": "Longitude",
            "type": "number"
          },
          "planet_id": {
            "description": "SE-compatible planet ID",
            "title": "Planet Id",
            "type": "integer"
          },
          "planet_name": {
            "description": "Planet name",
            "title": "Planet Name",
            "type": "string"
          },
          "rulership_score": {
            "description": "Score contribution from domicile",
            "title": "Rulership Score",
            "type": "integer"
          },
          "term_score": {
            "description": "Score contribution from terms",
            "title": "Term Score",
            "type": "integer"
          },
          "total_score": {
            "description": "Aggregate essential dignity score",
            "title": "Total Score",
            "type": "integer"
          },
          "triplicity_score": {
            "description": "Score contribution from triplicity",
            "title": "Triplicity Score",
            "type": "integer"
          }
        },
        "required": [
          "planet_id",
          "planet_name",
          "longitude",
          "total_score",
          "rulership_score",
          "exaltation_score",
          "triplicity_score",
          "term_score",
          "face_score"
        ],
        "title": "DignityResult",
        "type": "object"
      },
      "DignitySystemEnum": {
        "description": "Supported dignity scoring systems.",
        "enum": [
          "lilly_like_standard",
          "modern_balanced",
          "sidereal_variant"
        ],
        "title": "DignitySystemEnum",
        "type": "string"
      },
      "DispositorFinalDispositorResponse": {
        "description": "The final dispositor of the chart.",
        "properties": {
          "planet_id": {
            "type": "integer"
          },
          "planet_name": {
            "type": "string"
          }
        },
        "required": [
          "planet_id",
          "planet_name"
        ],
        "title": "DispositorFinalDispositorResponse",
        "type": "object"
      },
      "DispositorMutualReceptionResponse": {
        "description": "A pair of planets in mutual reception.",
        "properties": {
          "planet1_id": {
            "type": "integer"
          },
          "planet1_name": {
            "type": "string"
          },
          "planet2_id": {
            "type": "integer"
          },
          "planet2_name": {
            "type": "string"
          }
        },
        "required": [
          "planet1_id",
          "planet1_name",
          "planet2_id",
          "planet2_name"
        ],
        "title": "DispositorMutualReceptionResponse",
        "type": "object"
      },
      "DispositorNodeResponse": {
        "description": "A single node in the dispositor tree.",
        "properties": {
          "depth": {
            "description": "Number of hops to the chain terminus (final dispositor or cycle)",
            "type": "integer"
          },
          "dispositor_id": {
            "description": "Planet ID of the dispositor (ruler of this planet's sign)",
            "type": "integer"
          },
          "dispositor_name": {
            "description": "Dispositor planet name",
            "type": "string"
          },
          "is_final_dispositor": {
            "description": "True if this planet rules its own sign",
            "type": "boolean"
          },
          "planet_id": {
            "description": "Planet SE index",
            "type": "integer"
          },
          "planet_name": {
            "description": "Human-readable planet name",
            "type": "string"
          },
          "sign": {
            "description": "Sign number (0-based for API)",
            "type": "integer"
          },
          "sign_name": {
            "description": "Zodiac sign name",
            "type": "string"
          }
        },
        "required": [
          "planet_id",
          "planet_name",
          "sign",
          "sign_name",
          "dispositor_id",
          "dispositor_name",
          "depth",
          "is_final_dispositor"
        ],
        "title": "DispositorNodeResponse",
        "type": "object"
      },
      "DispositorTreeRequest": {
        "description": "Input for dispositor tree calculation. Provide each planet's sign placement. Signs use 0-based indexing (0=Aries, 11=Pisces) to match the standard API convention.",
        "properties": {
          "planets": {
            "description": "Array of planetary placements with planet ID and occupied sign.",
            "items": {
              "properties": {
                "planet_id": {
                  "description": "Standard planet ID (0=Sun, 1=Moon, 2=Mercury, 3=Venus, 4=Mars, 5=Jupiter, 6=Saturn)",
                  "type": "integer"
                },
                "sign": {
                  "description": "Zodiac sign the planet occupies (0=Aries … 11=Pisces). Converted to 1-based internally.",
                  "type": "integer"
                }
              },
              "required": [
                "planet_id",
                "sign"
              ],
              "type": "object"
            },
            "type": "array"
          }
        },
        "required": [
          "planets"
        ],
        "title": "DispositorTreeRequest",
        "type": "object"
      },
      "DispositorTreeResponse": {
        "description": "Dispositor tree analysis — shows the chain of planetary rulership, identifying final dispositors and mutual receptions.",
        "properties": {
          "calculation_metadata": {
            "additionalProperties": true,
            "description": "Processing metadata",
            "type": "object"
          },
          "final_dispositor": {
            "description": "The final dispositor (planet ruling its own sign), if one exists. Null if the chart has no single final dispositor.",
            "oneOf": [
              {
                "$ref": "#/components/schemas/DispositorFinalDispositorResponse"
              },
              {
                "nullable": true,
                "type": "object"
              }
            ]
          },
          "mutual_receptions": {
            "description": "Pairs of planets in mutual reception (each in the other's sign)",
            "items": {
              "$ref": "#/components/schemas/DispositorMutualReceptionResponse"
            },
            "type": "array"
          },
          "nodes": {
            "description": "All nodes in the dispositor tree",
            "items": {
              "$ref": "#/components/schemas/DispositorNodeResponse"
            },
            "type": "array"
          },
          "success": {
            "type": "boolean"
          }
        },
        "required": [
          "success",
          "nodes",
          "mutual_receptions"
        ],
        "title": "DispositorTreeResponse",
        "type": "object"
      },
      "DraconicChartRequest": {
        "properties": {
          "format": {
            "description": "Response format: json | llm.",
            "enum": [
              "json",
              "llm"
            ],
            "type": "string"
          },
          "subject": {
            "$ref": "#/components/schemas/SubjectRequest"
          }
        },
        "required": [
          "subject"
        ],
        "type": "object"
      },
      "DraconicChartResponse": {
        "properties": {
          "draconic_positions": {
            "items": {
              "$ref": "#/components/schemas/DraconicPosition"
            },
            "type": "array"
          },
          "metadata": {
            "type": "object"
          },
          "subject": {
            "$ref": "#/components/schemas/SubjectResponse"
          },
          "success": {
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "DraconicPosition": {
        "properties": {
          "draconic_longitude": {
            "format": "float",
            "type": "number"
          },
          "draconic_sign": {
            "type": "string"
          },
          "draconic_sign_deg": {
            "format": "float",
            "type": "number"
          },
          "id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "natal_longitude": {
            "format": "float",
            "type": "number"
          }
        },
        "type": "object"
      },
      "EclipseClassification": {
        "properties": {
          "central_duration_seconds": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "title": "Central Duration Seconds"
          },
          "gamma": {
            "title": "Gamma",
            "type": "number"
          },
          "greatest_magnitude": {
            "default": 0,
            "title": "Greatest Magnitude",
            "type": "number"
          },
          "inex_series": {
            "anyOf": [
              {
                "type": "integer"
              }
            ],
            "title": "Inex Series"
          },
          "kind": {
            "$ref": "#/components/schemas/EclipseKind"
          },
          "saros_member": {
            "default": 0,
            "title": "Saros Member",
            "type": "integer"
          },
          "saros_series": {
            "default": 0,
            "title": "Saros Series",
            "type": "integer"
          },
          "type": {
            "$ref": "#/components/schemas/EclipseType"
          }
        },
        "required": [
          "type",
          "kind",
          "gamma"
        ],
        "title": "EclipseClassification",
        "type": "object"
      },
      "EclipseKind": {
        "enum": [
          "solar",
          "lunar"
        ],
        "title": "EclipseKind",
        "type": "string"
      },
      "EclipseSummary": {
        "properties": {
          "date": {
            "title": "Date",
            "type": "string"
          },
          "gamma": {
            "default": 0,
            "title": "Gamma",
            "type": "number"
          },
          "jd": {
            "format": "double",
            "title": "Jd",
            "type": "number"
          },
          "kind": {
            "$ref": "#/components/schemas/EclipseKind"
          },
          "magnitude": {
            "default": 0,
            "title": "Magnitude",
            "type": "number"
          },
          "type": {
            "$ref": "#/components/schemas/EclipseType"
          }
        },
        "required": [
          "date",
          "jd",
          "kind"
        ],
        "title": "EclipseSummary",
        "type": "object"
      },
      "EclipseType": {
        "enum": [
          "total",
          "annular",
          "hybrid",
          "partial",
          "penumbral"
        ],
        "title": "EclipseType",
        "type": "string"
      },
      "ElectionalAspect": {
        "additionalProperties": false,
        "properties": {
          "aspect_type": {
            "title": "Aspect Type",
            "type": "string"
          },
          "orb": {
            "title": "Orb",
            "type": "number"
          },
          "planet1": {
            "title": "Planet1",
            "type": "string"
          },
          "planet2": {
            "title": "Planet2",
            "type": "string"
          },
          "quality_label": {
            "title": "Quality Label",
            "type": "string"
          },
          "quality_score": {
            "title": "Quality Score",
            "type": "integer"
          }
        },
        "title": "ElectionalAspect",
        "type": "object"
      },
      "ElectionalAspectSearchResponse": {
        "additionalProperties": false,
        "properties": {
          "aspects": {
            "items": {
              "$ref": "#/components/schemas/ElectionalAspect"
            },
            "type": "array"
          },
          "iso_time": {
            "title": "Iso Time",
            "type": "string"
          },
          "jd": {
            "format": "double",
            "title": "Jd",
            "type": "number"
          }
        },
        "required": [
          "aspects",
          "jd",
          "iso_time"
        ],
        "title": "ElectionalAspectSearchResponse",
        "type": "object"
      },
      "ElectionalIngress": {
        "additionalProperties": false,
        "properties": {
          "from_sign": {
            "title": "From Sign",
            "type": "string"
          },
          "ingress_time": {
            "title": "Ingress Time",
            "type": "string"
          },
          "is_retrograde": {
            "nullable": true,
            "title": "Is Retrograde",
            "type": "boolean"
          },
          "longitude": {
            "nullable": true,
            "title": "Longitude",
            "type": "number"
          },
          "planet_id": {
            "title": "Planet Id",
            "type": "integer"
          },
          "planet_name": {
            "title": "Planet Name",
            "type": "string"
          },
          "to_sign": {
            "title": "To Sign",
            "type": "string"
          }
        },
        "required": [
          "planet_name",
          "planet_id",
          "from_sign",
          "to_sign",
          "ingress_time"
        ],
        "title": "ElectionalIngress",
        "type": "object"
      },
      "ElectionalIngressCalendarResponse": {
        "additionalProperties": false,
        "properties": {
          "ingresses": {
            "items": {
              "$ref": "#/components/schemas/ElectionalIngress"
            },
            "type": "array"
          },
          "total_count": {
            "title": "Total Count",
            "type": "integer"
          }
        },
        "required": [
          "ingresses",
          "total_count"
        ],
        "title": "ElectionalIngressCalendarResponse",
        "type": "object"
      },
      "ElectionalMomentResponse": {
        "additionalProperties": false,
        "properties": {
          "aspects": {
            "items": {
              "$ref": "#/components/schemas/ElectionalAspect"
            },
            "nullable": true,
            "type": "array"
          },
          "day_ruler": {
            "nullable": true,
            "title": "Day Ruler",
            "type": "string"
          },
          "dignity_breakdown": {
            "items": {
              "$ref": "#/components/schemas/ElectionalPlanetDignity"
            },
            "nullable": true,
            "type": "array"
          },
          "is_void": {
            "nullable": true,
            "title": "Is Void",
            "type": "boolean"
          },
          "iso_time": {
            "title": "Iso Time",
            "type": "string"
          },
          "jd": {
            "format": "double",
            "title": "Jd",
            "type": "number"
          },
          "lunar_phase": {
            "nullable": true,
            "title": "Lunar Phase",
            "type": "string"
          },
          "rating": {
            "description": "excellent/good/moderate/poor/avoid",
            "title": "Rating",
            "type": "string"
          },
          "score": {
            "description": "Composite viability score 0-100",
            "title": "Score",
            "type": "integer"
          },
          "score_detail": {
            "additionalProperties": true,
            "nullable": true,
            "type": "object"
          },
          "void_ends_at": {
            "nullable": true,
            "title": "Void Ends At",
            "type": "string"
          }
        },
        "required": [
          "score",
          "rating",
          "jd",
          "iso_time"
        ],
        "title": "ElectionalMomentResponse",
        "type": "object"
      },
      "ElectionalPlanetDignity": {
        "additionalProperties": false,
        "properties": {
          "dignity_label": {
            "title": "Dignity Label",
            "type": "string"
          },
          "dignity_total": {
            "title": "Dignity Total",
            "type": "integer"
          },
          "is_retrograde": {
            "title": "Is Retrograde",
            "type": "boolean"
          },
          "longitude": {
            "title": "Longitude",
            "type": "number"
          },
          "motion_status": {
            "title": "Motion Status",
            "type": "string"
          },
          "planet_id": {
            "title": "Planet Id",
            "type": "integer"
          },
          "planet_name": {
            "title": "Planet Name",
            "type": "string"
          },
          "speed": {
            "title": "Speed",
            "type": "number"
          }
        },
        "title": "ElectionalPlanetDignity",
        "type": "object"
      },
      "ElectionalStation": {
        "additionalProperties": false,
        "properties": {
          "exact_time": {
            "title": "Exact Time",
            "type": "string"
          },
          "longitude": {
            "title": "Longitude",
            "type": "number"
          },
          "planet_id": {
            "title": "Planet Id",
            "type": "integer"
          },
          "planet_name": {
            "title": "Planet Name",
            "type": "string"
          },
          "sign": {
            "nullable": true,
            "title": "Sign",
            "type": "string"
          },
          "station_type": {
            "description": "retrograde_station or direct_station",
            "title": "Station Type",
            "type": "string"
          }
        },
        "required": [
          "planet_name",
          "planet_id",
          "station_type",
          "exact_time",
          "longitude"
        ],
        "title": "ElectionalStation",
        "type": "object"
      },
      "ElectionalStationResponse": {
        "additionalProperties": false,
        "properties": {
          "stations": {
            "items": {
              "$ref": "#/components/schemas/ElectionalStation"
            },
            "type": "array"
          },
          "total_count": {
            "title": "Total Count",
            "type": "integer"
          }
        },
        "required": [
          "stations",
          "total_count"
        ],
        "title": "ElectionalStationResponse",
        "type": "object"
      },
      "ElectionalWindow": {
        "additionalProperties": false,
        "properties": {
          "cautions": {
            "items": {
              "type": "string"
            },
            "nullable": true,
            "type": "array"
          },
          "duration_minutes": {
            "title": "Duration Minutes",
            "type": "number"
          },
          "end_time": {
            "title": "End Time",
            "type": "string"
          },
          "key_factors": {
            "items": {
              "type": "string"
            },
            "nullable": true,
            "type": "array"
          },
          "rank": {
            "title": "Rank",
            "type": "integer"
          },
          "rating": {
            "title": "Rating",
            "type": "string"
          },
          "score": {
            "title": "Score",
            "type": "integer"
          },
          "start_time": {
            "title": "Start Time",
            "type": "string"
          }
        },
        "required": [
          "rank",
          "score",
          "rating",
          "start_time",
          "end_time",
          "duration_minutes"
        ],
        "title": "ElectionalWindow",
        "type": "object"
      },
      "ElectionalWindowResponse": {
        "additionalProperties": false,
        "properties": {
          "search_summary": {
            "additionalProperties": true,
            "type": "object"
          },
          "windows": {
            "items": {
              "$ref": "#/components/schemas/ElectionalWindow"
            },
            "type": "array"
          }
        },
        "required": [
          "windows",
          "search_summary"
        ],
        "title": "ElectionalWindowResponse",
        "type": "object"
      },
      "EnhancedAspectResponse": {
        "additionalProperties": false,
        "description": "Enhanced aspect payload exposed by the public API.",
        "properties": {
          "aspect_quality": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Quality assessment derived from dignities or contextual analysis",
            "title": "Aspect Quality"
          },
          "aspect_type": {
            "description": "Aspect type (e.g., Conjunction, Square)",
            "title": "Aspect Type",
            "type": "string"
          },
          "classification": {
            "description": "Aspect classification (major or minor)",
            "title": "Classification",
            "type": "string"
          },
          "dignity_interaction": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Summary of the essential dignity interaction between the planets",
            "title": "Dignity Interaction"
          },
          "exact_angle": {
            "description": "Exact angle associated with the aspect type",
            "title": "Exact Angle",
            "type": "number"
          },
          "is_applying": {
            "anyOf": [
              {
                "type": "boolean"
              }
            ],
            "description": "True if the aspect is applying, False if separating, None when undetermined",
            "title": "Is Applying"
          },
          "mutual_reception": {
            "anyOf": [
              {
                "type": "boolean"
              }
            ],
            "description": "Whether the two planets are in mutual reception",
            "title": "Mutual Reception"
          },
          "orb": {
            "description": "Absolute distance from the exact angle in degrees",
            "title": "Orb",
            "type": "number"
          },
          "orb_allowance": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "description": "Maximum allowed orb for this aspect and planet pair in degrees",
            "title": "Orb Allowance"
          },
          "orb_percentage": {
            "description": "Percentage of the allowed orb that is used (0-100)",
            "title": "Orb Percentage",
            "type": "number"
          },
          "phase_angle": {
            "description": "Current angular separation between the bodies in degrees",
            "title": "Phase Angle",
            "type": "number"
          },
          "planet1": {
            "description": "First planet involved in the aspect",
            "title": "Planet1",
            "type": "string"
          },
          "planet2": {
            "description": "Second planet involved in the aspect",
            "title": "Planet2",
            "type": "string"
          },
          "speed_ratio": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "description": "Ratio of the slower planet's absolute speed to the faster one's (0-1)",
            "title": "Speed Ratio"
          },
          "strength": {
            "description": "Aspect strength scaled between 0.0 and 1.0",
            "title": "Strength",
            "type": "number"
          }
        },
        "required": [
          "planet1",
          "planet2",
          "aspect_type",
          "classification",
          "phase_angle",
          "exact_angle",
          "orb",
          "orb_percentage",
          "strength"
        ],
        "title": "EnhancedAspectResponse",
        "type": "object"
      },
      "EnhancedCalculationOptions": {
        "additionalProperties": false,
        "description": "Options for enhanced natal chart calculations.",
        "example": {
          "apsides": false,
          "aspect_patterns": false,
          "chart_shape": true,
          "element_balance": true,
          "elongations": false,
          "hemisphere_emphasis": true,
          "human_design_gates": false,
          "include_hermetic_lots": true,
          "lunar_phase": false,
          "retrograde_shadows": false,
          "sect_determination": true,
          "solar_relationships": true,
          "synodic_phases": true,
          "void_of_course": false
        },
        "properties": {
          "apsides": {
            "default": false,
            "description": "Compute periapsis/apoapsis points (perihelion/aphelion; Moon perigee/apogee) and simple separations to the current longitudes.",
            "title": "Apsides",
            "type": "boolean"
          },
          "aspect_patterns": {
            "default": false,
            "description": "Identify aspect patterns",
            "title": "Aspect Patterns",
            "type": "boolean"
          },
          "chart_shape": {
            "default": true,
            "description": "Determine chart shape pattern",
            "title": "Chart Shape",
            "type": "boolean"
          },
          "element_balance": {
            "default": true,
            "description": "Calculate elemental balance",
            "title": "Element Balance",
            "type": "boolean"
          },
          "elongations": {
            "default": false,
            "description": "Compute Sun-relative elongation metrics for major bodies (separation, signed delta, east/west).",
            "title": "Elongations",
            "type": "boolean"
          },
          "harmonic_numbers": {
            "anyOf": [
              {
                "items": {
                  "type": "integer"
                },
                "type": "array"
              }
            ],
            "description": "Harmonic numbers to calculate (default: [4, 5, 7, 9])",
            "title": "Harmonic Numbers"
          },
          "hemisphere_emphasis": {
            "default": true,
            "description": "Analyze hemisphere emphasis",
            "title": "Hemisphere Emphasis",
            "type": "boolean"
          },
          "hermetic_lots_selection": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              }
            ],
            "default": [
              "fortune",
              "spirit"
            ],
            "description": "Optional list of Hermetic lot identifiers to calculate (aliases accepted: arabic_parts_selection). If omitted, defaults to the canonical selection.",
            "items": {
              "enum": [
                "fortune",
                "spirit"
              ],
              "type": "string"
            },
            "title": "Hermetic Lots Selection",
            "x-ui-widget": "checkbox-group"
          },
          "human_design_gates": {
            "default": false,
            "description": "Compute Human Design / I Ching gate + line mappings from ecliptic longitude.",
            "title": "Human Design Gates",
            "type": "boolean"
          },
          "include_fixed_stars": {
            "anyOf": [
              {
                "type": "boolean"
              }
            ],
            "deprecated": true,
            "description": "DEPRECATED. Fixed-star computation is configured via configuration.fixed_star_options.include. This field is accepted for backward compatibility and may be removed in a future release.",
            "title": "Include Fixed Stars",
            "x-ui-hidden": true
          },
          "include_harmonics": {
            "default": false,
            "description": "Include harmonic chart positions",
            "title": "Include Harmonics",
            "type": "boolean"
          },
          "include_hermetic_lots": {
            "default": true,
            "description": "Calculate Hermetic lots",
            "title": "Include Hermetic Lots",
            "type": "boolean"
          },
          "include_midpoints": {
            "default": false,
            "description": "Calculate midpoints between planet pairs",
            "title": "Include Midpoints",
            "type": "boolean"
          },
          "lunar_phase": {
            "default": false,
            "description": "Compute lunar phase (name, illumination, phase angle, waxing/waning, and days-to-new/full).",
            "title": "Lunar Phase",
            "type": "boolean"
          },
          "retrograde_shadows": {
            "default": false,
            "description": "Compute retrograde station timings and pre/post-shadow windows (bounded day-scan; more expensive than snapshot retrograde analysis).",
            "title": "Retrograde Shadows",
            "type": "boolean"
          },
          "sect_determination": {
            "default": true,
            "description": "Perform sect determination",
            "title": "Sect Determination",
            "type": "boolean"
          },
          "solar_relationships": {
            "default": true,
            "description": "Compute solar relationship / visibility classifications (e.g., cazimi/combust/under-beams) and Mercury/Venus morning/evening star context.",
            "title": "Solar Relationships",
            "type": "boolean"
          },
          "synodic_phases": {
            "default": true,
            "description": "Compute synodic phase classifications derived from Sun-relative geometry (e.g., Mercury/Venus morning/evening star and conjunction type when near conjunction).",
            "title": "Synodic Phases",
            "type": "boolean"
          },
          "void_of_course": {
            "default": false,
            "description": "Compute Void-of-Course Moon status and window (bounded search within current sign).",
            "title": "Void Of Course",
            "type": "boolean"
          }
        },
        "title": "EnhancedCalculationOptions",
        "type": "object"
      },
      "EnhancedChartSuccessResponse": {
        "additionalProperties": true,
        "description": "Standardized envelope for enhanced chart responses.",
        "properties": {
          "data": {
            "allOf": [
              {
                "$ref": "#/components/schemas/NatalChartEnhancedResponse"
              }
            ],
            "description": "Enhanced chart payload"
          },
          "features_denied": {
            "description": "Feature flags that were requested but not included due to subscription tier gating (top-level convenience mirror).",
            "items": {
              "type": "string"
            },
            "title": "Features Denied",
            "type": "array"
          },
          "features_included": {
            "description": "Feature flags present in the response payload (top-level convenience mirror).",
            "items": {
              "type": "string"
            },
            "title": "Features Included",
            "type": "array"
          },
          "metadata": {
            "allOf": [
              {
                "$ref": "#/components/schemas/EnhancedResponseMetadata"
              }
            ],
            "description": "Response metadata (processing time, cache info)"
          },
          "output_mode": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Output projection mode (full | simple | llm)",
            "title": "Output Mode"
          },
          "schema_version": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Schema version for the selected output mode (e.g., full_v1, simple_v1, llm)",
            "title": "Schema Version"
          },
          "success": {
            "default": true,
            "description": "Response success status",
            "title": "Success",
            "type": "boolean"
          }
        },
        "required": [
          "data"
        ],
        "title": "EnhancedChartSuccessResponse",
        "type": "object"
      },
      "EnhancedResponseMetadata": {
        "additionalProperties": true,
        "description": "Standardized metadata for enhanced envelope responses.",
        "properties": {
          "cache_hit": {
            "anyOf": [
              {
                "type": "boolean"
              }
            ],
            "description": "Indicates whether the response returned from cache",
            "title": "Cache Hit"
          },
          "calculation_time_ms": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "description": "Observed calculation time including enrichment steps (milliseconds)",
            "title": "Calculation Time Ms"
          },
          "calculation_time_seconds": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "description": "Observed calculation time expressed in seconds for readability",
            "title": "Calculation Time Seconds"
          },
          "features_included": {
            "description": "Feature flags present in the response payload",
            "items": {
              "type": "string"
            },
            "title": "Features Included",
            "type": "array"
          },
          "processing_time_ms": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "description": "End-to-end processing time reported by the orchestrator (milliseconds)",
            "title": "Processing Time Ms"
          }
        },
        "title": "EnhancedResponseMetadata",
        "type": "object"
      },
      "EntitlementPayload": {
        "properties": {
          "billing_error": {
            "anyOf": [
              {
                "enum": [
                  "unauthorized",
                  "account_deleted",
                  "billing_unavailable"
                ],
                "type": "string"
              }
            ],
            "description": "Billing error code, when entitlement could not be fully resolved.",
            "title": "Billing Error"
          },
          "entitled": {
            "description": "True when the user can access entitled surfaces.",
            "title": "Entitled",
            "type": "boolean"
          },
          "is_admin": {
            "description": "True when the user has admin access.",
            "title": "Is Admin",
            "type": "boolean"
          },
          "is_beta": {
            "description": "True when the user has beta access.",
            "title": "Is Beta",
            "type": "boolean"
          },
          "reason": {
            "description": "Primary reason the user is entitled (if any).",
            "enum": [
              "admin",
              "subscription",
              "beta",
              "none"
            ],
            "title": "Reason",
            "type": "string"
          }
        },
        "required": [
          "entitled",
          "is_admin",
          "is_beta",
          "reason"
        ],
        "title": "EntitlementPayload",
        "type": "object"
      },
      "EquationOfTimeResponse": {
        "properties": {
          "apparent_solar_time": {
            "description": "The computed Apparent Solar Time (decimal hours)",
            "title": "Apparent Solar Time",
            "type": "number"
          },
          "equation_of_time_minutes": {
            "description": "The Equation of Time value in minutes",
            "title": "Equation Of Time Minutes",
            "type": "number"
          },
          "julian_day": {
            "description": "The Julian Day (TT) used for calculation",
            "format": "double",
            "title": "Julian Day",
            "type": "number"
          },
          "mean_solar_time": {
            "description": "The computed Mean Solar Time (decimal hours)",
            "title": "Mean Solar Time",
            "type": "number"
          }
        },
        "required": [
          "julian_day",
          "equation_of_time_minutes",
          "mean_solar_time",
          "apparent_solar_time"
        ],
        "title": "EquationOfTimeResponse",
        "type": "object"
      },
      "EquilibriumTide": {
        "properties": {
          "combined_m": {
            "description": "Combined equilibrium tide (meters)",
            "title": "Combined M",
            "type": "number"
          },
          "lunar_component_m": {
            "description": "Lunar component of equilibrium tide (meters)",
            "title": "Lunar Component M",
            "type": "number"
          },
          "note": {
            "description": "Explanatory note",
            "title": "Note",
            "type": "string"
          },
          "solar_component_m": {
            "description": "Solar component of equilibrium tide (meters)",
            "title": "Solar Component M",
            "type": "number"
          }
        },
        "required": [
          "lunar_component_m",
          "solar_component_m",
          "combined_m",
          "note"
        ],
        "title": "EquilibriumTide",
        "type": "object"
      },
      "EssentialDignityInfo": {
        "additionalProperties": true,
        "description": "Essential dignity information for a planet.",
        "properties": {
          "debilities_held": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              }
            ],
            "description": "List of debilities present",
            "title": "Debilities Held"
          },
          "detriment": {
            "description": "Planet is in detriment",
            "title": "Detriment",
            "type": "boolean"
          },
          "dignities_held": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              }
            ],
            "description": "List of dignities present",
            "title": "Dignities Held"
          },
          "dignity_score": {
            "description": "Aggregate essential dignity score",
            "title": "Dignity Score",
            "type": "number"
          },
          "domicile": {
            "description": "Planet holds domicile (rulership)",
            "title": "Domicile",
            "type": "boolean"
          },
          "effective_score": {
            "description": "Final dignity score after motion modifiers are applied.",
            "readOnly": true,
            "title": "Effective Score",
            "type": "number"
          },
          "exaltation": {
            "description": "Planet holds exaltation",
            "title": "Exaltation",
            "type": "boolean"
          },
          "exaltation_score": {
            "default": 0,
            "description": "Score contribution from exaltation",
            "example": 4,
            "title": "Exaltation Score",
            "type": "integer"
          },
          "face": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Face (decan) ruler holding dignity",
            "title": "Face"
          },
          "face_score": {
            "default": 0,
            "description": "Score contribution from decan (face) dignity",
            "example": 1,
            "title": "Face Score",
            "type": "integer"
          },
          "fall": {
            "description": "Planet is in fall",
            "title": "Fall",
            "type": "boolean"
          },
          "motion_modifier": {
            "default": 0,
            "description": "Score modifier applied due to motion state. Negative values weaken the raw dignity score.",
            "title": "Motion Modifier",
            "type": "number"
          },
          "motion_state": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Motion state used for dignity adjustments (direct, retrograde, stationary, unknown)",
            "title": "Motion State"
          },
          "planet": {
            "description": "Planet name",
            "title": "Planet",
            "type": "string"
          },
          "ruler": {
            "description": "Backward-compatible alias for domicile field.",
            "readOnly": true,
            "title": "Ruler",
            "type": "boolean"
          },
          "rulership_score": {
            "default": 0,
            "description": "Score contribution from domicile (rulership) dignity",
            "example": 5,
            "title": "Rulership Score",
            "type": "integer"
          },
          "sign": {
            "description": "Current sign",
            "title": "Sign",
            "type": "string"
          },
          "strength": {
            "description": "Dignity strength category",
            "title": "Strength",
            "type": "string"
          },
          "term": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Egyptian term ruler holding dignity",
            "title": "Term"
          },
          "term_score": {
            "default": 0,
            "description": "Score contribution from Egyptian terms",
            "example": 2,
            "title": "Term Score",
            "type": "integer"
          },
          "triplicity": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Triplicity mode where planet has dignity (day/night)",
            "title": "Triplicity"
          },
          "triplicity_score": {
            "default": 0,
            "description": "Score contribution from triplicity rulers",
            "example": 3,
            "title": "Triplicity Score",
            "type": "integer"
          },
          "warnings": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              }
            ],
            "description": "Non-fatal warnings encountered while deriving dignity metadata.",
            "title": "Warnings"
          }
        },
        "required": [
          "planet",
          "sign",
          "domicile",
          "exaltation",
          "detriment",
          "fall",
          "dignity_score",
          "strength",
          "ruler",
          "effective_score"
        ],
        "title": "EssentialDignityInfo",
        "type": "object"
      },
      "FirdariaRequest": {
        "description": "Input for firdaria (planetary period) calculation. Requires the natal birth datetime and whether the native was born during the day (Sun above horizon = diurnal) or at night (nocturnal). The day/night distinction determines which planet begins the 75-year cycle.",
        "properties": {
          "birth_datetime": {
            "description": "Natal birth datetime in ISO 8601 UTC format.",
            "format": "date-time",
            "title": "Birth Datetime",
            "type": "string"
          },
          "house_system": {
            "description": "Optional.",
            "type": "string"
          },
          "is_day_birth": {
            "description": "True if the native was born during the day (Sun above the horizon). Determines the diurnal vs nocturnal firdaria sequence. In diurnal charts, the Sun leads; in nocturnal charts, the Moon leads.",
            "title": "Is Day Birth",
            "type": "boolean"
          },
          "latitude": {
            "description": "Optional. If provided, calculates natal chart to determine ascendant/sect/lots.",
            "maximum": 90,
            "minimum": -90,
            "type": "number"
          },
          "longitude": {
            "description": "Optional.",
            "maximum": 180,
            "minimum": -180,
            "type": "number"
          },
          "target_datetime": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              }
            ],
            "description": "Date to evaluate the active period for. Defaults to the current date if omitted.",
            "title": "Target Datetime"
          }
        },
        "required": [
          "birth_datetime",
          "is_day_birth"
        ],
        "title": "FirdariaRequest",
        "type": "object"
      },
      "FirdariaResponse": {
        "description": "Firdaria planetary periods result — active period, current sub-period, and the full 75-year timeline.",
        "properties": {
          "all_periods": {
            "description": "Complete 75-year firdaria timeline with all major periods and their sub-periods.",
            "items": {
              "properties": {
                "duration_years": {
                  "type": "number"
                },
                "end_date": {
                  "format": "date-time",
                  "type": "string"
                },
                "is_active": {
                  "description": "True if this is the currently active major period.",
                  "type": "boolean"
                },
                "planet": {
                  "type": "string"
                },
                "start_date": {
                  "format": "date-time",
                  "type": "string"
                },
                "sub_periods": {
                  "items": {
                    "properties": {
                      "end_date": {
                        "format": "date-time",
                        "type": "string"
                      },
                      "is_active": {
                        "type": "boolean"
                      },
                      "planet": {
                        "type": "string"
                      },
                      "start_date": {
                        "format": "date-time",
                        "type": "string"
                      }
                    },
                    "type": "object"
                  },
                  "type": "array"
                }
              },
              "type": "object"
            },
            "title": "All Periods",
            "type": "array"
          },
          "birth_datetime": {
            "description": "Birth datetime used for the calculation.",
            "type": "string"
          },
          "current_period": {
            "description": "The major and sub-period active at the target date.",
            "properties": {
              "duration_years": {
                "description": "Duration of the major period in years.",
                "type": "number"
              },
              "end_date": {
                "description": "End of the major period.",
                "format": "date-time",
                "type": "string"
              },
              "planet": {
                "description": "Major period ruling planet.",
                "type": "string"
              },
              "start_date": {
                "description": "Start of the major period.",
                "format": "date-time",
                "type": "string"
              },
              "sub_period": {
                "description": "Active sub-period within the current major period.",
                "properties": {
                  "end_date": {
                    "format": "date-time",
                    "type": "string"
                  },
                  "planet": {
                    "description": "Sub-period ruling planet.",
                    "type": "string"
                  },
                  "start_date": {
                    "format": "date-time",
                    "type": "string"
                  }
                },
                "type": "object"
              }
            },
            "title": "Current Period",
            "type": "object"
          },
          "is_day_birth": {
            "description": "Whether the native is diurnal (day birth).",
            "type": "boolean"
          },
          "output_mode": {
            "description": "Output projection mode (json | llm).",
            "nullable": true,
            "type": "string"
          },
          "success": {
            "description": "Whether the calculation succeeded.",
            "title": "Success",
            "type": "boolean"
          }
        },
        "required": [
          "success",
          "current_period",
          "all_periods"
        ],
        "title": "FirdariaResponse",
        "type": "object"
      },
      "FixedStarCalculationResult": {
        "additionalProperties": false,
        "description": "Single fixed star calculation result.",
        "properties": {
          "constellation": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Constellation",
            "title": "Constellation"
          },
          "distance": {
            "description": "Distance in AU",
            "title": "Distance",
            "type": "number"
          },
          "latitude": {
            "description": "Ecliptic latitude in degrees",
            "title": "Latitude",
            "type": "number"
          },
          "longitude": {
            "description": "Ecliptic longitude in degrees",
            "title": "Longitude",
            "type": "number"
          },
          "magnitude": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "description": "Visual magnitude",
            "title": "Magnitude"
          },
          "name": {
            "description": "Star name",
            "title": "Name",
            "type": "string"
          },
          "spectral_class": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Spectral classification",
            "title": "Spectral Class"
          },
          "speed_latitude": {
            "description": "Speed in latitude (degrees/day)",
            "title": "Speed Latitude",
            "type": "number"
          },
          "speed_longitude": {
            "description": "Speed in longitude (degrees/day)",
            "title": "Speed Longitude",
            "type": "number"
          },
          "traditional_name": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Traditional/alternative name",
            "title": "Traditional Name"
          }
        },
        "required": [
          "name",
          "longitude",
          "latitude",
          "distance",
          "speed_longitude",
          "speed_latitude"
        ],
        "title": "FixedStarCalculationResult",
        "type": "object"
      },
      "FixedStarCatalogEnum": {
        "description": "Fixed star catalog snapshots.",
        "enum": [
          "bright_mag3",
          "bright_mag5",
          "royal_stars",
          "parans_key"
        ],
        "title": "FixedStarCatalogEnum",
        "type": "string"
      },
      "FixedStarConfig": {
        "additionalProperties": false,
        "description": "Configuration for fixed star calculations.",
        "example": {
          "catalog_version": "bright_mag5",
          "include": true,
          "magnitude_limit": 5.5,
          "orb": 2,
          "stars": [
            "Regulus",
            "Spica"
          ]
        },
        "properties": {
          "catalog_version": {
            "allOf": [
              {
                "$ref": "#/components/schemas/FixedStarCatalogEnum"
              }
            ],
            "default": "bright_mag5",
            "description": "Catalog snapshot identifier"
          },
          "include": {
            "default": false,
            "description": "Toggle fixed star conjunction calculations",
            "title": "Include",
            "type": "boolean"
          },
          "magnitude_limit": {
            "default": 6,
            "description": "Maximum magnitude (lower = brighter)",
            "maximum": 10,
            "minimum": 0,
            "title": "Magnitude Limit",
            "type": "number"
          },
          "orb": {
            "default": 2,
            "description": "Orb in degrees for fixed star hits",
            "maximum": 5,
            "minimum": 0.1,
            "title": "Orb",
            "type": "number"
          },
          "stars": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              }
            ],
            "description": "Optional whitelist of fixed stars to evaluate",
            "title": "Stars"
          }
        },
        "title": "FixedStarConfig",
        "type": "object"
      },
      "FixedStarConjunctionResponse": {
        "additionalProperties": false,
        "description": "Fixed star conjunction result.",
        "properties": {
          "exact": {
            "description": "Whether orb is below exact threshold",
            "title": "Exact",
            "type": "boolean"
          },
          "interpretation_hint": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Quick interpretation keyword",
            "title": "Interpretation Hint"
          },
          "orb": {
            "description": "Orb in degrees",
            "title": "Orb",
            "type": "number"
          },
          "planet": {
            "description": "Planet name",
            "title": "Planet",
            "type": "string"
          },
          "planet_longitude": {
            "description": "Planet longitude in degrees",
            "title": "Planet Longitude",
            "type": "number"
          },
          "star": {
            "description": "Fixed star name",
            "title": "Star",
            "type": "string"
          },
          "star_longitude": {
            "description": "Star longitude in degrees",
            "title": "Star Longitude",
            "type": "number"
          }
        },
        "required": [
          "star",
          "planet",
          "orb",
          "exact",
          "star_longitude",
          "planet_longitude"
        ],
        "title": "FixedStarConjunctionResponse",
        "type": "object"
      },
      "FixedStarPositionResponse": {
        "additionalProperties": false,
        "description": "Formatted fixed star position payload.",
        "properties": {
          "constellation": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Constellation",
            "title": "Constellation"
          },
          "distance_light_years": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "description": "Distance in light years",
            "title": "Distance Light Years"
          },
          "julian_day": {
            "anyOf": [
              {
                "format": "double",
                "type": "number"
              }
            ],
            "description": "Julian Day of calculation",
            "title": "Julian Day"
          },
          "latitude": {
            "description": "Latitude in degrees",
            "title": "Latitude",
            "type": "number"
          },
          "longitude": {
            "description": "Current longitude in degrees",
            "title": "Longitude",
            "type": "number"
          },
          "magnitude": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "description": "Apparent magnitude",
            "title": "Magnitude"
          },
          "name": {
            "description": "Fixed star name",
            "title": "Name",
            "type": "string"
          },
          "sign_longitude": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "description": "Longitude within sign",
            "title": "Sign Longitude"
          },
          "sign_name": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Zodiac sign",
            "title": "Sign Name"
          },
          "sign_symbol": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Zodiac sign symbol",
            "title": "Sign Symbol"
          },
          "spectral_class": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Spectral classification",
            "title": "Spectral Class"
          },
          "traditional_name": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Traditional name",
            "title": "Traditional Name"
          }
        },
        "required": [
          "name",
          "longitude",
          "latitude"
        ],
        "title": "FixedStarPositionResponse",
        "type": "object"
      },
      "FixedStarsCalculationRequest": {
        "additionalProperties": false,
        "description": "Request for fixed star position calculations.",
        "example": {
          "date_time": {
            "iso": "2023-12-07T15:30:00Z"
          },
          "min_magnitude": 2,
          "star_names": [
            "Regulus",
            "Spica",
            "Aldebaran"
          ]
        },
        "properties": {
          "date_time": {
            "allOf": [
              {
                "$ref": "#/components/schemas/DateTimeInput"
              }
            ],
            "description": "Datetime for calculation (ISO, components, or Julian day)"
          },
          "max_magnitude": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "description": "Filter stars by maximum magnitude",
            "title": "Max Magnitude"
          },
          "min_magnitude": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "description": "Filter stars by minimum magnitude (lower = brighter)",
            "title": "Min Magnitude"
          },
          "star_groups": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              }
            ],
            "description": "Predefined star groups (royal_stars, behenian, navigational, foundation_24, galactic)",
            "title": "Star Groups"
          },
          "star_names": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              }
            ],
            "description": "Specific fixed stars to calculate. Accepts catalog/display names (e.g., 'Regulus') and catalog ids (e.g., 'regulus', 'deneb_adige').",
            "title": "Star Names"
          },
          "strict_catalog_ids": {
            "default": false,
            "description": "When true, reject any unknown star/group identifier instead of silently skipping. Use /catalogs/fixed-stars and /catalogs/fixed-stars/groups to discover valid identifiers.",
            "title": "Strict Catalog Ids",
            "type": "boolean"
          }
        },
        "required": [
          "date_time"
        ],
        "title": "FixedStarsCalculationRequest",
        "type": "object"
      },
      "FixedStarsCalculationResponse": {
        "additionalProperties": false,
        "description": "Response from fixed stars calculation endpoint.",
        "properties": {
          "calculation_time": {
            "description": "Timestamp of calculation",
            "format": "date-time",
            "title": "Calculation Time",
            "type": "string"
          },
          "julian_day": {
            "description": "Julian Day used for calculation",
            "format": "double",
            "title": "Julian Day",
            "type": "number"
          },
          "metadata": {
            "anyOf": [
              {
                "type": "object"
              }
            ],
            "description": "Additional calculation metadata",
            "title": "Metadata"
          },
          "stars": {
            "description": "Calculated star positions",
            "items": {
              "$ref": "#/components/schemas/FixedStarCalculationResult"
            },
            "title": "Stars",
            "type": "array"
          },
          "success": {
            "default": true,
            "description": "Calculation success status",
            "title": "Success",
            "type": "boolean"
          }
        },
        "required": [
          "stars",
          "calculation_time",
          "julian_day"
        ],
        "title": "FixedStarsCalculationResponse",
        "type": "object"
      },
      "FixedStarsMetadata": {
        "additionalProperties": true,
        "description": "Metadata describing fixed star calculation.",
        "properties": {
          "available_catalog": {
            "description": "Whether built-in star catalog was available",
            "title": "Available Catalog",
            "type": "boolean"
          },
          "calculation_duration_ms": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "description": "Computation time in milliseconds",
            "title": "Calculation Duration Ms"
          },
          "calculation_time": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "ISO8601 timestamp of calculation",
            "title": "Calculation Time"
          },
          "error": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Optional error description if calculation degraded",
            "title": "Error"
          },
          "magnitude_limit": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "description": "Magnitude limit applied",
            "title": "Magnitude Limit"
          },
          "missing_stars": {
            "description": "Stars requested but unavailable",
            "items": {
              "type": "string"
            },
            "title": "Missing Stars",
            "type": "array"
          },
          "orb_used": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "description": "Orb used for conjunction detection",
            "title": "Orb Used"
          },
          "requested_star_count": {
            "description": "Number of stars requested",
            "title": "Requested Star Count",
            "type": "integer"
          },
          "selected_stars_count": {
            "description": "Count of Foundation 24 stars returned",
            "title": "Selected Stars Count",
            "type": "integer"
          },
          "total_stars_calculated": {
            "description": "Number of stars calculated",
            "title": "Total Stars Calculated",
            "type": "integer"
          }
        },
        "required": [
          "requested_star_count",
          "total_stars_calculated",
          "selected_stars_count",
          "available_catalog"
        ],
        "title": "FixedStarsMetadata",
        "type": "object"
      },
      "FixedStarsResponse": {
        "additionalProperties": false,
        "description": "Container for fixed star positions and conjunctions.",
        "properties": {
          "conjunctions": {
            "description": "Star-planet conjunctions",
            "items": {
              "$ref": "#/components/schemas/FixedStarConjunctionResponse"
            },
            "title": "Conjunctions",
            "type": "array"
          },
          "metadata": {
            "allOf": [
              {
                "$ref": "#/components/schemas/FixedStarsMetadata"
              }
            ],
            "description": "Calculation metadata"
          },
          "positions": {
            "description": "Calculated star positions",
            "items": {
              "$ref": "#/components/schemas/FixedStarPositionResponse"
            },
            "title": "Positions",
            "type": "array"
          }
        },
        "required": [
          "positions",
          "conjunctions",
          "metadata"
        ],
        "title": "FixedStarsResponse",
        "type": "object"
      },
      "ForcingIndices": {
        "properties": {
          "diurnal_class": {
            "description": "Tidal regime classification",
            "title": "Diurnal Class",
            "type": "string"
          },
          "diurnal_inequality": {
            "description": "Diurnal inequality value",
            "title": "Diurnal Inequality",
            "type": "number"
          },
          "king_tide_risk": {
            "description": "King tide risk score (0 to 1)",
            "title": "King Tide Risk",
            "type": "number"
          },
          "perigee_proximity": {
            "description": "Perigee proximity score (0 to 1)",
            "title": "Perigee Proximity",
            "type": "number"
          },
          "spring_neap_index": {
            "description": "Spring-neap index (-1 to +1)",
            "title": "Spring Neap Index",
            "type": "number"
          },
          "syzygy_status": {
            "description": "Syzygy status",
            "title": "Syzygy Status",
            "type": "string"
          },
          "total_forcing": {
            "description": "Total tidal forcing score",
            "title": "Total Forcing",
            "type": "number"
          }
        },
        "required": [
          "spring_neap_index",
          "syzygy_status",
          "diurnal_inequality",
          "diurnal_class",
          "total_forcing",
          "king_tide_risk",
          "perigee_proximity"
        ],
        "title": "ForcingIndices",
        "type": "object"
      },
      "HDActivation": {
        "description": "Single gate activation.",
        "properties": {
          "base": {
            "title": "Base",
            "type": "integer"
          },
          "color": {
            "title": "Color",
            "type": "integer"
          },
          "color_label": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "title": "Color Label"
          },
          "context": {
            "title": "Context",
            "type": "string"
          },
          "gate": {
            "title": "Gate",
            "type": "integer"
          },
          "line": {
            "title": "Line",
            "type": "integer"
          },
          "planet": {
            "title": "Planet",
            "type": "string"
          },
          "tone": {
            "title": "Tone",
            "type": "integer"
          },
          "tone_label": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "title": "Tone Label"
          }
        },
        "required": [
          "gate",
          "line",
          "color",
          "tone",
          "base",
          "planet",
          "context"
        ],
        "title": "HDActivation",
        "type": "object"
      },
      "HDChannel": {
        "description": "Defines a channel connection.",
        "properties": {
          "centers": {
            "items": {
              "type": "string"
            },
            "title": "Centers",
            "type": "array"
          },
          "gates": {
            "items": {
              "type": "integer"
            },
            "title": "Gates",
            "type": "array"
          },
          "id": {
            "title": "Id",
            "type": "string"
          },
          "name": {
            "title": "Name",
            "type": "string"
          }
        },
        "required": [
          "id",
          "name",
          "gates",
          "centers"
        ],
        "title": "HDChannel",
        "type": "object"
      },
      "HDConnectionChannel": {
        "description": "Analysis of a single channel in a relationship.",
        "properties": {
          "compromised_gate": {
            "anyOf": [
              {
                "type": "integer"
              }
            ],
            "title": "Compromised Gate"
          },
          "defined_by": {
            "title": "Defined By",
            "type": "string"
          },
          "id": {
            "title": "Id",
            "type": "string"
          },
          "name": {
            "title": "Name",
            "type": "string"
          },
          "type": {
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "id",
          "name",
          "type",
          "defined_by"
        ],
        "title": "HDConnectionChannel",
        "type": "object"
      },
      "HDVariables": {
        "description": "The 4 Transformations (Color/Tone Summary).",
        "properties": {
          "awareness": {
            "title": "Awareness",
            "type": "string"
          },
          "digestion": {
            "title": "Digestion",
            "type": "string"
          },
          "environment": {
            "title": "Environment",
            "type": "string"
          },
          "perspective": {
            "title": "Perspective",
            "type": "string"
          },
          "string": {
            "description": "The code, e.g. 'PLL DLL'",
            "title": "String",
            "type": "string"
          }
        },
        "required": [
          "string",
          "digestion",
          "environment",
          "perspective",
          "awareness"
        ],
        "title": "HDVariables",
        "type": "object"
      },
      "HTTPValidationError": {
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ValidationError"
            },
            "title": "Detail",
            "type": "array"
          }
        },
        "title": "HTTPValidationError",
        "type": "object"
      },
      "HarmonicConjunction": {
        "properties": {
          "harmonic": {
            "description": "Harmonic number",
            "title": "Harmonic",
            "type": "integer"
          },
          "midpoint": {
            "description": "Midpoint longitude of the conjunction",
            "title": "Midpoint",
            "type": "number"
          },
          "orb": {
            "description": "Angular separation in degrees",
            "title": "Orb",
            "type": "number"
          },
          "planet1": {
            "description": "First planet ID",
            "title": "Planet1",
            "type": "integer"
          },
          "planet2": {
            "description": "Second planet ID",
            "title": "Planet2",
            "type": "integer"
          }
        },
        "title": "HarmonicConjunction",
        "type": "object"
      },
      "HarmonicPosition": {
        "properties": {
          "harmonic": {
            "description": "Harmonic number used",
            "title": "Harmonic",
            "type": "integer"
          },
          "longitude": {
            "description": "Harmonic longitude [0, 360)",
            "title": "Longitude",
            "type": "number"
          },
          "natal_longitude": {
            "description": "Original natal longitude",
            "title": "Natal Longitude",
            "type": "number"
          },
          "planet_id": {
            "description": "Planet/body ID",
            "title": "Planet Id",
            "type": "integer"
          },
          "planet_name": {
            "description": "Human-readable planet name",
            "title": "Planet Name",
            "type": "string"
          },
          "sign": {
            "description": "Zodiac sign name at harmonic longitude",
            "title": "Sign",
            "type": "string"
          },
          "sign_degree": {
            "description": "Degree within sign [0, 30)",
            "title": "Sign Degree",
            "type": "number"
          }
        },
        "title": "HarmonicPosition",
        "type": "object"
      },
      "HarmonicsRequest": {
        "properties": {
          "bodies": {
            "description": "Array of celestial body positions with id and longitude.",
            "items": {
              "$ref": "#/components/schemas/HarmonicsRequestBody"
            },
            "title": "Bodies",
            "type": "array"
          },
          "harmonic": {
            "description": "Harmonic number (1–360). H1 = natal, H5 = quintile, H9 = navamsa.",
            "maximum": 360,
            "minimum": 1,
            "title": "Harmonic",
            "type": "integer"
          },
          "orb": {
            "default": 8,
            "description": "Orb in degrees for conjunction detection in the harmonic chart.",
            "title": "Orb",
            "type": "number"
          }
        },
        "required": [
          "bodies",
          "harmonic"
        ],
        "title": "HarmonicsRequest",
        "type": "object"
      },
      "HarmonicsRequestBody": {
        "properties": {
          "id": {
            "description": "Planet/body ID (e.g. 0=Sun, 1=Moon, …)",
            "title": "Id",
            "type": "integer"
          },
          "longitude": {
            "description": "Ecliptic longitude in decimal degrees [0, 360)",
            "title": "Longitude",
            "type": "number"
          }
        },
        "required": [
          "id",
          "longitude"
        ],
        "title": "HarmonicsRequestBody",
        "type": "object"
      },
      "HarmonicsResponse": {
        "properties": {
          "calculation_metadata": {
            "description": "Metadata about the calculation",
            "properties": {
              "computation_time_ms": {
                "description": "Computation time in milliseconds",
                "title": "Computation Time Ms",
                "type": "number"
              },
              "engine": {
                "description": "Calculation engine used",
                "title": "Engine",
                "type": "string"
              }
            },
            "title": "Calculation Metadata",
            "type": "object"
          },
          "conjunctions": {
            "description": "Conjunctions found in the harmonic chart",
            "items": {
              "$ref": "#/components/schemas/HarmonicConjunction"
            },
            "title": "Conjunctions",
            "type": "array"
          },
          "harmonic": {
            "description": "The harmonic number that was calculated",
            "title": "Harmonic",
            "type": "integer"
          },
          "positions": {
            "description": "Harmonic positions for each body",
            "items": {
              "$ref": "#/components/schemas/HarmonicPosition"
            },
            "title": "Positions",
            "type": "array"
          },
          "significance": {
            "description": "Astrological significance of this harmonic",
            "title": "Significance",
            "type": "string"
          }
        },
        "title": "HarmonicsResponse",
        "type": "object"
      },
      "HealthResponse": {
        "additionalProperties": false,
        "description": "API health check response.",
        "properties": {
          "ephemeris_available": {
            "description": "Whether ephemeris files are available",
            "title": "Ephemeris Available",
            "type": "boolean"
          },
          "status": {
            "default": "healthy",
            "description": "Service status",
            "title": "Status",
            "type": "string"
          },
          "uptime": {
            "description": "Service uptime in seconds",
            "title": "Uptime",
            "type": "number"
          },
          "version": {
            "description": "API version",
            "title": "Version",
            "type": "string"
          }
        },
        "required": [
          "version",
          "ephemeris_available",
          "uptime"
        ],
        "title": "HealthResponse",
        "type": "object"
      },
      "HeatmapScoreRequestPayload": {
        "properties": {
          "epoch": {
            "description": "ISO-8601 birth date/time",
            "type": "string"
          },
          "jd": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "string"
              }
            ],
            "description": "Julian Day for the birth chart (if no epoch or natal provided)"
          },
          "natal": {
            "$ref": "#/components/schemas/ACGNatalRequest"
          },
          "resolution": {
            "description": "Grid resolution step in degrees (e.g., 2 for 2x2 deg grid). Default is 2.",
            "type": "number"
          },
          "target_epoch": {
            "description": "Optional ISO-8601 target transit date instead of target_jd.",
            "type": "string"
          },
          "target_jd": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "string"
              }
            ],
            "description": "Optional. Julian Day for transits. If provided, computes a Transit (Cyclocartography) heatmap for this date against natal relocated angles."
          },
          "theme": {
            "description": "The objective/theme for the heatmap scoring.",
            "enum": [
              "love",
              "career",
              "wealth",
              "healing"
            ],
            "type": "string"
          }
        },
        "required": [
          "theme"
        ],
        "type": "object"
      },
      "HermeticLotResponse": {
        "description": "Hermetic lot payload trimmed for public API.",
        "properties": {
          "canonical_name": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Canonical Arabic part registry key for this Hermetic lot",
            "title": "Canonical Name"
          },
          "degree_symbol": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Degree display",
            "title": "Degree Symbol"
          },
          "display_name": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Human-friendly display name",
            "title": "Display Name"
          },
          "formula_used": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Formula identifier that resolved for this lot",
            "title": "Formula Used"
          },
          "house": {
            "anyOf": [
              {
                "type": "integer"
              }
            ],
            "description": "House position (1-12)",
            "title": "House"
          },
          "longitude": {
            "description": "Longitude in degrees",
            "title": "Longitude",
            "type": "number"
          },
          "name": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Prefixed Hermetic lot identifier (lot_*) to avoid naming collisions",
            "title": "Name"
          },
          "sign": {
            "description": "Zodiac sign",
            "title": "Sign",
            "type": "string"
          },
          "sign_longitude": {
            "description": "Longitude within sign",
            "title": "Sign Longitude",
            "type": "number"
          },
          "sign_symbol": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Zodiac sign symbol",
            "title": "Sign Symbol"
          }
        },
        "required": [
          "longitude",
          "sign",
          "sign_longitude"
        ],
        "title": "HermeticLotResponse",
        "type": "object"
      },
      "HermeticLotResult": {
        "additionalProperties": false,
        "description": "Single Hermetic lot position and metadata.",
        "properties": {
          "canonical_name": {
            "description": "Internal canonical lot identifier",
            "title": "Canonical Name",
            "type": "string"
          },
          "degree_in_sign": {
            "description": "Degrees within the zodiac sign (0-30)",
            "title": "Degree In Sign",
            "type": "number"
          },
          "description": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Lot meaning and interpretation",
            "title": "Description"
          },
          "display_name": {
            "description": "Formatted display name",
            "title": "Display Name",
            "type": "string"
          },
          "formula": {
            "description": "Calculation formula description",
            "title": "Formula",
            "type": "string"
          },
          "house": {
            "anyOf": [
              {
                "type": "integer"
              }
            ],
            "description": "House number (1-12) if applicable",
            "title": "House"
          },
          "keywords": {
            "description": "Thematic keywords",
            "items": {
              "type": "string"
            },
            "title": "Keywords",
            "type": "array"
          },
          "longitude": {
            "description": "Absolute ecliptic longitude in degrees (0-360)",
            "title": "Longitude",
            "type": "number"
          },
          "name": {
            "description": "Display name of the lot",
            "title": "Name",
            "type": "string"
          },
          "sign": {
            "description": "Zodiac sign name",
            "title": "Sign",
            "type": "string"
          },
          "sign_symbol": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Unicode zodiac sign symbol",
            "title": "Sign Symbol"
          },
          "traditional_source": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Traditional source reference",
            "title": "Traditional Source"
          }
        },
        "required": [
          "canonical_name",
          "name",
          "display_name",
          "longitude",
          "sign",
          "degree_in_sign",
          "formula"
        ],
        "title": "HermeticLotResult",
        "type": "object"
      },
      "HermeticLotsCalculationRequest": {
        "additionalProperties": false,
        "description": "Request for calculating Hermetic lots (Fortune Suite + optional/legacy).",
        "example": {
          "date_time": {
            "iso": "1985-06-15T14:30:00Z"
          },
          "include_legacy": false,
          "include_optional": false,
          "latitude": 40.7128,
          "longitude": -74.006
        },
        "properties": {
          "date_time": {
            "allOf": [
              {
                "$ref": "#/components/schemas/DateTimeInput"
              }
            ],
            "description": "Chart calculation datetime in ISO, components, or Julian day format",
            "example": {
              "iso": "2000-01-01T12:00:00Z"
            }
          },
          "include_legacy": {
            "default": false,
            "description": "Include legacy Hermetic lots previously in canonical catalog",
            "title": "Include Legacy",
            "type": "boolean"
          },
          "include_optional": {
            "default": false,
            "description": "Include optional catalog lots beyond Fortune Suite defaults",
            "title": "Include Optional",
            "type": "boolean"
          },
          "latitude": {
            "description": "Observer latitude in decimal degrees",
            "example": 40.7128,
            "maximum": 90,
            "minimum": -90,
            "title": "Latitude",
            "type": "number"
          },
          "longitude": {
            "description": "Observer longitude in decimal degrees",
            "example": -74.006,
            "maximum": 180,
            "minimum": -180,
            "title": "Longitude",
            "type": "number"
          }
        },
        "required": [
          "date_time",
          "latitude",
          "longitude"
        ],
        "title": "HermeticLotsCalculationRequest",
        "type": "object"
      },
      "HermeticLotsCalculationResponse": {
        "additionalProperties": false,
        "description": "Response from Hermetic lots calculation endpoint.",
        "properties": {
          "lots": {
            "description": "Calculated Hermetic lots",
            "items": {
              "$ref": "#/components/schemas/HermeticLotResult"
            },
            "title": "Lots",
            "type": "array"
          },
          "metadata": {
            "description": "Calculation metadata, sect determination, and settings",
            "title": "Metadata",
            "type": "object"
          },
          "success": {
            "default": true,
            "description": "Calculation success status",
            "title": "Success",
            "type": "boolean"
          }
        },
        "required": [
          "lots",
          "metadata"
        ],
        "title": "HermeticLotsCalculationResponse",
        "type": "object"
      },
      "HermeticLotsMetadata": {
        "additionalProperties": true,
        "description": "Summary metadata describing Hermetic lot calculations.",
        "properties": {
          "calculation_time_ms": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "description": "Computation time for Hermetic lot calculation in milliseconds",
            "title": "Calculation Time Ms"
          },
          "formulas_used": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              }
            ],
            "description": "Ordered list of formula identifiers executed for the returned lots",
            "title": "Formulas Used"
          },
          "hermetic_lot_names": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              }
            ],
            "description": "Hermetic lot identifiers included in the payload",
            "title": "Hermetic Lot Names"
          },
          "sect_determination": {
            "anyOf": [
              {
                "type": "object"
              }
            ],
            "description": "Sect determination context used when resolving formulas",
            "title": "Sect Determination"
          },
          "total_lots_calculated": {
            "anyOf": [
              {
                "type": "integer"
              }
            ],
            "description": "Number of Hermetic lots returned",
            "title": "Total Lots Calculated"
          }
        },
        "title": "HermeticLotsMetadata",
        "type": "object"
      },
      "HorizonEvents": {
        "properties": {
          "moonrise": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "ISO 8601 UTC moonrise time",
            "title": "Moonrise"
          },
          "moonset": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "ISO 8601 UTC moonset time",
            "title": "Moonset"
          },
          "polar": {
            "description": "True if location experiences polar day/night",
            "title": "Polar",
            "type": "boolean"
          },
          "sunrise": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "ISO 8601 UTC sunrise time",
            "title": "Sunrise"
          },
          "sunset": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "ISO 8601 UTC sunset time",
            "title": "Sunset"
          }
        },
        "required": [
          "polar"
        ],
        "title": "HorizonEvents",
        "type": "object"
      },
      "HouseCuspsRequest": {
        "additionalProperties": false,
        "description": "Request for house cusp calculations (granular endpoint).",
        "example": {
          "date_time": {
            "iso": "2025-12-11T12:00:00Z"
          },
          "house_systems": [
            "P",
            "W"
          ],
          "latitude": 40.7128,
          "longitude": -74.006
        },
        "properties": {
          "date_time": {
            "allOf": [
              {
                "$ref": "#/components/schemas/DateTimeInput"
              }
            ],
            "description": "Calculation datetime"
          },
          "house_systems": {
            "description": "House system codes to compute (1-5 entries)",
            "example": [
              "P"
            ],
            "items": {
              "type": "string"
            },
            "title": "House Systems",
            "type": "array"
          },
          "latitude": {
            "description": "Observer latitude in decimal degrees",
            "maximum": 90,
            "minimum": -90,
            "title": "Latitude",
            "type": "number"
          },
          "longitude": {
            "description": "Observer longitude in decimal degrees",
            "maximum": 180,
            "minimum": -180,
            "title": "Longitude",
            "type": "number"
          }
        },
        "required": [
          "date_time",
          "latitude",
          "longitude"
        ],
        "title": "HouseCuspsRequest",
        "type": "object"
      },
      "HouseCuspsResponse": {
        "additionalProperties": false,
        "description": "Response from house cusps granular endpoint.",
        "properties": {
          "house_systems": {
            "description": "House cusp results",
            "items": {
              "$ref": "#/components/schemas/HouseCuspsSystemResult"
            },
            "title": "House Systems",
            "type": "array"
          },
          "metadata": {
            "description": "Calculation metadata",
            "title": "Metadata",
            "type": "object"
          },
          "success": {
            "default": true,
            "description": "Calculation success status",
            "title": "Success",
            "type": "boolean"
          }
        },
        "required": [
          "house_systems",
          "metadata"
        ],
        "title": "HouseCuspsResponse",
        "type": "object"
      },
      "HouseCuspsSystemResult": {
        "additionalProperties": true,
        "description": "House cusp result for a single system.",
        "properties": {
          "cusps": {
            "description": "House cusps (12 values, degrees 0-360)",
            "items": {
              "type": "number"
            },
            "title": "Cusps",
            "type": "array"
          },
          "system_code": {
            "description": "House system code",
            "title": "System Code",
            "type": "string"
          },
          "system_name": {
            "description": "Human-readable house system name",
            "title": "System Name",
            "type": "string"
          }
        },
        "required": [
          "system_code",
          "system_name",
          "cusps"
        ],
        "title": "HouseCuspsSystemResult",
        "type": "object"
      },
      "HouseSystemEnum": {
        "description": "Supported house systems.",
        "enum": [
          "P",
          "K",
          "O",
          "R",
          "C",
          "E",
          "W"
        ],
        "title": "HouseSystemEnum",
        "type": "string"
      },
      "HousesResponse": {
        "additionalProperties": true,
        "description": "House system data in response.",
        "properties": {
          "cusps": {
            "description": "House cusp longitudes in degrees",
            "items": {
              "type": "number"
            },
            "title": "Cusps",
            "type": "array"
          },
          "system": {
            "description": "House system code",
            "title": "System",
            "type": "string"
          }
        },
        "required": [
          "system",
          "cusps"
        ],
        "title": "HousesResponse",
        "type": "object"
      },
      "HumanDesignChartData": {
        "description": "The core chart data.",
        "properties": {
          "activations": {
            "items": {
              "$ref": "#/components/schemas/HDActivation"
            },
            "title": "Activations",
            "type": "array"
          },
          "authority": {
            "description": "Deprecated placeholder; intentionally empty in computation-only responses.",
            "title": "Authority",
            "type": "string"
          },
          "centers": {
            "additionalProperties": {
              "type": "boolean"
            },
            "title": "Centers",
            "type": "object"
          },
          "channels": {
            "items": {
              "$ref": "#/components/schemas/HDChannel"
            },
            "title": "Channels",
            "type": "array"
          },
          "definition": {
            "description": "Deprecated placeholder; intentionally empty in computation-only responses.",
            "title": "Definition",
            "type": "string"
          },
          "design": {
            "title": "Design",
            "type": "object"
          },
          "incarnation_cross": {
            "description": "Deprecated placeholder; intentionally empty in computation-only responses.",
            "title": "Incarnation Cross",
            "type": "string"
          },
          "personality": {
            "title": "Personality",
            "type": "object"
          },
          "profile": {
            "description": "Deprecated placeholder; intentionally empty in computation-only responses.",
            "title": "Profile",
            "type": "string"
          },
          "strategy": {
            "description": "Deprecated placeholder; intentionally empty in computation-only responses.",
            "title": "Strategy",
            "type": "string"
          },
          "type": {
            "description": "Deprecated placeholder; intentionally empty in computation-only responses.",
            "title": "Type",
            "type": "string"
          },
          "variables": {
            "$ref": "#/components/schemas/HDVariables"
          }
        },
        "required": [
          "centers",
          "channels",
          "activations",
          "personality",
          "design"
        ],
        "title": "HumanDesignChartData",
        "type": "object"
      },
      "HumanDesignChartRequest": {
        "description": "Request model for a full Natal Human Design Chart.",
        "properties": {
          "birth_datetime_utc": {
            "format": "date-time",
            "title": "Birth Datetime Utc",
            "type": "string"
          },
          "format": {
            "default": "json",
            "description": "Response format: json | llm.",
            "title": "Format",
            "type": "string"
          },
          "include_chiron": {
            "default": false,
            "description": "Include Chiron gate mapping in the calculation.",
            "title": "Include Chiron",
            "type": "boolean"
          },
          "include_lilith": {
            "default": false,
            "description": "Include Black Moon Lilith gate mapping in the calculation.",
            "title": "Include Lilith",
            "type": "boolean"
          },
          "include_visual": {
            "default": false,
            "description": "When true, a high-fidelity Human Design bodygraph SVG/PNG is embedded in the response alongside the data payload. Adds 2 credits to the request cost.",
            "nullable": true,
            "title": "Include Visual",
            "type": "boolean"
          },
          "latitude": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "default": 0,
            "description": "Latitude for timezone resolution if needed, though UTC is preferred.",
            "title": "Latitude"
          },
          "longitude": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "default": 0,
            "description": "Longitude for timezone resolution.",
            "title": "Longitude"
          },
          "node_mode": {
            "default": "True",
            "description": "Node calculation mode: 'True' or 'Mean'. Default 'True'.",
            "title": "Node Mode",
            "type": "string"
          },
          "visual_config": {
            "$ref": "#/components/schemas/VisualRenderConfig",
            "description": "Optional rendering preferences for the inline bodygraph visual. Defaults: theme=dark, size=800, format=svg."
          }
        },
        "required": [
          "birth_datetime_utc"
        ],
        "title": "HumanDesignChartRequest",
        "type": "object"
      },
      "HumanDesignCompositeRequest": {
        "description": "Request for a Relationship/Composite Chart.",
        "properties": {
          "format": {
            "default": "json",
            "description": "Response format: json | llm.",
            "title": "Format",
            "type": "string"
          },
          "include_visual": {
            "default": false,
            "description": "If true, a full visual SVG or PNG output will be rendered and returned alongside the chart data. Note: Visuals incur a +2 credit surcharge.",
            "title": "Include Visual",
            "type": "boolean"
          },
          "subject_1": {
            "$ref": "#/components/schemas/HumanDesignChartRequest"
          },
          "subject_2": {
            "$ref": "#/components/schemas/HumanDesignChartRequest"
          },
          "visual_config": {
            "$ref": "#/components/schemas/VisualRenderConfig"
          }
        },
        "required": [
          "subject_1",
          "subject_2"
        ],
        "title": "HumanDesignCompositeRequest",
        "type": "object"
      },
      "HumanDesignCompositeResponse": {
        "description": "Composite / Relationship Analysis.",
        "properties": {
          "composite_chart": {
            "$ref": "#/components/schemas/HumanDesignChartData"
          },
          "connections": {
            "items": {
              "$ref": "#/components/schemas/HDConnectionChannel"
            },
            "title": "Connections",
            "type": "array"
          },
          "metadata": {
            "title": "Metadata",
            "type": "object"
          },
          "summary": {
            "additionalProperties": {
              "type": "string"
            },
            "title": "Summary",
            "type": "object"
          },
          "visual": {
            "$ref": "#/components/schemas/VisualResult",
            "description": "Inline chart visual, present only when include_visual=true was requested."
          }
        },
        "required": [
          "composite_chart",
          "connections",
          "summary",
          "metadata"
        ],
        "title": "HumanDesignCompositeResponse",
        "type": "object"
      },
      "HumanDesignLLMOutput": {
        "description": "AI-friendly summary context.",
        "properties": {
          "key_themes": {
            "items": {
              "type": "string"
            },
            "title": "Key Themes",
            "type": "array"
          },
          "summary": {
            "title": "Summary",
            "type": "string"
          }
        },
        "required": [
          "summary",
          "key_themes"
        ],
        "title": "HumanDesignLLMOutput",
        "type": "object"
      },
      "HumanDesignResponse": {
        "description": "Standardized API Response.",
        "properties": {
          "chart": {
            "$ref": "#/components/schemas/HumanDesignChartData"
          },
          "llm_context": {
            "$ref": "#/components/schemas/HumanDesignLLMOutput"
          },
          "metadata": {
            "title": "Metadata",
            "type": "object"
          },
          "visual": {
            "$ref": "#/components/schemas/VisualResult",
            "description": "Inline bodygraph visual, present only when include_visual=true was requested."
          }
        },
        "required": [
          "chart",
          "metadata"
        ],
        "title": "HumanDesignResponse",
        "type": "object"
      },
      "HumanDesignTransitRequest": {
        "description": "Request model for Human Design Transits (Current Weather).",
        "properties": {
          "datetime_utc": {
            "format": "date-time",
            "title": "Datetime Utc",
            "type": "string"
          },
          "format": {
            "default": "json",
            "description": "Response format: json | llm.",
            "title": "Format",
            "type": "string"
          },
          "include_visual": {
            "default": false,
            "description": "If true, a full visual SVG or PNG output will be rendered and returned alongside the chart data. Note: Visuals incur a +2 credit surcharge.",
            "title": "Include Visual",
            "type": "boolean"
          },
          "node_mode": {
            "default": "True",
            "description": "Node calculation mode: 'True' or 'Mean'.",
            "title": "Node Mode",
            "type": "string"
          },
          "visual_config": {
            "$ref": "#/components/schemas/VisualRenderConfig"
          }
        },
        "title": "HumanDesignTransitRequest",
        "type": "object"
      },
      "JulianDayRequest": {
        "additionalProperties": false,
        "properties": {
          "calendar": {
            "default": "proleptic_gregorian",
            "description": "Calendar system to use (e.g. proleptic_gregorian, julian)",
            "title": "Calendar",
            "type": "string"
          },
          "day": {
            "description": "Day of the month, can include fractional days",
            "title": "Day",
            "type": "number"
          },
          "hour": {
            "default": 0,
            "description": "Hour of the day (0-23)",
            "title": "Hour",
            "type": "number"
          },
          "minute": {
            "default": 0,
            "description": "Minute of the hour (0-59)",
            "title": "Minute",
            "type": "number"
          },
          "month": {
            "description": "Month of the year (1-12)",
            "maximum": 12,
            "minimum": 1,
            "title": "Month",
            "type": "integer"
          },
          "second": {
            "default": 0,
            "description": "Second of the minute (0-59)",
            "title": "Second",
            "type": "number"
          },
          "time_scale": {
            "default": "utc",
            "description": "Time scale (utc, tt)",
            "title": "Time Scale",
            "type": "string"
          },
          "year": {
            "description": "Astronomical year (0 = 1 BCE, -1 = 2 BCE)",
            "title": "Year",
            "type": "integer"
          }
        },
        "required": [
          "year",
          "month",
          "day"
        ],
        "title": "JulianDayRequest",
        "type": "object"
      },
      "JulianDayResponse": {
        "properties": {
          "input_interpretation": {
            "description": "Metadata about the input date/calendar",
            "title": "Input Interpretation",
            "type": "object"
          },
          "julian_day": {
            "description": "Julian Day number",
            "example": 2451545,
            "format": "double",
            "title": "Julian Day",
            "type": "number"
          },
          "julian_day_terrestrial": {
            "description": "Julian Day in Terrestrial Time (TT)",
            "title": "Julian Day Terrestrial",
            "type": "number"
          },
          "modified_julian_day": {
            "description": "Modified Julian Day (JD - 2400000.5)",
            "title": "Modified Julian Day",
            "type": "number"
          },
          "valid_range": {
            "description": "Validity range for high-precision calculations",
            "title": "Valid Range",
            "type": "object"
          }
        },
        "required": [
          "julian_day",
          "modified_julian_day",
          "julian_day_terrestrial",
          "input_interpretation",
          "valid_range"
        ],
        "title": "JulianDayResponse",
        "type": "object"
      },
      "LightChartResponse": {
        "description": "Lightweight chart representation for overlay-style comparisons.\n\nIncludes houses + angles to support chart rendering in comparative responses.",
        "properties": {
          "angles": {
            "allOf": [
              {
                "$ref": "#/components/schemas/AnglesResponse"
              }
            ],
            "description": "Chart angles"
          },
          "houses": {
            "allOf": [
              {
                "$ref": "#/components/schemas/HousesResponse"
              }
            ],
            "description": "House system cusps"
          },
          "planets": {
            "additionalProperties": {
              "$ref": "#/components/schemas/PlanetResponse"
            },
            "description": "Planetary positions keyed by name",
            "title": "Planets",
            "type": "object"
          },
          "subject": {
            "allOf": [
              {
                "$ref": "#/components/schemas/SubjectResponse"
              }
            ],
            "description": "Subject information"
          }
        },
        "required": [
          "subject",
          "planets",
          "houses",
          "angles"
        ],
        "title": "LightChartResponse",
        "type": "object"
      },
      "LocalCircumstances": {
        "properties": {
          "duration_seconds": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "title": "Duration Seconds"
          },
          "first_contact": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "title": "First Contact"
          },
          "fourth_contact": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "title": "Fourth Contact"
          },
          "magnitude": {
            "title": "Magnitude",
            "type": "number"
          },
          "max_eclipse": {
            "title": "Max Eclipse",
            "type": "string"
          },
          "obscuration": {
            "default": 0,
            "title": "Obscuration",
            "type": "number"
          },
          "second_contact": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "title": "Second Contact"
          },
          "sun_altitude": {
            "default": 0,
            "title": "Sun Altitude",
            "type": "number"
          },
          "sun_azimuth": {
            "default": 0,
            "title": "Sun Azimuth",
            "type": "number"
          },
          "third_contact": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "title": "Third Contact"
          },
          "type": {
            "$ref": "#/components/schemas/EclipseType"
          }
        },
        "required": [
          "type",
          "magnitude",
          "max_eclipse"
        ],
        "title": "LocalCircumstances",
        "type": "object"
      },
      "LocationAutocompleteResponse": {
        "additionalProperties": true,
        "description": "Response for /location/autocomplete endpoint.",
        "example": {
          "cached": false,
          "query": "san fran",
          "suggestions": [
            {
              "confidence": 0.97,
              "country_code": "US",
              "display_name": "San Francisco, California, United States",
              "latitude": 37.7749,
              "longitude": -122.4194,
              "place_id": "place.12345",
              "short_name": "San Francisco",
              "timezone": "America/Los_Angeles"
            }
          ],
          "total_results": 1
        },
        "properties": {
          "cached": {
            "default": false,
            "description": "True if results were served from cache",
            "title": "Cached",
            "type": "boolean"
          },
          "query": {
            "description": "Original search query",
            "title": "Query",
            "type": "string"
          },
          "suggestions": {
            "description": "List of matching location suggestions",
            "items": {
              "$ref": "#/components/schemas/LocationSuggestion"
            },
            "title": "Suggestions",
            "type": "array"
          },
          "total_results": {
            "description": "Number of suggestions returned",
            "minimum": 0,
            "title": "Total Results",
            "type": "integer"
          }
        },
        "required": [
          "query",
          "total_results"
        ],
        "title": "LocationAutocompleteResponse",
        "type": "object"
      },
      "LocationInput": {
        "additionalProperties": false,
        "description": "Geographic location with coordinates, elevation, and optional timezone.",
        "example": {
          "elevation": 10,
          "latitude": {
            "decimal": 40.7128
          },
          "longitude": {
            "decimal": -74.006
          },
          "timezone": {
            "iana_name": "America/New_York"
          }
        },
        "properties": {
          "elevation": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "default": 0,
            "description": "Elevation above sea level in meters",
            "title": "Elevation"
          },
          "latitude": {
            "allOf": [
              {
                "$ref": "#/components/schemas/CoordinateInput"
              }
            ],
            "description": "Geographic latitude"
          },
          "longitude": {
            "allOf": [
              {
                "$ref": "#/components/schemas/CoordinateInput"
              }
            ],
            "description": "Geographic longitude"
          },
          "timezone": {
            "$ref": "#/components/schemas/TimezoneInput",
            "description": "Local timezone information"
          }
        },
        "required": [
          "latitude",
          "longitude"
        ],
        "title": "LocationInput",
        "type": "object"
      },
      "LocationSuggestion": {
        "additionalProperties": true,
        "description": "Single location suggestion for autocomplete results.",
        "example": {
          "confidence": 0.97,
          "country_code": "US",
          "display_name": "San Francisco, California, United States",
          "latitude": 37.7749,
          "longitude": -122.4194,
          "place_id": "place.12345",
          "short_name": "San Francisco",
          "timezone": "America/Los_Angeles"
        },
        "properties": {
          "confidence": {
            "anyOf": [
              {
                "maximum": 1,
                "minimum": 0,
                "type": "number"
              }
            ],
            "description": "Optional confidence score from the provider (0-1)",
            "title": "Confidence"
          },
          "country_code": {
            "anyOf": [
              {
                "maxLength": 2,
                "minLength": 2,
                "type": "string"
              }
            ],
            "description": "ISO 3166-1 alpha-2 country code (e.g., US, GB)",
            "title": "Country Code"
          },
          "display_name": {
            "description": "Full human-readable name",
            "title": "Display Name",
            "type": "string"
          },
          "latitude": {
            "description": "Latitude in decimal degrees",
            "maximum": 90,
            "minimum": -90,
            "title": "Latitude",
            "type": "number"
          },
          "longitude": {
            "description": "Longitude in decimal degrees",
            "maximum": 180,
            "minimum": -180,
            "title": "Longitude",
            "type": "number"
          },
          "place_id": {
            "description": "Provider-specific place identifier",
            "title": "Place Id",
            "type": "string"
          },
          "short_name": {
            "description": "Short label suitable for UI chips",
            "title": "Short Name",
            "type": "string"
          },
          "timezone": {
            "description": "IANA timezone identifier (e.g., America/Los_Angeles)",
            "title": "Timezone",
            "type": "string"
          }
        },
        "required": [
          "place_id",
          "display_name",
          "short_name",
          "latitude",
          "longitude",
          "timezone"
        ],
        "title": "LocationSuggestion",
        "type": "object"
      },
      "LotPosition": {
        "additionalProperties": false,
        "description": "Normalized position for Hermetic lots and similar points.",
        "properties": {
          "degree_in_sign": {
            "description": "Longitude within sign (0-30)",
            "title": "Degree In Sign",
            "type": "number"
          },
          "formula": {
            "description": "Calculation formula description",
            "title": "Formula",
            "type": "string"
          },
          "house": {
            "description": "House position",
            "title": "House",
            "type": "integer"
          },
          "longitude": {
            "description": "Longitude in degrees",
            "title": "Longitude",
            "type": "number"
          },
          "name": {
            "description": "Lot identifier",
            "title": "Name",
            "type": "string"
          },
          "sign": {
            "description": "Zodiac sign",
            "title": "Sign",
            "type": "string"
          },
          "sign_symbol": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Zodiac sign symbol",
            "title": "Sign Symbol"
          }
        },
        "required": [
          "name",
          "longitude",
          "sign",
          "degree_in_sign",
          "house",
          "formula"
        ],
        "title": "LotPosition",
        "type": "object"
      },
      "LotSuiteEnum": {
        "description": "Predefined sets of Arabic parts/lots.",
        "enum": [
          "fortune_suite_canonical",
          "hermetic_core",
          "mercury_sect",
          "custom"
        ],
        "title": "LotSuiteEnum",
        "type": "string"
      },
      "LotsConfig": {
        "additionalProperties": false,
        "description": "Arabic part / lot configuration.",
        "example": {
          "include_all": true,
          "suite": "fortune_suite_canonical"
        },
        "properties": {
          "exclude": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              }
            ],
            "description": "Blacklist of lot identifiers to drop",
            "title": "Exclude"
          },
          "include": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              }
            ],
            "description": "Whitelist of lot identifiers (overrides include_all)",
            "title": "Include"
          },
          "include_all": {
            "default": true,
            "description": "Include every lot from the selected suite",
            "title": "Include All",
            "type": "boolean"
          },
          "suite": {
            "allOf": [
              {
                "$ref": "#/components/schemas/LotSuiteEnum"
              }
            ],
            "default": "fortune_suite_canonical",
            "description": "Predefined lot suite"
          }
        },
        "title": "LotsConfig",
        "type": "object"
      },
      "LunarContactTimes": {
        "properties": {
          "duration_minutes": {
            "default": 0,
            "title": "Duration Minutes",
            "type": "number"
          },
          "maximum": {
            "title": "Maximum",
            "type": "string"
          },
          "penumbral_end": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "title": "Penumbral End"
          },
          "penumbral_magnitude": {
            "default": 0,
            "title": "Penumbral Magnitude",
            "type": "number"
          },
          "penumbral_start": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "title": "Penumbral Start"
          },
          "totality_end": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "title": "Totality End"
          },
          "totality_start": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "title": "Totality Start"
          },
          "umbral_end": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "title": "Umbral End"
          },
          "umbral_magnitude": {
            "default": 0,
            "title": "Umbral Magnitude",
            "type": "number"
          },
          "umbral_start": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "title": "Umbral Start"
          }
        },
        "required": [
          "maximum"
        ],
        "title": "LunarContactTimes",
        "type": "object"
      },
      "LunarEclipseGlobalResponse": {
        "properties": {
          "contact_times": {
            "$ref": "#/components/schemas/LunarContactTimes"
          },
          "eclipse_classification": {
            "$ref": "#/components/schemas/EclipseClassification"
          },
          "meta": {
            "$ref": "#/components/schemas/CalculationMeta"
          },
          "safety": {
            "$ref": "#/components/schemas/SafetyWarnings"
          },
          "uncertainty": {
            "$ref": "#/components/schemas/UncertaintyInfo"
          }
        },
        "required": [
          "meta",
          "eclipse_classification",
          "contact_times"
        ],
        "title": "LunarEclipseGlobalResponse",
        "type": "object"
      },
      "LunarPhaseCalculationRequest": {
        "additionalProperties": false,
        "description": "Request for calculating lunar phase data.",
        "example": {
          "date_time": {
            "iso": "2025-12-11T12:00:00Z"
          }
        },
        "properties": {
          "date_time": {
            "allOf": [
              {
                "$ref": "#/components/schemas/DateTimeInput"
              }
            ],
            "description": "Calculation datetime in ISO, components, or Julian day format",
            "example": {
              "iso": "2000-01-01T12:00:00Z"
            }
          }
        },
        "required": [
          "date_time"
        ],
        "title": "LunarPhaseCalculationRequest",
        "type": "object"
      },
      "LunarPhaseCalculationResponse": {
        "additionalProperties": false,
        "description": "Response from lunar phase calculation endpoint.",
        "properties": {
          "metadata": {
            "description": "Calculation metadata and settings",
            "title": "Metadata",
            "type": "object"
          },
          "phase": {
            "allOf": [
              {
                "$ref": "#/components/schemas/LunarPhaseData"
              }
            ],
            "description": "Lunar phase data"
          },
          "success": {
            "default": true,
            "description": "Calculation success status",
            "title": "Success",
            "type": "boolean"
          }
        },
        "required": [
          "phase",
          "metadata"
        ],
        "title": "LunarPhaseCalculationResponse",
        "type": "object"
      },
      "LunarPhaseData": {
        "additionalProperties": false,
        "description": "Lunar phase information at a specific moment.",
        "properties": {
          "age_days": {
            "description": "Age of Moon in days since last New Moon",
            "title": "Age Days",
            "type": "number"
          },
          "angular_diameter": {
            "description": "Angular diameter of Moon in degrees",
            "title": "Angular Diameter",
            "type": "number"
          },
          "distance_km": {
            "description": "Earth-Moon distance in kilometers",
            "title": "Distance Km",
            "type": "number"
          },
          "elongation": {
            "description": "Sun-Moon elongation in degrees (0-180)",
            "title": "Elongation",
            "type": "number"
          },
          "illumination": {
            "description": "Percentage of lunar disk illuminated (0-100)",
            "title": "Illumination",
            "type": "number"
          },
          "name": {
            "description": "Phase name (New Moon, Waxing Crescent, First Quarter, etc.)",
            "title": "Name",
            "type": "string"
          },
          "phase_angle": {
            "description": "Phase angle in degrees (0-360)",
            "title": "Phase Angle",
            "type": "number"
          }
        },
        "required": [
          "name",
          "illumination",
          "elongation",
          "phase_angle",
          "age_days",
          "distance_km",
          "angular_diameter"
        ],
        "title": "LunarPhaseData",
        "type": "object"
      },
      "LunarPhaseResponse": {
        "additionalProperties": false,
        "description": "High-precision lunar phase calculation, indicating the exact illumination percentage, phase angle, and the time remaining until the next key phase.",
        "example": {
          "days_to_full": 2.5,
          "days_to_new": 12.3,
          "illumination": 78.5,
          "metadata": {
            "calculation_time_ms": 5.2
          },
          "phase_angle": 125.3,
          "phase_name": "Waxing Gibbous",
          "success": true,
          "waxing": true
        },
        "properties": {
          "days_to_full": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "description": "Days until next Full Moon",
            "title": "Days To Full"
          },
          "days_to_new": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "description": "Days until next New Moon",
            "title": "Days To New"
          },
          "illumination": {
            "description": "Moon illumination percentage (0-100)",
            "title": "Illumination",
            "type": "number"
          },
          "metadata": {
            "description": "Calculation metadata",
            "title": "Metadata",
            "type": "object"
          },
          "phase_angle": {
            "description": "Sun-Moon angle in degrees (0-360)",
            "title": "Phase Angle",
            "type": "number"
          },
          "phase_name": {
            "description": "Phase name (New Moon, Waxing Crescent, First Quarter, Waxing Gibbous, Full Moon, Waning Gibbous, Last Quarter, Waning Crescent)",
            "title": "Phase Name",
            "type": "string"
          },
          "success": {
            "default": true,
            "description": "Calculation success status",
            "title": "Success",
            "type": "boolean"
          },
          "waxing": {
            "description": "True if Moon is waxing",
            "title": "Waxing",
            "type": "boolean"
          }
        },
        "required": [
          "phase_name",
          "illumination",
          "phase_angle",
          "waxing",
          "metadata"
        ],
        "title": "LunarPhaseResponse",
        "type": "object"
      },
      "LunarPhaseResult": {
        "properties": {
          "events": {
            "description": "Moon phase events in the requested range",
            "items": {
              "$ref": "#/components/schemas/MoonPhaseEvent"
            },
            "title": "Events",
            "type": "array"
          }
        },
        "required": [
          "events"
        ],
        "title": "LunarPhaseResult",
        "type": "object"
      },
      "LunarReturnRequest": {
        "additionalProperties": false,
        "description": "Lunar return timing request (body fixed to Moon).",
        "example": {
          "birth_datetime": {
            "iso": "1990-06-15T14:30:00Z"
          },
          "house_system": "P",
          "include_chart": true,
          "location": {
            "elevation": 10,
            "latitude": {
              "decimal": 40.7128
            },
            "longitude": {
              "decimal": -74.006
            },
            "timezone": {
              "iana_name": "UTC"
            }
          },
          "return_location": {
            "elevation": 71,
            "latitude": {
              "decimal": 34.0522
            },
            "longitude": {
              "decimal": -118.2437
            },
            "timezone": {
              "iana_name": "UTC"
            }
          },
          "search_window_days": 30,
          "target_datetime": {
            "iso": "2024-06-15T00:00:00Z"
          }
        },
        "properties": {
          "birth_datetime": {
            "allOf": [
              {
                "$ref": "#/components/schemas/DateTimeInput"
              }
            ],
            "description": "Birth date/time (ISO-8601, components, or Julian day)"
          },
          "enhanced_options": {
            "$ref": "#/components/schemas/EnhancedCalculationOptions",
            "description": "Optional enhanced calculation flags applied when include_chart=true and preset=simple or format=llm. This controls additional computed analysis blocks (e.g., Human Design gates, lunar phase, midpoints)."
          },
          "house_system": {
            "$ref": "#/components/schemas/HouseSystemEnum",
            "default": "P",
            "description": "House system for chart calculation (P=Placidus, K=Koch, W=Whole Sign, etc.)"
          },
          "include_chart": {
            "default": false,
            "description": "Include full chart at return moment",
            "title": "Include Chart",
            "type": "boolean"
          },
          "include_visual": {
            "default": false,
            "description": "If true, a full visual SVG or PNG output will be rendered and returned alongside the chart data. Note: Visuals incur a +2 credit surcharge.",
            "title": "Include Visual",
            "type": "boolean"
          },
          "location": {
            "$ref": "#/components/schemas/LocationInput",
            "description": "Location context (timezone + optional elevation)"
          },
          "return_location": {
            "$ref": "#/components/schemas/LocationInput",
            "description": "Optional location for the return chart (defaults to `location` if omitted)"
          },
          "search_window_days": {
            "anyOf": [
              {
                "maximum": 5000,
                "minimum": 1,
                "type": "integer"
              }
            ],
            "description": "Days to search symmetrically around target datetime (defaults depend on body)",
            "title": "Search Window Days"
          },
          "target_datetime": {
            "allOf": [
              {
                "$ref": "#/components/schemas/DateTimeInput"
              }
            ],
            "description": "Target datetime to search around (ISO-8601, components, or Julian day)"
          },
          "visual_config": {
            "$ref": "#/components/schemas/VisualRenderConfig"
          }
        },
        "required": [
          "birth_datetime",
          "target_datetime"
        ],
        "title": "LunarReturnRequest",
        "type": "object"
      },
      "LunarReturnResponse": {
        "description": "Response payload for lunar return calculations.",
        "properties": {
          "calculation_metadata": {
            "$ref": "#/components/schemas/CalculationMetadata",
            "description": "Standardized calculation metadata describing the return computation"
          },
          "chart": {
            "$ref": "#/components/schemas/NatalChartResponse",
            "description": "Full chart calculation at return moment (if include_chart=True)"
          },
          "exact_datetime": {
            "description": "Exact return datetime (UTC)",
            "format": "date-time",
            "title": "Exact Datetime",
            "type": "string"
          },
          "location": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ReturnLocation"
              }
            ],
            "description": "Normalized location used for chart calculation"
          },
          "metadata": {
            "allOf": [
              {
                "$ref": "#/components/schemas/PredictiveMetadata"
              }
            ],
            "description": "Calculation metadata"
          },
          "output_mode": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Output projection mode (full | simple | llm)",
            "title": "Output Mode"
          },
          "schema_version": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Schema version for the selected output mode (e.g., full_v1, simple_v1, llm)",
            "title": "Schema Version"
          },
          "success": {
            "description": "Request success status",
            "title": "Success",
            "type": "boolean"
          },
          "visual": {
            "$ref": "#/components/schemas/VisualResult",
            "description": "Inline chart visual, present only when include_visual=true was requested."
          }
        },
        "required": [
          "success",
          "exact_datetime",
          "location",
          "metadata"
        ],
        "title": "LunarReturnResponse",
        "type": "object"
      },
      "LunarStandstillInfo": {
        "properties": {
          "declination": {
            "description": "Moon's declination at the peak",
            "title": "Declination",
            "type": "number"
          },
          "node_distance": {
            "description": "Angular distance to the node",
            "title": "Node Distance",
            "type": "number"
          },
          "peak_date": {
            "description": "ISO 8601 UTC timestamp of the peak of the standstill",
            "title": "Peak Date",
            "type": "string"
          },
          "type": {
            "description": "'major' or 'minor'",
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "type",
          "peak_date",
          "declination",
          "node_distance"
        ],
        "title": "LunarStandstillInfo",
        "type": "object"
      },
      "LunarStandstillResponse": {
        "description": "Lunar standstills for a specific year.",
        "properties": {
          "_meta": {
            "description": "Calculation metadata",
            "title": " Meta",
            "type": "object"
          },
          "events": {
            "description": "Standstill events in the year",
            "items": {
              "$ref": "#/components/schemas/LunarStandstillInfo"
            },
            "title": "Events",
            "type": "array"
          },
          "year": {
            "description": "Year searched",
            "title": "Year",
            "type": "integer"
          }
        },
        "required": [
          "year",
          "events",
          "_meta"
        ],
        "title": "LunarStandstillResponse",
        "type": "object"
      },
      "MidpointResult": {
        "additionalProperties": false,
        "description": "Single midpoint calculation result.",
        "properties": {
          "arc_type": {
            "description": "Arc type: 'short' or 'long'",
            "title": "Arc Type",
            "type": "string"
          },
          "longitude": {
            "description": "Midpoint longitude in degrees (0-360)",
            "title": "Longitude",
            "type": "number"
          },
          "occupied_by": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              }
            ],
            "description": "Planets/points occupying this midpoint (if include_occupied=true)",
            "title": "Occupied By"
          },
          "planet1": {
            "description": "First planet/point name",
            "title": "Planet1",
            "type": "string"
          },
          "planet2": {
            "description": "Second planet/point name",
            "title": "Planet2",
            "type": "string"
          },
          "sign": {
            "description": "Zodiac sign of midpoint",
            "title": "Sign",
            "type": "string"
          },
          "sign_degrees": {
            "description": "Degrees within sign (0-30)",
            "title": "Sign Degrees",
            "type": "number"
          }
        },
        "required": [
          "planet1",
          "planet2",
          "longitude",
          "arc_type",
          "sign",
          "sign_degrees"
        ],
        "title": "MidpointResult",
        "type": "object"
      },
      "MidpointsCalculationRequest": {
        "additionalProperties": false,
        "description": "Request for midpoint calculations.",
        "example": {
          "arc_type": "short",
          "date_time": {
            "iso": "2023-12-07T15:30:00Z"
          },
          "include_angles": true,
          "include_occupied": false,
          "latitude": 40.7128,
          "longitude": -74.006
        },
        "properties": {
          "arc_type": {
            "default": "short",
            "description": "Type of midpoint arc to calculate: 'short' (direct), 'long' (opposite), or 'both'",
            "enum": [
              "short",
              "long",
              "both"
            ],
            "title": "Arc Type",
            "type": "string"
          },
          "date_time": {
            "allOf": [
              {
                "$ref": "#/components/schemas/DateTimeInput"
              }
            ],
            "description": "Datetime for calculation (ISO, components, or Julian day)"
          },
          "house_system": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Optional house system for angle calculation (e.g., 'P', 'W'). Defaults to server settings when omitted.",
            "title": "House System"
          },
          "include_angles": {
            "default": false,
            "description": "Whether to include chart angles (ASC, MC, etc.) in midpoint pairs",
            "title": "Include Angles",
            "type": "boolean"
          },
          "include_occupied": {
            "default": false,
            "description": "Filter to only midpoints occupied by planets (within orb)",
            "title": "Include Occupied",
            "type": "boolean"
          },
          "latitude": {
            "anyOf": [
              {
                "maximum": 90,
                "minimum": -90,
                "type": "number"
              }
            ],
            "description": "Optional latitude for computing angles when include_angles=True. If include_angles=True, latitude and longitude must be provided.",
            "title": "Latitude"
          },
          "longitude": {
            "anyOf": [
              {
                "maximum": 180,
                "minimum": -180,
                "type": "number"
              }
            ],
            "description": "Optional longitude for computing angles when include_angles=True. If include_angles=True, latitude and longitude must be provided.",
            "title": "Longitude"
          },
          "orb": {
            "default": 1,
            "description": "Orb in degrees for occupied midpoint detection (default 1.0°)",
            "maximum": 10,
            "minimum": 0,
            "title": "Orb",
            "type": "number"
          },
          "sort_by": {
            "anyOf": [
              {
                "enum": [
                  "degree",
                  "planet1",
                  "planet2"
                ],
                "type": "string"
              }
            ],
            "description": "Optional sorting: by longitude degree, first planet name, or second planet name",
            "title": "Sort By"
          }
        },
        "required": [
          "date_time"
        ],
        "title": "MidpointsCalculationRequest",
        "type": "object"
      },
      "MidpointsCalculationResponse": {
        "additionalProperties": false,
        "description": "Response from midpoints calculation endpoint.",
        "properties": {
          "metadata": {
            "description": "Calculation metadata and settings",
            "title": "Metadata",
            "type": "object"
          },
          "midpoints": {
            "description": "Calculated midpoints",
            "items": {
              "$ref": "#/components/schemas/MidpointResult"
            },
            "title": "Midpoints",
            "type": "array"
          },
          "success": {
            "default": true,
            "description": "Calculation success status",
            "title": "Success",
            "type": "boolean"
          }
        },
        "required": [
          "midpoints",
          "metadata"
        ],
        "title": "MidpointsCalculationResponse",
        "type": "object"
      },
      "MoonAspectsResponse": {
        "additionalProperties": false,
        "description": "Comprehensive snapshot of all aspects currently being formed by the Moon, separated into applying (approaching) and separating (departing) phases.",
        "example": {
          "applying": [
            {
              "applying": true,
              "aspect_type": "square",
              "orb": 2.3,
              "planet": "Sun"
            }
          ],
          "aspects": [
            {
              "applying": true,
              "aspect_type": "square",
              "orb": 2.3,
              "planet": "Sun"
            }
          ],
          "count": 1,
          "metadata": {
            "calculation_time_ms": 18.5
          },
          "separating": [],
          "success": true
        },
        "properties": {
          "applying": {
            "description": "Applying aspects (Moon approaching)",
            "items": {
              "type": "object"
            },
            "title": "Applying",
            "type": "array"
          },
          "aspects": {
            "description": "All current Moon aspects",
            "items": {
              "type": "object"
            },
            "title": "Aspects",
            "type": "array"
          },
          "count": {
            "description": "Total aspect count",
            "title": "Count",
            "type": "integer"
          },
          "metadata": {
            "description": "Calculation metadata",
            "title": "Metadata",
            "type": "object"
          },
          "separating": {
            "description": "Separating aspects (Moon departing)",
            "items": {
              "type": "object"
            },
            "title": "Separating",
            "type": "array"
          },
          "success": {
            "default": true,
            "description": "Calculation success status",
            "title": "Success",
            "type": "boolean"
          }
        },
        "required": [
          "aspects",
          "applying",
          "separating",
          "count",
          "metadata"
        ],
        "title": "MoonAspectsResponse",
        "type": "object"
      },
      "MoonIngressesResponse": {
        "additionalProperties": false,
        "description": "Chronologically ordered list of lunar sign ingresses (when the Moon changes zodiac signs) within the requested date range.",
        "example": {
          "count": 13,
          "ingresses": [
            {
              "from_sign": "Aries",
              "time": "2025-12-01T08:15:00+00:00",
              "to_sign": "Taurus"
            },
            {
              "from_sign": "Taurus",
              "time": "2025-12-03T18:30:00+00:00",
              "to_sign": "Gemini"
            }
          ],
          "metadata": {
            "average_ingresses_per_month": 13,
            "cache_hit": true,
            "calculation_time_ms": 2.1,
            "end_date": "2025-12-31T23:59:59+00:00",
            "start_date": "2025-12-01T00:00:00+00:00",
            "zodiac_mode": "tropical"
          },
          "success": true
        },
        "properties": {
          "count": {
            "description": "Number of ingresses in range",
            "title": "Count",
            "type": "integer"
          },
          "ingresses": {
            "description": "Moon sign ingress events",
            "items": {
              "type": "object"
            },
            "title": "Ingresses",
            "type": "array"
          },
          "metadata": {
            "description": "Query metadata (calculation_time_ms, cache_hit, date range)",
            "title": "Metadata",
            "type": "object"
          },
          "success": {
            "default": true,
            "description": "Calculation success status",
            "title": "Success",
            "type": "boolean"
          }
        },
        "required": [
          "ingresses",
          "count",
          "metadata"
        ],
        "title": "MoonIngressesResponse",
        "type": "object"
      },
      "MoonPhaseEvent": {
        "properties": {
          "phase": {
            "description": "New Moon, First Quarter, Full Moon, or Last Quarter",
            "title": "Phase",
            "type": "string"
          },
          "time": {
            "description": "ISO 8601 UTC timestamp of exactly when the phase occurs",
            "title": "Time",
            "type": "string"
          }
        },
        "required": [
          "phase",
          "time"
        ],
        "title": "MoonPhaseEvent",
        "type": "object"
      },
      "MoonPhasesResponse": {
        "description": "Moon phases over a date range.",
        "properties": {
          "_meta": {
            "description": "Calculation metadata",
            "title": " Meta",
            "type": "object"
          },
          "data": {
            "allOf": [
              {
                "$ref": "#/components/schemas/LunarPhaseResult"
              }
            ],
            "description": "The matching phase events"
          },
          "range": {
            "additionalProperties": {
              "type": "string"
            },
            "description": "Start and end dates of the search",
            "title": "Range",
            "type": "object"
          }
        },
        "required": [
          "range",
          "data",
          "_meta"
        ],
        "title": "MoonPhasesResponse",
        "type": "object"
      },
      "NakshatraDetail": {
        "description": "Nakshatra (lunar mansion) details for a single planet.",
        "properties": {
          "deity": {
            "description": "Presiding deity",
            "title": "Deity",
            "type": "string"
          },
          "name": {
            "description": "Nakshatra name",
            "title": "Name",
            "type": "string"
          },
          "number": {
            "description": "Nakshatra number (1–27)",
            "title": "Number",
            "type": "integer"
          },
          "pada": {
            "description": "Pada / quarter (1–4)",
            "title": "Pada",
            "type": "integer"
          },
          "ruler": {
            "description": "Ruling planet (Vedic lords)",
            "title": "Ruler",
            "type": "string"
          }
        },
        "required": [
          "number",
          "name",
          "pada",
          "ruler",
          "deity"
        ],
        "title": "NakshatraDetail",
        "type": "object"
      },
      "NatalBatchChartResult": {
        "additionalProperties": true,
        "description": "Individual chart outcome within a batch payload.",
        "properties": {
          "calculation_metadata": {
            "$ref": "#/components/schemas/CalculationMetadata",
            "description": "Calculation metadata echoed for this subject"
          },
          "chart": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/NatalChartResponse"
              },
              {
                "$ref": "#/components/schemas/NatalChartEnhancedResponse"
              },
              {
                "type": "object"
              }
            ],
            "description": "Raw chart payload when the calculation succeeds",
            "title": "Chart"
          },
          "chart_type": {
            "description": "Chart flavor (natal | natal_enhanced)",
            "title": "Chart Type",
            "type": "string"
          },
          "error": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Error message when the calculation fails",
            "title": "Error"
          },
          "subject_name": {
            "description": "Subject name used for this chart",
            "title": "Subject Name",
            "type": "string"
          },
          "success": {
            "default": true,
            "description": "Whether the chart calculation succeeded",
            "title": "Success",
            "type": "boolean"
          }
        },
        "required": [
          "subject_name",
          "chart_type"
        ],
        "title": "NatalBatchChartResult",
        "type": "object"
      },
      "NatalBatchItem": {
        "additionalProperties": false,
        "description": "Single natal chart item within a batch request.",
        "example": {
          "configuration": {
            "coordinate_frame": "ecliptic",
            "coordinate_system": "geocentric",
            "house_system": "W",
            "object_set": "modern_plus_chiron",
            "zodiac_type": "tropical"
          },
          "enhanced_options": {
            "aspect_patterns": true,
            "include_midpoints": true
          },
          "format": "json",
          "preset": "full",
          "subject": {
            "birth_datetime": {
              "iso": "1992-01-10T04:15:00"
            },
            "birth_location": {
              "latitude": {
                "decimal": 40
              },
              "longitude": {
                "decimal": -74
              },
              "timezone": {
                "iana_name": "America/New_York"
              }
            },
            "name": "Batch Subject 1"
          }
        },
        "properties": {
          "configuration": {
            "$ref": "#/components/schemas/NatalConfig",
            "description": "Optional per-subject basic configuration"
          },
          "enhanced_configuration": {
            "$ref": "#/components/schemas/NatalEnhancedConfig",
            "description": "Optional per-subject enhanced configuration"
          },
          "enhanced_options": {
            "$ref": "#/components/schemas/EnhancedCalculationOptions",
            "description": "Optional enhanced calculation toggles for this item"
          },
          "format": {
            "anyOf": [
              {
                "enum": [
                  "json",
                  "llm"
                ],
                "type": "string"
              }
            ],
            "description": "Optional per-item response format (overrides batch-level default)",
            "title": "Format"
          },
          "options": {
            "$ref": "#/components/schemas/ResponseOptions",
            "description": "Optional response shaping overrides"
          },
          "preset": {
            "anyOf": [
              {
                "enum": [
                  "full",
                  "simple"
                ],
                "type": "string"
              }
            ],
            "description": "Optional per-item preset (overrides batch-level default)",
            "title": "Preset"
          },
          "subject": {
            "allOf": [
              {
                "$ref": "#/components/schemas/SubjectRequest"
              }
            ],
            "description": "Subject birth data"
          }
        },
        "required": [
          "subject"
        ],
        "title": "NatalBatchItem",
        "type": "object"
      },
      "NatalBatchLimits": {
        "additionalProperties": false,
        "description": "Batch request guardrails embedded in schemas.",
        "properties": {
          "max_payload_kilobytes": {
            "default": 512,
            "description": "Maximum payload size in kilobytes",
            "maximum": 5000,
            "minimum": 50,
            "title": "Max Payload Kilobytes",
            "type": "integer"
          },
          "max_subjects": {
            "default": 10,
            "description": "Maximum subjects per request",
            "maximum": 100,
            "minimum": 1,
            "title": "Max Subjects",
            "type": "integer"
          }
        },
        "title": "NatalBatchLimits",
        "type": "object"
      },
      "NatalBatchRequest": {
        "additionalProperties": false,
        "description": "Batch natal chart request containing multiple subjects.",
        "example": {
          "enhanced_options": {
            "aspect_patterns": true,
            "include_midpoints": true
          },
          "format": "json",
          "items": [
            {
              "configuration": {
                "coordinate_frame": "ecliptic",
                "coordinate_system": "geocentric",
                "house_system": "W",
                "object_set": "modern_plus_chiron",
                "zodiac_type": "tropical"
              },
              "subject": {
                "birth_datetime": {
                  "iso": "1992-01-10T04:15:00"
                },
                "birth_location": {
                  "latitude": {
                    "decimal": 40
                  },
                  "longitude": {
                    "decimal": -74
                  },
                  "timezone": {
                    "iana_name": "America/New_York"
                  }
                },
                "name": "Batch Subject 1"
              }
            },
            {
              "subject": {
                "birth_datetime": {
                  "iso": "1988-07-22T19:45:00"
                },
                "birth_location": {
                  "latitude": {
                    "decimal": 34.0522
                  },
                  "longitude": {
                    "decimal": -118.2437
                  },
                  "timezone": {
                    "iana_name": "America/Los_Angeles"
                  }
                },
                "name": "Batch Subject 2"
              }
            }
          ],
          "limits": {
            "max_payload_kilobytes": 512,
            "max_subjects": 10
          },
          "preset": "full"
        },
        "properties": {
          "enhanced_options": {
            "$ref": "#/components/schemas/EnhancedCalculationOptions",
            "description": "Optional enhanced calculation toggles for all items in the batch"
          },
          "format": {
            "anyOf": [
              {
                "enum": [
                  "json",
                  "llm"
                ],
                "type": "string"
              }
            ],
            "description": "Optional batch-level response format (default for all items)",
            "title": "Format"
          },
          "items": {
            "description": "List of subjects to compute",
            "items": {
              "$ref": "#/components/schemas/NatalBatchItem"
            },
            "maxItems": 100,
            "minItems": 1,
            "title": "Items",
            "type": "array"
          },
          "limits": {
            "allOf": [
              {
                "$ref": "#/components/schemas/NatalBatchLimits"
              }
            ],
            "description": "Server-advertised limits for validation"
          },
          "preset": {
            "anyOf": [
              {
                "enum": [
                  "full",
                  "simple"
                ],
                "type": "string"
              }
            ],
            "description": "Optional batch-level preset (default for all items)",
            "title": "Preset"
          }
        },
        "required": [
          "items"
        ],
        "title": "NatalBatchRequest",
        "type": "object"
      },
      "NatalBatchResponse": {
        "description": "Top-level batch response envelope.",
        "properties": {
          "data": {
            "allOf": [
              {
                "$ref": "#/components/schemas/NatalBatchResponseData"
              }
            ],
            "description": "Batch charts and summary payload"
          },
          "success": {
            "default": true,
            "description": "True when every chart succeeded",
            "title": "Success",
            "type": "boolean"
          }
        },
        "required": [
          "data"
        ],
        "title": "NatalBatchResponse",
        "type": "object"
      },
      "NatalBatchResponseData": {
        "description": "Data envelope for batch responses.",
        "properties": {
          "charts": {
            "description": "Per-subject chart results",
            "items": {
              "$ref": "#/components/schemas/NatalBatchChartResult"
            },
            "title": "Charts",
            "type": "array"
          },
          "summary": {
            "allOf": [
              {
                "$ref": "#/components/schemas/NatalBatchSummary"
              }
            ],
            "description": "Summary statistics for the batch run"
          }
        },
        "required": [
          "charts",
          "summary"
        ],
        "title": "NatalBatchResponseData",
        "type": "object"
      },
      "NatalBatchSummary": {
        "description": "Summary statistics for a batch run.",
        "properties": {
          "failed": {
            "description": "Subjects that failed to compute",
            "title": "Failed",
            "type": "integer"
          },
          "max_subjects": {
            "description": "Server-advertised per-request subject limit",
            "title": "Max Subjects",
            "type": "integer"
          },
          "payload_kilobytes": {
            "description": "Approximate payload size submitted by the client (KB)",
            "title": "Payload Kilobytes",
            "type": "number"
          },
          "process_time_ms": {
            "description": "Wall-clock processing time in milliseconds",
            "title": "Process Time Ms",
            "type": "number"
          },
          "processed": {
            "description": "Total subjects processed",
            "title": "Processed",
            "type": "integer"
          },
          "success": {
            "description": "Successfully computed subjects",
            "title": "Success",
            "type": "integer"
          }
        },
        "required": [
          "processed",
          "success",
          "failed",
          "process_time_ms",
          "max_subjects",
          "payload_kilobytes"
        ],
        "title": "NatalBatchSummary",
        "type": "object"
      },
      "NatalChartEnhancedRequest": {
        "additionalProperties": false,
        "description": "Request for enhanced natal chart with additional calculations.",
        "example": {
          "configuration": {
            "ayanamsa": "lahiri",
            "coordinate_frame": "equatorial",
            "coordinate_system": "topocentric",
            "house_system": "W",
            "object_set": "asteroids_major",
            "zodiac_type": "sidereal"
          },
          "subject": {
            "birth_datetime": {
              "iso": "1985-03-20T08:15:00"
            },
            "birth_location": {
              "latitude": {
                "decimal": 37.7749
              },
              "longitude": {
                "decimal": -122.4194
              },
              "timezone": {
                "iana_name": "America/Los_Angeles"
              }
            },
            "name": "Jane Smith"
          }
        },
        "properties": {
          "aspect_orb_preset": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "deprecated": true,
            "description": "DEPRECATED. Aspect orb preset name. Prefer sending this via enhanced option payloads where applicable. Accepted for backward compatibility.",
            "title": "Aspect Orb Preset",
            "x-ui-hidden": true
          },
          "configuration": {
            "allOf": [
              {
                "$ref": "#/components/schemas/NatalEnhancedConfig"
              }
            ],
            "description": "Engine-referenced enhanced configuration"
          },
          "custom_orb_config": {
            "anyOf": [
              {
                "type": "object"
              }
            ],
            "deprecated": true,
            "description": "DEPRECATED. Custom aspect orb configuration. Prefer sending this via enhanced option payloads where applicable. Accepted for backward compatibility.",
            "title": "Custom Orb Config",
            "x-ui-hidden": true
          },
          "enhanced_options": {
            "$ref": "#/components/schemas/EnhancedCalculationOptions",
            "description": "Options for enhanced calculations"
          },
          "include_all_traditional_parts": {
            "anyOf": [
              {
                "type": "boolean"
              }
            ],
            "deprecated": true,
            "description": "DEPRECATED. Prefer request body `options.include_all_traditional_parts` where applicable. This top-level field is accepted for backward compatibility and may be removed in a future release.",
            "title": "Include All Traditional Parts",
            "x-ui-hidden": true
          },
          "include_aspects": {
            "anyOf": [
              {
                "type": "boolean"
              }
            ],
            "deprecated": true,
            "description": "DEPRECATED. Prefer request body `options.include_aspects`. This field is accepted for backward compatibility and may be removed in a future release.",
            "title": "Include Aspects",
            "x-ui-hidden": true
          },
          "include_astrocartography": {
            "anyOf": [
              {
                "type": "boolean"
              }
            ],
            "deprecated": true,
            "description": "DEPRECATED. ACG output is controlled by dedicated ACG endpoints; this field is accepted for backward compatibility.",
            "title": "Include Astrocartography",
            "x-ui-hidden": true
          },
          "include_dignities": {
            "anyOf": [
              {
                "type": "boolean"
              }
            ],
            "deprecated": true,
            "description": "DEPRECATED. Prefer request body `options.include_dignities`. This top-level field is accepted for backward compatibility and may be removed in a future release.",
            "title": "Include Dignities",
            "x-ui-hidden": true
          },
          "include_hermetic_lots": {
            "anyOf": [
              {
                "type": "boolean"
              }
            ],
            "deprecated": true,
            "description": "DEPRECATED. Prefer request body `enhanced_options.include_hermetic_lots` (or `options.include_hermetic_lots`). This top-level field is accepted for backward compatibility and may be removed in a future release.",
            "title": "Include Hermetic Lots",
            "x-ui-hidden": true
          },
          "include_visual": {
            "default": false,
            "description": "When true, a high-fidelity chart wheel SVG/PNG is embedded in the response alongside the data payload. Adds 2 credits to the request cost.",
            "nullable": true,
            "title": "Include Visual",
            "type": "boolean"
          },
          "metadata_level": {
            "default": "standard",
            "description": "Controls metadata verbosity for enhanced responses. Common values: standard | full | audit.",
            "example": "standard",
            "title": "Metadata Level",
            "type": "string"
          },
          "options": {
            "$ref": "#/components/schemas/ResponseOptions",
            "description": "Response formatting options"
          },
          "subject": {
            "allOf": [
              {
                "$ref": "#/components/schemas/SubjectRequest"
              }
            ],
            "description": "Subject birth information"
          },
          "transit_datetime": {
            "$ref": "#/components/schemas/DateTimeInput",
            "description": "Transit datetime override. When provided on the /predictive/transit-chart endpoint, this datetime is used as the chart moment instead of the subject's birth_datetime."
          },
          "visual_config": {
            "$ref": "#/components/schemas/VisualRenderConfig",
            "description": "Optional rendering preferences for the inline visual. Defaults: theme=light, size=800, format=svg."
          }
        },
        "required": [
          "subject"
        ],
        "title": "NatalChartEnhancedRequest",
        "type": "object"
      },
      "NatalChartEnhancedResponse": {
        "additionalProperties": true,
        "description": "Enhanced natal chart response with additional calculations.\n\nAdjusted to match test expectations: aspects as a list, optional aspect_matrix,\npermissive calculation_metadata, and chart_type echo.",
        "properties": {
          "angles": {
            "allOf": [
              {
                "$ref": "#/components/schemas/AnglesResponse"
              }
            ],
            "description": "Chart angles"
          },
          "apsides": {
            "anyOf": [
              {
                "type": "object"
              }
            ],
            "description": "Apsides context (periapsis/apoapsis points: perihelion/aphelion; Moon perigee/apogee) and simple separations to current longitudes (opt-in).",
            "title": "Apsides"
          },
          "arabic_parts": {
            "$ref": "#/components/schemas/ArabicPartsResponse",
            "description": "Arabic parts payload"
          },
          "aspect_matrix": {
            "$ref": "#/components/schemas/AspectMatrixResponse",
            "description": "Aspect matrix summary"
          },
          "aspect_patterns": {
            "anyOf": [
              {
                "items": {
                  "$ref": "#/components/schemas/AspectPattern"
                },
                "type": "array"
              }
            ],
            "description": "Detected aspect patterns (Grand Trine, T-Square, Yod, Kite, Stellium, Grand Cross)",
            "title": "Aspect Patterns"
          },
          "aspects": {
            "description": "Enhanced aspects list",
            "items": {
              "$ref": "#/components/schemas/EnhancedAspectResponse"
            },
            "title": "Aspects",
            "type": "array"
          },
          "calculation_metadata": {
            "allOf": [
              {
                "$ref": "#/components/schemas/CalculationMetadata"
              }
            ],
            "description": "Calculation metadata"
          },
          "chart_shape": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Overall chart shape",
            "title": "Chart Shape"
          },
          "chart_type": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Chart type identifier",
            "title": "Chart Type"
          },
          "declination_aspects": {
            "anyOf": [
              {
                "items": {
                  "$ref": "#/components/schemas/DeclinationAspect"
                },
                "type": "array"
              }
            ],
            "description": "Declination-based aspects",
            "title": "Declination Aspects"
          },
          "element_balance": {
            "anyOf": [
              {
                "additionalProperties": {
                  "type": "number"
                },
                "type": "object"
              }
            ],
            "description": "Elemental balance",
            "title": "Element Balance"
          },
          "elongations": {
            "anyOf": [
              {
                "type": "object"
              }
            ],
            "description": "Sun-relative elongations (per-body separation and signed east/west delta) (opt-in).",
            "title": "Elongations"
          },
          "fixed_stars": {
            "$ref": "#/components/schemas/FixedStarsResponse",
            "description": "Fixed star data"
          },
          "harmonics": {
            "anyOf": [
              {
                "additionalProperties": {
                  "type": "object"
                },
                "type": "object"
              }
            ],
            "description": "Harmonic chart positions keyed by harmonic number",
            "title": "Harmonics"
          },
          "hemisphere_emphasis": {
            "anyOf": [
              {
                "additionalProperties": {
                  "type": "number"
                },
                "type": "object"
              }
            ],
            "description": "Hemisphere weights",
            "title": "Hemisphere Emphasis"
          },
          "hermetic_lots": {
            "anyOf": [
              {
                "additionalProperties": {
                  "$ref": "#/components/schemas/HermeticLotResponse"
                },
                "type": "object"
              }
            ],
            "description": "Hermetic lots",
            "title": "Hermetic Lots"
          },
          "hermetic_lots_metadata": {
            "$ref": "#/components/schemas/HermeticLotsMetadata",
            "description": "Metadata describing Hermetic lot calculations"
          },
          "houses": {
            "allOf": [
              {
                "$ref": "#/components/schemas/HousesResponse"
              }
            ],
            "description": "House information"
          },
          "human_design_gates": {
            "anyOf": [
              {
                "type": "object"
              }
            ],
            "description": "Human Design / I Ching gate + line mappings from ecliptic longitude (math-only; includes mapping version) (opt-in).",
            "title": "Human Design Gates"
          },
          "lunar_phase": {
            "anyOf": [
              {
                "type": "object"
              }
            ],
            "description": "Lunar phase context (phase name, illumination, phase angle, waxing/waning, days-to-new/full) (opt-in).",
            "title": "Lunar Phase"
          },
          "midpoints": {
            "anyOf": [
              {
                "items": {
                  "type": "object"
                },
                "type": "array"
              }
            ],
            "description": "Calculated midpoints between planet pairs",
            "title": "Midpoints"
          },
          "patterns_by_type": {
            "anyOf": [
              {
                "additionalProperties": {
                  "items": {
                    "type": "object"
                  },
                  "type": "array"
                },
                "type": "object"
              }
            ],
            "description": "Patterns organized by type for easier filtering",
            "title": "Patterns By Type"
          },
          "planets": {
            "additionalProperties": {
              "$ref": "#/components/schemas/PlanetResponse"
            },
            "description": "Planetary positions keyed by name",
            "title": "Planets",
            "type": "object"
          },
          "retrograde_shadows": {
            "anyOf": [
              {
                "type": "object"
              }
            ],
            "description": "Retrograde stations and shadow window estimates (opt-in; bounded scan around chart datetime).",
            "title": "Retrograde Shadows"
          },
          "sect_determination": {
            "$ref": "#/components/schemas/SectDeterminationResponse",
            "description": "Sect analysis"
          },
          "solar_relationships": {
            "anyOf": [
              {
                "type": "object"
              }
            ],
            "description": "Solar relationship / visibility classifications (e.g., cazimi/combust/under-beams) and Mercury/Venus morning/evening star context.",
            "title": "Solar Relationships"
          },
          "subject": {
            "allOf": [
              {
                "$ref": "#/components/schemas/SubjectResponse"
              }
            ],
            "description": "Subject information"
          },
          "success": {
            "default": true,
            "description": "Response success status",
            "title": "Success",
            "type": "boolean"
          },
          "synodic_phases": {
            "anyOf": [
              {
                "type": "object"
              }
            ],
            "description": "Synodic phase classifications derived from Sun-relative geometry (currently Mercury/Venus).",
            "title": "Synodic Phases"
          },
          "visual": {
            "$ref": "#/components/schemas/VisualResult",
            "description": "Inline chart wheel visual, present only when include_visual=true was requested."
          },
          "void_of_course": {
            "anyOf": [
              {
                "type": "object"
              }
            ],
            "description": "Void-of-Course Moon context (status, start/end window, last major aspect, sign context) (opt-in).",
            "title": "Void Of Course"
          }
        },
        "required": [
          "subject",
          "planets",
          "houses",
          "angles",
          "calculation_metadata"
        ],
        "title": "NatalChartEnhancedResponse",
        "type": "object"
      },
      "NatalChartRequest": {
        "additionalProperties": false,
        "description": "Request for natal chart calculation.",
        "example": {
          "configuration": {
            "coordinate_system": "geocentric",
            "house_system": "P",
            "object_set": "modern_plus_chiron",
            "zodiac_type": "tropical"
          },
          "options": {
            "include_aspects": true
          },
          "subject": {
            "birth_datetime": {
              "iso": "1990-06-15T14:30:00"
            },
            "birth_location": {
              "latitude": {
                "decimal": 40.7128
              },
              "longitude": {
                "decimal": -74.006
              },
              "timezone": {
                "iana_name": "America/New_York"
              }
            },
            "name": "John Doe"
          }
        },
        "properties": {
          "configuration": {
            "allOf": [
              {
                "$ref": "#/components/schemas/NatalConfig"
              }
            ],
            "description": "Engine-referenced natal configuration"
          },
          "options": {
            "$ref": "#/components/schemas/ResponseOptions",
            "description": "Response formatting options"
          },
          "subject": {
            "allOf": [
              {
                "$ref": "#/components/schemas/SubjectRequest"
              }
            ],
            "description": "Subject birth information"
          }
        },
        "required": [
          "subject"
        ],
        "title": "NatalChartRequest",
        "type": "object"
      },
      "NatalChartResponse": {
        "additionalProperties": true,
        "description": "Complete natal chart response (legacy contract).",
        "properties": {
          "angles": {
            "allOf": [
              {
                "$ref": "#/components/schemas/AnglesResponse"
              }
            ],
            "description": "Chart angles"
          },
          "aspects": {
            "description": "Aspect list",
            "items": {
              "$ref": "#/components/schemas/AspectResponse"
            },
            "title": "Aspects",
            "type": "array"
          },
          "calculation_time": {
            "description": "Calculation time (ISO)",
            "title": "Calculation Time",
            "type": "string"
          },
          "chart_type": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Chart type identifier",
            "title": "Chart Type"
          },
          "declination_aspects": {
            "anyOf": [
              {
                "items": {
                  "$ref": "#/components/schemas/DeclinationAspect"
                },
                "type": "array"
              }
            ],
            "description": "Parallel and contraparallel declination aspects",
            "title": "Declination Aspects"
          },
          "features_included": {
            "description": "List of feature flags included",
            "items": {
              "type": "string"
            },
            "title": "Features Included",
            "type": "array"
          },
          "hermetic_lots": {
            "anyOf": [
              {
                "additionalProperties": {
                  "$ref": "#/components/schemas/LotPosition"
                },
                "type": "object"
              }
            ],
            "description": "Traditional Hermetic Lots keyed by identifier",
            "title": "Hermetic Lots"
          },
          "houses": {
            "allOf": [
              {
                "$ref": "#/components/schemas/HousesResponse"
              }
            ],
            "description": "House information"
          },
          "planets": {
            "additionalProperties": {
              "$ref": "#/components/schemas/PlanetResponse"
            },
            "description": "Planetary positions keyed by name",
            "title": "Planets",
            "type": "object"
          },
          "subject": {
            "allOf": [
              {
                "$ref": "#/components/schemas/SubjectResponse"
              }
            ],
            "description": "Subject information"
          },
          "success": {
            "default": true,
            "description": "Response success status",
            "title": "Success",
            "type": "boolean"
          },
          "summary": {
            "description": "Summary metadata dictionary",
            "title": "Summary",
            "type": "object"
          }
        },
        "required": [
          "subject",
          "planets",
          "houses",
          "angles",
          "aspects",
          "calculation_time",
          "summary",
          "features_included"
        ],
        "title": "NatalChartResponse",
        "type": "object"
      },
      "NatalConfig": {
        "additionalProperties": false,
        "description": "Declarative configuration for natal calculations.",
        "example": {
          "coordinate_system": "geocentric",
          "delta_t_profile": "swiss_default",
          "house_system": "P",
          "object_set": "modern_plus_chiron",
          "zodiac_type": "tropical"
        },
        "properties": {
          "ascendant_on_left": {
            "default": true,
            "description": "When true (default), the Ascendant is placed at the 9 o'clock (West/left) position � matching the convention used by Astro.com, Solar Fire, and all major astrology software. Set to false to use the ecliptic-fixed (Aries-pinned) orientation instead.",
            "nullable": true,
            "title": "Ascendant on Left",
            "type": "boolean"
          },
          "asteroid_groups": {
            "anyOf": [
              {
                "items": {
                  "$ref": "#/components/schemas/AsteroidGroupEnum"
                },
                "type": "array"
              }
            ],
            "description": "Optional thematic asteroid groups to include alongside base object_set",
            "title": "Asteroid Groups"
          },
          "ayanamsa": {
            "$ref": "#/components/schemas/AyanamsaEnum",
            "description": "Sidereal ayanamsa (required when zodiac_type=sidereal)"
          },
          "coordinate_frame": {
            "allOf": [
              {
                "$ref": "#/components/schemas/CoordinateFrameEnum"
              }
            ],
            "default": "ecliptic",
            "description": "Reference frame for returned positions"
          },
          "coordinate_system": {
            "allOf": [
              {
                "$ref": "#/components/schemas/CoordinateSystemEnum"
              }
            ],
            "default": "geocentric",
            "description": "Coordinate system for base calculations (SE §4)"
          },
          "delta_t_profile": {
            "allOf": [
              {
                "$ref": "#/components/schemas/DeltaTProfileEnum"
              }
            ],
            "default": "swiss_default",
            "description": "ΔT curve selection (SE §7)"
          },
          "fixed_star_options": {
            "$ref": "#/components/schemas/FixedStarConfig",
            "description": "Detailed fixed star options"
          },
          "house_system": {
            "allOf": [
              {
                "$ref": "#/components/schemas/HouseSystemEnum"
              }
            ],
            "default": "P",
            "description": "House system (SE §6.2)"
          },
          "node_source": {
            "allOf": [
              {
                "$ref": "#/components/schemas/NodeSourceEnum"
              }
            ],
            "default": "true_osculating",
            "description": "Node/apsides mode (SE §2.2)"
          },
          "object_set": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ObjectSetEnum"
              }
            ],
            "default": "modern_plus_chiron",
            "description": "Celestial object bundle"
          },
          "validation_profile": {
            "$ref": "#/components/schemas/ValidationProfileEnum",
            "description": "Optional validation profile identifier"
          },
          "zodiac_type": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ZodiacTypeEnum"
              }
            ],
            "default": "tropical",
            "description": "Zodiac reference (tropical or sidereal)"
          }
        },
        "title": "NatalConfig",
        "type": "object"
      },
      "NatalEnhancedConfig": {
        "additionalProperties": false,
        "description": "Extended configuration for enhanced natal outputs.",
        "example": {
          "coordinate_system": "geocentric",
          "delta_t_profile": "swiss_default",
          "house_system": "P",
          "object_set": "modern_plus_chiron",
          "zodiac_type": "tropical"
        },
        "properties": {
          "additional_objects": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              }
            ],
            "description": "Optional list of additional computed objects (Chiron, Lilith, COB IDs)",
            "title": "Additional Objects"
          },
          "ascendant_on_left": {
            "default": true,
            "description": "When true (default), the Ascendant is placed at the 9 o'clock (West/left) position � matching the convention used by Astro.com, Solar Fire, and all major astrology software. Set to false to use the ecliptic-fixed (Aries-pinned) orientation instead.",
            "nullable": true,
            "title": "Ascendant on Left",
            "type": "boolean"
          },
          "asteroid_groups": {
            "anyOf": [
              {
                "items": {
                  "$ref": "#/components/schemas/AsteroidGroupEnum"
                },
                "type": "array"
              }
            ],
            "description": "Optional thematic asteroid groups to include alongside base object_set",
            "title": "Asteroid Groups"
          },
          "ayanamsa": {
            "$ref": "#/components/schemas/AyanamsaEnum",
            "description": "Sidereal ayanamsa (required when zodiac_type=sidereal)"
          },
          "coordinate_frame": {
            "allOf": [
              {
                "$ref": "#/components/schemas/CoordinateFrameEnum"
              }
            ],
            "default": "ecliptic",
            "description": "Reference frame for returned positions"
          },
          "coordinate_system": {
            "allOf": [
              {
                "$ref": "#/components/schemas/CoordinateSystemEnum"
              }
            ],
            "default": "geocentric",
            "description": "Coordinate system for base calculations (SE §4)"
          },
          "delta_t_profile": {
            "allOf": [
              {
                "$ref": "#/components/schemas/DeltaTProfileEnum"
              }
            ],
            "default": "swiss_default",
            "description": "ΔT curve selection (SE §7)"
          },
          "dignities": {
            "allOf": [
              {
                "$ref": "#/components/schemas/DignityConfig"
              }
            ],
            "description": "Dignity configuration"
          },
          "fixed_star_options": {
            "allOf": [
              {
                "$ref": "#/components/schemas/FixedStarConfig"
              }
            ],
            "description": "Enhanced fixed star configuration"
          },
          "house_system": {
            "allOf": [
              {
                "$ref": "#/components/schemas/HouseSystemEnum"
              }
            ],
            "default": "P",
            "description": "House system (SE §6.2)"
          },
          "lots": {
            "allOf": [
              {
                "$ref": "#/components/schemas/LotsConfig"
              }
            ],
            "description": "Arabic parts configuration"
          },
          "node_source": {
            "allOf": [
              {
                "$ref": "#/components/schemas/NodeSourceEnum"
              }
            ],
            "default": "true_osculating",
            "description": "Node/apsides mode (SE §2.2)"
          },
          "object_set": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ObjectSetEnum"
              }
            ],
            "default": "modern_plus_chiron",
            "description": "Celestial object bundle"
          },
          "validation_profile": {
            "$ref": "#/components/schemas/ValidationProfileEnum",
            "description": "Optional validation profile identifier"
          },
          "zodiac_type": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ZodiacTypeEnum"
              }
            ],
            "default": "tropical",
            "description": "Zodiac reference (tropical or sidereal)"
          }
        },
        "title": "NatalEnhancedConfig",
        "type": "object"
      },
      "NatalParansRequest": {
        "properties": {
          "subject": {
            "$ref": "#/components/schemas/SubjectRequest"
          }
        },
        "required": [
          "subject"
        ],
        "type": "object"
      },
      "NatalTransitsRequest": {
        "additionalProperties": false,
        "description": "Transit overlay request using a natal subject plus a target datetime.",
        "example": {
          "subject": {
            "birth_datetime": {
              "iso": "1990-06-15T14:30:00"
            },
            "birth_location": {
              "latitude": {
                "decimal": 40.7128
              },
              "longitude": {
                "decimal": -74.006
              },
              "timezone": {
                "iana_name": "America/New_York"
              }
            },
            "name": "Alice"
          },
          "transit_datetime": {
            "iso": "2025-01-01T00:00:00Z"
          }
        },
        "properties": {
          "configuration": {
            "$ref": "#/components/schemas/ChartConfiguration",
            "description": "Chart calculation settings"
          },
          "enhanced_options": {
            "$ref": "#/components/schemas/EnhancedCalculationOptions",
            "description": "Optional enhanced calculation flags applied to the natal and transit charts before cross-aspects are computed. This primarily affects enriched analysis blocks on the underlying enhanced charts (not returned in the json envelope), and will become important once comparative llm formatting includes these analyses."
          },
          "include_visual": {
            "default": false,
            "description": "If true, a full visual SVG or PNG output will be rendered and returned alongside the chart data. Note: Visuals incur a +2 credit surcharge.",
            "title": "Include Visual",
            "type": "boolean"
          },
          "subject": {
            "allOf": [
              {
                "$ref": "#/components/schemas/SubjectRequest"
              }
            ],
            "description": "Natal subject"
          },
          "transit_datetime": {
            "$ref": "#/components/schemas/DateTimeInput",
            "description": "Transit datetime (defaults to now UTC when omitted)"
          },
          "visual_config": {
            "$ref": "#/components/schemas/VisualRenderConfig"
          }
        },
        "required": [
          "subject"
        ],
        "title": "NatalTransitsRequest",
        "type": "object"
      },
      "NatalTransitsResponse": {
        "description": "Response for natal-to-transits overlay.",
        "properties": {
          "aspects": {
            "description": "Cross-aspects between natal and transits",
            "items": {
              "$ref": "#/components/schemas/AspectResponse"
            },
            "title": "Aspects",
            "type": "array"
          },
          "chart_a": {
            "allOf": [
              {
                "$ref": "#/components/schemas/LightChartResponse"
              }
            ],
            "description": "Natal planets"
          },
          "chart_b": {
            "allOf": [
              {
                "$ref": "#/components/schemas/LightChartResponse"
              }
            ],
            "description": "Transit planets"
          },
          "visual": {
            "$ref": "#/components/schemas/VisualResult",
            "description": "Inline chart visual, present only when include_visual=true was requested."
          }
        },
        "required": [
          "chart_a",
          "chart_b",
          "aspects"
        ],
        "title": "NatalTransitsResponse",
        "type": "object"
      },
      "NextVisibleResponse": {
        "properties": {
          "days_until": {
            "title": "Days Until",
            "type": "number"
          },
          "eclipse": {
            "$ref": "#/components/schemas/EclipseSummary"
          },
          "local_circumstances": {
            "$ref": "#/components/schemas/LocalCircumstances"
          }
        },
        "required": [
          "eclipse",
          "days_until"
        ],
        "title": "NextVisibleResponse",
        "type": "object"
      },
      "NodeSourceEnum": {
        "description": "Node/apsides calculation modes (SE §2.2).",
        "enum": [
          "true_osculating",
          "mean",
          "mean_apsides"
        ],
        "title": "NodeSourceEnum",
        "type": "string"
      },
      "ObjectScopeEnum": {
        "description": "Which celestial bodies/angles to include in predictive calculations.",
        "enum": [
          "planets_only",
          "planets_and_angles",
          "planets_and_points",
          "all_bodies"
        ],
        "title": "ObjectScopeEnum",
        "type": "string"
      },
      "ObjectSetEnum": {
        "description": "Standardized celestial object bundles.",
        "enum": [
          "traditional_7",
          "modern_10",
          "modern_plus_chiron",
          "asteroids_major",
          "full",
          "custom"
        ],
        "title": "ObjectSetEnum",
        "type": "string"
      },
      "Observer": {
        "properties": {
          "lat": {
            "description": "Observer latitude",
            "title": "Lat",
            "type": "number"
          },
          "lon": {
            "description": "Observer longitude",
            "title": "Lon",
            "type": "number"
          }
        },
        "required": [
          "lat",
          "lon"
        ],
        "title": "Observer",
        "type": "object"
      },
      "OptimizationCacheClearResponse": {
        "additionalProperties": true,
        "description": "Standard response for predictive cache clear operations.",
        "properties": {
          "cache_types_available": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              }
            ],
            "description": "Cache type identifiers that can be cleared",
            "title": "Cache Types Available"
          },
          "calculation_metadata": {
            "$ref": "#/components/schemas/CalculationMetadata",
            "description": "Standardized calculation metadata describing the optimization cache operation"
          },
          "details": {
            "anyOf": [
              {
                "type": "object"
              }
            ],
            "description": "Optional key-value diagnostic payload",
            "title": "Details"
          },
          "error": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Optional error identifier when success is False",
            "title": "Error"
          },
          "message": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Human-readable status message",
            "title": "Message"
          },
          "recommendation": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Optional follow-up recommendation for clients",
            "title": "Recommendation"
          },
          "success": {
            "description": "Indicates whether the cache was cleared successfully",
            "title": "Success",
            "type": "boolean"
          }
        },
        "required": [
          "success"
        ],
        "title": "OptimizationCacheClearResponse",
        "type": "object"
      },
      "OrbSystemEnum": {
        "description": "Orb system presets.",
        "enum": [
          "standard",
          "fixed",
          "traditional",
          "modern",
          "tight",
          "wide",
          "custom"
        ],
        "title": "OrbSystemEnum",
        "type": "string"
      },
      "OverlayRequest": {
        "additionalProperties": false,
        "description": "Positions-only overlay across 2–10 subjects.",
        "example": {
          "subjects": [
            {
              "birth_datetime": {
                "iso": "1990-06-15T14:30:00"
              },
              "birth_location": {
                "latitude": {
                  "decimal": 40.7128
                },
                "longitude": {
                  "decimal": -74.006
                },
                "timezone": {
                  "iana_name": "America/New_York"
                }
              },
              "name": "Alice"
            },
            {
              "birth_datetime": {
                "iso": "1992-02-10T09:15:00"
              },
              "birth_location": {
                "latitude": {
                  "decimal": 34.0522
                },
                "longitude": {
                  "decimal": -118.2437
                },
                "timezone": {
                  "iana_name": "America/Los_Angeles"
                }
              },
              "name": "Bob"
            }
          ]
        },
        "properties": {
          "configuration": {
            "$ref": "#/components/schemas/ChartConfiguration",
            "description": "Chart calculation settings"
          },
          "subjects": {
            "description": "List of subjects to overlay (2-10).",
            "items": {
              "$ref": "#/components/schemas/SubjectRequest"
            },
            "maxItems": 10,
            "minItems": 2,
            "title": "Subjects",
            "type": "array"
          }
        },
        "required": [
          "subjects"
        ],
        "title": "OverlayRequest",
        "type": "object"
      },
      "OverlayResponse": {
        "description": "Response for positions-only overlay.\n\nReturns lightweight charts for each subject (subject + planets) plus minimal\ncalculation metadata describing the overlay technique.",
        "properties": {
          "calculation_metadata": {
            "allOf": [
              {
                "$ref": "#/components/schemas/CalculationMetadata"
              }
            ],
            "description": "Minimal metadata about how the overlay was computed."
          },
          "charts": {
            "description": "Lightweight chart payloads, one per subject (subject + planets).",
            "items": {
              "$ref": "#/components/schemas/LightChartResponse"
            },
            "title": "Charts",
            "type": "array"
          }
        },
        "required": [
          "charts",
          "calculation_metadata"
        ],
        "title": "OverlayResponse",
        "type": "object"
      },
      "PaginationMetadata": {
        "description": "Pagination info for large result sets.",
        "properties": {
          "has_next": {
            "description": "True if more results available",
            "title": "Has Next",
            "type": "boolean"
          },
          "limit": {
            "default": 500,
            "description": "Results per page",
            "title": "Limit",
            "type": "integer"
          },
          "next_offset": {
            "anyOf": [
              {
                "type": "integer"
              }
            ],
            "description": "Offset for next page (use in next request)",
            "title": "Next Offset"
          },
          "total_count": {
            "anyOf": [
              {
                "type": "integer"
              }
            ],
            "description": "Total events matching filter (if available)",
            "title": "Total Count"
          }
        },
        "required": [
          "has_next"
        ],
        "title": "PaginationMetadata",
        "type": "object"
      },
      "PentaChannel": {
        "description": "Penta Channel Status (The 6 Channels).",
        "properties": {
          "function": {
            "title": "Function",
            "type": "string"
          },
          "id": {
            "title": "Id",
            "type": "string"
          },
          "missing_gates": {
            "items": {
              "type": "integer"
            },
            "title": "Missing Gates",
            "type": "array"
          },
          "name": {
            "title": "Name",
            "type": "string"
          },
          "status": {
            "title": "Status",
            "type": "string"
          }
        },
        "required": [
          "id",
          "name",
          "function",
          "status",
          "missing_gates"
        ],
        "title": "PentaChannel",
        "type": "object"
      },
      "PentaLeadership": {
        "description": "Analysis of the specific leadership gates in the G-Throat.",
        "properties": {
          "alpha_role": {
            "title": "Alpha Role",
            "type": "object"
          },
          "gaps": {
            "items": {
              "type": "string"
            },
            "title": "Gaps",
            "type": "array"
          },
          "style": {
            "title": "Style",
            "type": "string"
          }
        },
        "required": [
          "style",
          "alpha_role",
          "gaps"
        ],
        "title": "PentaLeadership",
        "type": "object"
      },
      "PentaMember": {
        "description": "Input member for a Penta group analysis.",
        "properties": {
          "birth_data": {
            "$ref": "#/components/schemas/HumanDesignChartRequest"
          },
          "id": {
            "title": "Id",
            "type": "string"
          },
          "name": {
            "title": "Name",
            "type": "string"
          }
        },
        "required": [
          "id",
          "name",
          "birth_data"
        ],
        "title": "PentaMember",
        "type": "object"
      },
      "PentaRedundancy": {
        "description": "Highlights areas of high overlap/competition.",
        "properties": {
          "impact": {
            "title": "Impact",
            "type": "string"
          },
          "members": {
            "items": {
              "type": "string"
            },
            "title": "Members",
            "type": "array"
          },
          "skill": {
            "title": "Skill",
            "type": "string"
          }
        },
        "required": [
          "skill",
          "members",
          "impact"
        ],
        "title": "PentaRedundancy",
        "type": "object"
      },
      "PentaRequest": {
        "description": "Request for Penta (Small Group) Analysis.\nValid for 3-5 people.",
        "properties": {
          "format": {
            "default": "json",
            "description": "Response format: json | llm.",
            "title": "Format",
            "type": "string"
          },
          "group_name": {
            "title": "Group Name",
            "type": "string"
          },
          "members": {
            "items": {
              "$ref": "#/components/schemas/PentaMember"
            },
            "maxItems": 5,
            "minItems": 3,
            "title": "Members",
            "type": "array"
          },
          "settings": {
            "anyOf": [
              {
                "type": "object"
              }
            ],
            "description": "Optional settings like house system or perspective",
            "title": "Settings"
          }
        },
        "required": [
          "group_name",
          "members"
        ],
        "title": "PentaRequest",
        "type": "object"
      },
      "PentaResponse": {
        "description": "Penta (Group) Analysis Response.\nFocuses on the Trans-auric form emergent from 3-5 people.",
        "properties": {
          "channels": {
            "items": {
              "$ref": "#/components/schemas/PentaChannel"
            },
            "title": "Channels",
            "type": "array"
          },
          "functional_attributes": {
            "items": {
              "$ref": "#/components/schemas/PentaSkillAttribute"
            },
            "title": "Functional Attributes",
            "type": "array"
          },
          "leadership_dynamics": {
            "$ref": "#/components/schemas/PentaLeadership"
          },
          "metadata": {
            "title": "Metadata",
            "type": "object"
          },
          "penta_summary": {
            "$ref": "#/components/schemas/PentaSummary"
          },
          "redundancies": {
            "items": {
              "$ref": "#/components/schemas/PentaRedundancy"
            },
            "title": "Redundancies",
            "type": "array"
          }
        },
        "required": [
          "penta_summary",
          "functional_attributes",
          "channels",
          "leadership_dynamics",
          "redundancies",
          "metadata"
        ],
        "title": "PentaResponse",
        "type": "object"
      },
      "PentaSkillAttribute": {
        "description": "Analysis of one of the 12 functional Penta skills.",
        "properties": {
          "contributors": {
            "items": {
              "type": "string"
            },
            "title": "Contributors",
            "type": "array"
          },
          "gate": {
            "title": "Gate",
            "type": "integer"
          },
          "redundancy": {
            "title": "Redundancy",
            "type": "integer"
          },
          "skill": {
            "title": "Skill",
            "type": "string"
          },
          "status": {
            "title": "Status",
            "type": "string"
          }
        },
        "required": [
          "gate",
          "skill",
          "status",
          "contributors",
          "redundancy"
        ],
        "title": "PentaSkillAttribute",
        "type": "object"
      },
      "PentaSummary": {
        "description": "High-level summary of the group dynamic.",
        "properties": {
          "functional_score": {
            "title": "Functional Score",
            "type": "number"
          },
          "group_size": {
            "title": "Group Size",
            "type": "integer"
          },
          "primary_gap": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "title": "Primary Gap"
          },
          "stability": {
            "title": "Stability",
            "type": "string"
          }
        },
        "required": [
          "stability",
          "functional_score",
          "group_size"
        ],
        "title": "PentaSummary",
        "type": "object"
      },
      "PlanetHouseChange": {
        "additionalProperties": false,
        "description": "Represents a planet that shifted houses after relocation.",
        "properties": {
          "body": {
            "description": "Name of the celestial body",
            "title": "Body",
            "type": "string"
          },
          "from_house": {
            "description": "Original house index",
            "maximum": 12,
            "minimum": 1,
            "title": "From House",
            "type": "integer"
          },
          "to_house": {
            "description": "Relocated house index",
            "maximum": 12,
            "minimum": 1,
            "title": "To House",
            "type": "integer"
          }
        },
        "required": [
          "body",
          "from_house",
          "to_house"
        ],
        "title": "PlanetHouseChange",
        "type": "object"
      },
      "PlanetPositionRequest": {
        "additionalProperties": false,
        "description": "Parameters for calculating the exact astronomical position of a single celestial body at a specific moment in time.",
        "example": {
          "date_time": {
            "iso": "2025-12-11T12:00:00Z"
          },
          "latitude": 40.7128,
          "longitude": -74.006,
          "planet_id": 0
        },
        "properties": {
          "date_time": {
            "allOf": [
              {
                "$ref": "#/components/schemas/DateTimeInput"
              }
            ],
            "description": "Calculation datetime in ISO, components, or Julian day format",
            "example": {
              "iso": "2000-01-01T12:00:00Z"
            }
          },
          "latitude": {
            "anyOf": [
              {
                "maximum": 90,
                "minimum": -90,
                "type": "number"
              }
            ],
            "description": "Observer latitude in decimal degrees (omit for geocentric calculation)",
            "example": 40.7128,
            "title": "Latitude"
          },
          "longitude": {
            "anyOf": [
              {
                "maximum": 180,
                "minimum": -180,
                "type": "number"
              }
            ],
            "description": "Observer longitude in decimal degrees (omit for geocentric calculation)",
            "example": -74.006,
            "title": "Longitude"
          },
          "planet_id": {
            "description": "SE-compatible planet ID (0=Sun, 1=Moon, 2=Mercury, etc.)",
            "example": 0,
            "title": "Planet Id",
            "type": "integer"
          }
        },
        "required": [
          "planet_id",
          "date_time"
        ],
        "title": "PlanetPositionRequest",
        "type": "object"
      },
      "PlanetPositionResponse": {
        "additionalProperties": false,
        "description": "Response from planet position calculation.",
        "properties": {
          "calculation_metadata": {
            "$ref": "#/components/schemas/CalculationMetadata",
            "description": "Calculation metadata (Julian day, coordinate system, etc.)"
          },
          "planet": {
            "allOf": [
              {
                "$ref": "#/components/schemas/PlanetResponse"
              }
            ],
            "description": "Planet position and metadata"
          },
          "success": {
            "default": true,
            "description": "Calculation success status",
            "title": "Success",
            "type": "boolean"
          }
        },
        "required": [
          "planet"
        ],
        "title": "PlanetPositionResponse",
        "type": "object"
      },
      "PlanetResponse": {
        "additionalProperties": true,
        "description": "Planet position data in response.",
        "properties": {
          "accidental_dignities": {
            "$ref": "#/components/schemas/AccidentalDignityInfo",
            "description": "Accidental dignities (tags-only; currently derived from house placement when available)"
          },
          "declination": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "description": "Declination in degrees",
            "title": "Declination"
          },
          "distance": {
            "description": "Distance from Earth",
            "title": "Distance",
            "type": "number"
          },
          "element": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Element (Fire, Earth, Air, Water)",
            "title": "Element"
          },
          "essential_dignities": {
            "$ref": "#/components/schemas/EssentialDignityInfo",
            "description": "Essential dignity analysis (requires enhanced calculation)"
          },
          "house_number": {
            "anyOf": [
              {
                "type": "integer"
              }
            ],
            "description": "House number (1-12)",
            "title": "House Number"
          },
          "is_retrograde": {
            "default": false,
            "description": "Whether planet is in retrograde motion (longitude_speed \u003c 0)",
            "title": "Is Retrograde",
            "type": "boolean"
          },
          "latitude": {
            "description": "Ecliptic latitude in degrees",
            "title": "Latitude",
            "type": "number"
          },
          "longitude": {
            "description": "Ecliptic longitude in degrees",
            "title": "Longitude",
            "type": "number"
          },
          "longitude_speed": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "description": "Longitude speed in degrees/day",
            "title": "Longitude Speed"
          },
          "modality": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Modality (Cardinal, Fixed, Mutable)",
            "title": "Modality"
          },
          "motion_type": {
            "default": "direct",
            "description": "Motion classification: direct, retrograde, stationary, or unknown",
            "example": "direct",
            "title": "Motion Type",
            "type": "string"
          },
          "name": {
            "description": "Planet name",
            "title": "Name",
            "type": "string"
          },
          "on_cusp": {
            "default": false,
            "description": "True when longitude is within cusp tolerance and planet is treated as entering the next house",
            "title": "On Cusp",
            "type": "boolean"
          },
          "out_of_bounds": {
            "default": false,
            "description": "Planet exceeds solar declination bounds",
            "title": "Out Of Bounds",
            "type": "boolean"
          },
          "right_ascension": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "description": "Geocentric right ascension in degrees",
            "title": "Right Ascension"
          },
          "sign_longitude": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "description": "Longitude within sign",
            "title": "Sign Longitude"
          },
          "sign_name": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Zodiac sign name",
            "title": "Sign Name"
          },
          "sign_symbol": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Zodiac sign symbol",
            "title": "Sign Symbol"
          },
          "topocentric_declination": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "description": "Topocentric declination in degrees (when applicable)",
            "title": "Topocentric Declination"
          },
          "topocentric_right_ascension": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "description": "Topocentric right ascension in degrees (when applicable)",
            "title": "Topocentric Right Ascension"
          }
        },
        "required": [
          "name",
          "longitude",
          "latitude",
          "distance"
        ],
        "title": "PlanetResponse",
        "type": "object"
      },
      "PlanetTransitRequest": {
        "additionalProperties": false,
        "description": "Request schema for planetary transit calculation.",
        "example": {
          "max_crossings": 3,
          "planet_name": "Mars",
          "start_date": "2024-01-01T00:00:00Z",
          "target_degree": 15.5
        },
        "properties": {
          "max_crossings": {
            "anyOf": [
              {
                "type": "integer"
              }
            ],
            "default": 1,
            "description": "Maximum crossings to find (for retrograde)",
            "title": "Max Crossings"
          },
          "planet_name": {
            "description": "Planet name (validated in route)",
            "title": "Planet Name",
            "type": "string"
          },
          "start_date": {
            "description": "Starting date for search",
            "format": "date-time",
            "title": "Start Date",
            "type": "string"
          },
          "target_degree": {
            "description": "Target longitude degree (0-360)",
            "title": "Target Degree",
            "type": "number"
          }
        },
        "required": [
          "planet_name",
          "target_degree",
          "start_date"
        ],
        "title": "PlanetTransitRequest",
        "type": "object"
      },
      "PlanetTransitResponse": {
        "description": "Response schema for planetary transit calculation.",
        "properties": {
          "calculation_metadata": {
            "$ref": "#/components/schemas/CalculationMetadata",
            "description": "Standardized calculation metadata describing the transit computation"
          },
          "metadata": {
            "allOf": [
              {
                "$ref": "#/components/schemas/PredictiveMetadata"
              }
            ],
            "description": "Calculation metadata"
          },
          "success": {
            "description": "Request success status",
            "title": "Success",
            "type": "boolean"
          },
          "total_count": {
            "description": "Number of transits found",
            "title": "Total Count",
            "type": "integer"
          },
          "transits": {
            "description": "Found transits",
            "items": {
              "$ref": "#/components/schemas/Transit"
            },
            "title": "Transits",
            "type": "array"
          }
        },
        "required": [
          "success",
          "transits",
          "total_count",
          "metadata"
        ],
        "title": "PlanetTransitResponse",
        "type": "object"
      },
      "PlanetaryReturnRequest": {
        "additionalProperties": false,
        "description": "Return timing request for a body near a target datetime.",
        "example": {
          "birth_datetime": {
            "iso": "1990-06-15T14:30:00Z"
          },
          "body": "Sun",
          "house_system": "P",
          "include_chart": true,
          "location": {
            "elevation": 10,
            "latitude": {
              "decimal": 40.7128
            },
            "longitude": {
              "decimal": -74.006
            },
            "timezone": {
              "iana_name": "UTC"
            }
          },
          "return_location": {
            "elevation": 71,
            "latitude": {
              "decimal": 34.0522
            },
            "longitude": {
              "decimal": -118.2437
            },
            "timezone": {
              "iana_name": "UTC"
            }
          },
          "search_window_days": 5,
          "target_datetime": {
            "iso": "2024-06-15T00:00:00Z"
          }
        },
        "properties": {
          "birth_datetime": {
            "allOf": [
              {
                "$ref": "#/components/schemas/DateTimeInput"
              }
            ],
            "description": "Birth date/time (ISO-8601, components, or Julian day)"
          },
          "body": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ReturnBodyEnum"
              }
            ],
            "description": "Body for return calculation"
          },
          "enhanced_options": {
            "$ref": "#/components/schemas/EnhancedCalculationOptions",
            "description": "Optional enhanced calculation flags applied when include_chart=true and preset=simple or format=llm. This controls additional computed analysis blocks (e.g., Human Design gates, lunar phase, midpoints)."
          },
          "house_system": {
            "$ref": "#/components/schemas/HouseSystemEnum",
            "default": "P",
            "description": "House system for chart calculation (P=Placidus, K=Koch, W=Whole Sign, etc.)"
          },
          "include_chart": {
            "default": false,
            "description": "Include full chart at return moment",
            "title": "Include Chart",
            "type": "boolean"
          },
          "include_visual": {
            "default": false,
            "description": "If true, a full visual SVG or PNG output will be rendered and returned alongside the chart data. Note: Visuals incur a +2 credit surcharge.",
            "title": "Include Visual",
            "type": "boolean"
          },
          "location": {
            "$ref": "#/components/schemas/LocationInput",
            "description": "Location context (timezone + optional elevation)"
          },
          "return_location": {
            "$ref": "#/components/schemas/LocationInput",
            "description": "Optional location for the return chart (defaults to `location` if omitted)"
          },
          "search_window_days": {
            "anyOf": [
              {
                "maximum": 5000,
                "minimum": 1,
                "type": "integer"
              }
            ],
            "description": "Days to search symmetrically around target datetime (defaults depend on body)",
            "title": "Search Window Days"
          },
          "target_datetime": {
            "allOf": [
              {
                "$ref": "#/components/schemas/DateTimeInput"
              }
            ],
            "description": "Target datetime to search around (ISO-8601, components, or Julian day)"
          },
          "visual_config": {
            "$ref": "#/components/schemas/VisualRenderConfig"
          }
        },
        "required": [
          "body",
          "birth_datetime",
          "target_datetime"
        ],
        "title": "PlanetaryReturnRequest",
        "type": "object"
      },
      "PlanetaryReturnResponse": {
        "description": "Response payload for unified return calculations.",
        "properties": {
          "calculation_metadata": {
            "$ref": "#/components/schemas/CalculationMetadata",
            "description": "Standardized calculation metadata describing the return computation"
          },
          "chart": {
            "$ref": "#/components/schemas/NatalChartResponse",
            "description": "Full chart calculation at return moment (if include_chart=True)"
          },
          "exact_datetime": {
            "description": "Exact return datetime (UTC)",
            "format": "date-time",
            "title": "Exact Datetime",
            "type": "string"
          },
          "location": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ReturnLocation"
              }
            ],
            "description": "Normalized location used for chart calculation"
          },
          "metadata": {
            "allOf": [
              {
                "$ref": "#/components/schemas/PredictiveMetadata"
              }
            ],
            "description": "Calculation metadata"
          },
          "output_mode": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Output projection mode (full | simple | llm)",
            "title": "Output Mode"
          },
          "schema_version": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Schema version for the selected output mode (e.g., full_v1, simple_v1, llm)",
            "title": "Schema Version"
          },
          "success": {
            "description": "Request success status",
            "title": "Success",
            "type": "boolean"
          },
          "visual": {
            "$ref": "#/components/schemas/VisualResult",
            "description": "Inline chart visual, present only when include_visual=true was requested."
          }
        },
        "required": [
          "success",
          "exact_datetime",
          "location",
          "metadata"
        ],
        "title": "PlanetaryReturnResponse",
        "type": "object"
      },
      "PositionInput": {
        "additionalProperties": false,
        "description": "A precomputed body position for direct wheel rendering. Supply instead of birth params to draw an arbitrary chart (e.g. solar arc, progressed/transit hybrid).",
        "properties": {
          "body": {
            "description": "Canonical lowercase body key (e.g. 'sun', 'moon', 'north_node'). Unknown keys render with a generic marker and the key as label.",
            "minLength": 1,
            "title": "Body",
            "type": "string"
          },
          "longitude": {
            "description": "Ecliptic longitude in degrees [0, 360).",
            "maximum": 360,
            "minimum": 0,
            "title": "Longitude",
            "type": "number"
          },
          "retrograde": {
            "description": "Explicit retrograde flag. Defaults to speed \u003c 0 when speed is given, else false.",
            "title": "Retrograde",
            "type": "boolean"
          },
          "speed": {
            "description": "Longitudinal speed in deg/day. When present and negative (and 'retrograde' is omitted), the body is treated as retrograde.",
            "title": "Speed",
            "type": "number"
          }
        },
        "required": [
          "body"
        ],
        "title": "PositionInput",
        "type": "object"
      },
      "PrecisionSummary": {
        "additionalProperties": true,
        "description": "Structured precision report for calculation metadata.",
        "properties": {
          "max_position_error_arcseconds": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "description": "Maximum validated positional error in arcseconds",
            "title": "Max Position Error Arcseconds"
          },
          "max_timing_error_seconds": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "description": "Maximum validated timing error in seconds",
            "title": "Max Timing Error Seconds"
          },
          "notes": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Additional human-readable context for the precision summary",
            "title": "Notes"
          },
          "reference_profile": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Reference dataset or validation profile used for the comparison",
            "title": "Reference Profile"
          }
        },
        "title": "PrecisionSummary",
        "type": "object"
      },
      "PredictiveConfig": {
        "description": "Unified configuration for all predictive methods.\n\nSpecifies which method to use, reference frames, time window, filtering,\nand orb settings. Works across transits, returns, progressions, etc.",
        "example": {
          "coordinate_system": "geocentric",
          "event_filters": {
            "include_objects": "planets_and_angles",
            "only_applying": false,
            "strength_filter": "moderate"
          },
          "house_system": "placidus",
          "method": "transits",
          "time_window": {
            "end": "2025-12-31T23:59:59Z",
            "mode": "utc",
            "start": "2025-01-01T00:00:00Z"
          },
          "zodiac_type": "tropical"
        },
        "properties": {
          "ascendant_on_left": {
            "default": true,
            "description": "When true (default), the Ascendant is placed at the 9 o'clock (West/left) position � matching the convention used by Astro.com, Solar Fire, and all major astrology software. Set to false to use the ecliptic-fixed (Aries-pinned) orientation instead.",
            "nullable": true,
            "title": "Ascendant on Left",
            "type": "boolean"
          },
          "coordinate_system": {
            "allOf": [
              {
                "$ref": "#/components/schemas/CoordinateSystemEnum"
              }
            ],
            "default": "geocentric",
            "description": "Coordinate system (geocentric, heliocentric, etc.)"
          },
          "event_filters": {
            "allOf": [
              {
                "$ref": "#/components/schemas/PredictiveEventFilter"
              }
            ],
            "description": "Filter by bodies, aspects, strength"
          },
          "house_system": {
            "allOf": [
              {
                "$ref": "#/components/schemas/HouseSystemEnum"
              }
            ],
            "default": "P",
            "description": "House system for all methods"
          },
          "location": {
            "anyOf": [
              {
                "type": "object"
              }
            ],
            "description": "Location override for returns/profections (lat/lon)",
            "title": "Location"
          },
          "method": {
            "allOf": [
              {
                "$ref": "#/components/schemas/PredictiveMethodEnum"
              }
            ],
            "description": "Which predictive method to calculate"
          },
          "orbs_profile": {
            "$ref": "#/components/schemas/AspectConfig",
            "description": "Orb/aspect config (reuses PRP-ASTRO-02 AspectConfig)"
          },
          "time_window": {
            "allOf": [
              {
                "$ref": "#/components/schemas/TimeWindow"
              }
            ],
            "description": "Time range for search (UTC or age-based)"
          },
          "zodiac_type": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ZodiacTypeEnum"
              }
            ],
            "default": "tropical",
            "description": "Zodiac reference"
          }
        },
        "required": [
          "method",
          "time_window"
        ],
        "title": "PredictiveConfig",
        "type": "object"
      },
      "PredictiveEvent": {
        "description": "Single predictive event (transit, return, progression, etc.).\n\nDescribes one moment when a body forms an aspect with another body,\nincluding timing, nature of the aspect, and orbital metrics.",
        "example": {
          "applying": true,
          "aspect": "conjunction",
          "metadata": {
            "days_to_exact": 0.5,
            "source_longitude": 84.2,
            "speed_degrees_per_day": 1,
            "target_longitude": 84
          },
          "method": "transits",
          "orb": 0.5,
          "source": "Sun",
          "strength": 0.95,
          "target": "Natal Mars",
          "timestamp": "2025-06-15T12:30:00Z"
        },
        "properties": {
          "applying": {
            "description": "True if orb decreasing (aspect tightening), False if separating",
            "title": "Applying",
            "type": "boolean"
          },
          "aspect": {
            "description": "Aspect type (e.g., 'conjunction', 'square', 'opposition')",
            "title": "Aspect",
            "type": "string"
          },
          "metadata": {
            "description": "Extra data (source/target long, speed, etc.)",
            "title": "Metadata",
            "type": "object"
          },
          "method": {
            "allOf": [
              {
                "$ref": "#/components/schemas/PredictiveMethodEnum"
              }
            ],
            "description": "Which method this event came from"
          },
          "orb": {
            "description": "Orb in degrees",
            "maximum": 180,
            "minimum": 0,
            "title": "Orb",
            "type": "number"
          },
          "source": {
            "description": "Moving body name (e.g., 'Sun', 'Progressed Sun')",
            "title": "Source",
            "type": "string"
          },
          "strength": {
            "description": "Strength/importance on 0-1 scale",
            "maximum": 1,
            "minimum": 0,
            "title": "Strength",
            "type": "number"
          },
          "target": {
            "description": "Stationary body name (e.g., 'Natal Mars')",
            "title": "Target",
            "type": "string"
          },
          "timestamp": {
            "description": "Moment of aspect (UTC)",
            "format": "date-time",
            "title": "Timestamp",
            "type": "string"
          }
        },
        "required": [
          "timestamp",
          "method",
          "source",
          "target",
          "aspect",
          "orb",
          "applying",
          "strength"
        ],
        "title": "PredictiveEvent",
        "type": "object"
      },
      "PredictiveEventFilter": {
        "description": "Narrows predictive results to specific bodies, aspects, and strength levels.\n\nDifferent from AspectConfig (which defines which aspects exist);\nthis filter defines which results to include after calculation.",
        "example": {
          "exclude_aspects": [
            "semi_square"
          ],
          "include_objects": "planets_and_angles",
          "min_orb_degrees": 0,
          "only_applying": false,
          "strength_filter": "moderate"
        },
        "properties": {
          "exclude_aspects": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              }
            ],
            "description": "E.g., ['semi_square', 'sesquiquadrate']",
            "title": "Exclude Aspects"
          },
          "exclude_bodies": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              }
            ],
            "description": "E.g., ['Chiron', 'Lilith']",
            "title": "Exclude Bodies"
          },
          "include_objects": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ObjectScopeEnum"
              }
            ],
            "default": "planets_and_angles"
          },
          "min_orb_degrees": {
            "default": 0,
            "description": "Exclude events with orb \u003e this",
            "maximum": 180,
            "minimum": 0,
            "title": "Min Orb Degrees",
            "type": "number"
          },
          "only_applying": {
            "default": false,
            "description": "True = return only orb-decreasing (applying) aspects",
            "title": "Only Applying",
            "type": "boolean"
          },
          "strength_filter": {
            "$ref": "#/components/schemas/AspectStrengthFilterEnum"
          }
        },
        "title": "PredictiveEventFilter",
        "type": "object"
      },
      "PredictiveEventsResponse": {
        "description": "Unified response for all predictive queries.",
        "example": {
          "events": [
            {
              "applying": true,
              "aspect": "conjunction",
              "metadata": {},
              "method": "transits",
              "orb": 0.5,
              "source": "Sun",
              "strength": 0.95,
              "target": "Natal Mars",
              "timestamp": "2025-06-15T12:30:00Z"
            }
          ],
          "metadata": {
            "calculation_type": "predictive",
            "input_validation_ms": 5.1,
            "process_time_ms": 45.2
          },
          "pagination": {
            "has_next": false,
            "limit": 500,
            "total_count": 1
          },
          "summary_stats": {
            "methods_included": [
              "transits"
            ],
            "strongest_event_strength": 0.95,
            "time_range_days": 365,
            "total_events": 1
          }
        },
        "properties": {
          "events": {
            "description": "Array of predictive events",
            "items": {
              "$ref": "#/components/schemas/PredictiveEvent"
            },
            "title": "Events",
            "type": "array"
          },
          "metadata": {
            "$ref": "#/components/schemas/CalculationMetadata",
            "description": "Processing metrics and version info"
          },
          "pagination": {
            "$ref": "#/components/schemas/PaginationMetadata",
            "description": "Pagination info if result set \u003e limit"
          },
          "summary_stats": {
            "description": "Aggregated counts: total_events, methods_included, strongest_event_strength, etc.",
            "title": "Summary Stats",
            "type": "object"
          }
        },
        "required": [
          "events"
        ],
        "title": "PredictiveEventsResponse",
        "type": "object"
      },
      "PredictiveMetadata": {
        "additionalProperties": true,
        "description": "Metadata for predictive calculation responses.",
        "properties": {
          "accuracy_statement": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Accuracy information",
            "title": "Accuracy Statement"
          },
          "cache_status": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Cache hit/miss status",
            "title": "Cache Status"
          },
          "calculation_metadata": {
            "$ref": "#/components/schemas/CalculationMetadata",
            "description": "Full calculation metadata describing ephemeris provenance, timing, and configuration"
          },
          "calculation_type": {
            "description": "Type of calculation performed",
            "title": "Calculation Type",
            "type": "string"
          },
          "nasa_validated": {
            "default": true,
            "description": "NASA validation status",
            "title": "Nasa Validated",
            "type": "boolean"
          },
          "performance_note": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Performance information",
            "title": "Performance Note"
          },
          "processing_time_ms": {
            "description": "Processing time in milliseconds",
            "title": "Processing Time Ms",
            "type": "number"
          },
          "search_range_years": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "description": "Years searched",
            "title": "Search Range Years"
          }
        },
        "required": [
          "calculation_type",
          "processing_time_ms"
        ],
        "title": "PredictiveMetadata",
        "type": "object"
      },
      "PredictiveMethodEnum": {
        "description": "Supported predictive astrology methods.\n\n- transits: Current/future planets aspecting natal positions\n- returns_solar: Annual solar return chart calculation\n- returns_lunar: Monthly lunar return chart calculation\n- secondary_progressions: 1 day = 1 year of life; progressed chart evaluation (includes Solar Arc and Tertiary)\n- solar_arc_directions: Arc derived from solar motion, applied to natal points\n- profections_annual: Sign-based annual profections (experimental)",
        "enum": [
          "transits",
          "returns_solar",
          "returns_lunar",
          "secondary_progressions",
          "solar_arc_directions",
          "profections_annual"
        ],
        "title": "PredictiveMethodEnum",
        "type": "string"
      },
      "PrenatalLunationRequest": {
        "properties": {
          "birth_datetime": {
            "type": "string"
          },
          "format": {
            "description": "Response format: json | llm.",
            "enum": [
              "json",
              "llm"
            ],
            "type": "string"
          },
          "house_system": {
            "type": "string"
          },
          "latitude": {
            "format": "float",
            "type": "number"
          },
          "longitude": {
            "format": "float",
            "type": "number"
          },
          "prenatal_type": {
            "enum": [
              "auto",
              "new_moon",
              "full_moon"
            ],
            "type": "string"
          }
        },
        "required": [
          "birth_datetime",
          "latitude",
          "longitude"
        ],
        "type": "object"
      },
      "PrenatalLunationResponse": {
        "properties": {
          "calculation_metadata": {
            "type": "object"
          },
          "natal_chart": {
            "$ref": "#/components/schemas/NatalChartEnhancedResponse"
          },
          "prenatal_full_moon": {
            "properties": {
              "datetime_iso": {
                "type": "string"
              },
              "days_before_birth": {
                "format": "float",
                "type": "number"
              },
              "julian_day": {
                "format": "float",
                "type": "number"
              }
            },
            "type": "object"
          },
          "prenatal_new_moon": {
            "properties": {
              "datetime_iso": {
                "type": "string"
              },
              "days_before_birth": {
                "format": "float",
                "type": "number"
              },
              "julian_day": {
                "format": "float",
                "type": "number"
              }
            },
            "type": "object"
          },
          "selected_lunation": {
            "properties": {
              "datetime_iso": {
                "type": "string"
              },
              "days_before_birth": {
                "format": "float",
                "type": "number"
              },
              "julian_day": {
                "format": "float",
                "type": "number"
              },
              "type": {
                "$ref": "#/components/schemas/SelectedLunationType"
              }
            },
            "type": "object"
          },
          "success": {
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "PrimaryDirectionEvent": {
        "properties": {
          "age_naibod": {
            "format": "float",
            "type": "number"
          },
          "age_ptolemy": {
            "format": "float",
            "type": "number"
          },
          "arc": {
            "format": "float",
            "type": "number"
          },
          "aspect_deg": {
            "format": "float",
            "type": "number"
          },
          "aspect_name": {
            "type": "string"
          },
          "is_converse": {
            "type": "boolean"
          },
          "method": {
            "type": "string"
          },
          "promittor_id": {
            "type": "integer"
          },
          "promittor_name": {
            "type": "string"
          },
          "significator_id": {
            "type": "integer"
          },
          "significator_name": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "PrimaryDirectionPlanet": {
        "properties": {
          "declination": {
            "format": "float",
            "type": "number"
          },
          "dsa": {
            "format": "float",
            "type": "number"
          },
          "id": {
            "type": "integer"
          },
          "is_above_horizon": {
            "type": "boolean"
          },
          "latitude": {
            "format": "float",
            "type": "number"
          },
          "longitude": {
            "format": "float",
            "type": "number"
          },
          "name": {
            "type": "string"
          },
          "nsa": {
            "format": "float",
            "type": "number"
          },
          "oa": {
            "format": "float",
            "type": "number"
          },
          "ra": {
            "format": "float",
            "type": "number"
          }
        },
        "type": "object"
      },
      "PrimaryDirectionsRequest": {
        "properties": {
          "format": {
            "description": "Response format: json | llm.",
            "enum": [
              "json",
              "llm"
            ],
            "type": "string"
          },
          "include_aspects": {
            "items": {
              "format": "float",
              "type": "number"
            },
            "type": "array"
          },
          "include_converse": {
            "type": "boolean"
          },
          "max_age_years": {
            "format": "float",
            "type": "number"
          },
          "subject": {
            "$ref": "#/components/schemas/SubjectRequest"
          }
        },
        "required": [
          "subject"
        ],
        "type": "object"
      },
      "PrimaryDirectionsResponse": {
        "properties": {
          "calculation_metadata": {
            "additionalProperties": true,
            "description": "Optional calculation provenance metadata (timing, engine flags, ayanamsa, etc.). Free-form; present when the handler attaches it.",
            "type": "object"
          },
          "directions": {
            "items": {
              "$ref": "#/components/schemas/PrimaryDirectionEvent"
            },
            "type": "array"
          },
          "geo_lat": {
            "format": "float",
            "type": "number"
          },
          "obliquity": {
            "format": "float",
            "type": "number"
          },
          "planets": {
            "items": {
              "$ref": "#/components/schemas/PrimaryDirectionPlanet"
            },
            "type": "array"
          }
        },
        "type": "object"
      },
      "ProfectionsRequest": {
        "description": "Input for annual profections calculation. Requires the natal ascendant sign (0 = Aries … 11 = Pisces) and the birth datetime to derive the native's age at the target date.",
        "properties": {
          "ascendant_sign": {
            "description": "Natal ascendant sign index (0 = Aries, 1 = Taurus, … 11 = Pisces). Determines the 1st-house starting sign for the profection wheel.",
            "maximum": 11,
            "minimum": 0,
            "title": "Ascendant Sign",
            "type": "integer"
          },
          "birth_datetime": {
            "description": "Natal birth datetime in ISO 8601 UTC format.",
            "format": "date-time",
            "title": "Birth Datetime",
            "type": "string"
          },
          "house_system": {
            "description": "Optional.",
            "type": "string"
          },
          "latitude": {
            "description": "Optional. If provided, calculates natal chart to determine ascendant/sect/lots.",
            "maximum": 90,
            "minimum": -90,
            "type": "number"
          },
          "longitude": {
            "description": "Optional.",
            "maximum": 180,
            "minimum": -180,
            "type": "number"
          },
          "target_datetime": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              }
            ],
            "description": "Date to evaluate the profection for. Defaults to the current date if omitted.",
            "title": "Target Datetime"
          },
          "years_backward": {
            "anyOf": [
              {
                "maximum": 120,
                "minimum": 0,
                "type": "integer"
              }
            ],
            "default": 5,
            "description": "Number of past profection years to include in the timeline. Default: 5.",
            "title": "Years Backward"
          },
          "years_forward": {
            "anyOf": [
              {
                "maximum": 120,
                "minimum": 0,
                "type": "integer"
              }
            ],
            "default": 10,
            "description": "Number of future profection years to include in the timeline. Default: 10.",
            "title": "Years Forward"
          }
        },
        "required": [
          "birth_datetime",
          "ascendant_sign"
        ],
        "title": "ProfectionsRequest",
        "type": "object"
      },
      "ProfectionsResponse": {
        "description": "Annual profections result — current active profection and the full timeline.",
        "properties": {
          "ascendant_sign_name": {
            "description": "Natal Ascendant sign name for reference.",
            "type": "string"
          },
          "birth_datetime": {
            "description": "Birth datetime used for the calculation.",
            "type": "string"
          },
          "current_year": {
            "description": "The active profection for the target date.",
            "properties": {
              "age": {
                "description": "Age of the native at the target date (birthday-based).",
                "type": "integer"
              },
              "birthday_next_year": {
                "description": "Estimated birthday datetime when the next profection begins.",
                "format": "date-time",
                "nullable": true,
                "type": "string"
              },
              "birthday_this_year": {
                "description": "Estimated birthday datetime for this profection year.",
                "format": "date-time",
                "nullable": true,
                "type": "string"
              },
              "element": {
                "description": "Element of the profected sign (Fire, Earth, Air, Water).",
                "type": "string"
              },
              "house_activated": {
                "description": "Whole-sign house number activated (1–12).",
                "type": "integer"
              },
              "is_angular": {
                "description": "Whether this is an angular-house year (1st, 4th, 7th, 10th). Angular years are traditionally the most significant.",
                "type": "boolean"
              },
              "modality": {
                "description": "Modality of the profected sign (Cardinal, Fixed, Mutable).",
                "type": "string"
              },
              "profected_sign": {
                "description": "Sign index of the profected Ascendant (0–11).",
                "type": "integer"
              },
              "profected_sign_name": {
                "description": "Name of the profected sign (e.g., \"Sagittarius\").",
                "type": "string"
              },
              "time_lord": {
                "description": "Modern planet name ruling the profected sign.",
                "type": "string"
              },
              "time_lord_traditional_name": {
                "description": "Traditional Hellenistic name for the time lord planet.",
                "type": "string"
              },
              "year_of_life": {
                "description": "Year of life (age + 1, e.g., 1st year of life = age 0).",
                "type": "integer"
              }
            },
            "required": [
              "age",
              "year_of_life",
              "profected_sign",
              "profected_sign_name",
              "house_activated",
              "time_lord",
              "time_lord_traditional_name",
              "element",
              "modality",
              "is_angular"
            ],
            "title": "Current Year",
            "type": "object"
          },
          "output_mode": {
            "description": "Output projection mode (json | llm).",
            "nullable": true,
            "type": "string"
          },
          "success": {
            "description": "Whether the calculation succeeded.",
            "title": "Success",
            "type": "boolean"
          },
          "timeline": {
            "description": "Profection entries for surrounding years (past and future).",
            "items": {
              "properties": {
                "age": {
                  "type": "integer"
                },
                "element": {
                  "type": "string"
                },
                "house_activated": {
                  "type": "integer"
                },
                "is_angular": {
                  "type": "boolean"
                },
                "is_current": {
                  "description": "True for the active profection year.",
                  "type": "boolean"
                },
                "modality": {
                  "type": "string"
                },
                "profected_sign": {
                  "type": "integer"
                },
                "profected_sign_name": {
                  "type": "string"
                },
                "time_lord": {
                  "type": "string"
                },
                "time_lord_traditional_name": {
                  "type": "string"
                },
                "year_of_life": {
                  "type": "integer"
                }
              },
              "type": "object"
            },
            "title": "Timeline",
            "type": "array"
          }
        },
        "required": [
          "success",
          "current_year",
          "timeline"
        ],
        "title": "ProfectionsResponse",
        "type": "object"
      },
      "ProgressedCalculationOptions": {
        "additionalProperties": false,
        "description": "Options controlling progression method and Naibod ratio.",
        "example": {
          "day_year_ratio": 1,
          "method": "secondary"
        },
        "properties": {
          "day_year_ratio": {
            "default": 1,
            "description": "Number of ephemeris days applied per tropical year elapsed (Naibod factor). Only used for secondary progressions. Default 1.0 is mean Naibod rate.",
            "maximum": 5,
            "minimum": 0.1,
            "title": "Day Year Ratio",
            "type": "number"
          },
          "method": {
            "default": "secondary",
            "description": "Progression method: secondary (1 day = 1 year with Naibod ratio), solar_arc (Sun's actual arc applied to all positions), tertiary (1 day = 1 sidereal lunar month)",
            "enum": [
              "secondary",
              "solar_arc",
              "tertiary"
            ],
            "title": "Method",
            "type": "string"
          }
        },
        "title": "ProgressedCalculationOptions",
        "type": "object"
      },
      "ProgressedChartData": {
        "additionalProperties": false,
        "description": "Progressed chart payload returned to clients.",
        "properties": {
          "angles": {
            "allOf": [
              {
                "$ref": "#/components/schemas/AnglesResponse"
              }
            ],
            "description": "Progressed chart angles"
          },
          "aspects": {
            "description": "Progressed aspects (empty when aspects are disabled)",
            "items": {
              "$ref": "#/components/schemas/EnhancedAspectResponse"
            },
            "title": "Aspects",
            "type": "array"
          },
          "declination_aspects": {
            "anyOf": [
              {
                "items": {
                  "$ref": "#/components/schemas/DeclinationAspect"
                },
                "type": "array"
              }
            ],
            "description": "Progressed declination aspects when requested",
            "title": "Declination Aspects"
          },
          "houses": {
            "allOf": [
              {
                "$ref": "#/components/schemas/HousesResponse"
              }
            ],
            "description": "Progressed house cusps and system information"
          },
          "natal_subject": {
            "allOf": [
              {
                "$ref": "#/components/schemas/SubjectResponse"
              }
            ],
            "description": "Normalized natal subject data used as the baseline"
          },
          "planets": {
            "additionalProperties": {
              "$ref": "#/components/schemas/PlanetResponse"
            },
            "description": "Progressed planetary positions keyed by body name",
            "title": "Planets",
            "type": "object"
          },
          "progressed_subject": {
            "allOf": [
              {
                "$ref": "#/components/schemas/SubjectResponse"
              }
            ],
            "description": "Subject data adjusted to the progressed datetime"
          }
        },
        "required": [
          "natal_subject",
          "progressed_subject",
          "planets",
          "houses",
          "angles"
        ],
        "title": "ProgressedChartData",
        "type": "object"
      },
      "ProgressedChartMetadata": {
        "additionalProperties": false,
        "description": "Metadata describing a progressed chart calculation.",
        "properties": {
          "cache_hit": {
            "anyOf": [
              {
                "type": "boolean"
              }
            ],
            "description": "Indicates whether the response originated from cache",
            "title": "Cache Hit"
          },
          "calculation_metadata": {
            "$ref": "#/components/schemas/CalculationMetadata",
            "description": "Low-level calculation metadata (precision, flags, etc.)"
          },
          "coordinate_mode": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Coordinate mode echoed from globals (e.g., zodiacal or in_mundo)",
            "title": "Coordinate Mode"
          },
          "day_year_ratio": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "description": "Naibod ratio applied (only for secondary progressions)",
            "title": "Day Year Ratio"
          },
          "globals_fingerprint": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Fingerprint of global ephemeris settings contributing to cache keys",
            "title": "Globals Fingerprint"
          },
          "method": {
            "default": "secondary",
            "description": "Progression method used: secondary (Naibod), solar_arc, or tertiary",
            "enum": [
              "secondary",
              "solar_arc",
              "tertiary"
            ],
            "title": "Method",
            "type": "string"
          },
          "progressed_datetime": {
            "description": "Ephemeris datetime used after applying the Naibod rate",
            "format": "date-time",
            "title": "Progressed Datetime",
            "type": "string"
          },
          "target_datetime": {
            "description": "Requested calendar datetime for the progression",
            "format": "date-time",
            "title": "Target Datetime",
            "type": "string"
          }
        },
        "required": [
          "target_datetime",
          "progressed_datetime"
        ],
        "title": "ProgressedChartMetadata",
        "type": "object"
      },
      "ProgressedChartRequest": {
        "additionalProperties": false,
        "description": "Progressed chart request built from a natal subject and target datetime.",
        "example": {
          "configuration": {
            "house_system": "P",
            "object_set": "asteroids_major",
            "zodiac_type": "tropical"
          },
          "options": {
            "include_aspects": true,
            "include_declination_aspects": true
          },
          "progression_options": {
            "day_year_ratio": 1,
            "method": "secondary"
          },
          "subject": {
            "birth_datetime": {
              "iso": "1990-01-01T12:00:00Z"
            },
            "birth_location": {
              "latitude": {
                "decimal": 34.0522
              },
              "longitude": {
                "decimal": -118.2437
              },
              "timezone": {
                "iana_name": "America/Los_Angeles"
              }
            },
            "name": "Secondary Progression Example"
          },
          "target_datetime": {
            "iso": "2025-11-06T00:00:00Z"
          }
        },
        "properties": {
          "configuration": {
            "$ref": "#/components/schemas/ChartConfiguration",
            "description": "Optional overrides for zodiac, houses, and additional bodies"
          },
          "enhanced_options": {
            "$ref": "#/components/schemas/EnhancedCalculationOptions",
            "description": "Optional enhanced calculation flags to apply when generating the natal-style chart snapshot used for preset=simple or format=llm (mirrors /ephemeris/natal-chart enhanced_options)."
          },
          "options": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ResponseOptions"
              }
            ],
            "description": "Response shaping options (aspects enabled by default)"
          },
          "progression_options": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ProgressedCalculationOptions"
              }
            ],
            "description": "Progression-specific tuning options"
          },
          "subject": {
            "allOf": [
              {
                "$ref": "#/components/schemas/SubjectRequest"
              }
            ],
            "description": "Subject information used as the natal reference"
          },
          "target_datetime": {
            "allOf": [
              {
                "$ref": "#/components/schemas/DateTimeInput"
              }
            ],
            "description": "Calendar date to progress the natal chart to"
          }
        },
        "required": [
          "subject",
          "target_datetime"
        ],
        "title": "ProgressedChartRequest",
        "type": "object"
      },
      "ProgressedChartResponse": {
        "additionalProperties": false,
        "description": "Standard API envelope for progressed chart results.",
        "properties": {
          "data": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ProgressedChartData"
              }
            ],
            "description": "Progressed chart payload"
          },
          "metadata": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ProgressedChartMetadata"
              }
            ],
            "description": "Metadata describing the progression context"
          },
          "output_mode": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Output projection mode (full | simple | llm)",
            "title": "Output Mode"
          },
          "schema_version": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Schema version for the selected output mode (e.g., full_v1, simple_v1, llm)",
            "title": "Schema Version"
          },
          "success": {
            "default": true,
            "description": "Indicates progression succeeded",
            "title": "Success",
            "type": "boolean"
          }
        },
        "required": [
          "data",
          "metadata"
        ],
        "title": "ProgressedChartResponse",
        "type": "object"
      },
      "RecentRequestItem": {
        "properties": {
          "endpoint": {
            "description": "Templated endpoint path.",
            "title": "Endpoint",
            "type": "string"
          },
          "latency_ms": {
            "description": "Request latency in milliseconds.",
            "title": "Latency Ms",
            "type": "number"
          },
          "method": {
            "description": "HTTP method.",
            "title": "Method",
            "type": "string"
          },
          "request_body_excerpt": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Redacted request body excerpt.",
            "title": "Request Body Excerpt"
          },
          "request_id": {
            "description": "Request identifier (matches API responses).",
            "title": "Request Id",
            "type": "string"
          },
          "response_body_excerpt": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Redacted response body excerpt.",
            "title": "Response Body Excerpt"
          },
          "status": {
            "description": "HTTP status code.",
            "title": "Status",
            "type": "integer"
          },
          "timestamp": {
            "description": "Request timestamp (UTC).",
            "format": "date-time",
            "title": "Timestamp",
            "type": "string"
          },
          "trace_id": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Optional trace identifier.",
            "title": "Trace Id"
          },
          "units_charged": {
            "description": "Usage units charged for the request.",
            "title": "Units Charged",
            "type": "integer"
          }
        },
        "required": [
          "timestamp",
          "method",
          "endpoint",
          "status",
          "latency_ms",
          "units_charged",
          "request_id"
        ],
        "title": "RecentRequestItem",
        "type": "object"
      },
      "RecentRequestsResponse": {
        "properties": {
          "requests": {
            "items": {
              "$ref": "#/components/schemas/RecentRequestItem"
            },
            "title": "Requests",
            "type": "array"
          }
        },
        "title": "RecentRequestsResponse",
        "type": "object"
      },
      "RelationalParansRequest": {
        "properties": {
          "subject1": {
            "$ref": "#/components/schemas/SubjectRequest"
          },
          "subject2": {
            "$ref": "#/components/schemas/SubjectRequest"
          }
        },
        "required": [
          "subject1",
          "subject2"
        ],
        "type": "object"
      },
      "RelocationAngle": {
        "additionalProperties": false,
        "description": "Position of a relocated chart angle.",
        "example": {
          "longitude": 123.456789,
          "sign": "Leo",
          "sign_longitude": 3.456789,
          "sign_symbol": "Leo"
        },
        "properties": {
          "longitude": {
            "description": "Longitude of the angle in degrees",
            "exclusiveMaximum": true,
            "maximum": 360,
            "minimum": 0,
            "title": "Longitude",
            "type": "number"
          },
          "sign": {
            "description": "Zodiac sign occupied by the angle",
            "title": "Sign",
            "type": "string"
          },
          "sign_longitude": {
            "description": "Degrees within the occupied sign",
            "exclusiveMaximum": true,
            "maximum": 30,
            "minimum": 0,
            "title": "Sign Longitude",
            "type": "number"
          },
          "sign_symbol": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Unicode symbol for the occupied zodiac sign",
            "title": "Sign Symbol"
          }
        },
        "required": [
          "longitude",
          "sign",
          "sign_longitude"
        ],
        "title": "RelocationAngle",
        "type": "object"
      },
      "RelocationAngles": {
        "additionalProperties": false,
        "description": "Relocated chart angles.",
        "properties": {
          "asc": {
            "allOf": [
              {
                "$ref": "#/components/schemas/RelocationAngle"
              }
            ],
            "description": "Ascendant details"
          },
          "dsc": {
            "allOf": [
              {
                "$ref": "#/components/schemas/RelocationAngle"
              }
            ],
            "description": "Descendant details"
          },
          "ic": {
            "allOf": [
              {
                "$ref": "#/components/schemas/RelocationAngle"
              }
            ],
            "description": "Imum Coeli details"
          },
          "mc": {
            "allOf": [
              {
                "$ref": "#/components/schemas/RelocationAngle"
              }
            ],
            "description": "Midheaven details"
          }
        },
        "required": [
          "asc",
          "mc",
          "dsc",
          "ic"
        ],
        "title": "RelocationAngles",
        "type": "object"
      },
      "RelocationHouse": {
        "additionalProperties": false,
        "description": "Information about a relocated house cusp.",
        "properties": {
          "index": {
            "description": "House index (1-12)",
            "maximum": 12,
            "minimum": 1,
            "title": "Index",
            "type": "integer"
          },
          "longitude": {
            "description": "Longitude of the house cusp",
            "exclusiveMaximum": true,
            "maximum": 360,
            "minimum": 0,
            "title": "Longitude",
            "type": "number"
          },
          "sign": {
            "description": "Zodiac sign on the cusp",
            "title": "Sign",
            "type": "string"
          },
          "sign_longitude": {
            "description": "Degrees within the cusp sign",
            "exclusiveMaximum": true,
            "maximum": 30,
            "minimum": 0,
            "title": "Sign Longitude",
            "type": "number"
          },
          "sign_symbol": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Unicode symbol for the sign",
            "title": "Sign Symbol"
          },
          "size": {
            "description": "House size in degrees",
            "exclusiveMinimum": true,
            "maximum": 360,
            "minimum": 0,
            "title": "Size",
            "type": "number"
          }
        },
        "required": [
          "index",
          "longitude",
          "sign",
          "sign_longitude",
          "size"
        ],
        "title": "RelocationHouse",
        "type": "object"
      },
      "RelocationInput": {
        "description": "Location override for composite charts.",
        "example": {
          "latitude": {
            "decimal": 40.7128
          },
          "longitude": {
            "decimal": -74.006
          }
        },
        "properties": {
          "latitude": {
            "$ref": "#/components/schemas/CoordinateInput"
          },
          "longitude": {
            "$ref": "#/components/schemas/CoordinateInput"
          }
        },
        "required": [
          "latitude",
          "longitude"
        ],
        "title": "RelocationInput",
        "type": "object"
      },
      "RelocationMetadata": {
        "additionalProperties": true,
        "description": "Metadata describing the relocation calculation.",
        "properties": {
          "calculation_source": {
            "default": "SuperNOVAS / Calceph",
            "description": "Computation backend identifier",
            "title": "Calculation Source",
            "type": "string"
          },
          "fallback_used": {
            "default": false,
            "description": "True if a fallback house system was required for stability",
            "title": "Fallback Used",
            "type": "boolean"
          },
          "house_system": {
            "description": "House system code actually used",
            "maxLength": 2,
            "minLength": 1,
            "title": "House System",
            "type": "string"
          },
          "julian_day": {
            "anyOf": [
              {
                "format": "double",
                "type": "number"
              }
            ],
            "description": "Julian Day representing the calculation instant",
            "title": "Julian Day"
          },
          "natal_house_system": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "House system used in the natal reference chart",
            "title": "Natal House System"
          },
          "observer_location": {
            "allOf": [
              {
                "$ref": "#/components/schemas/RelocationObserverLocation"
              }
            ],
            "description": "Observer coordinates used for relocation"
          },
          "reference_frame": {
            "default": "geocentric_ecliptic_J2000",
            "description": "Reference frame for planetary positions",
            "title": "Reference Frame",
            "type": "string"
          },
          "requested_house_system": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "House system code requested by the client",
            "title": "Requested House System"
          },
          "time_system": {
            "default": "UTC",
            "description": "Time standard applied to the calculation",
            "title": "Time System",
            "type": "string"
          },
          "topocentric_flag": {
            "default": false,
            "description": "Indicates whether topocentric positions were used",
            "title": "Topocentric Flag",
            "type": "boolean"
          }
        },
        "required": [
          "observer_location",
          "house_system"
        ],
        "title": "RelocationMetadata",
        "type": "object"
      },
      "RelocationObserverLocation": {
        "additionalProperties": false,
        "description": "Observer location metadata for the relocated chart.",
        "properties": {
          "elevation": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "description": "Elevation in meters above sea level",
            "title": "Elevation"
          },
          "latitude": {
            "description": "Observer latitude",
            "maximum": 90,
            "minimum": -90,
            "title": "Latitude",
            "type": "number"
          },
          "longitude": {
            "description": "Observer longitude",
            "maximum": 180,
            "minimum": -180,
            "title": "Longitude",
            "type": "number"
          }
        },
        "required": [
          "latitude",
          "longitude"
        ],
        "title": "RelocationObserverLocation",
        "type": "object"
      },
      "RelocationRequest": {
        "additionalProperties": false,
        "description": "Request payload for generating a relocation chart.",
        "example": {
          "house_system": "P",
          "natal": {
            "subject": {
              "birth_datetime": {
                "iso": "1990-01-01T12:00:00Z"
              },
              "birth_location": {
                "latitude": {
                  "decimal": 34.0522
                },
                "longitude": {
                  "decimal": -118.2437
                },
                "timezone": {
                  "iana_name": "America/Los_Angeles"
                }
              },
              "name": "Relocation Client"
            }
          },
          "relocation_lat": 40.7128,
          "relocation_lon": -74.006
        },
        "properties": {
          "house_system": {
            "$ref": "#/components/schemas/HouseSystemEnum",
            "description": "Override house system code to use for relocation (default matches natal)"
          },
          "natal": {
            "$ref": "#/components/schemas/NatalChartRequest",
            "description": "Full natal chart request payload when no natal_id is supplied"
          },
          "natal_id": {
            "anyOf": [
              {
                "maxLength": 64,
                "minLength": 1,
                "type": "string"
              }
            ],
            "description": "Reserved identifier for previously computed natal context (lookup support depends on deployment configuration)",
            "title": "Natal Id"
          },
          "relocation_elevation": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "description": "Optional elevation in meters for the relocation site",
            "title": "Relocation Elevation"
          },
          "relocation_lat": {
            "description": "Relocation latitude in decimal degrees",
            "maximum": 90,
            "minimum": -90,
            "title": "Relocation Lat",
            "type": "number"
          },
          "relocation_lon": {
            "description": "Relocation longitude in decimal degrees",
            "maximum": 180,
            "minimum": -180,
            "title": "Relocation Lon",
            "type": "number"
          }
        },
        "required": [
          "natal",
          "relocation_lat",
          "relocation_lon"
        ],
        "title": "RelocationRequest",
        "type": "object"
      },
      "RelocationResponse": {
        "additionalProperties": true,
        "description": "Lean response describing the relocated chart.",
        "example": {
          "angles": {
            "asc": {
              "longitude": 123.45,
              "sign": "Leo",
              "sign_longitude": 3.45,
              "sign_symbol": "Leo"
            },
            "dsc": {
              "longitude": 303.45,
              "sign": "Aquarius",
              "sign_longitude": 3.45,
              "sign_symbol": "Aquarius"
            },
            "ic": {
              "longitude": 30.1,
              "sign": "Taurus",
              "sign_longitude": 0.1,
              "sign_symbol": "Taurus"
            },
            "mc": {
              "longitude": 210.1,
              "sign": "Scorpio",
              "sign_longitude": 0.1,
              "sign_symbol": "Scorpio"
            }
          },
          "calculation_metadata": {
            "coordinate_system": "geocentric",
            "ephemeris_source": "SuperNOVAS / Calceph",
            "zodiac_type": "tropical"
          },
          "houses": [
            {
              "index": 1,
              "longitude": 123.45,
              "sign": "Leo",
              "sign_longitude": 3.45,
              "size": 30
            },
            {
              "index": 2,
              "longitude": 153.45,
              "sign": "Virgo",
              "sign_longitude": 3.45,
              "size": 28.7
            }
          ],
          "metadata": {
            "calculation_source": "SuperNOVAS / Calceph",
            "house_system": "P",
            "natal_house_system": "P",
            "observer_location": {
              "latitude": 40.7128,
              "longitude": -74.006
            },
            "reference_frame": "geocentric_ecliptic_J2000",
            "requested_house_system": "P",
            "time_system": "UTC",
            "topocentric_flag": false
          },
          "planet_house_changes": [
            {
              "body": "Sun",
              "from_house": 10,
              "to_house": 9
            },
            {
              "body": "Venus",
              "from_house": 7,
              "to_house": 8
            }
          ],
          "success": true,
          "summary": {
            "changed_houses": 12,
            "changed_planets": 2,
            "notes": "Relocated using Placidus; planetary longitudes unchanged."
          }
        },
        "properties": {
          "angles": {
            "allOf": [
              {
                "$ref": "#/components/schemas/RelocationAngles"
              }
            ],
            "description": "Relocated angles payload"
          },
          "calculation_metadata": {
            "$ref": "#/components/schemas/CalculationMetadata",
            "description": "Standardized calculation metadata for the relocation computation"
          },
          "houses": {
            "description": "House cusps after relocation",
            "items": {
              "$ref": "#/components/schemas/RelocationHouse"
            },
            "title": "Houses",
            "type": "array"
          },
          "metadata": {
            "allOf": [
              {
                "$ref": "#/components/schemas/RelocationMetadata"
              }
            ],
            "description": "Metadata for the relocation calculation"
          },
          "planet_house_changes": {
            "description": "Planets whose house placement changed",
            "items": {
              "$ref": "#/components/schemas/PlanetHouseChange"
            },
            "title": "Planet House Changes",
            "type": "array"
          },
          "planets": {
            "additionalProperties": {
              "$ref": "#/components/schemas/PlanetResponse"
            },
            "description": "Planetary positions keyed by body name, matching natal chart format",
            "title": "Planets",
            "type": "object"
          },
          "success": {
            "default": true,
            "description": "Indicates relocation succeeded",
            "title": "Success",
            "type": "boolean"
          },
          "summary": {
            "allOf": [
              {
                "$ref": "#/components/schemas/RelocationSummary"
              }
            ],
            "description": "Summary of relocation changes"
          }
        },
        "required": [
          "angles",
          "houses",
          "summary",
          "metadata"
        ],
        "title": "RelocationResponse",
        "type": "object"
      },
      "RelocationSummary": {
        "additionalProperties": false,
        "description": "Summary statistics for a relocation result.",
        "properties": {
          "changed_houses": {
            "description": "Number of houses whose cusps shifted",
            "minimum": 0,
            "title": "Changed Houses",
            "type": "integer"
          },
          "changed_planets": {
            "description": "Number of planets that moved houses",
            "minimum": 0,
            "title": "Changed Planets",
            "type": "integer"
          },
          "notes": {
            "description": "Human-readable summary of key decisions",
            "title": "Notes",
            "type": "string"
          }
        },
        "required": [
          "changed_planets",
          "changed_houses",
          "notes"
        ],
        "title": "RelocationSummary",
        "type": "object"
      },
      "ResponseOptions": {
        "description": "Options for customizing API response content and format.",
        "example": {
          "include_hermetic_lots": true,
          "include_metadata": true,
          "trim_precision": false
        },
        "properties": {
          "angle_format": {
            "default": "decimal",
            "description": "Angle format",
            "pattern": "^(decimal|dms)$",
            "title": "Angle Format",
            "type": "string"
          },
          "decimal_places": {
            "default": 6,
            "description": "Decimal places for coordinates",
            "maximum": 10,
            "minimum": 0,
            "title": "Decimal Places",
            "type": "integer"
          },
          "declination_orb": {
            "default": 1.2,
            "description": "Orb in degrees for declination-based aspects",
            "maximum": 5,
            "minimum": 0.1,
            "title": "Declination Orb",
            "type": "number"
          },
          "echo_top_level": {
            "default": false,
            "description": "Echo legacy top-level fields alongside data envelope",
            "title": "Echo Top Level",
            "type": "boolean"
          },
          "fixed_star_magnitude_limit": {
            "default": 6,
            "deprecated": true,
            "description": "DEPRECATED. Use configuration.fixed_star_options.magnitude_limit for fixed-star computation settings. This field will be removed in a future release.",
            "maximum": 10,
            "minimum": 0,
            "title": "Fixed Star Magnitude Limit",
            "type": "number",
            "x-ui-hidden": true
          },
          "fixed_star_orb": {
            "default": 2,
            "deprecated": true,
            "description": "DEPRECATED. Use configuration.fixed_star_options.orb for fixed-star computation settings. This field will be removed in a future release.",
            "maximum": 5,
            "minimum": 0.1,
            "title": "Fixed Star Orb",
            "type": "number",
            "x-ui-hidden": true
          },
          "include_aspects": {
            "default": true,
            "description": "Include aspect calculations",
            "title": "Include Aspects",
            "type": "boolean"
          },
          "include_declination_aspects": {
            "default": true,
            "description": "Include declination-based aspects",
            "title": "Include Declination Aspects",
            "type": "boolean"
          },
          "include_declination_values": {
            "default": true,
            "description": "Include per-planet declination and right-ascension values (and topocentric variants when applicable). This is a payload shaping control and may be tier-gated.",
            "title": "Include Declination Values",
            "type": "boolean"
          },
          "include_dignities": {
            "default": true,
            "description": "Include dignities (essential + accidental when available)",
            "title": "Include Dignities",
            "type": "boolean"
          },
          "include_fixed_stars": {
            "default": false,
            "deprecated": true,
            "description": "DEPRECATED. Fixed-star computation is configured via configuration.fixed_star_options.include. This field will be removed in a future release.",
            "title": "Include Fixed Stars",
            "type": "boolean",
            "x-ui-hidden": true
          },
          "include_hermetic_lots": {
            "default": true,
            "description": "Include Hermetic lot payload (aliases accepted: include_arabic_parts)",
            "title": "Include Hermetic Lots",
            "type": "boolean"
          },
          "include_houses": {
            "default": true,
            "description": "Include house positions",
            "title": "Include Houses",
            "type": "boolean"
          },
          "include_metadata": {
            "default": true,
            "description": "Include calculation metadata",
            "title": "Include Metadata",
            "type": "boolean"
          },
          "include_minor_aspects": {
            "default": false,
            "description": "Include minor aspects (e.g., quincunx, semisquare, quintile). When False (default), only major aspects are computed.",
            "title": "Include Minor Aspects",
            "type": "boolean"
          },
          "include_out_of_bounds": {
            "default": true,
            "description": "Include out-of-bounds flags for planets",
            "title": "Include Out Of Bounds",
            "type": "boolean"
          },
          "include_true_lilith": {
            "default": false,
            "description": "Include True/oscillating Lilith bodies in output",
            "title": "Include True Lilith",
            "type": "boolean"
          },
          "trim_precision": {
            "default": false,
            "description": "Reduce numerical precision for smaller responses",
            "title": "Trim Precision",
            "type": "boolean"
          }
        },
        "title": "ResponseOptions",
        "type": "object"
      },
      "RetrogradeStatus": {
        "description": "Planetary motion status.",
        "enum": [
          "direct",
          "retrograde",
          "stationary_direct",
          "stationary_retrograde"
        ],
        "title": "RetrogradeStatus",
        "type": "string"
      },
      "RetrogradeStatusRequest": {
        "additionalProperties": false,
        "description": "Request for planet retrograde status check.",
        "example": {
          "date_time": {
            "iso": "2025-12-11T12:00:00Z"
          },
          "planet_id": 2
        },
        "properties": {
          "date_time": {
            "allOf": [
              {
                "$ref": "#/components/schemas/DateTimeInput"
              }
            ],
            "description": "Calculation datetime in ISO, components, or Julian day format",
            "example": {
              "iso": "2000-01-01T12:00:00Z"
            }
          },
          "planet_id": {
            "description": "SE-compatible planet ID (0=Sun, 1=Moon, 2=Mercury, etc.)",
            "example": 2,
            "title": "Planet Id",
            "type": "integer"
          }
        },
        "required": [
          "planet_id",
          "date_time"
        ],
        "title": "RetrogradeStatusRequest",
        "type": "object"
      },
      "RetrogradeStatusResponse": {
        "additionalProperties": false,
        "description": "Response from retrograde status check.",
        "properties": {
          "is_retrograde": {
            "description": "True if planet is in retrograde motion",
            "title": "Is Retrograde",
            "type": "boolean"
          },
          "longitude_speed": {
            "description": "Longitude speed in degrees per day",
            "title": "Longitude Speed",
            "type": "number"
          },
          "motion_type": {
            "description": "Motion classification: direct, retrograde, or stationary",
            "example": "direct",
            "title": "Motion Type",
            "type": "string"
          },
          "planet_id": {
            "description": "SE-compatible planet ID",
            "title": "Planet Id",
            "type": "integer"
          },
          "planet_name": {
            "description": "Planet name",
            "title": "Planet Name",
            "type": "string"
          },
          "speed_threshold": {
            "default": 0.01,
            "description": "Threshold for stationary classification (degrees/day)",
            "title": "Speed Threshold",
            "type": "number"
          },
          "success": {
            "default": true,
            "description": "Calculation success status",
            "title": "Success",
            "type": "boolean"
          }
        },
        "required": [
          "planet_name",
          "planet_id",
          "is_retrograde",
          "motion_type",
          "longitude_speed"
        ],
        "title": "RetrogradeStatusResponse",
        "type": "object"
      },
      "ReturnBodyEnum": {
        "description": "Supported bodies for return calculations.",
        "enum": [
          "Sun",
          "Moon",
          "Mercury",
          "Venus",
          "Mars",
          "Jupiter",
          "Saturn",
          "Uranus",
          "Neptune",
          "Pluto",
          "Chiron",
          "Pholus",
          "Mean Node",
          "Mean Lilith",
          "True Lilith"
        ],
        "title": "ReturnBodyEnum",
        "type": "string"
      },
      "ReturnLocation": {
        "additionalProperties": false,
        "description": "Normalized location details echoed in return responses.",
        "example": {
          "elevation": 10,
          "latitude": 40.7128,
          "longitude": -74.006,
          "timezone": "America/New_York"
        },
        "properties": {
          "elevation": {
            "default": 0,
            "description": "Elevation above sea level in meters",
            "title": "Elevation",
            "type": "number"
          },
          "latitude": {
            "description": "Latitude in decimal degrees",
            "title": "Latitude",
            "type": "number"
          },
          "longitude": {
            "description": "Longitude in decimal degrees",
            "title": "Longitude",
            "type": "number"
          },
          "timezone": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "IANA timezone identifier",
            "title": "Timezone"
          }
        },
        "required": [
          "latitude",
          "longitude"
        ],
        "title": "ReturnLocation",
        "type": "object"
      },
      "ReverseGeocodeResponse": {
        "additionalProperties": true,
        "description": "Response for /location/reverse endpoint.",
        "example": {
          "city": "New York",
          "country": "United States",
          "country_code": "US",
          "display_name": "New York, New York, United States",
          "latitude": 40.7128,
          "longitude": -74.006,
          "region": "New York",
          "timezone": "America/New_York"
        },
        "properties": {
          "city": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "City or locality name, if available",
            "title": "City"
          },
          "country": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Full country name",
            "title": "Country"
          },
          "country_code": {
            "anyOf": [
              {
                "maxLength": 2,
                "minLength": 2,
                "type": "string"
              }
            ],
            "description": "ISO 3166-1 alpha-2 country code",
            "title": "Country Code"
          },
          "display_name": {
            "description": "Formatted name suitable for UI display",
            "title": "Display Name",
            "type": "string"
          },
          "latitude": {
            "description": "Latitude in decimal degrees",
            "maximum": 90,
            "minimum": -90,
            "title": "Latitude",
            "type": "number"
          },
          "longitude": {
            "description": "Longitude in decimal degrees",
            "maximum": 180,
            "minimum": -180,
            "title": "Longitude",
            "type": "number"
          },
          "region": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Region, state, or province name",
            "title": "Region"
          },
          "timezone": {
            "description": "IANA timezone identifier",
            "title": "Timezone",
            "type": "string"
          }
        },
        "required": [
          "latitude",
          "longitude",
          "timezone",
          "display_name"
        ],
        "title": "ReverseGeocodeResponse",
        "type": "object"
      },
      "SafetyWarnings": {
        "properties": {
          "baileys_beads_visible": {
            "default": false,
            "title": "Baileys Beads Visible",
            "type": "boolean"
          },
          "corona_visible_duration": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "title": "Corona Visible Duration"
          },
          "eye_protection_required": {
            "title": "Eye Protection Required",
            "type": "boolean"
          },
          "partial_phase_duration": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "title": "Partial Phase Duration"
          },
          "path_uncertainty_note": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "title": "Path Uncertainty Note"
          }
        },
        "required": [
          "eye_protection_required"
        ],
        "title": "SafetyWarnings",
        "type": "object"
      },
      "SarosSeriesResponse": {
        "properties": {
          "eclipses": {
            "default": [],
            "items": {
              "$ref": "#/components/schemas/EclipseSummary"
            },
            "title": "Eclipses",
            "type": "array"
          },
          "member": {
            "title": "Member",
            "type": "integer"
          },
          "node_type": {
            "title": "Node Type",
            "type": "string"
          },
          "series": {
            "title": "Series",
            "type": "integer"
          }
        },
        "required": [
          "series",
          "member",
          "node_type"
        ],
        "title": "SarosSeriesResponse",
        "type": "object"
      },
      "SectDeterminationResponse": {
        "additionalProperties": false,
        "description": "Sect determination analysis.",
        "properties": {
          "benefics_in_sect": {
            "description": "Benefics in proper sect",
            "items": {
              "type": "string"
            },
            "title": "Benefics In Sect",
            "type": "array"
          },
          "is_day_chart": {
            "description": "Is this a day chart",
            "title": "Is Day Chart",
            "type": "boolean"
          },
          "malefics_in_sect": {
            "description": "Malefics in proper sect",
            "items": {
              "type": "string"
            },
            "title": "Malefics In Sect",
            "type": "array"
          },
          "sect": {
            "description": "Chart sect (diurnal/nocturnal)",
            "title": "Sect",
            "type": "string"
          },
          "sect_conditions": {
            "description": "Detailed sect conditions",
            "title": "Sect Conditions",
            "type": "object"
          },
          "sect_light": {
            "description": "Sect light (Sun for day, Moon for night)",
            "title": "Sect Light",
            "type": "string"
          },
          "sun_above_horizon": {
            "description": "Is Sun above horizon",
            "title": "Sun Above Horizon",
            "type": "boolean"
          }
        },
        "required": [
          "is_day_chart",
          "sect",
          "sun_above_horizon",
          "sect_light",
          "benefics_in_sect",
          "malefics_in_sect",
          "sect_conditions"
        ],
        "title": "SectDeterminationResponse",
        "type": "object"
      },
      "SelectedLunationType": {
        "enum": [
          "new_moon",
          "full_moon"
        ],
        "type": "string"
      },
      "SiderealTimeResponse": {
        "properties": {
          "equation_of_equinoxes": {
            "description": "The nutation correction in hours",
            "title": "Equation Of Equinoxes",
            "type": "number"
          },
          "gmst": {
            "description": "Greenwich Mean Sidereal Time in hours",
            "title": "Gmst",
            "type": "number"
          },
          "information": {
            "description": "Metadata about the calculation engine",
            "title": "Information",
            "type": "object"
          },
          "last": {
            "description": "Local Apparent Sidereal Time in hours",
            "title": "Last",
            "type": "number"
          },
          "longitude_used": {
            "description": "The observer longitude used for LAST",
            "title": "Longitude Used",
            "type": "number"
          }
        },
        "required": [
          "gmst",
          "last",
          "equation_of_equinoxes",
          "longitude_used",
          "information"
        ],
        "title": "SiderealTimeResponse",
        "type": "object"
      },
      "SignIngress": {
        "properties": {
          "calculation_accuracy": {
            "default": 0,
            "title": "Calculation Accuracy",
            "type": "number"
          },
          "calculation_time": {
            "format": "date-time",
            "title": "Calculation Time",
            "type": "string"
          },
          "daily_motion": {
            "default": 0,
            "title": "Daily Motion",
            "type": "number"
          },
          "exact_longitude": {
            "default": 0,
            "title": "Exact Longitude",
            "type": "number"
          },
          "expected_time_in_new_sign": {
            "default": 0,
            "title": "Expected Time In New Sign",
            "type": "number"
          },
          "from_sign": {
            "title": "From Sign",
            "type": "string"
          },
          "ingress_number": {
            "default": 1,
            "title": "Ingress Number",
            "type": "integer"
          },
          "ingress_speed": {
            "default": 0,
            "title": "Ingress Speed",
            "type": "number"
          },
          "ingress_time": {
            "format": "date-time",
            "title": "Ingress Time",
            "type": "string"
          },
          "is_final_ingress": {
            "default": true,
            "title": "Is Final Ingress",
            "type": "boolean"
          },
          "metadata": {
            "title": "Metadata",
            "type": "object"
          },
          "next_re_ingress": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              }
            ],
            "title": "Next Re Ingress"
          },
          "planet_distance": {
            "default": 0,
            "title": "Planet Distance",
            "type": "number"
          },
          "planet_id": {
            "title": "Planet Id",
            "type": "integer"
          },
          "planet_latitude": {
            "default": 0,
            "title": "Planet Latitude",
            "type": "number"
          },
          "planet_name": {
            "title": "Planet Name",
            "type": "string"
          },
          "previous_ingress": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              }
            ],
            "title": "Previous Ingress"
          },
          "retrograde_status": {
            "allOf": [
              {
                "$ref": "#/components/schemas/RetrogradeStatus"
              }
            ],
            "default": "direct"
          },
          "search_iterations": {
            "default": 0,
            "title": "Search Iterations",
            "type": "integer"
          },
          "seasonal_significance": {
            "default": "",
            "title": "Seasonal Significance",
            "type": "string"
          },
          "sign_change_type": {
            "default": "normal",
            "title": "Sign Change Type",
            "type": "string"
          },
          "time_in_previous_sign": {
            "default": 0,
            "title": "Time In Previous Sign",
            "type": "number"
          },
          "to_sign": {
            "title": "To Sign",
            "type": "string"
          },
          "total_ingresses": {
            "default": 1,
            "title": "Total Ingresses",
            "type": "integer"
          }
        },
        "required": [
          "planet_id",
          "planet_name",
          "from_sign",
          "to_sign",
          "ingress_time"
        ],
        "title": "SignIngress",
        "type": "object"
      },
      "SignIngressRequest": {
        "additionalProperties": false,
        "description": "Request schema for sign ingress calculation.",
        "example": {
          "end_date": "2025-01-01T00:00:00Z",
          "planet_names": [
            "Mars",
            "Jupiter"
          ],
          "start_date": "2024-01-01T00:00:00Z",
          "target_sign": "Aries"
        },
        "properties": {
          "end_date": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              }
            ],
            "description": "Search range end date (default: +1 year)",
            "title": "End Date"
          },
          "planet_names": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              }
            ],
            "description": "Specific planets (validated in route)",
            "title": "Planet Names"
          },
          "start_date": {
            "description": "Search range start date",
            "format": "date-time",
            "title": "Start Date",
            "type": "string"
          },
          "target_sign": {
            "$ref": "#/components/schemas/ZodiacSignEnum",
            "description": "Specific sign to search for"
          }
        },
        "required": [
          "start_date"
        ],
        "title": "SignIngressRequest",
        "type": "object"
      },
      "SignIngressResponse": {
        "description": "Response schema for sign ingress calculation.",
        "properties": {
          "calculation_metadata": {
            "$ref": "#/components/schemas/CalculationMetadata",
            "description": "Standardized calculation metadata describing the ingress computation"
          },
          "ingresses": {
            "additionalProperties": {
              "items": {
                "$ref": "#/components/schemas/SignIngress"
              },
              "type": "array"
            },
            "description": "Ingresses grouped by planet name",
            "title": "Ingresses",
            "type": "object"
          },
          "metadata": {
            "allOf": [
              {
                "$ref": "#/components/schemas/PredictiveMetadata"
              }
            ],
            "description": "Calculation metadata"
          },
          "success": {
            "description": "Request success status",
            "title": "Success",
            "type": "boolean"
          },
          "total_count": {
            "description": "Total number of ingresses found",
            "title": "Total Count",
            "type": "integer"
          }
        },
        "required": [
          "success",
          "ingresses",
          "total_count",
          "metadata"
        ],
        "title": "SignIngressResponse",
        "type": "object"
      },
      "SolarEclipseGlobalResponse": {
        "properties": {
          "besselian_elements": {
            "$ref": "#/components/schemas/BesselianElements"
          },
          "eclipse_classification": {
            "$ref": "#/components/schemas/EclipseClassification"
          },
          "meta": {
            "$ref": "#/components/schemas/CalculationMeta"
          },
          "safety": {
            "$ref": "#/components/schemas/SafetyWarnings"
          },
          "uncertainty": {
            "$ref": "#/components/schemas/UncertaintyInfo"
          }
        },
        "required": [
          "meta",
          "eclipse_classification",
          "besselian_elements"
        ],
        "title": "SolarEclipseGlobalResponse",
        "type": "object"
      },
      "SolarEclipseLocalResponse": {
        "properties": {
          "besselian_elements": {
            "$ref": "#/components/schemas/BesselianElements"
          },
          "eclipse_classification": {
            "$ref": "#/components/schemas/EclipseClassification"
          },
          "local_circumstances": {
            "$ref": "#/components/schemas/LocalCircumstances"
          },
          "meta": {
            "$ref": "#/components/schemas/CalculationMeta"
          },
          "safety": {
            "$ref": "#/components/schemas/SafetyWarnings"
          },
          "uncertainty": {
            "$ref": "#/components/schemas/UncertaintyInfo"
          }
        },
        "required": [
          "meta",
          "eclipse_classification",
          "besselian_elements",
          "local_circumstances"
        ],
        "title": "SolarEclipseLocalResponse",
        "type": "object"
      },
      "SolarEventDetail": {
        "properties": {
          "altitude_deg": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "description": "Altitude in degrees (positive above horizon)",
            "title": "Altitude Deg"
          },
          "azimuth_deg": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "description": "Azimuth in degrees (0=North, 90=East)",
            "title": "Azimuth Deg"
          },
          "jd": {
            "description": "Exact time as a Julian Day number",
            "format": "double",
            "title": "Jd",
            "type": "number"
          },
          "time_iso": {
            "description": "Exact time in ISO 8601 format",
            "title": "Time Iso",
            "type": "string"
          },
          "type": {
            "description": "Type of event (sunrise, sunset, transit, etc.)",
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "type",
          "time_iso",
          "jd"
        ],
        "title": "SolarEventDetail",
        "type": "object"
      },
      "SolarEventResponse": {
        "properties": {
          "date": {
            "description": "The requested date",
            "title": "Date",
            "type": "string"
          },
          "events": {
            "description": "List of solar events found for the day",
            "items": {
              "$ref": "#/components/schemas/SolarEventDetail"
            },
            "title": "Events",
            "type": "array"
          },
          "information": {
            "description": "Metadata about the calculation engine",
            "title": "Information",
            "type": "object"
          },
          "latitude": {
            "description": "Observer latitude",
            "title": "Latitude",
            "type": "number"
          },
          "longitude": {
            "description": "Observer longitude",
            "title": "Longitude",
            "type": "number"
          }
        },
        "required": [
          "date",
          "latitude",
          "longitude",
          "events"
        ],
        "title": "SolarEventResponse",
        "type": "object"
      },
      "SolarReturnResponse": {
        "description": "Response payload for solar return calculations.",
        "properties": {
          "calculation_metadata": {
            "$ref": "#/components/schemas/CalculationMetadata",
            "description": "Standardized calculation metadata describing the return computation"
          },
          "chart": {
            "$ref": "#/components/schemas/NatalChartResponse",
            "description": "Full chart calculation at return moment (if include_chart=True)"
          },
          "exact_datetime": {
            "description": "Exact return datetime (UTC)",
            "format": "date-time",
            "title": "Exact Datetime",
            "type": "string"
          },
          "location": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ReturnLocation"
              }
            ],
            "description": "Normalized location used for chart calculation"
          },
          "metadata": {
            "allOf": [
              {
                "$ref": "#/components/schemas/PredictiveMetadata"
              }
            ],
            "description": "Calculation metadata"
          },
          "output_mode": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Output projection mode (full | simple | llm)",
            "title": "Output Mode"
          },
          "schema_version": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Schema version for the selected output mode (e.g., full_v1, simple_v1, llm)",
            "title": "Schema Version"
          },
          "success": {
            "description": "Request success status",
            "title": "Success",
            "type": "boolean"
          },
          "visual": {
            "$ref": "#/components/schemas/VisualResult",
            "description": "Inline chart visual, present only when include_visual=true was requested."
          }
        },
        "required": [
          "success",
          "exact_datetime",
          "location",
          "metadata"
        ],
        "title": "SolarReturnResponse",
        "type": "object"
      },
      "StemBranchPair": {
        "description": "A Heavenly Stem + Earthly Branch pair (one pillar).",
        "properties": {
          "branch": {
            "additionalProperties": {
              "type": "string"
            },
            "title": "Branch",
            "type": "object"
          },
          "stem": {
            "additionalProperties": {
              "type": "string"
            },
            "title": "Stem",
            "type": "object"
          }
        },
        "required": [
          "stem",
          "branch"
        ],
        "title": "StemBranchPair",
        "type": "object"
      },
      "StripeCheckoutSessionRequest": {
        "properties": {
          "embedded": {
            "default": false,
            "description": "When true, create an embedded Checkout Session and return a client secret instead of a redirect URL.",
            "example": false,
            "title": "Embedded",
            "type": "boolean"
          },
          "return_url": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Optional return URL for embedded checkout. Must match the configured frontend origin.",
            "example": "https://astromcp.io/billing/success",
            "title": "Return Url"
          },
          "tier": {
            "description": "Requested subscription tier for Stripe Checkout.",
            "enum": [
              "anonymous",
              "explorer",
              "developer",
              "pro",
              "scale",
              "service"
            ],
            "example": "pro",
            "title": "Tier",
            "type": "string"
          }
        },
        "required": [
          "tier"
        ],
        "title": "StripeCheckoutSessionRequest",
        "type": "object"
      },
      "StripeCheckoutSessionResponse": {
        "properties": {
          "clientSecret": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Stripe Checkout Session client secret (embedded checkout).",
            "title": "Clientsecret"
          },
          "sessionId": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Alias of session_id (embedded checkout convenience field).",
            "title": "Sessionid"
          },
          "session_id": {
            "description": "Stripe Checkout session id.",
            "title": "Session Id",
            "type": "string"
          },
          "url": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Stripe Checkout URL to redirect the user to (hosted checkout).",
            "title": "Url"
          }
        },
        "required": [
          "session_id"
        ],
        "title": "StripeCheckoutSessionResponse",
        "type": "object"
      },
      "StripePortalSessionResponse": {
        "properties": {
          "sessionId": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Alias of session_id (frontend convenience field).",
            "title": "Sessionid"
          },
          "session_id": {
            "description": "Stripe billing portal session id.",
            "title": "Session Id",
            "type": "string"
          },
          "url": {
            "description": "Stripe Customer Portal URL.",
            "title": "Url",
            "type": "string"
          }
        },
        "required": [
          "url",
          "session_id"
        ],
        "title": "StripePortalSessionResponse",
        "type": "object"
      },
      "StripePublicCheckoutConfirmRequest": {
        "properties": {
          "session_id": {
            "description": "Stripe Checkout session id to confirm.",
            "title": "Session Id",
            "type": "string"
          }
        },
        "required": [
          "session_id"
        ],
        "title": "StripePublicCheckoutConfirmRequest",
        "type": "object"
      },
      "StripePublicCheckoutConfirmResponse": {
        "properties": {
          "magic_link_sent": {
            "default": false,
            "description": "Whether a magic link was sent.",
            "title": "Magic Link Sent",
            "type": "boolean"
          },
          "payment_status": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Stripe payment status.",
            "title": "Payment Status"
          },
          "session_id": {
            "description": "Stripe Checkout session id.",
            "title": "Session Id",
            "type": "string"
          },
          "session_status": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Stripe session status.",
            "title": "Session Status"
          }
        },
        "required": [
          "session_id"
        ],
        "title": "StripePublicCheckoutConfirmResponse",
        "type": "object"
      },
      "StripePublicCheckoutSessionRequest": {
        "properties": {
          "email": {
            "description": "Email address used to initialize checkout and deliver access link.",
            "example": "user@example.com",
            "title": "Email",
            "type": "string"
          },
          "embedded": {
            "default": true,
            "description": "Embedded checkout must be true for public onboarding.",
            "example": true,
            "title": "Embedded",
            "type": "boolean"
          },
          "name": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Optional display name to associate with the checkout session.",
            "example": "Ada Lovelace",
            "title": "Name"
          },
          "return_url": {
            "description": "Frontend URL to return to after embedded checkout completes.",
            "example": "https://astromcp.io/billing/success",
            "title": "Return Url",
            "type": "string"
          },
          "tier": {
            "description": "Requested subscription tier (single-tier model).",
            "example": "pro",
            "title": "Tier",
            "type": "string"
          }
        },
        "required": [
          "email",
          "tier",
          "return_url"
        ],
        "title": "StripePublicCheckoutSessionRequest",
        "type": "object"
      },
      "StripePublicCheckoutSessionResponse": {
        "properties": {
          "clientSecret": {
            "description": "Stripe Checkout Session client secret (embedded checkout).",
            "title": "Clientsecret",
            "type": "string"
          },
          "session_id": {
            "description": "Stripe Checkout session id.",
            "title": "Session Id",
            "type": "string"
          }
        },
        "required": [
          "session_id",
          "clientSecret"
        ],
        "title": "StripePublicCheckoutSessionResponse",
        "type": "object"
      },
      "SubjectRequest": {
        "additionalProperties": false,
        "description": "Subject identity and birth data used to compute a chart.",
        "example": {
          "birth_datetime": {
            "iso": "1990-06-15T14:30:00"
          },
          "birth_location": {
            "latitude": {
              "decimal": 40.7128
            },
            "longitude": {
              "decimal": -74.006
            },
            "timezone": {
              "iana_name": "America/New_York"
            }
          },
          "name": "John Doe"
        },
        "properties": {
          "birth_datetime": {
            "allOf": [
              {
                "$ref": "#/components/schemas/DateTimeInput"
              }
            ],
            "description": "Birth date and time (alias: 'datetime')"
          },
          "birth_location": {
            "allOf": [
              {
                "$ref": "#/components/schemas/BirthLocation"
              }
            ],
            "description": "Birth location details"
          },
          "gender": {
            "anyOf": [
              {
                "maxLength": 32,
                "type": "string"
              }
            ],
            "description": "Gender (optional)",
            "title": "Gender"
          },
          "name": {
            "description": "Subject name",
            "maxLength": 120,
            "minLength": 1,
            "title": "Name",
            "type": "string"
          },
          "notes": {
            "anyOf": [
              {
                "maxLength": 1000,
                "type": "string"
              }
            ],
            "description": "Additional notes",
            "title": "Notes"
          }
        },
        "required": [
          "name",
          "birth_datetime",
          "birth_location"
        ],
        "title": "SubjectRequest",
        "type": "object"
      },
      "SubjectResponse": {
        "additionalProperties": true,
        "description": "Normalized subject data in response.",
        "properties": {
          "altitude": {
            "description": "Altitude in meters",
            "title": "Altitude",
            "type": "number"
          },
          "datetime": {
            "description": "ISO format datetime",
            "title": "Datetime",
            "type": "string"
          },
          "julian_day": {
            "description": "Julian Day Number",
            "format": "double",
            "title": "Julian Day",
            "type": "number"
          },
          "latitude": {
            "description": "Latitude in decimal degrees",
            "title": "Latitude",
            "type": "number"
          },
          "longitude": {
            "description": "Longitude in decimal degrees",
            "title": "Longitude",
            "type": "number"
          },
          "name": {
            "description": "Subject name",
            "title": "Name",
            "type": "string"
          },
          "timezone_name": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Timezone name if available",
            "title": "Timezone Name"
          },
          "utc_offset": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "description": "UTC offset in hours",
            "title": "Utc Offset"
          }
        },
        "required": [
          "name",
          "datetime",
          "julian_day",
          "latitude",
          "longitude",
          "altitude"
        ],
        "title": "SubjectResponse",
        "type": "object"
      },
      "SynastryRequest": {
        "additionalProperties": false,
        "description": "Synastry request comparing two natal subjects.",
        "example": {
          "subject_a": {
            "birth_datetime": {
              "iso": "1990-06-15T14:30:00"
            },
            "birth_location": {
              "latitude": {
                "decimal": 40.7128
              },
              "longitude": {
                "decimal": -74.006
              },
              "timezone": {
                "iana_name": "America/New_York"
              }
            },
            "name": "Alice"
          },
          "subject_b": {
            "birth_datetime": {
              "iso": "1992-02-10T09:15:00"
            },
            "birth_location": {
              "latitude": {
                "decimal": 34.0522
              },
              "longitude": {
                "decimal": -118.2437
              },
              "timezone": {
                "iana_name": "America/Los_Angeles"
              }
            },
            "name": "Bob"
          }
        },
        "properties": {
          "configuration": {
            "$ref": "#/components/schemas/ChartConfiguration",
            "description": "Chart calculation settings"
          },
          "enhanced_options": {
            "$ref": "#/components/schemas/EnhancedCalculationOptions",
            "description": "Optional enhanced calculation flags applied to both charts before synastry aspects are computed. Use this to enable interpretive math layers like midpoints/harmonics/patterns/HD gates. (Mirrors /ephemeris/natal-chart enhanced_options.)"
          },
          "include_visual": {
            "default": false,
            "description": "If true, a full visual SVG or PNG output will be rendered and returned alongside the chart data. Note: Visuals incur a +2 credit surcharge.",
            "title": "Include Visual",
            "type": "boolean"
          },
          "subject_a": {
            "allOf": [
              {
                "$ref": "#/components/schemas/SubjectRequest"
              }
            ],
            "description": "First subject (Inner Ring)"
          },
          "subject_b": {
            "allOf": [
              {
                "$ref": "#/components/schemas/SubjectRequest"
              }
            ],
            "description": "Second subject (Outer Ring)"
          },
          "visual_config": {
            "$ref": "#/components/schemas/VisualRenderConfig"
          }
        },
        "required": [
          "subject_a",
          "subject_b"
        ],
        "title": "SynastryRequest",
        "type": "object"
      },
      "SynastryResponse": {
        "description": "Response for synastry calculation.",
        "properties": {
          "aspects": {
            "description": "Cross-aspects between A and B",
            "items": {
              "$ref": "#/components/schemas/AspectResponse"
            },
            "title": "Aspects",
            "type": "array"
          },
          "chart_a": {
            "allOf": [
              {
                "$ref": "#/components/schemas/NatalChartEnhancedResponse"
              }
            ],
            "description": "Chart for Subject A"
          },
          "chart_b": {
            "allOf": [
              {
                "$ref": "#/components/schemas/NatalChartEnhancedResponse"
              }
            ],
            "description": "Chart for Subject B"
          },
          "visual": {
            "$ref": "#/components/schemas/VisualResult",
            "description": "Inline chart visual, present only when include_visual=true was requested."
          }
        },
        "required": [
          "chart_a",
          "chart_b",
          "aspects"
        ],
        "title": "SynastryResponse",
        "type": "object"
      },
      "ThunAnalysis": {
        "properties": {
          "ascending": {
            "description": "True if Moon latitude is increasing",
            "title": "Ascending",
            "type": "boolean"
          },
          "base_element": {
            "description": "earth | water | air | fire",
            "title": "Base Element",
            "type": "string"
          },
          "day_type": {
            "description": "root | leaf | flower | fruit",
            "title": "Day Type",
            "type": "string"
          },
          "favorable": {
            "items": {
              "type": "string"
            },
            "title": "Favorable",
            "type": "array"
          },
          "lat_velocity": {
            "description": "Latitude velocity in degrees per day",
            "title": "Lat Velocity",
            "type": "number"
          },
          "modifiers": {
            "items": {
              "$ref": "#/components/schemas/ThunModifier"
            },
            "title": "Modifiers",
            "type": "array"
          },
          "optimal": {
            "items": {
              "type": "string"
            },
            "title": "Optimal",
            "type": "array"
          },
          "quality_score": {
            "description": "Quality score from 0 to 100",
            "title": "Quality Score",
            "type": "integer"
          },
          "unfavorable": {
            "items": {
              "type": "string"
            },
            "title": "Unfavorable",
            "type": "array"
          }
        },
        "required": [
          "day_type",
          "base_element",
          "quality_score",
          "ascending",
          "lat_velocity"
        ],
        "title": "ThunAnalysis",
        "type": "object"
      },
      "ThunModifier": {
        "properties": {
          "aspect": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Aspect name",
            "title": "Aspect"
          },
          "impact": {
            "description": "Signed score delta",
            "title": "Impact",
            "type": "integer"
          },
          "orb": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "description": "Orb in degrees",
            "title": "Orb"
          },
          "planet": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Planet name",
            "title": "Planet"
          },
          "source": {
            "description": "Source of the modifier, e.g., 'saturn_opposition'",
            "title": "Source",
            "type": "string"
          }
        },
        "required": [
          "source",
          "impact"
        ],
        "title": "ThunModifier",
        "type": "object"
      },
      "TidalForcingResponse": {
        "description": "Full tidal forcing analysis for a location and time.",
        "properties": {
          "date": {
            "description": "Date in YYYY-MM-DD format (if requested by date)",
            "title": "Date",
            "type": "string"
          },
          "equilibrium": {
            "allOf": [
              {
                "$ref": "#/components/schemas/EquilibriumTide"
              }
            ],
            "description": "Theoretical equilibrium tide heights"
          },
          "forcing_indices": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ForcingIndices"
              }
            ],
            "description": "Computed forcing indicators"
          },
          "julian_day": {
            "description": "Julian Day of the calculation",
            "format": "double",
            "title": "Julian Day",
            "type": "number"
          },
          "lunar": {
            "allOf": [
              {
                "$ref": "#/components/schemas/TidalLunarData"
              }
            ],
            "description": "Lunar parameters"
          },
          "meta": {
            "allOf": [
              {
                "$ref": "#/components/schemas/TidalMeta"
              }
            ],
            "description": "Metadata and disclaimers"
          },
          "observer": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Observer"
              }
            ],
            "description": "Observer location"
          },
          "solar": {
            "allOf": [
              {
                "$ref": "#/components/schemas/TidalSolarData"
              }
            ],
            "description": "Solar parameters"
          }
        },
        "required": [
          "meta",
          "date",
          "julian_day",
          "observer",
          "lunar",
          "solar",
          "forcing_indices",
          "equilibrium"
        ],
        "title": "TidalForcingResponse",
        "type": "object"
      },
      "TidalLunarData": {
        "properties": {
          "days_to_perigee": {
            "description": "Approximate days to next perigee (-1 if unknown)",
            "title": "Days To Perigee",
            "type": "integer"
          },
          "declination": {
            "description": "Moon declination in degrees",
            "title": "Declination",
            "type": "number"
          },
          "distance_anomaly": {
            "description": "Distance anomaly (perigee proximity)",
            "title": "Distance Anomaly",
            "type": "number"
          },
          "distance_km": {
            "description": "Moon distance in km",
            "title": "Distance Km",
            "type": "number"
          },
          "perigee_status": {
            "description": "'near_perigee', 'near_apogee', or 'intermediate'",
            "title": "Perigee Status",
            "type": "string"
          },
          "phase_angle": {
            "description": "Lunar phase angle in degrees",
            "title": "Phase Angle",
            "type": "number"
          },
          "phase_name": {
            "description": "Lunar phase name",
            "title": "Phase Name",
            "type": "string"
          }
        },
        "required": [
          "phase_name",
          "phase_angle",
          "distance_km",
          "distance_anomaly",
          "declination",
          "perigee_status",
          "days_to_perigee"
        ],
        "title": "TidalLunarData",
        "type": "object"
      },
      "TidalMeta": {
        "properties": {
          "calculation_ms": {
            "description": "Calculation time in milliseconds",
            "title": "Calculation Ms",
            "type": "integer"
          },
          "calculation_type": {
            "description": "Type of calculation performed",
            "title": "Calculation Type",
            "type": "string"
          },
          "disclaimer": {
            "description": "Disclaimer about astronomical vs local predictions",
            "title": "Disclaimer",
            "type": "string"
          },
          "ephemeris": {
            "description": "Ephemeris used, e.g., 'DE440'",
            "title": "Ephemeris",
            "type": "string"
          }
        },
        "required": [
          "ephemeris",
          "calculation_type",
          "disclaimer",
          "calculation_ms"
        ],
        "title": "TidalMeta",
        "type": "object"
      },
      "TidalSolarData": {
        "properties": {
          "declination": {
            "description": "Sun declination in degrees",
            "title": "Declination",
            "type": "number"
          },
          "distance_au": {
            "description": "Sun distance in AU",
            "title": "Distance Au",
            "type": "number"
          }
        },
        "required": [
          "declination",
          "distance_au"
        ],
        "title": "TidalSolarData",
        "type": "object"
      },
      "TimeScaleEnum": {
        "description": "Time scale used for reporting results.",
        "enum": [
          "UTC",
          "TT",
          "TDB"
        ],
        "title": "TimeScaleEnum",
        "type": "string"
      },
      "TimeScalesRequest": {
        "properties": {
          "from_scale": {
            "default": "utc",
            "description": "Input time scale (utc, tt, tai, tdb, ut1)",
            "title": "From Scale",
            "type": "string"
          },
          "julian_day": {
            "description": "Julian Day to convert",
            "format": "double",
            "title": "Julian Day",
            "type": "number"
          },
          "latitude": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "description": "Observer latitude",
            "title": "Latitude"
          },
          "longitude": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "description": "Observer longitude",
            "title": "Longitude"
          }
        },
        "required": [
          "julian_day"
        ],
        "title": "TimeScalesRequest",
        "type": "object"
      },
      "TimeScalesResponse": {
        "properties": {
          "delta_t": {
            "description": "Delta T value used (seconds)",
            "example": 69.18,
            "title": "Delta T",
            "type": "number"
          },
          "jd_tai": {
            "description": "Julian Day in International Atomic Time",
            "example": 2461114.50043,
            "format": "double",
            "title": "Jd Tai",
            "type": "number"
          },
          "jd_tdb": {
            "description": "Julian Day in Barycentric Dynamical Time",
            "example": 2461114.500802,
            "format": "double",
            "title": "Jd Tdb",
            "type": "number"
          },
          "jd_tt": {
            "description": "Julian Day in Terrestrial Time",
            "example": 2461114.500801,
            "format": "double",
            "title": "Jd Tt",
            "type": "number"
          },
          "jd_ut1": {
            "description": "Julian Day in Universal Time 1",
            "example": 2461114.5000007,
            "format": "double",
            "title": "Jd Ut1",
            "type": "number"
          },
          "jd_utc": {
            "description": "Julian Day in Coordinated Universal Time",
            "example": 2461114.5,
            "format": "double",
            "title": "Jd Utc",
            "type": "number"
          },
          "offsets_seconds": {
            "additionalProperties": {
              "type": "number"
            },
            "description": "Offsets in seconds between scales relative to TT",
            "example": {
              "tai_tt": 32.184,
              "tt_tdb": 0.0016
            },
            "title": "Offsets Seconds",
            "type": "object"
          }
        },
        "required": [
          "jd_utc",
          "jd_ut1",
          "jd_tt",
          "jd_tai",
          "jd_tdb",
          "delta_t",
          "offsets_seconds"
        ],
        "title": "TimeScalesResponse",
        "type": "object"
      },
      "TimeWindow": {
        "description": "Time range for predictive search.\n\nSupports two mutually exclusive modes:\n1. UTC mode: start/end are ISO-8601 UTC timestamps (for transits, returns, directions)\n2. Age mode: age_start/age_end are float years since birth (for progressions, profections)\n\nConstraints:\n- UTC window: max 10 years; use pagination + limit for longer ranges\n- Age window: float values allowed (e.g., 2.5 = 2 years 6 months)",
        "example": {
          "end": "2026-01-01T00:00:00Z",
          "mode": "utc",
          "start": "2025-01-01T00:00:00Z"
        },
        "properties": {
          "age_end": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "description": "Age end (years since birth)",
            "title": "Age End"
          },
          "age_start": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "description": "Age start (years since birth)",
            "title": "Age Start"
          },
          "end": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              }
            ],
            "description": "Window end (exclusive) in UTC",
            "title": "End"
          },
          "mode": {
            "allOf": [
              {
                "$ref": "#/components/schemas/TimeWindowModeEnum"
              }
            ],
            "default": "utc"
          },
          "start": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              }
            ],
            "description": "Window start (inclusive) in UTC",
            "title": "Start"
          }
        },
        "title": "TimeWindow",
        "type": "object"
      },
      "TimeWindowModeEnum": {
        "description": "TimeWindow mode selector: UTC timestamps or age-based.",
        "enum": [
          "utc",
          "age"
        ],
        "title": "TimeWindowModeEnum",
        "type": "string"
      },
      "TimezoneInput": {
        "additionalProperties": false,
        "description": "Timezone input using IANA names or UTC offsets.",
        "example": {
          "iana_name": "America/New_York"
        },
        "properties": {
          "iana_name": {
            "anyOf": [
              {
                "maxLength": 128,
                "type": "string"
              }
            ],
            "description": "IANA timezone name",
            "title": "Iana Name"
          },
          "utc_offset": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "description": "UTC offset in hours",
            "title": "Utc Offset"
          }
        },
        "title": "TimezoneInput",
        "type": "object"
      },
      "TimezoneLookupRequest": {
        "description": "Request to look up an IANA timezone by geographic coordinates.",
        "example": {
          "latitude": 37.7749,
          "longitude": -122.4194
        },
        "properties": {
          "latitude": {
            "description": "Latitude in decimal degrees",
            "maximum": 90,
            "minimum": -90,
            "title": "Latitude",
            "type": "number"
          },
          "longitude": {
            "description": "Longitude in decimal degrees",
            "maximum": 180,
            "minimum": -180,
            "title": "Longitude",
            "type": "number"
          }
        },
        "required": [
          "latitude",
          "longitude"
        ],
        "title": "TimezoneLookupRequest",
        "type": "object"
      },
      "TimezoneLookupResponse": {
        "description": "Response for a timezone lookup operation.",
        "properties": {
          "calculation_metadata": {
            "$ref": "#/components/schemas/CalculationMetadata",
            "description": "Metadata describing how the timezone lookup was performed"
          },
          "fallback": {
            "default": false,
            "description": "True when a generic/UTC fallback was used",
            "title": "Fallback",
            "type": "boolean"
          },
          "latitude": {
            "description": "Echoed latitude input",
            "title": "Latitude",
            "type": "number"
          },
          "longitude": {
            "description": "Echoed longitude input",
            "title": "Longitude",
            "type": "number"
          },
          "timezone": {
            "description": "Resolved IANA timezone name (e.g., 'America/Los_Angeles')",
            "title": "Timezone",
            "type": "string"
          }
        },
        "required": [
          "timezone",
          "latitude",
          "longitude"
        ],
        "title": "TimezoneLookupResponse",
        "type": "object"
      },
      "TimezoneOffsetRequest": {
        "description": "Request to compute UTC offset for a coordinate at a specific instant.\n\nNote: If the provided datetime is naive (no tzinfo), it's interpreted as UTC.",
        "example": {
          "datetime_utc": "2025-07-01T12:00:00Z",
          "lat": 37.7749,
          "lon": -122.4194
        },
        "properties": {
          "datetime_utc": {
            "description": "Instant (ISO-8601). Naive interpreted as UTC.",
            "format": "date-time",
            "title": "Datetime Utc",
            "type": "string"
          },
          "lat": {
            "description": "Latitude in decimal degrees",
            "maximum": 90,
            "minimum": -90,
            "title": "Lat",
            "type": "number"
          },
          "lon": {
            "description": "Longitude in decimal degrees",
            "maximum": 180,
            "minimum": -180,
            "title": "Lon",
            "type": "number"
          }
        },
        "required": [
          "lat",
          "lon",
          "datetime_utc"
        ],
        "title": "TimezoneOffsetRequest",
        "type": "object"
      },
      "TimezoneOffsetResponse": {
        "description": "Offset details for a coordinate at a specific instant.",
        "properties": {
          "calculation_metadata": {
            "$ref": "#/components/schemas/CalculationMetadata",
            "description": "Metadata describing how the timezone offset was computed"
          },
          "fallback": {
            "default": false,
            "description": "True when a generic/UTC fallback was used",
            "title": "Fallback",
            "type": "boolean"
          },
          "is_dst": {
            "description": "Whether DST is in effect at the instant",
            "title": "Is Dst",
            "type": "boolean"
          },
          "offset_hours": {
            "description": "UTC offset in fractional hours at the given instant",
            "title": "Offset Hours",
            "type": "number"
          },
          "offset_seconds": {
            "description": "UTC offset in seconds at the given instant",
            "title": "Offset Seconds",
            "type": "integer"
          },
          "offset_string": {
            "description": "UTC offset formatted as ±HH:MM",
            "title": "Offset String",
            "type": "string"
          },
          "timezone": {
            "description": "Resolved IANA timezone (or generic Etc/GMT±N)",
            "title": "Timezone",
            "type": "string"
          }
        },
        "required": [
          "timezone",
          "offset_seconds",
          "offset_hours",
          "offset_string",
          "is_dst"
        ],
        "title": "TimezoneOffsetResponse",
        "type": "object"
      },
      "Transit": {
        "properties": {
          "approach_duration": {
            "default": 0,
            "title": "Approach Duration",
            "type": "number"
          },
          "calculation_accuracy": {
            "default": 0,
            "title": "Calculation Accuracy",
            "type": "number"
          },
          "calculation_time": {
            "format": "date-time",
            "title": "Calculation Time",
            "type": "string"
          },
          "crossing_number": {
            "default": 1,
            "title": "Crossing Number",
            "type": "integer"
          },
          "daily_motion": {
            "default": 0,
            "title": "Daily Motion",
            "type": "number"
          },
          "exact_time": {
            "format": "date-time",
            "title": "Exact Time",
            "type": "string"
          },
          "is_retrograde": {
            "default": false,
            "title": "Is Retrograde",
            "type": "boolean"
          },
          "metadata": {
            "title": "Metadata",
            "type": "object"
          },
          "next_crossing": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              }
            ],
            "title": "Next Crossing"
          },
          "orb_approaching": {
            "default": 1,
            "title": "Orb Approaching",
            "type": "number"
          },
          "orb_separating": {
            "default": 1,
            "title": "Orb Separating",
            "type": "number"
          },
          "planet_distance": {
            "default": 0,
            "title": "Planet Distance",
            "type": "number"
          },
          "planet_id": {
            "title": "Planet Id",
            "type": "integer"
          },
          "planet_latitude": {
            "default": 0,
            "title": "Planet Latitude",
            "type": "number"
          },
          "planet_longitude": {
            "default": 0,
            "title": "Planet Longitude",
            "type": "number"
          },
          "planet_name": {
            "title": "Planet Name",
            "type": "string"
          },
          "previous_crossing": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              }
            ],
            "title": "Previous Crossing"
          },
          "retrograde_status": {
            "allOf": [
              {
                "$ref": "#/components/schemas/RetrogradeStatus"
              }
            ],
            "default": "direct"
          },
          "search_iterations": {
            "default": 0,
            "title": "Search Iterations",
            "type": "integer"
          },
          "separation_duration": {
            "default": 0,
            "title": "Separation Duration",
            "type": "number"
          },
          "target_longitude": {
            "title": "Target Longitude",
            "type": "number"
          },
          "total_crossings": {
            "default": 1,
            "title": "Total Crossings",
            "type": "integer"
          },
          "total_influence_duration": {
            "default": 0,
            "title": "Total Influence Duration",
            "type": "number"
          },
          "transit_speed": {
            "default": 0,
            "title": "Transit Speed",
            "type": "number"
          },
          "transit_type": {
            "allOf": [
              {
                "$ref": "#/components/schemas/TransitType"
              }
            ],
            "default": "longitude_degree"
          },
          "zodiac_degree": {
            "default": 0,
            "title": "Zodiac Degree",
            "type": "integer"
          },
          "zodiac_minute": {
            "default": 0,
            "title": "Zodiac Minute",
            "type": "integer"
          },
          "zodiac_sign": {
            "default": "",
            "title": "Zodiac Sign",
            "type": "string"
          }
        },
        "required": [
          "planet_id",
          "planet_name",
          "target_longitude",
          "exact_time"
        ],
        "title": "Transit",
        "type": "object"
      },
      "TransitSearchRequest": {
        "additionalProperties": false,
        "description": "Request schema for general transit search.",
        "example": {
          "end_date": "2025-01-01T00:00:00Z",
          "planet_names": [
            "Mars",
            "Jupiter"
          ],
          "start_date": "2024-01-01T00:00:00Z",
          "target_degrees": [
            0,
            90,
            180,
            270
          ]
        },
        "properties": {
          "end_date": {
            "description": "Search range end date",
            "format": "date-time",
            "title": "End Date",
            "type": "string"
          },
          "planet_names": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              }
            ],
            "description": "Planets to include (validated in route)",
            "title": "Planet Names"
          },
          "search_criteria": {
            "anyOf": [
              {
                "type": "object"
              }
            ],
            "description": "Additional search criteria (currently not supported by the route; omit it)",
            "title": "Search Criteria"
          },
          "start_date": {
            "description": "Search range start date",
            "format": "date-time",
            "title": "Start Date",
            "type": "string"
          },
          "target_degrees": {
            "anyOf": [
              {
                "items": {
                  "type": "number"
                },
                "type": "array"
              }
            ],
            "description": "Specific degrees to search for",
            "title": "Target Degrees"
          }
        },
        "required": [
          "start_date",
          "end_date"
        ],
        "title": "TransitSearchRequest",
        "type": "object"
      },
      "TransitSearchResponse": {
        "description": "Response schema for general transit search.",
        "properties": {
          "calculation_metadata": {
            "$ref": "#/components/schemas/CalculationMetadata",
            "description": "Standardized calculation metadata describing the transit search"
          },
          "metadata": {
            "allOf": [
              {
                "$ref": "#/components/schemas/PredictiveMetadata"
              }
            ],
            "description": "Calculation metadata"
          },
          "results": {
            "description": "Search results organized by criteria",
            "title": "Results",
            "type": "object"
          },
          "search_range_years": {
            "description": "Years searched",
            "title": "Search Range Years",
            "type": "number"
          },
          "success": {
            "description": "Request success status",
            "title": "Success",
            "type": "boolean"
          }
        },
        "required": [
          "success",
          "results",
          "search_range_years",
          "metadata"
        ],
        "title": "TransitSearchResponse",
        "type": "object"
      },
      "TransitType": {
        "description": "Transit calculation types.",
        "enum": [
          "longitude_degree",
          "sign_ingress",
          "aspect_transit",
          "return_transit"
        ],
        "title": "TransitType",
        "type": "string"
      },
      "UncertaintyInfo": {
        "properties": {
          "confidence": {
            "$ref": "#/components/schemas/ConfidenceLevel"
          },
          "delta_t_uncertainty_seconds": {
            "title": "Delta T Uncertainty Seconds",
            "type": "number"
          },
          "path_uncertainty_km": {
            "anyOf": [
              {
                "type": "number"
              }
            ],
            "title": "Path Uncertainty Km"
          },
          "timing_uncertainty": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "title": "Timing Uncertainty"
          }
        },
        "required": [
          "confidence",
          "delta_t_uncertainty_seconds"
        ],
        "title": "UncertaintyInfo",
        "type": "object"
      },
      "UpdateAPIKeyRequest": {
        "description": "Request to update an existing API key's metadata.",
        "properties": {
          "name": {
            "anyOf": [
              {
                "maxLength": 100,
                "minLength": 1,
                "type": "string"
              }
            ],
            "description": "New descriptive name",
            "title": "Name"
          }
        },
        "title": "UpdateAPIKeyRequest",
        "type": "object"
      },
      "UpdateApiKeyOverageSettingsRequest": {
        "properties": {
          "currency": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Currency code (currently USD only).",
            "example": "USD",
            "title": "Currency"
          },
          "hard_stop_on_cap": {
            "anyOf": [
              {
                "type": "boolean"
              }
            ],
            "default": true,
            "description": "If true, requests hard-stop when the overage cap is reached.",
            "title": "Hard Stop On Cap"
          },
          "monthly_overage_cap_cents": {
            "anyOf": [
              {
                "minimum": 0,
                "type": "integer"
              }
            ],
            "description": "Monthly overage spend cap in cents. Required when enabling overages.",
            "title": "Monthly Overage Cap Cents"
          },
          "overages_enabled": {
            "description": "Whether overages are enabled for this API key.",
            "title": "Overages Enabled",
            "type": "boolean"
          }
        },
        "required": [
          "overages_enabled"
        ],
        "title": "UpdateApiKeyOverageSettingsRequest",
        "type": "object"
      },
      "UpdateBillingOveragesRequest": {
        "properties": {
          "overage_spend_cap_cents": {
            "anyOf": [
              {
                "minimum": 0,
                "type": "integer"
              }
            ],
            "description": "Monthly overage spend cap in cents. Required when enabling; null disables.",
            "title": "Overage Spend Cap Cents"
          },
          "overages_enabled": {
            "description": "Whether overages are enabled for this account's API keys.",
            "title": "Overages Enabled",
            "type": "boolean"
          }
        },
        "required": [
          "overages_enabled"
        ],
        "title": "UpdateBillingOveragesRequest",
        "type": "object"
      },
      "UsageUnitWeightsResponse": {
        "properties": {
          "categories": {
            "items": {
              "type": "string"
            },
            "title": "Categories",
            "type": "array"
          },
          "weights": {
            "additionalProperties": {
              "type": "integer"
            },
            "title": "Weights",
            "type": "object"
          }
        },
        "title": "UsageUnitWeightsResponse",
        "type": "object"
      },
      "ValidationError": {
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "integer"
                }
              ]
            },
            "title": "Location",
            "type": "array"
          },
          "msg": {
            "title": "Message",
            "type": "string"
          },
          "type": {
            "title": "Error Type",
            "type": "string"
          }
        },
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError",
        "type": "object"
      },
      "ValidationProfileEnum": {
        "description": "Validation profiles describing accuracy/performance trade-offs.",
        "enum": [
          "strict_precision",
          "balanced_default",
          "performance_optimized"
        ],
        "title": "ValidationProfileEnum",
        "type": "string"
      },
      "VedicChartRequest": {
        "description": "Request body for a Vedic natal chart.",
        "properties": {
          "ayanamsa": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "default": "lahiri",
            "description": "Ayanamsa system for tropical-to-sidereal conversion. Supported: lahiri (default), fagan_bradley, krishnamurti.",
            "example": "lahiri",
            "title": "Ayanamsa"
          },
          "datetime_utc": {
            "description": "Birth date-time in ISO 8601 UTC format. Example: '1990-01-15T08:30:00'",
            "example": "1990-01-15T08:30:00",
            "title": "Datetime Utc",
            "type": "string"
          },
          "include_visual": {
            "description": "When true, renders an inline South Indian Rashi grid SVG alongside the chart.",
            "type": "boolean"
          },
          "latitude": {
            "description": "Birth latitude in decimal degrees (north positive).",
            "example": 28.6139,
            "maximum": 90,
            "minimum": -90,
            "title": "Latitude",
            "type": "number"
          },
          "longitude": {
            "description": "Birth longitude in decimal degrees (east positive).",
            "example": 77.209,
            "maximum": 180,
            "minimum": -180,
            "title": "Longitude",
            "type": "number"
          },
          "visual_config": {
            "$ref": "#/components/schemas/VisualRenderConfig"
          }
        },
        "required": [
          "datetime_utc",
          "latitude",
          "longitude"
        ],
        "title": "VedicChartRequest",
        "type": "object"
      },
      "VedicChartResponse": {
        "description": "Full Vedic natal chart response.",
        "properties": {
          "metadata": {
            "title": "Metadata",
            "type": "object"
          },
          "planets": {
            "items": {
              "$ref": "#/components/schemas/VedicPlanetPosition"
            },
            "title": "Planets",
            "type": "array"
          },
          "success": {
            "default": true,
            "title": "Success",
            "type": "boolean"
          },
          "visual": {
            "$ref": "#/components/schemas/VisualResult"
          }
        },
        "required": [
          "planets",
          "metadata"
        ],
        "title": "VedicChartResponse",
        "type": "object"
      },
      "VedicPlanetPosition": {
        "description": "A single planet's Vedic chart data.",
        "properties": {
          "nakshatra": {
            "$ref": "#/components/schemas/NakshatraDetail"
          },
          "navamsa_sign": {
            "description": "Navamsa (D-9) sign placement",
            "title": "Navamsa Sign",
            "type": "string"
          },
          "planet": {
            "title": "Planet",
            "type": "string"
          },
          "rashi": {
            "description": "Vedic sign name (Sanskrit)",
            "title": "Rashi",
            "type": "string"
          },
          "rashi_degree": {
            "description": "Degree within the rashi (0–30)",
            "title": "Rashi Degree",
            "type": "number"
          },
          "rashi_element": {
            "title": "Rashi Element",
            "type": "string"
          },
          "rashi_western": {
            "description": "Western sign name equivalent",
            "title": "Rashi Western",
            "type": "string"
          },
          "sidereal_longitude": {
            "title": "Sidereal Longitude",
            "type": "number"
          },
          "tropical_longitude": {
            "title": "Tropical Longitude",
            "type": "number"
          }
        },
        "required": [
          "planet",
          "tropical_longitude",
          "sidereal_longitude",
          "rashi",
          "rashi_western",
          "rashi_degree",
          "rashi_element",
          "nakshatra",
          "navamsa_sign"
        ],
        "title": "VedicPlanetPosition",
        "type": "object"
      },
      "VenusConjunctionsResponse": {
        "description": "Success response containing Venus-Sun conjunctions over a range.",
        "properties": {
          "calculation_metadata": {
            "allOf": [
              {
                "$ref": "#/components/schemas/CalculationMetadata"
              }
            ],
            "description": "Execution timing and precision metadata"
          },
          "conjunctions": {
            "description": "List of conjunction events found in range",
            "items": {
              "$ref": "#/components/schemas/ConjunctionEvent"
            },
            "title": "Conjunctions",
            "type": "array"
          },
          "success": {
            "default": true,
            "description": "Status of the calculation",
            "title": "Success",
            "type": "boolean"
          }
        },
        "required": [
          "conjunctions",
          "calculation_metadata"
        ],
        "title": "VenusConjunctionsResponse",
        "type": "object"
      },
      "VenusDateRequest": {
        "description": "Request for computing Venus events at a specific time.",
        "properties": {
          "date": {
            "description": "ISO-8601 date or datetime",
            "title": "Date",
            "type": "string"
          }
        },
        "required": [
          "date"
        ],
        "title": "VenusDateRequest",
        "type": "object"
      },
      "VenusEightYearStarResponse": {
        "description": "Success response containing the 5-point Venus Star pattern.",
        "properties": {
          "calculation_metadata": {
            "allOf": [
              {
                "$ref": "#/components/schemas/CalculationMetadata"
              }
            ],
            "description": "Execution timing and precision metadata"
          },
          "success": {
            "default": true,
            "description": "Status of the calculation",
            "title": "Success",
            "type": "boolean"
          },
          "vertices": {
            "description": "The 5 conjunctions forming the current pentagram",
            "items": {
              "$ref": "#/components/schemas/ConjunctionEvent"
            },
            "title": "Vertices",
            "type": "array"
          }
        },
        "required": [
          "vertices",
          "calculation_metadata"
        ],
        "title": "VenusEightYearStarResponse",
        "type": "object"
      },
      "VenusElongation": {
        "description": "Details of a Venus greatest elongation event.",
        "properties": {
          "elongation_type": {
            "description": "Direction of elongation",
            "enum": [
              "greatest_eastern",
              "greatest_western"
            ],
            "title": "Elongation Type",
            "type": "string"
          },
          "julian_day": {
            "description": "Julian Day of the event",
            "format": "double",
            "title": "Julian Day",
            "type": "number"
          },
          "longitude": {
            "description": "Zodiac longitude of Venus at max elongation",
            "title": "Longitude",
            "type": "number"
          },
          "separation": {
            "description": "Maximum angular separation from the Sun in degrees",
            "title": "Separation",
            "type": "number"
          },
          "sign": {
            "description": "Zodiac sign name",
            "title": "Sign",
            "type": "string"
          },
          "timestamp": {
            "description": "ISO-8601 timestamp",
            "title": "Timestamp",
            "type": "string"
          },
          "visibility": {
            "description": "Venus visibility phase",
            "enum": [
              "morning_star",
              "evening_star"
            ],
            "title": "Visibility",
            "type": "string"
          }
        },
        "required": [
          "elongation_type",
          "separation",
          "longitude",
          "julian_day",
          "timestamp",
          "sign",
          "visibility"
        ],
        "title": "VenusElongation",
        "type": "object"
      },
      "VenusElongationsResponse": {
        "description": "Success response containing Venus greatest elongations over a range.",
        "properties": {
          "calculation_metadata": {
            "allOf": [
              {
                "$ref": "#/components/schemas/CalculationMetadata"
              }
            ],
            "description": "Execution timing and precision metadata"
          },
          "elongations": {
            "description": "List of greatest elongations found in range",
            "items": {
              "$ref": "#/components/schemas/VenusElongation"
            },
            "title": "Elongations",
            "type": "array"
          },
          "success": {
            "default": true,
            "description": "Status of the calculation",
            "title": "Success",
            "type": "boolean"
          }
        },
        "required": [
          "elongations",
          "calculation_metadata"
        ],
        "title": "VenusElongationsResponse",
        "type": "object"
      },
      "VenusPhaseDetails": {
        "description": "Current phase and visibility details for Venus.",
        "properties": {
          "is_cazimi": {
            "description": "True if within 17 arc minutes of Sun",
            "title": "Is Cazimi",
            "type": "boolean"
          },
          "is_retrograde": {
            "description": "True if Venus is moving retrograde",
            "title": "Is Retrograde",
            "type": "boolean"
          },
          "julian_day": {
            "description": "Julian Day of calculation",
            "format": "double",
            "title": "Julian Day",
            "type": "number"
          },
          "longitude": {
            "description": "Venus zodiac longitude",
            "title": "Longitude",
            "type": "number"
          },
          "next_event": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Next major synodic event (e.g. 'Station Direct', 'Superior Conjunction')",
            "title": "Next Event"
          },
          "phase": {
            "description": "Phase name (e.g. Scimitar, Evening Star, Interior Conjunction)",
            "title": "Phase",
            "type": "string"
          },
          "separation": {
            "description": "Angular separation from Sun",
            "title": "Separation",
            "type": "number"
          },
          "sun_longitude": {
            "description": "Sun zodiac longitude",
            "title": "Sun Longitude",
            "type": "number"
          },
          "timestamp": {
            "description": "ISO-8601 timestamp of calculation",
            "title": "Timestamp",
            "type": "string"
          },
          "visibility": {
            "description": "Visibility status",
            "enum": [
              "morning_star",
              "evening_star",
              "combust",
              "under_beams"
            ],
            "title": "Visibility",
            "type": "string"
          }
        },
        "required": [
          "timestamp",
          "julian_day",
          "longitude",
          "sun_longitude",
          "separation",
          "phase",
          "visibility",
          "is_retrograde",
          "is_cazimi"
        ],
        "title": "VenusPhaseDetails",
        "type": "object"
      },
      "VenusPhaseResponse": {
        "description": "Success response containing current Venus phase information.",
        "properties": {
          "calculation_metadata": {
            "allOf": [
              {
                "$ref": "#/components/schemas/CalculationMetadata"
              }
            ],
            "description": "Execution timing and precision metadata"
          },
          "phase_details": {
            "allOf": [
              {
                "$ref": "#/components/schemas/VenusPhaseDetails"
              }
            ],
            "description": "Detailed phase and visibility data"
          },
          "success": {
            "default": true,
            "description": "Status of the calculation",
            "title": "Success",
            "type": "boolean"
          }
        },
        "required": [
          "phase_details",
          "calculation_metadata"
        ],
        "title": "VenusPhaseResponse",
        "type": "object"
      },
      "VenusRangeRequest": {
        "description": "Request for computing Venus events over a time range.",
        "properties": {
          "beams_orb": {
            "default": 17,
            "description": "Orb for under beams (default 17 degrees)",
            "title": "Beams Orb",
            "type": "number"
          },
          "combust_orb": {
            "default": 8.5,
            "description": "Orb for combustion (default 8.5 degrees)",
            "title": "Combust Orb",
            "type": "number"
          },
          "end_date": {
            "description": "ISO-8601 end date",
            "title": "End Date",
            "type": "string"
          },
          "start_date": {
            "description": "ISO-8601 start date",
            "title": "Start Date",
            "type": "string"
          }
        },
        "required": [
          "start_date",
          "end_date"
        ],
        "title": "VenusRangeRequest",
        "type": "object"
      },
      "VenusStarPointsRequest": {
        "description": "Request for computing Venus Star Points around a birth date.",
        "properties": {
          "beams_orb": {
            "default": 17,
            "description": "Orb for under beams (default 17 degrees)",
            "title": "Beams Orb",
            "type": "number"
          },
          "combust_orb": {
            "default": 8.5,
            "description": "Orb for combustion (default 8.5 degrees)",
            "title": "Combust Orb",
            "type": "number"
          },
          "exact_threshold": {
            "default": 0.0166,
            "description": "Threshold for 'exact' flag in degrees (default 1 arc min)",
            "title": "Exact Threshold",
            "type": "number"
          },
          "subject": {
            "allOf": [
              {
                "$ref": "#/components/schemas/SubjectRequest"
              }
            ],
            "description": "Birth data (date, time, location)"
          }
        },
        "required": [
          "subject"
        ],
        "title": "VenusStarPointsRequest",
        "type": "object"
      },
      "VenusStarPointsResponse": {
        "description": "Success response containing Venus Star Points and metadata.",
        "properties": {
          "calculation_metadata": {
            "allOf": [
              {
                "$ref": "#/components/schemas/CalculationMetadata"
              }
            ],
            "description": "Execution timing and precision metadata"
          },
          "star_points": {
            "description": "The five Venus Star Points (3 pre-birth, 2 post-birth)",
            "items": {
              "$ref": "#/components/schemas/ConjunctionEvent"
            },
            "title": "Star Points",
            "type": "array"
          },
          "success": {
            "default": true,
            "description": "Status of the calculation",
            "title": "Success",
            "type": "boolean"
          }
        },
        "required": [
          "star_points",
          "calculation_metadata"
        ],
        "title": "VenusStarPointsResponse",
        "type": "object"
      },
      "VenusStation": {
        "description": "Details of a Venus station (Retrograde or Direct).",
        "properties": {
          "element": {
            "description": "Zodiac element",
            "title": "Element",
            "type": "string"
          },
          "julian_day": {
            "description": "Julian Day of the exact station",
            "format": "double",
            "title": "Julian Day",
            "type": "number"
          },
          "longitude": {
            "description": "Zodiac longitude of the station",
            "title": "Longitude",
            "type": "number"
          },
          "modality": {
            "description": "Zodiac modality",
            "title": "Modality",
            "type": "string"
          },
          "sign": {
            "description": "Zodiac sign name",
            "title": "Sign",
            "type": "string"
          },
          "station_type": {
            "description": "Direction change type",
            "enum": [
              "retrograde",
              "direct"
            ],
            "title": "Station Type",
            "type": "string"
          },
          "timestamp": {
            "description": "ISO-8601 timestamp of the station",
            "title": "Timestamp",
            "type": "string"
          },
          "venus_dignity": {
            "description": "Venus's essential dignity",
            "title": "Venus Dignity",
            "type": "string"
          }
        },
        "required": [
          "station_type",
          "longitude",
          "julian_day",
          "timestamp",
          "sign",
          "element",
          "modality",
          "venus_dignity"
        ],
        "title": "VenusStation",
        "type": "object"
      },
      "VenusStationsResponse": {
        "description": "Success response containing Venus station points over a range.",
        "properties": {
          "calculation_metadata": {
            "allOf": [
              {
                "$ref": "#/components/schemas/CalculationMetadata"
              }
            ],
            "description": "Execution timing and precision metadata"
          },
          "stations": {
            "description": "List of stationary points found in range",
            "items": {
              "$ref": "#/components/schemas/VenusStation"
            },
            "title": "Stations",
            "type": "array"
          },
          "success": {
            "default": true,
            "description": "Status of the calculation",
            "title": "Success",
            "type": "boolean"
          }
        },
        "required": [
          "stations",
          "calculation_metadata"
        ],
        "title": "VenusStationsResponse",
        "type": "object"
      },
      "VisualRenderConfig": {
        "additionalProperties": false,
        "description": "Optional rendering preferences for inline chart visuals.",
        "properties": {
          "format": {
            "default": "svg",
            "description": "Output encoding: \"svg\" (default) or \"png\". PNG requires resvg on the server.",
            "enum": [
              "svg",
              "png"
            ],
            "title": "Format",
            "type": "string"
          },
          "size": {
            "default": 800,
            "description": "Canvas pixel dimension. Range [200, 4000]. Default 800.",
            "maximum": 4000,
            "minimum": 200,
            "title": "Size",
            "type": "integer"
          },
          "theme": {
            "default": "light",
            "description": "Colour palette: \"light\" (default) or \"dark\".",
            "enum": [
              "light",
              "dark"
            ],
            "title": "Theme",
            "type": "string"
          }
        },
        "title": "VisualRenderConfig",
        "type": "object"
      },
      "VisualResult": {
        "description": "Embedded diagram payload returned alongside chart data when include_visual=true.",
        "properties": {
          "content_type": {
            "description": "MIME type of the data payload.",
            "title": "Content Type",
            "type": "string"
          },
          "credits_charged": {
            "description": "Additional credits consumed to render the visual (always 2).",
            "title": "Credits Charged",
            "type": "integer"
          },
          "data": {
            "description": "Raw SVG string (format=svg) or standard base64-encoded PNG bytes (format=png, no data: URI prefix).",
            "title": "Data",
            "type": "string"
          },
          "format": {
            "description": "Output format: \"svg\" or \"png\".",
            "title": "Format",
            "type": "string"
          },
          "type": {
            "description": "Diagram kind: \"wheel\" or \"bodygraph\".",
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "type",
          "format",
          "content_type",
          "credits_charged",
          "data"
        ],
        "title": "VisualResult",
        "type": "object"
      },
      "VoCData": {
        "properties": {
          "active": {
            "description": "True if currently void of course",
            "title": "Active",
            "type": "boolean"
          },
          "last_aspect": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Last major aspect before ingress",
            "title": "Last Aspect"
          },
          "last_aspect_jd": {
            "anyOf": [
              {
                "format": "double",
                "type": "number"
              }
            ],
            "description": "Julian Day of the last major aspect",
            "title": "Last Aspect Jd"
          },
          "moon_sign": {
            "description": "Current moon sign",
            "title": "Moon Sign",
            "type": "string"
          },
          "next_sign": {
            "description": "Next moon sign",
            "title": "Next Sign",
            "type": "string"
          },
          "void_end_jd": {
            "description": "Void end Julian Day",
            "format": "double",
            "title": "Void End Jd",
            "type": "number"
          },
          "void_start_jd": {
            "description": "Void start Julian Day",
            "format": "double",
            "title": "Void Start Jd",
            "type": "number"
          }
        },
        "required": [
          "active",
          "void_start_jd",
          "void_end_jd",
          "moon_sign",
          "next_sign"
        ],
        "title": "VoCData",
        "type": "object"
      },
      "VoidOfCourseResponse": {
        "additionalProperties": false,
        "description": "Calculated Void of Course window for the Moon, detailing the last major planetary aspect before its ingress into the next zodiac sign.",
        "example": {
          "current_sign": "Gemini",
          "is_void": true,
          "last_aspect": {
            "aspect_type": "sextile",
            "planet": "Venus",
            "time": "2025-12-11T14:32:00+00:00"
          },
          "metadata": {
            "cache_hit": false,
            "calculation_time_ms": 25.3
          },
          "next_sign": "Cancer",
          "success": true,
          "void_end": "2025-12-11T18:45:00+00:00",
          "void_start": "2025-12-11T14:32:00+00:00"
        },
        "properties": {
          "current_sign": {
            "description": "Moon's current zodiac sign",
            "title": "Current Sign",
            "type": "string"
          },
          "is_void": {
            "description": "True if Moon is currently Void of Course",
            "title": "Is Void",
            "type": "boolean"
          },
          "last_aspect": {
            "anyOf": [
              {
                "type": "object"
              }
            ],
            "description": "Last major aspect before ingress (COQTS: conjunction, opposition, square, trine, sextile)",
            "title": "Last Aspect"
          },
          "metadata": {
            "description": "Calculation metadata (calculation_time_ms, cache_hit)",
            "title": "Metadata",
            "type": "object"
          },
          "next_sign": {
            "description": "Next zodiac sign Moon will enter",
            "title": "Next Sign",
            "type": "string"
          },
          "success": {
            "default": true,
            "description": "Calculation success status",
            "title": "Success",
            "type": "boolean"
          },
          "void_end": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              }
            ],
            "description": "VoC period end (next sign ingress time)",
            "title": "Void End"
          },
          "void_start": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              }
            ],
            "description": "VoC period start (last aspect time or previous ingress if no aspects)",
            "title": "Void Start"
          }
        },
        "required": [
          "is_void",
          "current_sign",
          "next_sign",
          "metadata"
        ],
        "title": "VoidOfCourseResponse",
        "type": "object"
      },
      "WheelHouses": {
        "additionalProperties": false,
        "description": "House geometry for a precomputed wheel ring. Required for the inner/single ring to draw houses and anchor orientation; the outer overlay ring does not require it.",
        "properties": {
          "ascendant": {
            "description": "Ascendant in degrees [0, 360). Used for ASC-pinned orientation.",
            "maximum": 360,
            "minimum": 0,
            "title": "Ascendant",
            "type": "number"
          },
          "cusps": {
            "description": "12 absolute-degree house cusps.",
            "items": {
              "maximum": 360,
              "minimum": 0,
              "type": "number"
            },
            "maxItems": 12,
            "minItems": 12,
            "title": "Cusps",
            "type": "array"
          },
          "house_system": {
            "description": "House system code label (e.g. 'P').",
            "title": "House System",
            "type": "string"
          },
          "midheaven": {
            "description": "Midheaven in degrees [0, 360).",
            "maximum": 360,
            "minimum": 0,
            "title": "Midheaven",
            "type": "number"
          }
        },
        "required": [
          "cusps",
          "ascendant"
        ],
        "title": "WheelHouses",
        "type": "object"
      },
      "WheelSubject": {
        "additionalProperties": false,
        "description": "A wheel ring subject. Supply EITHER birth params (birth_datetime + birth_location, cast internally) OR a precomputed 'positions' array (rendered directly). When 'positions' is present, birth params are ignored for that subject.",
        "properties": {
          "birth_datetime": {
            "allOf": [
              {
                "$ref": "#/components/schemas/DateTimeInput"
              }
            ],
            "description": "Birth date and time. Ignored when 'positions' is supplied."
          },
          "birth_location": {
            "allOf": [
              {
                "$ref": "#/components/schemas/BirthLocation"
              }
            ],
            "description": "Birth location. Ignored when 'positions' is supplied."
          },
          "houses": {
            "allOf": [
              {
                "$ref": "#/components/schemas/WheelHouses"
              }
            ],
            "description": "Optional house geometry for a positions ring (inner/single ring)."
          },
          "name": {
            "description": "Optional display label for the ring.",
            "maxLength": 120,
            "minLength": 1,
            "title": "Name",
            "type": "string"
          },
          "positions": {
            "description": "Precomputed body positions. When present, the ring is rendered from these longitudes and birth params are ignored.",
            "items": {
              "$ref": "#/components/schemas/PositionInput"
            },
            "title": "Positions",
            "type": "array"
          }
        },
        "title": "WheelSubject",
        "type": "object"
      },
      "ZodiacResponse": {
        "description": "Chinese zodiac animal + element response.",
        "properties": {
          "animal": {
            "title": "Animal",
            "type": "string"
          },
          "branch": {
            "additionalProperties": {
              "type": "string"
            },
            "description": "Year's Earthly Branch",
            "title": "Branch",
            "type": "object"
          },
          "element": {
            "title": "Element",
            "type": "string"
          },
          "polarity": {
            "description": "Yin or Yang",
            "title": "Polarity",
            "type": "string"
          },
          "stem": {
            "additionalProperties": {
              "type": "string"
            },
            "description": "Year's Heavenly Stem",
            "title": "Stem",
            "type": "object"
          },
          "success": {
            "default": true,
            "title": "Success",
            "type": "boolean"
          },
          "year": {
            "title": "Year",
            "type": "integer"
          }
        },
        "required": [
          "year",
          "animal",
          "element",
          "polarity",
          "stem",
          "branch"
        ],
        "title": "ZodiacResponse",
        "type": "object"
      },
      "ZodiacSignEnum": {
        "description": "Zodiac signs for ingress calculations.",
        "enum": [
          "Aries",
          "Taurus",
          "Gemini",
          "Cancer",
          "Leo",
          "Virgo",
          "Libra",
          "Scorpio",
          "Sagittarius",
          "Capricorn",
          "Aquarius",
          "Pisces"
        ],
        "title": "ZodiacSignEnum",
        "type": "string"
      },
      "ZodiacTypeEnum": {
        "description": "Supported zodiac frameworks.",
        "enum": [
          "tropical",
          "sidereal"
        ],
        "title": "ZodiacTypeEnum",
        "type": "string"
      },
      "ZodiacalReleasingRequest": {
        "description": "Input for zodiacal releasing calculation. Requires the zodiac sign of the releasing Lot (0 = Aries … 11 = Pisces), the Lot name (fortune or spirit), and the birth datetime.",
        "properties": {
          "birth_datetime": {
            "description": "Natal birth datetime in ISO 8601 UTC format.",
            "format": "date-time",
            "title": "Birth Datetime",
            "type": "string"
          },
          "house_system": {
            "description": "Optional.",
            "type": "string"
          },
          "latitude": {
            "description": "Optional. If provided, calculates natal chart to determine ascendant/sect/lots.",
            "maximum": 90,
            "minimum": -90,
            "type": "number"
          },
          "longitude": {
            "description": "Optional.",
            "maximum": 180,
            "minimum": -180,
            "type": "number"
          },
          "lot_name": {
            "description": "Which Lot to release from. 'fortune' for body/health chapters, 'spirit' for career/action chapters.",
            "enum": [
              "fortune",
              "spirit"
            ],
            "title": "Lot Name",
            "type": "string"
          },
          "lot_sign": {
            "description": "Zodiac sign of the releasing Lot (0 = Aries, 1 = Taurus, … 11 = Pisces).",
            "maximum": 11,
            "minimum": 0,
            "title": "Lot Sign",
            "type": "integer"
          },
          "max_years": {
            "anyOf": [
              {
                "maximum": 200,
                "minimum": 1,
                "type": "integer"
              }
            ],
            "default": 100,
            "description": "Maximum number of years for the releasing timeline. Default: 100.",
            "title": "Max Years"
          },
          "target_datetime": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              }
            ],
            "description": "Date to highlight the active period for. Defaults to the current date if omitted.",
            "title": "Target Datetime"
          }
        },
        "required": [
          "lot_sign",
          "lot_name",
          "birth_datetime"
        ],
        "title": "ZodiacalReleasingRequest",
        "type": "object"
      },
      "ZodiacalReleasingResponse": {
        "description": "Zodiacal releasing timeline — L1 major periods with angular/loosing metadata, optional L2 sub-periods, and current-period identification.",
        "properties": {
          "calculation_metadata": {
            "description": "Metadata about the calculation.",
            "nullable": true,
            "properties": {
              "birth_datetime": {
                "type": "string"
              },
              "max_years": {
                "type": "integer"
              },
              "processing_time_ms": {
                "type": "number"
              },
              "target_datetime": {
                "nullable": true,
                "type": "string"
              }
            },
            "type": "object"
          },
          "current_period": {
            "description": "The L1 period active at the target datetime, if provided.",
            "nullable": true,
            "properties": {
              "is_angular": {
                "type": "boolean"
              },
              "is_loosing": {
                "type": "boolean"
              },
              "l1_index": {
                "description": "Index into l1_periods.",
                "type": "integer"
              },
              "months_into_period": {
                "description": "How many months into this L1 period the target date falls.",
                "type": "number"
              },
              "ruler": {
                "type": "string"
              },
              "sign_name": {
                "type": "string"
              }
            },
            "type": "object"
          },
          "l1_periods": {
            "description": "Level-1 major periods in the zodiacal releasing timeline.",
            "items": {
              "properties": {
                "end_month": {
                  "description": "Cumulative end month from birth.",
                  "type": "number"
                },
                "is_angular": {
                  "description": "Whether this sign is angular (1st, 4th, 7th, 10th) from the Lot. Angular periods are peak chapters.",
                  "type": "boolean"
                },
                "is_loosing": {
                  "description": "Whether this period's ruler is in a cadent sign from the Lot (loosing of the bond).",
                  "type": "boolean"
                },
                "l2_periods": {
                  "description": "Level-2 sub-periods within this L1 period.",
                  "items": {
                    "properties": {
                      "end_month": {
                        "type": "number"
                      },
                      "is_angular": {
                        "type": "boolean"
                      },
                      "months": {
                        "type": "number"
                      },
                      "ruler": {
                        "type": "string"
                      },
                      "sign": {
                        "type": "integer"
                      },
                      "sign_name": {
                        "type": "string"
                      },
                      "start_month": {
                        "type": "number"
                      }
                    },
                    "type": "object"
                  },
                  "nullable": true,
                  "type": "array"
                },
                "months": {
                  "description": "Duration of this period in months.",
                  "type": "number"
                },
                "ruler": {
                  "description": "Ruling planet name.",
                  "type": "string"
                },
                "sign": {
                  "description": "Sign index (0–11).",
                  "type": "integer"
                },
                "sign_name": {
                  "description": "Sign name.",
                  "type": "string"
                },
                "start_month": {
                  "description": "Cumulative start month from birth.",
                  "type": "number"
                }
              },
              "type": "object"
            },
            "title": "L1 Periods",
            "type": "array"
          },
          "lot_sign": {
            "description": "Sign index of the releasing Lot (0–11, API convention).",
            "type": "integer"
          },
          "lot_sign_name": {
            "description": "Name of the releasing Lot's sign (e.g., 'Leo').",
            "type": "string"
          },
          "output_mode": {
            "description": "Output projection mode (json | llm).",
            "nullable": true,
            "type": "string"
          },
          "peak_period_index": {
            "description": "Index of the longest angular L1 period (the peak chapter).",
            "type": "integer"
          },
          "starting_lot": {
            "description": "Name of the releasing Lot ('fortune' or 'spirit').",
            "type": "string"
          },
          "success": {
            "description": "Whether the calculation succeeded.",
            "title": "Success",
            "type": "boolean"
          },
          "total_months": {
            "description": "Total months covered by the releasing timeline.",
            "type": "number"
          }
        },
        "required": [
          "success",
          "starting_lot",
          "lot_sign",
          "lot_sign_name",
          "l1_periods",
          "total_months",
          "peak_period_index"
        ],
        "title": "ZodiacalReleasingResponse",
        "type": "object"
      },
      "app__api__models__predictive_schemas__ErrorResponse": {
        "description": "Standardized error response.",
        "properties": {
          "details": {
            "anyOf": [
              {
                "type": "object"
              }
            ],
            "description": "Additional error details",
            "title": "Details"
          },
          "error": {
            "description": "Error type identifier",
            "title": "Error",
            "type": "string"
          },
          "message": {
            "description": "Human-readable error message",
            "title": "Message",
            "type": "string"
          },
          "success": {
            "default": false,
            "description": "Request success status",
            "title": "Success",
            "type": "boolean"
          }
        },
        "required": [
          "error",
          "message"
        ],
        "title": "ErrorResponse",
        "type": "object"
      },
      "app__api__models__predictive_schemas__SolarReturnRequest": {
        "additionalProperties": false,
        "description": "Solar return timing request (body fixed to Sun).",
        "example": {
          "birth_datetime": {
            "iso": "1990-06-15T14:30:00Z"
          },
          "house_system": "P",
          "include_chart": true,
          "location": {
            "elevation": 10,
            "latitude": {
              "decimal": 40.7128
            },
            "longitude": {
              "decimal": -74.006
            },
            "timezone": {
              "iana_name": "UTC"
            }
          },
          "return_location": {
            "elevation": 71,
            "latitude": {
              "decimal": 34.0522
            },
            "longitude": {
              "decimal": -118.2437
            },
            "timezone": {
              "iana_name": "UTC"
            }
          },
          "search_window_days": 5,
          "target_datetime": {
            "iso": "2024-06-15T00:00:00Z"
          }
        },
        "properties": {
          "birth_datetime": {
            "allOf": [
              {
                "$ref": "#/components/schemas/DateTimeInput"
              }
            ],
            "description": "Birth date/time (ISO-8601, components, or Julian day)"
          },
          "enhanced_options": {
            "$ref": "#/components/schemas/EnhancedCalculationOptions",
            "description": "Optional enhanced calculation flags applied when include_chart=true and preset=simple or format=llm. This controls additional computed analysis blocks (e.g., Human Design gates, lunar phase, midpoints)."
          },
          "house_system": {
            "$ref": "#/components/schemas/HouseSystemEnum",
            "default": "P",
            "description": "House system for chart calculation (P=Placidus, K=Koch, W=Whole Sign, etc.)"
          },
          "include_chart": {
            "default": false,
            "description": "Include full chart at return moment",
            "title": "Include Chart",
            "type": "boolean"
          },
          "include_visual": {
            "default": false,
            "description": "If true, a full visual SVG or PNG output will be rendered and returned alongside the chart data. Note: Visuals incur a +2 credit surcharge.",
            "title": "Include Visual",
            "type": "boolean"
          },
          "location": {
            "$ref": "#/components/schemas/LocationInput",
            "description": "Location context (timezone + optional elevation)"
          },
          "return_location": {
            "$ref": "#/components/schemas/LocationInput",
            "description": "Optional location for the return chart (defaults to `location` if omitted)"
          },
          "search_window_days": {
            "anyOf": [
              {
                "maximum": 5000,
                "minimum": 1,
                "type": "integer"
              }
            ],
            "description": "Days to search symmetrically around target datetime (defaults depend on body)",
            "title": "Search Window Days"
          },
          "target_datetime": {
            "allOf": [
              {
                "$ref": "#/components/schemas/DateTimeInput"
              }
            ],
            "description": "Target datetime to search around (ISO-8601, components, or Julian day)"
          },
          "visual_config": {
            "$ref": "#/components/schemas/VisualRenderConfig"
          }
        },
        "required": [
          "birth_datetime",
          "target_datetime"
        ],
        "title": "SolarReturnRequest",
        "type": "object"
      },
      "app__api__models__schemas__system__ErrorResponse": {
        "additionalProperties": false,
        "description": "Standardized error response.",
        "properties": {
          "debug_info": {
            "anyOf": [
              {
                "type": "object"
              }
            ],
            "description": "Debug information",
            "title": "Debug Info"
          },
          "details": {
            "anyOf": [
              {
                "type": "object"
              }
            ],
            "description": "Additional error details",
            "title": "Details"
          },
          "error": {
            "description": "Error type/category",
            "title": "Error",
            "type": "string"
          },
          "message": {
            "description": "Human-readable error message",
            "title": "Message",
            "type": "string"
          },
          "request_id": {
            "anyOf": [
              {
                "type": "string"
              }
            ],
            "description": "Request identifier",
            "title": "Request Id"
          },
          "success": {
            "default": false,
            "description": "Always false for errors",
            "title": "Success",
            "type": "boolean"
          },
          "timestamp": {
            "description": "Error timestamp",
            "format": "date-time",
            "title": "Timestamp",
            "type": "string"
          }
        },
        "required": [
          "error",
          "message",
          "timestamp"
        ],
        "title": "ErrorResponse",
        "type": "object"
      },
      "app__api__routes__human_design__OppositionRequest": {
        "description": "Request for a Human Design planetary opposition chart.",
        "properties": {
          "birth_datetime_utc": {
            "format": "date-time",
            "title": "Birth Datetime Utc",
            "type": "string"
          },
          "format": {
            "default": "json",
            "description": "Response format: json | llm.",
            "title": "Format",
            "type": "string"
          },
          "include_chiron": {
            "default": true,
            "description": "Include Chiron in the HD chart activations.",
            "title": "Include Chiron",
            "type": "boolean"
          },
          "include_lilith": {
            "default": false,
            "description": "Include Black Moon Lilith in the HD chart activations.",
            "title": "Include Lilith",
            "type": "boolean"
          },
          "include_visual": {
            "default": false,
            "description": "If true, a full visual SVG or PNG output will be rendered and returned alongside the chart data. Note: Visuals incur a +2 credit surcharge.",
            "title": "Include Visual",
            "type": "boolean"
          },
          "planet": {
            "description": "Planet to calculate the opposition for.",
            "enum": [
              "uranus",
              "saturn",
              "jupiter"
            ],
            "title": "Planet",
            "type": "string"
          },
          "target_year": {
            "description": "Year to search for the opposition near.",
            "title": "Target Year",
            "type": "integer"
          },
          "visual_config": {
            "$ref": "#/components/schemas/VisualRenderConfig"
          }
        },
        "required": [
          "birth_datetime_utc",
          "planet",
          "target_year"
        ],
        "title": "OppositionRequest",
        "type": "object"
      },
      "app__api__routes__human_design__PlanetaryReturnRequest": {
        "description": "Request for a Human Design planetary return chart.",
        "properties": {
          "birth_datetime_utc": {
            "format": "date-time",
            "title": "Birth Datetime Utc",
            "type": "string"
          },
          "format": {
            "default": "json",
            "description": "Response format: json | llm.",
            "title": "Format",
            "type": "string"
          },
          "include_chiron": {
            "default": true,
            "description": "Include Chiron in the HD chart activations.",
            "title": "Include Chiron",
            "type": "boolean"
          },
          "include_lilith": {
            "default": false,
            "description": "Include Black Moon Lilith in the HD chart activations.",
            "title": "Include Lilith",
            "type": "boolean"
          },
          "include_visual": {
            "default": false,
            "description": "If true, a full visual SVG or PNG output will be rendered and returned alongside the chart data. Note: Visuals incur a +2 credit surcharge.",
            "title": "Include Visual",
            "type": "boolean"
          },
          "planet": {
            "description": "Planet to calculate the return for.",
            "enum": [
              "sun",
              "moon",
              "mercury",
              "venus",
              "mars",
              "jupiter",
              "saturn",
              "uranus",
              "neptune",
              "pluto",
              "chiron",
              "pholus"
            ],
            "title": "Planet",
            "type": "string"
          },
          "return_year": {
            "description": "Year to search for the return near.",
            "title": "Return Year",
            "type": "integer"
          },
          "visual_config": {
            "$ref": "#/components/schemas/VisualRenderConfig"
          }
        },
        "required": [
          "birth_datetime_utc",
          "planet",
          "return_year"
        ],
        "title": "PlanetaryReturnRequest",
        "type": "object"
      },
      "app__api__routes__human_design__SolarReturnRequest": {
        "description": "Request for a Solar Return chart.",
        "properties": {
          "birth_datetime_utc": {
            "format": "date-time",
            "title": "Birth Datetime Utc",
            "type": "string"
          },
          "format": {
            "default": "json",
            "description": "Response format: json | llm.",
            "title": "Format",
            "type": "string"
          },
          "include_visual": {
            "default": false,
            "description": "If true, a full visual SVG or PNG output will be rendered and returned alongside the chart data. Note: Visuals incur a +2 credit surcharge.",
            "title": "Include Visual",
            "type": "boolean"
          },
          "node_mode": {
            "default": "True",
            "title": "Node Mode",
            "type": "string"
          },
          "return_year": {
            "title": "Return Year",
            "type": "integer"
          },
          "visual_config": {
            "$ref": "#/components/schemas/VisualRenderConfig"
          }
        },
        "required": [
          "birth_datetime_utc",
          "return_year"
        ],
        "title": "SolarReturnRequest",
        "type": "object"
      }
    },
    "securitySchemes": {
      "apiKeyAuth": {
        "in": "header",
        "name": "X-API-Key",
        "type": "apiKey"
      },
      "bearerAuth": {
        "bearerFormat": "JWT/API-Key",
        "scheme": "bearer",
        "type": "http"
      },
      "meridianApiKeyAuth": {
        "in": "header",
        "name": "X-OpenEphemeris-API-Key",
        "type": "apiKey"
      },
      "serviceKeyAuth": {
        "in": "header",
        "name": "X-Service-Key",
        "type": "apiKey"
      }
    }
  },
  "info": {
    "description": "\n        **OpenEphemeris Engine** - Professional Astrological Calculations\n\n        A high-performance REST API for precise astrological chart calculations using the SuperNOVAS / Calceph engine.\n        \n        ## Features\n\n        - 🎯 **Precise Calculations**: SuperNOVAS / Calceph backend (NASA DE440) for astronomical accuracy\n        - 🏗️ **Flexible Input Formats**: Support for multiple coordinate, datetime, and timezone formats\n        - 🏠 **Multiple House Systems**: Placidus, Koch, Equal House, Whole Sign, and more\n        - ⚡ **High Performance**: Parallel processing and intelligent caching\n        - 📊 **Comprehensive Data**: Complete natal charts with planets, houses, angles, and aspects\n        - 🔒 **Input Validation**: Robust validation with clear error messages\n        - 📖 **OpenAPI Documentation**: Interactive API documentation and schema validation\n        - 🪐 **Transit Calculations**: Precise planetary transit timing with retrograde support\n        - 📅 **Predictive Features**: Solar/lunar returns, sign ingresses, and future transits\n        - 🤖 **Agent-First Design**: Optimized for LLM consumption and autonomous tool use\n\n        ## Agent-First Design\n\n        OpenEphemeris is built from the ground up to be \"Agent-First\". This means:\n\n        1. **High Information Density**: We provide comprehensive metadata to minimize the need for external lookup.\n        2. **Optimized Projections**: The `format=llm` parameter converts raw astronomical data into a structure that LLMs can reason about more effectively, reducing token usage while preserving interpretive nuance.\n        3. **Deterministic Contract**: API responses are versioned and strictly typed to ensure reliable tool-calling for AI agents.\n\n        ### Output Modes (`format` parameter)\n\n        Endpoints supporting enhanced formatting accept a `format` query parameter:\n\n        - `format=json` (default): The full, raw response schema. Best for applications needing every decimal point of precision.\n        - `format=llm`: A token-optimized projection. It replaces complex nested objects with flattened, \"punchy\" descriptions that provide immediate context for an LLM (e.g., automatically including the sign name alongside the degree).\n\n        ## Authentication\n\n        OpenEphemeris supports several authentication modes:\n\n        1. **JWT tokens (end users)** via Supabase:\n\n             ```http\n             Authorization: Bearer \u003cjwt_token\u003e\n             ```\n\n        2. **User API keys (integrations)** via `X-OpenEphemeris-API-Key`, `X-API-Key`, or `Authorization: Bearer`:\n\n             ```http\n             X-OpenEphemeris-API-Key: opene-...\n             ```\n             or\n             ```http\n             Authorization: Bearer opene-...\n             ```\n\n             *Note: Use `X-OpenEphemeris-API-Key` if your infrastructure (e.g. AWS/Azure) intercepts the standard `X-API-Key` header.*\n\n        3. **Service API keys (internal services)** via `X-Service-Key` header:\n\n             ```http\n             X-Service-Key: \u003cservice_key\u003e\n             ```\n\n        Valid service keys are intended for trusted internal services and\n        bypass rate limits. User requests remain subject to tier-based\n        rate limiting and usage metering.\n\n        ## Supported Formats\n\n        ### Coordinates\n        - **Decimal degrees**: `40.7128, -74.0060`\n        - **DMS strings**: `\"40°42'46\"N\", \"74°00'22\"W\"`\n        - **Component objects**: `{\"degrees\": 40, \"minutes\": 42, \"seconds\": 46, \"direction\": \"N\"}`\n\n        ### DateTime\n        - **ISO 8601 strings**: `\"2000-01-01T12:00:00\"`, `\"2000-01-01T12:00:00-05:00\"`\n        - **Julian Day numbers**: `2451545.0`\n        - **Component objects**: `{\"year\": 2000, \"month\": 1, \"day\": 1, \"hour\": 12}`\n\n        ### Timezones\n        - **IANA names**: `\"America/New_York\"`, `\"Europe/London\"`\n        - **UTC offsets**: `-5.0`, `+1.0`\n        - **Auto-detection**: Based on coordinates\n\n        ## Usage Examples\n\n        Calculate a natal chart with basic decimal coordinates:\n        ```json\n        {\n            \"subject\": {\n                \"name\": \"John Doe\",\n                \"datetime\": {\"iso_string\": \"1990-06-15T14:30:00\"},\n                \"latitude\": {\"decimal\": 40.7128},\n                \"longitude\": {\"decimal\": -74.0060},\n                \"timezone\": {\"name\": \"America/New_York\"}\n            }\n        }\n        ```\n        ",
    "title": "OpenEphemeris API",
    "version": "1.0.0"
  },
  "openapi": "3.0.3",
  "paths": {
    "/": {
      "get": {
        "description": "Welcome endpoint with API information and links to documentation.",
        "operationId": "root__get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "title": "Response Root  Get",
                  "type": "object"
                }
              }
            },
            "description": "Successful Response"
          }
        },
        "security": [],
        "summary": "API Root",
        "tags": [
          "api-metadata"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 0
      }
    },
    "/acg/aspects": {
      "post": {
        "description": "Calculate strictly isolated ACG aspect lines. Options configurations to include power lines/midpoints will be explicitly stripped.",
        "operationId": "aspects_acg_aspects_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ACGRequestPayload"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "FeatureCollection response (`features` is always an array; may be empty)."
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Calculate Astrocartography Aspect Lines",
        "tags": [
          "ACG"
        ],
        "x-meridian-tier": "Scale",
        "x-meridian-units": 10
      }
    },
    "/acg/ccg": {
      "post": {
        "description": "Compute cyclocartography transit snapshots over a time window.",
        "operationId": "ccg_acg_ccg_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ACGCCGRequestPayload"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Cyclocartography Time-Series (Go Engine)",
        "tags": [
          "ACG"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Developer",
        "x-meridian-units": 10
      }
    },
    "/acg/ccg/parans": {
      "post": {
        "description": "Computes on-demand transit parans at a single epoch.",
        "operationId": "acg_ccg_parans_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/NatalParansRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            },
            "description": "FeatureCollection response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Transit Parans",
        "tags": [
          "ACG"
        ],
        "x-meridian-tier": "Scale",
        "x-meridian-units": 10
      }
    },
    "/acg/crossings": {
      "post": {
        "description": "Find exact geographic points where two ACG lines intersect.\n\nThis is a novel feature — no other public ACG API provides crossing\npoints as structured data. Returns GeoJSON Point features.\n\nResponse packaging is stable: `type=FeatureCollection`, `features` is always an array (possibly empty), and `crossing_count` matches the feature count.",
        "operationId": "crossings_acg_crossings_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ACGRequestPayload"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "FeatureCollection response (`features` is always an array; may be empty)."
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "ACG Line Crossing Points (Go Engine)",
        "tags": [
          "ACG"
        ],
        "x-meridian-tier": "Scale",
        "x-meridian-units": 10
      }
    },
    "/acg/datasets": {
      "get": {
        "description": "List available celestial body catalogs and aspect angles.",
        "operationId": "datasets_acg_datasets_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "Successful Response"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Available ACG Datasets",
        "tags": [
          "ACG"
        ],
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 0
      }
    },
    "/acg/declination-lines": {
      "post": {
        "description": "Compute declination parallel and contra-parallel latitude bands.\n\nA NOVEL feature — no other ACG tool maps declination parallels\ngeographically. Returns horizontal GeoJSON lines where two bodies\nshare (parallel) or oppose (contra-parallel) declination.\n\nCurrent endpoint contract uses a fixed 1.5° orb (DefaultDeclinationOrb). No `max_orb` query parameter is accepted on this route.",
        "operationId": "declination_lines_acg_declination_lines_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ACGRequestPayload"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "ACG Declination Parallel Lines (Go Engine)",
        "tags": [
          "ACG"
        ],
        "x-meridian-tier": "Scale",
        "x-meridian-units": 10
      }
    },
    "/acg/features": {
      "post": {
        "description": "Query ACG features as a GeoJSON FeatureCollection.",
        "operationId": "features_acg_features_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ACGRequestPayload"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "ACG Feature Collection (Go Engine)",
        "tags": [
          "ACG"
        ],
        "x-internal": true,
        "x-meridian-tier": "service",
        "x-meridian-units": 10
      }
    },
    "/acg/heatmap/composite": {
      "post": {
        "description": "Generates a global GeoJSON heatmap scoring relocation viability for a composite synastry chart (midpoint method).",
        "operationId": "AcgHeatmapCompositeAcgHeatmapCompositePost",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CompositeHeatmapRequestPayload"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "Successful Response (GeoJSON FeatureCollection)"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Calculate Composite Heatmap",
        "tags": [
          "Astrocartography"
        ],
        "x-internal": true
      }
    },
    "/acg/hermetic-lines": {
      "post": {
        "description": "Calculates Astrocartography (ACG) geometry exclusively for the seven classical Hermetic Lots (Lot of Fortune, Spirit, Eros, Necessity, Courage, Victory, and Nemesis).\n\n### Astrological \u0026 Mathematical Geometry\nHermetic Lots are sensitive mathematical points derived from the natal Ascendant and two planetary positions (e.g., Day Fortune = Ascendant + Moon − Sun). Unlike planets, their ecliptic longitude shifts with the observer's natal birthplace, so `natal.birthplace_lat` and `natal.birthplace_lon` are **required** fields for this endpoint.\n\nThe engine converts each lot's ecliptic longitude to equatorial coordinates (Right Ascension and Declination) using the standard ecliptic-to-equatorial transformation, then runs those coordinates through the same angular line generators used for all ACG bodies.\n\n### Line Types Returned\nAll four standard angular line types are returned for each lot:\n\n- **MC** — Meridian where the lot culminates (2-point vertical meridian)\n- **IC** — Anti-culmination meridian, 180° opposite the MC (2-point vertical meridian)\n- **AC** — Horizon curve where the lot's equivalent point rises (181-point sinusoidal arc)\n- **DC** — Horizon curve where the lot's equivalent point sets (181-point sinusoidal arc)\n\nUse the `options.line_types` field to restrict output to a subset (e.g., `[\"MC\", \"IC\"]`).\n\n### Sect Awareness\nSect (day/night chart) is determined from the Sun's actual altitude at the natal birthplace and time. The day and night formulas are applied accordingly — e.g., Fortune uses `ASC + Moon − Sun` for day charts and `ASC + Sun − Moon` for night charts.",
        "operationId": "HermeticLines_acg_hermetic_lines_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ACGRequestPayload"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "FeatureCollection response (`features` is always an array; may be empty)."
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Hermetic Lines",
        "tags": [
          "ACG"
        ],
        "x-meridian-tier": "Scale",
        "x-meridian-units": 10
      }
    },
    "/acg/hits": {
      "post": {
        "description": "Find ACG lines closest to a geographic location.\n\nSupports two modes:\n\n1. **Proximity mode** (recommended): Provide `query_lat` and `query_lon` in the request body to find lines near any arbitrary point. Optionally set `radius_deg` (default: 3.0, max: 90). Returns features sorted by distance (closest first) with `min_distance_deg` and `min_distance_km` in each feature's properties.\n\n2. **Birthplace fallback**: If `query_lat`/`query_lon` are omitted but `natal.birthplace_lat`/`natal.birthplace_lon` are present, those coordinates are used as the query location.\n\n3. **Unfiltered mode** (backward-compatible): If neither query location nor natal birthplace is provided, all computed features are returned unfiltered.\n\nNew request fields (all optional):\n- `query_lat` (float): Latitude of the query point (-90 to 90)\n- `query_lon` (float): Longitude of the query point (-180 to 180)\n- `radius_deg` (float): Proximity radius in degrees (1° ≈ 111 km). Default: 3.0",
        "operationId": "hits_acg_hits_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ACGRequestPayload"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "ACG Line Proximity Hits (Go Engine)",
        "tags": [
          "ACG"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Developer",
        "x-meridian-units": 10
      }
    },
    "/acg/local-space": {
      "post": {
        "description": "Compute local space azimuth/altitude lines from observer location.",
        "operationId": "local_space_acg_local_space_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ACGLocalSpaceRequestPayload"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Local Space Azimuth Lines (Go Engine)",
        "tags": [
          "ACG"
        ],
        "x-meridian-status": "beta",
        "x-meridian-tier": "Developer",
        "x-meridian-units": 10
      }
    },
    "/acg/meta": {
      "get": {
        "description": "ACG engine version, capabilities, and status.",
        "operationId": "meta_acg_meta_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "Successful Response"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "ACG Engine Metadata",
        "tags": [
          "ACG"
        ],
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 0
      }
    },
    "/acg/midpoints": {
      "post": {
        "description": "Compute astrocartography lines for all N(N-1)/2 body-pair midpoints.\n\nUses short-arc RA averaging in equatorial space, then runs each virtual\nmidpoint body through the standard MC/IC/AC/DC generators.\nReturns MIDPOINT_MC, MIDPOINT_IC, MIDPOINT_AC, MIDPOINT_DC line types.",
        "operationId": "midpoints_acg_midpoints_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/NatalChartRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "ACG Midpoint Lines (Go Engine)",
        "tags": [
          "ACG"
        ],
        "x-meridian-tier": "Scale",
        "x-meridian-units": 10
      }
    },
    "/acg/parans": {
      "post": {
        "description": "Computes exact angular simultaneity events between N planetary bodies for a single chart.",
        "operationId": "acg_parans_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/NatalParansRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            },
            "description": "FeatureCollection response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Natal Parans",
        "tags": [
          "ACG"
        ],
        "x-meridian-tier": "Scale",
        "x-meridian-units": 10
      }
    },
    "/acg/power-lines": {
      "post": {
        "description": "Calculate strictly isolated ACG power lines (MC, IC, AC, DC). Options configurations to include aspects/midpoints will be explicitly stripped.",
        "operationId": "power_lines_acg_power_lines_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ACGRequestPayload"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "FeatureCollection response (`features` is always an array; may be empty)."
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Calculate Astrocartography Power Lines",
        "tags": [
          "ACG"
        ],
        "x-meridian-tier": "Developer",
        "x-meridian-units": 10
      }
    },
    "/acg/relational-parans": {
      "post": {
        "description": "Computes exact cross-chart angular simultaneity events between NxM planetary bodies for two charts.",
        "operationId": "acg_relational_parans_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RelationalParansRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            },
            "description": "FeatureCollection response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Relational Parans",
        "tags": [
          "ACG"
        ],
        "x-meridian-tier": "Scale",
        "x-meridian-units": 20
      }
    },
    "/calendar/astrology/cross-quarter": {
      "get": {
        "description": "Returns the 8 Wheel of the Year events (4 cross-quarters + 4 cardinal points) calculated using true apparent solar longitude from JPL DE440. Cross-quarter dates are the true midpoints between solstices and equinoxes, NOT the traditional Gregorian approximations. 🤖 AI-optimized output available — add `format=llm` to reduce payload ~45%.",
        "operationId": "cross_quarter_calendar_astrology_cross_quarter_get",
        "parameters": [
          {
            "description": "Calendar year (Gregorian). Standard range: 1550–2650 (DE440). Deep-time: -13000–17000 (DE441, paid tier only).",
            "in": "query",
            "name": "year",
            "required": true,
            "schema": {
              "description": "Calendar year (Gregorian). Standard range: 1550–2650 (DE440). Deep-time: -13000–17000 (DE441, paid tier only).",
              "example": 2025,
              "maximum": 17000,
              "minimum": -13000,
              "title": "Year",
              "type": "integer"
            }
          },
          {
            "description": "Response format: json | llm.",
            "in": "query",
            "name": "format",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Format",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CrossQuarterResponse"
                }
              }
            },
            "description": "8 Wheel of the Year events in chronological order"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Wheel of the Year — True Astronomical Dates",
        "tags": [
          "calendar"
        ],
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 10
      }
    },
    "/calendar/astrology/lunar-standstill": {
      "get": {
        "description": "Returns the current state of the 18.6-year lunar nodal cycle. Identifies Major Standstill (Moon reaches ±28.6° declination) and Minor Standstill (Moon limited to ±18.3°) epochs. The most recent Major Standstill is circa 2025.4.",
        "operationId": "lunar_standstill_calendar_astrology_lunar_standstill_get",
        "parameters": [
          {
            "description": "Date in YYYY-MM-DD format.",
            "in": "query",
            "name": "date",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Date",
              "type": "string"
            }
          },
          {
            "description": "Julian Day.",
            "in": "query",
            "name": "jd",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Jd",
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LunarStandstillResponse"
                }
              }
            },
            "description": "Nodal cycle status and next standstill dates"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Lunar Standstill — 18.6-Year Nodal Cycle Status",
        "tags": [
          "calendar"
        ],
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 10
      }
    },
    "/calendar/astrology/moon-phases": {
      "get": {
        "description": "Returns the current 8-phase lunar phase classification (not just 4), illumination fraction, Moon age in hours, and the next 4 principal phase moments (New, First Quarter, Full, Third Quarter). 🤖 AI-optimized output available — add `format=llm` to reduce payload ~45%.",
        "operationId": "moon_phases_calendar_astrology_moon_phases_get",
        "parameters": [
          {
            "description": "Date in YYYY-MM-DD format. Mutually exclusive with jd.",
            "in": "query",
            "name": "date",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Date",
              "type": "string"
            }
          },
          {
            "description": "Julian Day. Mutually exclusive with date.",
            "in": "query",
            "name": "jd",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Jd",
              "type": "number"
            }
          },
          {
            "description": "Response format: json | llm.",
            "in": "query",
            "name": "format",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Format",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MoonPhasesResponse"
                }
              }
            },
            "description": "Current phase and upcoming principal phases"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "8-Phase Lunar Classification + Next Principal Phases",
        "tags": [
          "calendar"
        ],
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 10
      }
    },
    "/catalogs/bodies": {
      "get": {
        "description": "Catalog-driven identifiers for selectable natal bodies (planets, nodes, Lilith points, major asteroids). This surface is intended for commercial clients and UIs.",
        "operationId": "get_bodies_catalog_catalogs_bodies_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CatalogBodiesResponse"
                }
              }
            },
            "description": "Successful Response"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Catalog of supported natal bodies",
        "tags": [
          "catalogs"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 1
      }
    },
    "/catalogs/fixed-stars": {
      "get": {
        "description": "Returns fixed stars discoverable via the built-in star catalog when available, falling back to the built-in registry for core stars.",
        "operationId": "get_fixed_stars_catalogs_fixed_stars_get",
        "parameters": [
          {
            "description": "Page size",
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 100,
              "description": "Page size",
              "maximum": 500,
              "minimum": 1,
              "title": "Limit",
              "type": "integer"
            }
          },
          {
            "description": "Offset into the full list",
            "in": "query",
            "name": "offset",
            "required": false,
            "schema": {
              "default": 0,
              "description": "Offset into the full list",
              "minimum": 0,
              "title": "Offset",
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CatalogFixedStarsResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Catalog of fixed stars (paginated)",
        "tags": [
          "catalogs"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 1
      }
    },
    "/catalogs/fixed-stars/groups": {
      "get": {
        "operationId": "get_fixed_star_groups_catalogs_fixed_stars_groups_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CatalogFixedStarGroupsResponse"
                }
              }
            },
            "description": "Successful Response"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Catalog of fixed star group identifiers",
        "tags": [
          "catalogs"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 1
      }
    },
    "/chinese/bazi": {
      "post": {
        "description": "Compute the Four Pillars (八字 BaZi) for a birth date and time. Returns the Heavenly Stem and Earthly Branch for each pillar (year, month, day, hour), along with the Day Master — the core element of BaZi self-analysis.\n\n**Heavenly Stems**: 10 stems cycling through 5 elements × 2 polarities.\n**Earthly Branches**: 12 branches, each associated with a zodiac animal.\n**Day Master (日主)**: The Day Stem's element represents the self.\n\n**Note**: This MVP uses Jan 1 as the year boundary. Traditional BaZi uses Lì Chūn (立春, ~Feb 4). See metadata for details.\n\n**Metering**: 1 unit per call.",
        "operationId": "bazi_chart_chinese_bazi_post",
        "parameters": [
          {
            "description": "Response format: json (full) or llm (compact columnar).",
            "in": "query",
            "name": "format",
            "required": false,
            "schema": {
              "default": "json",
              "description": "Response format: json (full) or llm (compact columnar).",
              "pattern": "^(?i)(json|llm)$",
              "title": "Format",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "authorization",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Authorization",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-Api-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-OpenEphemeris-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-OpenEphemeris-API-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "apikey",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Apikey",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BaZiRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BaZiResponse"
                }
              }
            },
            "description": "Full Four Pillars with stems, branches, and Day Master."
          },
          "422": {
            "description": "Validation error (bad date, out-of-range values)."
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Calculate Four Pillars of Destiny (BaZi)",
        "tags": [
          "chinese"
        ],
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 1
      }
    },
    "/chinese/bazi/annual-pillar": {
      "post": {
        "description": "Calculate the Heavenly Stem and Earthly Branch for any given Gregorian year (Liu Nian 流年 annual pillar). Optionally returns the NaYin resonance element.\n\n**Metering**: 1 unit per call.",
        "operationId": "bazi_annual_pillar_chinese_bazi_annual_pillar_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BaZiAnnualPillarRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BaZiAnnualPillarResponse"
                }
              }
            },
            "description": "Annual pillar stem, branch, and NaYin."
          },
          "422": {
            "description": "Validation error."
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "BaZi Annual Pillar (Liu Nian)",
        "tags": [
          "chinese"
        ],
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 1
      }
    },
    "/chinese/bazi/compatibility": {
      "post": {
        "description": "Assess the compatibility between two BaZi charts using Six Harmonies (六合), Three Harmonies (三合), Six Clashes (六冲), Six Harms (六害), and Day Master element interactions.\n\nReturns a 0–100 composite score, an assessment label (excellent / good / moderate / challenging), and a list of specific factors found.\n\n**Note**: The 0–100 scoring is an Open Ephemeris algorithmic interpretation. BaZi compatibility analysis is nuanced and multi-layered; this endpoint provides a structured starting point.\n\n**Metering**: 3 units per call.",
        "operationId": "bazi_compatibility_chinese_bazi_compatibility_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BaZiCompatibilityRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BaZiCompatibilityResponse"
                }
              }
            },
            "description": "Compatibility score, assessment, and contributing factors."
          },
          "422": {
            "description": "Validation error."
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "BaZi Compatibility (八字合婚)",
        "tags": [
          "chinese"
        ],
        "x-meridian-tier": "Developer",
        "x-meridian-units": 3
      }
    },
    "/chinese/bazi/element-balance": {
      "post": {
        "description": "Calculate the weighted Wu Xing (五行) element balance across all four pillars of a BaZi chart, including hidden stems within the earthly branches.\n\nReturns percentage scores for each of the five elements, Day Master strength (strong/weak/neutral), and the recommended Yong Shen (用神) favourable element.\n\n**Metering**: 2 units per call.",
        "operationId": "bazi_element_balance_chinese_bazi_element_balance_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BaZiRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BaZiElementBalanceResponse"
                }
              }
            },
            "description": "Five-element scores, Day Master strength, and Yong Shen."
          },
          "422": {
            "description": "Validation error."
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "BaZi Element Balance (Wu Xing)",
        "tags": [
          "chinese"
        ],
        "x-meridian-tier": "Developer",
        "x-meridian-units": 2
      }
    },
    "/chinese/bazi/luck-pillars": {
      "post": {
        "description": "Calculate the eight 10-year Da Yun (大运) luck pillars for a BaZi chart. Starting age is computed from the nearest solar term (Jié) boundary — 3 days from birth = 1 year of starting age (classical Zi Ping rule).\n\nRequires gender to determine whether pillars progress forward or backward through the sexagenary cycle.\n\n**Metering**: 2 units per call.",
        "operationId": "bazi_luck_pillars_chinese_bazi_luck_pillars_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BaZiLuckPillarsRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BaZiLuckPillarsResponse"
                }
              }
            },
            "description": "Eight Da Yun luck pillars with starting age and direction."
          },
          "422": {
            "description": "Validation error."
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "BaZi Luck Pillars (Da Yun)",
        "tags": [
          "chinese"
        ],
        "x-meridian-tier": "Developer",
        "x-meridian-units": 2
      }
    },
    "/chinese/bazi/solar-terms": {
      "post": {
        "description": "Return all 24 Jiéqì (节气) solar terms for a given Gregorian year, with exact datetime (UTC) computed from true apparent solar longitude.\n\nIncludes both the 12 Jié (节, month-starting terms used in BaZi) and the 12 Qì (气, mid-month terms). Dates are computed via the same ephemeris bridge used by /chinese/bazi.\n\n**Metering**: 2 units per call.",
        "operationId": "bazi_solar_terms_chinese_bazi_solar_terms_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BaZiSolarTermsRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BaZiSolarTermsResponse"
                }
              }
            },
            "description": "All 24 solar terms for the requested year."
          },
          "422": {
            "description": "Validation error."
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "24 Solar Terms for a Year",
        "tags": [
          "chinese"
        ],
        "x-meridian-tier": "Developer",
        "x-meridian-units": 2
      }
    },
    "/chinese/bazi/ten-gods": {
      "post": {
        "description": "Calculate the Ten Gods (十神 Shí Shén) for a BaZi chart relative to the Day Master. Returns the Ten God label, Chinese name, category, and hidden stem Ten Gods for all four pillars.\n\nThe Ten Gods describe the nature of each element in the chart relative to the self (Day Master): Friend, Rob Wealth, Eating God, Hurting Officer, Indirect Wealth, Direct Wealth, Seven Killings, Direct Officer, Indirect Resource, Direct Resource.\n\n**Metering**: 2 units per call.",
        "operationId": "bazi_ten_gods_chinese_bazi_ten_gods_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BaZiRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BaZiTenGodsResponse"
                }
              }
            },
            "description": "Ten Gods for all four pillars."
          },
          "422": {
            "description": "Validation error."
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "BaZi Ten Gods Analysis",
        "tags": [
          "chinese"
        ],
        "x-meridian-tier": "Developer",
        "x-meridian-units": 2
      }
    },
    "/chinese/zodiac": {
      "get": {
        "description": "Quick lookup of the Chinese zodiac animal, element, and Yin/Yang polarity for any Gregorian year. Also returns the year's Heavenly Stem and Earthly Branch.\n\nThe 12-animal cycle: Rat, Ox, Tiger, Rabbit, Dragon, Snake, Horse, Goat, Monkey, Rooster, Dog, Pig.\n\nThe 5-element cycle: Wood, Fire, Earth, Metal, Water (each element governs two consecutive years).\n\n**Metering**: 1 unit per call.",
        "operationId": "zodiac_lookup_chinese_zodiac_get",
        "parameters": [
          {
            "description": "Gregorian year to look up.",
            "in": "query",
            "name": "year",
            "required": true,
            "schema": {
              "description": "Gregorian year to look up.",
              "example": 2024,
              "maximum": 9999,
              "minimum": 1,
              "title": "Year",
              "type": "integer"
            }
          },
          {
            "description": "Response format: json (full) or llm (compact).",
            "in": "query",
            "name": "format",
            "required": false,
            "schema": {
              "default": "json",
              "description": "Response format: json (full) or llm (compact).",
              "pattern": "^(?i)(json|llm)$",
              "title": "Format",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "authorization",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Authorization",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-Api-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-OpenEphemeris-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-OpenEphemeris-API-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "apikey",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Apikey",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ZodiacResponse"
                }
              }
            },
            "description": "Zodiac animal, element, polarity, and stem/branch."
          },
          "422": {
            "description": "Validation error (missing or out-of-range year)."
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Chinese zodiac animal and element for a year",
        "tags": [
          "chinese"
        ],
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 1
      }
    },
    "/comparative/composite": {
      "post": {
        "description": "Calculate a composite chart (Davidson or Midpoint).\n\n🤖 AI-optimized output available — add `format=llm` to reduce payload ~65%.",
        "operationId": "calculate_composite_comparative_composite_post",
        "parameters": [
          {
            "deprecated": true,
            "description": "Deprecated: use preset+format. Accepts full|simple|llm.",
            "in": "query",
            "name": "output_mode",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Output Mode",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "preset",
            "required": false,
            "schema": {
              "default": "full",
              "pattern": "^(?i)(full|simple)$",
              "title": "Preset",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "format",
            "required": false,
            "schema": {
              "default": "json",
              "pattern": "^(?i)(json|llm|llm)$",
              "title": "Format",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CompositeRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NatalChartEnhancedResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Calculate Composite",
        "tags": [
          "comparative"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Developer",
        "x-meridian-units": 3
      }
    },
    "/comparative/composite/midpoint": {
      "post": {
        "description": "Calculate a 2-person midpoint composite (planets averaged; houses/angles from Davison midpoint time+place).\n\n🤖 AI-optimized output available — add `format=llm` to reduce payload ~65%.",
        "operationId": "calculate_composite_midpoint_comparative_composite_midpoint_post",
        "parameters": [
          {
            "deprecated": true,
            "description": "Deprecated: use preset+format. Accepts full|simple|llm.",
            "in": "query",
            "name": "output_mode",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Output Mode",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "preset",
            "required": false,
            "schema": {
              "default": "full",
              "pattern": "^(?i)(full|simple)$",
              "title": "Preset",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "format",
            "required": false,
            "schema": {
              "default": "json",
              "pattern": "^(?i)(json|llm|llm)$",
              "title": "Format",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CompositeRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NatalChartEnhancedResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Calculate Composite Midpoint",
        "tags": [
          "comparative"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Developer",
        "x-meridian-units": 3
      }
    },
    "/comparative/natal-transits": {
      "post": {
        "description": "Calculate a synastry-style overlay between a natal chart and transits.\n\n- Chart A: natal subject at birth\n- Chart B: the same subject/location at transit_datetime (defaults to now UTC)",
        "operationId": "calculate_natal_transits_comparative_natal_transits_post",
        "parameters": [
          {
            "in": "query",
            "name": "preset",
            "required": false,
            "schema": {
              "default": "full",
              "pattern": "^(?i)(full|simple)$",
              "title": "Preset",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "format",
            "required": false,
            "schema": {
              "default": "json",
              "pattern": "^(?i)(json|llm|llm)$",
              "title": "Format",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/NatalTransitsRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NatalTransitsResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Calculate Natal Transits",
        "tags": [
          "comparative"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Developer",
        "x-meridian-units": 3
      }
    },
    "/comparative/overlay": {
      "post": {
        "description": "Return lightweight chart payloads for an overlay across multiple subjects (no aspects).",
        "operationId": "calculate_overlay_comparative_overlay_post",
        "parameters": [
          {
            "deprecated": true,
            "description": "Deprecated: use preset+format. Accepts full|simple|llm.",
            "in": "query",
            "name": "output_mode",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Output Mode",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "preset",
            "required": false,
            "schema": {
              "default": "full",
              "pattern": "^(?i)(full|simple)$",
              "title": "Preset",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "format",
            "required": false,
            "schema": {
              "default": "json",
              "pattern": "^(?i)(json|llm|llm)$",
              "title": "Format",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OverlayRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OverlayResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Calculate Overlay",
        "tags": [
          "comparative"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Developer",
        "x-meridian-units": 3
      }
    },
    "/comparative/synastry": {
      "post": {
        "description": "Calculate a synastry chart (comparison between two subjects).\n\n🤖 AI-optimized output available — add `format=llm` to reduce payload ~65%.",
        "operationId": "calculate_synastry_comparative_synastry_post",
        "parameters": [
          {
            "in": "query",
            "name": "preset",
            "required": false,
            "schema": {
              "default": "full",
              "pattern": "^(?i)(full|simple)$",
              "title": "Preset",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "format",
            "required": false,
            "schema": {
              "default": "json",
              "pattern": "^(?i)(json|llm|llm)$",
              "title": "Format",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SynastryRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SynastryResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Calculate Synastry",
        "tags": [
          "comparative"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Developer",
        "x-meridian-units": 3
      }
    },
    "/eclipse/besselian-elements": {
      "get": {
        "description": "Raw Besselian elements (X, Y, d, μ, l₁, l₂, f₁, f₂) and their time derivatives for any eclipse. For researchers and advanced users.",
        "operationId": "get_besselian_elements_eclipse_besselian_elements_get",
        "parameters": [
          {
            "description": "Eclipse date (ISO 8601)",
            "in": "query",
            "name": "date",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Date",
              "type": "string"
            }
          },
          {
            "description": "Julian Day",
            "in": "query",
            "name": "jd",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Jd",
              "type": "number"
            }
          },
          {
            "in": "query",
            "name": "delta_t_model",
            "required": false,
            "schema": {
              "default": "espenak_meeus",
              "title": "Delta T Model",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BesselianElementsResponse"
                }
              }
            },
            "description": "Besselian elements for the eclipse"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Raw Besselian Elements",
        "tags": [
          "eclipse"
        ],
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 1
      }
    },
    "/eclipse/lunar/global": {
      "get": {
        "description": "Lunar eclipse visibility with contact times (penumbral, partial, total). Safe to view without eye protection. 🤖 AI-optimized output available — add `output_format=llm` to reduce payload ~55%.",
        "operationId": "get_lunar_eclipse_global_eclipse_lunar_global_get",
        "parameters": [
          {
            "description": "Eclipse date (ISO 8601)",
            "in": "query",
            "name": "date",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Date",
              "type": "string"
            }
          },
          {
            "description": "Julian Day",
            "in": "query",
            "name": "jd",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Jd",
              "type": "number"
            }
          },
          {
            "in": "query",
            "name": "delta_t_model",
            "required": false,
            "schema": {
              "default": "espenak_meeus",
              "title": "Delta T Model",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "output_format",
            "required": false,
            "schema": {
              "default": "raw",
              "title": "Output Format",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LunarEclipseGlobalResponse"
                }
              }
            },
            "description": "Lunar eclipse global circumstances"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Lunar Eclipse Global Circumstances",
        "tags": [
          "eclipse"
        ],
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 1
      }
    },
    "/eclipse/next-visible": {
      "get": {
        "description": "Find the next solar or lunar eclipse visible from specific coordinates. Planning tool for eclipse chasers.",
        "operationId": "get_next_visible_eclipse_eclipse_next_visible_get",
        "parameters": [
          {
            "description": "Observer latitude",
            "in": "query",
            "name": "lat",
            "required": true,
            "schema": {
              "description": "Observer latitude",
              "maximum": 90,
              "minimum": -90,
              "title": "Lat",
              "type": "number"
            }
          },
          {
            "description": "Observer longitude",
            "in": "query",
            "name": "lon",
            "required": true,
            "schema": {
              "description": "Observer longitude",
              "maximum": 180,
              "minimum": -180,
              "title": "Lon",
              "type": "number"
            }
          },
          {
            "description": "'solar', 'lunar', or 'any'",
            "in": "query",
            "name": "type",
            "required": false,
            "schema": {
              "default": "any",
              "description": "'solar', 'lunar', or 'any'",
              "title": "Type",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NextVisibleResponse"
                }
              }
            },
            "description": "Next visible eclipse with local circumstances"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Next Visible Eclipse",
        "tags": [
          "eclipse"
        ],
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 1
      }
    },
    "/eclipse/solar/global": {
      "get": {
        "description": "Calculate complete solar eclipse circumstances with Besselian elements and global path for a given date. Returns eclipse classification, Saros series, safety warnings, and uncertainty analysis. 🤖 AI-optimized output available — add `output_format=llm` to reduce payload ~55%.",
        "operationId": "get_solar_eclipse_global_eclipse_solar_global_get",
        "parameters": [
          {
            "description": "Eclipse date (ISO 8601, e.g. 2026-08-12)",
            "in": "query",
            "name": "date",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Date",
              "type": "string"
            }
          },
          {
            "description": "Julian Day (alternative to date)",
            "in": "query",
            "name": "jd",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Jd",
              "type": "number"
            }
          },
          {
            "description": "'espenak_meeus' or 'stephenson_2021'",
            "in": "query",
            "name": "delta_t_model",
            "required": false,
            "schema": {
              "default": "espenak_meeus",
              "description": "'espenak_meeus' or 'stephenson_2021'",
              "title": "Delta T Model",
              "type": "string"
            }
          },
          {
            "description": "'raw' or 'llm'",
            "in": "query",
            "name": "output_format",
            "required": false,
            "schema": {
              "default": "raw",
              "description": "'raw' or 'llm'",
              "title": "Output Format",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SolarEclipseGlobalResponse"
                }
              }
            },
            "description": "Solar eclipse global circumstances with Besselian elements"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Solar Eclipse Global Circumstances",
        "tags": [
          "eclipse"
        ],
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 1
      }
    },
    "/eclipse/solar/local": {
      "get": {
        "description": "Local circumstances for a specific observer: magnitude, obscuration, contact times (C1-C4), duration, and sun position. 🤖 AI-optimized output available — add `output_format=llm` to reduce payload ~55%.",
        "operationId": "get_solar_eclipse_local_eclipse_solar_local_get",
        "parameters": [
          {
            "description": "Eclipse date (ISO 8601)",
            "in": "query",
            "name": "date",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Date",
              "type": "string"
            }
          },
          {
            "description": "Julian Day",
            "in": "query",
            "name": "jd",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Jd",
              "type": "number"
            }
          },
          {
            "description": "Observer latitude",
            "in": "query",
            "name": "lat",
            "required": true,
            "schema": {
              "description": "Observer latitude",
              "maximum": 90,
              "minimum": -90,
              "title": "Lat",
              "type": "number"
            }
          },
          {
            "description": "Observer longitude",
            "in": "query",
            "name": "lon",
            "required": true,
            "schema": {
              "description": "Observer longitude",
              "maximum": 180,
              "minimum": -180,
              "title": "Lon",
              "type": "number"
            }
          },
          {
            "description": "Observer elevation in meters",
            "in": "query",
            "name": "elev",
            "required": false,
            "schema": {
              "default": 0,
              "description": "Observer elevation in meters",
              "title": "Elev",
              "type": "number"
            }
          },
          {
            "in": "query",
            "name": "delta_t_model",
            "required": false,
            "schema": {
              "default": "espenak_meeus",
              "title": "Delta T Model",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "output_format",
            "required": false,
            "schema": {
              "default": "raw",
              "title": "Output Format",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SolarEclipseLocalResponse"
                }
              }
            },
            "description": "Solar eclipse local circumstances for observer"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Solar Eclipse Local Circumstances",
        "tags": [
          "eclipse"
        ],
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 1
      }
    },
    "/electional/aspect-search": {
      "get": {
        "description": "List all applying and separating aspects active at a given moment, enriched with quality scores. Useful for identifying the astrological texture of a chosen time.",
        "operationId": "ElectionalAspectSearchElectionalAspectSearchGet",
        "parameters": [
          {
            "description": "Date/datetime to check (ISO 8601 or YYYY-MM-DD). Defaults to now.",
            "in": "query",
            "name": "date",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Julian Day alternative to date.",
            "in": "query",
            "name": "jd",
            "required": false,
            "schema": {
              "format": "double",
              "type": "number"
            }
          },
          {
            "description": "Maximum orb in degrees (default 8.0).",
            "in": "query",
            "name": "max_orb",
            "required": false,
            "schema": {
              "default": 8,
              "maximum": 15,
              "minimum": 0.5,
              "type": "number"
            }
          },
          {
            "description": "Comma-sep aspect filter: conjunction,sextile,square,trine,opposition. Defaults to all.",
            "in": "query",
            "name": "aspects",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Output format: json (default) or llm.",
            "in": "query",
            "name": "format",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ElectionalAspectSearchResponse"
                }
              }
            },
            "description": "Active aspects"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Active Aspect Search",
        "tags": [
          "electional"
        ],
        "x-meridian-tier": "Developer",
        "x-meridian-units": 5
      }
    },
    "/electional/find-window": {
      "get": {
        "description": "Search a date range for the highest-scoring astrological timing windows. Evaluates moments in 1-hour steps, applies optional constraints (VOC avoidance, retrograde avoidance, lunar phase filter), and returns the top N ranked windows.",
        "operationId": "ElectionalFindWindowElectionalFindWindowGet",
        "parameters": [
          {
            "description": "Start of search range (ISO 8601 or YYYY-MM-DD). Defaults to today.",
            "in": "query",
            "name": "start_date",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "End of search range. Defaults to 30 days after start.",
            "in": "query",
            "name": "end_date",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Observer latitude (decimal degrees).",
            "in": "query",
            "name": "latitude",
            "required": false,
            "schema": {
              "type": "number"
            }
          },
          {
            "description": "Observer longitude (decimal degrees).",
            "in": "query",
            "name": "longitude",
            "required": false,
            "schema": {
              "type": "number"
            }
          },
          {
            "description": "Maximum number of windows to return (1-20).",
            "in": "query",
            "name": "max_results",
            "required": false,
            "schema": {
              "default": 5,
              "maximum": 20,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "Exclude void-of-course Moon periods.",
            "in": "query",
            "name": "avoid_voc",
            "required": false,
            "schema": {
              "default": true,
              "type": "boolean"
            }
          },
          {
            "description": "Preferred lunar phase: waxing, waning, new, full, or any.",
            "in": "query",
            "name": "lunar_phase",
            "required": false,
            "schema": {
              "default": "any",
              "type": "string"
            }
          },
          {
            "description": "Comma-separated planet names to exclude when retrograde, e.g. Mercury,Mars.",
            "in": "query",
            "name": "avoid_retrograde",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Output format: json (default) or llm.",
            "in": "query",
            "name": "format",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ElectionalWindowResponse"
                }
              }
            },
            "description": "Window search results"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Find Electional Window",
        "tags": [
          "electional"
        ],
        "x-meridian-tier": "Developer",
        "x-meridian-units": 5
      }
    },
    "/electional/moment-analysis": {
      "get": {
        "description": "Score and analyse the astrological quality of a specific moment. Returns a 0-100 composite viability score derived from essential dignities, aspect quality, sect alignment, and void-of-course status.",
        "operationId": "ElectionalMomentAnalysisElectionalMomentAnalysisGet",
        "parameters": [
          {
            "description": "Date/datetime to analyse (ISO 8601 or YYYY-MM-DD). Defaults to now.",
            "in": "query",
            "name": "date",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Julian Day alternative to date. date takes priority.",
            "in": "query",
            "name": "jd",
            "required": false,
            "schema": {
              "format": "double",
              "type": "number"
            }
          },
          {
            "description": "Observer latitude — required for sect and VoC.",
            "in": "query",
            "name": "latitude",
            "required": false,
            "schema": {
              "type": "number"
            }
          },
          {
            "description": "Observer longitude (decimal degrees).",
            "in": "query",
            "name": "longitude",
            "required": false,
            "schema": {
              "type": "number"
            }
          },
          {
            "description": "Output format: json (default) or llm.",
            "in": "query",
            "name": "format",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ElectionalMomentResponse"
                }
              }
            },
            "description": "Moment analysis"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Electional Moment Analysis",
        "tags": [
          "electional"
        ],
        "x-meridian-tier": "Developer",
        "x-meridian-units": 5
      }
    },
    "/electional/station-tracker": {
      "get": {
        "description": "Find all retrograde and direct station dates for the specified planets in a given date range. Stations are moments when a planet appears stationary before changing direction.",
        "operationId": "ElectionalStationTrackerElectionalStationTrackerGet",
        "parameters": [
          {
            "description": "Start date (ISO 8601 or YYYY-MM-DD). Defaults to today.",
            "in": "query",
            "name": "start_date",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "End date. Defaults to 90 days after start.",
            "in": "query",
            "name": "end_date",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Comma-separated planet names. Defaults to all 7 classical planets.",
            "in": "query",
            "name": "planets",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Output format: json (default) or llm.",
            "in": "query",
            "name": "format",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ElectionalStationResponse"
                }
              }
            },
            "description": "Station events"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Planetary Station Tracker",
        "tags": [
          "electional"
        ],
        "x-meridian-tier": "Developer",
        "x-meridian-units": 5
      }
    },
    "/ephemeris/agro/calendar": {
      "get": {
        "description": "Returns compact biodynamic summaries for a date range (max 31 days).\n\nEach day includes: day type, quality score, ascending status, void-of-course\nactive flag, phase name, and illumination percentage. Designed for building\nmonthly planning calendars.\n\n🤖 AI-optimized output available — add `format=llm` to reduce payload ~80%.\n\n```bash\nGET /ephemeris/agro/calendar?lat=-33.87\u0026lon=151.21\u0026start=2026-03-01\u0026end=2026-03-31\u0026tz=Australia/Sydney\n```",
        "operationId": "get_agro_calendar_endpoint_ephemeris_agro_calendar_get",
        "parameters": [
          {
            "description": "Observer latitude (WGS84, degrees)",
            "in": "query",
            "name": "lat",
            "required": true,
            "schema": {
              "description": "Observer latitude (WGS84, degrees)",
              "maximum": 90,
              "minimum": -90,
              "title": "Lat",
              "type": "number"
            }
          },
          {
            "description": "Observer longitude (WGS84, degrees)",
            "in": "query",
            "name": "lon",
            "required": true,
            "schema": {
              "description": "Observer longitude (WGS84, degrees)",
              "maximum": 180,
              "minimum": -180,
              "title": "Lon",
              "type": "number"
            }
          },
          {
            "description": "Start date as YYYY-MM-DD",
            "example": "2026-03-01",
            "in": "query",
            "name": "start",
            "required": true,
            "schema": {
              "description": "Start date as YYYY-MM-DD",
              "title": "Start",
              "type": "string"
            }
          },
          {
            "description": "End date as YYYY-MM-DD (inclusive, max 31 days from start)",
            "example": "2026-03-31",
            "in": "query",
            "name": "end",
            "required": true,
            "schema": {
              "description": "End date as YYYY-MM-DD (inclusive, max 31 days from start)",
              "title": "End",
              "type": "string"
            }
          },
          {
            "description": "IANA timezone identifier",
            "example": "Australia/Sydney",
            "in": "query",
            "name": "tz",
            "required": false,
            "schema": {
              "default": "UTC",
              "description": "IANA timezone identifier",
              "title": "Tz",
              "type": "string"
            }
          },
          {
            "description": "Observer elevation in metres",
            "in": "query",
            "name": "elev_m",
            "required": false,
            "schema": {
              "default": 0,
              "description": "Observer elevation in metres",
              "maximum": 8849,
              "minimum": 0,
              "title": "Elev M",
              "type": "number"
            }
          },
          {
            "description": "Output format",
            "in": "query",
            "name": "format",
            "required": false,
            "schema": {
              "default": "json",
              "description": "Output format",
              "pattern": "^(?i)(json|llm|llm)$",
              "title": "Format",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "authorization",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Authorization",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-Api-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-OpenEphemeris-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-OpenEphemeris-API-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "apikey",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Apikey",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgroCalendarResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Biodynamic monthly calendar",
        "tags": [
          "agricultural"
        ],
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 1
      }
    },
    "/ephemeris/agro/daily": {
      "get": {
        "description": "Returns a complete Maria Thun biodynamic day profile for a given date and location.\n\n**Includes:**\n- Moon sign, element, latitude velocity (ascending/descending)\n- Thun day type (root / leaf / flower / fruit) with quality score (0–100)\n- Aspect modifiers with explained score impacts (Saturn, Jupiter, Mars, Node)\n- Activity recommendations (favorable / unfavorable / optimal tasks)\n- Void-of-course window (active status + next window)\n- Lunar phase + illumination\n- Sunrise, sunset, moonrise, moonset (topocentric, ±1s precision)\n\n**Zodiac:** Always tropical for Thun classification (per Thun methodology).  \n**Ephemeris:** DE440.\n\n🤖 AI-optimized output available — add `format=llm` to reduce payload ~70%.\n\n```bash\nGET /ephemeris/agro/daily?lat=-33.87\u0026lon=151.21\u0026date=2026-03-15\u0026tz=Australia/Sydney\n```",
        "operationId": "get_agro_daily_endpoint_ephemeris_agro_daily_get",
        "parameters": [
          {
            "description": "Observer latitude (WGS84, degrees)",
            "in": "query",
            "name": "lat",
            "required": true,
            "schema": {
              "description": "Observer latitude (WGS84, degrees)",
              "maximum": 90,
              "minimum": -90,
              "title": "Lat",
              "type": "number"
            }
          },
          {
            "description": "Observer longitude (WGS84, degrees)",
            "in": "query",
            "name": "lon",
            "required": true,
            "schema": {
              "description": "Observer longitude (WGS84, degrees)",
              "maximum": 180,
              "minimum": -180,
              "title": "Lon",
              "type": "number"
            }
          },
          {
            "description": "Date as YYYY-MM-DD",
            "example": "2026-03-15",
            "in": "query",
            "name": "date",
            "required": true,
            "schema": {
              "description": "Date as YYYY-MM-DD",
              "title": "Date",
              "type": "string"
            }
          },
          {
            "description": "IANA timezone identifier",
            "example": "Australia/Sydney",
            "in": "query",
            "name": "tz",
            "required": false,
            "schema": {
              "default": "UTC",
              "description": "IANA timezone identifier",
              "title": "Tz",
              "type": "string"
            }
          },
          {
            "description": "Observer elevation in metres",
            "in": "query",
            "name": "elev_m",
            "required": false,
            "schema": {
              "default": 0,
              "description": "Observer elevation in metres",
              "maximum": 8849,
              "minimum": 0,
              "title": "Elev M",
              "type": "number"
            }
          },
          {
            "description": "Output format",
            "in": "query",
            "name": "format",
            "required": false,
            "schema": {
              "default": "json",
              "description": "Output format",
              "pattern": "^(?i)(json|llm|llm)$",
              "title": "Format",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "authorization",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Authorization",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-Api-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-OpenEphemeris-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-OpenEphemeris-API-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "apikey",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Apikey",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgroDailyResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Biodynamic daily profile",
        "tags": [
          "agricultural"
        ],
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 1
      }
    },
    "/ephemeris/agro/void-of-course": {
      "get": {
        "description": "Returns the current Void of Course (VoC) Moon window for a given Julian Day.\n\nMethod 3: scans backward from the Moon's next sign ingress to find the last\nmajor Ptolemaic aspect (conjunction, sextile, square, trine, opposition) to\na traditional planet. The VoC period runs from that aspect until the ingress.\n\n```bash\nGET /ephemeris/agro/void-of-course?jd=2451545.0\n```",
        "operationId": "get_void_of_course_endpoint_ephemeris_agro_void_of_course_get",
        "parameters": [
          {
            "description": "Julian Day (UT1)",
            "example": 2451545,
            "in": "query",
            "name": "jd",
            "required": true,
            "schema": {
              "description": "Julian Day (UT1)",
              "format": "double",
              "title": "Jd",
              "type": "number"
            }
          },
          {
            "in": "header",
            "name": "authorization",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Authorization",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-Api-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-OpenEphemeris-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-OpenEphemeris-API-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "apikey",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Apikey",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VoCData"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Void of Course Moon",
        "tags": [
          "agricultural"
        ],
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 1
      }
    },
    "/ephemeris/angles-points": {
      "post": {
        "description": "Mechanical endpoint returning Asc/MC/Desc/IC plus Vertex/Anti-Vertex.",
        "operationId": "angles_points_ephemeris_angles_points_post",
        "parameters": [
          {
            "deprecated": true,
            "description": "Deprecated: use preset+format. Accepts full|simple|llm.",
            "in": "query",
            "name": "output_mode",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Output Mode",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "preset",
            "required": false,
            "schema": {
              "default": "full",
              "pattern": "^(?i)(full|simple)$",
              "title": "Preset",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "format",
            "required": false,
            "schema": {
              "default": "json",
              "pattern": "^(?i)(json|llm)$",
              "title": "Format",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "authorization",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Authorization",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-Api-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-OpenEphemeris-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-OpenEphemeris-API-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "apikey",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Apikey",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AnglesPointsRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnglesPointsResponse"
                }
              }
            },
            "description": "Angles calculated successfully"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Invalid input"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Calculation error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Calculate angles + points (granular)",
        "tags": [
          "ephemeris"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 1
      }
    },
    "/ephemeris/antiscia": {
      "post": {
        "description": "Calculate antiscia (mirror points across the Cancer/Capricorn solstice axis) and contra-antiscia for a set of planetary longitudes. Detects hidden conjunctions where one planet's antiscion falls on another planet's natal position. Central to Hellenistic and traditional Western astrology. 🤖 AI-optimized output available — add `format=llm` to reduce payload ~60%.",
        "operationId": "calculate_antiscia_ephemeris_antiscia_post",
        "parameters": [
          {
            "deprecated": true,
            "description": "Deprecated: use preset+format. Accepts full|simple|llm.",
            "in": "query",
            "name": "output_mode",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Output Mode",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "format",
            "required": false,
            "schema": {
              "default": "json",
              "pattern": "^(?i)(json|llm)$",
              "title": "Format",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "authorization",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Authorization",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-Api-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-OpenEphemeris-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-OpenEphemeris-API-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "apikey",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Apikey",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AntisciaRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AntisciaResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          },
          "422": {
            "description": "Unprocessable Entity - Invalid input format"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Calculate antiscia and contra-antiscia",
        "tags": [
          "ephemeris"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 1
      }
    },
    "/ephemeris/aspect-check": {
      "post": {
        "description": "Lightweight endpoint for calculating aspects between two celestial longitudes. Supports filtering by aspect type and custom orb limits.",
        "operationId": "aspect_check_ephemeris_aspect_check_post",
        "parameters": [
          {
            "deprecated": true,
            "description": "Deprecated: use preset+format. Accepts full|simple|llm.",
            "in": "query",
            "name": "output_mode",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Output Mode",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "preset",
            "required": false,
            "schema": {
              "default": "full",
              "pattern": "^(?i)(full|simple)$",
              "title": "Preset",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "format",
            "required": false,
            "schema": {
              "default": "json",
              "pattern": "^(?i)(json|llm)$",
              "title": "Format",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "authorization",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Authorization",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-Api-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-OpenEphemeris-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-OpenEphemeris-API-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "apikey",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Apikey",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AspectCheckRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AspectCheckResponse"
                }
              }
            },
            "description": "Aspects calculated successfully"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Invalid input (e.g., longitude out of range)"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Calculation error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Check aspects between two longitudes",
        "tags": [
          "ephemeris"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 1
      }
    },
    "/ephemeris/declinations": {
      "post": {
        "description": "Analyse ecliptic coordinates to compute equatorial declinations, detect out-of-bounds (OOB) planets, and find declination aspects (parallels and contraparallels).\n\nA planet is out of bounds when its declination exceeds the obliquity of the ecliptic (~23.44°). OOB planets operate outside the Sun's framework and are interpreted as wildcards in contemporary astrology. The Moon is the most frequently OOB body.\n\nParallels (same declination, same hemisphere) behave like conjunctions; contraparallels (equal but opposite declination) behave like oppositions.\n\n🤖 Agent-first endpoint — pure deterministic math, no ephemeris kernel required.",
        "operationId": "analyze_declinations_ephemeris_declinations_post",
        "parameters": [
          {
            "description": "Response format: json | llm.",
            "in": "query",
            "name": "format",
            "required": false,
            "schema": {
              "default": "json",
              "pattern": "^(?i)(json|llm)$",
              "title": "Format",
              "type": "string"
            }
          },
          {
            "deprecated": true,
            "description": "Deprecated: use format. Accepts full|simple|llm.",
            "in": "query",
            "name": "output_mode",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Output Mode",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DeclinationAnalysisRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeclinationAnalysisResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__predictive_schemas__ErrorResponse"
                }
              }
            },
            "description": "Unprocessable Entity - Invalid input"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__predictive_schemas__ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Out-of-Bounds Declination Analysis",
        "tags": [
          "ephemeris"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 1
      }
    },
    "/ephemeris/dignities": {
      "post": {
        "description": "Mechanical endpoint returning essential dignity scores for Sun..Pluto.",
        "operationId": "dignities_ephemeris_dignities_post",
        "parameters": [
          {
            "deprecated": true,
            "description": "Deprecated: use preset+format. Accepts full|simple|llm.",
            "in": "query",
            "name": "output_mode",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Output Mode",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "preset",
            "required": false,
            "schema": {
              "default": "full",
              "pattern": "^(?i)(full|simple)$",
              "title": "Preset",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "format",
            "required": false,
            "schema": {
              "default": "json",
              "pattern": "^(?i)(json|llm)$",
              "title": "Format",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "authorization",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Authorization",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-Api-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-OpenEphemeris-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-OpenEphemeris-API-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "apikey",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Apikey",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DignitiesRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DignitiesResponse"
                }
              }
            },
            "description": "Dignities calculated successfully"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Invalid input"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Calculation error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Calculate essential dignities (granular)",
        "tags": [
          "ephemeris"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 1
      }
    },
    "/ephemeris/dispositor-tree": {
      "post": {
        "description": "Build a dispositor tree from a set of planetary sign placements. Each planet is \"disposed\" by the ruler of the sign it occupies. The algorithm walks these rulership chains to identify final dispositors (planets ruling their own sign) and mutual receptions (pairs disposing each other).\n\nNo ephemeris kernel required — pass in pre-computed sign placements. Signs are 0-based in the API (0=Aries … 11=Pisces) and converted internally.\n\n🤖 Agent-first endpoint — pure deterministic math, no ephemeris required.",
        "operationId": "calculate_dispositor_tree_ephemeris_dispositor_tree_post",
        "parameters": [
          {
            "deprecated": true,
            "description": "Deprecated: use preset+format. Accepts full|simple|llm.",
            "in": "query",
            "name": "output_mode",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Output Mode",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "format",
            "required": false,
            "schema": {
              "default": "json",
              "pattern": "^(?i)(json|llm)$",
              "title": "Format",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "authorization",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Authorization",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-Api-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-OpenEphemeris-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-OpenEphemeris-API-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "apikey",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Apikey",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DispositorTreeRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DispositorTreeResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          },
          "422": {
            "description": "Unprocessable Entity - Invalid input format"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Build dispositor tree from planetary placements",
        "tags": [
          "ephemeris"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 1
      }
    },
    "/ephemeris/draconic": {
      "post": {
        "description": "Calculates draconic chart with True Node as 0 Aries.",
        "operationId": "CalculateDraconicChart",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DraconicChartRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DraconicChartResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Calculate Draconic Chart",
        "tags": [
          "ephemeris"
        ]
      }
    },
    "/ephemeris/fixed-stars": {
      "post": {
        "description": "Calculate positions for fixed stars at a specific moment. Supports individual star names, predefined groups (royal_stars, behenian, navigational, foundation_24, galactic), and magnitude filtering. Returns ecliptic coordinates, proper motion, and metadata for each star. 🤖 AI-optimized output available — add `format=llm` to reduce payload ~60%.",
        "operationId": "calculate_fixed_stars_ephemeris_fixed_stars_post",
        "parameters": [
          {
            "deprecated": true,
            "description": "Deprecated: use preset+format. Accepts full|simple|llm.",
            "in": "query",
            "name": "output_mode",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Output Mode",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "preset",
            "required": false,
            "schema": {
              "default": "full",
              "pattern": "^(?i)(full|simple)$",
              "title": "Preset",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "format",
            "required": false,
            "schema": {
              "default": "json",
              "pattern": "^(?i)(json|llm|llm)$",
              "title": "Format",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "authorization",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Authorization",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-Api-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-OpenEphemeris-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-OpenEphemeris-API-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "apikey",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Apikey",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FixedStarsCalculationRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FixedStarsCalculationResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          },
          "422": {
            "description": "Unprocessable Entity - Invalid input format"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Fixed star position calculations",
        "tags": [
          "ephemeris"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 1
      }
    },
    "/ephemeris/harmonics": {
      "post": {
        "description": "Calculate harmonic chart positions by multiplying natal longitudes by a harmonic number N and reducing modulo 360°. Finds conjunctions in the harmonic space to reveal hidden aspect patterns.\n\nHarmonic analysis is the mathematical backbone of aspect theory: the 5th harmonic unfolds quintiles, the 7th reveals septiles, the 9th produces the Vedic navamsa. Higher harmonics expose increasingly subtle geometric relationships invisible in a standard chart wheel.\n\n🤖 Agent-first endpoint — pure deterministic math, no ephemeris required.",
        "operationId": "calculate_harmonics_ephemeris_harmonics_post",
        "parameters": [
          {
            "description": "Response format: json | llm.",
            "in": "query",
            "name": "format",
            "required": false,
            "schema": {
              "default": "json",
              "pattern": "^(?i)(json|llm)$",
              "title": "Format",
              "type": "string"
            }
          },
          {
            "deprecated": true,
            "description": "Deprecated: use format. Accepts full|simple|llm.",
            "in": "query",
            "name": "output_mode",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Output Mode",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/HarmonicsRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HarmonicsResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__predictive_schemas__ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Harmonic Chart Analysis",
        "tags": [
          "ephemeris"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 1
      }
    },
    "/ephemeris/hermetic-lots": {
      "post": {
        "description": "Calculate Hermetic lots (Fortune Suite + optional/legacy) for a given datetime and location. Returns normalized lot positions with traditional source references, formulas, and keywords. Includes sect determination (diurnal/nocturnal) and house placements. Follows standalone pattern: direct Julian Day calculation without chart context. Supports format=json|llm via query params.",
        "operationId": "calculate_hermetic_lots_ephemeris_hermetic_lots_post",
        "parameters": [
          {
            "deprecated": true,
            "description": "Deprecated: use preset+format. Accepts full|simple|llm.",
            "in": "query",
            "name": "output_mode",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Output Mode",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "preset",
            "required": false,
            "schema": {
              "default": "full",
              "pattern": "^(?i)(full|simple)$",
              "title": "Preset",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "format",
            "required": false,
            "schema": {
              "default": "json",
              "pattern": "^(?i)(json|llm|llm)$",
              "title": "Format",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "authorization",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Authorization",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-Api-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-OpenEphemeris-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-OpenEphemeris-API-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "apikey",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Apikey",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/HermeticLotsCalculationRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HermeticLotsCalculationResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          },
          "422": {
            "description": "Unprocessable Entity - Invalid input format"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Calculate Hermetic lots for datetime and location",
        "tags": [
          "ephemeris"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 1
      }
    },
    "/ephemeris/house-cusps": {
      "post": {
        "description": "Mechanical endpoint returning house cusps for up to 5 house systems.",
        "operationId": "house_cusps_ephemeris_house_cusps_post",
        "parameters": [
          {
            "deprecated": true,
            "description": "Deprecated: use preset+format. Accepts full|simple|llm.",
            "in": "query",
            "name": "output_mode",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Output Mode",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "preset",
            "required": false,
            "schema": {
              "default": "full",
              "pattern": "^(?i)(full|simple)$",
              "title": "Preset",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "format",
            "required": false,
            "schema": {
              "default": "json",
              "pattern": "^(?i)(json|llm)$",
              "title": "Format",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "authorization",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Authorization",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-Api-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-OpenEphemeris-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-OpenEphemeris-API-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "apikey",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Apikey",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/HouseCuspsRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HouseCuspsResponse"
                }
              }
            },
            "description": "House cusps calculated successfully"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Invalid input"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Calculation error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Calculate house cusps (granular)",
        "tags": [
          "ephemeris"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 1
      }
    },
    "/ephemeris/house-systems": {
      "get": {
        "description": "Get list of supported astrological house systems",
        "operationId": "get_supported_house_systems_ephemeris_house_systems_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "List of supported house systems"
          },
          "400": {
            "description": "Bad Request - Input validation failed"
          },
          "404": {
            "description": "Not found"
          },
          "422": {
            "description": "Unprocessable Entity - Invalid input format"
          },
          "500": {
            "description": "Internal Server Error - Calculation failed"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Get Supported House Systems",
        "tags": [
          "api-metadata"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 1
      }
    },
    "/ephemeris/lunar-phase": {
      "post": {
        "description": "Calculate the current lunar phase based on Sun-Moon elongation. Returns phase name/angle, illumination percentage, and lunation metadata (New Moon/Full Moon dates, day of lunation, void-of-course status). 🤖 AI-optimized output available — add `format=llm` to reduce payload ~50%.",
        "operationId": "calculate_lunar_phase_endpoint_ephemeris_lunar_phase_post",
        "parameters": [
          {
            "deprecated": true,
            "description": "Deprecated: use preset+format. Accepts full|simple|llm.",
            "in": "query",
            "name": "output_mode",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Output Mode",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "preset",
            "required": false,
            "schema": {
              "default": "full",
              "pattern": "^(?i)(full|simple)$",
              "title": "Preset",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "format",
            "required": false,
            "schema": {
              "default": "json",
              "pattern": "^(?i)(json|llm|llm)$",
              "title": "Format",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "authorization",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Authorization",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-Api-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-OpenEphemeris-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-OpenEphemeris-API-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "apikey",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Apikey",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LunarPhaseCalculationRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LunarPhaseCalculationResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          },
          "422": {
            "description": "Unprocessable Entity - Invalid input format"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Calculate lunar phase for datetime",
        "tags": [
          "ephemeris"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 1
      }
    },
    "/ephemeris/midpoints": {
      "post": {
        "description": "Calculate zodiacal midpoints from planetary longitudes, detecting conjunctions and oppositions to sensitive points. Supports sort-by-type, tree grouping, and dial-degree formatting. 🤖 AI-optimized output available — add `format=llm` to reduce payload ~65%.",
        "operationId": "calculate_midpoints_ephemeris_midpoints_post",
        "parameters": [
          {
            "deprecated": true,
            "description": "Deprecated: use preset+format. Accepts full|simple|llm.",
            "in": "query",
            "name": "output_mode",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Output Mode",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "preset",
            "required": false,
            "schema": {
              "default": "full",
              "pattern": "^(?i)(full|simple)$",
              "title": "Preset",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "format",
            "required": false,
            "schema": {
              "default": "json",
              "pattern": "^(?i)(json|llm|llm)$",
              "title": "Format",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "authorization",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Authorization",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-Api-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-OpenEphemeris-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-OpenEphemeris-API-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "apikey",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Apikey",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MidpointsCalculationRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MidpointsCalculationResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          },
          "422": {
            "description": "Unprocessable Entity - Invalid input format"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Calculate midpoints for datetime",
        "tags": [
          "ephemeris"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 1
      }
    },
    "/ephemeris/moon/aspects": {
      "get": {
        "description": "Returns all current Moon aspects to traditional planets with **applying/separating classification**.\n\n**Performance:** 15-30ms\n\n**Aspect Classification:**\n- **Applying:** Moon approaching exact aspect (energies building)\n- **Separating:** Moon departing from exact aspect (energies waning)\n- Classification based on Moon vs planet speeds (Moon moves ~13°/day, faster than any planet)\n\n**Orb System:** Fixed traditional orbs (no custom orbs in v1)\n- Major aspects: Conjunction, Opposition, Square, Trine, Sextile\n- Minor aspects: Semi-sextile, Quincunx (optional via include_minor parameter)\n\n**Planets Checked:** Sun, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto\n\n**Use Cases:**\n- \"What aspects is the Moon making right now?\"\n- Moon aspect tracking for timing decisions\n- Lunar aspect calendars\n- Real-time lunar energy awareness\n\n**Example:**\n```bash\nGET /ephemeris/moon/aspects?datetime=2025-12-11T12:00:00Z\u0026include_minor=false\n```",
        "operationId": "get_moon_aspects_endpoint_ephemeris_moon_aspects_get",
        "parameters": [
          {
            "description": "ISO 8601 datetime",
            "example": "2025-12-11T12:00:00Z",
            "in": "query",
            "name": "datetime",
            "required": true,
            "schema": {
              "description": "ISO 8601 datetime",
              "title": "Datetime",
              "type": "string"
            }
          },
          {
            "description": "Zodiac mode: 'tropical' or 'sidereal'",
            "in": "query",
            "name": "zodiac_mode",
            "required": false,
            "schema": {
              "default": "tropical",
              "description": "Zodiac mode: 'tropical' or 'sidereal'",
              "pattern": "^(tropical|sidereal)$",
              "title": "Zodiac Mode",
              "type": "string"
            }
          },
          {
            "description": "Include minor aspects (semi-sextile, quincunx)",
            "in": "query",
            "name": "include_minor",
            "required": false,
            "schema": {
              "default": false,
              "description": "Include minor aspects (semi-sextile, quincunx)",
              "title": "Include Minor",
              "type": "boolean"
            }
          },
          {
            "description": "Response format: json | llm.",
            "in": "query",
            "name": "format",
            "required": false,
            "schema": {
              "default": "json",
              "description": "Response format: json | llm.",
              "pattern": "^(?i)(json|llm|llm)$",
              "title": "Format",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "authorization",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Authorization",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-Api-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-OpenEphemeris-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-OpenEphemeris-API-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "apikey",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Apikey",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MoonAspectsResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          },
          "422": {
            "description": "Unprocessable Entity - Invalid input format"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Get current Moon aspects",
        "tags": [
          "lunar"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 1
      }
    },
    "/ephemeris/moon/ingresses": {
      "get": {
        "description": "Returns all Moon sign ingress events within a date range.\n\n**Moon Ingress Frequency:** ~13 ingresses per month (Moon changes signs every ~2.5 days)\n\n**Performance:** \u003c5ms (cached), 50-100ms (cache miss)  \nCache is **pre-warmed for ±3 months** on startup and **refreshed daily at 00:01 UTC**.\n\n**Cache Strategy:**\n- Tropical and sidereal ingresses cached separately (different times due to ~24° ayanamsa offset)\n- Redis backend with 30-day TTL\n- Rolling 3-month window maintained automatically\n- Graceful fallback to live calculation if cache miss\n- Startup health check reports cache status\n\n**Use Cases:**\n- Monthly lunar calendars\n- \"Best days for haircuts\" timing apps\n- Moon sign tracking applications\n- Gardening/manifestation by Moon sign\n- Electional astrology lookups\n\n**Rate Limiting:** Max 90-day range per query to prevent abuse.\n\n**Example:**\n```bash\nGET /ephemeris/moon/ingresses?start_date=2025-12-01T00:00:00Z\u0026end_date=2025-12-31T23:59:59Z\u0026zodiac_mode=tropical\n```",
        "operationId": "get_moon_ingresses_endpoint_ephemeris_moon_ingresses_get",
        "parameters": [
          {
            "description": "Range start date (ISO 8601 format)",
            "example": "2025-12-01T00:00:00Z",
            "in": "query",
            "name": "start_date",
            "required": true,
            "schema": {
              "description": "Range start date (ISO 8601 format)",
              "title": "Start Date",
              "type": "string"
            }
          },
          {
            "description": "Range end date (ISO 8601 format, max 90 days from start)",
            "example": "2025-12-31T23:59:59Z",
            "in": "query",
            "name": "end_date",
            "required": true,
            "schema": {
              "description": "Range end date (ISO 8601 format, max 90 days from start)",
              "title": "End Date",
              "type": "string"
            }
          },
          {
            "description": "Zodiac mode: 'tropical' or 'sidereal'",
            "in": "query",
            "name": "zodiac_mode",
            "required": false,
            "schema": {
              "default": "tropical",
              "description": "Zodiac mode: 'tropical' or 'sidereal'",
              "pattern": "^(tropical|sidereal)$",
              "title": "Zodiac Mode",
              "type": "string"
            }
          },
          {
            "description": "Response format: json | llm.",
            "in": "query",
            "name": "format",
            "required": false,
            "schema": {
              "default": "json",
              "description": "Response format: json | llm.",
              "pattern": "^(?i)(json|llm|llm)$",
              "title": "Format",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "authorization",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Authorization",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-Api-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-OpenEphemeris-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-OpenEphemeris-API-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "apikey",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Apikey",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MoonIngressesResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          },
          "422": {
            "description": "Unprocessable Entity - Invalid input format"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Get Moon sign ingresses for date range",
        "tags": [
          "lunar"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 1
      }
    },
    "/ephemeris/moon/phase": {
      "get": {
        "description": "Returns lunar phase information for a specific datetime.\n\n**Performance:** \u003c10ms (trigonometric calculation via SuperNOVAS / Calceph)\n\n**Phase Names:** \n- New Moon\n- Waxing Crescent\n- First Quarter\n- Waxing Gibbous\n- Full Moon\n- Waning Gibbous\n- Last Quarter\n- Waning Crescent\n\n**Data Returned:**\n- Phase name and illumination percentage (0-100%)\n- Sun-Moon elongation angle (0-360°)\n- Waxing/waning classification\n- Moon age in days (~0-29.53 day cycle)\n- Moon distance from Earth (km)\n- Moon angular diameter (degrees)\n\n**Use Cases:**\n- Daily lunar calendars\n- Gardening by Moon phase (Full Moon planting, etc.)\n- Manifestation/ritual timing (New Moon intentions, Full Moon releases)\n- General lunar awareness apps\n- Fishing/hunting activity timing\n\n**Example:**\n```bash\nGET /ephemeris/moon/phase?datetime=2025-12-11T12:00:00Z\n```",
        "operationId": "get_lunar_phase_endpoint_ephemeris_moon_phase_get",
        "parameters": [
          {
            "description": "ISO 8601 datetime",
            "example": "2025-12-11T12:00:00Z",
            "in": "query",
            "name": "datetime",
            "required": true,
            "schema": {
              "description": "ISO 8601 datetime",
              "title": "Datetime",
              "type": "string"
            }
          },
          {
            "description": "Response format: json | llm.",
            "in": "query",
            "name": "format",
            "required": false,
            "schema": {
              "default": "json",
              "description": "Response format: json | llm.",
              "pattern": "^(?i)(json|llm|llm)$",
              "title": "Format",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "authorization",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Authorization",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-Api-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-OpenEphemeris-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-OpenEphemeris-API-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "apikey",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Apikey",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LunarPhaseResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          },
          "422": {
            "description": "Unprocessable Entity - Invalid input format"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Get lunar phase",
        "tags": [
          "lunar"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 1
      }
    },
    "/ephemeris/moon/void-of-course": {
      "get": {
        "description": "Returns Void of Course Moon status for a specific datetime using **Method 3 definition**.\n\n**Void of Course (VoC) Definition:**  \nMoon is VoC when it makes no major aspects (conjunction, opposition, square, trine, sextile)\nto traditional planets (Sun through Pluto) before changing zodiac signs.\n\n**Method 3 Logic:**\n- VoC period **cannot start before** Moon's last sign ingress\n- Searches backwards from next ingress for last major aspect (COQTS)\n- If no aspects found, VoC starts at previous ingress (calendar-accurate)\n- Uses fixed traditional orbs (no custom orbs in v1)\n\n**Performance:** 20-50ms (aspect search + ingress calculation)\n\n**Use Cases:**\n- Electional astrology: \"Is now a good time to sign contracts?\"\n- Daily VoC calendars for timing decisions\n- Timing-sensitive decision support tools\n\n**Example:**\n```bash\nGET /ephemeris/moon/void-of-course?datetime=2025-12-11T12:00:00Z\u0026zodiac_mode=tropical\n```",
        "operationId": "get_void_of_course_endpoint_ephemeris_moon_void_of_course_get",
        "parameters": [
          {
            "description": "ISO 8601 datetime (e.g., '2025-12-11T12:00:00Z')",
            "example": "2025-12-11T12:00:00Z",
            "in": "query",
            "name": "datetime",
            "required": true,
            "schema": {
              "description": "ISO 8601 datetime (e.g., '2025-12-11T12:00:00Z')",
              "title": "Datetime",
              "type": "string"
            }
          },
          {
            "description": "Zodiac mode: 'tropical' or 'sidereal'",
            "in": "query",
            "name": "zodiac_mode",
            "required": false,
            "schema": {
              "default": "tropical",
              "description": "Zodiac mode: 'tropical' or 'sidereal'",
              "pattern": "^(tropical|sidereal)$",
              "title": "Zodiac Mode",
              "type": "string"
            }
          },
          {
            "description": "Response format: json | llm.",
            "in": "query",
            "name": "format",
            "required": false,
            "schema": {
              "default": "json",
              "description": "Response format: json | llm.",
              "pattern": "^(?i)(json|llm|llm)$",
              "title": "Format",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "authorization",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Authorization",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-Api-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-OpenEphemeris-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-OpenEphemeris-API-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "apikey",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Apikey",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VoidOfCourseResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          },
          "422": {
            "description": "Unprocessable Entity - Invalid input format"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Get Void of Course Moon status",
        "tags": [
          "lunar"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 1
      }
    },
    "/ephemeris/natal-chart": {
      "post": {
        "description": "Calculate a comprehensive natal chart with optional enhanced features.\n    \n    **Features**\n    - Core: Planetary positions, houses, angles.\n    - Enhanced: Aspects, patterns, midpoints, harmonics, fixed stars, Arabic parts, dignities.\n    - Output modes: `full` (default), `simple` (core only), `llm` (AI-optimized).\n    \n    **Input Flexibility**\n    - Coordinates: decimal degrees, DMS strings, or component objects\n    - DateTime: ISO-8601 strings, Julian Day, or component objects\n    - Timezone: IANA names, UTC offsets, or auto-detection\n    \n    Legacy request fields (e.g., custom orb tables) are safely ignored under the simplified contract but remain accepted for compatibility.\n    \n    🤖 **AI-optimized output** available — add `format=llm` to reduce payload ~75%.",
        "operationId": "calculate_natal_chart_enhanced_ephemeris_natal_chart_post",
        "parameters": [
          {
            "deprecated": true,
            "description": "Deprecated: use preset+format. Accepts full|simple|llm.",
            "in": "query",
            "name": "output_mode",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Output Mode",
              "type": "string"
            }
          },
          {
            "description": "Computation preset: full | simple. Controls what is computed (pre-calculation).",
            "in": "query",
            "name": "preset",
            "required": false,
            "schema": {
              "default": "full",
              "description": "Computation preset: full | simple. Controls what is computed (pre-calculation).",
              "pattern": "^(?i)(full|simple)$",
              "title": "Preset",
              "type": "string"
            }
          },
          {
            "description": "Response format: json | llm. Controls response projection only.",
            "in": "query",
            "name": "format",
            "required": false,
            "schema": {
              "default": "json",
              "description": "Response format: json | llm. Controls response projection only.",
              "pattern": "^(?i)(json|llm)$",
              "title": "Format",
              "type": "string"
            }
          },
          {
            "deprecated": true,
            "description": "Deprecated: prefer request body `options.include_metadata`.",
            "in": "query",
            "name": "include_metadata",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Include Metadata",
              "type": "boolean"
            }
          },
          {
            "deprecated": true,
            "description": "Deprecated: prefer request body `options.trim_precision`.",
            "in": "query",
            "name": "trim_precision",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Trim Precision",
              "type": "boolean"
            }
          },
          {
            "deprecated": true,
            "description": "Deprecated: prefer request body `options.include_houses`.",
            "in": "query",
            "name": "include_houses",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Include Houses",
              "type": "boolean"
            }
          },
          {
            "deprecated": true,
            "description": "Deprecated: prefer request body `options.include_aspects`.",
            "in": "query",
            "name": "include_aspects",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Include Aspects",
              "type": "boolean"
            }
          },
          {
            "deprecated": true,
            "description": "Deprecated: prefer request body `options.include_dignities`.",
            "in": "query",
            "name": "include_dignities",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Include Dignities",
              "type": "boolean"
            }
          },
          {
            "deprecated": true,
            "description": "Deprecated: prefer request body `enhanced_options.include_hermetic_lots` (or legacy `options.include_hermetic_lots`).",
            "in": "query",
            "name": "include_hermetic_lots",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Include Hermetic Lots",
              "type": "boolean"
            }
          },
          {
            "deprecated": true,
            "description": "Deprecated: prefer request body `options.decimal_places`.",
            "in": "query",
            "name": "decimal_places",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Decimal Places",
              "type": "integer"
            }
          },
          {
            "deprecated": true,
            "description": "Deprecated: prefer request body `options.angle_format`.",
            "in": "query",
            "name": "angle_format",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Angle Format",
              "type": "string"
            }
          },
          {
            "deprecated": true,
            "description": "Deprecated: prefer request body `options.declination_orb`.",
            "in": "query",
            "name": "declination_orb",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Declination Orb",
              "type": "number"
            }
          },
          {
            "deprecated": true,
            "description": "Deprecated: prefer request body `options.include_true_lilith`.",
            "in": "query",
            "name": "include_true_lilith",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Include True Lilith",
              "type": "boolean"
            }
          },
          {
            "deprecated": true,
            "description": "Deprecated: prefer request body `options.echo_top_level`.",
            "in": "query",
            "name": "echo_top_level",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Echo Top Level",
              "type": "boolean"
            }
          },
          {
            "in": "header",
            "name": "authorization",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Authorization",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-Api-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-OpenEphemeris-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-OpenEphemeris-API-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "apikey",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Apikey",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/NatalChartEnhancedRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NatalChartEnhancedResponse"
                }
              }
            },
            "description": "Successful enhanced chart calculation"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Input validation error"
          },
          "422": {
            "description": "Unprocessable Entity - Invalid input format"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Chart calculation error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Enhanced Natal Chart Calculation",
        "tags": [
          "ephemeris"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 1
      }
    },
    "/ephemeris/natal/batch": {
      "post": {
        "description": "Compute multiple natal charts in a single request with shared guardrails. 🤖 AI-optimized output available — add `format=llm` to reduce payload ~80%.",
        "operationId": "calculate_natal_batch_ephemeris_natal_batch_post",
        "parameters": [
          {
            "deprecated": true,
            "description": "Deprecated: use preset+format. Accepts full|simple|llm.",
            "in": "query",
            "name": "output_mode",
            "required": false,
            "schema": {
              "description": "Deprecated: use preset+format. Accepts full|simple|llm.",
              "title": "Output Mode",
              "type": "string",
              "x-ui-hidden": true
            }
          },
          {
            "in": "query",
            "name": "preset",
            "required": false,
            "schema": {
              "default": "full",
              "pattern": "^(?i)(full|simple)$",
              "title": "Preset",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "format",
            "required": false,
            "schema": {
              "default": "json",
              "pattern": "^(?i)(json|llm|llm)$",
              "title": "Format",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "authorization",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Authorization",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-Api-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-OpenEphemeris-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-OpenEphemeris-API-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "apikey",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Apikey",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/NatalBatchRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NatalBatchResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          },
          "422": {
            "description": "Unprocessable Entity - Invalid input format"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Batch natal calculations",
        "tags": [
          "ephemeris"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Startup",
        "x-meridian-units": 1
      }
    },
    "/ephemeris/planet-position": {
      "post": {
        "description": "Lightweight endpoint for retrieving a single planet's position at a specific time. Supports both geocentric (default) and topocentric (with latitude/longitude) calculations.",
        "operationId": "planet_position_ephemeris_planet_position_post",
        "parameters": [
          {
            "deprecated": true,
            "description": "Deprecated: use preset+format. Accepts full|simple|llm.",
            "in": "query",
            "name": "output_mode",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Output Mode",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "preset",
            "required": false,
            "schema": {
              "default": "full",
              "pattern": "^(?i)(full|simple)$",
              "title": "Preset",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "format",
            "required": false,
            "schema": {
              "default": "json",
              "pattern": "^(?i)(json|llm)$",
              "title": "Format",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "authorization",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Authorization",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-Api-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-OpenEphemeris-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-OpenEphemeris-API-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "apikey",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Apikey",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PlanetPositionRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlanetPositionResponse"
                }
              }
            },
            "description": "Planet position calculated successfully"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Invalid input (e.g., unknown planet_id)"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Calculation error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Get single planet position",
        "tags": [
          "ephemeris"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 1
      }
    },
    "/ephemeris/prenatal-lunation": {
      "post": {
        "description": "Calculates the prenatal new and full moon for a subject.",
        "operationId": "CalculatePrenatalLunation",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PrenatalLunationRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PrenatalLunationResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Calculate Prenatal Lunation",
        "tags": [
          "ephemeris"
        ]
      }
    },
    "/ephemeris/progressed": {
      "post": {
        "description": "Return progressed positions, aspects, and metadata for a subject. Supports Secondary (Naibod), Tertiary, and Solar Arc methods. 🤖 **AI-optimized output** available — add \format=llm to reduce payload ~70%.",
        "operationId": "calculate_progressed_chart_ephemeris_progressed_post",
        "parameters": [
          {
            "deprecated": true,
            "description": "Deprecated: use preset+format. Accepts full|simple|llm.",
            "in": "query",
            "name": "output_mode",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Output Mode",
              "type": "string"
            }
          },
          {
            "description": "Computation preset: full | simple. For non-full formats this controls what is computed (pre-calculation).",
            "in": "query",
            "name": "preset",
            "required": false,
            "schema": {
              "default": "full",
              "description": "Computation preset: full | simple. For non-full formats this controls what is computed (pre-calculation).",
              "pattern": "^(?i)(full|simple)$",
              "title": "Preset",
              "type": "string"
            }
          },
          {
            "description": "Response format: json | llm.",
            "in": "query",
            "name": "format",
            "required": false,
            "schema": {
              "default": "json",
              "description": "Response format: json | llm.",
              "pattern": "^(?i)(json|llm|llm)$",
              "title": "Format",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "authorization",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Authorization",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-Api-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-OpenEphemeris-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-OpenEphemeris-API-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "apikey",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Apikey",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ProgressedChartRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProgressedChartResponse"
                }
              }
            },
            "description": "Successful progressed chart calculation"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Input validation error"
          },
          "422": {
            "description": "Unprocessable Entity - Invalid input format"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Calculation or internal error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Calculate progressed chart (Secondary, Tertiary, Solar Arc)",
        "tags": [
          "predictive"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 1
      }
    },
    "/ephemeris/relocation": {
      "post": {
        "description": "Return angles, house cusps, and planet house changes for a relocated chart. 🤖 AI-optimized output available — add `format=llm` to reduce payload ~55%.",
        "operationId": "relocation_chart_endpoint_ephemeris_relocation_post",
        "parameters": [
          {
            "description": "Response format: json | llm.",
            "in": "query",
            "name": "format",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Format",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "authorization",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Authorization",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-Api-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-OpenEphemeris-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-OpenEphemeris-API-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "apikey",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Apikey",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RelocationRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RelocationResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "description": "Bad Request - Input validation failed"
          },
          "422": {
            "description": "Unprocessable Entity - Invalid input format"
          },
          "500": {
            "description": "Internal Server Error - Calculation failed"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Calculate relocation chart",
        "tags": [
          "ephemeris"
        ],
        "x-meridian-status": "beta",
        "x-meridian-tier": "Developer",
        "x-meridian-units": 1
      }
    },
    "/ephemeris/retrograde-status": {
      "post": {
        "description": "Lightweight endpoint for determining whether a planet is retrograde at a specific time. Returns motion type (direct/retrograde/stationary) and speed data.",
        "operationId": "retrograde_status_ephemeris_retrograde_status_post",
        "parameters": [
          {
            "deprecated": true,
            "description": "Deprecated: use preset+format. Accepts full|simple|llm.",
            "in": "query",
            "name": "output_mode",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Output Mode",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "preset",
            "required": false,
            "schema": {
              "default": "full",
              "pattern": "^(?i)(full|simple)$",
              "title": "Preset",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "format",
            "required": false,
            "schema": {
              "default": "json",
              "pattern": "^(?i)(json|llm)$",
              "title": "Format",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "authorization",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Authorization",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-Api-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-OpenEphemeris-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-OpenEphemeris-API-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "apikey",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Apikey",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RetrogradeStatusRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RetrogradeStatusResponse"
                }
              }
            },
            "description": "Retrograde status determined successfully"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Invalid input (e.g., unknown planet_id)"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Calculation error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Check planet retrograde status",
        "tags": [
          "ephemeris"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 1
      }
    },
    "/ephemeris/schemas/natal-request": {
      "get": {
        "description": "Get JSON schema for natal chart request format",
        "operationId": "get_natal_request_schema_ephemeris_schemas_natal_request_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "JSON schema for natal chart requests"
          },
          "400": {
            "description": "Bad Request - Input validation failed"
          },
          "404": {
            "description": "Not found"
          },
          "422": {
            "description": "Unprocessable Entity - Invalid input format"
          },
          "500": {
            "description": "Internal Server Error - Calculation failed"
          }
        },
        "security": [],
        "summary": "Get Natal Chart Request Schema",
        "tags": [
          "api-metadata"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 1
      }
    },
    "/ephemeris/schemas/natal-response": {
      "get": {
        "description": "Get JSON schema for natal chart response format",
        "operationId": "get_natal_response_schema_ephemeris_schemas_natal_response_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "JSON schema for natal chart responses"
          },
          "400": {
            "description": "Bad Request - Input validation failed"
          },
          "404": {
            "description": "Not found"
          },
          "422": {
            "description": "Unprocessable Entity - Invalid input format"
          },
          "500": {
            "description": "Internal Server Error - Calculation failed"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Get Natal Chart Response Schema",
        "tags": [
          "api-metadata"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 1
      }
    },
    "/ephemeris/supported-metadata": {
      "get": {
        "description": "Get canonical metadata lookups used by calculations (sign elements/modalities, supported enums like dignity systems, house systems, node sources, etc.).",
        "operationId": "get_supported_metadata_ephemeris_supported_metadata_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "Supported metadata"
          },
          "400": {
            "description": "Bad Request - Input validation failed"
          },
          "404": {
            "description": "Not found"
          },
          "422": {
            "description": "Unprocessable Entity - Invalid input format"
          },
          "500": {
            "description": "Internal Server Error - Calculation failed"
          }
        },
        "security": [],
        "summary": "Get Supported Metadata",
        "tags": [
          "api-metadata"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 1
      }
    },
    "/ephemeris/supported-objects": {
      "get": {
        "description": "Get list of supported celestial objects in calculations",
        "operationId": "get_supported_objects_ephemeris_supported_objects_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "Supported celestial objects"
          },
          "400": {
            "description": "Bad Request - Input validation failed"
          },
          "404": {
            "description": "Not found"
          },
          "422": {
            "description": "Unprocessable Entity - Invalid input format"
          },
          "500": {
            "description": "Internal Server Error - Calculation failed"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Get Supported Celestial Objects",
        "tags": [
          "api-metadata"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 1
      }
    },
    "/ephemeris/venus-star-points": {
      "post": {
        "description": "Compute the five Venus Star Point events (conjunctions of Venus and Sun around birth). Returns a list of five ConjunctionEvent objects: three occurring before birth and two after. Includes extended metadata such as zodiac dignity, visibility phase, and combustion status. 🤖 AI-optimized output available — add `format=llm` to reduce payload ~60%.",
        "operationId": "get_venus_star_points_ephemeris_venus_star_points_post",
        "parameters": [
          {
            "description": "Response format: json | llm.",
            "in": "query",
            "name": "format",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Format",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "ephemeris_service",
            "required": false,
            "schema": {
              "title": "Ephemeris Service"
            }
          },
          {
            "in": "header",
            "name": "authorization",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Authorization",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-Api-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-OpenEphemeris-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-OpenEphemeris-API-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "apikey",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Apikey",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VenusStarPointsRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VenusStarPointsResponse"
                }
              }
            },
            "description": "Venus Star Points calculated successfully"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Invalid input validation"
          },
          "422": {
            "description": "Unprocessable Entity - Invalid input format"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Calculation failed"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Compute Venus Star Points",
        "tags": [
          "venus-cycles"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 1
      }
    },
    "/ephemeris/venus-star-points/conjunctions": {
      "post": {
        "description": "Find all Venus-Sun conjunctions in a specific date range. 🤖 AI-optimized output available — add `format=llm` to reduce payload ~60%.",
        "operationId": "get_venus_conjunctions_ephemeris_venus_star_points_conjunctions_post",
        "parameters": [
          {
            "description": "Response format: json | llm.",
            "in": "query",
            "name": "format",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Format",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "ephemeris_service",
            "required": false,
            "schema": {
              "title": "Ephemeris Service"
            }
          },
          {
            "in": "header",
            "name": "authorization",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Authorization",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-Api-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-OpenEphemeris-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-OpenEphemeris-API-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "apikey",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Apikey",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VenusRangeRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VenusConjunctionsResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "description": "Bad Request - Input validation failed"
          },
          "422": {
            "description": "Unprocessable Entity - Invalid input format"
          },
          "500": {
            "description": "Internal Server Error - Calculation failed"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Range-based Venus conjunctions",
        "tags": [
          "venus-cycles"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 1
      }
    },
    "/ephemeris/venus-star-points/eight-year-star": {
      "post": {
        "description": "Compute the 5-point star pattern surrounding a specific date. 🤖 AI-optimized output available — add `format=llm` to reduce payload ~60%.",
        "operationId": "get_eight_year_star_ephemeris_venus_star_points_eight_year_star_post",
        "parameters": [
          {
            "description": "Response format: json | llm.",
            "in": "query",
            "name": "format",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Format",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "ephemeris_service",
            "required": false,
            "schema": {
              "title": "Ephemeris Service"
            }
          },
          {
            "in": "header",
            "name": "authorization",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Authorization",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-Api-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-OpenEphemeris-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-OpenEphemeris-API-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "apikey",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Apikey",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VenusDateRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VenusEightYearStarResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "description": "Bad Request - Input validation failed"
          },
          "422": {
            "description": "Unprocessable Entity - Invalid input format"
          },
          "500": {
            "description": "Internal Server Error - Calculation failed"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Venus 8-year star pattern",
        "tags": [
          "venus-cycles"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 1
      }
    },
    "/ephemeris/venus-star-points/elongations": {
      "post": {
        "description": "Find all Venus greatest elongations in a date range. 🤖 AI-optimized output available — add `format=llm` to reduce payload ~60%.",
        "operationId": "get_venus_elongations_ephemeris_venus_star_points_elongations_post",
        "parameters": [
          {
            "description": "Response format: json | llm.",
            "in": "query",
            "name": "format",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Format",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "ephemeris_service",
            "required": false,
            "schema": {
              "title": "Ephemeris Service"
            }
          },
          {
            "in": "header",
            "name": "authorization",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Authorization",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-Api-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-OpenEphemeris-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-OpenEphemeris-API-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "apikey",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Apikey",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VenusRangeRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VenusElongationsResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "description": "Bad Request - Input validation failed"
          },
          "422": {
            "description": "Unprocessable Entity - Invalid input format"
          },
          "500": {
            "description": "Internal Server Error - Calculation failed"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Venus greatest elongations",
        "tags": [
          "venus-cycles"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 1
      }
    },
    "/ephemeris/venus-star-points/phase": {
      "post": {
        "description": "Compute current visibility and cycle phase for Venus. 🤖 AI-optimized output available — add `format=llm` to reduce payload ~60%.",
        "operationId": "get_venus_phase_ephemeris_venus_star_points_phase_post",
        "parameters": [
          {
            "description": "Response format: json | llm.",
            "in": "query",
            "name": "format",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Format",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "ephemeris_service",
            "required": false,
            "schema": {
              "title": "Ephemeris Service"
            }
          },
          {
            "in": "header",
            "name": "authorization",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Authorization",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-Api-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-OpenEphemeris-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-OpenEphemeris-API-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "apikey",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Apikey",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VenusDateRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VenusPhaseResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "description": "Bad Request - Input validation failed"
          },
          "422": {
            "description": "Unprocessable Entity - Invalid input format"
          },
          "500": {
            "description": "Internal Server Error - Calculation failed"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Venus phase and visibility",
        "tags": [
          "venus-cycles"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 1
      }
    },
    "/ephemeris/venus-star-points/stations": {
      "post": {
        "description": "Find all Venus stationary points (Retrograde/Direct) in range. 🤖 AI-optimized output available — add `format=llm` to reduce payload ~60%.",
        "operationId": "get_venus_stations_ephemeris_venus_star_points_stations_post",
        "parameters": [
          {
            "description": "Response format: json | llm.",
            "in": "query",
            "name": "format",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Format",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "ephemeris_service",
            "required": false,
            "schema": {
              "title": "Ephemeris Service"
            }
          },
          {
            "in": "header",
            "name": "authorization",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Authorization",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-Api-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-OpenEphemeris-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-OpenEphemeris-API-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "apikey",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Apikey",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VenusRangeRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VenusStationsResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "description": "Bad Request - Input validation failed"
          },
          "422": {
            "description": "Unprocessable Entity - Invalid input format"
          },
          "500": {
            "description": "Internal Server Error - Calculation failed"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Venus station points",
        "tags": [
          "venus-cycles"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 1
      }
    },
    "/health": {
      "get": {
        "description": "Basic health check for the entire API service.",
        "operationId": "global_health_check_health_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "Successful Response"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "Service Unavailable - readiness check failed"
          }
        },
        "security": [],
        "summary": "Global Health Check",
        "tags": [
          "health"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 0
      }
    },
    "/health/detailed": {
      "get": {
        "description": "Comprehensive health check with dependency status validation.",
        "operationId": "detailed_health_check_health_detailed_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "Successful Response"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "Service Unavailable - readiness check failed"
          }
        },
        "security": [],
        "summary": "Detailed Health Check",
        "tags": [
          "health"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 0
      }
    },
    "/human-design/chart": {
      "post": {
        "description": "Generate a full Human Design bodygraph.\n\nRequires 'service' tier or admin access (Beta).",
        "operationId": "create_human_design_chart_human_design_chart_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/HumanDesignChartRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HumanDesignResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Create Human Design Chart",
        "tags": [
          "Human Design"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 2
      }
    },
    "/human-design/composite": {
      "post": {
        "description": "Generate a Composite / Relationship Chart.\nAnalyzes Electromagnetic connection, Split definition bridging, etc.",
        "operationId": "human_design_composite_human_design_composite_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/HumanDesignCompositeRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HumanDesignCompositeResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Human Design Composite",
        "tags": [
          "Human Design"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 2
      }
    },
    "/human-design/cycles/opposition": {
      "post": {
        "description": "Calculate the Human Design chart at the moment a planet opposes its natal position (180°).\nMost commonly used for Uranus Opposition (~age 42), Saturn Opposition (~age 14-15, ~44), and Jupiter Opposition (~age 6, ~18, ~30).",
        "operationId": "opposition_chart_human_design_cycles_opposition_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/app__api__routes__human_design__OppositionRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HumanDesignResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Planetary Opposition Chart",
        "tags": [
          "Human Design"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 2
      }
    },
    "/human-design/cycles/return": {
      "post": {
        "description": "Calculate a Human Design chart at the moment any planet returns to its natal longitude.\nSupports all major HD-relevant planets: sun, moon, mars, jupiter, saturn, chiron, uranus.",
        "operationId": "planetary_return_chart_human_design_cycles_return_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/app__api__routes__human_design__PlanetaryReturnRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HumanDesignResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Planetary Return Chart",
        "tags": [
          "Human Design"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 2
      }
    },
    "/human-design/cycles/solar-return": {
      "post": {
        "description": "Calculate a Solar Return Chart for a specific year.\nDetermines exact moment Sun returns to natal degree, then runs a full chart.",
        "operationId": "solar_return_chart_human_design_cycles_solar_return_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/app__api__routes__human_design__SolarReturnRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HumanDesignResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Solar Return Chart",
        "tags": [
          "Human Design"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 2
      }
    },
    "/human-design/penta": {
      "post": {
        "description": "Generate a Penta (Group Dynamics) Analysis.\nValid for groups of 3 to 5 people.\nFocuses on trans-auric forms (BG5).",
        "operationId": "human_design_penta_human_design_penta_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PentaRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PentaResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Human Design Penta",
        "tags": [
          "Human Design"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 2
      }
    },
    "/human-design/transit": {
      "post": {
        "description": "Get current Human Design planetary transit field (Neutrino Weather).\nReturns only personality activations (no design/type calculation).",
        "operationId": "human_design_transit_human_design_transit_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/HumanDesignTransitRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "title": "Response Human Design Transit Human Design Transit Post",
                  "type": "object"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Human Design Transit",
        "tags": [
          "Human Design"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 2
      }
    },
    "/location/autocomplete": {
      "get": {
        "description": "Returns location suggestions with coordinates and timezone for typeahead search. Results are cached according to backend cache configuration.",
        "operationId": "autocomplete_location_location_autocomplete_get",
        "parameters": [
          {
            "description": "Search query (city name, address, etc.)",
            "in": "query",
            "name": "query",
            "required": true,
            "schema": {
              "description": "Search query (city name, address, etc.)",
              "example": "San Francisco",
              "maxLength": 100,
              "minLength": 2,
              "title": "Query",
              "type": "string"
            }
          },
          {
            "description": "Maximum number of suggestions to return",
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 5,
              "description": "Maximum number of suggestions to return",
              "maximum": 10,
              "minimum": 1,
              "title": "Limit",
              "type": "integer"
            }
          },
          {
            "description": "Place types: place (cities), address, poi",
            "in": "query",
            "name": "types",
            "required": false,
            "schema": {
              "default": "place",
              "description": "Place types: place (cities), address, poi",
              "example": "place",
              "title": "Types",
              "type": "string"
            }
          },
          {
            "description": "Optional ISO country code filter (e.g., US, GB)",
            "in": "query",
            "name": "country",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Country",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "authorization",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Authorization",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-Api-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-OpenEphemeris-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-OpenEphemeris-API-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "apikey",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Apikey",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LocationAutocompleteResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "description": "Bad Request - Invalid parameters"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "503": {
            "description": "Service Unavailable - Geocoding provider down"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Search for locations by name",
        "tags": [
          "location-timezone"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 1
      }
    },
    "/location/reverse": {
      "get": {
        "description": "Convert latitude/longitude to a human-readable location with timezone.",
        "operationId": "reverse_geocode_location_reverse_get",
        "parameters": [
          {
            "description": "Latitude in decimal degrees",
            "in": "query",
            "name": "lat",
            "required": true,
            "schema": {
              "description": "Latitude in decimal degrees",
              "example": 40.7128,
              "maximum": 90,
              "minimum": -90,
              "title": "Lat",
              "type": "number"
            }
          },
          {
            "description": "Longitude in decimal degrees",
            "in": "query",
            "name": "lng",
            "required": true,
            "schema": {
              "description": "Longitude in decimal degrees",
              "example": -74.006,
              "maximum": 180,
              "minimum": -180,
              "title": "Lng",
              "type": "number"
            }
          },
          {
            "in": "header",
            "name": "authorization",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Authorization",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-Api-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-OpenEphemeris-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-OpenEphemeris-API-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "apikey",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Apikey",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReverseGeocodeResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "description": "Bad Request - Invalid parameters"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "503": {
            "description": "Service Unavailable - Geocoding provider down"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Reverse geocode coordinates to location name",
        "tags": [
          "location-timezone"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 1
      }
    },
    "/meta/openapi.json": {
      "get": {
        "description": "Return the OpenAPI schema for automated client generation.\n\nUsed by frontend build processes to generate type-safe API clients.\nAuthentication is NOT required for this discovery endpoint to facilitate\nautomated toolchain integration.\n\nReturns:\n    OpenAPI 3.0 schema (JSON)",
        "operationId": "get_openapi_schema_meta_openapi_json_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "Successful Response"
          }
        },
        "security": [],
        "summary": "Get Openapi Schema",
        "tags": [
          "api-metadata"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 0
      }
    },
    "/meta/version": {
      "get": {
        "description": "Return current API version and contract hash for cache invalidation.\n\nFrontend CI uses this to detect schema changes and trigger client regeneration.\nAuthentication is not required for this discovery endpoint.",
        "operationId": "get_api_version_meta_version_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "Successful Response"
          }
        },
        "security": [],
        "summary": "Get Api Version",
        "tags": [
          "api-metadata"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 0
      }
    },
    "/predictive/primary-directions": {
      "post": {
        "description": "Calculates Placidian semi-arc primary directions.",
        "operationId": "CalculatePrimaryDirections",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PrimaryDirectionsRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PrimaryDirectionsResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Calculate Primary Directions",
        "tags": [
          "predictive"
        ]
      }
    },
    "/predictive/returns": {
      "post": {
        "description": "Calculate the nearest return timing (body returns to its natal longitude) near a target datetime.\n\n    Supported bodies: Sun–Uranus, Mean Node, Mean/True Lilith.\n\n    🤖 AI-optimized output available — add `format=llm` to reduce payload ~65%.",
        "operationId": "calculate_planetary_return_predictive_returns_post",
        "parameters": [
          {
            "deprecated": true,
            "description": "Deprecated: use preset+format. Accepts full|simple|llm.",
            "in": "query",
            "name": "output_mode",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Output Mode",
              "type": "string"
            }
          },
          {
            "description": "Computation preset: full | simple. Controls what is computed when include_chart=true.",
            "in": "query",
            "name": "preset",
            "required": false,
            "schema": {
              "default": "full",
              "description": "Computation preset: full | simple. Controls what is computed when include_chart=true.",
              "pattern": "^(?i)(full|simple)$",
              "title": "Preset",
              "type": "string"
            }
          },
          {
            "description": "Response format: json | llm.",
            "in": "query",
            "name": "format",
            "required": false,
            "schema": {
              "default": "json",
              "description": "Response format: json | llm.",
              "pattern": "^(?i)(json|llm|llm)$",
              "title": "Format",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "include_metadata",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Include Metadata",
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "trim_precision",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Trim Precision",
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "include_houses",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Include Houses",
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "include_aspects",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Include Aspects",
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "include_minor_aspects",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Include Minor Aspects",
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "include_declination_aspects",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Include Declination Aspects",
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "include_dignities",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Include Dignities",
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "include_hermetic_lots",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Include Hermetic Lots",
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "decimal_places",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Decimal Places",
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "angle_format",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Angle Format",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PlanetaryReturnRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlanetaryReturnResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__predictive_schemas__ErrorResponse"
                }
              }
            },
            "description": "Bad Request - Input validation failed"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__predictive_schemas__ErrorResponse"
                }
              }
            },
            "description": "Return not found within the specified search window (increase search_window_days)"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__predictive_schemas__ErrorResponse"
                }
              }
            },
            "description": "Unprocessable Entity - Invalid input"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__predictive_schemas__ErrorResponse"
                }
              }
            },
            "description": "Rate Limit Exceeded - Too many requests"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__predictive_schemas__ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Calculate Planetary Return Timing",
        "tags": [
          "predictive"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Developer",
        "x-meridian-units": 5
      }
    },
    "/predictive/returns/lunar": {
      "post": {
        "description": "Calculate the nearest lunar return timing (Moon returns to its natal longitude) near a target datetime.",
        "operationId": "calculate_lunar_return_predictive_returns_lunar_post",
        "parameters": [
          {
            "deprecated": true,
            "description": "Deprecated: use preset+format. Accepts full|simple|llm.",
            "in": "query",
            "name": "output_mode",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Output Mode",
              "type": "string"
            }
          },
          {
            "description": "Computation preset: full | simple. Controls what is computed when include_chart=true.",
            "in": "query",
            "name": "preset",
            "required": false,
            "schema": {
              "default": "full",
              "description": "Computation preset: full | simple. Controls what is computed when include_chart=true.",
              "pattern": "^(?i)(full|simple)$",
              "title": "Preset",
              "type": "string"
            }
          },
          {
            "description": "Response format: json | llm.",
            "in": "query",
            "name": "format",
            "required": false,
            "schema": {
              "default": "json",
              "description": "Response format: json | llm.",
              "pattern": "^(?i)(json|llm|llm)$",
              "title": "Format",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "include_metadata",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Include Metadata",
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "trim_precision",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Trim Precision",
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "include_houses",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Include Houses",
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "include_aspects",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Include Aspects",
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "include_minor_aspects",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Include Minor Aspects",
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "include_declination_aspects",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Include Declination Aspects",
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "include_dignities",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Include Dignities",
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "include_hermetic_lots",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Include Hermetic Lots",
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "decimal_places",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Decimal Places",
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "angle_format",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Angle Format",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LunarReturnRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LunarReturnResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__predictive_schemas__ErrorResponse"
                }
              }
            },
            "description": "Bad Request - Input validation failed"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__predictive_schemas__ErrorResponse"
                }
              }
            },
            "description": "Return not found within the specified search window (increase search_window_days)"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__predictive_schemas__ErrorResponse"
                }
              }
            },
            "description": "Unprocessable Entity - Invalid input"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__predictive_schemas__ErrorResponse"
                }
              }
            },
            "description": "Rate Limit Exceeded - Too many requests"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__predictive_schemas__ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Calculate Lunar Return Timing",
        "tags": [
          "predictive"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Developer",
        "x-meridian-units": 5
      }
    },
    "/predictive/returns/solar": {
      "post": {
        "description": "Calculate the nearest solar return timing (Sun returns to its natal longitude) near a target datetime.",
        "operationId": "calculate_solar_return_predictive_returns_solar_post",
        "parameters": [
          {
            "deprecated": true,
            "description": "Deprecated: use preset+format. Accepts full|simple|llm.",
            "in": "query",
            "name": "output_mode",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Output Mode",
              "type": "string"
            }
          },
          {
            "description": "Computation preset: full | simple. Controls what is computed when include_chart=true.",
            "in": "query",
            "name": "preset",
            "required": false,
            "schema": {
              "default": "full",
              "description": "Computation preset: full | simple. Controls what is computed when include_chart=true.",
              "pattern": "^(?i)(full|simple)$",
              "title": "Preset",
              "type": "string"
            }
          },
          {
            "description": "Response format: json | llm.",
            "in": "query",
            "name": "format",
            "required": false,
            "schema": {
              "default": "json",
              "description": "Response format: json | llm.",
              "pattern": "^(?i)(json|llm|llm)$",
              "title": "Format",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "include_metadata",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Include Metadata",
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "trim_precision",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Trim Precision",
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "include_houses",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Include Houses",
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "include_aspects",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Include Aspects",
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "include_minor_aspects",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Include Minor Aspects",
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "include_declination_aspects",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Include Declination Aspects",
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "include_dignities",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Include Dignities",
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "include_hermetic_lots",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Include Hermetic Lots",
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "decimal_places",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Decimal Places",
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "angle_format",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Angle Format",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/app__api__models__predictive_schemas__SolarReturnRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SolarReturnResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__predictive_schemas__ErrorResponse"
                }
              }
            },
            "description": "Bad Request - Input validation failed"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__predictive_schemas__ErrorResponse"
                }
              }
            },
            "description": "Return not found within the specified search window (increase search_window_days)"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__predictive_schemas__ErrorResponse"
                }
              }
            },
            "description": "Unprocessable Entity - Invalid input"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__predictive_schemas__ErrorResponse"
                }
              }
            },
            "description": "Rate Limit Exceeded - Too many requests"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__predictive_schemas__ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Calculate Solar Return Timing",
        "tags": [
          "predictive"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Developer",
        "x-meridian-units": 5
      }
    },
    "/predictive/time-lords/firdaria": {
      "post": {
        "description": "Calculate firdaria (فرادير) — the medieval Persian planetary period system that assigns each of the seven classical planets a fixed number of years as the dominant ruler of life. The 75-year master cycle differs for day births (diurnal) and night births (nocturnal). Each major period is subdivided into seven sub-periods in Chaldean order.\n\nFirdaria operates independently of signs and houses — it is purely a time-based system making it complementary to profections and transits. Think of it as a 75-year program schedule: knowing your current major and sub-period ruler tells you which planetary archetype is most active in your life right now.\n\n🤖 Agent-first endpoint — pure deterministic math, no ephemeris required.",
        "operationId": "calculate_firdaria_predictive_time_lords_firdaria_post",
        "parameters": [
          {
            "description": "Response format: json | llm.",
            "in": "query",
            "name": "format",
            "required": false,
            "schema": {
              "default": "json",
              "pattern": "^(?i)(json|llm)$",
              "title": "Format",
              "type": "string"
            }
          },
          {
            "deprecated": true,
            "description": "Deprecated: use format. Accepts full|simple|llm.",
            "in": "query",
            "name": "output_mode",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Output Mode",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FirdariaRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FirdariaResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__predictive_schemas__ErrorResponse"
                }
              }
            },
            "description": "Unprocessable Entity - Invalid input"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__predictive_schemas__ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Firdaria Planetary Periods",
        "tags": [
          "predictive"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Developer",
        "x-meridian-units": 5
      }
    },
    "/predictive/time-lords/profections": {
      "post": {
        "description": "Calculate annual profections — the foundational Hellenistic timing technique that advances one zodiac sign per birthday from the natal Ascendant. Returns the profected sign, activated house, time lord planet, element, modality, and a full multi-year timeline.\n\nProfections are the simplest and most widely used timing technique in traditional astrology, experiencing a major revival in modern Hellenistic practice. Each year of life activates one whole-sign house from the Ascendant; the ruler of that sign becomes the \"time lord\" coloring the entire year. Angular years (1st, 4th, 7th, 10th) are typically the most eventful.\n\n🤖 Agent-first endpoint — pure deterministic math, no ephemeris required.",
        "operationId": "calculate_profections_predictive_time_lords_profections_post",
        "parameters": [
          {
            "description": "Response format: json | llm.",
            "in": "query",
            "name": "format",
            "required": false,
            "schema": {
              "default": "json",
              "pattern": "^(?i)(json|llm)$",
              "title": "Format",
              "type": "string"
            }
          },
          {
            "deprecated": true,
            "description": "Deprecated: use format. Accepts full|simple|llm.",
            "in": "query",
            "name": "output_mode",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Output Mode",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ProfectionsRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProfectionsResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__predictive_schemas__ErrorResponse"
                }
              }
            },
            "description": "Unprocessable Entity - Invalid input"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__predictive_schemas__ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Annual Profections Time Lords",
        "tags": [
          "predictive"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Developer",
        "x-meridian-units": 5
      }
    },
    "/predictive/time-lords/zodiacal-releasing": {
      "post": {
        "description": "Calculate zodiacal releasing — the most powerful timing technique in Hellenistic astrology. Divides life into chapters ruled by zodiac signs, starting from a sensitive Lot (Fortune or Spirit). Each sign rules for its planetary ruler's minor years in months. Angular periods (1st, 4th, 7th, 10th from the Lot) mark peak chapters. Loosing of the bond occurs when a period's ruler falls in a cadent sign.\n\nReturns L1 major periods with optional L2 sub-periods, peak period identification, angular/loosing flags, and an optional current-period highlight at the target datetime.\n\n🤖 Agent-first endpoint — pure deterministic math, no ephemeris required.",
        "operationId": "calculate_zodiacal_releasing_predictive_time_lords_zodiacal_releasing_post",
        "parameters": [
          {
            "description": "Response format: json | llm.",
            "in": "query",
            "name": "format",
            "required": false,
            "schema": {
              "default": "json",
              "pattern": "^(?i)(json|llm)$",
              "title": "Format",
              "type": "string"
            }
          },
          {
            "deprecated": true,
            "description": "Deprecated: use format. Accepts full|simple|llm.",
            "in": "query",
            "name": "output_mode",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Output Mode",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ZodiacalReleasingRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ZodiacalReleasingResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__predictive_schemas__ErrorResponse"
                }
              }
            },
            "description": "Unprocessable Entity - Invalid input"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__predictive_schemas__ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Zodiacal Releasing Time Lords",
        "tags": [
          "predictive"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Developer",
        "x-meridian-units": 5
      }
    },
    "/predictive/transit-chart": {
      "post": {
        "description": "Return a full chart payload for a given moment (transit chart). Includes all supported bodies: Sun–Pluto (core) plus Chiron, Mean/True North \u0026 South Nodes, Mean/True Lilith (Black Moon), and Ceres (extended bodies — gracefully omitted when ephemeris kernels are unavailable). Also returns houses/angles, aspects (major; minor opt-in), and a `body_categories` map for UI rendering. This is a chart snapshot endpoint (not a transit event search). 🤖 AI-optimized output: add `format=llm` to reduce payload ~70%.",
        "operationId": "calculate_transit_chart_predictive_transit_chart_post",
        "parameters": [
          {
            "deprecated": true,
            "description": "Deprecated: use preset+format. Accepts full|simple|llm.",
            "in": "query",
            "name": "output_mode",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Output Mode",
              "type": "string"
            }
          },
          {
            "description": "Computation preset: full | simple. Controls what is computed (pre-calculation).",
            "in": "query",
            "name": "preset",
            "required": false,
            "schema": {
              "default": "full",
              "description": "Computation preset: full | simple. Controls what is computed (pre-calculation).",
              "pattern": "^(?i)(full|simple)$",
              "title": "Preset",
              "type": "string"
            }
          },
          {
            "description": "Response format: json | llm. Controls response projection only.",
            "in": "query",
            "name": "format",
            "required": false,
            "schema": {
              "default": "json",
              "description": "Response format: json | llm. Controls response projection only.",
              "pattern": "^(?i)(json|llm|llm)$",
              "title": "Format",
              "type": "string"
            }
          },
          {
            "description": "Opt-in to minor aspects (e.g., quincunx, semisquare, quintile).",
            "in": "query",
            "name": "include_minor_aspects",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Include Minor Aspects",
              "type": "boolean"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/NatalChartEnhancedRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EnhancedChartSuccessResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__predictive_schemas__ErrorResponse"
                }
              }
            },
            "description": "Bad Request - Input validation failed"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__predictive_schemas__ErrorResponse"
                }
              }
            },
            "description": "Unprocessable Entity - Invalid input format"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__predictive_schemas__ErrorResponse"
                }
              }
            },
            "description": "Rate Limit Exceeded - Too many requests"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__predictive_schemas__ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - Calculation failed"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Calculate transit chart (full chart snapshot)",
        "tags": [
          "predictive"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Personal",
        "x-meridian-units": 1
      }
    },
    "/predictive/transits/planet-to-degree": {
      "post": {
        "description": "Calculate when a planet transits to a specific longitude degree.\n    \n    **Features:**\n    - Sub-minute precision for transit timing\n    - Retrograde motion handling with multiple crossings\n    - Duration calculations (approach and separation)\n    - All traditional and modern planets supported\n    \n    **Performance:** \u003c50ms for single transit calculations",
        "operationId": "calculate_planet_transit_predictive_transits_planet_to_degree_post",
        "parameters": [
          {
            "in": "query",
            "name": "include_metadata",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Include Metadata",
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "trim_precision",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Trim Precision",
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "decimal_places",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Decimal Places",
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "angle_format",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Angle Format",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PlanetTransitRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlanetTransitResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__predictive_schemas__ErrorResponse"
                }
              }
            },
            "description": "Bad Request - Input validation failed"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__predictive_schemas__ErrorResponse"
                }
              }
            },
            "description": "Unprocessable Entity - Invalid input format"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__predictive_schemas__ErrorResponse"
                }
              }
            },
            "description": "Rate Limit Exceeded - Too many requests"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__predictive_schemas__ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - Calculation failed"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Calculate Planetary Transit to Degree",
        "tags": [
          "predictive"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Personal",
        "x-meridian-units": 5
      }
    },
    "/predictive/transits/search": {
      "post": {
        "description": "Search for various types of transit events within a date range.\n    \n    **Features:**\n    - Comprehensive transit searches\n    - Configurable date ranges (up to 5 years)\n    - Multiple transit types and aspects\n    - Detailed timing and metadata\n    \n    **Performance:** Optimized for large-scale searches",
        "operationId": "search_transits_predictive_transits_search_post",
        "parameters": [
          {
            "in": "query",
            "name": "include_metadata",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Include Metadata",
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "trim_precision",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Trim Precision",
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "decimal_places",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Decimal Places",
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "angle_format",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Angle Format",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TransitSearchRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TransitSearchResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__predictive_schemas__ErrorResponse"
                }
              }
            },
            "description": "Bad Request - Input validation failed"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__predictive_schemas__ErrorResponse"
                }
              }
            },
            "description": "Unprocessable Entity - Invalid input format"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__predictive_schemas__ErrorResponse"
                }
              }
            },
            "description": "Rate Limit Exceeded - Too many requests"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__predictive_schemas__ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - Calculation failed"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Search Transit Events",
        "tags": [
          "predictive"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Personal",
        "x-meridian-units": 5
      }
    },
    "/predictive/transits/sign-ingresses": {
      "post": {
        "description": "Calculate planetary sign ingresses (when planets change zodiac signs).\n    \n    **Features:**\n    - Sub-minute precision for ingress timing\n    - Retrograde status detection\n    - All traditional and modern planets\n    - Batch processing for multiple planets\n    \n    **Performance:** \u003c200ms for batch ingress calculations",
        "operationId": "calculate_sign_ingresses_predictive_transits_sign_ingresses_post",
        "parameters": [
          {
            "in": "query",
            "name": "include_metadata",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Include Metadata",
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "trim_precision",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Trim Precision",
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "decimal_places",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Decimal Places",
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "angle_format",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Angle Format",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SignIngressRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SignIngressResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__predictive_schemas__ErrorResponse"
                }
              }
            },
            "description": "Bad Request - Input validation failed"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__predictive_schemas__ErrorResponse"
                }
              }
            },
            "description": "Unprocessable Entity - Invalid input format"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__predictive_schemas__ErrorResponse"
                }
              }
            },
            "description": "Rate Limit Exceeded - Too many requests"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__predictive_schemas__ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - Calculation failed"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Calculate Sign Ingresses",
        "tags": [
          "predictive"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Personal",
        "x-meridian-units": 5
      }
    },
    "/tidal/forcing": {
      "get": {
        "description": "Calculate astronomical gravitational forcing potential (spring/neap, perigee, etc) for a specific location.",
        "operationId": "get_tidal_forcing_endpoint_tidal_forcing_get",
        "parameters": [
          {
            "description": "Observer latitude",
            "in": "query",
            "name": "lat",
            "required": true,
            "schema": {
              "description": "Observer latitude",
              "maximum": 90,
              "minimum": -90,
              "title": "Lat",
              "type": "number"
            }
          },
          {
            "description": "Observer longitude",
            "in": "query",
            "name": "lon",
            "required": true,
            "schema": {
              "description": "Observer longitude",
              "maximum": 180,
              "minimum": -180,
              "title": "Lon",
              "type": "number"
            }
          },
          {
            "description": "Date in YYYY-MM-DD format",
            "in": "query",
            "name": "date",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Date",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TidalForcingResponse"
                }
              }
            },
            "description": "Tidal forcing metrics and indices"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Astronomical Tidal Forcing",
        "tags": [
          "tidal"
        ],
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 1
      }
    },
    "/tidal/forcing/deep-time": {
      "get": {
        "description": "Calculate astronomical gravitational forcing for dates outside the standard Gregorian calendar range using DE441.",
        "operationId": "get_tidal_forcing_deep_time_endpoint_tidal_forcing_deep_time_get",
        "parameters": [
          {
            "description": "Observer latitude",
            "in": "query",
            "name": "lat",
            "required": true,
            "schema": {
              "description": "Observer latitude",
              "maximum": 90,
              "minimum": -90,
              "title": "Lat",
              "type": "number"
            }
          },
          {
            "description": "Observer longitude",
            "in": "query",
            "name": "lon",
            "required": true,
            "schema": {
              "description": "Observer longitude",
              "maximum": 180,
              "minimum": -180,
              "title": "Lon",
              "type": "number"
            }
          },
          {
            "description": "Julian Day",
            "in": "query",
            "name": "jd",
            "required": true,
            "schema": {
              "description": "Julian Day",
              "format": "double",
              "title": "Jd",
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TidalForcingResponse"
                }
              }
            },
            "description": "Tidal forcing metrics and indices"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "DE441 ephemeris not loaded in engine"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Astronomical Tidal Forcing (Deep Time)",
        "tags": [
          "tidal"
        ],
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 1
      }
    },
    "/time/delta-t": {
      "get": {
        "description": "Provide Delta T (TT - UT1) for any historical/future epoch.",
        "operationId": "get_delta_t_time_delta_t_get",
        "parameters": [
          {
            "description": "Date (YYYY-MM-DD)",
            "in": "query",
            "name": "date",
            "required": true,
            "schema": {
              "description": "Date (YYYY-MM-DD)",
              "example": "2026-03-15",
              "title": "Date",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "authorization",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Authorization",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-Api-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-OpenEphemeris-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-OpenEphemeris-API-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "apikey",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Apikey",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeltaTResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Delta T (TT-UT1) calculation",
        "tags": [
          "Time Conversion"
        ],
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 1
      }
    },
    "/time/equation-of-time": {
      "get": {
        "description": "Compute the Equation of Time (sundial correction) in minutes for a given JD.",
        "operationId": "get_equation_of_time_time_equation_of_time_get",
        "parameters": [
          {
            "description": "Julian Day (Terrestrial Time)",
            "in": "query",
            "name": "jd",
            "required": true,
            "schema": {
              "description": "Julian Day (Terrestrial Time)",
              "format": "double",
              "title": "Jd",
              "type": "number"
            }
          },
          {
            "in": "header",
            "name": "authorization",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Authorization",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-Api-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-OpenEphemeris-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-OpenEphemeris-API-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "apikey",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Apikey",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EquationOfTimeResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Equation of Time",
        "tags": [
          "Time Conversion"
        ],
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 1
      }
    },
    "/time/julian-day": {
      "post": {
        "description": "Bridge between civil calendars and astronomical time. Handles BCE dates.",
        "operationId": "calculate_julian_day_time_julian_day_post",
        "parameters": [
          {
            "in": "header",
            "name": "authorization",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Authorization",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-Api-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-OpenEphemeris-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-OpenEphemeris-API-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "apikey",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Apikey",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/JulianDayRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JulianDayResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Calendar conversion to Julian Day Number",
        "tags": [
          "Time Conversion"
        ],
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 1
      }
    },
    "/time/scales": {
      "post": {
        "description": "Convert between major astronomical time scales (UTC, TT, TAI, TDB, UT1).",
        "operationId": "post_time_scales_time_scales_post",
        "parameters": [
          {
            "in": "header",
            "name": "authorization",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Authorization",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-Api-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-OpenEphemeris-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-OpenEphemeris-API-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "apikey",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Apikey",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TimeScalesRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TimeScalesResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Time Scale Conversions",
        "tags": [
          "Time Conversion"
        ],
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 1
      }
    },
    "/time/sidereal": {
      "get": {
        "description": "Compute Local Apparent Sidereal Time (LAST) and Greenwich Mean Sidereal Time (GMST).",
        "operationId": "get_sidereal_time_time_sidereal_get",
        "parameters": [
          {
            "description": "Date (YYYY-MM-DD) or Julian Day (jd:2451545.0)",
            "in": "query",
            "name": "date",
            "required": true,
            "schema": {
              "description": "Date (YYYY-MM-DD) or Julian Day (jd:2451545.0)",
              "example": "2026-03-15",
              "title": "Date",
              "type": "string"
            }
          },
          {
            "description": "Observer longitude (positive East)",
            "in": "query",
            "name": "longitude",
            "required": false,
            "schema": {
              "default": 0,
              "description": "Observer longitude (positive East)",
              "maximum": 180,
              "minimum": -180,
              "title": "Longitude",
              "type": "number"
            }
          },
          {
            "in": "header",
            "name": "authorization",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Authorization",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-Api-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-OpenEphemeris-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-OpenEphemeris-API-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "apikey",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Apikey",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SiderealTimeResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Sidereal Time (LAST \u0026 GMST)",
        "tags": [
          "Time Conversion"
        ],
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 1
      }
    },
    "/time/solar-event": {
      "get": {
        "description": "Compute exact times for sunrise, sunset, and solar transit for a given day and location.",
        "operationId": "get_solar_events_time_solar_event_get",
        "parameters": [
          {
            "description": "Date (YYYY-MM-DD)",
            "in": "query",
            "name": "date",
            "required": true,
            "schema": {
              "description": "Date (YYYY-MM-DD)",
              "example": "2026-03-20",
              "title": "Date",
              "type": "string"
            }
          },
          {
            "description": "Observer latitude",
            "in": "query",
            "name": "latitude",
            "required": true,
            "schema": {
              "description": "Observer latitude",
              "maximum": 90,
              "minimum": -90,
              "title": "Latitude",
              "type": "number"
            }
          },
          {
            "description": "Observer longitude",
            "in": "query",
            "name": "longitude",
            "required": true,
            "schema": {
              "description": "Observer longitude",
              "maximum": 180,
              "minimum": -180,
              "title": "Longitude",
              "type": "number"
            }
          },
          {
            "in": "header",
            "name": "authorization",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Authorization",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-Api-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-OpenEphemeris-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-OpenEphemeris-API-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "apikey",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Apikey",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SolarEventResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/app__api__models__schemas__system__ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Solar Events (Sunrise/Sunset/Transit)",
        "tags": [
          "Time Conversion"
        ],
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 1
      }
    },
    "/timezone/lookup": {
      "post": {
        "description": "Return the IANA timezone for the provided coordinates.\n\nIf no timezone can be confidently determined (e.g., mid-ocean or invalid\ninputs), the endpoint falls back to UTC and marks `fallback=true`.\nThe underlying lookup is cached within the core tools.",
        "operationId": "timezone_lookup_timezone_lookup_post",
        "parameters": [
          {
            "in": "header",
            "name": "authorization",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Authorization",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-Api-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-OpenEphemeris-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-OpenEphemeris-API-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "apikey",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Apikey",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TimezoneLookupRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TimezoneLookupResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "description": "Bad Request - Input validation failed"
          },
          "422": {
            "description": "Unprocessable Entity - Invalid input format"
          },
          "500": {
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Resolve IANA timezone from coordinates",
        "tags": [
          "location-timezone"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 1
      }
    },
    "/timezone/offset": {
      "post": {
        "description": "Return the timezone and UTC offset for the provided coordinates and instant.\n\n- Resolves an IANA timezone from the coordinates\n- Applies the timezone's historical/DST rules at the given instant\n- Returns offset in seconds/hours, a formatted string, and a DST flag",
        "operationId": "timezone_offset_timezone_offset_post",
        "parameters": [
          {
            "in": "header",
            "name": "authorization",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Authorization",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-Api-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-OpenEphemeris-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-OpenEphemeris-API-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "apikey",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Apikey",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TimezoneOffsetRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TimezoneOffsetResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "description": "Bad Request - Input validation failed"
          },
          "422": {
            "description": "Unprocessable Entity - Invalid input format"
          },
          "500": {
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get UTC offset at datetime for coordinates",
        "tags": [
          "location-timezone"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 1
      }
    },
    "/vedic/chart": {
      "post": {
        "description": "Calculate planetary positions in the sidereal zodiac with Jyotish overlays. Each planet receives its rashi (sign), nakshatra (lunar mansion) with pada and ruling planet, and navamsa (D-9 divisional chart) sign.\n\n**Ayanamsa**: Defaults to Lahiri, the standard for North Indian Jyotish. Also supports Fagan-Bradley and Krishnamurti.\n\n**Planets**: Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Rahu (North Node), and Ketu (South Node).\n\n**Metering**: 1 unit per call.",
        "operationId": "vedic_chart_vedic_chart_post",
        "parameters": [
          {
            "description": "Response format: json (full) or llm (compact columnar).",
            "in": "query",
            "name": "format",
            "required": false,
            "schema": {
              "default": "json",
              "description": "Response format: json (full) or llm (compact columnar).",
              "pattern": "^(?i)(json|llm)$",
              "title": "Format",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "authorization",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Authorization",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-Api-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-OpenEphemeris-API-Key",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "X-OpenEphemeris-API-Key",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "apikey",
            "required": false,
            "schema": {
              "nullable": true,
              "title": "Apikey",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VedicChartRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VedicChartResponse"
                }
              }
            },
            "description": "Vedic chart with sidereal positions, nakshatras, and navamsa."
          },
          "422": {
            "description": "Validation error (bad datetime, unsupported ayanamsa, etc.)"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Generate a Vedic (sidereal) natal chart",
        "tags": [
          "vedic"
        ],
        "x-meridian-tier": "Explorer",
        "x-meridian-units": 1
      }
    },
    "/visualization/bi-wheel": {
      "post": {
        "description": "Generate SVG/PNG bi-wheel chart. Requires Developer tier.",
        "operationId": "generate_bi_wheel_visualization_bi_wheel_post",
        "parameters": [
          {
            "in": "query",
            "name": "format",
            "required": false,
            "schema": {
              "default": "svg",
              "pattern": "^(svg|png)$",
              "title": "Format",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "size",
            "required": false,
            "schema": {
              "default": 800,
              "maximum": 2400,
              "minimum": 200,
              "title": "Size",
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "style",
            "required": false,
            "schema": {
              "default": "light",
              "pattern": "^(light|dark|mono)$",
              "title": "Style",
              "type": "string"
            }
          },
          {
            "description": "When true, suppresses the OpenEphemeris watermark/logomark in the rendered SVG. Intended for white-label and embedded use cases where the chart is presented inside a host product's branded shell.",
            "in": "query",
            "name": "no_logo",
            "required": false,
            "schema": {
              "default": false,
              "title": "No Logo",
              "type": "boolean"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BiWheelRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "image/png": {
                "schema": {
                  "format": "binary",
                  "type": "string"
                }
              },
              "image/svg+xml": {
                "schema": {
                  "format": "binary",
                  "type": "string"
                }
              }
            },
            "description": "Successful Response"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "Forbidden (tier upgrade required)"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Generate Bi Wheel",
        "tags": [
          "visualization"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Developer",
        "x-meridian-units": 2
      }
    },
    "/visualization/bodygraph": {
      "post": {
        "description": "Generates a visually premium Human Design bodygraph (SVG or PNG).",
        "operationId": "GenerateBodygraphVisualization_visualization_bodygraph_post",
        "parameters": [
          {
            "in": "query",
            "name": "format",
            "required": false,
            "schema": {
              "default": "svg",
              "pattern": "^(svg|png)$",
              "title": "Format",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "size",
            "required": false,
            "schema": {
              "default": 800,
              "maximum": 2400,
              "minimum": 200,
              "title": "Size",
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "style",
            "required": false,
            "schema": {
              "default": "light",
              "pattern": "^(light|dark|mono)$",
              "title": "Style",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "show_variables",
            "required": false,
            "schema": {
              "default": false,
              "title": "Show Variables",
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "show_planet_columns",
            "required": false,
            "schema": {
              "default": false,
              "title": "Show Planet Columns",
              "type": "boolean"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/HumanDesignChartRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "image/png": {
                "schema": {
                  "format": "binary",
                  "type": "string"
                }
              },
              "image/svg+xml": {
                "schema": {
                  "format": "binary",
                  "type": "string"
                }
              }
            },
            "description": "Successful Response"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "Forbidden (tier upgrade required)"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Human Design Bodygraph",
        "tags": [
          "visualization"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Developer",
        "x-meridian-units": 2
      }
    },
    "/visualization/chart-wheel": {
      "post": {
        "description": "Generate SVG/PNG chart wheel. Requires Developer tier. Explorer-tier and lower API keys receive 403 by design; there is no lower-tier fallback wheel-rendering endpoint in the current contract.",
        "operationId": "generate_chart_wheel_visualization_chart_wheel_post",
        "parameters": [
          {
            "in": "query",
            "name": "format",
            "required": false,
            "schema": {
              "default": "svg",
              "pattern": "^(svg|png)$",
              "title": "Format",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "size",
            "required": false,
            "schema": {
              "default": 800,
              "maximum": 2400,
              "minimum": 200,
              "title": "Size",
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "style",
            "required": false,
            "schema": {
              "default": "light",
              "pattern": "^(light|dark|mono)$",
              "title": "Style",
              "type": "string"
            }
          },
          {
            "description": "When true, suppresses the OpenEphemeris watermark/logomark in the rendered SVG. Intended for white-label and embedded use cases where the chart is presented inside a host product's branded shell.",
            "in": "query",
            "name": "no_logo",
            "required": false,
            "schema": {
              "default": false,
              "title": "No Logo",
              "type": "boolean"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChartWheelRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "image/png": {
                "schema": {
                  "format": "binary",
                  "type": "string"
                }
              },
              "image/svg+xml": {
                "schema": {
                  "format": "binary",
                  "type": "string"
                }
              }
            },
            "description": "Successful Response"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "Forbidden (tier upgrade required)"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "meridianApiKeyAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "serviceKeyAuth": []
          }
        ],
        "summary": "Generate Chart Wheel",
        "tags": [
          "visualization"
        ],
        "x-meridian-status": "live",
        "x-meridian-tier": "Developer",
        "x-meridian-units": 2
      }
    }
  },
  "servers": [
    {
      "description": "Production",
      "url": "https://api.openephemeris.com"
    }
  ],
  "tags": [
    {
      "description": "Discover the foundation of any chart. Get natal positions, houses, lots, core aspects, and fixed stars. Calculated with NASA-grade precision (DE440). Deep-time queries (DE441) are fully supported. **1 unit per request.**",
      "name": "ephemeris"
    },
    {
      "description": "Look ahead (or behind). Find exact times for transits, cast solar \u0026 lunar returns, and calculate progressions. **5 units per request.**",
      "name": "predictive"
    },
    {
      "description": "Explore relationships and overlays. Cast synastry, composite, and transit-to-natal charts effortlessly. **3 units per request.** (Scales by subject count for composites/overlays.)",
      "name": "comparative"
    },
    {
      "description": "Render chart imagery. Generate natal chart wheels and comparative bi-wheels as SVG or PNG. Requires Developer tier. **2 units per request.**",
      "name": "visualization"
    },
    {
      "description": "Map the cosmos to the earth. Astrocartography (ACG), cyclocartography (CCG), and Local Space endpoints. Returns GeoJSON feature collections—perfect for drawing maps in your app. **2 units per request.**",
      "name": "ACG"
    },
    {
      "description": "Find the shadows. Calculate solar and lunar eclipses, global circumstances, next-visible searches, and Saros series data. **3 units per request.**",
      "name": "eclipse"
    },
    {
      "description": "Map the energetic blueprint. Bodygraphs, composite charts, transit fields, and pentas. **3 units per request.**",
      "name": "Human Design"
    },
    {
      "description": "Eastern insights. BaZi (Four Pillars), Zi Wei Dou Shu, and I Ching endpoints. **1 unit per request.**",
      "name": "chinese"
    },
    {
      "description": "Vedic (Jyotish) calculations including Ayanamsha, Vargas, Dashas, and Panchang elements. **1 unit per request.**",
      "name": "vedic"
    },
    {
      "description": "Work with the earth's rhythms. Biodynamic planting profiles and multi-day agricultural calendars. **2 units per request.**",
      "name": "agricultural"
    },
    {
      "description": "Calculate tidal forces and lunar coastal influences. **1 unit per request.**",
      "name": "tidal"
    },
    {
      "description": "Explore the elegant dance of Venus. Synodic cycle analysis and Star Points. **2 units per request.**",
      "name": "venus-cycles"
    },
    {
      "description": "Mark the turning of the wheel. Cross-quarter days, exact moon phases, and lunar standstills. **2 units per request.**",
      "name": "calendar"
    },
    {
      "description": "Track the Moon's journey. Phases, void-of-course windows, and exact lunar ingresses. **1 unit per request.**",
      "name": "lunar"
    },
    {
      "description": "Geocoding and timezone resolution to help you locate your charts accurately. **1 unit per request.**",
      "name": "location-timezone"
    },
    {
      "description": "Explore our extensive reference catalogs. See all supported planets, asteroids, fixed stars, and star groups available for calculation. **Free — not metered.**",
      "name": "catalogs"
    },
    {
      "description": "Discover the API schema and current contract hash. **Free — not metered.**",
      "name": "api-metadata"
    },
    {
      "description": "System health and readiness checks. **Free — not metered.**",
      "name": "health"
    },
    {
      "name": "Time Conversion"
    }
  ]
}