HEPTAPOD: Agentic HEP Automation Toolkit

• HEPTAPOD is an orchestration framework that automates high-energy physics simulation and analysis by leveraging LLM-driven agentic planning.
• It employs schema-validated tool registries, structured run-card management, and sandboxed execution to enhance reproducibility and transparency.
• The system integrates multi-step processes from symbolic model generation to jet clustering, ensuring auditable, human-in-the-loop workflow control.

The HEP Toolkit for Agentic Planning, Orchestration, and Deployment (HEPTAPOD) is an orchestration framework designed to enable agentic, reproducible, and auditable automation of high-energy physics (HEP) simulation and analysis workflows through LLM–driven planning and tool use. HEPTAPOD provides a structured interface for LLMs to coordinate complex, multi-step HEP pipelines—spanning symbolic model generation, Monte Carlo simulation, and downstream data analysis—by integrating schema-validated tool invocation, structured context management, and run-card–driven configuration. It establishes a transparent, human-in-the-loop foundation for modernizing HEP workflow execution and tracking (Menzo et al., 17 Dec 2025).

1. Design Motivation and Objectives

Contemporary HEP pipelines, despite relying on a mature suite of upstream scientific packages (FeynRules, MadGraph, Pythia, FastJet, etc.), require significant manual orchestration. Researchers typically write and maintain extensive scripts or shell pipelines to propagate model parameters, edit and manage run cards, interpret heterogeneous output, debug opaque failures, and synchronize multi-stage data flows. Traditional approaches suffer from fragile string manipulation and ad hoc bookkeeping, impeding reproducibility and scalability.

Recent advancements in transformer-based LLMs have produced models capable of “agentic” reasoning: planning multi-step tasks, calling tools via structured API protocols, maintaining dialogue and workflow state, and iteratively retrying on error. HEPTAPOD leverages these agentic capabilities to automate and coordinate HEP pipelines while enforcing:

• Reproducibility, via versioned run cards, machine-readable manifests, and conversational logs;
• Transparency, through schema-validated APIs and structured tool outputs;
• Human-in-the-loop control, with explicit checkpoints for researcher approval.

The principal objective is to allow an LLM to orchestrate a sequence of HEP simulation and analysis steps—from Lagrangian definition through event-level data analysis—while ensuring all workflow logic remains auditable and robust to upstream or downstream changes (Menzo et al., 17 Dec 2025).

2. System Architecture

HEPTAPOD’s architecture comprises three interconnected layers, all managed by the Orchestral AI orchestration engine:

1. Schema-Validated Tool Registry

A Python library wraps individual HEP codes (e.g., FeynRules, MG5_aMC@NLO, Pythia, FastJet) as “tools.” Each tool is defined by a Python class, with explicit type annotations that are automatically translated into JSON schemas for allowed inputs and outputs. Tool docstrings encode domain semantics. This registry ensures consistent, schema-constrained interaction between agent and computational resources without exposing internal scripts.

2. Agent-Orchestration Layer

The orchestration layer presents the LLM (e.g., GPT-OSS-120B) with: - A full conversational log, - The JSON schema plus docstring (“semantic prompt”) for each available tool, - A system prompt enforcing domain-specific constraints (e.g., “never fabricate physics,” “use run cards as canonical configuration”).

The LLM reasons over its current state, optionally emits a tool call (as structured JSON), which is then validated and dispatched by the orchestration engine. All returned outputs (filenames, cross sections, event metadata) are injected as structured JSON into the ongoing conversation, enabling memory-efficient iterative planning.

3. Sandboxed Execution Engine

All tool invocations occur in isolated workspaces (“sandboxes”). The engine handles runtime file management, placeholder resolution in run cards (e.g., [[LHEF_PATH]]), stdout/stderr capture, and conversion of exit outcomes to structured JSON success or error objects. Every event and output is appended to a persistent provenance log.

The closed-loop workflow operates as:

1. LLM reasons over context;
2. Emits tool call (validated);
3. Engine executes tool in sandbox;
4. Returns structured JSON output;
5. Appends output to session context;
6. LLM reasons again, repeating as needed.

3. LLM–Tool Integration

HEPTAPOD exposes tools to the LLM using an OpenAI-style function-calling API, where each tool is described by its JSON schema (auto-generated from type annotations) along with a semantic docstring. When an agent determines, for example, that a UFO model should be generated, it issues:

{ "name": "FeynRulesToUFOTool", "arguments": { "model_path": "feynrules/models/S1_LQ_RR.fr", "output_dir": "feynrules/models/S1_LQ_RR_UFO" } }

The orchestrator validates this JSON against the corresponding schema, executes the underlying tool, and returns results as structured objects:

{ "ok": true, "output_dir": "feynrules/models/S1_LQ_RR_UFO", "files_created": [ "...couplings.py", "...vertices.py" ] }

The agent iteratively builds context: after each tool call, new JSON fields (such as run IDs, cross sections, event counts) are injected into the session, allowing further planning (e.g., dispatching a Pythia job).

Run cards provide domain-tailored configuration templates, frequently containing placeholders (e.g., [[UFO_PATH]], [[NEVENTS]]). When the agent provides necessary runtime values, the relevant tool substitutes in the concrete paths/parameters prior to execution. This system eliminates reliance on brittle string mutation routines typical of legacy scripts (Menzo et al., 17 Dec 2025).

4. Schema-Validated Operations and Run-Card Management

All tool classes in HEPTAPOD inherit from a common BaseTool and distinguish between “RuntimeField” (agent-settable at call time) and “StateField” (injected by the orchestrator, not visible to the agent). For illustration:

class PythiaFromRunCardTool(BaseTool): command_card: str = RuntimeField(description="Path to Pythia8 .cmnd") nevents: int = RuntimeField(description="Number of events") seed: Optional[int] = RuntimeField(...) # State fields pythia_exe: str = StateField(...)

The orchestration engine auto-generates a corresponding JSON schema:

{ "name": "PythiaFromRunCardTool", "parameters": { "type": "object", "properties": { "command_card": { "type": "string" }, "nevents": { "type": "integer" }, "seed": { "type": ["integer", "null"] } }, "required": ["command_card", "nevents"] } }

Canonical configuration files (e.g., MadGraph’s “.mg5”, Pythia’s “.cmnd”) serve as templates. The agent need only specify physics-relevant fields (masses, couplings, seed values), and the orchestrator ensures correct substitution in the appropriate slots:

import model [[UFO_PATH]] generate p p > S1 S1~, (S1> e- u), (S1~> e+ u~) output S1_LQ_scan launch set nevents [[NEVENTS]] set seed [[SEED]]

Tool invocations are schema-validated before runtime via jsonschema.validate(agent_call, tool_schema), guaranteeing that only well-formed, properly-typed, and fully-specified configurations ever reach the corresponding executables.

5. Agentic BSM Monte Carlo Pipeline Example

A detailed benchmark is provided in the form of a BSM leptoquark production and analysis workflow. The process, as orchestrated by a HEPTAPOD agent, includes:

• Model Definition: The scalar leptoquark $S_1\sim(\overline{\mathbf{3}},1,1/3)$ is specified via its Lagrangian,

$$\mathcal{L}\supset (D_{\mu}S_1)^{\dagger}(D^{\mu}S_1) + y_{ij}\,\overline{u^c_{R\,i}\;e_{R\,j}\;} S_1 + \mathrm{h.c.}$$

with diagonal Yukawa couplings $y_{ij} = y\delta_{ij}$.

• End-to-End Workflow:

1. UFO model generation with FeynRules (FeynRulesToUFOTool).
2. Parameter scan over $m_{S_1}\in\{1.0, 1.5, 2.0\}$ TeV via MadGraph with tool return such as:

   { "scan_detected": true, "n_runs": 3, "runs": [ {"run_id": "run_01", "scan_params": {"mass#9000005": 1000.0}, "lhe_file": ".../run_01.lhe.gz", "cross_section": 0.1017 } // ... ] }

3. Hadronization with Pythia (PythiaFromRunCardTool) for each scan point.
4. LHE→JSONL event conversion (evtjsonl-1.0).
5. Jet clustering (Anti-$k_T$, $R=0.4$) via JetClusterSlowJetTool.
6. Selection of leading leptons/jets with FilterByPDGIDTool and GetHardestN[Jets]Tool.
7. Resonance reconstruction using leptons and jets:

   $$m_{\rm LQ}^{(i)} = \sqrt{(p_{\ell_i} + p_{j_i})^2}, \quad m^{\min}_{\rm LQ} = \min\{ m_{\rm LQ}^{(1)}, m_{\rm LQ}^{(2)} \}$$

   via ResonanceReconstructionTool, outputting $m_{\min}$, $m_{\max}$ arrays and histograms.

8. Plotting via a Python/Matplotlib tool.

The agent maintains and updates a structured “to-do” task list, marking items complete as tool invocations succeed:

## Monte Carlo Signal-Validation for S1 Leptoquark - [*] Generate UFO model from FeynRules - [ ] Generate parton-level events (MG5) with nevents=10000 - [ ] Shower & hadronize (Pythia) for each run - [ ] Cluster jets (R=0.4) - [ ] Select hardest 2 leptons (PDG±11,±13) & hardest 2 jets - [ ] Compute m^{min}_{LQ} and m^{max}_{LQ} - [ ] Plot histograms of m^{min}_{LQ} for all mass points - [ ] Summarize cross sections & event counts

6. Mechanisms for Reproducibility and Provenance

All tool calls and their outcomes are serialized into a persistent provenance log, typically as a JSONL session trace. This ensures every decision and outcome (including errors) can be reconstructed post hoc.

Explicit “human approval” breakpoints are supported: for example, after a new run card is generated, the agent pauses for researcher review. All error information is structured (never a raw stack trace):

{ "status": "error", "code": "FileNotFound", "message": "...", "tool": "JetClusterSlowJetTool", "missing_path": ".../jets.jsonl" }

This structure permits the agent to inspect, reason about, and repair failed steps rather than terminating. Final outputs, such as cross section tables, event counts, and data file paths, are consistently exported in machine-readable formats alongside visual products.

7. Performance and Scalability Considerations

HEPTAPOD’s event and object serialization in JSONL format supports streaming and memory-efficient processing of large Monte Carlo datasets (>10^6 events), allowing transparent pipelining and parallelization. Conversion tools produce fixed-shape NumPy arrays compatible with downstream vectorized ML models (JAX, PyTorch). The orchestration layer is stateless between tool calls, so batch or parallel execution across many parameter points is natively supported.

JSON schema validation introduces negligible computational overhead compared to external tool runtimes. Opportunities for future scaling include multi-agent parallelization (e.g., assigning one planning agent per parameter scan point) and retrieval-augmented prompt engineering for caching and reuse of frequent run-card templates.

---

HEPTAPOD refactors fragile, manually-scripted HEP workflows, replacing them with robust, agent-driven, schema-grounded, and fully auditable pipelines that tightly couple LLM planning with canonical HEP simulation and analysis software (Menzo et al., 17 Dec 2025).