HelioAI

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.

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

No API key required for data access. No manual parameter hunting.

Features

• Hybrid RAG — semantic (MiniLM) + lexical (BM25) search over 83k parameters, fused by Reciprocal Rank Fusion. Finds both vague descriptions and exact codes (BGSEc, FGM, igrf_8sec_gse).
• Event catalogs & timetables — access 217 curated AMDA catalogs (ICMEs, bow-shock crossings, reconnection events, substorms, …). Download a parameter across every event in one call — the foundation for superposed epoch analysis and statistical surveys.
• PlasmaPy tools — plasma β, gyrofrequency, Debye length, Alfvén speed, inertial length, power spectrum — ready-made for the agent.
• Sandboxed Python — the agent writes and runs analysis code under bubblewrap isolation on Linux (see SECURITY.md). All scripts are saved for reproducibility.
• 6 specialised skills — parameter_hunter, data_analyst, plasma_physicist, librarian, plotting, helioai_helper — loaded as markdown, zero coupling to the agent loop.
• Derived recipes — 10 reusable scientific scripts, each with a cited reference: θ_Bn, Walén test, MVAB, Rankine-Hugoniot jump conditions, two-spacecraft shock timing, pressure balance, pitch angle distribution, superposed epoch, SEP onset (Poisson-CUSUM), Parker spiral connectivity.
• Literature search — find_papers queries NASA ADS for papers relevant to an event or parameter; a dedicated librarian sub-agent handles multi-round literature searches without derailing the main analysis.
• Fill value masking — clean() helper in the sandbox automatically masks CDF fill values (|x| ≥ 1e30, ±inf) before any plot or analysis.
• Data quality checks — every get_timeseries download is scanned (deterministically, no LLM) for missing/fill values, data gaps, and 5σ outliers; the agent flags them only when they matter, so you know what you're working with before analysis.
• Plan preview — for a multi-step request the agent first lays out a short structured plan (the steps and the tool/method each will use), then executes — transparent, no black box.
• Standalone notebook export — any session exports as a self-contained .ipynb: load_data() calls are rewritten to direct spz.get_data(...), sandbox-only helpers are stripped, and a Methods & data acknowledgements cell lists the recipes and references used — every cell re-runs in a plain Jupyter kernel.
• Multiple interfaces — interactive CLI, Jupyter magic, Web UI (FastAPI + SSE + activity dock), MCP server (Claude Desktop / claude CLI).
• User profile — inject your preferred missions, domain, and plot style once; the agent adapts to you.
• Heliophysics scope guardrail — the agent stays on-topic; a dev token unlocks unrestricted mode for development.

Installation

pip install helioai-agent

Or from source with uv:

git clone https://github.com/erdoganfurkan/HelioAI.git
cd HelioAI
uv sync

First run — build the parameter index (one-time, ~10 min, 83k products):

helioai index

This downloads the speasy catalogue and indexes it into a local ChromaDB. It lands in <repo>/data/ when running from a clone, and in ~/.local/share/helioai/ when installed from PyPI — override either with HELIOAI_DATA_DIR.

Configuration

Copy .env.example to .env and set at least one LLM provider key:

# LLM provider (groq | gemini | azure | opencode | ollama)
HELIOAI_LLM_PROVIDER=groq

GROQ_API_KEY=your_key_here
GEMINI_API_KEY=your_key_here

# Azure OpenAI (if using azure)
AZURE_OPENAI_API_KEY=...
AZURE_OPENAI_ENDPOINT=...
AZURE_OPENAI_DEPLOYMENT=gpt-4o

# OpenCode Zen (if using opencode) — however you reach it (Go plan, BYOK), no default model
OPENCODE_API_KEY=...
HELIOAI_OPENCODE_MODEL=...

# Ollama (if using ollama — no API key needed)
HELIOAI_OLLAMA_URL=http://localhost:11434
HELIOAI_OLLAMA_MODEL=qwen2.5:14b-instruct

Any other OpenAI-compatible endpoint works too — providers are a base_url entry in helioai/core/llm/factory.py, not a class.

Usage

Interactive CLI

helioai

helioai> solar wind density from ACE in January 2005
helioai> compare MMS and Cluster magnetic field during 2017-07-11 reconnection event
helioai> compute plasma beta in the magnetosheath — B=20nT, n=20cm-3, T=200eV
helioai> show me the IMF Bz for all ICMEs in the Richardson & Cane catalog between 2003 and 2005
helioai> superposed epoch analysis of MMS bow-shock crossings — proton density, 2017

One-shot mode:

helioai "IP shock detection in WIND/MFI data, 2005-01-16 to 2005-01-17"

Jupyter

%load_ext helioai.interfaces.jupyter_magic

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

Figures render inline. Export the session as a notebook:

%helioai_export

Web UI

helioai serve --web
# → http://localhost:7890

Three-panel layout: conversation · artifact viewer (plots, parameter cards) · code panel (generated scripts).

Claude Desktop / MCP

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "helioai": {
      "command": "helioai-mcp"
    }
  }
}

Or run the HTTP MCP server:

helioai-mcp --http --port 8080

Docker

docker compose -f docker/docker-compose.yml up -d
# → http://localhost:7890

Mount ./data for persistent index and sessions. Set your LLM keys in .env.

Data coverage

In addition, 217 AMDA event catalogs and timetables are accessible as first-class tools: ICMEs (Richardson & Cane — 341 events, ICME multi-catalog — 2003 events), bow-shock crossings (MMS 2797, THEMIS ~60k), magnetic reconnection EDR events (72), substorm onsets (2437), flux transfer events, MAVEN shock crossings (3837), and monthly MMS burst-mode timetables (2015–present).

Full parameter catalogue via list_missions() or helioai "what missions are available". Full catalog catalogue via list_catalogs() or helioai "what event catalogs are available".

Agent tools

Data access

Event catalogs

Literature

Analysis

Sub-agents

Architecture

helioai/
├── config.py                   env vars, provider settings, RAG config
├── core/
│   ├── agent_loop.py           async streaming agent (stream_chat)
│   ├── sub_agents.py           specialised sub-agents (parameter_hunter, …)
│   ├── tool_exec.py            shared tool execution logic
│   ├── session.py              SQLite conversation history
│   ├── skills_loader.py        markdown skill loader
│   ├── skills/                 6 × SKILL.md
│   └── llm/                    groq · gemini · azure · ollama + factory
├── tools/
│   ├── rag.py                  hybrid BM25+dense RAG (RRF fusion)
│   ├── speasy_tools.py         search_parameters, get_timeseries, list_missions
│   ├── plasmapy_tools.py       6 plasma physics functions
│   ├── sandbox.py              sandboxed Python execution
│   └── recipes.py              scientific recipe loader
├── interfaces/
│   ├── cli.py                  readline CLI
│   ├── jupyter_magic.py        IPython magic
│   └── web/                    FastAPI + SSE + vanilla JS UI
├── mcp_server.py               MCP stdio + HTTP streamable
├── export.py                   session → reproducible .ipynb
├── indexer.py                  speasy catalogue → ChromaDB
└── docker/                     Dockerfile + docker-compose.yml

Development

uv sync --extra dev
.venv/bin/python -m pytest             # 797 tests, 80% coverage (no exclusions)
.venv/bin/python -m ruff check .       # lint
.venv/bin/python -m ruff format .      # format

Pre-commit hooks (ruff + trailing-whitespace):

pre-commit install

Roadmap

• CI/CD — GitHub Actions (lint + test matrix Python 3.12/3.13/3.14)
• Docker — helioai serve --web in a container (docker/)
• PyPI release — pip install helioai-agent
• JOSS paper

License

MIT — see LICENSE.

Related projects

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