quickstart · for developers

Attach the harness in a few lines.

laserbrain checks your agent against the goal it started from and returns it when it drifts. The check runs locally and free — a pure function, no key, no latency. Add a key later to retain history and get the fleet view. Here is the whole surface.

1 · install

shell
pip install laserbrain          # Python · zero dependencies

npm  install laserbrain         # Node / TypeScript · ships its own types

laserbrain demo                 # watch an agent drift off-goal and get returned

Same name on both registries, independent release lines — neither is ahead of the other. Both are checked against the same conformance corpus, so a verdict is a verdict either side. One difference worth knowing: the Node build comes from a Worker context with no user-turn signal, so reground — the verdict for “the human changed the goal” — cannot arise there. Every other reason is identical.

Source, MIT: github.com/degibug-del/laserbrain · PyPI · npm

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" reading

progress is advancing | stuck | circling; distance is 0–10 to done. Reasons: advancing, grounded, goal-drift, stalled, self-report, ungrammatical.

Pass tokens and it can tell you what the drift cost.

python
r = client.messages.create(...)

v = hz.check(goal="build the JSON parser", progress="advancing", distance=6,
             tokens=r.usage.input_tokens + r.usage.output_tokens)

Optional, one line. With a key, the count is recorded beside the verdict and your account totals everything spent at or after the first drifting verdict — a ledger of tokens actually spent on runs already off-goal, not an estimate. Leave it out and the check is identical; you simply have no cost figure at the end of the month.

3 · close the loop — the act layer

Hand laserbrain your step and it detects drift and injects the return. Your step reads ctx["return"] and steers back. The return cuts steps — that is measured. Whether it keeps the answer as good is not established, and fewer steps is not fewer tokens: the studies, nulls included.

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 i

what’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 →

go further