superlocalmemory 3.5.7 → 3.6.0

package/src/superlocalmemory/optimize/compress/prose_llmlingua.py

@@ -0,0 +1,77 @@
+# compress/prose_llmlingua.py
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later
+#
+# LLMLingua-2 paper: Microsoft Research + MIT (2024).
+# Model: XLM-RoBERTa fine-tuned as token binary classifier.
+# License: MIT (github.com/microsoft/LLMLingua)
+
+"""LLMLinguaCompressor — opt-in LLMLingua-2 prose compressor.
+
+SAFETY RULES (NON-NEGOTIABLE):
+  1. ONLY called for prose/narrative content — NEVER JSON or code.
+  2. compress_mode MUST be "aggressive" in optimize.json.
+  3. Lossy — CCR stores original before this runs.
+  4. Import errors caught — returns original on failure.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+logger = logging.getLogger("slm.optimize.compress.llmlingua")
+
+_DEFAULT_RATE: float = 0.5
+_MODEL_BERT: str = "microsoft/llmlingua-2-bert-base-multilingual-cased-meetingbank"
+_MODEL_XLM: str = "microsoft/llmlingua-2-xlm-roberta-large-meetingbank"
+
+
+class LLMLinguaCompressor:
+    """Opt-in LLMLingua-2 prose compressor."""
+
+    def __init__(
+        self,
+        model_name: str = _MODEL_BERT,
+        device_map: str = "cpu",
+        rate: float = _DEFAULT_RATE,
+    ) -> None:
+        import os
+        if os.environ.get("SLM_DISABLE_HF_DOWNLOAD", "0") == "1":
+            raise ImportError(
+                "LLMLingua-2 model download blocked: SLM_DISABLE_HF_DOWNLOAD=1. "
+                "Set compress_llmlingua_allow_download=true in optimize.json."
+            )
+        try:
+            from llmlingua import PromptCompressor  # type: ignore[import]
+        except ImportError as e:
+            raise ImportError(
+                "llmlingua package not installed. Install: pip install llmlingua."
+            ) from e
+
+        logger.info("Loading LLMLingua-2 model=%s device=%s", model_name, device_map)
+        self._compressor: Any = PromptCompressor(
+            model_name=model_name,
+            use_llmlingua2=True,
+            device_map=device_map,
+        )
+        self._rate = rate
+        logger.info("LLMLingua-2 loaded successfully model=%s", model_name)
+
+    def compress(self, text: str, rate: float | None = None) -> str:
+        """Compress prose text using LLMLingua-2. Fail-open: returns original on error."""
+        effective_rate = rate if rate is not None else self._rate
+        try:
+            result = self._compressor.compress_prompt(
+                [text],
+                rate=effective_rate,
+                use_token_level_filter=True,
+            )
+            compressed = result.get("compressed_prompt", text)
+            if not isinstance(compressed, str) or not compressed:
+                logger.warning("LLMLingua-2 returned unexpected output — passthrough")
+                return text
+            return compressed
+        except Exception as exc:
+            logger.warning("LLMLingua-2 compress failed — passthrough: %s", exc)
+            return text

package/src/superlocalmemory/optimize/compress/router.py

@@ -0,0 +1,548 @@
+# compress/router.py
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later
+#
+# Routing pattern adapted from:
+#   headroom/transforms/content_router.py (Apache-2.0, Headroom contributors)
+#   Specifically: ContentRouter._determine_strategy(), _strategy_from_detection()
+#   Attribution: See ATTRIBUTION.md.
+
+"""CompressRouter — implements CompressHook, dispatches to sub-compressors.
+
+INTERFACE-CONTRACT v2.2 §3 defines: compress(ProxyRequest) → ProxyRequest.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import threading
+from dataclasses import dataclass
+from typing import Any
+
+from superlocalmemory.optimize.proxy.lifecycle import ProxyRequest, CompressHook
+from superlocalmemory.optimize.config.store import ConfigStore
+
+logger = logging.getLogger("slm.optimize.compress.router")
+
+_MIN_CHARS_FOR_COMPRESSION: int = 500
+_MIN_RATIO_STRUCTURED: float = 0.60
+
+
+class CompressRouter:
+    """Implements CompressHook Protocol per INTERFACE-CONTRACT §3.
+
+    compress(req: ProxyRequest) → ProxyRequest
+    on_compress(before_tokens, after_tokens, lossy) — metrics callback
+
+    Singleton per daemon instance.
+    """
+
+    _instance: "CompressRouter | None" = None
+    _lock: threading.Lock = threading.Lock()
+
+    @classmethod
+    def get_instance(cls) -> "CompressRouter":
+        if cls._instance is None:
+            with cls._lock:
+                if cls._instance is None:
+                    cls._instance = cls()
+        return cls._instance
+
+    def __init__(self) -> None:
+        self._json_compressor: "JSONCompressor | None" = None
+        self._code_compressor: "CodeCompressor | None" = None
+        self._llmlingua_compressor: "LLMLinguaCompressor | None" = None
+        self._ccr_store: "CCRStore | None" = None
+        self._aligner: "CacheAligner | None" = None
+        self._config_store: ConfigStore | None = None
+        self._metrics_counters: Any = None
+
+    # ── CompressHook Protocol (INTERFACE-CONTRACT §3) ──────────────────────
+
+    def compress(self, req: ProxyRequest) -> ProxyRequest:
+        """Compress request body. Called by proxy after cache miss.
+
+        CONTRACT §3: compress(req: ProxyRequest) -> ProxyRequest (NOT ctx → CompressResult).
+        Returns req unchanged on error / no-op (fail-open).
+        """
+        try:
+            cfg = self._get_config()
+
+            if not cfg.compress_enabled:
+                return req
+            if req.stream:
+                return req
+            if req.has_tools:
+                return req  # §6.5 safety rule
+
+            body = dict(req.body)
+            messages = body.get("messages", [])
+            if not isinstance(messages, list):
+                return req
+
+            # Step 5: CacheAligner on system prompt (detection only)
+            system_text = body.get("system", "")
+            if isinstance(system_text, str) and system_text:
+                aligner = self._get_aligner()
+                align_result = aligner.detect(system_text)
+                if align_result.findings:
+                    logger.warning(
+                        "[%s] CacheAligner: %d volatile tokens — "
+                        "provider prefix cache may be unstable: %s",
+                        req.request_id,
+                        len(align_result.findings),
+                        [f.label for f in align_result.findings[:5]],
+                    )
+
+            # Step 6: compress each content block
+            aggressive = cfg.compress_mode == "aggressive"
+            protect_recent = cfg.compress_protect_recent
+            new_messages, tokens_before, tokens_after, strategy = self._compress_messages(
+                messages=messages,
+                aggressive=aggressive,
+                protect_recent=protect_recent,
+                request_id=req.request_id,
+                model=body.get("model", ""),
+                tenant_id="default",
+            )
+
+            if tokens_after >= tokens_before:
+                return req  # no improvement
+
+            body["messages"] = new_messages
+            new_bytes = json.dumps(body, ensure_ascii=False, separators=(",", ":")).encode()
+
+            # CONTRACT §3: fire on_compress metrics callback
+            lossy = strategy == "llmlingua2_prose"
+            self.on_compress(tokens_before, tokens_after, lossy)
+
+            return ProxyRequest(
+                provider=req.provider,
+                method=req.method,
+                path=req.path,
+                headers=req.headers,
+                body=body,
+                body_bytes=new_bytes,
+                request_id=req.request_id,
+                stream=req.stream,
+                has_tools=req.has_tools,
+            )
+
+        except Exception as exc:
+            logger.warning("[%s] CompressRouter.compress failed (fail-open): %s",
+                           req.request_id if hasattr(req, 'request_id') else '?', exc)
+            return req
+
+    def on_compress(self, before_tokens: int, after_tokens: int, lossy: bool) -> None:
+        """Metrics callback — CONTRACT §3. MUST NOT raise."""
+        try:
+            saved = max(0, before_tokens - after_tokens)
+            if self._metrics_counters is not None:
+                # M-02: Call proper method instead of accessing private attribute
+                self._metrics_counters.on_compress(saved, lossy)
+            logger.debug("on_compress: saved=%d tokens lossy=%s", saved, lossy)
+        except Exception as exc:
+            logger.debug("on_compress metrics update failed (non-fatal): %s", exc)
+
+    def set_metrics(self, counters: Any) -> None:
+        self._metrics_counters = counters
+
+    # ── Internal routing ──────────────────────────────────────────────────
+
+    def _compress_messages(
+        self,
+        messages: list[dict[str, Any]],
+        aggressive: bool,
+        protect_recent: int,
+        request_id: str,
+        model: str,
+        tenant_id: str,
+    ) -> tuple[list[dict[str, Any]], int, int, str]:
+        total_before = 0
+        total_after = 0
+        primary_strategy = "none"
+        new_messages: list[dict[str, Any]] = []
+
+        protect_indices = set(range(max(0, len(messages) - protect_recent), len(messages)))
+
+        for idx, msg in enumerate(messages):
+            role = msg.get("role", "")
+            is_tool_msg = (
+                role == "tool"
+                or role == "user"
+                or _msg_has_tool_result(msg)
+            )
+            if idx in protect_indices or is_tool_msg:
+                new_messages.append(msg)
+                continue
+
+            new_content, before, after, strat = self._compress_content_block(
+                content=msg.get("content", ""),
+                aggressive=aggressive,
+                request_id=request_id,
+                model=model,
+                tenant_id=tenant_id,
+            )
+            total_before += before
+            total_after += after
+            if strat != "none":
+                primary_strategy = strat
+
+            new_msg = dict(msg)
+            new_msg["content"] = new_content
+            new_messages.append(new_msg)
+
+        return new_messages, total_before, total_after, primary_strategy
+
+    def _compress_content_block(
+        self,
+        content: Any,
+        aggressive: bool,
+        request_id: str,
+        model: str,
+        tenant_id: str,
+    ) -> tuple[Any, int, int, str]:
+        if isinstance(content, str):
+            return self._compress_text(content, aggressive, request_id, model, tenant_id)
+
+        if isinstance(content, list):
+            new_blocks: list[Any] = []
+            total_before = 0
+            total_after = 0
+            primary = "none"
+            for block in content:
+                if not isinstance(block, dict):
+                    new_blocks.append(block)
+                    continue
+                block_type = block.get("type", "")
+                if block_type in ("text", "tool_result"):
+                    text = block.get("text", "") or _tool_result_text(block)
+                    if len(text) < _MIN_CHARS_FOR_COMPRESSION:
+                        new_blocks.append(block)
+                        continue
+                    new_text, before, after, strat = self._compress_text(
+                        text, aggressive, request_id, model, tenant_id
+                    )
+                    total_before += before
+                    total_after += after
+                    if strat != "none":
+                        primary = strat
+                    new_block = dict(block)
+                    if block_type == "text":
+                        new_block["text"] = new_text
+                    else:
+                        new_block = _set_tool_result_text(new_block, new_text)
+                    new_blocks.append(new_block)
+                else:
+                    new_blocks.append(block)
+            return new_blocks, total_before, total_after, primary
+
+        return content, 0, 0, "none"
+
+    def _compress_text(
+        self,
+        text: str,
+        aggressive: bool,
+        request_id: str,
+        model: str,
+        tenant_id: str,
+    ) -> tuple[str, int, int, str]:
+        tokens_before = _token_estimate(text)
+
+        # JSON detection
+        stripped = text.strip()
+        if stripped.startswith(("{", "[")):
+            try:
+                parsed = json.loads(stripped)
+                compressor = self._get_json_compressor()
+                compressed = compressor.compress(parsed)
+                tokens_after = _token_estimate_structured(compressed)
+                tokens_before_adj = _token_estimate_structured(text)
+                ratio = tokens_after / tokens_before_adj if tokens_before_adj else 1.0
+                if ratio < _MIN_RATIO_STRUCTURED:
+                    # B-03: store-before-compress
+                    ccr_id = self._ccr_store_original(text.encode(), model, tenant_id)
+                    if ccr_id:
+                        try:
+                            obj = json.loads(compressed)
+                            if isinstance(obj, dict):
+                                obj["__slm_ccr__"] = ccr_id
+                                compressed = json.dumps(obj, ensure_ascii=False, separators=(",", ":"))
+                            elif isinstance(obj, list):
+                                # RB-02: list-root embedding
+                                wrapper = {"__slm_ccr__": ccr_id, "__slm_data__": obj}
+                                compressed = json.dumps(wrapper, ensure_ascii=False, separators=(",", ":"))
+                        except Exception:
+                            pass
+                        self._ccr_update_compressed(ccr_id, compressed.encode())
+                    logger.debug("[%s] JSON compressed %.2f ratio ccr_id=%s", request_id, ratio, ccr_id)
+                    return compressed, tokens_before_adj, tokens_after, "extractive_json"
+                return text, tokens_before, tokens_before, "none"
+            except (json.JSONDecodeError, Exception):
+                pass
+
+        # Code detection
+        lang = _detect_language(text)
+        if lang is not None:
+            compressor = self._get_code_compressor()
+            # RB-03: compress first, compute ratio, then store CCR only if beneficial
+            compressed_probe = compressor.compress(text, language=lang, ccr_id="")
+            tokens_after = _token_estimate(compressed_probe)
+            ratio = tokens_after / tokens_before if tokens_before else 1.0
+            if ratio < _MIN_RATIO_STRUCTURED:
+                # B-03: store-before-compress
+                ccr_id = self._ccr_store_original(text.encode(), model, tenant_id)
+                compressed = compressor.compress(text, language=lang, ccr_id=ccr_id)
+                if ccr_id:
+                    self._ccr_update_compressed(ccr_id, compressed.encode())
+                logger.debug("[%s] Code compressed lang=%s ratio=%.2f ccr_id=%s",
+                             request_id, lang, ratio, ccr_id)
+                return compressed, tokens_before, tokens_after, "extractive_code"
+            return text, tokens_before, tokens_before, "none"
+
+        # Prose: only if aggressive mode AND compress_prose is enabled
+        # (Phase 3 — opt-in prose tier; off by default; gated by config
+        # field compress_prose added in LLD-04 INTERFACE-CONTRACT v2.)
+        cfg = self._get_config()
+        prose_enabled = bool(getattr(cfg, "compress_prose", False))
+        if aggressive and prose_enabled:
+            compressor = self._get_llmlingua_compressor()
+            if compressor is not None:
+                # B-03: store-before-compress
+                ccr_id = self._ccr_store_original(text.encode(), model, tenant_id)
+                compressed = compressor.compress(text)
+                if ccr_id:
+                    self._ccr_update_compressed(ccr_id, compressed.encode())
+                tokens_after = _token_estimate(compressed)
+                logger.info(
+                    "[%s] LLMLingua-2 prose compressed rate=%.2f ccr_id=%s (LOSSY)",
+                    request_id,
+                    tokens_after / tokens_before if tokens_before else 1.0,
+                    ccr_id,
+                )
+                return compressed, tokens_before, tokens_after, "llmlingua2_prose"
+
+        return text, tokens_before, tokens_before, "none"
+
+    # ── Lazy loaders ─────────────────────────────────────────────────────
+
+    def _get_json_compressor(self) -> "JSONCompressor":
+        if self._json_compressor is None:
+            from superlocalmemory.optimize.compress.extractive_json import JSONCompressor
+            self._json_compressor = JSONCompressor()
+        return self._json_compressor
+
+    def _get_code_compressor(self) -> "CodeCompressor":
+        if self._code_compressor is None:
+            from superlocalmemory.optimize.compress.extractive_code import CodeCompressor
+            self._code_compressor = CodeCompressor()
+        return self._code_compressor
+
+    def _get_llmlingua_compressor(self) -> "LLMLinguaCompressor | None":
+        if self._llmlingua_compressor is None:
+            try:
+                from superlocalmemory.optimize.compress.prose_llmlingua import LLMLinguaCompressor
+                self._llmlingua_compressor = LLMLinguaCompressor()
+            except ImportError:
+                logger.warning("LLMLinguaCompressor not available — prose compression disabled")
+                return None
+        return self._llmlingua_compressor
+
+    def _get_ccr_store(self) -> "CCRStore":
+        if self._ccr_store is None:
+            from superlocalmemory.optimize.compress.ccr import CCRStore
+            self._ccr_store = CCRStore()
+        return self._ccr_store
+
+    def _get_aligner(self) -> "CacheAligner":
+        if self._aligner is None:
+            from superlocalmemory.optimize.compress.align import CacheAligner
+            self._aligner = CacheAligner()
+        return self._aligner
+
+    def _get_config(self):
+        if self._config_store is None:
+            self._config_store = ConfigStore()
+        return self._config_store.get()
+
+    # ── CCR helpers ───────────────────────────────────────────────────────
+
+    def _ccr_store_original(self, original_bytes: bytes, model: str, tenant_id: str) -> str:
+        """B-03: Store original BEFORE compression. Returns ccr_id or '' on failure."""
+        try:
+            store = self._get_ccr_store()
+            return store.store(original=original_bytes, model=model, tenant_id=tenant_id)
+        except Exception as exc:
+            logger.warning("CCR store failed (non-fatal): %s", exc)
+            return ""
+
+    def _ccr_update_compressed(self, ccr_id: str, compressed_bytes: bytes) -> None:
+        """B-03: Update CCR row with compressed bytes after compression completes."""
+        try:
+            store = self._get_ccr_store()
+            store.update_compressed(ccr_id, compressed_bytes)
+        except Exception as exc:
+            logger.debug("CCR update_compressed failed (non-fatal): %s", exc)
+
+    # ── Public convenience method (M-06) ──────────────────────────────────
+
+    def compress_text(self, text: str, strategy: str = "auto") -> "CompressTextResult":
+        """Convenience method for test harness. NEVER raises."""
+        try:
+            cfg = self._get_config()
+            aggressive = cfg.compress_mode == "aggressive"
+            compressed, tb, ta, strat = self._compress_text(
+                text, aggressive, request_id="eval", model="", tenant_id="default"
+            )
+            return CompressTextResult(
+                compressed_text=compressed, strategy=strat,
+                tokens_before=tb, tokens_after=ta,
+            )
+        except Exception as exc:
+            logger.debug("compress_text failed (non-fatal): %s", exc)
+            return CompressTextResult(
+                compressed_text=text, strategy="none",
+                tokens_before=len(text.split()), tokens_after=len(text.split()),
+            )
+
+
+@dataclass
+class CompressTextResult:
+    compressed_text: str
+    strategy: str  # "extractive_json" | "extractive_code" | "llmlingua2_prose" | "none"
+    tokens_before: int
+    tokens_after: int
+
+
+# ── Module-level helpers ──────────────────────────────────────────────────────
+
+def _token_estimate(text: str) -> int:
+    return len(text.split()) if text else 0
+
+
+def _token_estimate_structured(text: str) -> int:
+    return max(1, len(text) // 4) if text else 0
+
+
+def _msg_has_tool_result(msg: dict) -> bool:
+    """B-09: Detect historical tool_result blocks in messages."""
+    content = msg.get("content", "")
+    if isinstance(content, list):
+        for block in content:
+            if not isinstance(block, dict):
+                continue
+            if block.get("type") == "tool_result":
+                return True
+            if "tool_use_id" in block:
+                return True
+    return False
+
+
+def _detect_language(text: str) -> str | None:
+    """Detect programming language. Returns None if ambiguous.
+
+    B-11: Line-start anchored regex. Threshold = 3 signal lines.
+    """
+    import re
+
+    if not text or len(text) < 50:
+        return None
+
+    lines = text.split("\n", 30)
+
+    if lines and lines[0].startswith("#!"):
+        shebang = lines[0].lower()
+        if "python" in shebang:
+            return "python"
+        if "node" in shebang or "javascript" in shebang:
+            return "javascript"
+
+    if lines and lines[0].startswith("```"):
+        lang_hint = lines[0][3:].strip().lower()
+        _KNOWN = {"python", "javascript", "js", "typescript", "ts", "go", "rust", "java", "cpp", "c++", "c"}
+        if lang_hint in _KNOWN:
+            if lang_hint in ("cpp", "c++"):
+                return "cpp"
+            if lang_hint in ("js", "typescript", "ts"):
+                return "javascript"
+            return lang_hint
+
+    _LANG_PATTERNS: dict[str, list[str]] = {
+        "python": [
+            r"^\s*(async\s+)?def\s+\w+\s*\(",
+            r"^\s*class\s+\w+[\s:(]",
+            r"^\s*import\s+\w+",
+            r"^\s*from\s+\w+\s+import\s+",
+        ],
+        "javascript": [
+            r"^\s*(async\s+)?function\s+\w+\s*\(",
+            r"^\s*class\s+\w+(\s+extends)?",
+            r"^\s*const\s+\w+\s*=",
+            r"^\s*import\s+.+from\s+['\"]",
+            r"^\s*export\s+(default\s+|const\s+|class\s+)",
+        ],
+        "go": [
+            r"^\s*func\s+(\(\w[\w\s\*]*\)\s+)?\w+\s*\(",
+            r"^\s*package\s+\w+",
+            r"^\s*import\s+[\(\"\`]",
+            r"^\s*type\s+\w+\s+(struct|interface)\s*\{",
+        ],
+        "rust": [
+            r"^\s*(pub\s+)?(async\s+)?fn\s+\w+",
+            r"^\s*use\s+\w+",
+            r"^\s*(pub\s+)?struct\s+\w+",
+            r"^\s*impl(\s+\w+)?\s+",
+        ],
+        "java": [
+            r"^\s*(public|private|protected)\s+(static\s+)?\w+\s+\w+\s*\(",
+            r"^\s*import\s+[\w\.]+;",
+            r"^\s*(public|private|protected)?\s*class\s+\w+",
+        ],
+    }
+
+    def _count_signals(patterns: list[str]) -> int:
+        count = 0
+        for line in lines:
+            for pat in patterns:
+                if re.search(pat, line):
+                    count += 1
+                    break
+        return count
+
+    scores: dict[str, int] = {
+        lang: _count_signals(patterns)
+        for lang, patterns in _LANG_PATTERNS.items()
+    }
+    best_lang, best_score = max(scores.items(), key=lambda kv: kv[1])
+    if best_score >= 3:
+        return best_lang
+
+    return None
+
+
+def _tool_result_text(block: dict) -> str:
+    content = block.get("content", "")
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        parts = [b.get("text", "") for b in content if isinstance(b, dict) and b.get("type") == "text"]
+        return "\n".join(parts)
+    return ""
+
+
+def _set_tool_result_text(block: dict, new_text: str) -> dict:
+    content = block.get("content", "")
+    if isinstance(content, str):
+        return {**block, "content": new_text}
+    if isinstance(content, list):
+        new_content = []
+        replaced = False
+        for b in content:
+            if not replaced and isinstance(b, dict) and b.get("type") == "text":
+                new_content.append({**b, "text": new_text})
+                replaced = True
+            else:
+                new_content.append(b)
+        return {**block, "content": new_content}
+    return block

package/src/superlocalmemory/optimize/config/__init__.py

@@ -0,0 +1,35 @@
+"""Module-level accessor for OptimizeConfig (INTERFACE-CONTRACT §2).
+
+LLD-01 (and all other Optimize LLDs) import get_optimize_config() from this
+module. They NEVER construct ConfigStore themselves or read optimize.json directly.
+"""
+
+from __future__ import annotations
+
+from superlocalmemory.optimize.config.schema import OptimizeConfig
+
+_store: "ConfigStore | None" = None
+
+
+def get_optimize_config() -> OptimizeConfig:
+    """Return the current active OptimizeConfig (thread-safe, no I/O)."""
+    if _store is None:
+        from superlocalmemory.optimize.config.defaults import DEFAULT_OPTIMIZE_CONFIG
+        return DEFAULT_OPTIMIZE_CONFIG
+    return _store.get()
+
+
+def load_optimize_config() -> OptimizeConfig:
+    """Alias of get_optimize_config() — INTERFACE-CONTRACT v2 §2."""
+    return get_optimize_config()
+
+
+def _set_config_store(store: "ConfigStore") -> None:
+    global _store
+    _store = store
+
+
+def _reset_config_store() -> None:
+    """Reset the module-level store (testing only)."""
+    global _store
+    _store = None