Open source · Apache-2.0 · v0.1.0

An agentic harness for high-energy physics

Built on the Claude Agent SDK · works with any MCP client

Abstract. fisicai gives an AI agent the tools a particle physicist actually uses: the INSPIRE-HEP literature database, arXiv, HEPData, the Scikit-HEP analysis stack, and — most importantly — published statistical likelihoods from real LHC searches. The agent reads a paper, fetches its likelihood, patches in a new signal, and runs pyhf.infer — doing in minutes what today takes a phenomenologist weeks. It doesn't just talk about papers. It reinterprets them.

View on GitHub

Figure 1: a real session (full walkthrough). The agent chains inspire_search → hepdata_download_likelihood → pyhf_cls and reproduces the published CLs of the ATLAS SUSY-2018-31 search to all published digits — from the analysis's own statistical model, not a digitized curve.

1Reinterpretation is the bottleneck

A single LHC analysis takes a team of physicists years: skims, background estimates, systematics, multivariate discriminants, statistical interpretation. Reinterpreting that analysis for a new theory model — the thing that makes a search scientifically durable — usually never happens, because nobody has the time.

But the field quietly built the infrastructure to change that. ATLAS, and increasingly CMS, now publish their full statistical models as pyhf JSON workspaces on HEPData. An agent that can read a paper, fetch its likelihood, patch in a new signal, and run the fit closes the loop. fisicai is the harness that makes that loop routine.

2The tools a physicist actually uses

Literature

Search INSPIRE-HEP, fetch arXiv abstracts and full text, and pull citation-ready BibTeX straight from INSPIRE. inspire_search arxiv_fetch

Data

Locate HEPData records and their resources — including the published pyhf workspaces of real searches. hepdata_get hepdata_download_likelihood

Statistics

Apply signal patches to published likelihoods and compute observed and expected CLs limits. pyhf_list_patches pyhf_cls

Analysis

A sandbox with the Scikit-HEP stack — uproot, awkward, hist, pyhf, matplotlib — for cutflows, histograms, and plots.

Domain knowledge lives in versioned markdown skills — how to reinterpret a search, how to run a cutflow. Teach the agent your workflow by writing a skill, not by patching code.

3Analysis bundles: the code and the paper

Research output isn't a chat answer — it's an analysis. fisicai analyze makes the agent deliver a complete, reproducible bundle: the analysis code, every result as data, and a compiled LaTeX note in experiment-publication style.

$ fisicai analyze "measure the Z boson mass
   in the Open Data dimuon skim"

analyses/zmumu_z_mass/
├── analysis.py        # runs end-to-end
├── results/
│   ├── results.json   # every quoted number
│   └── results.tex    # generated \newcommand’s
├── figures/*.pdf      # mplhep-styled
└── note/
    ├── note.tex       # quotes macros only
    ├── references.bib # fetched from INSPIRE
    └── note.pdf       # compiled with tectonic

The invariant: the note cannot drift from the code. Prose numbers come from generated macros, citations come from INSPIRE's own BibTeX, and rerunning analysis.py regenerates the whole artifact.

This is not a mock-up. Below is the actual note the agent produced for that command — selection cutflow, muon kinematics with the Jacobian peak, the Voigtian fit with per-bin pulls, a fit-range systematic scan, and INSPIRE-fetched references, over six pages.

Note page 1: title, abstract, introduction — **Figure 2:** the generated note.pdf, compiled from the committed bundle. Every quoted number is a generated macro; every figure is `mplhep`-styled and produced by `analysis.py`; every reference is INSPIRE's own BibTeX. Click any page to read the PDF.

Note page 2: event selection, cutflow table, muon kinematics figure — **Figure 2:** the generated note.pdf, compiled from the committed bundle. Every quoted number is a generated macro; every figure is `mplhep`-styled and produced by `analysis.py`; every reference is INSPIRE's own BibTeX. Click any page to read the PDF.

4HEPAbench: trust is a number

How do you trust an AI with physics? You score it against results that are already known. HEPAbench is a benchmark of analysis tasks with published reference answers. Every check carries a continuous score in [0, 1], so harnesses, models, and prompts can be optimized against it — improvements show up as score, not anecdotes. The scorer is harness-agnostic: any agent that writes an answer.json can be benchmarked.

Table 1: HEPAbench v0 — the fisicai agent scores 4/4. The recorded answers are committed to the repo and re-scored on every push in CI: these claims are continuously verified, not prose.

Task	Reference	Agent
`toy_cls` — CLs fit, toy workspace	0.0525 (pyhf docs)	0.05251
`literature_stop_4body` — INSPIRE retrieval	arXiv:2301.08096	exact
`atlas_multib_cls` — published ATLAS likelihood	0.24444	0.24444
`opendata_zmumu` — Z mass, CMS 2012 data	91.1876 GeV (PDG)	90.95 GeV

Figure 3: the atlas_multib_cls task. Observed CLs against the expected ±1σ and ±2σ bands, every value computed by the agent from the search's published pyhf workspace.

hepabench validate goes further for full bundles: it turns "the agent wrote a paper" into "the agent wrote a reproducible paper". It reruns analysis.py in a clean copy and requires an identical results.json, checks that no result is hand-typed in the note, that every citation resolves, and that the note compiles from scratch. The note shown in Figure 2 passes all six checks:

$ hepabench validate analyses/zmumu_z_mass
  [PASS] files: ok
  [PASS] reproducible: identical
  [PASS] macros_in_sync: in sync
  [PASS] no_raw_numbers: clean
  [PASS] citations: ok
  [PASS] compiles: ok
  bundle score: 1.000

Contributing a task is one YAML file: a prompt and a published reference value. Tasks that agents fail are the most valuable ones.

5Use it from the agent you already have

Every tool is also exposed as a standard MCP server — vendor-neutral, works with Claude Code, Cursor, opencode, or any other MCP client. Your agent gains the literature, HEPData, and pyhf tools plus the write-up machinery for producing validated analysis bundles.

# Claude Code
$ claude mcp add fisicai -- fisicai-mcp

# any MCP client config
{ "mcpServers": { "fisicai": { "command": "fisicai-mcp" } } }

6Roadmap

✓ M1Literature agent — end-to-end INSPIRE and arXiv research tasks.
✓ M2Reinterpretation — reproduce a published ATLAS exclusion point from its HEPData likelihood: an objective, physics-grade correctness check.
M3Community — grow HEPAbench, recast scans over patchsets, simplified likelihoods, and whatever the reinterpretation community asks for first.
→Beyond — the simulation chain for reinterpreting new models: MadGraph → fast sim → efficiency maps → patched likelihoods. And new results on new data.