superlocalmemory 4.1.13 → 4.1.14

package/src/superlocalmemory/loops/__init__.py

@@ -1,58 +0,0 @@
-"""SuperLocalMemory bounded loops.
-
-Agent loops that stop when an independent gate passes — not when the agent
-says it is done — with the run's history persisted in SLM's durable memory.
-
-Public API::
-
-    from superlocalmemory.loops import (
-        Bounds, Rung, Status, Verdict, LapResult, Outcome,
-        run_bounded_loop, InMemoryLedger, SLMMemoryLedger, open_engine_store,
-    )
-"""
-
-from __future__ import annotations
-
-from superlocalmemory.loops.engine import run_bounded_loop
-from superlocalmemory.loops.ledger import (
-    InMemoryLedger,
-    LedgerEntry,
-    LedgerStore,
-    SLMMemoryLedger,
-    engine_backed_ledger,
-    open_engine_store,
-    pool_backed_ledger,
-)
-from superlocalmemory.loops.models import (
-    Bounds,
-    LapResult,
-    Outcome,
-    Rung,
-    Status,
-    Verdict,
-)
-from superlocalmemory.loops.rules import (
-    no_progress,
-    rung_requires_approval,
-    stop_condition_met,
-)
-
-__all__ = [
-    "Bounds",
-    "Rung",
-    "Status",
-    "Verdict",
-    "LapResult",
-    "Outcome",
-    "run_bounded_loop",
-    "LedgerEntry",
-    "LedgerStore",
-    "InMemoryLedger",
-    "SLMMemoryLedger",
-    "engine_backed_ledger",
-    "pool_backed_ledger",
-    "open_engine_store",
-    "no_progress",
-    "rung_requires_approval",
-    "stop_condition_met",
-]

package/src/superlocalmemory/loops/budget.py

@@ -1,58 +0,0 @@
-"""Cumulative budget accounting for a bounded-loop run.
-
-The meter tracks laps, tokens, and wall-clock time and reports when any bound
-in effect has been exceeded. It is intentionally tiny and side-effect-free
-apart from its own internal counters, and the clock is injected so tests are
-deterministic.
-"""
-
-from __future__ import annotations
-
-from typing import Callable
-
-from superlocalmemory.loops.models import Bounds
-
-
-class BudgetMeter:
-    """Accumulate spend across laps and answer "have we gone over?".
-
-    ``now`` is a zero-argument callable returning monotonic-ish seconds
-    (``time.monotonic`` in production, a fake in tests). The start time is
-    captured at construction so wall-clock enforcement needs no globals.
-    """
-
-    def __init__(self, now: Callable[[], float]) -> None:
-        self._now = now
-        self._start = now()
-        self._tokens = 0
-
-    def spend(self, tokens: int) -> None:
-        """Record token spend for a completed lap (negative values ignored)."""
-        if tokens > 0:
-            self._tokens += tokens
-
-    def exceeded(self, lap: int, bounds: Bounds) -> tuple[bool, str]:
-        """Return ``(tripped, reason)`` for the bounds checked before a lap runs.
-
-        Checked in priority order: iteration cap, token budget, wall-clock.
-        ``lap`` is the 1-based number of the lap about to run, so exceeding
-        ``max_iterations`` is reported when the (max+1)-th lap is attempted.
-        """
-        if lap > bounds.max_iterations:
-            return True, "max-iterations"
-        # >= so a budget of N never permits an (N+1)-th lap's worth of spend:
-        # once cumulative tokens reach the ceiling, the next lap is refused.
-        if bounds.max_tokens is not None and self._tokens >= bounds.max_tokens:
-            return True, "token-budget"
-        if bounds.max_wallclock_s is not None:
-            elapsed = self._now() - self._start
-            if elapsed > bounds.max_wallclock_s:
-                return True, "wallclock"
-        return False, ""
-
-    def snapshot(self) -> dict:
-        """Point-in-time spend, suitable for a ledger entry."""
-        return {
-            "tokens": self._tokens,
-            "wallclock_s": round(self._now() - self._start, 3),
-        }

package/src/superlocalmemory/loops/engine.py

@@ -1,174 +0,0 @@
-"""The bounded-loop orchestrator.
-
-``run_bounded_loop`` executes a loop for a single goal under a fixed set of
-:class:`Bounds`. Its one non-negotiable invariant: **the independent gate
-decides when the loop is finished — never the agent.** A runner's
-``agent_claimed_done`` flag is written to the ledger for audit and is never
-read when deciding to terminate.
-
-Each lap, in strict order:
-
-1. Poll the kill switch (highest priority — checked before any work).
-2. Check the budget bounds (iteration cap, tokens, wall-clock).
-3. Run the agent's proposer for one lap.
-4. Accumulate token spend.
-5. Ask the *independent* gate for a verdict.
-6. Decide: a passing gate (plus any required approval) ends the run; an
-   exhausted no-progress window halts it; otherwise continue.
-
-Runner and gate are plain callables taking the 1-based lap number, so this
-engine carries no subprocess, sandbox, or framework machinery — SLM loops
-converge on a checkable memory/verification condition, and heavier isolation
-belongs to the standalone bounded-loops engine, not here.
-"""
-
-from __future__ import annotations
-
-import os
-import time
-import uuid
-from datetime import datetime, timezone
-from typing import Callable, Optional
-
-from superlocalmemory.loops.budget import BudgetMeter
-from superlocalmemory.loops.ledger import InMemoryLedger, LedgerEntry, LedgerStore
-from superlocalmemory.loops.models import (
-    Bounds,
-    LapResult,
-    Outcome,
-    Rung,
-    Status,
-    Verdict,
-)
-from superlocalmemory.loops.rules import (
-    no_progress,
-    rung_requires_approval,
-    stop_condition_met,
-)
-
-RunnerFn = Callable[[int], LapResult]
-GateFn = Callable[[int], Verdict]
-ApproverFn = Callable[[Verdict], bool]
-KillSwitchFn = Callable[[], bool]
-ClockFn = Callable[[], str]
-
-_KILL_ENV = "SLM_LOOP_KILL"
-
-
-def _utc_now_iso() -> str:
-    return datetime.now(timezone.utc).isoformat()
-
-
-def _env_killed() -> bool:
-    return bool(os.environ.get(_KILL_ENV))
-
-
-def run_bounded_loop(
-    name: str,
-    *,
-    bounds: Bounds,
-    runner: RunnerFn,
-    gate: GateFn,
-    rung: Rung = Rung.L1,
-    ledger: Optional[LedgerStore] = None,
-    approver: Optional[ApproverFn] = None,
-    killswitch: Optional[KillSwitchFn] = None,
-    clock: Optional[ClockFn] = None,
-    monotonic: Optional[Callable[[], float]] = None,
-    run_id: Optional[str] = None,
-) -> Outcome:
-    """Run one bounded loop and return its :class:`Outcome`.
-
-    Only ``name``, ``bounds``, ``runner`` and ``gate`` are required. Every
-    other dependency is injected for determinism in tests; sensible defaults
-    (UTC clock, monotonic timer, env-var kill switch, in-memory ledger) apply
-    otherwise.
-    """
-    run_id = run_id or f"{name}-{uuid.uuid4().hex[:8]}"
-    ledger = ledger if ledger is not None else InMemoryLedger()
-    clock = clock or _utc_now_iso
-    monotonic = monotonic or time.monotonic
-    killswitch = killswitch or _env_killed
-    budget = BudgetMeter(monotonic)
-
-    lap_changes: list[bool] = []
-    lap = 0
-
-    def emit(decision: str, verdict: Verdict, result: LapResult | None = None) -> None:
-        ledger.record(
-            LedgerEntry(
-                run_id=run_id,
-                name=name,
-                lap=lap,
-                ts=clock(),
-                decision=decision,
-                passed=verdict.passed,
-                detail=verdict.detail,
-                # The agent's own claim is recorded for audit only — never used
-                # to terminate (see the loop invariant). Log is capped so a
-                # verbose runner can't bloat the ledger row.
-                agent_claimed_done=bool(result.agent_claimed_done) if result else False,
-                runner_log=(result.log or "")[:2000] if result else "",
-                budget=budget.snapshot(),
-            )
-        )
-
-    while True:
-        lap += 1
-
-        # 1. Kill switch — before any work (so laps reports completed laps).
-        if killswitch():
-            emit("killed", Verdict(False, "kill switch tripped"))
-            return Outcome(Status.KILLED, "killed", lap - 1, run_id)
-
-        # 2. Budget bounds — before running the agent.
-        tripped, why = budget.exceeded(lap, bounds)
-        if tripped:
-            emit("halt", Verdict(False, why))
-            return Outcome(Status.HALT, why, lap - 1, run_id)
-
-        # 3. Run the proposer for one lap.
-        try:
-            result = runner(lap)
-        except Exception as exc:  # runner failure is a terminal ERROR
-            detail = f"runner error: {type(exc).__name__}: {exc}"
-            emit("error", Verdict(False, detail))
-            return Outcome(Status.ERROR, detail, lap, run_id)
-
-        # 4. Accumulate spend.
-        budget.spend(result.tokens)
-        lap_changes.append(result.changed)
-
-        # 4b. The budget is a HARD ceiling and takes precedence over the gate.
-        # Token spend and elapsed wall-clock are only knowable AFTER the lap
-        # runs, so re-check here: an overshooting lap must HALT even when its own
-        # gate would pass. ``lap`` (not lap+1) keeps the iteration cap from
-        # tripping while we are still within the allowed iteration count.
-        tripped, why = budget.exceeded(lap, bounds)
-        if tripped:
-            emit("halt", Verdict(False, why), result)
-            return Outcome(Status.HALT, why, lap, run_id)
-
-        # 5. Independent gate — agent's own claim is never consulted here.
-        try:
-            verdict = gate(lap)
-        except Exception as exc:
-            detail = f"gate error: {type(exc).__name__}: {exc}"
-            emit("error", Verdict(False, detail), result)
-            return Outcome(Status.ERROR, detail, lap, run_id)
-
-        # 6. Decide.
-        if stop_condition_met(verdict):
-            if rung_requires_approval(rung, bounds):
-                granted = bool(approver(verdict)) if approver is not None else False
-                if not granted:
-                    emit("pause", verdict, result)
-                    return Outcome(Status.PAUSE, "awaiting-approval", lap, run_id)
-            emit("done", verdict, result)
-            return Outcome(Status.DONE, "gate-passed", lap, run_id)
-
-        if no_progress(lap_changes, bounds.no_progress_window):
-            emit("halt", Verdict(False, "no-progress"), result)
-            return Outcome(Status.HALT, "no-progress", lap, run_id)
-
-        emit("continue", verdict, result)

package/src/superlocalmemory/loops/ledger.py

@@ -1,298 +0,0 @@
-"""Durable, queryable ledger for bounded-loop runs.
-
-Every lap produces one append-only :class:`LedgerEntry`. A ledger persists
-those entries so a run can be inspected, resumed, and audited after the fact.
-
-Two implementations ship:
-
-* :class:`InMemoryLedger` — a dict-backed store used by tests and as a safe
-  fallback when no SLM data root is available.
-* :class:`SLMMemoryLedger` — the real backend. It writes each lap through a
-  SuperLocalMemory engine so the ledger *is* memory: queryable via ``slm
-  recall``, visible in the dashboard, and resumable across sessions. This is
-  what makes SLM's take on bounded loops distinct — the loop's history lives
-  in the same durable store as everything else the agent remembers.
-
-The engine-backed store mirrors the exact profile-scoped SQL contract the
-shipped framework adapters already rely on, so it stays valid as the engine
-evolves.
-"""
-
-from __future__ import annotations
-
-import json
-from dataclasses import asdict, dataclass, field
-from pathlib import Path
-from typing import Any, Protocol, runtime_checkable
-
-LEDGER_TAG = "slm-loop"
-_LEDGER_IMPORTANCE = 2  # below ordinary user memories so laps never crowd recall
-_SESSION_PREFIX = "loop:"
-
-
-@dataclass(frozen=True)
-class LedgerEntry:
-    """One immutable row recording what happened on a single lap."""
-
-    run_id: str
-    name: str
-    lap: int
-    ts: str
-    decision: str  # continue | done | halt | pause | killed | error
-    passed: bool
-    detail: str
-    # The runner's own claim (audit-only; never terminates the loop) + its log.
-    agent_claimed_done: bool = False
-    runner_log: str = ""
-    budget: dict[str, Any] = field(default_factory=dict)
-
-    def to_json(self) -> str:
-        return json.dumps(asdict(self), ensure_ascii=False, separators=(",", ":"))
-
-    @classmethod
-    def from_json(cls, text: str) -> "LedgerEntry | None":
-        try:
-            data = json.loads(text)
-        except (TypeError, json.JSONDecodeError):
-            return None
-        if not isinstance(data, dict) or "run_id" not in data or "lap" not in data:
-            return None
-        return cls(
-            run_id=str(data.get("run_id", "")),
-            name=str(data.get("name", "")),
-            lap=int(data.get("lap", 0)),
-            ts=str(data.get("ts", "")),
-            decision=str(data.get("decision", "")),
-            passed=bool(data.get("passed", False)),
-            detail=str(data.get("detail", "")),
-            agent_claimed_done=bool(data.get("agent_claimed_done", False)),
-            runner_log=str(data.get("runner_log", "")),
-            budget=data.get("budget") if isinstance(data.get("budget"), dict) else {},
-        )
-
-
-@runtime_checkable
-class LedgerStore(Protocol):
-    """Append-only audit trail keyed by run."""
-
-    def record(self, entry: LedgerEntry) -> None: ...
-    def laps(self, run_id: str) -> list[LedgerEntry]: ...
-    def runs(self, name: str) -> list[str]: ...
-
-
-class InMemoryLedger:
-    """Process-local ledger. Never raises; ideal for tests and offline demos."""
-
-    def __init__(self) -> None:
-        self._by_run: dict[str, list[LedgerEntry]] = {}
-
-    def record(self, entry: LedgerEntry) -> None:
-        self._by_run.setdefault(entry.run_id, []).append(entry)
-
-    def laps(self, run_id: str) -> list[LedgerEntry]:
-        return list(self._by_run.get(run_id, ()))
-
-    def runs(self, name: str) -> list[str]:
-        seen: list[str] = []
-        for run_id, entries in self._by_run.items():
-            if entries and entries[0].name == name and run_id not in seen:
-                seen.append(run_id)
-        return seen
-
-
-class SLMMemoryLedger:
-    """Ledger backed by a SuperLocalMemory engine store.
-
-    ``store`` is any object exposing ``add(content, *, session_id, metadata)``,
-    ``list_session(session_id)`` and ``list_prefix(prefix)`` — the small
-    contract :func:`open_engine_store` provides. Injecting it keeps this class
-    free of engine-construction concerns and trivially testable with a fake.
-    """
-
-    def __init__(self, store: Any) -> None:
-        self._store = store
-
-    @staticmethod
-    def _session_id(run_id: str) -> str:
-        return f"{_SESSION_PREFIX}{run_id}"
-
-    def record(self, entry: LedgerEntry) -> None:
-        self._store.add(
-            entry.to_json(),
-            session_id=self._session_id(entry.run_id),
-            metadata={
-                "integration": "slm-loop",
-                "loop_name": entry.name,
-                "loop_run_id": entry.run_id,
-                "loop_lap": entry.lap,
-                "loop_decision": entry.decision,
-                "tags": [LEDGER_TAG, f"loop:{entry.name}"],
-                "importance": _LEDGER_IMPORTANCE,
-                "project_name": "slm-loop",
-            },
-        )
-
-    def laps(self, run_id: str) -> list[LedgerEntry]:
-        rows = self._store.list_session(self._session_id(run_id))
-        entries = [LedgerEntry.from_json(r.get("content", "")) for r in rows]
-        return [e for e in entries if e is not None]
-
-    def runs(self, name: str) -> list[str]:
-        """Run ids for ``name``, newest run first.
-
-        ``list_prefix`` returns rows created_at DESC, so the first time a run's
-        id is seen it is its most-recent lap; ``slm loop history`` therefore
-        lists the most recent runs first.
-        """
-        rows = self._store.list_prefix(_SESSION_PREFIX)
-        ordered: list[str] = []
-        for row in rows:
-            entry = LedgerEntry.from_json(row.get("content", ""))
-            if entry is not None and entry.name == name and entry.run_id not in ordered:
-                ordered.append(entry.run_id)
-        return ordered
-
-
-class _EngineLedgerStore:
-    """Minimal profile-scoped store over a SuperLocalMemory engine.
-
-    Uses the engine's non-blocking write-through path when available and
-    direct, escaped, profile-scoped reads.  The ``store`` fallback preserves
-    compatibility with lightweight adapter/test engines that predate
-    ``store_fast``.
-    """
-
-    def __init__(self, engine: Any, *, owns_engine: bool = True) -> None:
-        self._engine = engine
-        # When False, this store does NOT own the engine's lifecycle (the
-        # caller — e.g. the MCP daemon — keeps it), so close() must not tear
-        # down a shared engine. open_engine_store() passes True (it built the
-        # engine); engine_backed_ledger() passes False (daemon-owned engine).
-        self._owns_engine = owns_engine
-
-    def add(self, content: str, *, session_id: str, metadata: dict) -> None:
-        # A loop ledger needs the durable parent row and immediate lexical
-        # recall, not synchronous embeddings/entity/graph enrichment. Loading
-        # the heavyweight embedding worker for every bounded-loop lap can stall
-        # the loop for the full worker timeout and consume ~1 GB for metadata.
-        # The write-through path persists the same session-scoped content in
-        # milliseconds; ordinary background enrichment can still promote it.
-        fast_metadata = {**metadata, "session_id": session_id}
-        store_fast = getattr(self._engine, "store_fast", None)
-        if callable(store_fast):
-            store_fast(
-                content,
-                metadata=fast_metadata,
-                index_external=False,
-            )
-            return
-
-        self._engine.store(
-            content,
-            session_id=session_id,
-            metadata=metadata,
-        )
-
-    def list_session(self, session_id: str) -> list[dict]:
-        # Cap the read: a bounded-loop run is capped at max_iterations laps, so
-        # a legitimate run is small; the LIMIT stops a pathologically long
-        # session_id from forcing an unbounded materialization on every
-        # `slm loop show` / history lookup.
-        rows = self._engine.db.execute(
-            "SELECT content, created_at FROM memories "
-            "WHERE profile_id=? AND session_id=? "
-            "ORDER BY created_at ASC, rowid ASC LIMIT 5000",
-            (self._engine.profile_id, session_id),
-        )
-        return [dict(row) for row in rows]
-
-    def list_prefix(self, prefix: str) -> list[dict]:
-        escaped = prefix.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")
-        # Cap the scan so a long-lived, high-volume ledger can't force an
-        # unbounded read on `slm loop history`.
-        rows = self._engine.db.execute(
-            "SELECT content, created_at FROM memories "
-            "WHERE profile_id=? AND session_id LIKE ? ESCAPE '\\' "
-            "ORDER BY created_at DESC, rowid DESC LIMIT 5000",
-            (self._engine.profile_id, escaped + "%"),
-        )
-        return [dict(row) for row in rows]
-
-    def close(self) -> None:
-        if self._owns_engine:
-            self._engine.close()
-
-
-class _PoolLedgerStore(_EngineLedgerStore):
-    """Write through the owned daemon/worker; read through the LIGHT engine.
-
-    MCP intentionally keeps a LIGHT engine in-process.  That engine owns a
-    read-only database view but refuses ``store``/``store_fast``.  The pool is
-    the admitted writer and shares the same canonical store, so loop laps stay
-    immediately queryable without turning every MCP process into a heavy
-    writer.
-    """
-
-    def __init__(self, pool: Any, reader_engine: Any) -> None:
-        super().__init__(reader_engine, owns_engine=False)
-        self._pool = pool
-
-    def add(self, content: str, *, session_id: str, metadata: dict) -> None:
-        result = self._pool.store(
-            content,
-            metadata={
-                **metadata,
-                "session_id": session_id,
-                "profile_id": self._engine.profile_id,
-            },
-        )
-        accepted = bool(result.get("ok") or result.get("success"))
-        if not accepted:
-            raise RuntimeError(
-                result.get("error", "owned SLM writer rejected loop ledger entry")
-            )
-
-
-def engine_backed_ledger(engine: Any) -> SLMMemoryLedger:
-    """Build an SLM-backed ledger over an ALREADY-OPEN engine.
-
-    Unlike :func:`open_engine_store`, this neither creates nor owns the engine —
-    the caller (e.g. the MCP daemon, which keeps one long-lived engine per
-    profile) retains full ownership and lifecycle. The returned ledger never
-    closes the engine, so it is safe to build one per tool call. The engine's
-    per-call, WAL-mode connection model makes the ledger's reads/writes safe
-    from a worker thread.
-    """
-    return SLMMemoryLedger(_EngineLedgerStore(engine, owns_engine=False))
-
-
-def pool_backed_ledger(pool: Any, reader_engine: Any) -> SLMMemoryLedger:
-    """Build an MCP-safe ledger: admitted pool writes, LIGHT engine reads."""
-    return SLMMemoryLedger(_PoolLedgerStore(pool, reader_engine))
-
-
-def open_engine_store(db_path: str | Path) -> _EngineLedgerStore:
-    """Build an engine-backed ledger store rooted at ``db_path``.
-
-    Raises ``ImportError`` with an install hint if the SLM runtime is missing.
-    """
-    from dataclasses import replace
-
-    try:
-        from superlocalmemory.core.config import SLMConfig
-        from superlocalmemory.core.engine import MemoryEngine
-        from superlocalmemory.storage.models import Mode
-    except ImportError as exc:  # pragma: no cover - defensive
-        raise ImportError(
-            "SuperLocalMemory runtime is required for the SLM-backed loop "
-            "ledger. Install it with: python -m pip install superlocalmemory."
-        ) from exc
-
-    path = Path(db_path).expanduser().resolve()
-    config = SLMConfig.for_mode(Mode.A, base_dir=path.parent)
-    config.db_path = path
-    config.forgetting = replace(config.forgetting, enabled=False)
-    config.retrieval.use_cross_encoder = False
-    engine = MemoryEngine(config)
-    engine.initialize()
-    return _EngineLedgerStore(engine)