Metadata-Version: 2.4
Name: oculr
Version: 0.1.0
Summary: Client for the Oculr local Automation API: launch real browser profiles, pick a per-launch stealth level, and connect over CDP.
Project-URL: Homepage, https://oculr.ai
Project-URL: Documentation, https://oculr.ai/developers
Project-URL: Repository, https://github.com/oculr-ai/oculr-sdk
License: MIT
Keywords: ai-agent,ai-agents,anti-detect,antidetect,antidetect-browser,automation,browser,browser-automation,cdp,fingerprint,mcp,model-context-protocol,oculr,playwright,puppeteer,stealth
Requires-Python: >=3.9
Provides-Extra: playwright
Requires-Dist: playwright; extra == 'playwright'
Description-Content-Type: text/markdown

# oculr (Python)

Thin Python client for the **Oculr local Automation API**. Launch real browser
profiles on your own machine, choose a per-launch stealth level, and connect over
CDP with Playwright or Selenium.

Zero runtime dependencies (stdlib only). Playwright is optional, for the
`connect_playwright()` helper.

## Install

```bash
pip install oculr
# optional, for connect_playwright():
pip install playwright
```

## Usage

```python
import os
from oculr import OculrClient
from playwright.sync_api import sync_playwright

# The desktop app shows the port and token under Settings.
oculr = OculrClient("http://127.0.0.1:8378", token=os.environ["OCULR_TOKEN"])

# Low-level: launch and get a ready CDP endpoint + driver recipes.
res = oculr.launch("de-store-01", stealth="balanced", headless=False)
print(res["ws_endpoint"])

# High-level: launch and connect a Playwright browser in one call.
with sync_playwright() as p:
    browser, _ = oculr.connect_playwright(p, "de-store-01", stealth="max")
    page = browser.contexts[0].pages[0]
    page.goto("https://example.com")
    oculr.stop("de-store-01")
```

### Stealth dial

`stealth` is chosen per launch: `"off"` (clean Chromium, no fingerprint
injection), `"balanced"` (native fingerprints, the default) or `"max"` (strongest
noise). Overrides apply to that launch only and are never written back to the
profile.

## API

`list_profiles()`, `create_profile(**body)`, `get_profile(id)`,
`update_profile(id, **body)`, `delete_profile(id)`, `generate_profile(**body)`,
`launch(id, **options)`, `stop(id)`, `status()`,
`connect_playwright(playwright, id, **options)`.

Errors raise `OculrError` with `.status` and `.body`.
