laserbrain 0.2.0__tar.gz

laserbrain-0.2.0/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: laserbrain
+Version: 0.2.0
+Summary: Attach the smart recursion harness to any agent loop — a provably-correct, external check for when an AI agent (or team) has drifted from its goal.
+Author: phronesis
+License: MIT
+Project-URL: Homepage, https://phronesis.world/laserbrain
+Project-URL: Research, https://phronesis.world/laserbrain/research
+Project-URL: Demo, https://phronesis.world/laserbrain/demo
+Keywords: ai,agents,oversight,drift,mcp,llm,multi-agent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# laserbrain
+
+Attach the **smart recursion harness** to any agent loop — a provably-correct,
+external check for when an AI agent (or a team of agents) has drifted from its goal.
+
+An agent watching only itself provably can't catch its own drift: each step looks
+fine next to the last while it wanders far from where it began. laserbrain is a
+**fixed reference** it checks against instead. There's a proof.
+[The theorem and the studies (nulls included).](https://phronesis.world/laserbrain/research)
+· [Watch it work.](https://phronesis.world/laserbrain/demo)
+
+The check is a pure function, so this SDK runs it **locally and free** — no key, no
+latency. Add a key and it also mirrors to the API for retained drift history,
+alerts and the fleet view: you pay to *see* your agents drift, not for the check.
+
+```bash
+pip install laserbrain
+```
+
+## The check (local, free)
+
+```python
+from laserbrain import Harness
+
+hz = Harness()                      # add key="lb_live_…" to also retain history
+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…"
+```
+
+`progress` is one of `advancing | stuck | circling`; `distance` is 0–10 to done.
+Reasons: `advancing`, `grounded`, `goal-drift`, `stalled`, `self-report:stuck/circling`,
+`ungrammatical`.
+
+## The act layer — close the loop
+
+Give laserbrain your step function 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))
+```
+
+## Recursion teams — styled multi-agent oversight
+
+A **recursion team** styles each role's recursion: a `deep` explorer tolerates
+displacement, a `tight` checker returns fast. laserbrain runs the team, watches the
+shared goal (the fixed reference), and injects the return per role — catching the
+**echo/agreement spiral** a self-watching group can't see.
+
+```python
+from laserbrain import Team
+
+def agent(role, history, injected):
+    # your LLM call for this role; `injected` is a return-to-ground note (or None)
+    return position, distance
+
+Team("adversarial-deliberation", goal="…").run(agent)
+# presets: deep-search · iterative-refinement · adversarial-deliberation
+```
+
+## Oversight, provenance, continuity
+
+**Human-in-the-loop.** A self-correcting return usually takes. When it doesn't —
+the agent keeps drifting past `escalate_after` steps — laserbrain escalates *that
+drift* to a human. The human doesn't watch every step; they see only what the fixed
+reference caught. Their decision overrides the auto-return.
+
+```python
+def on_escalate(v, ctx):
+    return ask_a_human(v.reason, v.advice)     # Slack, a queue, a webhook — you wire it
+                                               # returning a decision injects it as the return
+Harness().run(step, escalate_after=3, on_escalate=on_escalate)
+```
+
+**Provenance.** Every check is written to a hash-chained ledger — tamper-evident and
+verifiable offline, by anyone, no key. Editing a past verdict to hide a drift breaks
+the chain at that link.
+
+```python
+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
+```
+
+**Team continuity.** Snapshot a running team and resume it in a later session — the
+shared goal (the fixed reference) and the dialogue carry over, so the group re-grounds
+instead of starting cold.
+
+```python
+snap = team.snapshot()                         # JSON-safe; persist it anywhere
+team = Team.restore(snap)                       # keeps watching the same ground
+```
+
+## Framework adapters
+
+Already on LangGraph, CrewAI, AutoGen, or the OpenAI Agents SDK? Attach laserbrain
+without changing your loop. Because it checks a fixed reference, it needs the agent
+to *spell* its state — so each adapter takes an `extract` that maps your framework's
+state to `(goal, progress, distance)`. **No adapter imports a framework**: each
+returns a plain callable you hand to the framework's own hook, so install only the
+one you use.
+
+```python
+from laserbrain.adapters import guard, langgraph_node, crewai_step_callback, middleware
+
+# generic — wrap any step that returns dict(goal=, progress=, distance=)
+@guard
+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_edge("agent", "laserbrain")
+g.add_conditional_edges("laserbrain",
+    lambda s: "return" if s["laserbrain"].drifting else "agent")   # .advice steers the return
+
+# CrewAI — a step_callback that fires each agent step
+Agent(..., step_callback=crewai_step_callback(lambda o: (o.goal, o.status, o.dist)))
+
+# anything else (AutoGen, OpenAI Agents, a custom loop) — one check per step
+lb = middleware(extract=my_extract)
+v = lb(step_output)
+if v.drifting: reinject(v.advice)
+```
+
+Each adapter runs the check locally and free; pass `key=`/`run_id=` (or your own
+`Harness`) to also retain history.
+
+## What's proven, and what isn't
+
+The **single-agent** detector mirrors the frozen, published instrument
+(`drift.ts @ 6b483de7`) and rests on a theorem: detection is sound and complete, and
+no self-monitoring agent can be. The **multi-agent** dialogue and recursion teams are
+a prototype extension — useful, not (yet) a theorem. Whether *returning* an agent
+keeps the answer as good is [an honest open question](https://phronesis.world/laserbrain/research);
+this SDK gives you the detection and the return mechanism, and says plainly what each is.
+
+MIT · [phronesis.world/laserbrain](https://phronesis.world/laserbrain)

laserbrain-0.2.0/README.md

@@ -0,0 +1,144 @@
+# laserbrain
+
+Attach the **smart recursion harness** to any agent loop — a provably-correct,
+external check for when an AI agent (or a team of agents) has drifted from its goal.
+
+An agent watching only itself provably can't catch its own drift: each step looks
+fine next to the last while it wanders far from where it began. laserbrain is a
+**fixed reference** it checks against instead. There's a proof.
+[The theorem and the studies (nulls included).](https://phronesis.world/laserbrain/research)
+· [Watch it work.](https://phronesis.world/laserbrain/demo)
+
+The check is a pure function, so this SDK runs it **locally and free** — no key, no
+latency. Add a key and it also mirrors to the API for retained drift history,
+alerts and the fleet view: you pay to *see* your agents drift, not for the check.
+
+```bash
+pip install laserbrain
+```
+
+## The check (local, free)
+
+```python
+from laserbrain import Harness
+
+hz = Harness()                      # add key="lb_live_…" to also retain history
+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…"
+```
+
+`progress` is one of `advancing | stuck | circling`; `distance` is 0–10 to done.
+Reasons: `advancing`, `grounded`, `goal-drift`, `stalled`, `self-report:stuck/circling`,
+`ungrammatical`.
+
+## The act layer — close the loop
+
+Give laserbrain your step function 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))
+```
+
+## Recursion teams — styled multi-agent oversight
+
+A **recursion team** styles each role's recursion: a `deep` explorer tolerates
+displacement, a `tight` checker returns fast. laserbrain runs the team, watches the
+shared goal (the fixed reference), and injects the return per role — catching the
+**echo/agreement spiral** a self-watching group can't see.
+
+```python
+from laserbrain import Team
+
+def agent(role, history, injected):
+    # your LLM call for this role; `injected` is a return-to-ground note (or None)
+    return position, distance
+
+Team("adversarial-deliberation", goal="…").run(agent)
+# presets: deep-search · iterative-refinement · adversarial-deliberation
+```
+
+## Oversight, provenance, continuity
+
+**Human-in-the-loop.** A self-correcting return usually takes. When it doesn't —
+the agent keeps drifting past `escalate_after` steps — laserbrain escalates *that
+drift* to a human. The human doesn't watch every step; they see only what the fixed
+reference caught. Their decision overrides the auto-return.
+
+```python
+def on_escalate(v, ctx):
+    return ask_a_human(v.reason, v.advice)     # Slack, a queue, a webhook — you wire it
+                                               # returning a decision injects it as the return
+Harness().run(step, escalate_after=3, on_escalate=on_escalate)
+```
+
+**Provenance.** Every check is written to a hash-chained ledger — tamper-evident and
+verifiable offline, by anyone, no key. Editing a past verdict to hide a drift breaks
+the chain at that link.
+
+```python
+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
+```
+
+**Team continuity.** Snapshot a running team and resume it in a later session — the
+shared goal (the fixed reference) and the dialogue carry over, so the group re-grounds
+instead of starting cold.
+
+```python
+snap = team.snapshot()                         # JSON-safe; persist it anywhere
+team = Team.restore(snap)                       # keeps watching the same ground
+```
+
+## Framework adapters
+
+Already on LangGraph, CrewAI, AutoGen, or the OpenAI Agents SDK? Attach laserbrain
+without changing your loop. Because it checks a fixed reference, it needs the agent
+to *spell* its state — so each adapter takes an `extract` that maps your framework's
+state to `(goal, progress, distance)`. **No adapter imports a framework**: each
+returns a plain callable you hand to the framework's own hook, so install only the
+one you use.
+
+```python
+from laserbrain.adapters import guard, langgraph_node, crewai_step_callback, middleware
+
+# generic — wrap any step that returns dict(goal=, progress=, distance=)
+@guard
+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_edge("agent", "laserbrain")
+g.add_conditional_edges("laserbrain",
+    lambda s: "return" if s["laserbrain"].drifting else "agent")   # .advice steers the return
+
+# CrewAI — a step_callback that fires each agent step
+Agent(..., step_callback=crewai_step_callback(lambda o: (o.goal, o.status, o.dist)))
+
+# anything else (AutoGen, OpenAI Agents, a custom loop) — one check per step
+lb = middleware(extract=my_extract)
+v = lb(step_output)
+if v.drifting: reinject(v.advice)
+```
+
+Each adapter runs the check locally and free; pass `key=`/`run_id=` (or your own
+`Harness`) to also retain history.
+
+## What's proven, and what isn't
+
+The **single-agent** detector mirrors the frozen, published instrument
+(`drift.ts @ 6b483de7`) and rests on a theorem: detection is sound and complete, and
+no self-monitoring agent can be. The **multi-agent** dialogue and recursion teams are
+a prototype extension — useful, not (yet) a theorem. Whether *returning* an agent
+keeps the answer as good is [an honest open question](https://phronesis.world/laserbrain/research);
+this SDK gives you the detection and the return mechanism, and says plainly what each is.
+
+MIT · [phronesis.world/laserbrain](https://phronesis.world/laserbrain)

laserbrain-0.2.0/laserbrain/__init__.py

@@ -0,0 +1,411 @@
+"""
+laserbrain — attach the smart recursion harness to any agent loop.
+
+The check is a pure function, so it runs LOCALLY and free (the open grammar, no
+key, no latency). Give it a key and it also mirrors to the API for retained drift
+history, alerts and the fleet view — you pay to *see* your agents drift, not for
+the check. Model-agnostic: you provide the agent, laserbrain closes the loop.
+
+    from laserbrain import Harness
+    hz = Harness()                                  # local + free (add key=... to retain)
+    v = hz.check(goal="build the parser", progress="advancing", distance=6)
+    if v.drifting: ...                              # v.advice tells the agent to return
+
+    hz.run(step, on_return=lambda v, ctx: ...)      # the act layer: auto-inject the return
+
+    from laserbrain import Team
+    Team("adversarial-deliberation", goal="…").run(agent_fn)   # a styled recursion team
+
+The single-agent detector mirrors the frozen drift.ts @ 6b483de7 (the published
+instrument); the multi-agent dialogue + recursion teams are the prototype extension.
+"""
+from __future__ import annotations
+from dataclasses import dataclass
+import hashlib, json, re, urllib.request
+
+__all__ = ['Harness', 'Team', 'Verdict', 'PRESETS', 'norm', 'verify_audit']
+API_DEFAULT = 'https://laserbrain-mcp.degibug.workers.dev'
+
+
+# ── provenance: a tamper-evident, hash-chained ledger of every check ───────────
+def _canon(d):
+    return json.dumps(d, sort_keys=True, separators=(',', ':'))
+
+
+def _link(prev, body):
+    return hashlib.sha256((prev + _canon(body)).encode()).hexdigest()
+
+
+def verify_audit(chain):
+    """Independently verify an exported audit chain. Returns (ok, first_bad_index):
+       (True, -1) if intact, else (False, i) at the first tampered/broken link.
+       Free and offline — anyone can audit an agent's run without a key."""
+    prev = ''
+    for i, rec in enumerate(chain):
+        body = {k: rec[k] for k in rec if k != 'hash'}
+        if rec.get('prev') != prev or _link(prev, body) != rec.get('hash'):
+            return (False, i)
+        prev = rec['hash']
+    return (True, -1)
+
+# ── the fixed-reference primitive (frozen: drift.ts @ 6b483de7) ────────────────
+_STOP = {'the', 'a', 'an', 'to', 'of', 'and', 'or', 'for', 'in', 'on', 'at', 'is', 'it', 'this',
+         'that', 'with', 'my', 'your', 'our', 'i', 'we', 'be', 'as', 'by', 'from', 'into', 'out',
+         'up', 'so', 'then'}
+_STEM = re.compile(r"(ings?|edly|ed|ers?|es|s|tion|ment)$")
+_PROGRESS = {'advancing', 'stuck', 'circling'}
+
+
+def norm(s):
+    out = set()
+    for w in re.findall(r"[a-z0-9']+", str(s).lower()):
+        if w in _STOP:
+            continue
+        r = _STEM.sub('', w) if len(w) > 4 else w
+        if r:
+            out.add(r)
+    return out
+
+
+def _jac(a, b):
+    if not a and not b:
+        return 0.0
+    return 1 - len(a & b) / len(a | b)
+
+
+def _sim(a, b):
+    return 1 - _jac(a, b)
+
+
+def _asdist(d):
+    try:
+        return max(0, min(10, int(float(d))))
+    except Exception:
+        return 5
+
+
+def _displacement(goal, progress, distance, ground):
+    return (0.5 * _jac(norm(goal), norm(ground['goal']))
+            + 0.3 * abs(_asdist(distance) - ground['dist']) / 10
+            + 0.2 * (0 if progress == ground['progress'] else 1))
+
+
+_DRIFT = ('ungrammatical', 'goal-drift', 'stalled')
+
+
+def _isdrift(reason):
+    return reason in _DRIFT or reason.startswith('self-report')
+
+
+@dataclass
+class Verdict:
+    drifting: bool
+    reason: str
+    phi: float
+    advice: str
+
+
+class _Run:
+    """Single-agent drift state for one task run."""
+    def __init__(self):
+        self.ground = None
+        self.first_goal = set()
+        self.dist_hist = []
+        self.trace = []          # (reason, drifting)
+
+    def step(self, goal, progress, distance):
+        prev = _isdrift(self.trace[-1][0]) if self.trace else False
+
+        def emit(reason, drifting, advice, phi=0.0):
+            self.trace.append((reason, drifting))
+            return Verdict(drifting, reason, round(phi, 2), advice)
+
+        goal = str(goal or '').strip()
+        if not goal or progress not in _PROGRESS:
+            return emit('ungrammatical', True, 'You cannot spell a clear goal and a valid progress. Return to ground.')
+        d = _asdist(distance)
+        if self.ground is None:
+            self.ground = {'goal': goal, 'progress': progress, 'dist': d}
+            self.first_goal = norm(goal)
+            self.dist_hist = [d]
+            return emit('grounded', False, 'Ground state set — continue, and check each step.')
+        phi = _displacement(goal, progress, d, self.ground)
+        if progress in ('stuck', 'circling') and phi > 0.15:
+            return emit(f'self-report:{progress}', prev,
+                        f'You reported {progress} and have moved from ground. Return to your goal.' if prev
+                        else f'You reported {progress}. If it holds next step, return to ground.', phi)
+        g = norm(goal)
+        anchor = (len(g & self.first_goal) / len(g | self.first_goal)) if (g or self.first_goal) else 0.0
+        if anchor < 0.30:
+            return emit('goal-drift', True, f'Your goal no longer matches the one you started with (overlap {anchor:.2f}). Return.', phi)
+        self.dist_hist.append(d)
+        dh = self.dist_hist
+        if len(dh) > 4 and min(dh[-4:]) >= dh[-5]:
+            return emit('stalled', prev,
+                        "Distance stopped falling and you were already off ground — return." if prev
+                        else "Distance isn't falling. If it holds, return.", phi)
+        return emit('advancing', False, f'On track (Φ={phi:.2f}). Continue.', phi)
+
+
+def _post(api, key, path, body):
+    try:
+        r = urllib.request.Request(api + path, method='POST', data=json.dumps(body).encode(),
+                                   headers={'authorization': f'Bearer {key}', 'content-type': 'application/json',
+                                            'user-agent': 'laserbrain-sdk/0.2'})
+        with urllib.request.urlopen(r, timeout=8) as resp:
+            return json.load(resp)
+    except Exception:
+        return None
+
+
+def _get(api, key, path):
+    try:
+        r = urllib.request.Request(api + path, headers={'authorization': f'Bearer {key}',
+                                                        'user-agent': 'laserbrain-sdk/0.2'})
+        with urllib.request.urlopen(r, timeout=8) as resp:
+            return json.load(resp)
+    except Exception:
+        return None
+
+
+class Harness:
+    """Single-agent harness. Local + free; pass key= to also retain history via the API."""
+    def __init__(self, key=None, run_id=None, api=API_DEFAULT):
+        self.key, self.api = key, api
+        self.run_id = run_id or 'run'
+        self._run = _Run()
+        self._audit = []             # append-only, hash-chained ledger (survives reset)
+
+    def _record(self, goal, progress, distance, v):
+        prev = self._audit[-1]['hash'] if self._audit else ''
+        body = {'i': len(self._audit), 'run_id': self.run_id, 'goal': str(goal or ''),
+                'progress': progress, 'distance': _asdist(distance),
+                'reason': v.reason, 'drifting': v.drifting, 'phi': v.phi, 'prev': prev}
+        body['hash'] = _link(prev, {k: body[k] for k in body if k != 'hash'})
+        self._audit.append(body)
+
+    def check(self, goal, progress='advancing', distance=5, tokens=None, overhead=False) -> Verdict:
+        v = self._run.step(goal, progress, distance)
+        self._record(goal, progress, distance, v)
+        if self.key:  # mirror to the API for retained history / alerts (best-effort)
+            body = {'run_id': self.run_id, 'goal': goal, 'progress': progress, 'distance': distance}
+            if tokens is not None:
+                body['tokens'] = tokens
+                body['overhead'] = overhead
+            _post(self.api, self.key, '/v1/drift', body)
+        return v
+
+    def audit(self):
+        """The tamper-evident ledger of every check this harness ran. Verify it with
+           laserbrain.verify_audit(chain) — offline, no key. Append-only across reset()."""
+        return list(self._audit)
+
+    def export_audit(self, path):
+        """Write the audit chain to a JSON file a reviewer can independently verify."""
+        with open(path, 'w') as f:
+            json.dump(self._audit, f, indent=2)
+        return path
+
+    def escalate(self, verdict, streak=None, detail=None):
+        """Raise a persisting drift to the hosted human-in-the-loop queue (needs key).
+           The local on_escalate hook is the general mechanism; this is the managed
+           surface (a review queue + a decision a human makes on the dashboard).
+           Returns the escalation id to poll with resolution(), or None offline."""
+        if not self.key:
+            return None
+        body = {'run_id': self.run_id, 'reason': verdict.reason, 'advice': verdict.advice}
+        if streak is not None:
+            body['streak'] = streak
+        if detail:
+            body['detail'] = detail
+        return (_post(self.api, self.key, '/v1/escalation', body) or {}).get('esc_id')
+
+    def resolution(self, esc_id):
+        """Poll a hosted escalation for the human's decision. Returns
+           {'decision': 'return'|'allow'|'stop', 'note': …} once decided, else None."""
+        if not self.key or not esc_id:
+            return None
+        r = _get(self.api, self.key, f'/v1/escalation?id={esc_id}')
+        if r and r.get('status') == 'decided':
+            return {'decision': r.get('decision'), 'note': r.get('note')}
+        return None
+
+    def reset(self):
+        self._run = _Run()           # new task run; the audit ledger keeps accumulating
+
+    def run(self, step, max_steps=30, on_return=None, escalate_after=None, on_escalate=None):
+        """The act layer. `step(ctx)` -> dict(goal, progress, distance, tokens?, done?).
+           On drift, on_return(verdict, ctx) fires and ctx['return'] = advice so your next
+           step can steer back. If the drift *persists* for `escalate_after` steps without
+           recovering, on_escalate(verdict, ctx) fires — the human-in-the-loop hook; if it
+           returns a decision string, that overrides the auto-return (a human's call is
+           injected instead). Returns the final ctx."""
+        ctx = {'returns': 0, 'streak': 0}
+        for _ in range(max_steps):
+            s = step(ctx) or {}
+            v = self.check(s.get('goal', ''), s.get('progress', 'advancing'), s.get('distance', 5), s.get('tokens'))
+            ctx['verdict'] = v
+            if v.drifting:
+                ctx['returns'] += 1
+                ctx['streak'] += 1
+                ctx['return'] = v.advice        # the act: inject the return into the loop
+                if on_return:
+                    on_return(v, ctx)           # on_return is a notification hook, not the injection
+                if escalate_after and ctx['streak'] >= escalate_after and not ctx.get('escalated'):
+                    ctx['escalated'] = True      # a self-correcting return didn't take — get a human
+                    decision = (on_escalate or (lambda v, c: None))(v, ctx)
+                    if decision:                 # a human's decision overrides the auto-return
+                        ctx['return'] = ctx['decision'] = decision
+            else:
+                ctx['streak'] = 0                # recovered — a fresh streak can escalate again
+                ctx.pop('return', None)
+                ctx.pop('escalated', None)
+            if s.get('done') or _asdist(s.get('distance', 5)) == 0:
+                break
+        return ctx
+
+
+# ── multi-agent: dialogue + recursion teams (prototype extension) ──────────────
+_ECHO_MIN, _PROG_WIN, _GOAL_MIN = 0.25, 3, 0.30
+
+
+class _Dialogue:
+    def __init__(self, goal):
+        self.goal = norm(goal)
+        self.dist_hist, self.echo_hist, self.turns = [], [], []
+
+    def step(self, agent, position, distance, restated_goal=None):
+        pos = norm(position)
+        d = _asdist(distance)
+
+        def emit(reason, drifting, advice, echo=0.0):
+            self.turns.append({'agent': agent, 'pos': pos, 'reason': reason, 'drifting': drifting})
+            return {'reason': reason, 'drifting': drifting, 'echo': round(echo, 2), 'dist': d, 'advice': advice}
+
+        if self.goal and not self.turns and not restated_goal and not pos:
+            pass
+        if not self.goal:
+            g = norm(restated_goal or position or '')
+            if not g:
+                return emit('ungrammatical', True, 'The first turn must spell the shared goal.')
+            self.goal = g
+            self.dist_hist, self.echo_hist = [d], [0.0]
+            return emit('grounded', False, 'Shared goal set — the fixed reference for the group.')
+        if not pos:
+            return emit('ungrammatical', True, 'This agent cannot spell its position.')
+        others = [set(t['pos']) for t in self.turns[-3:] if t['agent'] != agent]
+        echo = max((_sim(pos, o) for o in others), default=0.0)
+        self.echo_hist.append(echo)
+        mean_echo = sum(self.echo_hist[-3:]) / len(self.echo_hist[-3:])
+        self.dist_hist.append(d)
+        dh = self.dist_hist
+        stalled = len(dh) > _PROG_WIN and dh[-1] >= dh[-1 - _PROG_WIN]
+        if restated_goal and _sim(norm(restated_goal), self.goal) < _GOAL_MIN:
+            return emit('topic-drift', True, 'The dialogue has left the shared goal — return to it.', echo)
+        last = self.turns[-1]['reason'] if self.turns else None
+        if stalled and mean_echo >= _ECHO_MIN:
+            return emit('echo-spiral', last == 'echo-spiral', 'The agents agree while the goal gets no closer — break the loop.', echo)
+        if stalled:
+            return emit('deliberation-stall', last == 'deliberation-stall', 'No progress toward the shared goal — return to it.', echo)
+        return emit('advancing', False, f'On track — closing on the goal (dist {d}).', echo)
+
+
+_ALL_MODES = ['ungrammatical', 'topic-drift', 'echo-spiral', 'deliberation-stall', 'goal-drift', 'stalled', 'self-report:stuck', 'self-report:circling']
+_DEPTH = {
+    'deep': {'ungrammatical', 'topic-drift', 'goal-drift'},
+    'balanced': {'ungrammatical', 'topic-drift', 'goal-drift', 'echo-spiral', 'self-report:stuck', 'self-report:circling'},
+    'tight': set(_ALL_MODES),
+}
+PRESETS = {
+    'deep-search': [
+        {'role': 'explorer', 'recurse': 'deep'},
+        {'role': 'checker', 'recurse': 'tight', 'return': 'Restate the goal and verify the last step against it.'},
+    ],
+    'iterative-refinement': [
+        {'role': 'drafter', 'recurse': 'balanced'},
+        {'role': 'critic', 'recurse': 'balanced', 'modes': ['echo-spiral', 'topic-drift', 'ungrammatical'], 'return': 'You are agreeing, not improving. Name one concrete flaw and change it.'},
+    ],
+    'adversarial-deliberation': [
+        {'role': 'advocate-a', 'recurse': 'deep'},
+        {'role': 'advocate-b', 'recurse': 'deep'},
+        {'role': 'synthesizer', 'recurse': 'tight', 'return': 'The debate is looping. State the single decision that resolves the shared goal.'},
+    ],
+}
+
+
+def _style_return(reason, role):
+    if reason in ('advancing', 'grounded'):
+        return False
+    acts = set(role['modes']) if role.get('modes') else _DEPTH.get(role['recurse'], _DEPTH['balanced'])
+    return reason in acts
+
+
+class Team:
+    """Run a styled recursion team and close the loop — detect, then inject the return."""
+    def __init__(self, preset, goal, key=None, api=API_DEFAULT):
+        if isinstance(preset, str):
+            if preset not in PRESETS:
+                raise ValueError(f'unknown preset {preset!r}; choose {list(PRESETS)}')
+            self.roles = PRESETS[preset]
+            self.name = preset
+        else:
+            self.roles, self.name = list(preset), 'custom'
+        self.goal, self.key, self.api = goal, key, api
+        self._dlg = _Dialogue(goal)
+
+    def snapshot(self):
+        """Serialize the team's shared ground + dialogue so a later session can resume
+           it instead of starting cold — subjective continuity for a group. JSON-safe."""
+        d = self._dlg
+        return {'name': self.name, 'roles': self.roles, 'goal': self.goal,
+                'dlg': {'goal': sorted(d.goal), 'dist_hist': list(d.dist_hist), 'echo_hist': list(d.echo_hist),
+                        'turns': [{'agent': t['agent'], 'pos': sorted(t['pos']),
+                                   'reason': t['reason'], 'drifting': t['drifting']} for t in d.turns]}}
+
+    @classmethod
+    def restore(cls, snap, key=None, api=API_DEFAULT):
+        """Resume a team from snapshot(): the shared goal (the fixed reference) and the
+           dialogue history carry over, so the group keeps watching the same ground."""
+        t = cls(list(snap['roles']), snap['goal'], key=key, api=api)
+        t.name = snap['name']
+        d = t._dlg
+        s = snap['dlg']
+        d.goal = set(s['goal'])
+        d.dist_hist, d.echo_hist = list(s['dist_hist']), list(s['echo_hist'])
+        d.turns = [{'agent': x['agent'], 'pos': set(x['pos']), 'reason': x['reason'],
+                    'drifting': x['drifting']} for x in s['turns']]
+        return t
+
+    def run(self, agent_fn, max_turns=12, on_return=None, verbose=True):
+        """`agent_fn(role, history, injected) -> (position, distance)`. On a role's
+           policy firing, its return advice is injected into the NEXT turn. Returns a
+           transcript list of dicts."""
+        transcript, injected = [], None
+        for turn in range(max_turns):
+            role = self.roles[turn % len(self.roles)]
+            pos, dist = agent_fn(role, transcript, injected)
+            injected = None
+            r = self._dlg.step(role['role'], pos, dist)
+            act = _style_return(r['reason'], role)
+            rec = {'turn': turn, 'role': role['role'], 'recurse': role['recurse'],
+                   'reason': r['reason'], 'echo': r['echo'], 'dist': r['dist'], 'return': act}
+            transcript.append(rec)
+            if verbose:
+                print(f"  {role['role']:12}({role['recurse']:8}): {r['reason']:18} echo={r['echo']:<4} dist={r['dist']}" + ('  ↩ RETURN' if act else ''))
+            if self.key:
+                _post(self.api, self.key, '/v1/dialogue',
+                      {'conv_id': self.name, 'agent': role['role'], 'position': pos, 'distance': dist,
+                       'team': self.name, 'role': role['role'], **({'goal': self.goal} if turn == 0 else {})})
+            if act:
+                injected = role.get('return', 'Return to the shared goal and take the step that most directly resolves it.')
+                (on_return or (lambda a, c: None))(injected, rec)
+            if _asdist(dist) == 0:
+                if verbose:
+                    print('  ✓ resolved.')
+                break
+        return transcript
+
+
+# framework adapters (LangGraph, CrewAI, generic) — imported last to avoid a cycle
+from .adapters import guard, langgraph_node, crewai_step_callback, middleware  # noqa: E402
+__all__ += ['guard', 'langgraph_node', 'crewai_step_callback', 'middleware']

laserbrain-0.2.0/laserbrain/adapters.py

@@ -0,0 +1,140 @@
+"""
+laserbrain.adapters — attach the harness to the popular agent frameworks.
+
+laserbrain checks a fixed reference, so it needs the agent to *spell* its state.
+Frameworks don't hand you that, so every adapter takes an `extract` you provide:
+
+    extract(x) -> (goal:str, progress:'advancing'|'stuck'|'circling', distance:0..10)
+
+Nothing here imports a framework. Each adapter returns a plain callable you pass
+to the framework's own hook — a graph node, a step_callback, a per-step check — so
+the frameworks stay optional: install only the one you use. The check still runs
+locally and free; pass key=/run_id= (or your own Harness) to also retain history.
+
+    from laserbrain.adapters import guard, langgraph_node, crewai_step_callback
+
+    @guard                                  # step returns dict(goal=, progress=, distance=)
+    def step(state): ...
+
+    g.add_node('laserbrain', langgraph_node(extract=my_extract))     # LangGraph
+    Agent(..., step_callback=crewai_step_callback(my_extract))        # CrewAI
+    v = middleware(my_extract)(obj)          # anything else: one call per step
+"""
+from __future__ import annotations
+from . import Harness, Verdict
+
+__all__ = ['guard', 'langgraph_node', 'crewai_step_callback', 'middleware', 'dict_extract']
+
+STATE_KEY = 'laserbrain'
+
+
+def _harness(harness, key, run_id):
+    return harness if harness is not None else Harness(key=key, run_id=run_id or 'run')
+
+
+def dict_extract(x):
+    """Default extractor: read (goal, progress, distance) from a dict or an object
+       carrying those keys/attributes."""
+    get = x.get if isinstance(x, dict) else (lambda k, d=None: getattr(x, k, d))
+    return get('goal', ''), get('progress', 'advancing'), get('distance', 5)
+
+
+# ── 1. generic decorator — the framework-agnostic core ─────────────────────────
+def guard(fn=None, *, extract=None, harness=None, key=None, run_id=None, on_return=None):
+    """Wrap any agent step. After it runs, laserbrain checks the result; the Verdict
+       is attached (result['laserbrain'] when the result is a dict), and on drift
+       on_return(verdict, result) is called if given.
+
+           @guard                                    # result is dict(goal, progress, distance)
+           def step(state): ...
+
+           @guard(extract=lambda out: (out.goal, out.status, out.dist))
+           def step(state): ...
+
+       The wrapped function gains a `.harness` attribute for reset()/history."""
+    hz = _harness(harness, key, run_id)
+    ex = extract or dict_extract
+
+    def wrap(f):
+        def wrapped(*a, **k):
+            out = f(*a, **k)
+            g, p, d = ex(out)
+            v = hz.check(g, p, d)
+            if isinstance(out, dict):
+                out[STATE_KEY] = v
+            if v.drifting and on_return:
+                on_return(v, out)
+            return out
+        wrapped.harness = hz
+        return wrapped
+
+    return wrap(fn) if callable(fn) else wrap
+
+
+# ── 2. LangGraph — a node that writes the Verdict into graph state ─────────────
+def langgraph_node(extract=None, harness=None, key=None, run_id=None, state_key=STATE_KEY):
+    """Return a LangGraph node: state -> {state_key: Verdict}. Add it after your
+       agent node and branch on the verdict with a conditional edge.
+
+           g.add_node('laserbrain', langgraph_node(extract=my_extract))
+           g.add_edge('agent', 'laserbrain')
+           g.add_conditional_edges('laserbrain',
+               lambda s: 'return' if s['laserbrain'].drifting else 'agent')
+
+       On drift, state['laserbrain'].advice is the return-to-ground message to feed
+       back into your agent node (your 'return' branch)."""
+    hz = _harness(harness, key, run_id)
+    ex = extract or dict_extract
+
+    def node(state):
+        g, p, d = ex(state)
+        return {state_key: hz.check(g, p, d)}
+
+    node.harness = hz
+    return node
+
+
+# ── 3. CrewAI — a step_callback that fires each agent step ─────────────────────
+def crewai_step_callback(extract, harness=None, key=None, run_id=None, on_return=None):
+    """Return a callback for CrewAI's step_callback=. It fires on each agent step;
+       extract(step_output) -> (goal, progress, distance). On drift it calls
+       on_return(verdict, step_output) — default prints the return advice.
+
+           Agent(..., step_callback=crewai_step_callback(my_extract))
+           Crew(...,  step_callback=crewai_step_callback(my_extract))"""
+    hz = _harness(harness, key, run_id)
+    on_return = on_return or (lambda v, o: print(f'[laserbrain] ↩ {v.reason}: {v.advice}'))
+
+    def cb(step_output):
+        try:
+            g, p, d = extract(step_output)
+        except Exception:
+            return None
+        v = hz.check(g, p, d)
+        if v.drifting:
+            on_return(v, step_output)
+        return v
+
+    cb.harness = hz
+    return cb
+
+
+# ── 4. generic middleware — one call per step, for anything else ───────────────
+def middleware(extract=None, harness=None, key=None, run_id=None):
+    """Return a per-step checker `check(x) -> Verdict` for any framework that gives
+       you a hook (AutoGen reply functions, the OpenAI Agents SDK, a custom loop).
+       Call it wherever a step completes; branch on verdict.drifting and feed
+       verdict.advice back to steer the agent.
+
+           lb = middleware(extract=my_extract)
+           v = lb(step_output)
+           if v.drifting: reinject(v.advice)"""
+    hz = _harness(harness, key, run_id)
+    ex = extract or dict_extract
+
+    def check(x):
+        g, p, d = ex(x)
+        return hz.check(g, p, d)
+
+    check.harness = hz
+    return check

laserbrain-0.2.0/laserbrain.egg-info/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: laserbrain
+Version: 0.2.0
+Summary: Attach the smart recursion harness to any agent loop — a provably-correct, external check for when an AI agent (or team) has drifted from its goal.
+Author: phronesis
+License: MIT
+Project-URL: Homepage, https://phronesis.world/laserbrain
+Project-URL: Research, https://phronesis.world/laserbrain/research
+Project-URL: Demo, https://phronesis.world/laserbrain/demo
+Keywords: ai,agents,oversight,drift,mcp,llm,multi-agent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# laserbrain
+
+Attach the **smart recursion harness** to any agent loop — a provably-correct,
+external check for when an AI agent (or a team of agents) has drifted from its goal.
+
+An agent watching only itself provably can't catch its own drift: each step looks
+fine next to the last while it wanders far from where it began. laserbrain is a
+**fixed reference** it checks against instead. There's a proof.
+[The theorem and the studies (nulls included).](https://phronesis.world/laserbrain/research)
+· [Watch it work.](https://phronesis.world/laserbrain/demo)
+
+The check is a pure function, so this SDK runs it **locally and free** — no key, no
+latency. Add a key and it also mirrors to the API for retained drift history,
+alerts and the fleet view: you pay to *see* your agents drift, not for the check.
+
+```bash
+pip install laserbrain
+```
+
+## The check (local, free)
+
+```python
+from laserbrain import Harness
+
+hz = Harness()                      # add key="lb_live_…" to also retain history
+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…"
+```
+
+`progress` is one of `advancing | stuck | circling`; `distance` is 0–10 to done.
+Reasons: `advancing`, `grounded`, `goal-drift`, `stalled`, `self-report:stuck/circling`,
+`ungrammatical`.
+
+## The act layer — close the loop
+
+Give laserbrain your step function 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))
+```
+
+## Recursion teams — styled multi-agent oversight
+
+A **recursion team** styles each role's recursion: a `deep` explorer tolerates
+displacement, a `tight` checker returns fast. laserbrain runs the team, watches the
+shared goal (the fixed reference), and injects the return per role — catching the
+**echo/agreement spiral** a self-watching group can't see.
+
+```python
+from laserbrain import Team
+
+def agent(role, history, injected):
+    # your LLM call for this role; `injected` is a return-to-ground note (or None)
+    return position, distance
+
+Team("adversarial-deliberation", goal="…").run(agent)
+# presets: deep-search · iterative-refinement · adversarial-deliberation
+```
+
+## Oversight, provenance, continuity
+
+**Human-in-the-loop.** A self-correcting return usually takes. When it doesn't —
+the agent keeps drifting past `escalate_after` steps — laserbrain escalates *that
+drift* to a human. The human doesn't watch every step; they see only what the fixed
+reference caught. Their decision overrides the auto-return.
+
+```python
+def on_escalate(v, ctx):
+    return ask_a_human(v.reason, v.advice)     # Slack, a queue, a webhook — you wire it
+                                               # returning a decision injects it as the return
+Harness().run(step, escalate_after=3, on_escalate=on_escalate)
+```
+
+**Provenance.** Every check is written to a hash-chained ledger — tamper-evident and
+verifiable offline, by anyone, no key. Editing a past verdict to hide a drift breaks
+the chain at that link.
+
+```python
+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
+```
+
+**Team continuity.** Snapshot a running team and resume it in a later session — the
+shared goal (the fixed reference) and the dialogue carry over, so the group re-grounds
+instead of starting cold.
+
+```python
+snap = team.snapshot()                         # JSON-safe; persist it anywhere
+team = Team.restore(snap)                       # keeps watching the same ground
+```
+
+## Framework adapters
+
+Already on LangGraph, CrewAI, AutoGen, or the OpenAI Agents SDK? Attach laserbrain
+without changing your loop. Because it checks a fixed reference, it needs the agent
+to *spell* its state — so each adapter takes an `extract` that maps your framework's
+state to `(goal, progress, distance)`. **No adapter imports a framework**: each
+returns a plain callable you hand to the framework's own hook, so install only the
+one you use.
+
+```python
+from laserbrain.adapters import guard, langgraph_node, crewai_step_callback, middleware
+
+# generic — wrap any step that returns dict(goal=, progress=, distance=)
+@guard
+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_edge("agent", "laserbrain")
+g.add_conditional_edges("laserbrain",
+    lambda s: "return" if s["laserbrain"].drifting else "agent")   # .advice steers the return
+
+# CrewAI — a step_callback that fires each agent step
+Agent(..., step_callback=crewai_step_callback(lambda o: (o.goal, o.status, o.dist)))
+
+# anything else (AutoGen, OpenAI Agents, a custom loop) — one check per step
+lb = middleware(extract=my_extract)
+v = lb(step_output)
+if v.drifting: reinject(v.advice)
+```
+
+Each adapter runs the check locally and free; pass `key=`/`run_id=` (or your own
+`Harness`) to also retain history.
+
+## What's proven, and what isn't
+
+The **single-agent** detector mirrors the frozen, published instrument
+(`drift.ts @ 6b483de7`) and rests on a theorem: detection is sound and complete, and
+no self-monitoring agent can be. The **multi-agent** dialogue and recursion teams are
+a prototype extension — useful, not (yet) a theorem. Whether *returning* an agent
+keeps the answer as good is [an honest open question](https://phronesis.world/laserbrain/research);
+this SDK gives you the detection and the return mechanism, and says plainly what each is.
+
+MIT · [phronesis.world/laserbrain](https://phronesis.world/laserbrain)

laserbrain-0.2.0/laserbrain.egg-info/SOURCES.txt

@@ -0,0 +1,8 @@
+README.md
+pyproject.toml
+laserbrain/__init__.py
+laserbrain/adapters.py
+laserbrain.egg-info/PKG-INFO
+laserbrain.egg-info/SOURCES.txt
+laserbrain.egg-info/dependency_links.txt
+laserbrain.egg-info/top_level.txt

laserbrain-0.2.0/laserbrain.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

laserbrain-0.2.0/laserbrain.egg-info/top_level.txt

@@ -0,0 +1 @@
+laserbrain

laserbrain-0.2.0/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "laserbrain"
+version = "0.2.0"
+description = "Attach the smart recursion harness to any agent loop — a provably-correct, external check for when an AI agent (or team) has drifted from its goal."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "phronesis" }]
+keywords = ["ai", "agents", "oversight", "drift", "mcp", "llm", "multi-agent"]
+dependencies = []
+
+[project.urls]
+Homepage = "https://phronesis.world/laserbrain"
+Research = "https://phronesis.world/laserbrain/research"
+Demo = "https://phronesis.world/laserbrain/demo"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["laserbrain*"]

laserbrain-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+