Metadata-Version: 2.4
Name: gl-browser-use
Version: 0.0.0b8
Summary: A typed Python SDK for running browser automation tasks through `browser-use`
Author-email: Reinhart Linanda <reinhart.linanda@gdplabs.id>
Requires-Python: <3.13,>=3.11
Description-Content-Type: text/markdown
Requires-Dist: browser-use<0.12.0,>=0.11.13
Requires-Dist: json-repair<0.47.0,>=0.46.0
Requires-Dist: pydantic<3.0.0,>=2.0.0
Requires-Dist: requests<3.0.0,>=2.32.4
Provides-Extra: steel
Requires-Dist: steel-sdk<0.17.0,>=0.16.0; extra == "steel"
Provides-Extra: infrastructure
Requires-Dist: gl-browser-use[steel]; extra == "infrastructure"
Provides-Extra: minio
Requires-Dist: minio<8.0.0,>=7.2.20; extra == "minio"
Provides-Extra: storage
Requires-Dist: gl-browser-use[minio]; extra == "storage"
Provides-Extra: full
Requires-Dist: gl-browser-use[infrastructure,storage]; extra == "full"

# GL Browser Use

GL Browser Use is a typed Python SDK for running browser automation tasks through `browser-use`. It provides a stable client facade, structured stream events, explicit result objects, optional Steel browser infrastructure, optional MinIO/S3-compatible recording storage, and bounded retries for recoverable browser-session failures.

## Installation

Install the core SDK:

```bash
pip install gl-browser-use
```

Install optional providers only when you need them:

```bash
pip install "gl-browser-use[steel]"           # Steel browser infrastructure
pip install "gl-browser-use[infrastructure]"  # All browser infrastructure providers
pip install "gl-browser-use[minio]"           # MinIO/S3-compatible object storage
pip install "gl-browser-use[storage]"         # All object storage providers
pip install "gl-browser-use[full]"            # Infrastructure + storage providers
```

Use the concrete extras (`steel`, `minio`) in application dependency files when you want to pin exactly which provider you depend on. The slot extras (`infrastructure`, `storage`, `full`) are convenience aliases and may include more providers later.

## Quick Start

`BrowserUseClient` supports streaming and non-streaming execution. API keys can be passed directly or read from environment variables.

```python
import asyncio

from gl_browser_use import BrowserUseClient, BrowserUseClientConfig
from gl_browser_use.infrastructure import SteelBrowserInfrastructure
from gl_browser_use.storage import MinIOS3CompatibleStorage


async def main() -> None:
    client = BrowserUseClient(
        config=BrowserUseClientConfig(
            llm_openai_api_key="...",
            page_extraction_llm_openai_api_key="...",
            max_session_retries=2,
            session_retry_delay_in_s=3.0,
        ),
        infrastructure=SteelBrowserInfrastructure(),  # reads STEEL_API_KEY by default
        storage=MinIOS3CompatibleStorage.from_environment(),
    )

    async for event in client.run("Open Hacker News and list five article titles"):
        print(event.content)


asyncio.run(main())
```

For a single aggregated result:

```python
from gl_browser_use import BrowserUseClient, BrowserUseClientConfig
from gl_browser_use.infrastructure import SteelBrowserInfrastructure

client = BrowserUseClient(
    config=BrowserUseClientConfig(
        llm_openai_api_key="...",
        page_extraction_llm_openai_api_key="...",
    ),
    infrastructure=SteelBrowserInfrastructure(),
)

result = client.run_sync("Open Hacker News and list five article titles")

print(result.status)
print(result.final_output)
print(result.session_id)
print(result.streaming_url)
print(result.recording_url)
print(result.metadata)
```

## Configuration

`BrowserUseClientConfig` validates required values when the client is created. If `llm_openai_api_key` or `page_extraction_llm_openai_api_key` is not passed, both default to `OPENAI_API_KEY`.

Common client options:

1. `llm_openai_model`: primary browser-control model. Default: `o3`.
2. `page_extraction_llm_openai_model`: page extraction model. Default: `gpt-5-mini`.
3. `extend_system_message`: optional system prompt extension.
4. `vision_detail_level`: `auto`, `low`, or `high`. Default: `auto`.
5. `llm_timeout_in_s`: optional LLM timeout.
6. `step_timeout_in_s`: per-step browser timeout. Default: `180`.
7. `enable_cloud_sync`: controls `browser-use` cloud sync. Default: `False`.
8. `logging_level`: `debug`, `info`, `warning`, `error`, or `result`. Default: `info`.
9. `max_session_retries`: recoverable session retries. Default: `2`.
10. `session_retry_delay_in_s`: delay between retries. Default: `3.0`.

Optional provider environment variables:

1. `STEEL_API_KEY`: used by `SteelBrowserInfrastructure()` when `api_key` is not passed.
2. `OBJECT_STORAGE_URL`: MinIO/S3 endpoint, for example `localhost:9001` or `https://storage.example`.
3. `OBJECT_STORAGE_USERNAME`: object storage access key.
4. `OBJECT_STORAGE_PASSWORD`: object storage secret key.
5. `OBJECT_STORAGE_BUCKET_NAME`: target bucket name.
6. `OBJECT_STORAGE_DIRECTORY_PREFIX`: optional object key prefix.
7. `OBJECT_STORAGE_SECURE`: `true` for HTTPS when the endpoint has no scheme.

Copy `.env.example` to `.env` for local development, then load it with your application environment manager.

## Runtime API

The client exposes three run methods:

1. `run(task)`: async generator that yields `BrowserUseStreamEvent` values as work progresses.
2. `run_once(task)`: async method that returns one `BrowserUseRunResult` and includes emitted events in `result.events`.
3. `run_sync(task)`: blocking wrapper around `run_once()` using `asyncio.run()`.

Do not call `run_sync()` from an already running event loop. Use `await run_once()` or `async for event in run()` in async applications.

Cancelling the stream by breaking from `async for` or calling `await stream.aclose()` cancels the underlying run task. Browser sessions and infrastructure sessions are released in cleanup.

## Result Contract

`BrowserUseRunResult` contains:

1. `status`: `success`, `error`, or `cancelled`.
2. `task`: normalized task string.
3. `final_output`: final text extracted from the underlying agent, or `Task completed` when no final text is available.
4. `session_id`: infrastructure session ID when an external browser session was used.
5. `streaming_url`: browser debug or streaming URL when available.
6. `recording_url`: expected recording URL when recording is configured.
7. `steps`: number of browser-use steps executed.
8. `error`: terminal error message for error results.
9. `events`: collected stream events for `run_once()`.
10. `metadata`: attempt, retry, and recording metadata.

Recording metadata uses these statuses:

1. `disabled`: infrastructure, storage, or browser context is not available.
2. `unsupported`: the selected infrastructure does not support recording.
3. `unavailable`: storage is configured but not available.
4. `scheduled`: a background recording upload has been scheduled.
5. `unknown`: recording may have started, but the terminal error did not include enough context to determine the final state.

## Streaming Contract

`BrowserUseStreamEvent` contains:

1. `event_type`
2. `content`
3. `thinking_and_activity_info`
4. `is_final`
5. `tool_info`
6. `metadata`

Important event content values:

1. `Receive streaming URL`: emitted when a browser debug or streaming URL is available.
2. `Receive recording URL`: emitted when a recording URL can be resolved.
3. `Task completed`: emitted for the final successful step.

Activity events encode iframe URLs in `thinking_and_activity_info["data_value"]` as a JSON string:

```json
{"type": "iframe", "message": "<url>"}
```

Step events include serialized tool calls in `tool_info["tool_calls"]`.

## Retries And Errors

The client retries only classified recoverable browser-session failures, such as browser closure or websocket disconnect messages. Before each retry, it emits a retry status event. Retries are bounded by `max_session_retries`, so total attempts are `max_session_retries + 1`.

Non-recoverable task failures return `BrowserUseRunResult(status="error")`. Recoverable failures that exhaust all attempts raise `BrowserUseRetryExhaustedError`.

SDK error types:

1. `BrowserUseConfigurationError`: missing or invalid runtime configuration.
2. `BrowserUseDependencyError`: optional provider dependency problem.
3. `BrowserUseMissingDependencyError`: optional provider extra is not installed.
4. `BrowserUseExecutionError`: execution-time failure.
5. `BrowserUseRetryExhaustedError`: recoverable session retries were exhausted.

## Optional Providers

Optional providers are lazy-loaded. Importing `gl_browser_use` does not require Steel or MinIO to be installed.

```python
from gl_browser_use.infrastructure import SteelBrowserInfrastructure
from gl_browser_use.storage import MinIOS3CompatibleStorage
```

`SteelBrowserInfrastructure` creates Steel browser sessions and provides CDP/streaming URLs. `MinIOS3CompatibleStorage` uploads session recordings to MinIO or an S3-compatible service and returns presigned URLs.

## Development

From `libs/gl-browser-use`:

```bash
make install-dev
make test-unit
make test-integration
make lint
make build-check
```

Useful targets:

1. `make test`: run all tests.
2. `make test-unit`: run unit tests with coverage.
3. `make test-integration`: run integration-marked contract tests.
4. `make lint`: run Ruff checks.
5. `make format`: run Ruff fixes and formatter.
6. `make pre-commit`: run pre-commit hooks.
7. `make build-check`: build the package and validate artifacts with Twine.
