five-levels: Generate Verified Interactive Explainers with a Research Agent

five-levels is the runnable artifact behind the implementation report on explaining topics at five levels. It adds a second output format to a deep research agent: instead of a paper, --format five-levels turns a research question into one standalone interactive HTML page — a topic explained to a child, a teenager, an undergraduate, a PhD student, and a peer, in the spirit of WIRED's "5 Levels" series. It is aimed at learning-systems engineers and applied researchers evaluating whether the format, or the verification pattern behind it, fits their own pipelines.

What it does

The agent package (research-agent/src/deep_research/explainer/, nine files including graph.py, shell.py, repair.py, and validate.py) runs a fixed pipeline: research into an append-only evidence ledger, a design call that produces the running example, palette, shared_data_js, and five LevelPlans, five parallel write_level calls, assembly into a fixed HTML shell, node --check per level, headless-Chrome validation with at most two repair rounds (only failing levels go back), claim-level verification of all five levels' prose against the ledger, and a publish gate that blocks anything that skipped a step. Each level carries a bespoke D3 or canvas panel; one running example and one shared data model thread all five levels.

A standalone browser validator (scripts/validate-explainer.mjs) drives installed Chrome via playwright-core: it clicks each rail tab, checks for a real <svg> or <canvas>, operates up to 10 controls, flags static ones, and screenshots each level. Offline tools (repair, rerender) let you re-run validation or rebuild a finished page through the current shell without new model calls. A --persona flag carries an expert voice from the CLI into every prompt and the masthead. Intended uses: generating verified explainer pages end to end, or borrowing the validator as a pattern for checking model-written interactive pages.

Who it's for

Learning-systems engineers and researchers who want a reproducible path from research question to verified explainer; instructional designers evaluating the "one running example, five rebuilds" format; and engineers who only want the browser validator. This is a research-grade tool, not a product: runs cost real tokens (roughly 150k–210k input / 51k–71k output on the paper's runs), and human review of the page before publishing is part of the design, not optional.

How to use it

There is no package release — install by cloning:

git clone https://github.com/binaryninja/five-levels
cd five-levels
uv sync --project research-agent
npm install
cp .env.example .env

The memory example page in examples/ was produced by this exact run:

uv run --project research-agent deep-research \
  "How does human memory work: how are memories encoded, consolidated, retrieved, and forgotten?" \
  --pillar learning --preset quick --format five-levels \
  --persona "a neuroscientist who studies memory" --export

The repository README covers the full CLI surface, the shell contract, and the offline repair and rerender commands.

Status and roadmap

Active as of September 2026; the repo ships alongside the paper, with CI running the 155 Python tests and the validator's --check. Known limitations, stated plainly: verification checks prose, not panels; the repair loop fixes code, not pedagogy; the validator proves absence of failure, not presence of function (a no-op button passes); English only; every page loads D3 7.9.0 from cdnjs, so a "standalone" page keeps one runtime third-party dependency; and persona consistency is prompt-level only, guarded by a single plumbing test. No version tag exists — cite the commit.

Source and license

Source lives at the public GitHub repository, MIT-licensed, Copyright (c) 2026 Jeremy Richards. Model output is sanitized of active markup and pages ship with a strict CSP (connect-src 'none'), but published pages should still get human review before they reach learners.

Related research

• Learning, explained at five levels — the implementation report documenting the format, the pipeline, and the verification gates behind this tool.
• What is a verified interactive explainer? — the concept page defining the format; the natural next read if you are deciding whether it fits your problem.
• What is a model-agnostic AI pipeline? — the pipeline architecture this format extends.

FAQ

Can I validate an explainer page without running the research agent?

Yes. The browser validator is standalone: npm run explainer:validate -- --file <page.html> --out <dir> drives your installed Chrome via playwright-core and writes per-level screenshots and results. Run node scripts/validate-explainer.mjs --check first to verify the environment, including that Chrome launches.

Does verification cover the interactive panels or just the prose?

Prose only. The verifier checks the five levels' text against the evidence ledger; the panel and shared-data JavaScript are exercised in headless Chrome for errors and wired controls, but computed values are never fact-checked. A simulation can converge to a wrong number and still pass, so panel review remains a human job.

What do I need installed to run it?

uv, Node, an installed Google Chrome, and model-provider API keys in a .env file. There is no pip or npm package — install is a git clone followed by uv sync and npm install. Add --preflight-only to check the environment, including browser launch, before spending research budget.