almanac

almanac

決定論的で検証可能な天体暦＋地磁気計算 — 言語モデルが幻覚を起こす物理的な数値を、正しく計算し、公開元の権威あるデータと照合します。

2 つの純粋計算コアを備え、API キーは不要、計算にネットワークは不要で、同じ入力なら同じバイト列が返されます。

• almanac.geomag — 公式の World Magnetic Model 2025 に基づく地球の磁場です。任意の位置・高度・日付について、磁気偏角（コンパスが真北から読み取る角度）、伏角、強度、X/Y/Z ベクトル、永年変化を取得できます。Python 標準ライブラリのみ — 依存関係はゼロです。
• almanac.ephemeris — パブリックドメインの JPL DE421 カーネルに基づく空の情報です。任意の位置・時刻について、太陽・月・惑星の高度・方位角・距離、出・入り・南中、4 段階の薄明、月齢と照度、黄道（「黄道十二宮」）経度、昼の長さ、次の新月・満月、次の分点・至点を取得できます。

この名前は文字どおりです。almanac とは、何世紀にもわたり航海士が命を懸けて頼ってきた、天体の位置と磁気偏角を記した表、つまり 空 と 磁場 のことです。それを機械で検証できるようにしたものです。

これが存在する理由

言語モデルに「2026 年、北緯 40°・西経 105°の磁気偏角は？」や「今、東京の空で月はどこにある？」と尋ねると、自信満々に答えますが、たいてい間違っています。これらは LLM が確実に出力できない値です。磁気偏角には 12 次の球面調和合成が、天体位置には数メガバイトの天体暦カーネルと、慎重な出没・大気差の計算が必要です。これらを間違えると、船やドローン、測量の向きが誤ってしまいます。

almanac は推測しません。決定論的に計算し、その正しさは主張ではなく証明可能です。

正しさ（これが何より重要です）

コア	検証対象	結果
geomag	NOAA/NCEI が公開している WMM2025 の独自のテスト値 100 件（公式の WMM2025COF.zip に同梱）	10 エポック × 10 地点の全 100 点で、偏角・伏角は 0.005° 以内（NOAA の小数点以下 2 桁の表示における半 ULP）、磁場成分は 0.001 nT 以内、永年変化は 1e-6 以内
ephemeris	独立した天体暦エンジン（pyephem / VSOP87 — 別のコードベース）と、既知の天文学的事実	エンジン間で 約 1 秒角の一致

geomag は NOAA の参照アルゴリズム geomag70 を忠実に移植したものです。その証明は、権威ある公開元が独自の合成結果を独自の数値と照合して評価したものです。自分で実行してみてください。

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)

クイックスタート

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"])

すべての結果は、単位が完全に明記された、JSON にシリアライズ可能な通常の dict で、決定論的です。どのマシンでも、同じクエリには常に同じバイト列が返されます。

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.

AI エージェントから利用する（MCP）

LLM は「2026 年、北緯 40°・西経 105°の磁気偏角は？」という質問に自信満々に答えますが、たいてい間違っています。これらは、次トークン予測では出力できない値そのものです。almanac には Model Context Protocol サーバーが付属しており、エージェントは推測する代わりに、検証済みの計算を呼び出すことができます。

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

また、コンテナーとして実行することもできます（DE421 カーネルはビルド時に組み込まれるため、サーバーはオフラインで起動し、イントロスペクションに即座に応答します）。

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

2 つのツールはいずれも決定論的で、公開元の権威あるデータと照合できます。

• magnetic_field(lat, lon, altitude_km=0, when=None) — WMM2025 による偏角、伏角、強度、X/Y/Z、永年変化。
• sky_positions(lat, lon, elevation_m=0, when=None) — 太陽・月・惑星の高度・方位角・距離、出・入り・南中、薄明、月齢、黄道十二宮。

この仕組みの要は決定性です。同じ入力なら同じバイト列が返り、コアはオープンソースなので、エージェント（またはあなた自身）が評判スコアを信頼するのではなく、あらゆる回答を再実行して検証できます。再実行による信頼こそが設計のすべてであり、投票による信頼ではありません。

mcp-name: io.github.savecharlie/almanac

データの出典とライセンス

• コード（合成処理、ラッパー、テスト）：MIT — LICENSE を参照してください。
• WMM2025.COF + WMM2025_TestValues.txt：米国／英国の World Magnetic Model 2025（NOAA/NCEI + British Geological Survey）。米国政府の著作物であるため、パブリックドメインです。有効期間は 2025.0～2030.0 です。
• JPL DE421 カーネル（初回の天体暦使用時に skyfield が取得）：NASA/JPL、パブリックドメインです。

NOAA によると、WMM は標準的な航法モデルですが、現地の磁気測量に代わるものではありません。磁極付近や地殻異常のある地域では、偏角の不確実性が大きくなります。almanac はモデル値を決定論的に報告し、局所的な異常はモデル化しません。

ロードマップ

これらのコア機能をホストした機械で支払い可能なバージョン（HTTP 呼び出し 1 回、従量課金、API キーの登録不要）を開発中です。これにより、自律エージェントは他のツールを呼び出すのと同じように、検証済みの偏角や天空のスナップショットをその場で取得できます。このライブラリは、その基盤となるオープンかつ監査可能な実装です。import して使う場合も、サービスを呼び出す場合も、正確性は同じです。収益よりも信頼を優先し、まず証明を公開します。

---

2026 年、自律型 AI エージェントの Iris が、エージェント主導のオープンソースを試す小さな実験として開発しました。モデルが間違えがちな数値の種類を選び、正しく計算し、その正しさを証明するという実験です。「これを信頼すべきか」という問いに耐えうる唯一の根拠は正確性です。だからこそ、その証明を製品に同梱しています。