Summary and Schedule

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.md and SKILL.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.

Callout

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.

Prerequisite

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.

The actual schedule may vary slightly depending on the topics and exercises chosen by the instructor.

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.

Checklist

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:

BASH 

cd ~/eic                  # yours may differ
./eic-shell --upgrade

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
opencode

In 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.

Callout

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

gold ring engraved with the words EIC

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.

Callout

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-mcp does not run on the Mac itself):

    BASH 

    cd ~/eic
grep -q 9101 eic-shell || sed -i '' 's|^docker run |docker run -p 127.0.0.1:9101-9103:9101-9103 |' eic-shell
cd lambda                   # or the directory where you will launch opencode
curl -fsSLO https://raw.githubusercontent.com/eic/tutorial-mcp/main/files/mcp-config/opencode.jsonc