xhelio-spice: Instructions file for Claude Code

CLAUDE.md — xhelio-spice

What This Is

xhelio-spice is a standalone Python package that wraps SpiceyPy with automatic SPICE kernel management. Users call get_position("PSP", ...) and xhelio-spice handles kernel download, caching, loading, and computation. It was extracted from helio-ai-agent's spice/ module in Feb 2026.

Repository Structure

src/xhelio_spice/
  __init__.py          # Public API re-exports, version
  missions.py          # NAIF IDs, kernel URLs, name resolution, SEGMENTED_MISSIONS
  kernel_manager.py    # Download, cache, load/unload kernels (singleton)
  ephemeris.py         # get_position, get_trajectory, get_state
  frames.py            # transform_vector, coordinate frame listings
  server.py            # MCP server (FastMCP, 6 tools)
  __main__.py          # python -m xhelio_spice entrypoint
  manifests/           # Bundled JSON manifests for segmented missions
    __init__.py
    cassini.json       # 505 SPK segments (2001–2017)
    mro.json           # 185 SPK segments (2006–2026)
    mars2020.json      # 52 SPK segments (2019–2036)
    lro.json           # LRO SPK segments
    lunar_prospector.json  # Lunar Prospector SPK segments
    mgs.json           # Mars Global Surveyor SPK segments
    mars_odyssey.json  # 98 SPK segments (2001–2026)
    stardust.json      # 14 SPK segments (1999–2011)
    akatsuki.json      # 10 SPK segments (2011–2021)
    grail.json         # 9 SPK segments (2011–2012)
    magellan.json      # 8 SPK segments (1990–1994)
    exomars_tgo.json   # 322 SPK segments (2018–2026)
    chandrayaan1.json  # 300 SPK segments (2008–2009)
scripts/
  build_manifest.py    # Developer script to regenerate manifests from NAIF
tests/                 # 220 tests, all mocked (no network/SPICE needed)
pyproject.toml         # hatchling build, xhelio-spice-mcp CLI entrypoint
server.json            # MCP registry manifest

Key Design Decisions

• Kernel cache: XHELIO_SPICE_KERNEL_DIR env var > ~/.xhelio_spice/kernels/ default. helio-ai-agent overrides to ~/.helio-agent/spice_kernels/ via agent/mcp_client.py.
• Two kernel strategies:
  • Single-file missions (PSP, SOLO, Juno, etc.): one SPK file per mission, downloaded in full via ensure_mission_kernels().
  • Segmented missions (Cassini, MRO, Mars 2020, LRO, Lunar Prospector, MGS, Mars Odyssey, Stardust, Akatsuki, GRAIL, Magellan, ExoMars TGO, Chandrayaan-1): many SPK files with time coverage recorded in bundled JSON manifests. Only segments overlapping the requested time window are downloaded, via ensure_segmented_kernels().
• ACE, Wind, DSCOVR are not supported — no public SPK kernels. Would need JPL Horizons API or CDF orbit files.
• Cache management: get_cache_info() groups cached files by mission. delete_mission_cache(), delete_cached_files(), and purge_cache() allow selective or full cleanup. Every MCP tool response includes cache_size_mb so the LLM can monitor disk usage.
• MCP server uses _create_server() factory pattern for lazy mcp import and testability.
• Thread safety: KernelManager is a singleton with RLock — SPICE has a global kernel pool.