superlocalmemory 3.5.7 → 3.6.0

package/src/superlocalmemory/optimize/adapters/_agent_registry.py

@@ -0,0 +1,120 @@
+"""Agent redirect registry — DATA ONLY, no logic.
+
+PORT: 8765 (INTERFACE-CONTRACT §0). There is NO port 52415 anywhere.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+AGENT_REGISTRY: dict[str, dict[str, Any]] = {
+    "claude": {
+        "binary": "claude",
+        "mechanism": "env",
+        "env_vars": {"ANTHROPIC_BASE_URL": "http://127.0.0.1:8765"},
+        "settings_path": None,
+        "protocol": "anthropic",
+        "print_only": False,
+        "help_text": (
+            "Launches `claude` with ANTHROPIC_BASE_URL pointing at the SLM proxy.\n"
+            "All Claude Code calls are intercepted: cache checked, response stored."
+        ),
+    },
+    "claude-settings": {
+        "binary": None,
+        "mechanism": "settings-file",
+        "settings_path": "~/.claude/settings.json",
+        "env_vars": {"ANTHROPIC_BASE_URL": "http://127.0.0.1:8765"},
+        "protocol": "anthropic",
+        "print_only": False,
+        "help_text": (
+            "Writes ANTHROPIC_BASE_URL into ~/.claude/settings.json env block."
+        ),
+    },
+    "antigravity": {
+        "binary": "agy",
+        "mechanism": "print-only",
+        "protocol": "anthropic",
+        "print_only": True,
+        "help_text": (
+            "Antigravity (agy) redirect must be verified at runtime.\n"
+            "Run: agy --help | grep -i base\n"
+            "Then export the appropriate env var manually."
+        ),
+    },
+    "cline": {
+        "binary": None,
+        "mechanism": "config-file",
+        "config_path": "{vscode_user_dir}/settings.json",
+        "config_key": "cline.openAiApiBase",
+        "config_value": "http://127.0.0.1:8765/v1",
+        "protocol": "openai",
+        "print_only": False,
+        "help_text": (
+            "Edits VS Code user settings to set cline.openAiApiBase."
+        ),
+    },
+    "opencode": {
+        "binary": "opencode",
+        "mechanism": "print-only",
+        "protocol": "openai",
+        "print_only": True,
+        "help_text": (
+            "OpenCode redirect must be verified at runtime.\n"
+            "Run: opencode --print-config"
+        ),
+    },
+    "cursor": {
+        "binary": "cursor",
+        "mechanism": "print-only",
+        "protocol": "openai",
+        "print_only": True,
+        "help_text": (
+            "Cursor settings cannot be automated via env vars.\n"
+            "Manual: Settings → Models → Override OpenAI Base URL → http://127.0.0.1:8765/v1"
+        ),
+    },
+    "aider": {
+        "binary": "aider",
+        "mechanism": "env",
+        "env_vars": {
+            "OPENAI_API_BASE": "http://127.0.0.1:8765/v1",
+            "ANTHROPIC_BASE_URL": "http://127.0.0.1:8765",
+        },
+        "protocol": "both",
+        "print_only": False,
+        "help_text": (
+            "Launches `aider` with both OpenAI and Anthropic base URLs set."
+        ),
+    },
+    "codex": {
+        "binary": "codex",
+        "mechanism": "env",
+        "env_vars": {"OPENAI_BASE_URL": "http://127.0.0.1:8765/v1"},
+        "protocol": "openai",
+        "print_only": False,
+        "help_text": (
+            "Launches `codex` with OPENAI_BASE_URL pointing at the SLM proxy."
+        ),
+    },
+    "copilot": {
+        "binary": "copilot",
+        "mechanism": "print-only",
+        "protocol": "anthropic",
+        "print_only": True,
+        "help_text": (
+            "Copilot redirect must be verified at runtime.\n"
+            "Run: gh copilot --help | grep -i provider"
+        ),
+    },
+    "generic": {
+        "binary": None,
+        "mechanism": "print-only",
+        "protocol": "openai",
+        "print_only": True,
+        "help_text": (
+            "Generic OpenAI-compatible client:\n"
+            "  export OPENAI_BASE_URL=http://127.0.0.1:8765/v1"
+        ),
+    },
+}

package/src/superlocalmemory/optimize/adapters/anthropic_adapter.py

@@ -0,0 +1,115 @@
+"""SLM Anthropic SDK adapter.
+
+Adapted from OmniCache (MIT). See ATTRIBUTION.md.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from superlocalmemory.optimize.cache.manager import CacheManager
+    from superlocalmemory.optimize.config.schema import OptimizeConfig
+
+logger = logging.getLogger(__name__)
+
+
+def _detect_async_anthropic(client: Any) -> bool:
+    try:
+        from anthropic import AsyncAnthropic
+        return isinstance(client, AsyncAnthropic)
+    except ImportError:
+        return False
+
+
+class SLMAnthropicAdapter:
+    """Wraps anthropic.Anthropic (or AsyncAnthropic) messages with SLM cache."""
+
+    def __init__(
+        self,
+        client: Any,
+        cache_manager: "CacheManager",
+        config: "OptimizeConfig",
+        tenant_id: str = "default",
+    ) -> None:
+        self._original = client
+        self._cache_manager = cache_manager
+        self._cache_view = cache_manager.for_tenant(tenant_id)
+        self._config = config
+        self._tenant_id = tenant_id
+        self._is_async: bool = _detect_async_anthropic(client)
+        self.messages = _MessagesProxy(self)
+
+    def _build_cache_key(self, kwargs: dict) -> str:
+        model = kwargs.get("model", "unknown")
+        messages = kwargs.get("messages", [])
+        system = kwargs.get("system", "")
+        exclude = {"model", "messages", "system", "stream", "metadata"}
+        params = {k: v for k, v in kwargs.items() if k not in exclude}
+        return self._cache_manager.build_key(
+            {"model": model, "messages": messages, "system": system, "params": params},
+            self._tenant_id,
+        )
+
+    def _should_cache(self, kwargs: dict) -> bool:
+        if kwargs.get("stream", False):
+            return False
+        if kwargs.get("tools"):
+            return False
+        return True
+
+    def _messages_create_sync(self, **kwargs: Any) -> Any:
+        if not self._config.cache_enabled or not self._should_cache(kwargs):
+            return self._original.messages.create(**kwargs)
+        key = self._build_cache_key(kwargs)
+        if key is None:
+            return self._original.messages.create(**kwargs)
+        hit = self._cache_view.get(key)
+        if hit is not None:
+            try:
+                import json as _json
+                return _json.loads(hit.decode("utf-8"))
+            except Exception:
+                return self._original.messages.create(**kwargs)
+        response = self._original.messages.create(**kwargs)
+        try:
+            import json as _json
+            encoded = _json.dumps(response, default=str).encode("utf-8")
+            self._cache_view.set(key, encoded)
+        except Exception as exc:
+            logger.warning("SLMAnthropicAdapter: failed to cache response: %s", exc)
+        return response
+
+    async def _messages_create_async(self, **kwargs: Any) -> Any:
+        if not self._config.cache_enabled or not self._should_cache(kwargs):
+            return await self._original.messages.create(**kwargs)
+        key = self._build_cache_key(kwargs)
+        if key is None:
+            return await self._original.messages.create(**kwargs)
+        hit = self._cache_view.get(key)
+        if hit is not None:
+            try:
+                import json as _json
+                return _json.loads(hit.decode("utf-8"))
+            except Exception:
+                return await self._original.messages.create(**kwargs)
+        response = await self._original.messages.create(**kwargs)
+        try:
+            import json as _json
+            encoded = _json.dumps(response, default=str).encode("utf-8")
+            self._cache_view.set(key, encoded)
+        except Exception as exc:
+            logger.warning("SLMAnthropicAdapter: failed to cache response: %s", exc)
+        return response
+
+
+class _MessagesProxy:
+    def __init__(self, adapter: SLMAnthropicAdapter) -> None:
+        self._adapter = adapter
+
+    def create(self, **kwargs: Any) -> Any:
+        if self._adapter._is_async:
+            return self._adapter._messages_create_async(**kwargs)
+        return self._adapter._messages_create_sync(**kwargs)

package/src/superlocalmemory/optimize/adapters/openai_adapter.py

@@ -0,0 +1,125 @@
+"""SLM OpenAI SDK adapter.
+
+Adapted from OmniCache (MIT). See ATTRIBUTION.md.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from superlocalmemory.optimize.cache.manager import CacheManager
+    from superlocalmemory.optimize.config.schema import OptimizeConfig
+
+logger = logging.getLogger(__name__)
+
+
+def _detect_async_openai(client: Any) -> bool:
+    try:
+        from openai import AsyncOpenAI
+        return isinstance(client, AsyncOpenAI)
+    except ImportError:
+        return False
+
+
+class SLMOpenAIAdapter:
+    """Wraps openai.OpenAI (or AsyncOpenAI) with SLM cache hooks."""
+
+    def __init__(
+        self,
+        client: Any,
+        cache_manager: "CacheManager",
+        config: "OptimizeConfig",
+        tenant_id: str = "default",
+    ) -> None:
+        self._original = client
+        self._cache_manager = cache_manager
+        self._cache_view = cache_manager.for_tenant(tenant_id)
+        self._config = config
+        self._tenant_id = tenant_id
+        self._is_async: bool = _detect_async_openai(client)
+        self.chat = _ChatCompletionsProxy(self)
+
+    def _build_cache_key(self, kwargs: dict) -> str:
+        model = kwargs.get("model", "unknown")
+        messages = kwargs.get("messages", [])
+        exclude = {"model", "messages", "stream", "user", "request_id"}
+        params = {k: v for k, v in kwargs.items() if k not in exclude}
+        canonical = json.dumps(
+            {"messages": messages, "params": params},
+            sort_keys=True, default=str,
+        )
+        return self._cache_manager.build_key(
+            {"model": model, "messages": messages, "params": params},
+            self._tenant_id,
+        )
+
+    def _should_cache(self, kwargs: dict) -> bool:
+        if kwargs.get("stream", False):
+            return False
+        if kwargs.get("tools") or kwargs.get("functions"):
+            return False
+        return True
+
+    def _chat_create_sync(self, **kwargs: Any) -> Any:
+        if not self._config.cache_enabled or not self._should_cache(kwargs):
+            return self._original.chat.completions.create(**kwargs)
+        key = self._build_cache_key(kwargs)
+        if key is None:
+            return self._original.chat.completions.create(**kwargs)
+        hit = self._cache_view.get(key)
+        if hit is not None:
+            try:
+                import json as _json
+                return _json.loads(hit.decode("utf-8"))
+            except Exception:
+                return self._original.chat.completions.create(**kwargs)
+        response = self._original.chat.completions.create(**kwargs)
+        try:
+            import json as _json
+            encoded = _json.dumps(response, default=str).encode("utf-8")
+            self._cache_view.set(key, encoded)
+        except Exception as exc:
+            logger.warning("SLMOpenAIAdapter: failed to cache response: %s", exc)
+        return response
+
+    async def _chat_create_async(self, **kwargs: Any) -> Any:
+        if not self._config.cache_enabled or not self._should_cache(kwargs):
+            return await self._original.chat.completions.create(**kwargs)
+        key = self._build_cache_key(kwargs)
+        if key is None:
+            return await self._original.chat.completions.create(**kwargs)
+        hit = self._cache_view.get(key)
+        if hit is not None:
+            try:
+                import json as _json
+                return _json.loads(hit.decode("utf-8"))
+            except Exception:
+                return await self._original.chat.completions.create(**kwargs)
+        response = await self._original.chat.completions.create(**kwargs)
+        try:
+            import json as _json
+            encoded = _json.dumps(response, default=str).encode("utf-8")
+            self._cache_view.set(key, encoded)
+        except Exception as exc:
+            logger.warning("SLMOpenAIAdapter: failed to cache response: %s", exc)
+        return response
+
+
+class _ChatCompletionsProxy:
+    """Mimics openai.resources.chat.Chat interface: `client.chat.completions.create`."""
+
+    def __init__(self, adapter: SLMOpenAIAdapter) -> None:
+        self._adapter = adapter
+        self.completions = self._Completions(adapter)
+
+    class _Completions:
+        def __init__(self, adapter: SLMOpenAIAdapter) -> None:
+            self._adapter = adapter
+
+        def create(self, **kwargs: Any) -> Any:
+            if self._adapter._is_async:
+                return self._adapter._chat_create_async(**kwargs)
+            return self._adapter._chat_create_sync(**kwargs)

package/src/superlocalmemory/optimize/adapters/wrap.py

@@ -0,0 +1,188 @@
+"""slm wrap <agent> — table-driven per-agent proxy activation.
+
+PORT: 8765 (INTERFACE-CONTRACT §0). No 52415 anywhere in this file.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+from superlocalmemory.optimize.adapters._agent_registry import AGENT_REGISTRY
+from superlocalmemory.optimize.proxy.lifecycle import ensure_proxy_running, proxy_port
+
+
+def list_agents() -> list[str]:
+    """Return all registered agent keys."""
+    return list(AGENT_REGISTRY.keys())
+
+
+def wrap_agent(
+    agent_key: str,
+    agent_args: list[str],
+    *,
+    persistent: bool = False,
+    dry_run: bool = False,
+) -> int:
+    """Configure proxy redirection for <agent_key> and optionally launch it.
+
+    Returns:
+        0 on success, 1 on error, agent's exit code when subprocess launched.
+    """
+    if agent_key not in AGENT_REGISTRY:
+        known = ", ".join(AGENT_REGISTRY.keys())
+        print(
+            f"[slm wrap] Unknown agent '{agent_key}'. Known: {known}",
+            file=sys.stderr,
+        )
+        return 1
+
+    if not ensure_proxy_running():
+        print(
+            f"[slm wrap] proxy is not enabled in optimize.json — set "
+            f"`proxy_enabled: true` (port 8765) and re-run, or run "
+            f"`slm optimize on` first.",
+            file=sys.stderr,
+        )
+        return 1
+
+    port = proxy_port()
+    spec = AGENT_REGISTRY[agent_key]
+    mechanism = spec.get("mechanism", "print-only")
+
+    if mechanism == "print-only":
+        print(f"[slm wrap] {agent_key}: manual instructions")
+        print(spec.get("help_text", ""))
+        return 0
+
+    if mechanism == "settings-file":
+        # Persist env var to a settings file
+        settings_path_str = spec.get("settings_path", "")
+        env_vars = spec.get("env_vars", {})
+        if not env_vars:
+            print(f"[slm wrap] {agent_key}: no env vars to set", file=sys.stderr)
+            return 1
+        expanded = str(Path(settings_path_str).expanduser())
+        path = Path(expanded)
+        if dry_run:
+            print(f"[slm wrap] would write {path} with env={env_vars}")
+            return 0
+        existing: dict = {}
+        if path.exists():
+            try:
+                existing = json.loads(path.read_text(encoding="utf-8"))
+            except (json.JSONDecodeError, OSError, ValueError):
+                existing = {}
+        existing.setdefault("env", {})
+        for k, v in env_vars.items():
+            existing["env"][k] = v
+        try:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            _atomic_write_text(path, json.dumps(existing, indent=2))
+        except (OSError, ValueError) as exc:
+            print(f"[slm wrap] could not write {path}: {exc}", file=sys.stderr)
+            return 1
+        print(f"[slm wrap] wrote {path}")
+        return 0
+
+    if mechanism == "config-file":
+        # VS Code settings.json edit. config_path may be:
+        # - absolute path → use directly
+        # - template with {vscode_user_dir} → expand via _vscode_user_dir()
+        # - relative path → resolve against current working directory
+        config_value = spec.get("config_value", "")
+        config_key = spec.get("config_key", "")
+        config_path_str = spec.get("config_path", "")
+        if not config_path_str:
+            print("[slm wrap] no config_path specified", file=sys.stderr)
+            return 1
+        if "{vscode_user_dir}" in config_path_str:
+            vscode_dir = _vscode_user_dir()
+            if vscode_dir is None:
+                print("[slm wrap] VS Code user dir not found", file=sys.stderr)
+                return 1
+            path = Path(config_path_str.replace("{vscode_user_dir}", str(vscode_dir)))
+        else:
+            path = Path(config_path_str).expanduser()
+        if dry_run:
+            print(f"[slm wrap] would write {path} key={config_key} value={config_value}")
+            return 0
+        existing = {}
+        if path.exists():
+            try:
+                existing = json.loads(path.read_text(encoding="utf-8"))
+            except (json.JSONDecodeError, OSError):
+                existing = {}
+        existing[config_key] = config_value
+        try:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            _atomic_write_text(path, json.dumps(existing, indent=2))
+        except OSError as exc:
+            print(f"[slm wrap] could not write {path}: {exc}", file=sys.stderr)
+            return 1
+        print(f"[slm wrap] wrote {path}")
+        return 0
+
+    if mechanism == "env":
+        # Launch the binary with env vars injected
+        binary = spec.get("binary")
+        env_vars = spec.get("env_vars", {})
+        if not binary:
+            print(f"[slm wrap] {agent_key}: no binary specified", file=sys.stderr)
+            return 1
+        if shutil.which(binary) is None:
+            print(
+                f"[slm wrap] binary '{binary}' not found in PATH. "
+                f"Install {agent_key} or set PATH.",
+                file=sys.stderr,
+            )
+            return 1
+        full_env = os.environ.copy()
+        for k, v in env_vars.items():
+            full_env[k] = v.replace("{port}", str(port))
+        if dry_run:
+            print(f"[slm wrap] would exec: {binary} {' '.join(agent_args)}")
+            print(f"[slm wrap] env: {env_vars}")
+            return 0
+        try:
+            return subprocess.call([binary, *agent_args], env=full_env)
+        except FileNotFoundError as exc:
+            print(f"[slm wrap] could not launch {binary}: {exc}", file=sys.stderr)
+            return 1
+
+    print(f"[slm wrap] {agent_key}: unknown mechanism {mechanism!r}", file=sys.stderr)
+    return 1
+
+
+def _atomic_write_text(path: Path, content: str) -> None:
+    tmp = path.with_suffix(path.suffix + ".tmp")
+    with open(tmp, "w", encoding="utf-8") as f:
+        f.write(content)
+        f.flush()
+        os.fsync(f.fileno())
+    os.replace(tmp, path)
+    try:
+        os.chmod(path, 0o600)
+    except OSError:
+        pass
+
+
+def _vscode_user_dir() -> Path | None:
+    """Return the VS Code user settings directory for the current OS."""
+    if sys.platform == "darwin":
+        p = Path.home() / "Library" / "Application Support" / "Code" / "User"
+        return p if p.exists() or p.parent.exists() else None
+    if sys.platform.startswith("win"):
+        appdata = os.environ.get("APPDATA")
+        if appdata:
+            p = Path(appdata) / "Code" / "User"
+            return p
+        return None
+    # Linux
+    p = Path.home() / ".config" / "Code" / "User"
+    return p

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

@@ -0,0 +1,31 @@
+"""optimize/cache — exact-response cache (Phase 1)."""
+
+from __future__ import annotations
+
+from superlocalmemory.optimize.cache.exact import ExactCache
+from superlocalmemory.optimize.cache.invalidation import InvalidationEngine
+from superlocalmemory.optimize.cache.key_builder import CacheConfig, KeyBuilder
+from superlocalmemory.optimize.cache.manager import (
+    CacheManager,
+    NoOpSemantic,
+    SemanticTier,
+    _TenantScopedManager,
+)
+from superlocalmemory.optimize.cache.stampede import StampedeShield
+
+__all__ = [
+    "CacheManager",
+    "CacheView",
+    "ExactCache",
+    "InvalidationEngine",
+    "KeyBuilder",
+    "CacheConfig",
+    "StampedeShield",
+    "SemanticTier",
+    "NoOpSemantic",
+    "_TenantScopedManager",
+]
+
+
+# Lazy alias so import order doesn't matter
+CacheView = _TenantScopedManager