# hep-data-llm

[![PyPI - Version](https://img.shields.io/pypi/v/hep-data-llm.svg)](https://pypi.org/project/hep-data-llm)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/hep-data-llm.svg)](https://pypi.org/project/hep-data-llm)

-----

## Table of Contents

- [Installation](#installation)
- [License](#license)

## 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
1. Build the `docker` image that is used to run `servicex`, `awkward`, and friends: `docker build -t atlasplotagent:latest Docker`
1. If you are running a `servicex` workflow, [get an access token](https://servicex-frontend.readthedocs.io/en/stable/connect_servicex.html). Make sure the `servicex.yaml` file is either in your home directory or your current working directory.
1. 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!

```text
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

```console
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.

### Running with `uvx`

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

```console
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!

## License

`hep-data-llm` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.
