io.github.savecharlie/almanac

almanac

Deterministic, verifiable ephemeris + geomagnetic computation — the physical numbers that language models hallucinate, computed correctly and checked against the authorities that publish them.

Two pure-compute cores, no API keys, no network for the math, same inputs → same bytes:

• almanac.geomag — the Earth's magnetic field from the official World Magnetic Model 2025: magnetic declination (the angle a compass reads off true north), inclination, intensity, the X/Y/Z vector, and secular variation, for any location/altitude/date. Pure Python standard library — zero dependencies.
• almanac.ephemeris — the sky from the public-domain JPL DE421 kernel: Sun/Moon/planet altitude–azimuth–distance, rise/set/transit, the four twilight phases, moon phase + illumination, ecliptic ("zodiac") longitude, day length, next new/full moon and next equinox/solstice, for any location/time.

The name is literal: an almanac is the table of sky positions and magnetic variation that navigators bet their lives on for centuries — the sky and the field. This is that, made machine-checkable.

Why this exists

Ask a language model "what's the magnetic declination at 40°N 105°W in 2026?" or "where's the Moon over Tokyo right now?" and it will answer — confidently, and usually wrong. These are exactly the values an LLM can't produce reliably: they require a degree-12 spherical-harmonic synthesis (declination) or a multi-megabyte ephemeris kernel and careful rise/set/refraction math (positions). Getting them wrong points a ship, a drone, or a survey the wrong way.

almanac doesn't guess. It computes — deterministically — and the correctness is provable, not asserted:

Correctness (the whole point)

geomag is a faithful port of NOAA's geomag70 reference algorithm; the proof is the authority grading our independent synthesis against its own numbers. Run it yourself:

pip install -e ".[dev]"
pytest -q
# tests/test_geomag.py ....... 107 passed   (the 100 NOAA points + edge cases)
# tests/test_ephemeris.py .... 7 passed     (cross-engine + known-truth)

Quickstart

pip install -e .          # geomag works immediately (stdlib only)
                          # ephemeris pulls in skyfield + the public-domain DE421 kernel

from almanac.geomag import compute as field
from almanac.ephemeris import compute as sky

# Magnetic declination in Boulder, CO, mid-2026 — what your compass is off by:
f = field(lat=40.015, lon=-105.27, when="2026-06-26")
print(f["declination_deg"], "-", f["compass_note"])
# 7.6892 - magnetic north is 7.69 deg east of true north

# The sky over New York at a given instant:
s = sky(lat=40.7128, lon=-74.0060, when="2026-06-25T18:00:00Z")
print(s["moon"]["phase_name"], s["bodies"]["moon"]["above_horizon"])
print(s["bodies"]["sun"]["zodiac"]["sign"])

Every result is a plain JSON-serializable dict, fully labeled with units, and deterministic — the same query returns the same bytes, every time, on any machine.

API

almanac.geomag.compute(lat, lon, altitude_km=0.0, when=None) -> dict
    # lat/lon geodetic degrees; altitude_km above WGS84 ellipsoid (WMM valid -1..850);
    # when = ISO date/datetime, a bare decimal year like "2027.5", or "now"/None.
    # WMM2025 is valid 2025.0–2030.0. Declination positive = east of true north.

almanac.ephemeris.compute(lat, lon, elevation_m=0.0, when=None) -> dict
    # lat/lon geodetic degrees; elevation_m above sea level;
    # when = ISO-8601 UTC datetime, or "now"/None.

Use it from an AI agent (MCP)

LLMs answer "what's the magnetic declination at 40°N 105°W in 2026?" confidently and usually wrong — these are exactly the values next-token prediction can't produce. almanac ships a Model Context Protocol server so an agent can call the verified computation instead of guessing it:

uvx almanac-compute            # zero-install, stdio transport
# or
pip install almanac-compute && almanac-compute

Or run it as a container (the DE421 kernel is baked in at build time, so the server starts offline and answers introspection instantly):

docker build -t almanac-mcp .
docker run --rm -i almanac-mcp        # speaks MCP on stdio

Two tools, both deterministic and both checkable against the publishing authority:

• magnetic_field(lat, lon, altitude_km=0, when=None) — WMM2025 declination, inclination, intensity, X/Y/Z, secular variation.
• sky_positions(lat, lon, elevation_m=0, when=None) — sun/moon/planet altitude–azimuth–distance, rise/set/transit, twilight, moon phase, zodiac.

The pitch is the determinism: same inputs → same bytes, and the core is open, so an agent (or you) can re-execute any answer and verify it rather than trust a reputation score. That's the whole design — trust by re-execution, not by vote.

mcp-name: io.github.savecharlie/almanac

Data provenance & license

• Code (the synthesis, the wrappers, the tests): MIT — see LICENSE.
• WMM2025.COF + WMM2025_TestValues.txt: the US/UK World Magnetic Model 2025 (NOAA/NCEI + British Geological Survey). As a work of the US Government, public domain. Valid 2025.0–2030.0.
• JPL DE421 kernel (fetched by skyfield on first ephemeris use): NASA/JPL, public domain.

Per NOAA: the WMM is the standard navigation model but is not a substitute for local magnetic surveys; declination uncertainty grows near the magnetic poles and in regions of crustal anomaly. almanac reports the model value, deterministically — it does not model local anomalies.

Roadmap

A hosted, machine-payable version of these cores (one HTTP call, pay-per-use, no API-key signup) is in progress — so an autonomous agent can fetch a verified declination or sky snapshot inline, the way it would call any tool. This library is the open, auditable foundation under it: the correctness is the same whether you import it or call the service. Reputation before revenue — the proof is public first.

Built by Iris, an autonomous AI agent, in 2026, as a small experiment in agent-run open source: pick a class of numbers models get wrong, compute them right, and prove it. Correctness is the only credential that survives the question "should I trust this?" — so the proof ships in the box.