helioai-agent 0.4.0

AI agent for heliophysics and space plasma data analysis.

Ask questions in natural language — HelioAI finds the right parameter across 70+ missions, downloads it, runs the analysis, and produces reproducible plots and notebooks.

📖 Documentation · listed in the PyHC Project List

What it does

You:      "IP shock in WIND data, January 2005 — compute θ_Bn"

HelioAI:  → resolves param IDs for B, Vp, Np across 83k speasy products
          → downloads the time series via speasy (AMDA / CDAWeb / CSA)
          → runs shock detection + coplanarity theorem in a sandboxed Python env
          → returns a plot, the θ_Bn value, and a reproducible .ipynb notebook

Data access needs no API key. Parameter hunting is the agent's job, not yours.

_{A real session, unedited — only the waiting between turns is compressed. The activity log lists every tool call and ends with a provenance verdict; the code panel holds the exact Python that produced the figure, which is also what the session exports as a runnable notebook.}

Why it's different

• It finds the parameter. Hybrid RAG — semantic (MiniLM) + lexical (BM25), fused by Reciprocal Rank Fusion — over 83 000 speasy products. Handles both vague descriptions and exact codes (BGSEc, FGM, igrf_8sec_gse).
• It works on events, not just intervals. 217 curated AMDA catalogs (ICMEs, bow-shock crossings, substorms, reconnection events) are first-class tools — download a parameter across every event in one call.
• The result is reproducible. Every session exports to a self-contained .ipynb that re-runs in a plain Jupyter kernel, with a Methods & data acknowledgements cell listing the recipes and references used.
• It shows its work. A provenance ledger checks the numbers in the answer against what was actually computed, and 11 vetted recipes (θ_Bn, Walén, MVAB, Rankine-Hugoniot, …) each carry a citation.
• It runs inside the agent you already use. HelioAI is also an MCP server, so Claude Code, Claude Desktop or Codex can call its tools with no LLM key of its own.

Full feature list in the documentation.

Install

pip install helioai-agent
helioai index          # one-time — fetches the prebuilt index (~125 MB), or builds it locally

Then set one LLM provider key (opencode, groq, gemini, azure or ollama — the OpenCode Zen gateway serves reasoning models behind a single key, and the model name is required since there is no sensible default):

export HELIOAI_LLM_PROVIDER=opencode
export OPENCODE_API_KEY=...
export HELIOAI_OPENCODE_MODEL=deepseek-v4-pro

→ Full installation and configuration guide

Use it

helioai                       # interactive CLI
helioai "θ_Bn for the 2005-01-16 WIND shock"      # one-shot
helioai serve --web           # web UI on http://localhost:7890
helioai mcp-install           # wire it into Claude Code, Claude Desktop or Codex
helioai doctor                # is the index built, the sandbox real, the key found?

In Jupyter:

%load_ext helioai.interfaces.jupyter_magic
%%helioai
Download Bz from ACE for the 2003 Halloween storm and plot the sudden commencement.

→ All four interfaces, in detail

Data coverage

Plus 217 AMDA event catalogs and timetables. Ask helioai "what missions are available" or helioai "what event catalogs are available" for the live list.

Documentation

Contributing

Issues and pull requests are welcome — see CONTRIBUTING.md and SECURITY.md (the sandbox model matters if you touch run_python).

uv sync --extra dev
.venv/bin/python -m pytest      # the whole suite, coverage floor 70%, no exclusions
.venv/bin/python -m ruff check . && .venv/bin/python -m ruff format --check .

How to cite

If HelioAI contributes to published work, please cite it:

@software{erdogan_helioai,
  author  = {Erdogan, Furkan},
  title   = {{HelioAI}: a natural-language agent for heliophysics data discovery and analysis},
  year    = {2026},
  version = {0.4.0},
  url     = {https://github.com/erdoganfurkan/HelioAI},
  license = {MIT}
}

GitHub's Cite this repository button gives the same from CITATION.cff. Please also cite the data providers you used (AMDA/CDPP, CDAWeb/NASA, CSA/ESA) and the method references each exported notebook lists in its Methods & data acknowledgements cell.

License

MIT — see LICENSE.

Related projects

• speasy — the data access layer powering HelioAI
• PlasmaPy — plasma physics calculations
• PyHC — Python in Heliophysics Community