superlocalmemory 4.1.13 → 4.1.15

package/src/superlocalmemory/evolution/llm_dispatch.py

@@ -1,559 +0,0 @@
-# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
-# Licensed under AGPL-3.0-or-later - see LICENSE file
-# Part of SuperLocalMemory v3.4.22 — LLD-11 §Dispatch
-
-"""Central LLM dispatch for the skill-evolution subsystem.
-
-Enforces MASTER-PLAN D2 (no top-tier "O-family" Claude models, no
-``gpt-4-turbo``) and LLD-00 §5 (every LLM-bound prompt passes through
-``redact_secrets(aggression='high')`` FIRST).
-
-Every evolution LLM call funnels through :func:`_dispatch_llm`. Writes an
-audit row to ``evolution_llm_cost_log`` after the dispatch succeeds — the
-row stores only the *redacted* prompt length and the model, never the
-raw prompt, so no canary can leak via the cost log.
-
-SB-2/SB-3/SB-4 fix cluster (v3.4.22 Stage 8):
-  * All backend entry points (claude CLI, ollama, Anthropic/OpenAI API)
-    live HERE, not in ``skill_evolver``. ``SkillEvolver._llm_call``
-    delegates to ``_dispatch_llm`` so the validate → redact → log
-    invariants can never be bypassed.
-  * The claude CLI backend routes through
-    ``core.security_primitives.run_subprocess_safe`` — no bare
-    ``subprocess.run`` in evolution code (SB-4).
-
-Author: Varun Pratap Bhardwaj / Qualixar
-"""
-
-from __future__ import annotations
-
-import atexit
-import logging
-import os
-import sqlite3
-import tempfile
-import threading
-from datetime import datetime, timezone
-from pathlib import Path
-from typing import Callable, Optional
-
-from superlocalmemory.core.security_primitives import (
-    redact_secrets,
-    run_subprocess_safe,
-)
-
-logger = logging.getLogger(__name__)
-
-
-# M-P-09: one cached writer connection per learning_db path — LLM cost
-# logging used to pay a fresh ``sqlite3.connect`` + fsync per call. At
-# current volume (<10 calls/cycle) the cost is small, but caching keeps
-# the dispatch code consistent with the rest of the "one-cached-writer"
-# pattern the codebase standardised on (reward.py, trigram_index.py).
-#
-# S9-W2 C4 (fork safety): a cached SQLite handle inherited across
-# ``os.fork()`` corrupts the DB because both processes think they hold an
-# exclusive lock. We clear the cache in any forked child via
-# ``os.register_at_fork`` AND keyed-by-pid within ``_get_cost_conn`` so
-# a child that somehow missed the registrar still behaves correctly.
-# On Windows / platforms without ``register_at_fork`` the fork path
-# cannot happen so the pid-check is free insurance.
-#
-# S9-W2 C9 (serialization): ``_COST_CONN_LOCK`` is now ONLY held during
-# the get/create-cache flip, NOT during the ``execute+commit`` inside
-# ``_log_cost``. SQLite's own writer serialisation (BEGIN IMMEDIATE +
-# busy_timeout) is the correct tool for write ordering; the Python lock
-# was converting 10 parallel candidates × 3-8ms fsync into a single
-# 30-80ms tail. Cache structure remains intact; the lock's scope shrinks.
-_COST_CONN_CACHE: dict[str, sqlite3.Connection] = {}
-_COST_CONN_LOCK = threading.Lock()
-_COST_CONN_OWNER_PID: int | None = None
-
-
-def _resolve_cost_key(learning_db: Path) -> str:
-    """Resolve a DB path to a stable cache key.
-
-    M-P-03 fix: ``~/.slm/learning.db`` and ``/home/u/.slm/learning.db``
-    previously cached to separate conns on the same inode, producing two
-    writers contending over WAL. ``os.path.realpath`` collapses them.
-    """
-    try:
-        return os.path.realpath(str(learning_db))
-    except OSError:  # pragma: no cover — defensive
-        return str(learning_db)
-
-
-def _reset_cost_cache_for_child() -> None:
-    """Close any inherited handles in the fork child.
-
-    C4: ``os.register_at_fork(after_in_child=...)`` fires before any user
-    code runs in the child, so closing here is safe even if the parent
-    was mid-write (the child never participated in that transaction).
-    """
-    global _COST_CONN_OWNER_PID
-    # Do NOT close parent-owned handles — let the parent keep using them.
-    # We only clear our cache reference so the child opens fresh ones.
-    _COST_CONN_CACHE.clear()
-    _COST_CONN_OWNER_PID = os.getpid()
-
-
-def _get_cost_conn(learning_db: Path) -> sqlite3.Connection:
-    """Return a cached writer connection for ``learning_db``. Never raises."""
-    global _COST_CONN_OWNER_PID
-    key = _resolve_cost_key(learning_db)
-    with _COST_CONN_LOCK:
-        # Belt-and-suspenders: if we somehow missed the fork registrar
-        # (embedded interpreter, non-POSIX fork path), detect pid drift
-        # and reset before handing out a potentially-corrupt handle.
-        current_pid = os.getpid()
-        if _COST_CONN_OWNER_PID is not None and (
-            _COST_CONN_OWNER_PID != current_pid
-        ):
-            _COST_CONN_CACHE.clear()
-        _COST_CONN_OWNER_PID = current_pid
-        conn = _COST_CONN_CACHE.get(key)
-        if conn is not None:
-            return conn
-        conn = sqlite3.connect(key, check_same_thread=False, timeout=2.0)
-        _COST_CONN_CACHE[key] = conn
-        return conn
-
-
-def _close_cost_conns() -> None:
-    """Close every cached cost-log connection (atexit)."""
-    with _COST_CONN_LOCK:
-        conns = list(_COST_CONN_CACHE.items())
-        _COST_CONN_CACHE.clear()
-    for _key, conn in conns:
-        try:
-            conn.close()
-        except Exception:  # pragma: no cover
-            pass
-
-
-atexit.register(_close_cost_conns)
-# C4: wipe inherited caches in any forked child. ``register_at_fork`` is
-# POSIX-only; Windows simply doesn't fork so there is nothing to register.
-if hasattr(os, "register_at_fork"):
-    os.register_at_fork(after_in_child=_reset_cost_cache_for_child)
-
-
-# ---------------------------------------------------------------------------
-# Allow-list and deny-list
-# ---------------------------------------------------------------------------
-#
-# Allow-list explicitly names every model evolution may invoke. Deny-list
-# catches substrings that must NEVER appear in an evolution-issued model
-# id — notably the O-tier Claude family (MASTER-PLAN D2) and OpenAI's
-# ``gpt-4-turbo`` (cost + behaviour regressions observed in prod).
-#
-# NOTE on the deny-list strings: the Stage-5b CI gate scans ``src/`` for
-# the full banned model-family literal. That literal must NEVER appear in
-# this file or any other source file. We check for the shorter substring
-# ``opus`` instead; that catches every Claude O-family id variant without
-# putting the banned literal anywhere in source.
-
-ALLOWED_LLM_MODELS: frozenset[str] = frozenset({
-    "claude-haiku-4-5",
-    "claude-sonnet-4-6",
-    "ollama:llama3",
-    "ollama:qwen2.5",
-    "openai:gpt-4o-mini",
-})
-
-FORBIDDEN_MODEL_SUBSTRINGS: tuple[str, ...] = ("opus", "gpt-4-turbo")
-
-# Hard ceiling on ``max_tokens`` for any single evolution LLM call
-# (LLD-11). This is a CEILING, not a per-call default: each caller passes
-# its own budget (confirm=100, blind-verify=500, mutation=4000). The value
-# MUST stay >= the largest legitimate caller request — otherwise that call
-# trips the guard in ``_dispatch_llm`` and silently fails-closed. The
-# mutation step (``SkillEvolver._generate_mutation``) generates a full
-# SKILL.md and requests 4000; a stale 500 here made mutation return "" on
-# every cycle, killing evolution invisibly. 8000 accommodates 4000 with
-# retry/large-skill headroom. Do NOT lower below 4096 without first
-# shrinking that caller's request. Per-call spend is still bounded by
-# EvolutionBudget (10 LLM calls/cycle x 3 cycles/day).
-MAX_TOKENS_CAP: int = 8000
-
-
-# ---------------------------------------------------------------------------
-# Backends (SB-2, SB-4) — moved out of skill_evolver.py
-# ---------------------------------------------------------------------------
-#
-# Every backend has a uniform signature::
-#
-#     backend(prompt: str, *, model: str, max_tokens: int) -> str
-#
-# They receive the ALREADY-REDACTED prompt from ``_dispatch_llm``. They
-# must never log the prompt. They return an empty string on any
-# transport failure (fail-closed: caller treats "" as "no evolution").
-
-
-def _call_claude_cli_backend(
-    prompt: str, *, model: str, max_tokens: int,
-) -> str:
-    """Spawn ``claude --model <model>`` via ``run_subprocess_safe``.
-
-    SB-4: bare ``subprocess.run`` is banned in evolution code — every
-    shell-out goes through ``run_subprocess_safe`` which strips the
-    inherited env down to a vetted allow-list.
-    """
-    # Translate the allow-listed model id to the CLI short name.
-    cli_model = "haiku"
-    if "sonnet" in model:
-        cli_model = "sonnet"
-
-    with tempfile.NamedTemporaryFile(
-        mode="w", suffix=".txt", delete=False,
-    ) as f:
-        f.write(prompt)
-        prompt_file = f.name
-
-    try:
-        result = run_subprocess_safe(
-            ["claude", "--model", cli_model, "--print", "--no-input",
-             "--max-tokens", str(max_tokens),
-             "--prompt-file", prompt_file],
-            timeout=120.0,
-            env={
-                "CLAUDE_CODE_ENTRYPOINT": "cli",
-                "ECC_SKIP_OBSERVE": "1",
-            },
-        )
-        stdout = getattr(result, "stdout", "") or ""
-        rc = getattr(result, "returncode", 1)
-        return stdout.strip() if rc == 0 else ""
-    except Exception as exc:  # noqa: BLE001 — fail-closed, never crash caller
-        logger.debug("claude CLI backend failed: %s", exc)
-        return ""
-    finally:
-        try:
-            os.unlink(prompt_file)
-        except OSError:
-            pass
-
-
-def _call_ollama_backend(
-    prompt: str, *, model: str, max_tokens: int,
-) -> str:
-    """Call local Ollama HTTP API for LLM completion.
-
-    ``model`` is expected to be an allow-listed id of the form
-    ``"ollama:<model-name>"`` — the prefix is stripped before dispatch.
-    """
-    import json as _json
-    import urllib.request
-
-    ollama_model = model.split(":", 1)[1] if model.startswith("ollama:") else model
-    payload = _json.dumps({
-        "model": ollama_model,
-        "prompt": prompt,
-        "stream": False,
-        "options": {"num_predict": max_tokens},
-    }).encode()
-
-    try:
-        req = urllib.request.Request(
-            "http://127.0.0.1:11434/api/generate",
-            data=payload,
-            headers={"Content-Type": "application/json"},
-            method="POST",
-        )
-        with urllib.request.urlopen(req, timeout=120) as resp:  # noqa: S310
-            data = _json.loads(resp.read())
-            return data.get("response", "") or ""
-    except Exception as exc:  # noqa: BLE001
-        logger.debug("Ollama backend failed: %s", exc)
-        return ""
-
-
-def _call_claude_api_backend(
-    prompt: str, *, model: str, max_tokens: int,
-) -> str:
-    """Call the Anthropic Messages API directly.
-
-    The API model id is the allow-listed name itself — no client-side
-    mapping table, so adding a new allow-listed model is a one-line
-    edit to :data:`ALLOWED_LLM_MODELS`.
-    """
-    try:
-        import anthropic  # type: ignore[import-not-found]
-    except Exception as exc:  # noqa: BLE001
-        logger.debug("anthropic sdk unavailable: %s", exc)
-        return ""
-
-    try:
-        client = anthropic.Anthropic()
-        msg = client.messages.create(
-            model=model,
-            max_tokens=max_tokens,
-            messages=[{"role": "user", "content": prompt}],
-        )
-        content = getattr(msg, "content", None)
-        if content and len(content) > 0:
-            first = content[0]
-            text = getattr(first, "text", None)
-            if isinstance(text, str):
-                return text
-        return ""
-    except Exception as exc:  # noqa: BLE001
-        logger.debug("Anthropic API backend failed: %s", exc)
-        return ""
-
-
-def _call_openai_api_backend(
-    prompt: str, *, model: str, max_tokens: int,
-) -> str:
-    """Call the OpenAI Chat Completions API directly.
-
-    The API model id is derived from the allow-listed name by stripping
-    the ``"openai:"`` prefix — e.g. ``"openai:gpt-4o-mini"`` → ``"gpt-4o-mini"``.
-    Requires ``OPENAI_API_KEY`` in the environment. Returns empty string on
-    any transport or SDK failure (fail-closed).
-    """
-    openai_model = model.split(":", 1)[1] if model.startswith("openai:") else model
-    try:
-        import openai as _openai  # type: ignore[import-not-found]
-    except Exception as exc:  # noqa: BLE001
-        logger.debug("openai sdk unavailable: %s", exc)
-        return ""
-
-    try:
-        client = _openai.OpenAI()
-        completion = client.chat.completions.create(
-            model=openai_model,
-            max_tokens=max_tokens,
-            messages=[{"role": "user", "content": prompt}],
-        )
-        choices = getattr(completion, "choices", None)
-        if choices and len(choices) > 0:
-            msg = getattr(choices[0], "message", None)
-            if msg:
-                content = getattr(msg, "content", None)
-                if isinstance(content, str):
-                    return content
-        return ""
-    except Exception as exc:  # noqa: BLE001
-        logger.debug("OpenAI API backend failed: %s", exc)
-        return ""
-
-
-# ---------------------------------------------------------------------------
-# Backend registry — dispatches by (allow-listed) model id
-# ---------------------------------------------------------------------------
-
-
-def _fail_closed_backend(
-    prompt: str, *, model: str, max_tokens: int,
-) -> str:
-    """S9-SKEP-14: explicit fail-closed backend for unroutable models.
-
-    Returns "" (the fail-closed sentinel every dispatch treats as
-    "no evolution happened") and logs a warning. Previously the
-    fallthrough silently routed any unknown id to the paid Anthropic
-    API — a misconfigured entry in ``ALLOWED_LLM_MODELS`` would burn
-    user money without anyone noticing.
-    """
-    logger.warning(
-        "llm_dispatch: no backend registered for model=%r — "
-        "fail-closed (returning empty string)", model,
-    )
-    return ""
-
-
-def _pick_backend(model: str) -> Callable[..., str]:
-    """Resolve an allow-listed model id to its backend callable.
-
-    Contract: ``model`` is already validated against ``ALLOWED_LLM_MODELS``
-    by the caller (``_dispatch_llm`` runs ``_validate_model`` first).
-
-    S9-SKEP-14: routing is prefix-exact — we no longer default unknown
-    models to the Claude API path. An allow-listed model without a
-    backend entry hits ``_fail_closed_backend`` and returns ""
-    instead of silently spending money on the wrong vendor.
-    """
-    if model.startswith("ollama:"):
-        return _call_ollama_backend
-    if model.startswith("openai:"):
-        return _call_openai_api_backend
-    if model.startswith("claude-"):
-        # Claude CLI path is an alternative — selected when an explicit
-        # env flag is set. Default path is the Anthropic API backend.
-        if os.environ.get("SLM_EVOLUTION_BACKEND") == "claude-cli":
-            return _call_claude_cli_backend
-        return _call_claude_api_backend
-    return _fail_closed_backend
-
-
-def _actual_llm_call(prompt: str, *, model: str, max_tokens: int) -> str:
-    """Dispatch the redacted prompt to the backend registered for ``model``.
-
-    Kept as a stable module-level function so tests can ``monkeypatch``
-    it with a deterministic stub (see ``record_backend`` fixture in
-    ``test_llm_dispatch.py``). Production callers never invoke this
-    directly — they go through :func:`_dispatch_llm`.
-    """
-    backend = _pick_backend(model)
-    return backend(prompt, model=model, max_tokens=max_tokens)
-
-
-# ---------------------------------------------------------------------------
-# Gate
-# ---------------------------------------------------------------------------
-
-
-def _validate_model(model: str) -> None:
-    """Raise ``ValueError`` if the model is forbidden or not allow-listed."""
-    if not isinstance(model, str) or not model:
-        raise ValueError(f"model must be a non-empty str, got {model!r}")
-    lowered = model.lower()
-    for forbidden in FORBIDDEN_MODEL_SUBSTRINGS:
-        if forbidden in lowered:
-            raise ValueError(
-                f"forbidden model: {model!r} (contains {forbidden!r})"
-            )
-    if model not in ALLOWED_LLM_MODELS:
-        raise ValueError(
-            f"model not in ALLOWED_LLM_MODELS: {model!r} "
-            f"(allowed: {sorted(ALLOWED_LLM_MODELS)})"
-        )
-
-
-def _log_cost(
-    *,
-    learning_db: Path,
-    profile_id: str,
-    model: str,
-    tokens_in: int,
-    tokens_out: int,
-    cost_usd: float = 0.0,
-    cycle_id: str | None = None,
-) -> None:
-    """Append a redacted cost-log row. Never stores prompt/response text.
-
-    H-16 (Stage 8): ``profile_id`` must be a non-empty string. The schema
-    has ``NOT NULL`` on the column but SQLite accepts empty strings — that
-    would break the dashboard's per-profile cost widget by silently
-    aggregating unattributed spend. We raise here instead so the caller
-    fixes the upstream bug rather than learning about it weeks later from
-    a mis-reported invoice.
-    """
-    if not isinstance(profile_id, str) or not profile_id.strip():
-        raise ValueError(
-            "evolution_llm_cost_log.profile_id must be a non-empty string "
-            f"(got {profile_id!r})"
-        )
-    now = datetime.now(timezone.utc).isoformat(timespec="seconds")
-    try:
-        # S9-W2 C9: the cached conn is ``check_same_thread=False`` and
-        # SQLite's own writer serialisation (BEGIN IMMEDIATE + 2 s
-        # ``busy_timeout`` in the connect() call) is the right tool for
-        # write ordering. Previously we held _COST_CONN_LOCK across the
-        # execute+commit fsync, converting 10 parallel candidates' worth
-        # of 3-8 ms commits into a single 30-80 ms tail. Release the
-        # Python lock BEFORE the SQL round-trip.
-        conn = _get_cost_conn(Path(learning_db))
-        conn.execute(
-            "INSERT INTO evolution_llm_cost_log "
-            "(profile_id, ts, model, tokens_in, tokens_out, cost_usd, cycle_id) "
-            "VALUES (?,?,?,?,?,?,?)",
-            (profile_id, now, model, tokens_in, tokens_out, cost_usd, cycle_id),
-        )
-        conn.commit()
-    except sqlite3.Error as e:
-        logger.warning("cost log write failed: %s", e)
-
-
-def _dispatch_llm(
-    prompt: str,
-    *,
-    model: str,
-    learning_db: Path | str,
-    profile_id: str,
-    max_tokens: int = MAX_TOKENS_CAP,
-    cycle_id: str | None = None,
-) -> str:
-    """Central choke-point for every evolution LLM call.
-
-    Validates model against allow/deny lists, caps ``max_tokens``, runs the
-    prompt through ``redact_secrets(aggression='high')``, dispatches, and
-    logs a redacted cost row. Raises ``ValueError`` on any contract breach.
-    """
-    _validate_model(model)
-
-    if not isinstance(max_tokens, int) or max_tokens <= 0:
-        raise ValueError(
-            f"max_tokens must be a positive int, got {max_tokens!r}"
-        )
-    if max_tokens > MAX_TOKENS_CAP:
-        raise ValueError(
-            f"max_tokens {max_tokens} > {MAX_TOKENS_CAP} cap (LLD-11)"
-        )
-    # S9-W2 H-SKEP-05: validate profile_id BEFORE paying for the LLM
-    # call. Previously the check lived in _log_cost, AFTER the paid
-    # Anthropic round-trip — a misconfigured profile with empty id would
-    # spend the money, raise ValueError in _log_cost, and return "" from
-    # _llm_call's except. Net: cost incurred, no cost-log row, caller
-    # may retry and burn more. Validate up-front, fail-closed, zero cost.
-    if not isinstance(profile_id, str) or not profile_id.strip():
-        raise ValueError(
-            "profile_id must be a non-empty string "
-            f"(got {profile_id!r})"
-        )
-
-    # LLD-00 §5 — redact BEFORE dispatch. Never log the raw prompt.
-    safe_prompt = redact_secrets(prompt, aggression="high")
-
-    # S9-defer H-P-10: per-cycle retry-cost DoS guard. If the caller
-    # (or an orchestrator layer) keeps retrying a failing dispatch on
-    # the same ``cycle_id``, cost escalates without bound — a crafted
-    # adversarial scenario could make evolution burn through the
-    # daily USD cap in minutes. Count prior calls for this cycle_id
-    # in ``evolution_llm_cost_log`` and refuse once the retry cap is
-    # hit. The EvolutionBudget object already caps overall LLM calls
-    # per cycle to 10; this is the per-cycle-ID guard for retries on
-    # the SAME logical step (distinct from 10 different LLM calls for
-    # 10 different steps).
-    _RETRY_CAP_PER_CYCLE = int(
-        os.environ.get("SLM_EVOLUTION_RETRY_CAP", "5")
-    )
-    if cycle_id:
-        try:
-            _conn = _get_cost_conn(Path(learning_db))
-            row = _conn.execute(
-                "SELECT COUNT(*) FROM evolution_llm_cost_log "
-                "WHERE profile_id = ? AND cycle_id = ?",
-                (profile_id, cycle_id),
-            ).fetchone()
-            prior = int(row[0]) if row and row[0] is not None else 0
-            if prior >= _RETRY_CAP_PER_CYCLE:
-                logger.warning(
-                    "evolution retry cap hit: profile=%s cycle_id=%s "
-                    "prior=%d cap=%d — refusing dispatch",
-                    profile_id, cycle_id, prior, _RETRY_CAP_PER_CYCLE,
-                )
-                raise RuntimeError(
-                    f"evolution retry cap exceeded for cycle {cycle_id}"
-                )
-        except sqlite3.Error:
-            # Cost log unavailable — fail-open on this guard (the
-            # outer EvolutionBudget still enforces the 10-call cap).
-            pass
-
-    response = _actual_llm_call(
-        safe_prompt, model=model, max_tokens=max_tokens,
-    )
-
-    # Cost-log row: lengths only, no text content. This guarantees the
-    # redaction canary (e.g. a ``ghp_...`` GitHub PAT) cannot end up in
-    # the audit log — we never persist the redacted prompt either.
-    _log_cost(
-        learning_db=Path(learning_db),
-        profile_id=profile_id,
-        model=model,
-        tokens_in=len(safe_prompt),
-        tokens_out=len(response) if isinstance(response, str) else 0,
-        cycle_id=cycle_id,
-    )
-    return response