spatial-memory-mcp 1.0.3__py3-none-any.whl → 1.6.0__py3-none-any.whl

spatial_memory/core/embeddings.py

@@ -12,6 +12,11 @@ from typing import TYPE_CHECKING, Any, Literal, TypeVar
 
 import numpy as np
 
+from spatial_memory.core.circuit_breaker import (
+    CircuitBreaker,
+    CircuitOpenError,
+    CircuitState,
+)
 from spatial_memory.core.errors import ConfigurationError, EmbeddingError
 
 if TYPE_CHECKING:
@@ -158,6 +163,7 @@ class EmbeddingService:
 
     Supports local sentence-transformers models and optional OpenAI API.
     Uses ONNX Runtime by default for 2-3x faster inference.
+    Optionally uses a circuit breaker for fault tolerance with external services.
     """
 
     def __init__(
@@ -165,6 +171,11 @@ class EmbeddingService:
         model_name: str = "all-MiniLM-L6-v2",
         openai_api_key: str | Any | None = None,
         backend: EmbeddingBackend = "auto",
+        circuit_breaker: CircuitBreaker | None = None,
+        circuit_breaker_enabled: bool = True,
+        circuit_breaker_failure_threshold: int = 5,
+        circuit_breaker_reset_timeout: float = 60.0,
+        cache_max_size: int = 1000,
     ) -> None:
         """Initialize the embedding service.
 
@@ -174,6 +185,16 @@ class EmbeddingService:
                 Can be a string or a SecretStr (pydantic).
             backend: Inference backend. 'auto' uses ONNX if available (default),
                 'onnx' forces ONNX Runtime, 'pytorch' forces PyTorch.
+            circuit_breaker: Optional pre-configured circuit breaker instance.
+                If provided, other circuit breaker parameters are ignored.
+            circuit_breaker_enabled: Whether to enable circuit breaker for OpenAI calls.
+                Defaults to True. Only applies to OpenAI models.
+            circuit_breaker_failure_threshold: Number of consecutive failures before
+                opening the circuit. Default is 5.
+            circuit_breaker_reset_timeout: Seconds to wait before attempting recovery.
+                Default is 60.0 seconds.
+            cache_max_size: Maximum number of embeddings to cache (LRU eviction).
+                Default is 1000. Set to 0 to disable caching.
         """
         self.model_name = model_name
         # Handle both plain strings and SecretStr (pydantic)
@@ -191,7 +212,7 @@ class EmbeddingService:
 
         # Embedding cache (LRU with max size)
         self._embed_cache: OrderedDict[str, np.ndarray] = OrderedDict()
-        self._cache_max_size = 1000
+        self._cache_max_size = cache_max_size
         self._cache_lock = threading.Lock()
 
         # Determine if using OpenAI
@@ -203,6 +224,23 @@ class EmbeddingService:
                     "OpenAI API key required for OpenAI embedding models"
                 )
 
+        # Circuit breaker for OpenAI API calls (optional)
+        if circuit_breaker is not None:
+            self._circuit_breaker: CircuitBreaker | None = circuit_breaker
+        elif circuit_breaker_enabled and self.use_openai:
+            self._circuit_breaker = CircuitBreaker(
+                failure_threshold=circuit_breaker_failure_threshold,
+                reset_timeout=circuit_breaker_reset_timeout,
+                name=f"embedding_service_{model_name}",
+            )
+            logger.info(
+                f"Circuit breaker enabled for embedding service "
+                f"(threshold={circuit_breaker_failure_threshold}, "
+                f"timeout={circuit_breaker_reset_timeout}s)"
+            )
+        else:
+            self._circuit_breaker = None
+
     def _load_local_model(self) -> None:
         """Load local sentence-transformers model with ONNX or PyTorch backend."""
         if self._model is not None:
@@ -273,8 +311,11 @@ class EmbeddingService:
             raise EmbeddingError(f"Failed to initialize OpenAI client: {masked_error}") from e
 
     def _get_cache_key(self, text: str) -> str:
-        """Generate cache key from text content."""
-        return hashlib.md5(text.encode()).hexdigest()
+        """Generate cache key from text content.
+
+        Uses MD5 for speed (not security) - collisions are acceptable for cache.
+        """
+        return hashlib.md5(text.encode(), usedforsecurity=False).hexdigest()
 
     @property
     def dimensions(self) -> int:
@@ -300,6 +341,26 @@ class EmbeddingService:
             self._load_local_model()
         return self._active_backend or "pytorch"
 
+    @property
+    def circuit_state(self) -> CircuitState | None:
+        """Get the current circuit breaker state.
+
+        Returns:
+            CircuitState if circuit breaker is enabled, None otherwise.
+        """
+        if self._circuit_breaker is None:
+            return None
+        return self._circuit_breaker.state
+
+    @property
+    def circuit_breaker(self) -> CircuitBreaker | None:
+        """Get the circuit breaker instance.
+
+        Returns:
+            CircuitBreaker if enabled, None otherwise.
+        """
+        return self._circuit_breaker
+
     def embed(self, text: str) -> np.ndarray:
         """Generate embedding for a single text.
 
@@ -320,27 +381,31 @@ class EmbeddingService:
 
         # Generate embedding (outside lock to allow concurrent generation)
         if self.use_openai:
-            embedding = self._embed_openai([text])[0]
+            embedding = self._embed_openai_with_circuit_breaker([text])[0]
         else:
             embedding = self._embed_local([text])[0]
 
-        # Cache the result
-        with self._cache_lock:
-            # Check if another thread already cached it
-            if cache_key not in self._embed_cache:
-                # Evict oldest entries if at capacity
-                while len(self._embed_cache) >= self._cache_max_size:
-                    self._embed_cache.popitem(last=False)
-                self._embed_cache[cache_key] = embedding.copy()
-            else:
-                # Another thread cached it, move to end
-                self._embed_cache.move_to_end(cache_key)
+        # Cache the result (if caching enabled)
+        if self._cache_max_size > 0:
+            with self._cache_lock:
+                # Check if another thread already cached it
+                if cache_key not in self._embed_cache:
+                    # Evict oldest entries if at capacity
+                    while len(self._embed_cache) >= self._cache_max_size:
+                        self._embed_cache.popitem(last=False)
+                    self._embed_cache[cache_key] = embedding.copy()
+                else:
+                    # Another thread cached it, move to end
+                    self._embed_cache.move_to_end(cache_key)
 
         return embedding
 
     def embed_batch(self, texts: list[str]) -> list[np.ndarray]:
         """Generate embeddings for multiple texts.
 
+        Uses cache for already-embedded texts and only generates
+        embeddings for texts not in cache.
+
         Args:
             texts: List of texts to embed.
 
@@ -351,10 +416,47 @@ class EmbeddingService:
             logger.debug("embed_batch called with empty input, returning empty list")
             return []
 
-        if self.use_openai:
-            return self._embed_openai(texts)
-        else:
-            return self._embed_local(texts)
+        # If caching disabled, generate all embeddings directly
+        if self._cache_max_size <= 0:
+            if self.use_openai:
+                return self._embed_openai_with_circuit_breaker(texts)
+            else:
+                return self._embed_local(texts)
+
+        # Check cache for each text
+        results: list[np.ndarray | None] = [None] * len(texts)
+        texts_to_embed: list[tuple[int, str]] = []  # (index, text)
+
+        with self._cache_lock:
+            for i, text in enumerate(texts):
+                cache_key = self._get_cache_key(text)
+                if cache_key in self._embed_cache:
+                    self._embed_cache.move_to_end(cache_key)
+                    results[i] = self._embed_cache[cache_key].copy()
+                else:
+                    texts_to_embed.append((i, text))
+
+        # Generate embeddings for uncached texts
+        if texts_to_embed:
+            uncached_texts = [t for _, t in texts_to_embed]
+            if self.use_openai:
+                new_embeddings = self._embed_openai_with_circuit_breaker(uncached_texts)
+            else:
+                new_embeddings = self._embed_local(uncached_texts)
+
+            # Store results and cache them
+            with self._cache_lock:
+                for (idx, text), embedding in zip(texts_to_embed, new_embeddings):
+                    results[idx] = embedding
+                    cache_key = self._get_cache_key(text)
+                    if cache_key not in self._embed_cache:
+                        # Evict oldest entries if at capacity
+                        while len(self._embed_cache) >= self._cache_max_size:
+                            self._embed_cache.popitem(last=False)
+                        self._embed_cache[cache_key] = embedding.copy()
+
+        # Type assertion - all results should be filled
+        return [r for r in results if r is not None]
 
     def clear_cache(self) -> int:
         """Clear embedding cache. Returns number of entries cleared."""
@@ -387,6 +489,41 @@ class EmbeddingService:
             masked_error = _mask_api_key(str(e))
             raise EmbeddingError(f"Failed to generate embeddings: {masked_error}") from e
 
+    def _embed_openai_with_circuit_breaker(self, texts: list[str]) -> list[np.ndarray]:
+        """Generate embeddings using OpenAI API with circuit breaker protection.
+
+        Wraps the OpenAI embedding call with a circuit breaker to prevent
+        cascading failures when the API is unavailable.
+
+        Args:
+            texts: List of texts to embed.
+
+        Returns:
+            List of embedding vectors.
+
+        Raises:
+            EmbeddingError: If circuit is open or embedding generation fails.
+        """
+        if self._circuit_breaker is None:
+            # No circuit breaker, call directly
+            return self._embed_openai(texts)
+
+        try:
+            return self._circuit_breaker.call(self._embed_openai, texts)
+        except CircuitOpenError as e:
+            logger.warning(
+                f"Circuit breaker is open for embedding service, "
+                f"time until retry: {e.time_until_retry:.1f}s"
+                if e.time_until_retry is not None
+                else "Circuit breaker is open for embedding service"
+            )
+            raise EmbeddingError(
+                f"Embedding service temporarily unavailable (circuit open). "
+                f"Try again in {e.time_until_retry:.0f} seconds."
+                if e.time_until_retry is not None
+                else "Embedding service temporarily unavailable (circuit open)."
+            ) from e
+
     @retry_on_api_error(max_attempts=3, backoff=1.0)
     def _embed_openai(self, texts: list[str]) -> list[np.ndarray]:
         """Generate embeddings using OpenAI API with retry logic.

spatial_memory/core/errors.py

@@ -1,5 +1,24 @@
 """Custom exceptions for Spatial Memory MCP Server."""
 
+from pathlib import Path
+
+
+def sanitize_path_for_error(path: str | Path) -> str:
+    """Extract only the filename from a path for safe error messages.
+
+    Prevents leaking full system paths in error messages which could
+    expose sensitive directory structure information.
+
+    Args:
+        path: Full path or filename.
+
+    Returns:
+        Just the filename portion.
+    """
+    if isinstance(path, Path):
+        return path.name
+    return Path(path).name
+
 
 class SpatialMemoryError(Exception):
     """Base exception for all spatial memory errors."""
@@ -35,6 +54,37 @@ class StorageError(SpatialMemoryError):
     pass
 
 
+class PartialBatchInsertError(StorageError):
+    """Raised when batch insert partially fails.
+
+    Provides information about which records were successfully inserted
+    before the failure, enabling recovery or rollback.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        succeeded_ids: list[str],
+        total_requested: int,
+        failed_batch_index: int | None = None,
+    ) -> None:
+        """Initialize with details about partial failure.
+
+        Args:
+            message: Error description.
+            succeeded_ids: IDs of successfully inserted records.
+            total_requested: Total number of records requested to insert.
+            failed_batch_index: Index of the batch that failed (if batched).
+        """
+        self.succeeded_ids = succeeded_ids
+        self.total_requested = total_requested
+        self.failed_batch_index = failed_batch_index
+        super().__init__(
+            f"{message}. "
+            f"Inserted {len(succeeded_ids)}/{total_requested} records before failure."
+        )
+
+
 class ValidationError(SpatialMemoryError):
     """Raised when input validation fails."""
 
@@ -141,6 +191,10 @@ class PathSecurityError(SpatialMemoryError):
         - Path outside allowed directories
         - Symlink to disallowed location
         - Invalid file extension
+
+    Note:
+        Error messages only include the filename, not the full path,
+        to avoid leaking system directory structure.
     """
 
     def __init__(
@@ -151,12 +205,18 @@ class PathSecurityError(SpatialMemoryError):
     ) -> None:
         self.path = path
         self.violation_type = violation_type
-        self.message = message or f"Path security violation ({violation_type}): {path}"
+        safe_name = sanitize_path_for_error(path)
+        self.message = message or f"Path security violation ({violation_type}): {safe_name}"
         super().__init__(self.message)
 
 
 class FileSizeLimitError(SpatialMemoryError):
-    """Raised when a file exceeds size limits."""
+    """Raised when a file exceeds size limits.
+
+    Note:
+        Error messages only include the filename, not the full path,
+        to avoid leaking system directory structure.
+    """
 
     def __init__(
         self,
@@ -169,8 +229,9 @@ class FileSizeLimitError(SpatialMemoryError):
         self.max_size_bytes = max_size_bytes
         actual_mb = actual_size_bytes / (1024 * 1024)
         max_mb = max_size_bytes / (1024 * 1024)
+        safe_name = sanitize_path_for_error(path)
         super().__init__(
-            f"File exceeds size limit: {path} is {actual_mb:.2f}MB "
+            f"File exceeds size limit: {safe_name} is {actual_mb:.2f}MB "
             f"(max: {max_mb:.2f}MB)"
         )
 
@@ -243,3 +304,14 @@ class FileLockError(SpatialMemoryError):
         self.timeout = timeout
         self.message = message or f"Failed to acquire file lock at {lock_path} after {timeout}s"
         super().__init__(self.message)
+
+
+# =============================================================================
+# Migration Error
+# =============================================================================
+
+
+class MigrationError(SpatialMemoryError):
+    """Raised when a database migration fails."""
+
+    pass

spatial_memory/core/filesystem.py

@@ -0,0 +1,178 @@
+"""Filesystem detection utilities for identifying network filesystems.
+
+This module provides utilities to detect if a path is on a network filesystem
+(NFS, SMB/CIFS) where file-based locking may not work reliably.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import platform
+import subprocess
+from enum import Enum
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+class FilesystemType(Enum):
+    """Types of filesystems that can be detected."""
+
+    LOCAL = "local"
+    NFS = "nfs"
+    SMB = "smb"
+    CIFS = "cifs"
+    NETWORK_UNKNOWN = "network_unknown"
+    UNKNOWN = "unknown"
+
+
+def detect_filesystem_type(path: Path) -> FilesystemType:
+    """Detect the filesystem type for a given path.
+
+    Args:
+        path: Path to check. Will resolve to absolute path.
+
+    Returns:
+        FilesystemType indicating the detected filesystem.
+        Returns LOCAL for local filesystems, specific types for
+        network filesystems, or UNKNOWN if detection fails.
+    """
+    try:
+        resolved = path.resolve()
+
+        if platform.system() == "Windows":
+            return _detect_windows(resolved)
+        else:
+            return _detect_unix(resolved)
+    except Exception as e:
+        logger.debug(f"Filesystem detection failed for {path}: {e}")
+        return FilesystemType.UNKNOWN
+
+
+def _detect_windows(path: Path) -> FilesystemType:
+    """Detect filesystem type on Windows.
+
+    Uses GetDriveTypeW to check if drive is remote.
+    """
+    try:
+        import ctypes
+
+        # Get the drive letter (e.g., "C:\\")
+        drive = str(path)[:3] if len(str(path)) >= 3 else str(path)
+
+        # Ensure it ends with backslash for GetDriveTypeW
+        if not drive.endswith("\\"):
+            drive = drive + "\\"
+
+        # DRIVE_REMOTE = 4
+        drive_type = ctypes.windll.kernel32.GetDriveTypeW(drive)
+
+        if drive_type == 4:  # DRIVE_REMOTE
+            logger.debug(f"Detected remote drive: {drive}")
+            return FilesystemType.NETWORK_UNKNOWN
+        else:
+            return FilesystemType.LOCAL
+
+    except Exception as e:
+        logger.debug(f"Windows filesystem detection failed: {e}")
+        return FilesystemType.UNKNOWN
+
+
+def _detect_unix(path: Path) -> FilesystemType:
+    """Detect filesystem type on Unix-like systems.
+
+    Uses 'df -T' or 'mount' to determine filesystem type.
+    """
+    try:
+        # Try using df -T first (more portable)
+        result = subprocess.run(
+            ["df", "-T", str(path)],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+
+        if result.returncode == 0:
+            output = result.stdout.lower()
+            # Check for common network filesystem types
+            if "nfs" in output:
+                return FilesystemType.NFS
+            if "cifs" in output:
+                return FilesystemType.CIFS
+            if "smb" in output:
+                return FilesystemType.SMB
+            if "fuse.sshfs" in output:
+                return FilesystemType.NETWORK_UNKNOWN
+            # If none of the above, assume local
+            return FilesystemType.LOCAL
+
+    except subprocess.TimeoutExpired:
+        logger.debug("df command timed out - may indicate network filesystem issue")
+        return FilesystemType.NETWORK_UNKNOWN
+    except FileNotFoundError:
+        # df not available, try alternative
+        pass
+    except Exception as e:
+        logger.debug(f"df command failed: {e}")
+
+    # Fallback: try reading /proc/mounts on Linux
+    try:
+        if os.path.exists("/proc/mounts"):
+            with open("/proc/mounts") as f:
+                mounts = f.read().lower()
+                path_str = str(path).lower()
+                # Find the mount point for this path
+                for line in mounts.split("\n"):
+                    parts = line.split()
+                    if len(parts) >= 3:
+                        mount_point = parts[1]
+                        fs_type = parts[2]
+                        if path_str.startswith(mount_point):
+                            if "nfs" in fs_type:
+                                return FilesystemType.NFS
+                            if "cifs" in fs_type or "smb" in fs_type:
+                                return FilesystemType.SMB
+    except Exception as e:
+        logger.debug(f"/proc/mounts check failed: {e}")
+
+    return FilesystemType.LOCAL
+
+
+def is_network_filesystem(path: Path) -> bool:
+    """Check if a path is on a network filesystem.
+
+    Args:
+        path: Path to check.
+
+    Returns:
+        True if the path appears to be on a network filesystem
+        (NFS, SMB, CIFS, or unknown network type).
+    """
+    fs_type = detect_filesystem_type(path)
+    return fs_type in (
+        FilesystemType.NFS,
+        FilesystemType.SMB,
+        FilesystemType.CIFS,
+        FilesystemType.NETWORK_UNKNOWN,
+    )
+
+
+def get_filesystem_warning_message(fs_type: FilesystemType, path: Path) -> str:
+    """Generate a warning message for network filesystem detection.
+
+    Args:
+        fs_type: The detected filesystem type.
+        path: The path that was checked.
+
+    Returns:
+        A warning message string explaining the risks.
+    """
+    return (
+        f"WARNING: Storage path appears to be on a network filesystem ({fs_type.value}). "
+        f"Path: {path}\n"
+        f"File-based locking does not work reliably on network filesystems. "
+        f"Running multiple instances against this storage may cause data corruption. "
+        f"To suppress this warning, set SPATIAL_MEMORY_ACKNOWLEDGE_NETWORK_FS_RISK=true "
+        f"or use a local filesystem path."
+    )