superbrowser-sdk 2.1.1__tar.gz → 2.2.1__tar.gz

superbrowser_sdk-2.2.1/.github/workflows/stress.yml

@@ -0,0 +1,64 @@
+name: Stress Test
+
+on:
+  workflow_dispatch:
+    inputs:
+      mode:
+        description: "Quick or realistic"
+        required: true
+        default: "quick"
+        type: choice
+        options:
+          - quick
+          - realistic
+      sessions:
+        description: "Number of sessions (realistic mode)"
+        required: false
+        default: "3"
+      concurrency:
+        description: "Concurrency (realistic mode)"
+        required: false
+        default: "2"
+
+permissions:
+  contents: read
+
+jobs:
+  stress:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install Super Browser
+        run: |
+          pip install --upgrade pip
+          pip install -e ".[patchright]"
+          python -m patchright install chromium
+
+      - name: Run stress test (quick)
+        if: inputs.mode == 'quick'
+        run: |
+          python scripts/stress_real_world.py --quick \
+            --output stress-results
+
+      - name: Run stress test (realistic)
+        if: inputs.mode == 'realistic'
+        run: |
+          python scripts/stress_real_world.py --realistic \
+            --sessions ${{ inputs.sessions }} \
+            --concurrency ${{ inputs.concurrency }} \
+            --output stress-results
+
+      - name: Upload stress report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: stress-report
+          path: stress-results/
+          retention-days: 90
+          if-no-files-found: warn

{superbrowser_sdk-2.1.1 → superbrowser_sdk-2.2.1}/.gitignore

@@ -70,6 +70,7 @@ benchmarks/results/
 
 # Smoke test results
 smoke-results/
+stress-results/
 
 # E2E trend artifacts
 tests/e2e/artifacts/e2e-history.json

{superbrowser_sdk-2.1.1 → superbrowser_sdk-2.2.1}/CHANGELOG.md

@@ -7,6 +7,79 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.2.1] — 2026-06-17
+
+### Overview
+
+**v2.2.1 — Runtime Correctness**
+
+Patch release fixing three user-facing runtime defects discovered in
+post-release source audit. No new features, no breaking changes.
+
+### Fixed
+
+- **Rich page fingerprint `interactive_count`** (loop.py): Was iterating
+  dict keys instead of `.values()`, calling `.get()` on string keys.
+  The `except` block silently returned `interactive_count=0` every time,
+  weakening page change detection. Now correctly counts interactive
+  nodes via `is_interactive` attribute.
+
+- **iframe action scoping** (controller.py + facade.py): `enter_frame()`
+  pushed a frame locator but no interaction method used it — all actions
+  targeted the top-level page instead of the iframe. New
+  `FrameInteractionTarget` adapter normalizes Playwright's
+  `FrameLocator` API (`.locator(sel).click()`) to match the controller's
+  selector-tier signatures (`.click(sel)`).
+
+- **IPReputationClient async path** (ip_reputation.py): Replaced
+  deprecated `asyncio.get_event_loop()` with `asyncio.get_running_loop()`
+  to fix DeprecationWarning on every call and future RuntimeError risk.
+
+### Internal
+
+- **Stress signal accuracy** (#167): RSS measurement prefers `psutil`
+  with platform-aware fallback; periodic `RSSSampler`; hard sleeps
+  replaced with `_wait_for_condition()` polling; `parallel_profiles`
+  verifies cross-context isolation; `/api/upload` returns real digest.
+
+## [2.2.0] — 2026-06-16
+
+### Overview
+
+**v2.2.0 — API Ergonomics**
+
+v2.2 polishes the public API surface based on the Track D discovery
+audit. No new features, no breaking changes — cleaner imports, better
+CLI discoverability, and a new `python -m super_browser` entry point.
+
+### Added
+
+- **`python -m super_browser` support**: New `__main__.py` delegates to
+  the CLI dispatcher, so users can run either `superbrowser version` or
+  `python -m super_browser version`.
+
+### Changed
+
+- **Standardized top-level imports**: All examples, quickstart, and docs
+  now use `from super_browser import SuperBrowser`, `Config`, and
+  `create_llm` instead of deep module paths.
+- **CLI help clarified**:
+  - `stealth-check` → "Run offline fingerprint scoring and report"
+  - `stealth-validate` → "Validate fingerprint against baselines
+    (CI/regression mode)"
+  - `result-demo` → labeled as internal command
+- **API reference cleaned**: Removed stale `SuperBrowserConfig`
+  references (class removed in v2.0) and the removed `core` field row
+  from `AgentConfig`.
+- **`raw_page` deprecation updated**: Removal target changed from
+  "v2.1" to "v3.0" — the alias stays available through the v2.x series.
+
+### Track D audit artifacts
+
+- `docs/api-ergonomics-audit.md` — full discovery document with 15
+  findings across three buckets (patch-safe, backward-compatible polish,
+  defer).
+
 ## [2.1.1] — 2026-06-16
 
 ### Fixed — Smoke workflow install spec format

{superbrowser_sdk-2.1.1 → superbrowser_sdk-2.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: superbrowser-sdk
-Version: 2.1.1
+Version: 2.2.1
 Summary: Anti-detection agent browser SDK — stealth, budget governance, security guardrails, and structured error recovery behind one async facade
 Project-URL: Homepage, https://github.com/Octo-Lex/Super-Browser
 Project-URL: Documentation, https://github.com/Octo-Lex/Super-Browser#readme

superbrowser_sdk-2.2.1/docs/api-ergonomics-audit.md

@@ -0,0 +1,195 @@
+# Track D — API Ergonomics Audit
+
+> **v2.1.1 baseline** — 2026-06-16
+>
+> Discovery document for the v2.2 "API Ergonomics" track.
+> No code changes in this audit — findings only.
+
+---
+
+## Methodology
+
+Systematic inspection of:
+
+1. Public API surface (`__all__`, signatures, return types)
+2. CLI help output, command naming, option consistency
+3. Testing utilities (`E2EContext`, `MockLLMClient`, report builders)
+4. Documentation (quickstart, API reference, architecture, examples)
+5. Migration remnants from v1.x → v2.0
+
+---
+
+## Findings
+
+### Bucket 1 — Patch-safe (docs, help text, examples, aliases)
+
+These changes are safe to ship without any risk to existing code.
+
+#### 1.1 Stale `SuperBrowserConfig` in API reference
+
+`docs/api-reference.md` still references `SuperBrowserConfig` in three
+places — a class removed in v2.0:
+
+- Line 45: constructor signature shows `config: Optional[SuperBrowserConfig]`
+- Line 54: parameter table lists `SuperBrowserConfig | None`
+- Line 631: `AgentConfig.core` field table references `SuperBrowserConfig`
+
+**Fix:** Replace all `SuperBrowserConfig` → `Config` in the API reference.
+
+#### 1.2 Inconsistent import paths in examples and quickstart
+
+The top-level package exports `SuperBrowser`, `Config`, `ActionResult`,
+`StreamEvent`, and `create_llm` via `__all__`. But examples and docs use
+inconsistent deep-import paths:
+
+| Canonical (top-level) | Deep import used in docs/examples |
+|:----------------------|:----------------------------------|
+| `from super_browser import SuperBrowser` | `from super_browser.agent.facade import SuperBrowser` |
+| `from super_browser import create_llm` | `from super_browser.agent.llm.factory import create_llm` |
+| `from super_browser import Config` | `from super_browser.config import Config` |
+
+Files affected:
+- `examples/basic_usage.py`
+- `examples/budget_tracking.py`
+- `examples/error_handling.py`
+- `examples/multi_tab_workflow.py`
+- `examples/session_persistence.py`
+- `docs/quickstart.md` (multiple sections)
+
+**Fix:** Standardize all examples and quickstart to use top-level imports.
+
+#### 1.3 Quickstart verification command uses deep import
+
+```bash
+# Current (deep import):
+python -c "from super_browser.agent.facade import SuperBrowser; print('OK')"
+
+# Should be:
+python -c "from super_browser import SuperBrowser; print('OK')"
+```
+
+#### 1.4 `raw_page` deprecation message is stale
+
+The `DeprecationWarning` says:
+
+> `raw_page is deprecated, use backend_page instead. Will be removed in v2.1.`
+
+We are in v2.1.1. Either:
+
+- **(a)** Update the message to say "Will be removed in v2.2" (defer)
+- **(b)** Actually remove `raw_page` (breaking, see Bucket 3)
+
+Recommendation: **(a)** — update the message, defer removal.
+
+#### 1.5 CLI has no `python -m super_browser` entry point
+
+Neither `python -m super_browser` nor `python -m super_browser.cli` works —
+only the `superbrowser` console script does. Adding a `__main__.py` is a
+common user expectation and trivially safe.
+
+**Fix:** Add `src/super_browser/__main__.py` that calls `cli.main()`.
+
+#### 1.6 CLI `result-demo` command is internal-looking
+
+`result-demo` is a demonstration command that has no production use.
+It clutters the top-level help output. Consider hiding it from the main
+help listing or moving it to a `--debug` subgroup.
+
+**Fix:** Remove from help listing (keep functional for backward compat).
+
+#### 1.7 CLI `stealth-check` vs `stealth-validate` naming is confusing
+
+Two similarly named commands with different purposes:
+
+| Command | Purpose |
+|:--------|:--------|
+| `stealth-check` | Offline fingerprint scoring + report |
+| `stealth-validate` | Fingerprint validation against baselines + CI mode |
+
+**Fix:** Clarify in help text. Renaming would be a breaking change (defer).
+
+### Bucket 2 — Backward-compatible polish
+
+These add convenience without breaking existing code.
+
+#### 2.1 `create_llm` should be in `__all__` already (confirmed OK)
+
+Verified — `create_llm` is already exported at top level. No action needed.
+
+#### 2.2 `ActionResult.ok` could have a boolean alias property
+
+`ActionResult` uses `.ok` for success/failure. Some users may expect `.success`
+or `.is_ok`. Currently only `.ok` exists. Adding a read-only property alias is
+backward-compatible.
+
+**Decision:** Low value, skip unless explicitly requested.
+
+#### 2.3 `Config.from_env()` is not in quickstart's verification flow
+
+The quickstart shows `Config.from_env()` but doesn't show how to verify it
+succeeded without an LLM API key (validation will report a missing key).
+
+**Fix:** Add a note in quickstart that `validate()` returns errors but doesn't
+raise, and that the missing-API-key error is expected for browser-only use.
+
+#### 2.4 Testing utilities could export `build_e2e_json_report` at a stable path
+
+`build_e2e_json_report` is in `super_browser.testing` — good. But the E2E
+schema v3 validator (`scripts/validate_e2e_report.py`) is not importable.
+If users want to validate reports programmatically, they'd need to run the
+script. Consider extracting the validator into an importable function.
+
+**Decision:** Defer unless external consumers request it.
+
+### Bucket 3 — Defer / avoid (risk to v2.x stability)
+
+#### 3.1 Removing `raw_page` alias entirely
+
+The migration doc said it would be removed in v2.1, but it still works with
+a deprecation warning. Removing it would break any v1.x code that hasn't
+migrated. Since v2.0 just shipped, defer to v3.0.
+
+**Decision:** Defer. Update deprecation message to say "v3.0" instead.
+
+#### 3.2 Removing legacy `core` sub-dict compat in `_build_agent()`
+
+`_build_agent()` still merges a legacy `core` sub-dict for v1.x backward
+compatibility. Removing it would break old YAML/dict configs. Defer.
+
+**Decision:** Defer. No urgency — the compat path is ~5 lines of code.
+
+#### 3.3 Renaming CLI commands
+
+Renaming `stealth-check` → `stealth-score` or `stealth-validate` →
+`stealth-baseline` would improve clarity but break scripts/automation.
+
+**Decision:** Defer to a major version if at all.
+
+#### 3.4 Removing `result-demo` CLI command
+
+Removing it entirely would break anyone who uses it. Keep it functional
+but hide from help (Bucket 1.6).
+
+---
+
+## Summary
+
+| Bucket | Items | Risk | Recommended PR |
+|:-------|------:|:-----|:---------------|
+| **Patch-safe** | 7 | None | PR #163 |
+| **Backward-compatible polish** | 4 | Minimal | Optional |
+| **Defer** | 4 | Breaking | v3.0 |
+
+### Recommended PR #163 scope (patch-safe only)
+
+1. Fix `SuperBrowserConfig` → `Config` in API reference (3 occurrences)
+2. Standardize examples to use top-level imports
+3. Standardize quickstart to use top-level imports
+4. Fix quickstart verification command
+5. Update `raw_page` deprecation message to "v3.0"
+6. Add `__main__.py` for `python -m super_browser` support
+7. Hide `result-demo` from CLI help listing
+8. Clarify `stealth-check` vs `stealth-validate` help text
+
+All items are documentation, help text, or additive-only code changes.
+No public API signatures change.

{superbrowser_sdk-2.1.1 → superbrowser_sdk-2.2.1}/docs/api-reference.md

@@ -1,6 +1,6 @@
 # API Reference
 
-> **Super Browser** v2.1.1 — Complete public API documentation.
+> **Super Browser** v2.2.0 — Complete public API documentation.
 
 This reference covers every public class, method, and function in Super Browser. Classes are grouped by subsystem.
 
@@ -42,7 +42,7 @@ The primary entry point for all browser automation. Wraps the agent loop, stealt
 
 ```python
 class SuperBrowser(
-    config: Optional[SuperBrowserConfig] = None,
+    config: Optional[Config] = None,
     *,
     tool_registry: Optional[ToolRegistry] = None,
     llm_client: Optional[LLMClient] = None,
@@ -51,7 +51,7 @@ class SuperBrowser(
 
 | Parameter | Type | Default | Description |
 |---|---|---|---|
-| `config` | `SuperBrowserConfig \| None` | `None` | Agent configuration. Uses defaults when `None`. |
+| `config` | `Config \| None` | `None` | Agent configuration. Uses defaults when `None`. |
 | `tool_registry` | `ToolRegistry \| None` | `None` | Custom tool registry. Creates a default registry when `None`. |
 | `llm_client` | `LLMClient \| None` | `None` | LLM client for `act()` calls. **Required** for `act()`. |
 
@@ -628,7 +628,7 @@ if errors:
 | `llm_provider` | `str` | `"anthropic"` | LLM provider: `"anthropic"` or `"openai"`. |
 | `llm_model` | `str` | `"claude-sonnet-4-20250514"` | Model identifier. |
 | `llm_api_key` | `str` | `""` | API key for the chosen provider. |
-| `core` | `SuperBrowserConfig` | defaults | Nested agent-level settings. |
+
 
 #### `TracingConfig`
 

{superbrowser_sdk-2.1.1 → superbrowser_sdk-2.2.1}/docs/architecture.md

@@ -1,6 +1,6 @@
 # Architecture
 
-> **Super Browser** v2.1.1 — System architecture, data flow, and extension points.
+> **Super Browser** v2.2.0 — System architecture, data flow, and extension points.
 
 ---
 

{superbrowser_sdk-2.1.1 → superbrowser_sdk-2.2.1}/docs/quickstart.md

@@ -26,7 +26,7 @@ pip install superbrowser-sdk[patchright]
 Verify the installation:
 
 ```python
-python -c "from super_browser.agent.facade import SuperBrowser; print('OK')"
+python -c "from super_browser import SuperBrowser; print('OK')"
 # OK
 ```
 
@@ -68,7 +68,7 @@ Create `my_first_browser.py`:
 """5-minute Super Browser quickstart."""
 
 import asyncio
-from super_browser.agent.facade import SuperBrowser
+from super_browser import SuperBrowser
 
 
 class MockLLMClient:
@@ -151,7 +151,7 @@ export SB_DAILY_BUDGET=5.0
 > browser is less detectable than headless).
 
 ```python
-from super_browser.config import Config
+from super_browser import Config
 
 config = Config.from_env()
 errors = config.validate()
@@ -178,7 +178,7 @@ tracing:
 ```
 
 ```python
-from super_browser.config import Config
+from super_browser import Config
 
 config = Config.from_yaml("super-browser.yaml")
 ```
@@ -186,7 +186,7 @@ config = Config.from_yaml("super-browser.yaml")
 ### Option C: Dictionary
 
 ```python
-from super_browser.config import Config
+from super_browser import Config
 
 config = Config.from_dict({
     "agent": {
@@ -205,7 +205,7 @@ config = Config.from_dict({
 With a real API key, create an LLM client directly:
 
 ```python
-from super_browser.agent.llm.factory import create_llm
+from super_browser import create_llm
 
 # Explicit
 llm = create_llm(provider="anthropic", model="claude-sonnet-4-20250514", api_key="sk-ant-...")

{superbrowser_sdk-2.1.1 → superbrowser_sdk-2.2.1}/examples/backend_selection.py

@@ -12,7 +12,7 @@ import asyncio
 import logging
 
 from super_browser import Config
-from super_browser.agent.facade import SuperBrowser
+from super_browser import SuperBrowser
 from super_browser.browser.config import SessionConfig
 
 logging.basicConfig(level=logging.INFO, format="%(name)s  %(levelname)s  %(message)s")

{superbrowser_sdk-2.1.1 → superbrowser_sdk-2.2.1}/examples/basic_usage.py

@@ -11,7 +11,7 @@ Run:
 import asyncio
 import logging
 
-from super_browser.agent.facade import SuperBrowser
+from super_browser import SuperBrowser
 
 # Configure logging to see what's happening
 logging.basicConfig(

{superbrowser_sdk-2.1.1 → superbrowser_sdk-2.2.1}/examples/budget_tracking.py

@@ -18,7 +18,7 @@ import asyncio
 import logging
 from pathlib import Path
 
-from super_browser.agent.facade import SuperBrowser
+from super_browser import SuperBrowser
 from super_browser.agent.llm.protocol import LLMClient
 from super_browser.budget.governor import TokenBudgetGovernor
 from super_browser.budget.types import (

{superbrowser_sdk-2.1.1 → superbrowser_sdk-2.2.1}/examples/error_handling.py

@@ -12,7 +12,7 @@ Run:
 import asyncio
 import logging
 
-from super_browser.agent.facade import SuperBrowser
+from super_browser import SuperBrowser
 from super_browser.results.types import FailureCategory
 
 logging.basicConfig(level=logging.INFO, format="%(name)s  %(levelname)s  %(message)s")

{superbrowser_sdk-2.1.1 → superbrowser_sdk-2.2.1}/examples/multi_tab_workflow.py

@@ -11,7 +11,7 @@ Run:
 import asyncio
 import logging
 
-from super_browser.agent.facade import SuperBrowser
+from super_browser import SuperBrowser
 
 logging.basicConfig(level=logging.INFO, format="%(name)s  %(levelname)s  %(message)s")
 logger = logging.getLogger(__name__)

{superbrowser_sdk-2.1.1 → superbrowser_sdk-2.2.1}/examples/session_persistence.py

@@ -12,7 +12,7 @@ Run:
 import asyncio
 import logging
 
-from super_browser.agent.facade import SuperBrowser
+from super_browser import SuperBrowser
 
 logging.basicConfig(level=logging.INFO, format="%(name)s  %(levelname)s  %(message)s")
 logger = logging.getLogger(__name__)

{superbrowser_sdk-2.1.1 → superbrowser_sdk-2.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "superbrowser-sdk"
-version = "2.1.1"
+version = "2.2.1"
 description = "Anti-detection agent browser SDK — stealth, budget governance, security guardrails, and structured error recovery behind one async facade"
 readme = "README.md"
 license = { text = "Apache-2.0" }