AI Assistant

FDP ships a natural-language assistant for fusion data analysis. You describe a data task in plain language — "fetch ip for shot 200000 and report the peak in MA" — and the assistant writes and runs TokSearch pipeline code against the FDP data stack, iterating on errors until it has an answer. It is built into the toksearch package (toksearch.llm) and reaches your data through the same fdp environment as any other tool on this site.

The assistant comes in several forms, all installed by default with fdp-core:

Form	Command	Use it for
One-shot query	fdp query "..."	Quick questions from the shell
Terminal chat	fdp chat	Interactive analysis sessions
Chat GUI	fdp chat --gui	Browser chat with inline plots
Coding-assistant skills	fdp skills install	Teaching Claude Code / Cursor / Codex the TokSearch API
MCP server	python -m toksearch.llm.mcp	Serving FDP documentation to any MCP-capable agent
Python API	from toksearch.llm import Session	Embedding the agent in your own tools

For the full API reference see the TokSearch LLM documentation and the end-to-end LLM tutorial.

Quick start

Pick a backend credential (one of):

export ANTHROPIC_API_KEY=sk-...       # Anthropic API (the default backend)
export OPENAI_API_KEY=sk-...          # OpenAI      (--backend openai)
claude login                          # Claude Max  (--backend claude-max, no API key)
# or put a key in ~/amsc_api_key      # AmSC        (--backend amsc, DIII-D on-prem)

Then:

fdp query "Fetch ip for shot 200000 and report the peak current in MA."
fdp chat                # interactive terminal session
fdp chat --gui          # local Gradio GUI; --no-browser to skip opening a tab
fdp backends            # list every backend/preset available in your install

fdp chat/fdp query accept --backend, --model, and -n/--max-iterations. The backend default resolves in order: --backend flag → $FDP_LLM_BACKEND → ~/.fdp/config.toml [llm].backend → built-in anthropic. Persistent configuration lives in ~/.fdp/config.toml:

[llm]
backend = "claude-max"
model = "claude-sonnet-4-6"
anthropic_api_key = "sk-..."   # alternative to the env var; chmod 600

The assistant executes the code it writes on your machine. It shows each code block as it runs; review them as you would any generated code.

Skills for coding assistants

The same documentation the agent uses internally ships as skills — focused API guides (pipelines, signals, PTDATA, IMAS, MDSplus, datasets, per-device specifics) contributed by each installed package (toksearch, toksearch_d3d, toksearch_mast). If you work in Claude Code, Cursor, or Codex, install them so your assistant writes correct TokSearch code:

fdp skills list                    # what's available + install status
fdp skills install                 # → ~/.claude/skills (Claude Code, default)
fdp skills install --backend cursor   # → ~/.cursor/rules
fdp skills install --backend codex    # → ~/.codex/instructions.md

--force overwrites previously installed copies. The installer offers the same thing at install time via fdp-install --install-skills.

MCP server

Any MCP-capable agent can consume the skill library directly: toksearch (≥ 2.8.2) includes a standalone MCP server that serves every installed skill as a skill://<name> resource plus a read_skill tool, over stdio. For Claude Code:

claude mcp add toksearch-skills -- fdp run python -m toksearch.llm.mcp

Device portability

The assistant discovers signals, documentation, and Python namespaces from whatever device packages are installed — the same agent that answers DIII-D questions in a toksearch_d3d environment answers MAST questions (against the public FAIR MAST archive, no token needed) in a toksearch_mast environment, with no configuration changes.