Metadata-Version: 2.4
Name: hepagent
Version: 0.3.1
Summary: Agent AI for HEP tasks
Project-URL: Homepage, https://github.com/xju2/hepagent
Author-email: "X. Ju" <xju@lbl.gov>
License: MIT License
        
        Copyright (c) 2025 Xiangyang Ju
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: agents,cosmology,hep
Requires-Python: >=3.12
Requires-Dist: camb>=1.6.5
Requires-Dist: matplotlib>=3.10.8
Requires-Dist: numpy>=2.3.5
Requires-Dist: openai-agents[litellm]>=0.6.3
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: textual>=6.11.0
Requires-Dist: typer>=0.24.1
Provides-Extra: iri
Requires-Dist: globus-sdk>=4.4.1; extra == 'iri'
Requires-Dist: iri-client>=0.1.4; extra == 'iri'
Provides-Extra: tracing
Requires-Dist: mlflow>=3.10.0; extra == 'tracing'
Description-Content-Type: text/markdown

# Project
![coverage](https://img.shields.io/badge/coverage-70%25-green)

## Introduction

`hepagent` is an AI agent framework tailored for High Energy Physics (HEP) and cosmology workflows. Key features include:

- **Multi-provider LLM support**: seamlessly switch between providers such as `cborg`, `openai`, `amsc`, and `gemini` via a unified CLI (`hepagent run`) or programmatic API, with per-provider configuration managed in `providers.toml`.
- **Skill-based domain knowledge**: a modular skill registry (`.agents/skills/`) packages domain-specific instructions (e.g. running Nyx cosmology simulations) that agents load on demand, keeping prompts concise and context-relevant.
- **Bash and REPL agents**: interactive shell agents with configurable YOLO (auto-approve), CONFIRM, and HUMAN execution modes, output character limits, and turn budgets—safe for running on HPC clusters.
- **Textual TUI agent**: a rich Terminal User Interface (`TextualAgent`) with real-time display of agent thinking, step navigation, and live cost tracking.
- **HPC / Slurm integration**: built-in tooling for submitting and monitoring Slurm jobs, Globus data transfers, and IRI compute resources.
- **Extensible tool system**: common and domain-specific tools are registered under `src/hepagent/tools/`, making it straightforward to add new capabilities without touching agent logic.

## Installation

### Quick start (no code checkout required)

With [uv](https://docs.astral.sh/uv/) installed, you can run `hepagent` directly from PyPI without cloning the repository:

```bash
# Run once without installing permanently
uvx hepagent -h

# Or install as a persistent tool
uv tool install hepagent
hepagent -h
```

### Developer setup (from source)

```bash
git clone https://github.com/xju2/hepagent.git
cd hepagent
uv python install 3.12
make sync
uv run hepagent list-platforms
uv run hepagent list-models --platform cborg
```

### Configurations
After the installation, you can find default configurations at `$HOME/.hepagent`.
The environment variables are stored in `$HOME/.hepagent/config/env_vars.toml`.

To use a LLM provider, set the corresponding API keys as environment variables.
You may also want to set `OPENAI_AGENTS_DISABLE_TRACING=1` to disable the tracing logs,
especially if you do not have an OPENAI_API_KEY.

If you don't want to store API keys in the TOML file,
you can set them to environment variables directly.
```bash
export CBORG_API_KEY="your-api-key"
export OPENAI_API_KEY="your-api-key"
export AMSC_API_KEY="your-api-key"
export GEMINI_API_KEY="your-api-key"
```


## Instructions

### Choose a platform and model
You can run the agent as in the following examples.
The default model is `cborg:gemini-flash` if not specified.

List available models for a platform:
```bash
uv run hepagent list-models --platform cborg
uv run hepagent list-models --platform amsc
uv run hepagent list-models --platform openai
uv run hepagent list-models --platform gemini
```


### Run an agent with a specific model and task:

```bash
uv run hepagent run --agent "shell" --model "gemini:models/gemini-flash-lite-latest" "how many python files in this code repository"
uv run hepagent run --agent "scientist" --model "cborg:gemini-flash" "I would like to simulate a cosmology sky with Nyx code." --max-turn 30
uv run hepagent run --agent "coder" --model "openai:gpt-5-mini" "Create a worktree for adding a new feature: chunkle."
uv run hepagent run --agent "scientist" --model "gemini:models/gemini-2.0-flash" "..."  # uses Gemini provider
```

YOLO mode (auto-approve all bash commands):
```bash
uv run hepagent run --agent "scientist" --yolo "your task here"
```

### Interactive Bash Agent with REPL
```
python src/hepagent/scripts/bash_repl.py
```
With custom turn budget:
```
HEPAGENT_MAX_TURNS=80 python src/hepagent/scripts/bash_repl.py
```
