gl-browser-use 0.0.0b7__tar.gz

gl_browser_use-0.0.0b7/MANIFEST.in

@@ -0,0 +1,5 @@
+global-exclude *.key
+global-exclude *.env
+global-exclude *.aes
+prune tests
+prune build

gl_browser_use-0.0.0b7/PKG-INFO

@@ -0,0 +1,236 @@
+Metadata-Version: 2.4
+Name: gl-browser-use
+Version: 0.0.0b7
+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.

gl_browser_use-0.0.0b7/README.md

@@ -0,0 +1,214 @@
+# 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.

gl_browser_use-0.0.0b7/gl_browser_use/__init__.py

@@ -0,0 +1,60 @@
+"""GL Browser Use SDK.
+
+Public namespace for :class:`BrowserUseClient` and supporting models,
+errors, infrastructure, and storage abstractions.
+
+Authors:
+    Reinhart Linanda (reinhart.linanda@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from gl_browser_use.client import BrowserUseClient
+from gl_browser_use.config import BrowserUseClientConfig
+from gl_browser_use.errors import (
+    BrowserUseConfigurationError,
+    BrowserUseDependencyError,
+    BrowserUseExecutionError,
+    BrowserUseMissingDependencyError,
+    BrowserUseRetryExhaustedError,
+    BrowserUseSDKError,
+)
+from gl_browser_use.infrastructure import __getattr__ as _infrastructure_getattr
+from gl_browser_use.infrastructure.base import BrowserInfrastructure, BrowserInfrastructureContext
+from gl_browser_use.models import BrowserUseRunResult, BrowserUseStreamEvent
+from gl_browser_use.storage import __getattr__ as _storage_getattr
+from gl_browser_use.storage.base import ObjectStorage
+
+__all__ = [
+    "BrowserUseClient",
+    "BrowserUseClientConfig",
+    "BrowserUseConfigurationError",
+    "BrowserUseDependencyError",
+    "BrowserUseExecutionError",
+    "BrowserUseMissingDependencyError",
+    "BrowserUseRetryExhaustedError",
+    "BrowserUseSDKError",
+    "BrowserUseRunResult",
+    "BrowserUseStreamEvent",
+    "BrowserInfrastructure",
+    "BrowserInfrastructureContext",
+    "SteelBrowserInfrastructure",
+    "ObjectStorage",
+    "MinIOS3CompatibleStorage",
+]
+
+
+def __getattr__(name: str):
+    """Expose optional classes lazily to avoid import-time dependency failures."""
+    if name == "SteelBrowserInfrastructure":
+        return _infrastructure_getattr(name)
+    if name == "MinIOS3CompatibleStorage":
+        return _storage_getattr(name)
+    raise AttributeError(f"module 'gl_browser_use' has no attribute {name!r}")
+
+
+def __dir__() -> list[str]:
+    return sorted(__all__)
+
+
+__version__ = "0.1.0"