Summary and Setup
In most analyses the bottleneck is not the physics but the software around it: finding data, decoding a data model, getting branch names and units right, iterating on fitting and plotting code. This lesson shows how to hand that overhead to an AI assistant without giving up rigor: every step produces a number you can check, and the whole procedure is reproducible.
The worked example is a real measurement from the ePIC experiment: reconstructing the weak decay Λ⁰ → p π⁻ and extracting its yield from the proton–pion invariant-mass spectrum.
The lesson develops three ideas and applies them end to end:
- an agentic assistant: a language model placed in a loop where it can read files, run code, and react to the results, rather than only returning text;
- the Model Context Protocol (MCP): an open standard for offering analysis tools to any assistant, so the workflow is portable; and
-
persistent instructions (
AGENTS.mdandSKILL.md): versioned context and procedures that make a run repeatable and auditable.
The lesson uses opencode, but the parts you build (MCP tool servers, a skill) work with any assistant.
What you will produce
A workflow in which an assistant opens a real ePIC reconstruction file, queries its schema through a verifiable tool interface, builds the Λ⁰ invariant-mass spectrum, and fits it, driven by natural-language requests, with results and provenance you can independently check.
Prerequisites
- Comfort at the command line (running commands, editing files).
- Working knowledge of Python or ROOT is useful; the assistant writes most of the code.
- Introductory particle-physics concepts (four-momentum, invariant mass, histograms, fitting).
- No prior experience with AI tooling is assumed, and the core episodes need no paid account or GPU.
See the Setup page for installation.
This lesson originated at an ePIC workshop on generative AI for physics. It complements the other EIC tutorials, which cover locating and reading the data.
eic-shell contains everything this lesson needs: the three MCP
servers (uproot, xrootd, rucio), the eic-mcp command that
starts them, and the opencode assistant. You need no grid
certificate and download no data: rucio is already signed
in to the shared read-only eicread account.
Quick checklist
1. eic-shell
See the environment
setup guide if you do not have eic-shell yet. Then, in the folder
with ./eic-shell:
2. Start the servers and the assistant
BASH
./eic-shell
mkdir -p lambda && cd lambda # a working directory for the analysis
eic-mcp up # uproot, xrootd, rucio on 127.0.0.1:9101-9103
eic-mcp config opencode # writes opencode.jsonc here
opencodeIn opencode, /mcp should list uproot,
xrootd, and rucio as connected. The free
hosted models need no login. If eic-mcp or
opencode is not found, exit eic-shell, return to the folder
containing the launcher, run ./eic-shell --upgrade, and
start eic-shell again.
On macOS, eic-shell is a Docker container: the servers stop when you
leave it, and its home (/root) is wiped, so opencode
forgets its settings. Keep your work in the eic-shell folder.
Check it works
In an empty directory, ask: “Create hello.py that prints the PDG
Λ⁰ baryon mass in GeV, then run it.” The assistant should write the
file and run it, printing 1.115683. If it only shows the
code, switch it to agent (build) mode.
Other assistants
One assistant to rule them all? Any agentic assistant — one that can read/write your files and run commands, not just emit text — works, and MCP works with any.
| Tool | Interface | Free access |
|---|---|---|
| opencode | terminal | open source (MIT); free hosted models (no key), bring your own key, or a local model |
| GitHub Copilot | VS Code, CLI | free tier; free Pro for verified students/educators/OSS maintainers |
| Gemini CLI | terminal | open source; free tier with a personal Google account |
| Codex | terminal, IDE | included with ChatGPT plans |
| Claude Code | terminal, IDE | included with Claude plans |
| Cursor | dedicated editor | free tier |
| Cline / Continue | VS Code extensions | open source; bring your own key |
eic-shell also has claude and copilot: run
eic-mcp config claude (or copilot), then start
it. The first login prints a code to paste in a browser, so it works
over SSH.
Assistant outside eic-shell
The servers must run in eic-shell, but the client can run on your
machine. Keep eic-mcp up running and put the client config
in the directory where you start the client.
Linux, WSL: apptainer shares the host network. Run
eic-mcp config <client>there.-
macOS: publish the ports once, restart
./eic-shell, and download the example config (eic-mcpdoes not run on the Mac itself):