hep-data-llm 1.1.0b1

No project description provided

hep-data-llm

---

Table of Contents

• Installation
• License

Introduction

This repo contains the code used to translate english queries for plots into the actual plots using LLM's and python packages and tools like ServiceX, Awkward, Vector, and hist.

Benchmark studies with the 8 adl-index as presented in conferences can be found in the results directory.

Use --help at the root level and on commands (e.g. hep-data-llm plot --help) to get a complete list of options.

Installation

To run out of the box you'll need to do the following once:

Prerequisites:

1. You'll need to have docker installed on your machine
2. Build the docker image that is used to run servicex, awkward, and friends: docker build -t atlasplotagent:latest Docker
3. If you are running a servicex workflow, get an access token. Make sure the servicex.yaml file is either in your home directory or your current working directory.
4. You'll need token(s) to access the LLM. Here is what the .env looks like. Please create this either in your local directory or your home directory. Make sure only you can read it: this is access to a paid service!

api_openai_com_API_KEY=<openai-key>
api_together_xyz_API_KEY=<together.ai key>
openrouter_ai_API_KEY=<openrouter-key>

Running in a local python environment

pip install hep-data-llm
hep-data-llm plot "Plot the ETmiss of all events in the rucio dataset mc23_13p6TeV:mc23_13p6TeV.801167.Py8EG_A14NNPDF23LO_jj_JZ2.deriv.DAOD_PHYSLITE.e8514_e8528_a911_s4114_r15224_r15225_p6697." output.md

The output will be in output.md - view in a markdown rendering problem (I use vscode). A img directory will be created and it will contain the plot (hopefully).

Use hep-data-llm plot --help to see all the options you can give it. It defaults to using gpt-5, the most successful model in tests.

Default questions

A questions.yaml file is bundled with the package containing a list of common plotting questions. To run one of these questions by number, pass the index (starting from 1) instead of the full text:

hep-data-llm plot 1 output.md

This will execute the first question from questions.yaml.

Running with uvx

This is great if you want to just run once or twice.

uvx hep-data-llm plot "Plot the ETmiss of all events in the rucio dataset mc23_13p6TeV:mc23_13p6TeV.801167.Py8EG_A14NNPDF23LO_jj_JZ2.deriv.DAOD_PHYSLITE.e8514_e8528_a911_s4114_r15224_r15225_p6697." output.md

This uses the uvx tool to install a temporary environment. If you want to keep this around to use, you can use uv tool install hep-data-llm. Do remember to update it every now and then!

Usage

new profile

Use the `new profile " to create a new profile. It copies the default profile, and you can then modify it and update it with new prompt or other items.

License

hep-data-llm is distributed under the terms of the MIT license.