AgentRivet 0.1.0

Multi-agent framework for generating Rivet analysis routines using large language models

AgentRivet is an agentic workflow for turning a HEP arXiv paper into a Rivet analysis routine. It combines deterministic paper and metadata lookup with a small set of focused LLM agents:

• an Analyst agent that converts the paper into a structured analysis summary
• a Coder agent that writes or revises the Rivet routine
• a CodeReviewer agent that checks Rivet and C++ correctness
• a PhysicsReviewer agent that checks physics fidelity against the analysis summary

What the package does

Given an arXiv identifier, AgentRivet:

1. checks whether a Rivet routine already exists for the analysis
2. downloads and extracts the paper text
3. builds a structured analysis summary from the paper
4. generates a Rivet C++ draft
5. reviews that draft with two separate reviewers (Coder then Physicist)
6. iterates up to a fixed number of review rounds
7. writes the final .cc file and a review report

The important design choice is that the full paper text is used only by the Analyst agent. The iterative code-generation loop runs on the structured analysis summary plus the most recent review outputs, not on the full paper text every time.

Installation Notes

The package metadata is defined in [pyproject.toml].

Base dependencies listed there:

• arxiv
• pydantic
• pypdf

Optional extras:

• openai
• google-genai
• anthropic
• pytest for development

The runtime code also imports requests, so your environment must provide that package as well.

How to install from source

Set up in a Python virtual environment

python -m venv myPyEnv
source myPyEnv/bin/activate

then install the package using

pip install -e .

How to run

From inside the top level directory:

./agent-rivet

You will be prompted for an arXiv ID.

You can also pass the arXiv ID directly:

./agent-rivet -a 2511.15569

You can choose a provider explicitly:

./agent-rivet -a 2511.15569 --provider google
./agent-rivet -a 2511.15569 --provider openai
./agent-rivet -a 2511.15569 --provider anthropic

You can also override the model:

./agent-rivet -a 2511.15569 --provider google --model gemini-3.1-pro-preview

Environment variables

agent-rivet detects the provider and model from either CLI flags or environment variables.

Supported environment variables:

• LLM_PROVIDER
• LLM_MODEL
• GOOGLE_API_KEY
• OPENAI_API_KEY
• ANTHROPIC_API_KEY

Examples:

export LLM_PROVIDER=google
export GOOGLE_API_KEY=...
./agent-rivet -a 2511.15569

export LLM_PROVIDER=openai
export LLM_MODEL=gpt-5
export OPENAI_API_KEY=...
./agent-rivet -a 2511.15569

If --model and LLM_MODEL are not supplied, utils.detect_provider() chooses a default model for the selected provider.

A more detailed discussion of the code structure can be found here