Metadata-Version: 2.4
Name: hpcpilot
Version: 0.1.0
Summary: Agnostic HPC AI Agent framework — multi-backend LLM, SLURM tools, terminal UI
Author-email: Youzhi Yu <yuyouzhi666@icloud.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/PursuitOfDataScience/hpcpilot
Project-URL: Repository, https://github.com/PursuitOfDataScience/hpcpilot.git
Project-URL: Issues, https://github.com/PursuitOfDataScience/hpcpilot/issues
Keywords: hpc,slurm,sbatch,llm,agent,cli
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: English
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Distributed Computing
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: prompt_toolkit<4,>=3.0
Requires-Dist: requests>=2.31
Provides-Extra: full
Requires-Dist: ddgs>=0.7; extra == "full"
Requires-Dist: trafilatura>=1.6; extra == "full"
Provides-Extra: web
Requires-Dist: ddgs>=0.7; extra == "web"
Requires-Dist: trafilatura>=1.6; extra == "web"
Provides-Extra: ui
Requires-Dist: prompt_toolkit<4,>=3.0; extra == "ui"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-mock>=3.10; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.3.0; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

<div align="center">

```
██╗  ██╗██████╗  ██████╗     █████╗  ██████╗ ███████╗███╗   ██╗████████╗
██║  ██║██╔══██╗██╔════╝    ██╔══██╗██╔════╝ ██╔════╝████╗  ██║╚══██╔══╝
███████║██████╔╝██║         ███████║██║  ███╗█████╗  ██╔██╗ ██║   ██║   
██╔══██║██╔═══╝ ██║         ██╔══██║██║   ██║██╔══╝  ██║╚██╗██║   ██║   
██║  ██║██║     ╚██████╗    ██║  ██║╚██████╔╝███████╗██║ ╚████║   ██║   
╚═╝  ╚═╝╚═╝      ╚═════╝    ╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚═╝  ╚═══╝   ╚═╝   
```

**Talk to your SLURM cluster in plain English.**

A colorful terminal agent that checks nodes, diagnoses jobs, predicts wait times,
fixes permissions, and reads your cluster's own docs — no bash incantations required.

[![CI](https://github.com/PursuitOfDataScience/hpcpilot/actions/workflows/ci.yml/badge.svg)](https://github.com/PursuitOfDataScience/hpcpilot/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/hpcpilot.svg)](https://pypi.org/project/hpcpilot/)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](#license)
[![Status: beta](https://img.shields.io/badge/status-beta-orange.svg)](#status)

</div>

---

## See it

<p align="center">
  <img src="assets/demo.gif" width="840" alt="hpcpilot: diagnose a pending job, mirror the cluster's docs by URL, then answer from them">
</p>

> Diagnose a pending job, mirror the cluster's docs straight from their URL, then
> get an answer cited from them. The agent streams markdown, shows each tool as it
> runs, and asks before anything that changes state. Type `/` any time for commands.

## Why hpcpilot

- 🗣️ **Plain-English ops** — "show my pending jobs", "who's hogging node midway3-0042", "extend job 1837465 by 2 hours".
- 📚 **Knows *your* cluster** — point it at your docs folder **or a docs-site URL** and it mirrors the whole user guide locally, then cites the right page.
- 🛟 **Safe by default** — mutating actions (chmod, chgrp, `scontrol update`) show a preview and need confirmation; secrets are stored `0600`, session-only unless you opt in.
- 🔌 **Bring any model** — it auto-detects an installed `claude`/`codex`, or use any API provider; switch and search models live with `/model`.
- 🎨 **A real TUI** — gradient banner, streaming answers, live tool status, searchable menus, persistent history.

## Quickstart

```bash
pip install "hpcpilot[full]"

hpcpilot          # first run walks you through setup
```

That's it. On first launch a short wizard helps you pick a model, point at your
docs, and start asking questions. If you already have the `claude` or `codex` CLI
installed, hpcpilot uses it automatically — **zero config, no API key needed.**

## Living in the TUI

Type `/` to open the command menu (arrow keys to choose, Enter to run):

| Command | What it does |
|---------|--------------|
| `/model` | Browse, **search**, and switch models (type to filter a long list) |
| `/effort` | Set reasoning effort (low / medium / high) |
| `/docs` | Show, add, or `/docs sync` your cluster documentation |
| `/tools` | List the HPC tools the agent can call |
| `/config` | Re-run the setup wizard |
| `/keys` | See where your API key comes from (or clear it) |
| `/copy` · `/save` | Copy the last answer · save the transcript |
| `/clear` · `/retry` · `/help` · `/exit` | …and the usual essentials |

Don't know a model's exact name? Just open `/model` and type `fast`, `reasoning`,
`gemini`, or part of a name — the picker filters as you type.

## Teach it your cluster's docs

Point hpcpilot at a **local folder** of markdown, or at a **docs-site URL** — a whole
user guide with many pages. A URL is crawled once (sitemap, then the site's own nav
links) into a local cache, so the agent reads it instantly and offline:

```bash
# A local folder…
hpcpilot --docs-base-path /path/to/cluster-docs

# …or mirror an online user guide (the whole site, not one page)
hpcpilot --docs-url https://docs.rcc.uchicago.edu/
```

You can also paste a path or URL in the wizard's **Docs** step. Inside the TUI,
`/docs` shows what's loaded, `/docs add` adds a source, and `/docs sync` re-crawls
when the docs change. Then ask *"how do I request a GPU node?"* and the agent reads
the relevant page and answers with specifics. *(URL mirroring uses the `full` extra.)*

## 🎬 Regenerate the demo

The GIF above is built with [vhs](https://github.com/charmbracelet/vhs) from
[`assets/demo.tape`](assets/demo.tape), which runs
[`scripts/demo.py`](scripts/demo.py) — a self-animating session that uses
hpcpilot's *real* banner, streaming renderer, and tool-status output, so it looks
exactly like the app while staying fully reproducible (no live LLM or cluster).

```bash
conda install -c conda-forge vhs ttyd ffmpeg   # one-time
vhs assets/demo.tape                            # re-renders assets/demo.gif
```

Edit the questions or timing in `scripts/demo.py` and re-run to taste.

<details>
<summary><strong>Models & providers</strong> (click to expand)</summary>

hpcpilot talks to any OpenAI-compatible API, plus the Claude and Codex CLIs. It does
**not** hard-code model names — use `/model` (or `--list-models <provider>`) to see
what each provider currently offers and pick the latest.

| Provider | `--backend` | Auth |
|----------|-------------|------|
| OpenAI | `openai` | `OPENAI_API_KEY` |
| Google Gemini | `gemini` | `GEMINI_API_KEY` |
| Groq | `groq` | `GROQ_API_KEY` |
| OpenRouter | `openrouter` | `OPENROUTER_API_KEY` |
| DeepSeek | `deepseek` | `DEEPSEEK_API_KEY` |
| Mistral | `mistral` | `MISTRAL_API_KEY` |
| xAI | `xai` | `XAI_API_KEY` |
| Together | `together` | `TOGETHER_API_KEY` |
| OpenCode | `opencode` | `OPENCODE_API_KEY` |
| Any OpenAI-compatible API | `custom` | `--api-base-url` |
| Claude CLI | `claude` | uses the `claude` binary |
| Codex CLI | `codex` | uses the `codex` binary |

**API vs. CLI backends:** API backends use hpcpilot's curated HPC tools (job wait
prediction, permission checks, quota lookups, doc reading). CLI backends drive the
external agent binary directly with its own toolset.

Useful flags: `--model`, `--effort {low,medium,high}`, `--docs-url`, `--docs-base-path`,
`--list-models`, `--list-tools`, `--dangerous-bypass`, `--config-path`.

</details>

## Install from source

```bash
git clone https://github.com/PursuitOfDataScience/hpcpilot.git
cd hpcpilot
pip install -e ".[full]"
hpcpilot
```

## Status

Beta. The portable SLURM tools (`squeue`/`sinfo`/`scontrol`) work on any SLURM
cluster; site-specific account/quota commands are configurable. Issues and PRs welcome.

## License

MIT — see [LICENSE](LICENSE).
