superlocalmemory 4.1.13 → 4.1.14

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

@@ -1,17 +0,0 @@
-# compress/__init__.py
-# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
-# Licensed under AGPL-3.0-or-later
-
-"""SLM v3.6 Optimize — Compression module.
-
-Public surface:
-    CompressRouter  — implements CompressHook Protocol from lifecycle.py
-    CCRStore        — CCR original storage and retrieval
-    CacheAligner    — volatile-token detection for system prompt prefix stability
-"""
-
-from superlocalmemory.optimize.compress.router import CompressRouter, CompressTextResult
-from superlocalmemory.optimize.compress.ccr import CCRStore
-from superlocalmemory.optimize.compress.align import CacheAligner, AlignResult
-
-__all__ = ["CompressRouter", "CompressTextResult", "CCRStore", "CacheAligner", "AlignResult"]

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

@@ -1,159 +0,0 @@
-# compress/align.py
-# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
-# Licensed under AGPL-3.0-or-later
-
-"""CacheAligner — flags volatile tokens in a system prompt.
-
-A "volatile" token is one that differs between otherwise-identical requests —
-a UUID, an ISO-8601 timestamp, a JWT, or a hex digest. When such tokens sit in
-the stable prefix of a prompt they break provider prefix caching, so the router
-surfaces them. This module only *detects*; it never rewrites the prompt.
-"""
-
-from __future__ import annotations
-
-import base64
-import binascii
-import logging
-import uuid as _uuid
-from dataclasses import dataclass, field
-from datetime import datetime
-
-logger = logging.getLogger("slm.optimize.compress.align")
-
-_HEX_HASH_LENGTHS = frozenset({32, 40, 64})   # md5 / sha1 / sha256 hex widths
-_UUID_CANONICAL_LEN = 36                       # 8-4-4-4-12, dashes included
-_JWT_SEGMENTS = 3                              # header.payload.signature
-_JWT_MIN_SEGMENT_BYTES = 4
-_MAX_FINDINGS = 20                             # cap the sample list we retain
-_SAMPLE_LEN = 20                               # chars kept per finding sample
-_TOKEN_STRIP = ".,;:!?\"'()[]{}<>`|\\"         # trimmed off each raw token
-
-_LABEL_UUID = "uuid"
-_LABEL_ISO8601 = "iso8601"
-_LABEL_JWT = "jwt"
-_LABEL_HEX_HASH = "hex_hash"
-
-
-@dataclass(frozen=True)
-class VolatileFinding:
-    label: str
-    sample: str
-
-
-@dataclass
-class AlignResult:
-    prefix_stable: bool = True
-    stability_score: float = 1.0
-    findings: list[VolatileFinding] = field(default_factory=list)
-    total_tokens_scanned: int = 0
-
-
-class CacheAligner:
-    """Detects volatile tokens in system prompts. No mutation. Thread-safe."""
-
-    def detect(self, system_prompt: str) -> AlignResult:
-        try:
-            return _detect(system_prompt)
-        except Exception as exc:
-            logger.debug("CacheAligner.detect failed (non-fatal): %s", exc)
-            return AlignResult()
-
-
-def _detect(text: str) -> AlignResult:
-    tokens = _split_tokens(text)
-    findings: list[VolatileFinding] = []
-    volatile = 0
-    for token in tokens:
-        label = _classify_token(token)
-        if label is None:
-            continue
-        volatile += 1
-        if len(findings) < _MAX_FINDINGS:
-            findings.append(VolatileFinding(label=label, sample=token[:_SAMPLE_LEN]))
-
-    total = len(tokens)
-    score = round(1.0 - volatile / total, 4) if total else 1.0
-    return AlignResult(
-        prefix_stable=(volatile == 0),
-        stability_score=score,
-        findings=findings,
-        total_tokens_scanned=total,
-    )
-
-
-def _split_tokens(content: str) -> list[str]:
-    """Whitespace-split, then strip surrounding punctuation/quoting from each
-    token so a value wrapped in backticks or brackets is still recognised."""
-    if not content:
-        return []
-    tokens: list[str] = []
-    for raw in content.split():
-        cleaned = raw.strip(_TOKEN_STRIP)
-        if cleaned:
-            tokens.append(cleaned)
-    return tokens
-
-
-def _classify_token(token: str) -> str | None:
-    """Return the volatile-kind label for a token, or None when it is stable.
-
-    Ordered most-specific first: a canonical-length UUID before a dotted JWT,
-    then timestamps, then bare hex digests.
-    """
-    if _is_uuid(token):
-        return _LABEL_UUID
-    if "." in token and _is_jwt_shape(token):
-        return _LABEL_JWT
-    if _is_iso8601(token):
-        return _LABEL_ISO8601
-    if _is_hex_hash(token):
-        return _LABEL_HEX_HASH
-    return None
-
-
-def _is_uuid(token: str) -> bool:
-    if len(token) != _UUID_CANONICAL_LEN or token.count("-") != 4:
-        return False
-    try:
-        _uuid.UUID(token)
-    except (ValueError, AttributeError):
-        return False
-    return True
-
-
-def _is_iso8601(token: str) -> bool:
-    if len(token) < 8 or ("T" not in token and "-" not in token):
-        return False
-    # datetime.fromisoformat pre-3.11 rejects a trailing 'Z'; normalise it.
-    candidate = token[:-1] + "+00:00" if token.endswith("Z") else token
-    try:
-        datetime.fromisoformat(candidate)
-    except (ValueError, TypeError):
-        return False
-    return True
-
-
-def _is_jwt_shape(token: str) -> bool:
-    segments = token.split(".")
-    if len(segments) != _JWT_SEGMENTS:
-        return False
-    for seg in segments:
-        if len(seg) < _JWT_MIN_SEGMENT_BYTES:
-            return False
-        padded = seg + "=" * (-len(seg) % 4)  # restore base64url padding
-        try:
-            base64.urlsafe_b64decode(padded.encode("ascii"))
-        except (binascii.Error, ValueError, UnicodeEncodeError):
-            return False
-    return True
-
-
-def _is_hex_hash(token: str) -> bool:
-    if len(token) not in _HEX_HASH_LENGTHS:
-        return False
-    try:
-        int(token, 16)
-    except ValueError:
-        return False
-    return True

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

@@ -1,116 +0,0 @@
-# compress/ccr.py
-# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
-# Licensed under AGPL-3.0-or-later
-#
-# Storage: llmcache_ccr table defined in INTERFACE-CONTRACT §1.
-# Database access: CacheDB.ccr_put() and CacheDB.ccr_get() per INTERFACE-CONTRACT §1.
-
-"""CCRStore — stores pre-compression originals, provides retrieval tool."""
-
-from __future__ import annotations
-
-import logging
-import re
-import threading
-from typing import TYPE_CHECKING
-
-if TYPE_CHECKING:
-    from superlocalmemory.optimize.storage.db import CacheDB
-
-logger = logging.getLogger("slm.optimize.compress.ccr")
-
-# SEC-C-04: UUID4 format validator — only ^UUID4^ values pass
-_UUID4_RE = re.compile(
-    r'^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$'
-)
-
-
-class CCRStore:
-    """Stores compression originals and retrieves them by ccr_id.
-
-    Thread-safe. Singleton per daemon instance.
-    """
-
-    _instance: "CCRStore | None" = None
-    _lock: threading.Lock = threading.Lock()
-
-    @classmethod
-    def get_instance(cls) -> "CCRStore":
-        if cls._instance is None:
-            with cls._lock:
-                if cls._instance is None:
-                    cls._instance = cls()
-        return cls._instance
-
-    def __init__(self) -> None:
-        self._db: "CacheDB | None" = None
-
-    def store(
-        self,
-        original: bytes,
-        model: str = "",
-        tenant_id: str = "default",
-        ttl_seconds: int | None = None,
-    ) -> str:
-        """Store a pre-compression original. Returns ccr_id (UUID4) or '' on failure.
-
-        B-03: Called BEFORE compression runs.
-        RB-05: Only original bytes accepted; compressed bytes stored via update_compressed().
-        """
-        try:
-            import uuid as _uuid_mod
-            import time as _time_mod
-            ccr_id = str(_uuid_mod.uuid4())
-            db = self._get_db()
-            ttl_expires = (
-                _time_mod.time() + ttl_seconds
-                if ttl_seconds is not None
-                else None
-            )
-            db.ccr_put(ccr_id, original, ttl_expires=ttl_expires, tenant_id=tenant_id)
-            logger.debug("CCR stored ccr_id=%s orig_bytes=%d tenant=%s", ccr_id, len(original), tenant_id)
-            return ccr_id
-        except Exception as exc:
-            logger.warning("CCRStore.store failed (fail-open): %s", exc)
-            return ""
-
-    def update_compressed(self, ccr_id: str, compressed_bytes: bytes) -> None:
-        """Update the compressed_hash for an existing CCR row. Non-fatal if fails."""
-        try:
-            db = self._get_db()
-            if hasattr(db, "ccr_update_compressed"):
-                db.ccr_update_compressed(ccr_id, compressed_bytes)
-        except Exception as exc:
-            logger.debug("CCRStore.update_compressed failed (non-fatal): %s", exc)
-
-    def retrieve(self, ccr_id: str, *, tenant_id: str = "default") -> bytes | None:
-        """Retrieve a CCR original by ccr_id scoped to tenant. Returns None if not found or TTL expired.
-
-        H-02: tenant_id enforces row-level isolation — a caller cannot retrieve
-        content stored under a different tenant's scope.
-        """
-        try:
-            db = self._get_db()
-            return db.ccr_get(ccr_id, tenant_id=tenant_id)
-        except Exception as exc:
-            logger.warning("CCRStore.retrieve failed (ccr_id=%s): %s", ccr_id, exc)
-            return None
-
-    def delete(self, ccr_id: str, *, tenant_id: str = "default") -> None:
-        """Delete a CCR row by ccr_id scoped to tenant. Idempotent — never raises.
-
-        Defensive delete — idempotent: deleting a non-existent ccr_id is a no-op.
-        H-02: tenant_id guard prevents cross-tenant deletion.
-        """
-        try:
-            db = self._get_db()
-            db.ccr_delete(ccr_id, tenant_id=tenant_id)
-            logger.debug("CCR deleted ccr_id=%s tenant=%s", ccr_id, tenant_id)
-        except Exception as exc:
-            logger.warning("CCRStore.delete failed (non-fatal): %s", exc)
-
-    def _get_db(self) -> "CacheDB":
-        if self._db is None:
-            from superlocalmemory.optimize.storage.db import CacheDB
-            self._db = CacheDB()
-        return self._db

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

@@ -1,71 +0,0 @@
-# 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_XLM,
-        device_map: str = "cpu",
-        rate: float = _DEFAULT_RATE,
-    ) -> None:
-        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