astrology-engine

Astrology Engine — Volmarr's Longhall

Full-spectrum astrological computation. Swiss Ephemeris on bare metal. Norse sky, Hellenistic roots, Vedic depth.

The Astrology Engine is a reproducible computation forge for astrology: real ephemeris positions, strict time and location handling, and machine-readable output — no cloud, no API keys, no lookup tables, no fabricated chart positions. Forty-seven CLI subcommands span Western, Hellenistic, Vedic (Jyotisha), Northern runic, divination, Chinese, and Tibetan traditions, with every technique carrying its provenance, its limits, and its evidence.

The project's rule, held since the first commit: compute it honestly, prove it with tests, document what it cannot do, and push every slice.

What it does

This is not a keyword reader or a chart-wheel generator. The engine:

• Calculates real ephemeris positions via Swiss Ephemeris (pyswisseph), with disclosed Moshier fallback when Swiss data is unavailable
• Converts civil time to UTC with strict IANA timezone handling — DST folds and gaps reject rather than guess
• Casts natal charts with houses, angles, aspects (applying/separating), essential dignities, Arabic Lots, antiscia, and Hellenistic analysis (sect, bonification, joys, triplicity, bounds)
• Runs Jyotisha: sidereal D1, 16 classical vargas, Vimshottari dashas, instant panchanga, nakshatras and padas
• Walks the Northern runic cycles: half-month runes, solar runic hours, Northern planetary hours, sele detection — from a fully transcribed, honestly-labeled corpus
• Finds exact transit dates, stations, ingresses and eclipses with a precision-aware event root finder
• Draws astrocartography MC/IC/ASC/DSC lines and relocation charts from spherical geometry, not lookup tables
• Answers as JSON or text, with capability discovery (capabilities) and agent tool schemas (tools) for the Hermes agent skill

Every result records its conventions, input certainty, backend and version, and warnings. A technique is only advertised when it is implemented, tested, and documented — never merely planned.

The 47 subcommands

The Runic Star-Program

A dedicated expansion, ROADMAP_RUNIC.md, is giving the engine the full runic astrology of the Northern Tradition as systematized by Nigel Pennick in Runes and Astrology (2023) — built slice by slice, each slice pushed, each table labeled modern synthesis, computation forever kept separate from interpretation.

Delivered — the full program:

Try it: python3 astrology_engine.py runic --datetime 2026-05-16T16:45 --lon 0 --timezone UTC --full

Honest transcription is the law here: the book's own quirks (a noon discontinuity in the planetary-hour grid, a worked example that conflicts with the hour-wheel) are preserved in per-section notes, never silently "corrected".

The Oracles Program

A second expansion, ROADMAP_ORACLES.md, gave the engine six further divination arts — built slice by slice, each slice pushed, each historical claim labeled, computation forever kept separate from interpretation.

Delivered — the full program:

Try it: python3 astrology_engine.py tibetan 1972-09-01

Honesty is the law here too: rune-poem meanings are distinguished from modern synthesis, tree-lore caveats are recorded, calendrical anchors are cross-checked against published tables rather than recalled, and where Tibetan lineages disagree the disagreement is documented, not smoothed over.

Quick start

# Full natal chart (text)
python3 astrology_engine.py natal \
  --date 1972-09-01 --time 08:18 \
  --lat 42.8142 --lon -73.9396 --timezone America/New_York

# Reproducible chart as JSON (typed path)
astroengine chart --date 1972-09-01 --time 08:18 \
  --latitude 42.8142 --longitude -73.9396 --timezone America/New_York

# Vedic D1 with nakshatras
astroengine vedic --date 1972-09-01 --time 08:18 \
  --latitude 42.8142 --longitude -73.9396 --timezone America/New_York

# Runic half-month for today
python3 -c "
from astroengine.runic import half_month_rune
import datetime
print(half_month_rune(datetime.date.today().isoformat()))"

# Lunar intelligence right now
python3 astrology_engine.py lunar

# What exact transits hit in the next year?
python3 astrology_engine.py predict \
  --date 1972-09-01 --time 08:18 \
  --lat 42.8142 --lon -73.9396 --timezone America/New_York \
  --start 2026-01-01 --end 2027-01-01

# What can the engine do, as JSON?
astroengine capabilities

Installation

Requirements: Python 3.11+, and a C compiler for pyswisseph only if no wheel exists for your platform (wheels cover Linux, macOS, Windows).

# Core install
python -m pip install .

# With geo support (timezonefinder) and test tooling
python -m pip install '.[geo,test]'

# Verify
astroengine capabilities
python -m pytest -q        # full suite, offline, explicit coordinates

The engine runs on a Raspberry Pi 5, a laptop, or a server — anywhere Python 3.11+ runs. No network calls are made at runtime; tests are fully offline.

Provenance and honesty

• Backends are disclosed. Every computation reports the actual ephemeris backend (Swiss vs Moshier) and flags. Optional bodies (Chiron, asteroids) report unavailability instead of faking positions.
• Time is strict. Unknown birth times produce flagged local-noon charts with no houses or angles. Ambiguous or nonexistent DST times reject until disambiguated. Timezone input is explicit IANA or UTC.
• Techniques are versioned. data/*.json holds immutable rule tables; nothing mutates them at runtime. Capabilities report what is implemented, tested, and documented — roadmap items stay visibly planned.
• Interpretation is separate. The engine computes positions and cycle memberships. Symbolic readings (runic or otherwise) are a distinct, labeled layer. Nothing here is a validated predictor or advice engine.
• Evidence is kept. VERIFICATION.md records test evidence and limits; DEVLOG.md is the living build record.

Hermes agent integration

SKILL.md is the checked-in Hermes skill: capability discovery, eight tool schemas, local whitelisted routing, and cited explanations. An agent asks astroengine capabilities, selects a tool, and receives JSON-safe, provenance-bearing results — no prompt-engineering folklore required. See data/tool_schemas.json.

Mythic Engineering

This repo is built with Mythic Engineering: vision, domain, interface, execution, verification — worked through six roles in order, every slice:

Each slice follows the loop: task document → implement → verify → update docs → commit → push → confirm remote HEAD → next slice. No force pushes. No deletions without the human's word. Read AGENTS.md and RULES.AI.md before touching code.

File structure

Further reading

• ROADMAP.md — the complete expansion program
• ROADMAP_RUNIC.md — the runic star-program
• ARCHITECTURE.md / DESIGN_PRINCIPLES.md
• PHILOSOPHY.md — why reproducible astrology matters
• VERIFICATION.md — evidence and limits
• docs/README_classic.md — the previous README, preserved

Heill, traveler. The stars are computed truly here — what you make of them is your own wyrd. — Yrsa Freydisdottir, for Volmarr