structuremappingmemory 1.0.0__py3-none-any.whl

sma/agent/llm.py

@@ -0,0 +1,280 @@
+"""LLM orchestration layer.
+
+The LLM is intentionally downstream of extraction and retrieval. It receives a
+mode, a user question, and already-retrieved evidence, then verbalizes an
+answer. It cannot write facts to memory or affect candidate generation.
+
+Two interchangeable backends:
+- LocalOrchestrator:    quantized Qwen GGUF via llama-cpp (CPU, offline)
+- DeepSeekOrchestrator: DeepSeek's OpenAI-compatible API (needs
+                        SMA_DEEPSEEK_API_KEY in the environment or repo .env)
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+
+DEFAULT_MODEL_REPO = "Qwen/Qwen2.5-0.5B-Instruct-GGUF"
+DEFAULT_MODEL_FILE = "qwen2.5-0.5b-instruct-q4_k_m.gguf"
+DEFAULT_MODEL_PATH = "models/qwen2.5-0.5b-instruct-q4_k_m.gguf"
+
+DEEPSEEK_BASE_URL = "https://api.deepseek.com"
+DEEPSEEK_MODEL = "deepseek-chat"
+DEEPSEEK_KEY_ENV = "SMA_DEEPSEEK_API_KEY"
+
+SYSTEM_PROMPT = (
+    "You are the answer writer for SMA-1, an agentic memory system. Retrieval is already "
+    "complete; you only verbalize. The evidence items are PAST incidents retrieved from memory "
+    "as candidate precedents for the user's input. If the input is itself a new incident (e.g. "
+    "raw log lines), do NOT look for those literal entries - hostnames, dates and IDs will "
+    "always differ. Instead say which precedent has the most similar failure pattern (the "
+    "sequence/causal shape of events), what happened in it, and what that suggests here, citing "
+    "items like [1]. Only when no precedent shares even the failure pattern, say so plainly. "
+    "For ordinary questions, answer strictly from the evidence. Reply in 2-5 short sentences. "
+    "Never repeat yourself."
+)
+
+
+MAX_HISTORY_TURNS = 8
+
+
+def build_messages(
+    question: str, mode: str, evidence: list[dict], history: list[dict] | None = None
+) -> list[dict]:
+    # Plain numbered texts only: provenance hashes and scores are for the UI
+    # and audit trail, not the verbalizer — small models parrot them back.
+    # 900 chars/item: the H3 judge pass showed a 400-char cap truncates exactly
+    # the anomaly lines questions ask about (abstention artifacts); 900 x 5
+    # items stays within the local model's 4k context alongside chat history.
+    def _item(i: int, row: dict) -> str:
+        why = row.get("alignment")
+        head = f"[{i + 1}]" + (f" (why retrieved: {why})" if why else "")
+        return f"{head} {row.get('text', '')[:900]}"
+
+    # Coverage warnings (blueprint 12-R3) ride along as pseudo-rows with a
+    # "warning" key and no text; surface them as caveats, not evidence items.
+    warnings = [row["warning"] for row in evidence if row.get("warning")]
+    rows = [row for row in evidence if not row.get("warning")]
+    evidence_text = "\n".join(_item(i, row) for i, row in enumerate(rows[:8]))
+    warning_text = "".join(f"\nCaveat: {w}." for w in warnings)
+    window_caveat = (
+        "\nCaveat: each evidence item is one bounded session window. Events outside a "
+        "window are not recorded in it - the absence of an event in the evidence is NOT "
+        "evidence that it did not happen. Never infer outcomes from absence."
+        if rows
+        else ""
+    )
+    user = (
+        f"Evidence retrieved by the '{mode}' memory for the latest question:\n"
+        f"{evidence_text or '(none retrieved)'}{window_caveat}{warning_text}\n\n"
+        f"Question: {question}"
+    )
+    messages = [{"role": "system", "content": SYSTEM_PROMPT}]
+    for turn in (history or [])[-MAX_HISTORY_TURNS * 2:]:
+        role = turn.get("role")
+        content = turn.get("content")
+        if role in ("user", "assistant") and isinstance(content, str) and content:
+            messages.append({"role": role, "content": content})
+    messages.append({"role": "user", "content": user})
+    return messages
+
+
+def _env_key(name: str) -> str | None:
+    """Read a key from the environment, falling back to the repo .env file."""
+    value = os.environ.get(name)
+    if value:
+        return value
+    env_path = Path(".env")
+    if env_path.exists():
+        for line in env_path.read_text(encoding="utf-8").splitlines():
+            line = line.strip()
+            if line.startswith(f"{name}="):
+                return line.split("=", 1)[1].strip()
+    return None
+
+
+@dataclass(frozen=True)
+class OrchestratorConfig:
+    model_path: str = DEFAULT_MODEL_PATH
+    n_ctx: int = 4096
+    n_threads: int = 8
+    temperature: float = 0.2
+    max_tokens: int = 220
+    repeat_penalty: float = 1.25
+    top_p: float = 0.9
+
+
+class LocalOrchestrator:
+    name = "local"
+
+    def __init__(self, config: OrchestratorConfig | None = None):
+        self.config = config or OrchestratorConfig(
+            model_path=os.environ.get("SMA_LLM_MODEL", DEFAULT_MODEL_PATH)
+        )
+        self._llm = None
+        self._load_error: str | None = None
+
+    @property
+    def status(self) -> dict:
+        if self._llm is not None:
+            return {
+                "backend": "llama_cpp",
+                "model": Path(self.config.model_path).name,
+                "loaded": True,
+            }
+        path = Path(self.config.model_path)
+        return {
+            "backend": "deterministic_fallback" if not path.exists() else "llama_cpp",
+            "model": Path(self.config.model_path).name,
+            "loaded": False,
+            "load_error": self._load_error or ("model file missing" if not path.exists() else ""),
+            "recommended_model": f"{DEFAULT_MODEL_REPO}/{DEFAULT_MODEL_FILE}",
+        }
+
+    def _ensure_loaded(self) -> bool:
+        if self._llm is not None:
+            return True
+        path = Path(self.config.model_path)
+        if not path.exists():
+            self._load_error = "model file missing; run scripts/fetch_model.py"
+            return False
+        try:
+            from llama_cpp import Llama
+
+            self._llm = Llama(
+                model_path=str(path),
+                n_ctx=self.config.n_ctx,
+                n_threads=self.config.n_threads,
+                verbose=False,
+            )
+            return True
+        except Exception as exc:  # pragma: no cover - depends on optional runtime
+            self._load_error = str(exc)
+            return False
+
+    def answer(
+        self, question: str, mode: str, evidence: list[dict], history: list[dict] | None = None
+    ) -> str:
+        if not self._ensure_loaded():
+            return fallback_answer(question, mode, evidence, self.status)
+        # Chat completion uses the model's own instruct template (raw completion
+        # makes small Qwen models ramble); repeat_penalty + tight max_tokens
+        # stop the looping/repetition failure mode of 0.5B quantized models.
+        response = self._llm.create_chat_completion(  # type: ignore[union-attr]
+            messages=build_messages(question, mode, evidence, history),
+            max_tokens=self.config.max_tokens,
+            temperature=self.config.temperature,
+            top_p=self.config.top_p,
+            repeat_penalty=self.config.repeat_penalty,
+        )
+        text = (response["choices"][0]["message"]["content"] or "").strip()
+        return text or fallback_answer(question, mode, evidence, self.status)
+
+    def complete(self, messages: list[dict], max_tokens: int = 600, temperature: float = 0.0) -> str:
+        """Raw chat completion for non-verbalizer callers (e.g. adapter drafting).
+
+        Raises RuntimeError when the local model is unavailable - drafting has
+        no deterministic fallback, by design (rules either come from a model or
+        a human, never from a heuristic pretending to be one).
+        """
+        if not self._ensure_loaded():
+            raise RuntimeError(f"local model unavailable: {self._load_error}")
+        response = self._llm.create_chat_completion(  # type: ignore[union-attr]
+            messages=messages,
+            max_tokens=max_tokens,
+            temperature=temperature,
+            top_p=self.config.top_p,
+            repeat_penalty=self.config.repeat_penalty,
+        )
+        return (response["choices"][0]["message"]["content"] or "").strip()
+
+
+class DeepSeekOrchestrator:
+    name = "deepseek"
+
+    def __init__(self, model: str = DEEPSEEK_MODEL, api_key: str | None = None):
+        self.model = model
+        self._api_key = api_key or _env_key(DEEPSEEK_KEY_ENV)
+        self._last_error: str | None = None
+
+    @property
+    def status(self) -> dict:
+        return {
+            "backend": "deepseek_api",
+            "model": self.model,
+            "key_present": bool(self._api_key),
+            "last_error": self._last_error or "",
+        }
+
+    def answer(
+        self, question: str, mode: str, evidence: list[dict], history: list[dict] | None = None
+    ) -> str:
+        if not self._api_key:
+            self._last_error = f"{DEEPSEEK_KEY_ENV} not set"
+            return fallback_answer(question, mode, evidence, self.status)
+        try:
+            import httpx
+
+            response = httpx.post(
+                f"{DEEPSEEK_BASE_URL}/chat/completions",
+                headers={"Authorization": f"Bearer {self._api_key}"},
+                json={
+                    "model": self.model,
+                    "messages": build_messages(question, mode, evidence, history),
+                    "temperature": 0.3,
+                    "max_tokens": 400,
+                },
+                timeout=60.0,
+            )
+            response.raise_for_status()
+            self._last_error = None
+            text = (response.json()["choices"][0]["message"]["content"] or "").strip()
+            return text or fallback_answer(question, mode, evidence, self.status)
+        except Exception as exc:
+            self._last_error = f"{type(exc).__name__}: {exc}"
+            return fallback_answer(question, mode, evidence, self.status)
+
+    def complete(self, messages: list[dict], max_tokens: int = 600, temperature: float = 0.0) -> str:
+        """Raw chat completion for non-verbalizer callers (e.g. adapter drafting)."""
+        if not self._api_key:
+            raise RuntimeError(f"{DEEPSEEK_KEY_ENV} not set")
+        import httpx
+
+        response = httpx.post(
+            f"{DEEPSEEK_BASE_URL}/chat/completions",
+            headers={"Authorization": f"Bearer {self._api_key}"},
+            json={
+                "model": self.model,
+                "messages": messages,
+                "temperature": temperature,
+                "max_tokens": max_tokens,
+            },
+            timeout=60.0,
+        )
+        response.raise_for_status()
+        return (response.json()["choices"][0]["message"]["content"] or "").strip()
+
+
+def fallback_answer(question: str, mode: str, evidence: list[dict], status: dict) -> str:
+    evidence = [row for row in evidence if not row.get("warning")]
+    if not evidence:
+        return (
+            f"No evidence was retrieved for `{mode}`. Local LLM status: "
+            f"{status.get('load_error') or status.get('last_error') or status.get('backend')}."
+        )
+    top = evidence[0]
+    lines = [
+        f"Mode `{mode}` retrieved {len(evidence)} evidence item(s).",
+        f"Top evidence: {top.get('text', '')}",
+        f"Provenance: {top.get('provenance', top.get('source_id', ''))}",
+        "Local LLM is not available, so this is a deterministic evidence summary "
+        f"rather than generated prose ({status.get('load_error') or status.get('last_error') or 'no backend'}).",
+    ]
+    return "\n".join(lines)
+
+
+default_orchestrator = LocalOrchestrator()
+default_deepseek = DeepSeekOrchestrator()

sma/agent/policies.py

@@ -0,0 +1,21 @@
+"""Hard API policies for SMA agent memory."""
+
+from __future__ import annotations
+
+
+def reject_free_text_facts(annotation) -> None:
+    if isinstance(annotation, str):
+        raise ValueError("free-text facts are rejected; route annotations through encode()")
+    if isinstance(annotation, dict) and "sexpr" not in annotation and "case_id" not in annotation:
+        raise ValueError("annotations must be encoded cases or canonical S-expressions")
+
+
+def require_provenance(claims: list[dict]) -> list[dict]:
+    checked: list[dict] = []
+    for claim in claims:
+        if not claim.get("provenance"):
+            claim = dict(claim)
+            claim["status"] = "unsupported-by-memory"
+        checked.append(claim)
+    return checked
+

sma/agent/service.py

@@ -0,0 +1,95 @@
+"""In-process SMA memory service used by CLI, API, and UI."""
+
+from __future__ import annotations
+
+from dataclasses import asdict
+from pathlib import Path
+
+from sma.encoders import get_encoder
+from sma.index.macfac import MacFacIndex
+from sma.ir.schema import Case, make_case
+from sma.ir.sexpr import canonical_case_text, loads_case
+from sma.match.engine import match_cases
+from sma.match.explain import correspondence_table, explain_text
+from sma.match.infer import candidate_inferences
+from sma.match.types import MatchConfig
+from sma.match.verifier import verify_inference
+from sma.sage.pools import SagePool
+from sma.store import CaseStore
+
+from .policies import reject_free_text_facts
+
+
+class MemoryService:
+    def __init__(self, store_path: str | Path = "data/processed/store"):
+        self.store = CaseStore(store_path)
+        self.config = MatchConfig(gamma=0.25, rho=0.5, delta=2)
+        self.index = MacFacIndex(self.config)
+        self.gmaps = {}
+        self.pools: dict[str, SagePool] = {}
+        for case in self.store.iter_cases():
+            self.index.add(case)
+
+    def encode(self, artifact: str, adapter_id: str, **kwargs) -> dict:
+        result = get_encoder(adapter_id).encode(artifact, **kwargs)
+        self.store.put(result.case)
+        self.index.add(result.case)
+        return {
+            "case_id": result.case.case_id,
+            "n_statements": len(result.case.statements),
+            "warnings": list(result.warnings),
+            "sexpr": canonical_case_text(result.case.statements),
+        }
+
+    def inline_case(self, sexpr: str) -> Case:
+        return make_case(loads_case(sexpr), {"adapter": "inline"})
+
+    def retrieve(self, case_id: str | None = None, inline_case: str | None = None, k: int = 10) -> list[dict]:
+        query = self.store.get(case_id) if case_id else self.inline_case(inline_case or "")
+        return [asdict(result) for result in self.index.retrieve(query, k=k)]
+
+    def map(self, base_id: str, target_id: str, scorer: str = "ses") -> dict:
+        config = MatchConfig(
+            gamma=self.config.gamma,
+            rho=self.config.rho,
+            delta=self.config.delta,
+            scorer=scorer,
+        )
+        gmap = match_cases(self.store.get(base_id), self.store.get(target_id), config=config)
+        gmap_id = f"{base_id[:8]}_{target_id[:8]}_{scorer}"
+        self.gmaps[gmap_id] = gmap
+        return {
+            "gmap_id": gmap_id,
+            "correspondences": gmap.correspondences,
+            "SES_n": gmap.normalized_score,
+            "gap": gmap.optimality_gap,
+            "kernels_used": len(gmap.kernels),
+        }
+
+    def project(self, gmap_id: str) -> list[dict]:
+        return [asdict(inference) for inference in candidate_inferences(self.gmaps[gmap_id])]
+
+    def verify(self, inference: str) -> dict:
+        result = verify_inference(inference)
+        return asdict(result)
+
+    def store_annotations(self, case_id: str, outcome_annotations) -> dict:
+        reject_free_text_facts(outcome_annotations)
+        return {"status": "ok", "case_id": case_id}
+
+    def generalize(self, pool_id: str, case_id: str) -> dict:
+        pool = self.pools.setdefault(pool_id, SagePool(pool_id=pool_id, config=self.config))
+        assignment = pool.assimilate(self.store.get(case_id))
+        return {"pool_id": pool_id, "assignment": assignment}
+
+    def pool_stats(self, pool_id: str) -> dict:
+        pool = self.pools.setdefault(pool_id, SagePool(pool_id=pool_id, config=self.config))
+        return pool.stats()
+
+    def explain(self, gmap_id: str) -> dict:
+        gmap = self.gmaps[gmap_id]
+        return {"text": explain_text(gmap), "table": correspondence_table(gmap)}
+
+
+default_service = MemoryService()
+

sma/cli.py

@@ -0,0 +1,65 @@
+"""CLI for SMA MVP."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from sma.agent.service import MemoryService
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="sma")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    enc = sub.add_parser("encode")
+    enc.add_argument("adapter_id")
+    enc.add_argument("artifact_file")
+    enc.add_argument("--store", default="data/processed/store")
+
+    ret = sub.add_parser("retrieve")
+    ret.add_argument("case_id")
+    ret.add_argument("--k", type=int, default=10)
+    ret.add_argument("--store", default="data/processed/store")
+
+    mp = sub.add_parser("map")
+    mp.add_argument("base_id")
+    mp.add_argument("target_id")
+    mp.add_argument("--scorer", default="ses")
+    mp.add_argument("--store", default="data/processed/store")
+
+    report = sub.add_parser("report")
+    report.add_argument("--out", default="reports/report.html")
+
+    sub.add_parser("ui")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> None:
+    args = build_parser().parse_args(argv)
+    if args.cmd == "report":
+        from sma.eval.report import main as report_main
+
+        raise SystemExit(report_main(["--out", args.out]))
+    if args.cmd == "ui":
+        from sma.ui.app import main as ui_main
+
+        raise SystemExit(ui_main([]))
+
+    service = MemoryService(getattr(args, "store", "data/processed/store"))
+    if args.cmd == "encode":
+        artifact = open(args.artifact_file, encoding="utf-8").read()
+        print(json.dumps(service.encode(artifact, args.adapter_id), indent=2))
+    elif args.cmd == "retrieve":
+        print(json.dumps(service.retrieve(case_id=args.case_id, k=args.k), indent=2))
+    elif args.cmd == "map":
+        print(json.dumps(service.map(args.base_id, args.target_id, args.scorer), indent=2))
+    else:
+        print(f"unknown command: {args.cmd}", file=sys.stderr)
+        raise SystemExit(2)
+
+
+if __name__ == "__main__":
+    main()
+

sma/encoders/__init__.py

@@ -0,0 +1,38 @@
+from .agentobs import AgentObservationEncoder
+from .base import EncodeResult
+from .code_treesitter import CodeEncoder
+from .logs_drain import LogEncoder
+from .prose_tier1 import ProseTier1Encoder
+from .structured import StructuredEncoder
+from .healthcare import HealthcareEncoder
+from .traces import TraceEncoder
+
+ENCODERS = {
+    "logs": LogEncoder,
+    "code": CodeEncoder,
+    "traces": TraceEncoder,
+    "structured": StructuredEncoder,
+    "healthcare": HealthcareEncoder,
+    "agentobs": AgentObservationEncoder,
+    "prose_tier1": ProseTier1Encoder,
+}
+
+
+def get_encoder(adapter_id: str):
+    if adapter_id not in ENCODERS:
+        raise KeyError(f"unknown adapter: {adapter_id}")
+    return ENCODERS[adapter_id]()
+
+
+__all__ = [
+    "AgentObservationEncoder",
+    "CodeEncoder",
+    "ENCODERS",
+    "EncodeResult",
+    "LogEncoder",
+    "ProseTier1Encoder",
+    "StructuredEncoder",
+    "TraceEncoder",
+    "get_encoder",
+]
+

sma/encoders/agentobs.py

@@ -0,0 +1,27 @@
+"""Agent observation encoder."""
+
+from __future__ import annotations
+
+from sma.ir.schema import entity, make_case, stmt
+
+from .base import EncodeResult
+
+
+class AgentObservationEncoder:
+    adapter_id = "agentobs"
+    version = "0.1.0"
+
+    def encode(self, artifact: str, **kwargs) -> EncodeResult:
+        command = kwargs.get("command", "tool")
+        exit_code = str(kwargs.get("exit_code", 0))
+        obs = entity("obs_0", "observation")
+        statements = [
+            stmt("toolOutput", obs, entity(command, "command")),
+            stmt("exitCode", obs, entity(exit_code, "integer")),
+        ]
+        if "error" in artifact.lower() or exit_code != "0":
+            statements.append(stmt("failureEvent", obs, entity(command, "command")))
+        if artifact.strip():
+            statements.append(stmt("outputDigest", obs, entity(str(abs(hash(artifact))), "digest")))
+        return EncodeResult(make_case(statements, {"adapter": self.adapter_id, "tier": 0}), ())
+

sma/encoders/base.py

@@ -0,0 +1,23 @@
+"""Encoder base classes."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+from sma.ir.schema import Case
+
+
+@dataclass(frozen=True)
+class EncodeResult:
+    case: Case
+    warnings: tuple[str, ...] = ()
+
+
+class Encoder(Protocol):
+    adapter_id: str
+    version: str
+
+    def encode(self, artifact: str, **kwargs) -> EncodeResult:
+        ...
+

sma/encoders/code_treesitter.py

@@ -0,0 +1,64 @@
+"""Code and bug encoder with Python AST fallback."""
+
+from __future__ import annotations
+
+import ast
+import re
+
+from sma.ir.schema import Statement, entity, make_case, stmt
+
+from .base import EncodeResult
+
+
+class CodeEncoder:
+    adapter_id = "code"
+    version = "0.1.0"
+
+    def encode(self, artifact: str, **kwargs) -> EncodeResult:
+        language = kwargs.get("language", "python")
+        if language == "python":
+            return self._encode_python(artifact)
+        return self._encode_regex(artifact)
+
+    def _encode_python(self, artifact: str) -> EncodeResult:
+        statements: list[Statement] = []
+        try:
+            tree = ast.parse(artifact)
+        except SyntaxError as exc:
+            return EncodeResult(
+                make_case([stmt("syntaxError", entity(str(exc.lineno or 0), "line"))], {"adapter": self.adapter_id, "tier": 0}),
+                (str(exc),),
+            )
+        for node in ast.walk(tree):
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+                kind = "class" if isinstance(node, ast.ClassDef) else "function"
+                statements.append(stmt("defines", entity(kind, "kind"), entity(node.name, kind)))
+            elif isinstance(node, ast.Call):
+                name = call_name(node.func)
+                if name:
+                    statements.append(stmt("calls", entity("module", "scope"), entity(name, "callable")))
+            elif isinstance(node, (ast.Import, ast.ImportFrom)):
+                for alias in node.names:
+                    statements.append(stmt("imports", entity("module", "scope"), entity(alias.name, "module")))
+            elif isinstance(node, ast.Raise):
+                statements.append(stmt("throws", entity("module", "scope"), entity(type(node).__name__, "exception")))
+            elif isinstance(node, ast.ExceptHandler):
+                exc = getattr(node.type, "id", "Exception") if node.type is not None else "Exception"
+                statements.append(stmt("catches", entity("module", "scope"), entity(exc, "exception")))
+        return EncodeResult(make_case(statements or [stmt("emptyCode", entity("module"))], {"adapter": self.adapter_id, "tier": 0}), ())
+
+    def _encode_regex(self, artifact: str) -> EncodeResult:
+        statements: list[Statement] = []
+        for name in re.findall(r"\b(?:function|def|class)\s+([A-Za-z_]\w*)", artifact):
+            statements.append(stmt("defines", entity("symbol", "kind"), entity(name, "symbol")))
+        return EncodeResult(make_case(statements or [stmt("rawCode", entity("module"))], {"adapter": self.adapter_id, "tier": 0}), ())
+
+
+def call_name(node: ast.AST) -> str | None:
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Attribute):
+        parent = call_name(node.value)
+        return f"{parent}.{node.attr}" if parent else node.attr
+    return None
+