Western Oracle Adapter Contract

This contract defines how external Western astrology outputs enter the high-rigor Jyotish workflow.

Purpose

scripts/western_oracle_adapter.py converts an external Western astrology JSON export into the standard western_evidence_packet.

It is an evidence adapter, not a bundled Western astrology engine.

Native Tropical Natal Layer

scripts/western_chart_engine.py uses the existing Swiss Ephemeris binding to calculate a tropical natal chart from birth data. For direct_chart and rectification, the unified workflow defaults to western_mode: "auto" when no external payload is supplied. It records planetary longitude/speed, Placidus houses, ASC/MC/DC/IC, major aspects with explicit orb limits, element/mode distribution, and traditional house-ruler chains.

The native result is deliberately partial: it does not calculate secondary progressions, solar arcs, non-solar returns, synastry, or interpretive signals. prashna does not receive a natal Western packet by default. Set western_mode to external_only or off to suppress automatic calculation. Explicit western_evidence_packet and western_oracle_payload always take precedence.

Optional Timing Input

To add only requested native time evidence, pass:

{
  "western_timing": {
    "transit_date": "2026-07-09",
    "solar_return_year": 2026,
    "secondary_progression_date": "2026-07-09",
    "solar_arc_date": "2026-07-09",
    "converse_secondary_progression_date": "2026-07-09",
    "converse_solar_arc_date": "2026-07-09",
    "midpoint_date": "2026-07-09",
    "lunar_return_start_date": "2026-07-01",
    "duration_scan_start_date": "2026-07-01",
    "duration_scan_end_date": "2026-07-31",
    "parans_date": "2026-07-09"
  }
}

transit_date produces a local-date transit-to-natal major-aspect snapshot. solar_return_year locates the exact tropical solar return and calculates its return chart at the supplied birthplace/location. Both are calculation data, not event verdicts. secondary_progression_date uses one ephemeris day per tropical year for progressed planets. solar_arc_date applies the true secondary-progressed-Sun arc to natal planets/ASC/MC. converse_secondary_progression_date and converse_solar_arc_date add the matching backward-progressed layers. midpoint_date emits natal midpoint geometry and transit midpoint conjunction/opposition hits. lunar_return_start_date finds the next exact tropical lunar return. duration_scan_start_date plus duration_scan_end_date groups daily transit-to-natal aspect windows. These remain evidence layers, not event verdicts. Progressed angles are marked blocked until a method is selected; parans_date currently returns a structured blocked state because a latitude-aware rising/setting/culminating solver is not yet implemented.

Accepted Input

{
  "source_engine": "kerykeion_external_json",
  "natal": {
    "ascendant": "Virgo",
    "mc": "Gemini"
  },
  "timing_techniques": {
    "solar_return": {
      "annual_focus": "career"
    }
  },
  "aspects": [
    {
      "date": "2026-07-07",
      "planet": "Uranus",
      "aspect": "conjunction",
      "target": "MC"
    }
  ]
}

Explicit signals may be provided. When present, explicit signals are preserved and aspect-derived signals are not guessed.

Derived Signal Rules

The adapter currently maps only a small auditable subset:

Aspect Pattern	Signal
Uranus conjunction MC/Midheaven	`career_relocation / career_triggered_relocation`
Jupiter trine/sextile Mercury/Venus/MC	`career / client_cooperation_opportunity`
Saturn conjunction Sun/Mercury/Venus	`career / career_responsibility_test`

More mappings require tests and source notes before being added.

Entry Points

API and MCP callers may pass either field:

western_oracle_payload: raw external Western astrology JSON export; the project normalizes it with western_oracle_adapter.
western_evidence_packet: pre-normalized packet; the project carries it directly into runtime_evidence_log.
western_mode: auto (default for non-Prashna birth-chart entries), external_only, or off.

When Jyotish evidence also carries matching cross_system_signals, Cross-System Arbitration can become used. If only Western evidence is present, arbitration stays partial or blocked.

CLI

python3 scripts/western_oracle_adapter.py \
  --input /path/to/western_oracle.json \
  --theme career \
  --question-type career

The command prints a western_evidence_packet JSON object.

License Boundary

The premium skill may accept JSON exports from Kerykeion, Flatlib, Immanuel, Astro.com, GongShenXing, or desktop software.

Do not copy third-party source code into the premium package unless the exact project and dependency licenses permit bundling.

The adapter stores derived evidence and source labels only.

4.8 KiB Raw Blame History