Physics Assistant Demo

A fully reproducible end-to-end workflow that demonstrates NextStat as an AI oracle: ingest .root histograms, build a HistFactory workspace, run an anomaly scan, compute discovery p-values and upper limits, and export plot-ready artifacts.

What It Does

Ingests .root histograms via NextStat's native ROOT reader
Builds a HistFactory workspace from observed data + signal/background templates
Proposes an anomaly scan across mass windows
Computes discovery p-values (p₀, Z₀) and CLs upper limits
Exports JSON plot artifacts + optional PNG renders

Transport Modes

Mode	Description	Requirements
Local	All tools in-process via Python bindings	NextStat wheel installed
Server	Statistical tools over HTTP, ROOT ingest stays local	nextstat-server running
Docker	Agent container + nextstat-server via docker compose	Docker only

Running the Demo

Local Mode

# from repo root:
PYTHONPATH=bindings/ns-py/python python demos/physics_assistant/run_demo.py \
  --transport local \
  --out-dir demos/physics_assistant/out/local \
  --render

Server Mode

# Start the server first:
nextstat serve --port 3742

# Then run the demo:
export NEXTSTAT_SERVER_URL=http://127.0.0.1:3742
PYTHONPATH=bindings/ns-py/python python demos/physics_assistant/run_demo.py \
  --transport server \
  --out-dir demos/physics_assistant/out/server

Docker Mode

docker compose -f demos/physics_assistant/env/docker/docker-compose.yml up --build

Outputs written to demos/physics_assistant/env/docker/out/ on the host.

Output Artifacts

File	Description
`demo_result.json`	Main result bundle (validated by schema)
`tool_calls.json`	Ordered tool-call log (requests + tool_result.v1 envelopes)
`nominal_workspace.json`	Nominal model workspace
`best_anomaly_workspace.json`	Best window from anomaly scan
`anomaly_scan_plot_data.json`	Plot-ready arrays (JSON)
`plots/*.png`	Optional PNGs (when --render is enabled)

Design Note: Why Ingest Is Always Local

The inference server does not expose nextstat_read_root_histogram by design — file I/O is a security surface. The demo exercises server mode fully by shipping only workspace_json to the server for inference calls.