Metadata-Version: 2.4
Name: cosmicephemeris-client
Version: 0.3.0
Summary: Synchronous Python client for the Cosmic Ephemeris calculation gateway
License-Expression: ISC
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Provides-Extra: receipts
Requires-Dist: cryptography<48,>=42; extra == "receipts"
Dynamic: license-file

# Cosmic Ephemeris Python client

> **Current boundary (2026-10-05):** version 0.3.0 is the breaking product-identity release for all 78 live methods under the canonical `cosmicephemeris-client` distribution. Earlier 0.2.x paragraphs document the predecessor package history; they are not claims that those versions exist under the new distribution name.

Predecessor version 0.2.38 added `electional_criterion_repair_hardening_regret_audit` as the 78th method. It is registry-published; the matching route and migrations 039-064 are live in R231.

Source version 0.2.37 adds `electional_criterion_repair_hardening_pareto_hierarchy_audit` as the 77th candidate method. It is not yet registry-published; the matching route and migrations 039-063 are live in R231.

Source version 0.2.36 adds `electional_criterion_repair_hardening_pareto_audit` as the 76th candidate method. It is not yet registry-published; the matching route and migrations 039-062 are live in R231.

Source version 0.2.35 adds `electional_criterion_repair_hardening_audit` as the 75th candidate method. It is not yet registry-published; the matching route and migrations 039-061 are live in R231.

Source version 0.2.34 adds `electional_criterion_repair_loss_frontier_audit` as the 74th candidate method. It is not yet registry-published; the matching route and migrations 039-060 are live in R231.

Source version 0.2.32 adds `electional_criterion_repair_coverage_audit` as the 72nd candidate method. It is not yet registry-published; the matching route and migrations 039-058 are live in R231.

Source version 0.2.31 adds `electional_criterion_repair_hierarchy_audit` as the 71st candidate method. It is not yet registry-published; the matching route and migrations 039-057 are live in R231.

Source version 0.2.30 adds `electional_criterion_repair_overlap_audit` as the 70th candidate method. It is not yet registry-published; the matching route and migrations 039-056 are live in R231.

Source version 0.2.29 adds `electional_criterion_repair_distinction_audit` as the 69th candidate method. It is not yet registry-published; the matching route and migrations 039-055 are live in R231.

Source version 0.2.27 adds `electional_criterion_robust_repair_audit` as the 67th candidate method. It is not yet registry-published; the matching route and migrations 039-053 are live in R231.

Source version 0.2.26 adds `electional_criterion_conflict_core_audit` as the 66th candidate method. It is not yet registry-published; the matching route and migrations 039-052 are live in R231.

Source version 0.2.25 adds `electional_criterion_shapley_audit` as the 65th candidate method. It is not yet registry-published; the matching route and migrations 039-051 are live in R231.

Source version 0.2.24 adds `electional_criterion_budget_pareto_audit` as the 64th candidate method. It is not yet registry-published; the matching route and migrations 039-050 are live in R231.

Source version 0.2.23 adds `electional_criterion_budget_regret_audit` as the 63rd candidate method. It is not yet registry-published; the matching route and migrations 039-049 are live in R231.

Source version 0.2.19 adds `electional_criterion_pair_audit` as a 59th candidate method. It is not yet registry-published; the matching service route and migrations 039-045 are live in R231.

The predecessor package at version 0.2.12 covers the R204-era 52-route contract. Predecessor version 0.2.38 covers the live R231 service's 78 routes: 77 standard operations plus the separate Pro Nakshatra Timeline. Minor-body calculations are not part of the contract.

Source version 0.2.18 adds `electional_criterion_omission_audit` as a 58th candidate method after the R210 sampling-phase audit, R209 resolution audit, R208 feasibility audit, R207 tolerance frontier, and R206 robustness audit. It is not yet registry-published; the matching service routes and migrations 039-044 are live in R231.

A synchronous client for Python 3.10+, with no runtime dependencies.
The package import is `cosmicephemeris_client`; the distribution name is
`cosmicephemeris-client`. Version 0.3.0 matches the live service. Package availability never substitutes for checking the target service environment.

Install version 0.3.0 with `python -m pip install cosmicephemeris-client==0.3.0`, or install from a local checkout using `python -m pip install ./clients/python`.
Building needs setuptools and wheel; the installed client uses only the standard
library. Keep API credentials in trusted server or command-line environments.

```python
from cosmicephemeris_client import CosmicEphemerisClient, HTTPError, RequestTimeoutError

# Reads COSMICEPHEMERIS_KEY; alternatively pass api_key=your_key explicitly.
client = CosmicEphemerisClient()
birth = {
    "date": "1990-01-01",
    "time": "12:00",
    "timezone": "America/New_York",
    "lat": 40.7128,
    "lon": -74.006,
}

try:
    result = client.birth_chart(birth)
    sun = result["chart"]["planets"]["Sun"]
except HTTPError as error:
    print(error.status, error.retry_after)  # Sanitized; does not trigger a retry.
except RequestTimeoutError:
    print("Deadline exceeded; this request may already have consumed quota.")
```

An explicit key takes precedence over `COSMICEPHEMERIS_KEY`. Keys must contain exactly
64 hexadecimal characters. The SDK never reads another application's settings,
environment files, browser sessions, or stored keys. Do not place keys in source
control, browser code, URLs, or logs.

## Methods and current response shapes

Each method takes one dictionary using the gateway's field names. It returns
the **complete parsed JSON object without changing its envelope**. Exported
`TypedDict` input types and `py.typed` support editors. Methods without a detailed response type return
`dict[str, Any]` (`JSONResponse`). `lunar_nodes`, `returns`, `solar_arcs` and
`vimshottari` provide detailed response type hints; Vimshottari is a union of
`VimshottariResponseDepth2`, `VimshottariResponseDepth3`, and
`VimshottariResponseDepth4`. The return's existing
nested chart remains `JSONResponse`.
Type hints describe the server contract and do not perform response validation.

| Method | OpenAPI operation ID | Input | Important response path |
|---|---|---|---|
| `birth_chart` | `calculateBirthChart` | Birth fields; optional zodiac/ayanamsa | `result["chart"]` |
| `place_search` **beta** | `searchPlaces` | Query; optional uppercase country codes and limit | Ordered versioned candidates in `result["results"]` |
| `timezone_resolve` **beta** | `resolvePlaceTimezone` | Versioned place ID plus local date/time | Explicit civil-time status/candidates and unique `resolved_input` |
| `natal_context` **beta** | `calculateNatalContext` | Birth; optional zodiac/ayanamsa/houses/formats | Stable facts, calculation hash, and selected text artifacts |
| `aspects` | `calculateAspects` | `{"birth": birth}`; optional zodiac/ayanamsa | `result["aspects"]["aspects"]` is the array |
| `houses` | `calculateHouses` | `{"birth": birth, "system": "whole_sign"}`; optional zodiac/ayanamsa | Full chart at top level; `result["houses"]["systems"]` |
| `synastry` | `calculateSynastry` | `{"personA": birth, "personB": other}`; optional zodiac/ayanamsa | `result["charts"]`, `result["aspects"]` |
| `transits` | `calculateTransits` | Birth plus required `transitDate`; optional `transitTime`, timezone, zodiac/ayanamsa | `result["transits"]["natal_chart"]`, `transit_chart`, `aspects` |
| `horoscope` **beta** | `calculateHoroscope` | Birth plus optional transit fields, timezone, zodiac/ayanamsa | `result["interpretation"]` |
| `nakshatra_timeline` | `calculateNakshatraTimeline` | Planet, `start_utc`, `end_utc`, ayanamsa | `result["segments"]` |
| `natal_svg` **beta** | `calculateNatalSvg` | Birth; optional zodiac, ayanamsa, houses/theme/show_aspects, named aspect profile or custom aspects, `include_png` | `result["svg"]`, optional `result["png"]` |
| `vargas` **beta** | `calculateVargas` | Birth; optional ayanamsa and one of twenty-four divisions through D150 | `result["bodies"]["moon"]["sign"]`, `result["ascendant"]` |
| `vimshottari` **beta** | `calculateVimshottari` | Birth; optional ayanamsa and depth 2/3/4 | `result["birth_balance"]`, `result["periods"]` |
| `ashtakoota` **beta** | `calculateAshtakoota` | Required groom/bride births; optional ayanamsa | `result["kootas"]`, `result["total"]`; no verdict/advice |
| `ashtakavarga` **beta** | `calculateAshtakavarga` | Required birth; optional ayanamsa and `include_reductions` | BAV, Prastara, SAV, and opt-in reductions/pindas; no interpretation |
| `numerology` **beta** | `calculateNumerology` | Gregorian `birth_date`; optional ASCII `name`, boolean `master_numbers`/`y_vowel`, integer `year` | `numbers` contains symbolic reduction traces; no interpretations or predictions |
| `composite` **beta** | `calculateComposite` | personA/personB; optional zodiac/ayanamsa/house_system | `result["planets"]`, synthetic `result["houses"]` |
| `panchang` **beta** | `calculatePanchang` | at civil snapshot; optional ayanamsa | `result["vara"]`, `result["solar_events"]` |
| `secondary_progressions` **beta** | `calculateSecondaryProgressions` | birth and target civil time; optional zodiac/ayanamsa/house_system | `result["progressed_planets"]`, separate natal_context |
| `varga_svg` **beta** | `calculateVargaSvg` | birth; optional ayanamsa/division/layout/theme/`include_png` | `result["svg"]`, `result["chart"]`, optional `result["png"]` |
| `lunar_nodes` **beta** | `calculateLunarNodes` | at civil instant without coordinates; optional zodiac/ayanamsa | `result["mean"]["north"]`, `result["true"]["north"]` |
| `returns` **beta** | `calculateReturns` | birth, body sun/moon, after civil time; optional zodiac/ayanamsa/house_system/location | `result["return_utc"]`, `result["chart"]`, `result["search"]` |
| `solar_arcs` **beta** | `calculateSolarArcs` | birth and target civil time; optional zodiac/ayanamsa/house_system | `result["arc"]`, `result["directed_planets"]`, `result["directed_angles"]`, `result["directed_houses"]` |
| `moon_phases` **beta** | `calculateMoonPhases` | instant `at` or calendar civil `start`/`end`; optional display timezone and `include_ical` | `result["result"]["phase_sector"]` or `result["result"]["events"]`; optional `result["result"]["ical"]` |
| `planetary_events` **beta** | `calculatePlanetaryEvents` | whole-second UTC interval, event types/bodies; optional aspects/zodiac/ayanamsa | `result["result"]["events"]` |
| `house_ingresses` **beta** | `calculateHouseIngresses` | reference birth, whole-second UTC interval, bodies; optional Equal/Whole Sign and zodiac/ayanamsa | `result["result"]["events"]`, fixed cusps |
| `aspect_windows` **beta** | `calculateAspectWindows` | whole-second UTC interval, bodies; optional aspects/orb/zodiac/ayanamsa/iCalendar | `result["result"]["windows"]` |
| `event_calendar` **beta** | `calculateEventCalendar` | whole-second UTC interval and selected event families | `result["result"]["events"]`; optional iCalendar, strict opt-in fixed-column CSV, and opt-in deduplicated pass groups |
| `event_rule_search` **beta** | `calculateEventRuleSearch` | bounded versioned AND/OR/NOT rules, location, and interval | validation/cost analysis plus sampled matches and windows |
| `convention_compare` **beta** | `calculateConventionCompare` | two profiles with one birth, or two trusted signed responses | field-level differences without ranking or interpretation |
| `chart_robustness` **beta** | `calculateChartRobustness` | unknown or approximate birth time plus 2–3 convention profiles | sampled stability classifications without rectification, ranking, or prediction |
| `civil_time_audit` **beta** | `calculateCivilTimeAudit` | pinned place, local date/time, one explicit profile | both repeated-time chart candidates and exact 22-fact differences, or no shifted gap time |
| `chart_input_readiness` **beta** | `calculateChartInputReadiness` | pinned place, exact/approximate/unknown time quality, explicit profile | route readiness plus resolved, candidate, or sampled evidence for 22 facts |
| `house_system_readiness` **beta** | `calculateHouseSystemReadiness` | exact birth and explicit tropical/sidereal profile | fixed 25-system availability matrix with fingerprints and no fallback |
| `house_placement_stability` **beta** | `calculateHousePlacementStability` | exact birth and explicit tropical/sidereal profile | exact assignments, unweighted agreement ratios, and deterministic equivalence groups across available 12-house systems |
| `aspect_policy_stability` **beta** | `calculateAspectPolicyStability` | exact birth, explicit profile, optional 3–10 points, and 2–4 named aspect policies | admission reasons, signed orb margins, set fingerprints, and deterministic equivalence groups |
| `house_boundary_proximity` **beta** | `calculateHouseBoundaryProximity` | exact birth, explicit profile, optional 1–10 points and 0.1–10° threshold | exact two-sided cusp clearance, normalized position, nearest-boundary ties, and explicit no-fallback geometry failures |
| `location_precision_audit` **beta** | `calculateLocationPrecisionAudit` | exact birth, one explicit 12-house system, 0.1–500 km radius, optional 1–10 points | nine sample rows, planet-house stability, maximum angle/cusp displacement, and explicit no-fallback geometry failures |
| `location_transition_scan` **beta** | `calculateLocationTransitionScan` | exact birth, one explicit 12-house system, 1–500 km maximum radius, optional 1–10 points | 65 checkpoints and per-bearing first observed angle-sign, cusp-sign, and planet-house transition brackets or explicit failure states |
| `chart_uncertainty_envelope` **beta** | `calculateChartUncertaintyEnvelope` | exact birth, one explicit 12-house system, 5–180 minute uncertainty, 0.1–500 km radius, optional 1–10 points | full-factorial 7-time × 9-location evidence separating time-axis, location-axis, combined, and interaction-only observed variation |
| `electional_robustness_audit` **live beta** | `calculateElectionalRobustnessAudit` | exact event, explicit zodiac profile, electional filters, 5-180 minute tolerance, and 0.1-500 km radius | fixed 7-time x 9-location rule evidence with axis-level failure attribution; live in R231 |
| `electional_tolerance_frontier` **live beta** | `calculateElectionalToleranceFrontier` | exact event, explicit zodiac profile, electional filters, 5-180 minute maximum shift, and 0.1-500 km radius | ten-step earlier/later and eight-bearing observed match/failure brackets; live in R231 |
| `electional_feasibility_audit` **live beta** | `calculateElectionalFeasibilityAudit` | whole-second UTC interval up to seven days, location, explicit zodiac profile, electional filters, and 15/30/60 minute sampling | sampled feasibility, all blocking signatures, and inclusion-minimal failed-rule sets with exact witnesses; live in R231 |
| `electional_resolution_audit` **live beta** | `calculateElectionalResolutionAudit` | whole-second UTC interval up to seven days, location, explicit zodiac profile, and electional filters | one finest grid, aligned 30/60-minute projections, observed runs, and exact missed-run witnesses; live in R231 |
| `electional_sampling_phase_audit` **live beta** | `calculateElectionalSamplingPhaseAudit` | whole-second UTC interval up to seven days, location, explicit zodiac profile, and electional filters | all 30/60-minute sampling phases, observed runs, and exact phase-sensitive witnesses; live in R231 |
| `electional_criterion_omission_audit` **live beta** | `calculateElectionalCriterionOmissionAudit` | feasibility-audit input with explicit 15/30/60-minute sampling | exact leave-one-rule-out samples, unique/cofailure counts, and contiguous runs; live in R231 |
| `electional_criterion_pair_audit` **live beta** | `calculateElectionalCriterionPairAudit` | feasibility-audit input with explicit 15/30/60-minute sampling | exact pair-only exclusion witnesses and contiguous pair-omission runs; live in R231 |
| `electional_criterion_relation_audit` **live beta** | `calculateElectionalCriterionRelationAudit` | feasibility-audit input with explicit 15/30/60-minute sampling | exact pairwise truth tables and observed relation counterexamples; live in R231 |
| `electional_criterion_budget_audit` **live beta** | `calculateElectionalCriterionBudgetAudit` | feasibility-audit input with explicit 15/30/60-minute sampling | all tied optimum rule sets at each exact omission budget; live in R231 |
| `electional_criterion_budget_stability_audit` **live beta** | `calculateElectionalCriterionBudgetStabilityAudit` | resolution-audit input with one fixed finest grid | universal versus grid-sensitive optimum rule sets; live in R231 |
| `electional_criterion_budget_regret_audit` **live beta** | `calculateElectionalCriterionBudgetRegretAudit` | resolution-audit input with one fixed finest grid | every exact minimax worst-grid-regret option with rational evidence; live in R231 |
| `electional_criterion_budget_pareto_audit` **live beta** | `calculateElectionalCriterionBudgetParetoAudit` | resolution-audit input with one fixed finest grid | every weight-free non-dominated exact-budget option with dominance certificates; live in R231 |
| `electional_criterion_shapley_audit` **live beta** | `calculateElectionalCriterionShapleyAudit` | resolution-audit input with one fixed finest grid | exact rational interaction-aware criterion attribution with per-grid efficiency proofs; live in R231 |
| `electional_criterion_conflict_core_audit` **live beta** | `calculateElectionalCriterionConflictCoreAudit` | resolution-audit input with one fixed finest grid | every inclusion-minimal sampled window-level rule conflict with per-member relaxation witnesses across seven grids; live in R231 |
| `electional_criterion_robust_repair_audit` **live beta** | `calculateElectionalCriterionRobustRepairAudit` | resolution-audit input with one fixed finest grid | every inclusion-minimal omission set feasible across all evaluable grids, with exact witnesses and blocking-grid certificates; live in R231 |
| `electional_criterion_repair_impact_audit` **live beta** | `calculateElectionalCriterionRepairImpactAudit` | resolution-audit input with one fixed finest grid | exact sampled consequence ledger for every minimal robust repair, including per-rule violations, histograms, and least-violation witnesses; live in R231 |
| `electional_criterion_repair_distinction_audit` **live beta** | `calculateElectionalCriterionRepairDistinctionAudit` | resolution-audit input with one fixed finest grid | exact sampled distinction certificate for every minimal robust-repair pair, including differing grids, exclusive counts, and one witness; live in R231 |
| `electional_criterion_repair_overlap_audit` **live beta** | `calculateElectionalCriterionRepairOverlapAudit` | resolution-audit input with one fixed finest grid | exact sampled overlap/containment relation, counts, reduced fraction, grids, and shared/directional witnesses for every minimal repair pair; live in R231 |
| `electional_criterion_repair_hierarchy_audit` **live beta** | `calculateElectionalCriterionRepairHierarchyAudit` | resolution-audit input with one fixed finest grid | exact containment poset, Hasse cover edges, maximum antichain, deterministic longest chain, and minimum chain cover; live in R231 |
| `electional_criterion_repair_coverage_audit` **live beta** | `calculateElectionalCriterionRepairCoverageAudit` | resolution-audit input with one fixed finest grid | exact support-signature groups, per-repair exclusive/multiple support, and single-repair union-loss certificates; live in R231 |
| `electional_criterion_repair_resilience_audit` **live beta** | `calculateElectionalCriterionRepairResilienceAudit` | resolution-audit input with one fixed finest grid | inclusion-minimal multi-repair failure coalitions and exact guaranteed-survival curves; live in R231 |
| `electional_criterion_repair_loss_frontier_audit` **live beta** | `calculateElectionalCriterionRepairLossFrontierAudit` | resolution-audit input with one fixed finest grid | exhaustive worst-case observation loss and complete failure-set histograms through three unavailable repairs; live in R231 |
| `electional_criterion_repair_hardening_audit` **live beta** | `calculateElectionalCriterionRepairHardeningAudit` | resolution-audit input with one fixed finest grid | exact single-repair protection counterfactuals and remaining worst-case failure witnesses through budget three; live in R231 |
| `electional_criterion_repair_hardening_pareto_audit` **live beta** | `calculateElectionalCriterionRepairHardeningParetoAudit` | resolution-audit input with one fixed finest grid | exact weight-free dominance, equivalence, incomparability, and all Pareto-undominated hardening ties; live in R231 |
| `electional_criterion_repair_hardening_pareto_hierarchy_audit` **live beta** | `calculateElectionalCriterionRepairHardeningParetoHierarchyAudit` | resolution-audit input with one fixed finest grid | exact hardening-profile dominance poset, successive Pareto layers, Hasse cover edges, maximum antichain, deterministic longest chain, and minimum chain cover; live in R231 |
| `electional_criterion_repair_hardening_regret_audit` **live beta** | `calculateElectionalCriterionRepairHardeningRegretAudit` | resolution-audit input with one fixed finest grid | exact weight-free regret against every failure-budget optimum and all least-maximum-regret hardening ties; live in R231 |
| `synastry_svg` **beta** | `calculateSynastrySvg` | two births; optional zodiac/houses/theme/aspects/`include_png` | `result["svg"]`, optional `result["png"]` |
| `transit_svg` **beta** | `calculateTransitSvg` | birth and transit date; optional display controls/`include_png` | `result["svg"]`, optional `result["png"]` |
| `natal_report` **beta** | `calculateNatalReport` | birth; optional zodiac/houses/theme/SVG/download | `result["html"]`, source-linked `result["facts"]`, optional `result["download"]` |
| `birth_time_sensitivity` **beta** | `calculateBirthTimeSensitivity` | civil interval up to six hours, or explicit unknown/approximate time, plus coordinates | `result["result"]["samples"]`, optional workflow classification |
| `fixed_stars` **beta** | `calculateFixedStars` | civil instant and 1–6 documented stars | `result["objects"]`; no minor bodies |
| `relocation_chart` **beta** | `calculateRelocationChart` | birth and destination coordinates; optional zodiac/ayanamsa/houses | `result["natal_reference"]`, `result["relocated_chart"]` |
| `astrocartography` **beta** | `calculateAstrocartography` | civil instant, 1–10 unique Sun-through-Pluto bodies, optional `include_geojson`, `include_geojson_seq`, `include_ndjson`, `include_topojson`, `include_kml`, `include_gpx`, `include_csv`, `include_wkt`, `include_wkb`, `include_gml`, `basemap`, `include_svg`, `include_png`, and `theme` | bounded geometry plus optional deterministic RFC 7946 GeoJSON, RFC 8142 GeoJSON Text Sequences, newline-delimited GeoJSON Features, unquantized TopoJSON, OGC KML 2.2, GPX 1.1, RFC 4180 CSV, WKT, WKB, GML 3.2 artifacts, and 1200×800 SVG/PNG coordinate-grid or bundled Natural Earth coastline map |
| `eclipse_geometry` **beta** | `calculateEclipseGeometry` | whole-second UTC interval up to 366 days, selected solar/lunar types, optional WGS84 observer | global events and optional sea-level/no-refraction snapshot in each event |
| `electional_search` **beta** | `calculateElectionalSearch` | location, one or more AND-only filters, and UTC interval up to seven days | hourly matches and sampled windows |
| `natal_analysis` **beta** | `calculateNatalAnalysis` | birth, aspect controls, and strict sidereal graha-drishti or partial-Shadbala opt-ins | aspects/patterns plus optional `graha_drishti` or `shadbala_foundation` |
| `planetary_hours` **beta** | `calculatePlanetaryHours` | civil date, IANA timezone, and coordinates | twenty-four unequal day/night temporal hours and rulers |
| `davison` **beta** | `calculateDavison` | personA/personB; optional zodiac/ayanamsa/house_system | `result["chart"]`, `result["midpoint"]`, `result["metadata"]` |

The never-live extended-sky methods were retired rather than depend on licensed
minor-body source data. They are not SDK methods or API contracts.

Graha drishti is a separate opt-in on `natal_analysis`. Exact `True` requires
explicit `zodiac: "sidereal"`; omission/false preserves the existing response.
Ruleset `parashari_whole_sign_full_aspects_v1` includes Sun, Moon, Mars,
Mercury, Jupiter, Venus, and Saturn only. It returns full whole-sign targets and
occupying classical grahas, with no node aspects, partial strengths, or
interpretation. The request remains one standard quota unit.

Synastry cross-aspects retain `transit` for person B and `natal` for person A.
The horoscope route is a beta, deterministic structured interpretation; it is
not a stable prose-report or LLM contract. Birth-chart/aspects compute both
legacy house systems; the houses method filters to the requested system.
Its `placidus`, `porphyry`, `meridian`, `campanus`, `regiomontanus`,
`alcabitius`, `koch`, `morinus`, `topocentric`, `sripati`, `vehlow`, `horizon`, `krusinski`, `sunshine`, `sunshine_alt`, `savard`, `pullen_sd`, `pullen_sr`, `carter`, `apc`, `equal_mc`, and `natural` options are beta, with explicit rejection and no fallback. Gauquelin is Houses-only because its response contains 36 sectors; natal
SVG accepts the preceding twelve-house systems, while other chart/report routes do not accept
Porphyry, Meridian, Campanus, Regiomontanus, Alcabitius, Koch, Morinus, Topocentric, Sripati, Vehlow, Horizon/Azimuth, Krusinski-Pisa-Goelzer, Sunshine, Sunshine alternative, Savard-A, Pullen SD, Pullen SR, Carter, APC, Equal MC, or Natural. Meridian cusp 1 is
the Equatorial Ascendant; Campanus, Regiomontanus, Alcabitius, and Koch cusp 1
are the physical Ascendant. Morinus cusps are latitude-independent; its cusps 1 and 10 are not the physical Ascendant and Midheaven. Topocentric uses Polich/Page house geometry with the physical Ascendant and Midheaven as cusps 1 and 10; it does not alter planet positions. Sripati shifts each cusp to the midpoint of the preceding Porphyry sector; its cusps 1 and 10 are not the physical angles. Vehlow uses twelve equal 30-degree ecliptic houses with the physical Ascendant at the center of house 1; its cusps 1 and 10 are not the physical angles. Horizon/Azimuth projects twelve equal local-horizon divisions through vertical circles to the ecliptic; cusp 1 is not the physical Ascendant and cusp 10 is the Midheaven. Krusinski-Pisa-Goelzer projects twelve equal Ascendant-zenith great-circle divisions through celestial meridian circles; cusps 1 and 10 are the physical Ascendant and Midheaven. Sunshine uses the Treindl construction from trisected solar diurnal and nocturnal semi-arcs; cusps 1 and 10 are the physical Ascendant and Midheaven. Sunshine alternative uses the separate Makransky prime-vertical projection for the same solar house points. Savard-A projects one-third and two-thirds geographic-latitude circles through the prime vertical; cusps 1 and 10 are the physical Ascendant and Midheaven and opposite cusps are antipodal. Pullen SD redistributes each ecliptic quadrant's deviation from 90 degrees with quarter/half/quarter weighting; cusp 10 is the physical Midheaven and cusp 1 uses the orientation-adjusted Ascendant. Pullen SR proportions complementary quadrant house widths as rx, x, rx and r³x, r⁴x, r³x; cusp 10 is the physical Midheaven and cusp 1 uses the orientation-adjusted Ascendant. Carter divides right ascension into twelve equal arcs from the orientation-adjusted Ascendant and projects them to the ecliptic; cusp 10 is not generally the physical Midheaven. APC divides the Ascendant parallel into six sectors below and six above the horizon; cusps 1 and 10 are the orientation-adjusted angles and intermediate opposite cusps are not generally antipodal. Equal MC fixes the physical Midheaven at cusp 10 and places twelve equal 30-degree ecliptic houses; cusp 1 is generally not the physical Ascendant. Natural fixes cusp 1 at zero degrees Aries in the selected zodiac and places all cusps on sign boundaries; physical angles remain separate. Gauquelin is Houses-only and returns 36 clockwise semiarc sector boundaries under the existing houses map; sector 1 is Ascendant and sector 10 is Midheaven. Regiomontanus, Alcabitius, Koch, Morinus, Topocentric, Sripati, Vehlow, Horizon/Azimuth, Krusinski-Pisa-Goelzer, Sunshine, Sunshine alternative, Savard-A, Pullen SD, Pullen SR, Carter, APC, Equal MC, Natural, and Gauquelin are not admitted by saved
profiles. Equal/Whole Sign remain the existing chart defaults.

```python
timeline = client.nakshatra_timeline({
    "planet": "moon",
    "start_utc": "2026-01-01T00:00:00Z",
    "end_utc": "2026-01-03T00:00:00Z",
    "ayanamsa": "lahiri",
})
```

The timeline is Pro-only, always sidereal, supports the nine documented bodies,
and allows a positive range up to 180 days. It uses a separate quota. It does not
accept a sampling-step override. Dates across routes remain limited to
1900–2050. Legacy chart nodes and timeline Rahu/Ketu remain mean-node calculations;
the separate `lunar_nodes` beta supplies a distinct geometric osculating model.
Installing the SDK does not change any existing calculation convention or accuracy.

The SVG route accepts birth data, not an uploaded chart, SVG, URL, font or image.
Defaults are Equal houses, light theme, major aspects shown, tropical zodiac
and Lahiri when sidereal. The result contains an SVG string inside JSON; it is
not a browser credential or hosted-widget API.

Natal, synastry, transit and varga SVG plus natal report accept exact `light`,
`dark`, or `monochrome`. Defaults are unchanged. Monochrome is a fixed
grayscale palette, not an accessibility certification; optional PNG pixels are
grayscale while retaining RGB encoding.

Natal report HTML accepts optional `report_branding` with a required 1–64 character bounded ASCII `display_name` and optional exact `amber`, `blue`, or `green` accent. It is escaped, text-only, visibly attributed to Cosmic Ephemeris, and invalid with non-HTML formats; omission preserves exact predecessor bytes. No logo, URL, markup, template, remote resource, localization, or fact mutation is accepted.

Natal report downloads accept exact `include_download: True`. Omitted
`download_format` retains HTML; exact `pdf`, `docx`, `xlsx`, `ods`, `epub`, `odt`, `rtf`, `json`, `csv`, `xml`, `ndjson`, `tsv`, `markdown`, `text`, or
`zip` selects deterministic PDF, editable macro-free OOXML, editable
macro-free and formula-free OOXML workbook, macro-free ODF 1.3, editable dependency-free RTF, machine-readable JSON, tabular CSV, fixed-order XML, canonical one-record-per-fact NDJSON, escaped fixed-column TSV, UTF-8 calculation facts/plain text, or the unchanged fixed
HTML/PDF/calculation-JSON bundle.

Vargas and Vimshottari always use sidereal coordinates with Lahiri default.
Vargas supports D1/D2/D3/D4/D5/D6/D7/D8/D9/D10/D11/D12/D16/D20/D24/D27/D30/D40/D45/D60/D81/D108/D144/D150 (default D9) for nine traditional bodies plus the
Ascendant, not outer planets. Vimshottari returns nine major periods, each with
nine subperiods, using a fixed 365.25-day Julian year. Its first period begins
at the theoretical natal-major start, which can precede birth. Arithmetic
schedule dates may extend outside the ephemeris input-date window; they are
not predictions or additional ephemeris calculations. Optional `depth: 3` adds
one fixed third level; omission or `depth: 2` preserves the original response.
No arbitrary depth,
year model, range or specialist signoff is claimed. Each of these beta routes
costs one standard-call unit under unchanged plan quotas/prices and uses the
normal request deadline.

## Validation, deadlines and errors

The client checks required fields, supported enums, numeric coordinate bounds,
date/time formats, timeline ranges and the 128 KiB request limit before sending.
It accepts JSON numbers for coordinates and documented lowercase enum values;
unknown fields and explicit null optionals are rejected. Omit unused optional
fields. Timezone identifiers, DST ambiguity/nonexistence and undefined
Ascendant geometry remain server validation. Supplying a known UTC instant
avoids ambiguous local clock changes. No defaults are inserted into payloads.

Normal requests have a 20-second caller deadline; planetary events, eclipse geometry, electional search, event rules and aspect windows have 35 seconds; timelines, birth-time sensitivity, electional robustness audit, electional tolerance frontier, electional feasibility audit, and electional resolution audit have 70 seconds.
Configure `timeout=`, `planetary_events_timeout=`, and `timeline_timeout=` with finite positive seconds up to
300. The deadline covers network establishment, TLS, headers, response body and
JSON parsing, but starts after local input validation/serialization.

The synchronous call uses a daemon transport worker so a stalled operating-system
DNS lookup or slowly arriving headers/body cannot keep the caller waiting past
its deadline. Cancellation shuts down the known socket. A DNS call itself
cannot be forcibly stopped; its worker retains a slot until it exits and checks
cancellation before sending credentials. There are at most eight outstanding
transport workers **across all client instances in a process**. Exhaustion raises
`ClientBusyError` without starting another request. No context manager or explicit
close is needed; every completed exchange closes its connection. Successful
calls do not reuse connections.

`max_response_bytes=` defaults to 4 MiB and may be set from 1 byte through 64 MiB.
Oversized, truncated, compressed, non-object, duplicate-key or malformed JSON
responses are rejected. Bodies are read incrementally; compressed responses are
not decompressed. The standard library also limits HTTP header count and line
length. Errors omit request payloads, response bodies, credentials, raw headers,
and underlying transport exceptions. `HTTPError` exposes only numeric `status`
and sanitized `retry_after` (integer seconds or a normalized HTTP date).

There are **no automatic retries**, including for 429, 503 or timeouts. Once the
gateway reserves quota, even an invalid payload, dependency failure or timeout
consumes a unit. A client disconnect does not cancel admitted server work.

## Transport origin

The default is `https://api.cosmicephemeris.com`; calls use `POST /api/astro/...` with
`Authorization: Bearer`. A custom `base_url` must be a trusted HTTPS origin
without a path, credentials, query or fragment. Selecting another HTTPS origin
authorizes sending your key to that origin. TLS certificates and hostnames are
verified. Proxy environment variables, cookies and redirects are not used.
Every redirect is returned as `HTTPError`; keys are never forwarded to its
destination.

For local Node gateway testing only:

```python
client = CosmicEphemerisClient(
    api_key=your_synthetic_key,
    base_url="http://127.0.0.1:5100",
    allow_http_localhost=True,
)
```

HTTP requires explicit opt-in and both a loopback/localhost URL and a loopback
connected peer. Never point the client directly at the internal Python engine.

## Offline checks

From this directory, after local installation:

```sh
python -m unittest discover -s tests -v
```

Tests use generated synthetic keys and local HTTP/HTTPS servers. Real TLS tests
generate temporary certificates with local OpenSSL and explicitly skip if it is
unavailable; no certificate keys are committed. They do not call the
production API or Stripe. The example under `examples/` makes a billable API
request when explicitly run with a real key. Its executable-example test replaces
the transport with a local mock and uses no real account key.

## Additional bounded beta calculations

- Composite: strict personA/personB birth objects; shortest-arc planetary and angle midpoints. Equal/Whole Sign houses are synthetic from midpoint Ascendant, not physical/Davison houses. Near-antipodal sources reject; no Placidus, nodes or speeds.
- Panchang: strict at civil snapshot and optional ayanamsa, always sidereal. Latitude is inclusive [-88,88]. Classifications are at the requested instant; solar events use the USNO -50 arcminute horizon at elevation 0, not Hindu-geocentric sunrise. Civil weekday and sunrise-based vara differ. Unavailable bounded sunrise gives explicit null vara. Historical local offsets can include seconds; paired UTC fields are interoperable.
- Secondary progressions: strict birth plus target date/time/timezone, target>=birth. Planets only, fixed 365.2421904-day year in uniform TT; natal_context angles/houses are not progressed. Derived progressed_utc may contain actual leap second 60; preserve the string rather than passing it blindly to JavaScript Date/Python datetime. No progressed angles/houses/aspects/nodes/speeds or prediction claim.
- Varga SVG: birth plus optional ayanamsa, any supported D1/D2/D3/D4/D5/D6/D7/D8/D9/D10/D11/D12/D16/D20/D24/D27/D30/D40/D45/D60/D81/D108/D144/D150 division, layout north_indian/south_indian and theme light/dark/monochrome. Defaults D1/north_indian/dark; /vargas instead defaults D9. Original North fixed-house/South fixed-sign SVG, houses counted from divisional Ascendant; not bhava-chalit. Response.chart is the unchanged Vargas result; SVG is bounded to 128 KiB inside JSON.
  D150 additionally accepts exact `d150_method` values `"deva_keralam_chandra_kala_nadi_non_uniform"`, `"deva_keralam_chandra_kala_nadi_uniform_direct"`, `"parivritti_cyclic"`, `"movable_aries_forward_fixed_taurus_reverse_dual_gemini_forward"`, `"movable_aries_forward_fixed_scorpio_reverse_dual_sagittarius_forward"`, `"movable_aries_forward_fixed_leo_reverse_dual_sagittarius_forward"`, and `"movable_source_sign_forward_fixed_source_sign_reverse_dual_source_sign_forward"`; omission retains the uniform-direct D150 response, and the field is rejected for every other division.

- Lunar nodes: `lunar_nodes` takes an `at` civil instant with no coordinates and optional zodiac/ayanamsa. The response provides north/south pairs for Meeus mean nodes and geometric DE421 osculating nodes, each with its explicit source frame. `LunarNodesInput` and `LunarNodesResponse` are exported types. Chart and timeline node fields keep the existing mean-node contract.
- Returns: `returns` takes birth, exact body `sun` or `moon`, and an `after` civil instant. Optional zodiac/ayanamsa, Equal/Whole Sign houses and `location:{lat,lon}` are supported; location defaults to birth coordinates. `ReturnsInput` and `ReturnsResponse` type the new request/envelope. Read `return_utc`, `chart` and `search`. The first return lies beyond a one-millisecond start exclusion and the full fixed 370-day Sun/32-day Moon TT window must fit the supported UTC range. `after` may precede birth. Preserve leap-second UTC strings; numerical tolerance does not establish physical accuracy.

- Solar arcs: `solar_arcs` takes strict birth plus target civil time and optional zodiac/ayanamsa/Equal or Whole Sign houses. Omitted `method` and exact `true_solar_arc` preserve the direct true tropical Sun arc. Exact `method: "mean_naibod"` applies the fixed 0.98564733° mean longitude key per elapsed 365.2421904-day TT model year. Both methods direct natal planets and Ascendant/MC uniformly and retain synthetic houses, one-unit accounting, the 1900–2050 dates, and natal-date ayanamsa policy. No relocation, converse/right-ascension arc, MC-derived angle recalculation, arbitrary key, aspects, nodes or speeds.
- Vimshottari depth: `depth` accepts integer 2, 3, or 4. Omission/2 and the complete depth-3 response remain unchanged. Depth 4 adds 6,561 Sookshma leaves, `birth_balance.sookshma_dasha_lord`, and exact count metadata. Fourth-level leaves omit the redundant display-only `years` field so the complete response stays below 1 MiB. Python rejects floats, strings and booleans. Depth 4 is synchronous-only under the durable-job 256 KiB cap. The arithmetic is bounded and deterministic, not arbitrary recursion or prediction; an admitted synchronous call costs one standard unit.
- Eclipse geometry: `eclipse_geometry` searches at most 366 UTC days. Optional `observer` coordinates add a fixed sea-level, no-refraction topocentric snapshot at each rounded global maximum. It does not calculate the location's maximum, contacts, visibility at other instants, paths, maps, terrain/weather, safety guidance or interpretation.
- Electional search: `electional_search` applies one or more documented AND-only filters at fixed hourly samples for at most seven days/168 samples. Results are sampled candidates without continuous guarantees, ranking, recommendations, void-of-course analysis or interpretation.
- Natal analysis: `natal_analysis` returns configured aspects, optional midpoint axes, and geometric Grand Trine, T-square, Grand Cross, and Yod matches for selected Sun-through-Pluto points. `additional_points` may explicitly select Vertex/Antivertex, Equatorial Ascendant/Descendant, and Lots of Fortune/Spirit; they stay separate from aspects and interpretation.
- Planetary hours: `planetary_hours` returns twelve daylight and twelve nighttime unequal temporal hours with Chaldean rulers. It requires a complete sunrise-sunset-next-sunrise sequence and supplies no electional advice.

All thirty deployed additive beta routes reserve one standard-call unit, accept only exact documented fields/enums, and retain existing prices, quotas and no automatic retry. Practitioner sign-off and a complete astrology catalogue are not claimed.

### Aspect windows beta

Use `client.aspect_windows(...)` for exact-hit-anchored major-aspect orb intervals, repeat numbering, clipped boundaries and optional RFC 5545 text. Inputs span at most 31 UTC days and use a 35-second default deadline.
