1 · install
shell
pip install laserbrain # zero dependencies
laserbrain demo # watch an agent drift off-goal and get returned
2 · the check
Each step, your agent spells its state — the goal, whether it’s advancing, and how far from done. laserbrain remembers the ground it started from and tells you if it has drifted.
python
from laserbrain import Harness
hz = Harness()
v = hz.check(goal="build the JSON parser", progress="advancing", distance=6)
if v.drifting:
print(v.reason, "—", v.advice) # e.g. goal-drift — your goal no longer matches…
print(v.ground_score) # a bounded [0,1] "how grounded" readingprogress is advancing | stuck | circling; distance is 0–10 to done. Reasons: advancing, grounded, goal-drift, stalled, self-report, ungrammatical.
3 · close the loop — the act layer
Hand laserbrain your step and it detects drift and injects the return, so the agent recovers instead of spinning. Your step reads ctx["return"] and steers back.
python
def step(ctx):
if ctx.get("return"): # laserbrain told us to return to ground
... # steer the agent back toward its goal
...
return dict(goal="build the JSON parser", progress="advancing", distance=d, done=d == 0)
ctx = Harness().run(step, on_return=lambda v, ctx: print("↩", v.advice))4 · async agents
Same loop, awaited — your step and callbacks may be async, and the API mirror runs off the event loop so it never blocks. Afterward, report() prints the shape of the run.
python
hz = Harness()
await hz.arun(async_step) # the act layer for asyncio agents
print(hz.report())
# laserbrain · 11 steps · 1 drift(s)
# goal: 'build the JSON parser'
# Φ ▁▂▃▃▃▃▃▃▅▇█ peak 0.21
# drifts: stalled×1
5 · your framework
Already on LangGraph, CrewAI, AutoGen, or the OpenAI Agents SDK? You map your state to (goal, progress, distance), and laserbrain watches from inside your loop. No adapter imports a framework — install only the one you use.
python
from laserbrain.adapters import guard, langgraph_node, crewai_step_callback, middleware
@guard # any step returning dict(goal=, progress=, distance=)
def step(state): ...
# LangGraph — a node that writes the Verdict into graph state; branch on it
g.add_node("laserbrain", langgraph_node(extract=lambda s: (s["goal"], "advancing", s["dist"])))
g.add_conditional_edges("laserbrain", lambda s: "return" if s["laserbrain"].drifting else "agent")
# CrewAI — a step_callback that fires each agent step
Agent(..., step_callback=crewai_step_callback(lambda o: (o.goal, o.status, o.dist)))6 · when a return doesn’t take — a human decides
If the drift persists past a few self-corrections, escalate it to a person. They see only what the fixed reference caught, and their decision overrides the auto-return. Every check is also written to a tamper-evident, offline-verifiable audit log.
python
Harness().run(step, escalate_after=3, on_escalate=ask_a_human) # human-in-the-loop
hz.export_audit("run.json")
from laserbrain import verify_audit
verify_audit(json.load(open("run.json"))) # (True, -1) intact · (False, i) broken at link iwhat’s proven — and what isn’t
The single-agent detector is a theorem — a fixed external reference is necessary and sufficient to catch drift, and no self-watching monitor is. Whether returning makes the final answer better is an open question we’ve tested and not established. The multi-agent teams are a prototype. We say plainly what each is. The proof and every study →