Metadata-Version: 2.4
Name: sherpa-agent
Version: 0.1.0
Summary: Hybrid vision web agent — planner + UI-TARS grounder + Playwright
Project-URL: Homepage, https://github.com/AnilPuram/Sherpa
Project-URL: Repository, https://github.com/AnilPuram/Sherpa
Project-URL: Documentation, https://github.com/AnilPuram/Sherpa#readme
Project-URL: Issues, https://github.com/AnilPuram/Sherpa/issues
Author: Anil Puram
Keywords: browser,llm,openrouter,playwright,web-agent
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
Requires-Python: >=3.12
Requires-Dist: httpx<1,>=0.28
Requires-Dist: playwright<2,>=1.54
Requires-Dist: pydantic<3,>=2.11
Description-Content-Type: text/markdown

# Sherpa

Sherpa is a hybrid web agent: a planner reads the page (screenshot + compact controls/content),
a screenshot-only grounder picks click coordinates, and Playwright acts. Default models are
Qwen3.5-35B-A3B (planner/verifier) and UI-TARS-1.5-7B (grounder) via OpenRouter.

## Install (Browser Use–style)

With [uv](https://docs.astral.sh/uv/) (recommended):

```bash
# From GitHub (until published on PyPI):
uv tool install git+https://github.com/AnilPuram/Sherpa.git

# Or from a local checkout:
uv tool install .

# After PyPI publish:
# uv tool install sherpa-agent
# uvx --from sherpa-agent sherpa --help

# One-shot without a permanent install:
uvx --from git+https://github.com/AnilPuram/Sherpa.git sherpa --help
```

Then:

```bash
sherpa install          # Playwright Chromium (+ Linux system deps)
sherpa init             # creates .env if missing
# edit .env → OPENROUTER_API_KEY=
sherpa "Confirm the page heading on https://example.com, then finish."
```

`sherpa install` runs the same pattern as Browser Use (`uvx playwright install chromium`,
with `--with-deps` on Linux). If Chromium is missing when you run a task, Sherpa installs it
automatically.

### Dev checkout

```bash
uv sync
uv run sherpa install
uv run sherpa init
uv run sherpa "Confirm the page heading on https://example.com"
```

## Usage

Config is one required key. Sherpa loads `.env` automatically (without overriding variables
already set in your shell). Optional model/budget overrides are commented in `.env.example`.

```bash
# Start URL can be in the task, or passed explicitly:
sherpa "Confirm the page heading" --url https://example.com

# Headless + machine-readable result:
sherpa "…" --url https://example.com --headless --json
```

By default the browser is headed, steps print as they run, and artifacts go to
`artifacts/runs/<timestamp>/`.

## Verify offline

```bash
uv run ruff check .
uv run pytest
uv run sherpa eval
```

Use `--real-model` only when you intend paid OpenRouter calls for grounding eval:

```bash
uv run sherpa eval --real-model --output artifacts/eval.json
```

## Benchmarks / research

WebVoyager subset tooling, judgment rubrics, run history, and the cross-agent bakeoff live under
`eval/` and the docs below. Live WebVoyager still requires `--real-model` so offline scoring stays
safe and free.

```bash
uv run sherpa webvoyager --output artifacts/webvoyager-offline.json
uv run sherpa webvoyager --real-model --max-cost-usd 1.00 \
  --artifacts artifacts/webvoyager --output artifacts/webvoyager-live.json
```

See `WEBVOYAGER_TESTS_AND_RESULTS.md`, `WEBVOYAGER_RUN_HISTORY.md`, and
`eval/bakeoff-round2-comparison.md`.

## How it works

The loop keeps a bounded progress ledger and memories, recovers from grounding/execution errors,
and requires a separate verifier to accept every `done` answer. Defaults: 20 planner steps, 5
consecutive corrections, high planner reasoning effort. Details: `ARCHITECTURE.md`.

## Files

- `src/sherpa/cli.py`: simple task CLI + research subcommands
- `src/sherpa/install_browser.py`: `sherpa install` / auto Chromium setup
- `src/sherpa/agent.py`: bounded progress, recovery, and hybrid-observation agent loop
- `src/sherpa/models.py`: planner, grounder, and verifier OpenRouter boundary
- `src/sherpa/eval.py`: point-in-box grounding evaluation
- `src/sherpa/webvoyager.py`: offline validation and bounded live WebVoyager subset runner
- `ARCHITECTURE.md`: agent flow and component diagrams
- `eval/bakeoff-round2-comparison.md`: Sherpa vs Browser Use vs Magnitude bakeoff
- `scripts/bakeoff/`: external-agent bakeoff runners
