spatial-memory-mcp 1.6.1__py3-none-any.whl

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."
+    )

spatial_memory/core/health.py

@@ -0,0 +1,289 @@
+"""Health check infrastructure for Spatial Memory MCP Server."""
+
+from __future__ import annotations
+
+import logging
+import time
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from enum import Enum
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from spatial_memory.core.database import Database
+
+logger = logging.getLogger(__name__)
+
+
+class HealthStatus(Enum):
+    """Health status levels."""
+
+    HEALTHY = "healthy"
+    DEGRADED = "degraded"
+    UNHEALTHY = "unhealthy"
+
+
+@dataclass
+class CheckResult:
+    """Result of a single health check."""
+
+    name: str
+    status: HealthStatus
+    message: str
+    latency_ms: float | None = None
+
+
+@dataclass
+class HealthReport:
+    """Aggregate health report for system components."""
+
+    status: HealthStatus
+    checks: list[CheckResult]
+    timestamp: datetime
+
+
+class HealthChecker:
+    """Health checker for system components.
+
+    This class performs health checks on the database, embeddings service,
+    and storage system to ensure the server is ready to accept traffic.
+    """
+
+    def __init__(
+        self,
+        database: Database | None = None,
+        embeddings: Any = None,
+        storage_path: Path | None = None,
+    ) -> None:
+        """Initialize health checker.
+
+        Args:
+            database: Database instance to check (optional).
+            embeddings: Embedding service to check (optional).
+            storage_path: Storage path to check for writability (optional).
+        """
+        self.database = database
+        self.embeddings = embeddings
+        self.storage_path = storage_path
+
+    def check_database(self) -> CheckResult:
+        """Check database connectivity and basic operations.
+
+        Returns:
+            CheckResult with database health status.
+        """
+        if self.database is None:
+            return CheckResult(
+                name="database",
+                status=HealthStatus.UNHEALTHY,
+                message="Database not configured",
+            )
+
+        try:
+            start_time = time.perf_counter()
+
+            # Try to get row count to verify database is operational
+            count = self.database.count()
+            latency = (time.perf_counter() - start_time) * 1000
+
+            # Check if database is degraded based on latency
+            if latency > 5000:  # 5 seconds
+                return CheckResult(
+                    name="database",
+                    status=HealthStatus.DEGRADED,
+                    message=f"Database operational but slow ({count} rows)",
+                    latency_ms=latency,
+                )
+
+            return CheckResult(
+                name="database",
+                status=HealthStatus.HEALTHY,
+                message=f"Database operational ({count} rows)",
+                latency_ms=latency,
+            )
+
+        except Exception as e:
+            logger.error(f"Database health check failed: {e}")
+            return CheckResult(
+                name="database",
+                status=HealthStatus.UNHEALTHY,
+                message=f"Database error: {str(e)[:100]}",
+            )
+
+    def check_embeddings(self) -> CheckResult:
+        """Check embedding service is functional.
+
+        Returns:
+            CheckResult with embeddings service health status.
+        """
+        if self.embeddings is None:
+            return CheckResult(
+                name="embeddings",
+                status=HealthStatus.UNHEALTHY,
+                message="Embeddings service not configured",
+            )
+
+        try:
+            start_time = time.perf_counter()
+
+            # Try a test embedding
+            test_vector = self.embeddings.embed("health check test")
+            latency = (time.perf_counter() - start_time) * 1000
+
+            # Verify vector is correct shape
+            if len(test_vector) != self.embeddings.dimensions:
+                return CheckResult(
+                    name="embeddings",
+                    status=HealthStatus.UNHEALTHY,
+                    message=(
+                        f"Embedding dimension mismatch: "
+                        f"got {len(test_vector)}, expected {self.embeddings.dimensions}"
+                    ),
+                    latency_ms=latency,
+                )
+
+            # Check if service is degraded based on latency
+            if latency > 10000:  # 10 seconds
+                return CheckResult(
+                    name="embeddings",
+                    status=HealthStatus.DEGRADED,
+                    message=f"Embeddings operational but slow ({self.embeddings.model_name})",
+                    latency_ms=latency,
+                )
+
+            return CheckResult(
+                name="embeddings",
+                status=HealthStatus.HEALTHY,
+                message=(
+                    f"Embeddings operational "
+                    f"({self.embeddings.model_name}, {self.embeddings.dimensions}d)"
+                ),
+                latency_ms=latency,
+            )
+
+        except Exception as e:
+            logger.error(f"Embeddings health check failed: {e}")
+            return CheckResult(
+                name="embeddings",
+                status=HealthStatus.UNHEALTHY,
+                message=f"Embeddings error: {str(e)[:100]}",
+            )
+
+    def check_storage(self) -> CheckResult:
+        """Check storage path is writable.
+
+        Returns:
+            CheckResult with storage health status.
+        """
+        if self.storage_path is None:
+            return CheckResult(
+                name="storage",
+                status=HealthStatus.HEALTHY,
+                message="Storage check skipped (no path configured)",
+            )
+
+        try:
+            # Check if directory exists
+            if not self.storage_path.exists():
+                return CheckResult(
+                    name="storage",
+                    status=HealthStatus.UNHEALTHY,
+                    message=f"Storage path does not exist: {self.storage_path}",
+                )
+
+            # Try to write and delete a test file
+            test_file = self.storage_path / ".health_check"
+            try:
+                test_file.write_text("health check", encoding="utf-8")
+                test_file.unlink()
+            except Exception as e:
+                return CheckResult(
+                    name="storage",
+                    status=HealthStatus.UNHEALTHY,
+                    message=f"Storage path not writable: {e}",
+                )
+
+            return CheckResult(
+                name="storage",
+                status=HealthStatus.HEALTHY,
+                message=f"Storage writable ({self.storage_path})",
+            )
+
+        except Exception as e:
+            logger.error(f"Storage health check failed: {e}")
+            return CheckResult(
+                name="storage",
+                status=HealthStatus.UNHEALTHY,
+                message=f"Storage error: {str(e)[:100]}",
+            )
+
+    def get_health_report(self) -> HealthReport:
+        """Run all checks and return aggregate report.
+
+        Returns:
+            HealthReport with all check results.
+        """
+        checks: list[CheckResult] = []
+
+        # Run all configured checks
+        if self.database is not None:
+            checks.append(self.check_database())
+
+        if self.embeddings is not None:
+            checks.append(self.check_embeddings())
+
+        if self.storage_path is not None:
+            checks.append(self.check_storage())
+
+        # Determine overall status
+        # If any check is unhealthy, overall is unhealthy
+        # If any check is degraded, overall is degraded
+        # Otherwise, healthy
+        overall_status = HealthStatus.HEALTHY
+        for check in checks:
+            if check.status == HealthStatus.UNHEALTHY:
+                overall_status = HealthStatus.UNHEALTHY
+                break
+            elif check.status == HealthStatus.DEGRADED:
+                overall_status = HealthStatus.DEGRADED
+
+        return HealthReport(
+            status=overall_status,
+            checks=checks,
+            timestamp=datetime.now(timezone.utc),
+        )
+
+    def is_ready(self) -> bool:
+        """Check if system can accept traffic (readiness probe).
+
+        All critical checks (database and embeddings) must pass.
+
+        Returns:
+            True if system is ready, False otherwise.
+        """
+        report = self.get_health_report()
+
+        # All checks must be at least degraded (not unhealthy)
+        for check in report.checks:
+            # Storage is optional, skip it
+            if check.name == "storage":
+                continue
+
+            if check.status == HealthStatus.UNHEALTHY:
+                return False
+
+        return True
+
+    def is_alive(self) -> bool:
+        """Check if process is alive (liveness probe).
+
+        Basic process health check.
+
+        Returns:
+            True if process is alive, False otherwise.
+        """
+        # Basic check - if we can run this code, we're alive
+        # In a more sophisticated implementation, this could check
+        # for deadlocks, stuck threads, etc.
+        return True

spatial_memory/core/helpers.py

@@ -0,0 +1,79 @@
+"""Common utility functions for Spatial Memory MCP."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import numpy as np
+
+
+def deserialize_metadata(record: dict[str, Any]) -> None:
+    """Deserialize metadata JSON string to dict in-place.
+
+    Args:
+        record: Database record dict to modify in-place
+    """
+    if record.get("metadata"):
+        if isinstance(record["metadata"], str):
+            record["metadata"] = json.loads(record["metadata"])
+    else:
+        record["metadata"] = {}
+
+
+def serialize_metadata(metadata: dict[str, Any] | None) -> str:
+    """Serialize metadata dict to JSON string.
+
+    Args:
+        metadata: Metadata dict or None
+
+    Returns:
+        JSON string
+    """
+    return json.dumps(metadata) if metadata else "{}"
+
+
+def convert_distance_to_similarity(record: dict[str, Any]) -> None:
+    """Convert _distance field to similarity score in-place.
+
+    Similarity is calculated as 1 - distance and clamped to [0, 1].
+
+    Args:
+        record: Database record dict to modify in-place
+    """
+    if "_distance" in record:
+        record["similarity"] = max(0.0, min(1.0, 1 - record["_distance"]))
+        del record["_distance"]
+
+
+def deserialize_record(record: dict[str, Any]) -> dict[str, Any]:
+    """Fully deserialize a database record.
+
+    Applies:
+    - Metadata JSON deserialization
+    - Distance to similarity conversion
+
+    Args:
+        record: Database record dict
+
+    Returns:
+        Deserialized record
+    """
+    deserialize_metadata(record)
+    convert_distance_to_similarity(record)
+    return record
+
+
+def serialize_vector(vector: np.ndarray | list[float]) -> list[float]:
+    """Convert vector to list format for storage.
+
+    Args:
+        vector: numpy array or list
+
+    Returns:
+        List of floats
+    """
+    if isinstance(vector, np.ndarray):
+        result: list[float] = vector.tolist()
+        return result
+    return vector