0.4.0 — running it, and looking at what happened

0.3.0 could describe a graph, check it, and choose a route through it. It could not execute one, and it could not draw one without a domain baked into the drawing. This release does both.

Install

pip install "browsergraph @ git+https://github.com/aidonerightcorp/browsergraph.git@v0.4.0"

The wheel has no dependencies at all. Every engine, OCR backend and plotting library is an optional extra, so a graph can be built, drawn, linted, compiled and mock-run with nothing else installed.

Added

• An executor — map steps, branches, parallel workers, fallbacks, a cache, content-hashed artifacts, and receipts for failures too. Steps record when they started, not only how long they took, so a picture of a run can show two of them overlapping instead of stacking them end to end.
• solve — one call that tries routes, runs them, judges the output, and returns a champion and a fallback. Judging is a separate argument because "did it work" must not mean "did it not raise": a route returning an empty record passes that test with full marks.
• Seven pictures of any workbench — shape, route space, funnel, per-step evidence, run timeline, solve scoreboard, learning trend — plus Mermaid, JSON and matplotlib renderings and a self-contained HTML report that opens with no network. Domain-neutral: viz takes a graph and knows nothing else.
• browsergraph draw and browsergraph solve — both of the above were reachable only from Python.
• Eleven problem templates across nine domains, each carrying its anti-patterns.
• Bounded execution — a step gets its own process with a clock and a memory ceiling. Lifecycle isolation, not a sandbox, and it says so in its first paragraph.
• A hash-chained journal, so evidence survives the process and an edited history is detectable.
• Model-guided exploration — the model proposes, the compiler disposes, and a refused suggestion is recorded as refused.

Fixed

• A run's verdict never reached the per-candidate posteriors. solve stamps the judge's answer onto the receipt, but only the per-step flag was read — so after six runs, a reader that produced two records and one that produced none had identical posteriors.
• An optimism clamp saturated every candidate whose prior plus bonus reached 1.0 — which, since an undeclared prior is 1.0, was almost all of them. Tried and untried scored identically and the search stopped exploring.
• The pair detector compared a route's outcome against the product of two rates, a category error: on data built with no interaction at all it reported eleven.
• Exhaustive search materialised the whole product and took 53GB of the machine with it on a 3.8-trillion-route space. It now refuses above a limit, with the number in the message, and streams below it.
• Discovery and the compiler disagreed about types, so a notebook reported zero legal routes forever; compile_route never checked candidate ports despite a comment saying it did; artifacts were detected by name rather than content, so a second run reported writing nothing.

Full notes in CHANGELOG.md. 1,341 tests.

browsergraph 0.3.0 — the universal graph model

Six stages, fourteen sub-steps, 3,802,314,700,800 routes — and a search that says how much of the space it actually looked at.

Install without PyPI (the wheel is attached and verified in a clean virtualenv):

pip install https://github.com/aidonerightcorp/browsergraph/releases/download/v0.3.0/browsergraph-0.3.0-py3-none-any.whl
browsergraph capabilities
browsergraph workbench -o studio.html

Explore it live: https://aidonerightcorp.github.io/browsergraph/

Added

• The universal graph model — portable node manifests, atomic candidates, ordered stages, complete routes, typed feedback channels and optimization profiles, with a validator that returns every problem rather than the first. Plain English: HOW_IT_WORKS.md.
• Sub-steps — stages decompose recursively. "Acquire inputs" is three decisions, not one, and drawing it flat hid 44,343× of the search space.
• Policy gating and route search — policy gates before anything is scored; greedy, beam or exhaustive, always reporting coverage.
• Receipts — route, spec, environment, per-step timing, artifacts with content hashes, and a pasteable replay line. Written for failures too.
• A capability handshake — engines declare what they can do; a graph is checked before a browser launches, and the refusal names the engines that could run it.
• Fourteen nodes — press, select, upload, download, frames, cookies, viewport, PDF, plus wait_stable, a11y_tree, assert_text, assert_url, attribute, count.
• A model router — ten roles routed to the right model with a recorded reason.
• OCR — five interchangeable backends, and a check that caught a WebKit render that laid out perfectly and drew not one glyph.

Fixed

• Every objective profile ranked identically — raw values were combined, so latency in the thousands swamped quality in [0,1]. "Balanced" was secretly speed-only.
• Beam search bought nothing — it matched plain greedy at width 1, 8, 32, 128 and 512.
• Ranking was O(n²), making exhaustive search correct and unreachable.
• The chromedriver came from PATH, not from the browser being launched.
• Playwright's frame switch was decorative.

859 tests, mypy and ruff clean.

v0.2.0 — contracts, CDP engines, and things that were declared but did not work

The theme of this release is capabilities that were declared and did not work — the
worst state for a capability table to be in, because the validator accepts your spec and
the failure arrives much later.

Highlights

Every engine actually runs. 126 verified engine × binary × display combinations, up
from 51, each one launched against a served page rather than read off a table. Playwright,
Patchright, playwright-stealth, rebrowser, Selenium, undetected-chromedriver, SeleniumBase,
Botasaurus, Camoufox, nodriver, zendriver, pydoll — plus engine=http, which needs no
browser at all. Chromium, Chrome, Firefox, WebKit and Brave, headless, headed and xvfb.

Contracts, enforced. A node's declarations are load-bearing: the linter decides whether
a graph verifies its mutations by trusting mutates, and the scheduler parallelises on
reads/writes. A node that misdeclares itself does not fail — it silently switches those
checks off. Declarations are now checked at import, at composition, and at run time.

Two diagrams. browsergraph planes draws the architecture: a task decomposes into
planes, each offering interchangeable candidates, and the chosen route moves as evidence
arrives. browsergraph space draws the configuration space — click stealth=undetected
and five engines grey out at once.

Notebooks work. Jupyter, Kaggle and Colab run every cell inside an asyncio loop, which
Playwright's sync API refuses. The adapter is now driven from a worker thread, so
engine=playwright works in a notebook with no setup — screenshots and video included.

browsergraph bootstrap. Probe, pip, browser binary, system libraries, a Chrome
already on PATH — re-launching after every step, because an installer's exit code is not
evidence that a browser starts.

Fixed

• A failed Playwright launch poisoned the whole interpreter for every later call.
• Escalation never reached its alternatives; an unbounded retry burned every attempt on the
  engine that had just failed.
• Selenium could not drive Firefox at all — a snap wrapper script plus Chrome's flag syntax.
• Every Firefox session leaked a geckodriver process; a snap-confined process cannot be
  signalled even by its owner, and selenium swallows its own teardown failure.
• The default LLMConfig returned HTTP Error 404 against a healthy Ollama.
• Phone extraction invented a number on python.org, whose homepage prints a Fibonacci series.
• focus reported negative savings, and doctor reported a working engine as missing.

Full detail in CHANGELOG.md.

Install

pip install "browsergraph[playwright] @ git+https://github.com/aidonerightcorp/browsergraph.git"
browsergraph bootstrap
browsergraph doctor

Or run the whole tour on Kaggle
without installing anything.

618 tests, mypy and ruff clean.