ACBE — Adaptive Counterfactual Browser Evolution
The autonomous self-improvement layer for AI web agents.
An AI browser agent should not endlessly repeat the exact same mistakes. It should diagnose verified failures, synthesize counterfactual alternatives, validate in a shadow sandbox, and transfer learned heuristics permanently—without retraining model weights.
Key Benchmarks (ACBE-Bench)
Across 25 standardized modern web hazard scenarios (shadow roots, dynamic overlays, timing jitter, polymorphic class mutation):
- 95.2% Autonomous Recovery Rate (recovers trapped navigation sessions with zero human intervention)
- 87.5% Zero-Shot Cross-Environment Transfer (generalizes heuristics learned on one domain to completely unseen websites)
- 0.0% Regression Rate (strictly guarded by two-proportion Z-test statistical gates)
Installation
Install the zero-dependency core engine from PyPI:
pip install acbe
Or install with optional full dashboard and browser dependencies:
pip install "acbe[full]"
Quickstart in 30 Seconds
Python SDK
from acbe import ACBE
from acbe.agents.custom_agent import ScriptedAgent
from acbe.core.types import ActionType, LocatorStrategy
from acbe.experiments.runner import TaskStep
from benchmarks.environments import make_shop_environment
# 1. Initialize environment with an adversarial trap (e.g. look-alike button)
env = make_shop_environment("demo-shop", trap=True)
# 2. Define baseline agent
agent = ScriptedAgent(
steps=[
TaskStep(ActionType.CLICK, "Browse products"),
TaskStep(ActionType.CLICK, "Add to cart"),
TaskStep(ActionType.CLICK, "Proceed to checkout"),
],
locator_strategy=LocatorStrategy.TEXT_VISUAL,
)
# 3. Wrap with ACBE self-healing layer
system = ACBE(agent=agent, browser="mock", environment=env)
# 4. Execute and observe autonomous self-healing
result = system.run_and_improve("Add product to cart and checkout.")
print("Initial Run:", result.initial_success)
print("Improvement Triggered:", result.improvement_triggered)
print("Promoted Strategy:", result.improvement.top_candidate)
CLI
ACBE includes a full developer CLI:
# Initialize local state store
acbe init
# Run a navigation task
acbe run wrong_element_0
# Trigger autonomous diagnosis and repair loop
acbe improve wrong_element_0
# Launch the local REST API server
acbe serve --port 8420
The 5-Stage Closed Learning Loop
Task Execution ➔ Invariant Verification ➔ Root Cause Diagnosis
➔ Counterfactual Strategy Funnel ➔ Shadow Sandbox A/B Gate
➔ Procedural Memory Indexing ➔ Zero-Shot Transfer
- Deterministic Invariant Checks: Agents are never permitted to declare their own success. External DOM state hashes verify post-conditions.
- Root Cause Diagnosis: Maps failure symptoms to 13+ deterministic web trap classes (e.g., selector drift, hydration delay, overlay interception).
- Counterfactual Strategy Funnel: Synthesizes alternative execution candidates filtered cheaply from heuristic to LLM-level.
- Statistical Promotion Gate: Validates candidates in a shadow sandbox against baseline and regression suites ($z \ge 1.96, p < 0.05$).
- Procedural Vector Memory: Records promoted rules for runtime reuse across mutated domains.
Interactive Console & Landing Page
ACBE includes a Next.js 14 engineering console featuring:
- Virtual Browser Viewport: Step-by-step element trajectory inspector with target highlighting.
- Diagnostic Failure Lab: Bayesian root cause confidence meters and inline 1-click auto-repair.
- 4-Tier Strategy Registry: Visual advancement funnel (Draft ➔ Experimental ➔ Validated ➔ Promoted).
- A/B Trial Comparator: Head-to-head win rate comparison and token overhead meters.
- Lineage DAG & Safe Rollback: 1-click atomic snapshot rollback for full provenance.
To launch the full stack locally:
# Windows 1-click launcher
start_project.bat
# Or manual launch:
py -m acbe.cli.main serve --port 8420
cd frontend && npm run dev
Project Architecture
acbe/ # Core installable Python library
├── core/ # Types, config, state machine invariants
├── failure/ # Diagnostic engine & 13-class taxonomy store
├── strategy/ # Heuristic synthesis & MCTS candidate ranking
├── experiments/ # A/B runner, statistical promotion gates
├── memory/ # SQLite & vector procedural store
├── evolution/ # Version DAG lineage & safe rollback engine
└── api/ # Flask REST API engine
benchmarks/ # ACBE-Bench standardized web hazard tasks
frontend/ # Next.js 14 + Tailwind luxury console & landing page
tests/ # Complete pytest test suite (143 unit tests)
Testing
Run all automated unit tests:
pytest tests/ -q
# 143 passed in 9.79s
License
MIT License. Open research & developer contribution welcomed.
Metadata
Release files for acbe 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| acbe-0.1.0.tar.gz | 83.5 kB | Without provenance | Details for acbe-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| acbe-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for acbe-0.1.0-py3-none-any.whl |
Total release size: 170.8 kB
Release files / acbe-0.1.0.tar.gz
| Download URL | acbe-0.1.0.tar.gz |
|---|---|
| Size | 83.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
73f77a7d97b5a650bdb476caaa21c3bbe3377e39e1026ce74eec8f10f1f3cbaa
|
|
BLAKE2b-256 checksum How to use checksums |
c87e2e22e7844828841502388b2422718131e449b7ce34191ddd08ee73f90dcf
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.10
|
Release files / acbe-0.1.0-py3-none-any.whl
| Download URL | acbe-0.1.0-py3-none-any.whl |
|---|---|
| Size | 87.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a23992acd283e0213e88a27185bd7f20e7fa06b09559c7d7311b1d9c158d272b
|
|
BLAKE2b-256 checksum How to use checksums |
a6e4c1b7329b5a7199075385005058c4218326761cd5308987c32ab68738be77
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.10
|
Security for acbe 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.