Metadata-Version: 2.4
Name: AgentRivet
Version: 0.1.0
Summary: Multi-agent framework for generating Rivet analysis routines using large language models
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://gitlab.com/hepcedar/AgentRivet
Project-URL: Repository, https://gitlab.com/hepcedar/AgentRivet
Project-URL: Documentation, https://gitlab.com/hepcedar/AgentRivet
Project-URL: Issues, https://gitlab.com/hepcedar/AgentRivet/-/issues
Project-URL: Archived release (Zenodo), https://doi.org/10.5281/zenodo.20646340
Keywords: particle physics,HEP,Rivet,LLM,AI,Agentic AI,analysis preservation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: COPYING
Requires-Dist: arxiv
Requires-Dist: pydantic
Requires-Dist: pypdf
Requires-Dist: requests
Provides-Extra: anthropic
Requires-Dist: anthropic; extra == "anthropic"
Provides-Extra: google
Requires-Dist: google-genai; extra == "google"
Provides-Extra: openai
Requires-Dist: openai; extra == "openai"
Provides-Extra: dev
Requires-Dist: openai; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file


![AgentRivet](docs/brand/agent-rivet-banner.png)

`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
4. builds a structured analysis summary from the paper
5. generates a Rivet C++ draft
6. reviews that draft with two separate reviewers (Coder then Physicist)
7. iterates up to a fixed number of review rounds
8. 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
```bash
python -m venv myPyEnv
source myPyEnv/bin/activate
```
then install the package using

```bash
pip install -e .
```

## How to run

From inside the top level directory:

```bash
./agent-rivet
```

You will be prompted for an arXiv ID.

You can also pass the arXiv ID directly:

```bash
./agent-rivet -a 2511.15569
```

You can choose a provider explicitly:

```bash
./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:

```bash
./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:

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

```bash
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](docs/code-structure.md)

