Metadata-Version: 2.5
Name: browserrig
Version: 0.1.0
Summary: Event-driven Chrome automation for Harnessed.
Project-URL: Homepage, https://github.com/mathisarends/browserrig
Project-URL: Documentation, https://github.com/mathisarends/browserrig/blob/main/README.md#documentation
Project-URL: Repository, https://github.com/mathisarends/browserrig
Project-URL: Issues, https://github.com/mathisarends/browserrig/issues
Project-URL: Changelog, https://github.com/mathisarends/browserrig/blob/main/CHANGELOG.md
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: beautifulsoup4<5,>=4.14
Requires-Dist: cdpify[websocket]<0.5,>=0.4.0
Requires-Dist: charset-normalizer<4,>=3.4
Requires-Dist: defusedxml<0.8,>=0.7.1
Requires-Dist: harnessed==0.11.0
Requires-Dist: httpx2<3,>=2.16
Requires-Dist: markdownify<2,>=1.2
Requires-Dist: mutagen<2,>=1.47
Requires-Dist: odfpy<2,>=1.4.1
Requires-Dist: onnxruntime==1.30.0
Requires-Dist: opencv-python<5,>=4.13
Requires-Dist: openpyxl<4,>=3.1.5
Requires-Dist: pillow<14,>=13
Requires-Dist: pydantic<3,>=2.12
Requires-Dist: pypdf<7,>=6.21.4
Requires-Dist: pypdfium2<6,>=5.14
Requires-Dist: python-docx<2,>=1.2
Requires-Dist: python-pptx<2,>=1.0.2
Requires-Dist: pyyaml<7,>=6
Requires-Dist: rapidocr==3.9.2
Requires-Dist: striprtf<0.1,>=0.0.29
Requires-Dist: xlrd<3,>=2.0.2
Provides-Extra: anthropic
Requires-Dist: harnessed[anthropic]==0.11.0; extra == 'anthropic'
Provides-Extra: mcp
Requires-Dist: harnessed[mcp]==0.11.0; extra == 'mcp'
Provides-Extra: openai
Requires-Dist: harnessed[openai]==0.11.0; extra == 'openai'
Provides-Extra: otel
Requires-Dist: harnessed[otel]==0.11.0; extra == 'otel'
Description-Content-Type: text/markdown

# Browserrig

Browserrig is an event-driven Chrome automation library for AI agents and Python applications. It combines direct browser access with a composable [Harnessed](https://github.com/mathisarends/harnessed/releases/tag/v0.11.0) agent, structured page observations, browser actions, and typed events.

Agents can navigate tabs, interact with DOM elements or screenshot coordinates, download and read files, and be paused or steered during a session. Chrome can be launched locally or connected through CDP.

```mermaid
flowchart LR
    App[Python application] --> Agent[browserrig.Agent]
    Agent --> Chrome
    Chrome --> State[Page observations and screenshots]
    State --> Agent
    Chrome --> Events[Typed events]
    Agent --> Files[Workspace and downloads]
```

## Quick start

Python 3.12+ and Chrome or Chromium are required. Install the package with the
provider extra you need:

```sh
python -m pip install "browserrig[openai]"
```

Set `OPENAI_API_KEY` in your environment, save the Python example below as
`agent.py`, and run `python agent.py`. The `anthropic`, `mcp`, and `otel` extras
enable the corresponding Harnessed integrations. For direct browser access
without a model provider, install `browserrig` without an extra.

The base installation includes document readers and local CPU OCR, including
ONNX Runtime and OpenCV. These native dependencies make the installation larger
than the wheel for Browserrig itself.

To run the examples from a source checkout instead (uv required):

```powershell
uv sync --locked --extra openai
Copy-Item .env.example .env
# Set OPENAI_API_KEY in .env.
uv run --env-file .env --extra openai python -m examples.openai_agent --headed
```

The example explores the Voyager missions. Use `--url` and `--task` to change the starting page and mission, `OPENAI_MODEL` to select a model, and `--quiet` to suppress streamed events. Add `--done` to allow standalone progress messages and require an explicit completion tool before the final answer. The final answer goes to stdout. Tests use scripted models and need no API key.

## Compose an agent

`Agent` is a browser-ready [Harnessed](https://github.com/mathisarends/harnessed) agent. Its plugins bring together page observations, tools, context management and the choreography of browser input. Configure the pieces you need while keeping the rest of the default kit:

```python
import asyncio

from harnessed import PolicyDecision
from harnessed.models.pydantic_ai import PydanticAIModel
from harnessed.plugins import Approvals
from pydantic_ai.models.openai import OpenAIResponsesModel

from browserrig import (
    Agent, ContextCompaction, ImageContext, Launch, Observe,
    Screenshots, ScreenshotTrigger, UntilCompaction, WindowRatio,
)


async def main():
    agent = Agent(
        model=PydanticAIModel(OpenAIResponsesModel("gpt-6.1-terra")),
        browser=Launch(url="https://en.wikipedia.org/wiki/Voyager_program", headless=False),
        plugins=[
            Approvals(default=PolicyDecision.ALLOW),
            Observe(screenshots=Screenshots(trigger=ScreenshotTrigger.EACH_STEP)),
            ImageContext(UntilCompaction()),
            ContextCompaction(trigger=WindowRatio(0.8)),
        ],
    )
    async with agent.session() as session:
        await session.context.set("constraints", "Include source URLs.")
        result = await session.run("Compare the Voyager missions.", max_steps=20)
        print(result.text)


asyncio.run(main())
```

Install the `openai` extra and set `OPENAI_API_KEY` as in the quick start. The example captures a screenshot at each model step, keeps images until their steps are compacted, and summarizes older context when the model window reaches 80% (or at 100,000 tokens when its size is unknown). The session also carries application context across the task.

This example explicitly permits tool actions with `Approvals(default=PolicyDecision.ALLOW)`.
By default, actions with side effects require approval. Configure an approval
handler with `Approvals(approver=...)` when your application should ask before
acting; without a handler or an explicit allow policy, those actions are rejected.

Plugins replace matching defaults in place or add new capabilities; `without=(...)` removes defaults. By default, `InputPacing` moves the pointer and types at a person's pace, while `InputVisualization` stages actions for viewers through events such as cursor movement, highlights and browser UI. To run without that pacing and presentation, add `without=(InputPacing, InputVisualization)` to `Agent` (import both from `browserrig`). They can also be configured independently.

Sessions support streaming events, pausing, steering and resuming a running task. See the [agent guide](https://github.com/mathisarends/browserrig/blob/main/docs/agent-guide.md) and [browser composition](https://github.com/mathisarends/browserrig/blob/main/docs/browser-composition.md) for controls, context policies and extension points. For direct browser access or connecting to an existing Chrome instance, see [browser interaction](https://github.com/mathisarends/browserrig/blob/main/docs/browser-interaction.md).

Mount `plugins=[Done()]` to opt into [explicit completion and structured final
answers](https://github.com/mathisarends/browserrig/blob/main/docs/agent-guide.md#explicit-completion-and-output-formats). Without it,
ordinary text responses retain Harnessed's default completion behavior.

## Release status

Browserrig is an early 0.x release; public APIs may change between minor versions.
CI covers Python 3.12–3.14 on Windows and Linux, with real Chrome integration tests
on Linux. macOS is not covered by CI; select Chrome explicitly with
`Launch(executable=...)` or `BROWSERRIG_CHROME` there.

Perspective-transformed frames and recovery from browser process crashes remain
limitations. See the [changelog](https://github.com/mathisarends/browserrig/blob/main/CHANGELOG.md)
for release notes.

## Documentation

| Guide | Contents |
| --- | --- |
| [Agent guide](https://github.com/mathisarends/browserrig/blob/main/docs/agent-guide.md) | Setup, action chains, prompts, sessions and controls |
| [Browser interaction](https://github.com/mathisarends/browserrig/blob/main/docs/browser-interaction.md) | Direct access, observations, input and page content |
| [Files and events](https://github.com/mathisarends/browserrig/blob/main/docs/files-and-events.md) | Downloads, workspace, file readers and event streams |
| [Browser composition](https://github.com/mathisarends/browserrig/blob/main/docs/browser-composition.md) | Configure and compose browser plugins |
| [Telemetry](https://github.com/mathisarends/browserrig/blob/main/docs/telemetry.md) | Local traces, configuration and troubleshooting |
| [Development](https://github.com/mathisarends/browserrig/blob/main/docs/development.md) | Setup, checks, tests and project status |
| [Harnessed telemetry feedback](https://github.com/mathisarends/browserrig/blob/main/docs/harnessed-telemetry-feedback.md) | Integration findings |

## License

[MIT](https://github.com/mathisarends/browserrig/blob/main/LICENSE).
