# caelus

MIT astrological ephemeris engine in TypeScript. Zero dependencies, zero
I/O in core (data injected). Computes apparent geocentric positions for
sun, moon, mercury..pluto, chiron, mean_node, true_node (+ mean_lilith,
true_lilith,
ceres, pallas, juno, vesta, pholus,
cupido, hades, zeus, kronos, apollon, admetos, vulkanus, poseidon on
request); speeds, retrograde flags, ecliptic lat, distance (AU), RA/Dec;
tropical or sidereal zodiac (lahiri, fagan_bradley, krishnamurti, raman,
yukteshwar, galcent_0sag, true_citra); topocentric option; ASC/MC/vertex/east point; 12 house
systems (placidus, porphyry, equal, whole_sign, koch, regiomontanus,
campanus, alcabitius, morinus, meridian, polich_page, vehlow); major
aspects; pheno (phase, elongation, diameter, magnitude), equation of
time, az/alt, refraction; 318 fixed stars (HYG catalog); Gauquelin
sectors; event search (rise/set/meridian transits,
zodiac crossings, lunar phases, stations, solar/lunar eclipses). Higher layers: derived charts (returns, progressions, solar arc, composite, Davison, harmonics, antiscia, declination aspects, dignities, sect), electional primitives (applying/separating, combustion/cazimi, planetary hours, void-of-course Moon, house placement), the when() declarative query engine, the turbo longitude tier, and scan/rankMoments ranked time search, the 3D great-circle aspect (angularSeparation3d), astrocartography angle lines, ephemeris time series, a chart feature space with configuration search (chart-to-vector, cosine similarity, searchConfigurations), and a geometric compiler that inverts geometric constraints to a chart form and flags impossible ones. Supported range 1800-2149 (1850-2150 Chebyshev
tiers). Verified per-body vs Swiss Ephemeris (1900-2099): Sun-Saturn
<=1", Uranus <=1.9", Neptune <=4.6", Moon <=2.5", Pluto <=2.5" (series
valid 1885-2099), Chiron <=1", mean node <=1", true node <= 1' vs SE's
built-in ephemeris, mean lilith <=1.3", the 8 new
house systems exact; sidereal adds <=0.3". TS engine pinned to a Python
reference by 3,218 golden checks (worst diff 0.41e-9 arcsec).
Repo: https://github.com/heavyblotto/caelus
## Install

- caelus@0.11.0 — the engine
- caelus-birth@0.11.0 — local birth time + place -> UT (use this; see below)
- caelus-wheel@0.11.0 — React SVG chart wheel, plus ChartSphere (3D), AstroMap (astrocartography), EphemerisGraph
- caelus-mcp@0.11.0 — MCP server, 9 chart tools over stdio; also hosted over MCP Streamable HTTP (stateless) at https://www.ephemengine.com/api/mcp
- caelus-engine (PyPI) — the Python reference engine (no numpy), https://pypi.org/project/caelus-engine/

## Entry points

- `caelus` — Engine, BODIES, julianDay, mod, fmtLon, types
- `caelus/data-embedded` — bundled coefficient data (~85 KB gz), browser/edge
- `caelus/node` — loadNodeData(dir, vsopTier, moonTier) fs loader, Node only

```ts
import { Engine } from "caelus";
import { embeddedData } from "caelus/data-embedded";
const engine = new Engine(embeddedData);
const chart = engine.chart(1990, 6, 10, 18, 30, 0, 27.95, -82.46, "placidus");
// options form: house system, sidereal zodiac, extra bodies, topocentric
const sid = engine.chart(1990, 6, 10, 18, 30, 0, 27.95, -82.46,
  { houseSystem: "koch", zodiac: "sidereal:lahiri", bodies: ["mean_lilith"] });
```

## THE INPUT IS UT — not local time

`engine.chart(...)` takes UT date/time components. Converting a user's
local birth time with `new Date(localString)` uses the RUNTIME's timezone
and silently produces charts wrong by hours. Use caelus-birth:

```ts
import { toUT } from "caelus-birth";
const t = toUT({ year: 1990, month: 6, day: 10, hour: 14, minute: 30,
                 lat: 27.95, lon: -82.46 });   // local clock time + place
// t.utc -> UT components for engine.chart(); t.status flags DST edge cases
```

Longitude is EAST-positive everywhere (Americas are negative).

## Chart object shape

```ts
{
  jdUt: number,
  houseSystem, houseSystemRequested,  // differ when Placidus falls back
                                      // to whole_sign above polar circles
  zodiac,                             // "tropical" | "sidereal:<ayanamsa>"
  bodies: { [body]: { lon, speed, retrograde, sign, signDeg,
                      lat, dist, ra, dec } },  // degrees; dist in AU
  angles: { asc, mc, vertex, eastPoint },
  cusps: number[12],
  aspects: [{ a, b, aspect, orb }],
}
```

## More

- Validation tables: https://ephemengine.com/validation
- Data provenance:   https://ephemengine.com/provenance
- Hosted MCP endpoint (Streamable HTTP): https://www.ephemengine.com/api/mcp
- Pitfalls for coding agents: docs/agents.md in the repo
- MCP spec: MCP_SPEC.md in the repo