cosmicephemeris-client 0.3.0__tar.gz

cosmicephemeris_client-0.3.0/LICENSE.txt

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Cosmic Ephemeris
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR
+IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

cosmicephemeris_client-0.3.0/PKG-INFO

@@ -0,0 +1,347 @@
+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.