mcp-plesk-dev-docs 0.4.2__py3-none-any.whl

plesk_unified/model_config.py

@@ -0,0 +1,218 @@
+"""
+Model profile configuration for mcp-plesk-dev-docs.
+
+Profiles let you trade RAM/VRAM footprint against retrieval quality.
+Select a profile via the PLESK_MODEL_PROFILE environment variable.
+
+    PLESK_MODEL_PROFILE=light    ~200 MB total  (M2 MacBook Air, memory-constrained)
+    PLESK_MODEL_PROFILE=full     ~1.8 GB total  (RTX 4070 Super, max quality)
+    PLESK_MODEL_PROFILE=medium   ~600 MB total  (balanced middle ground)
+
+You can also override individual components without changing the profile:
+        PLESK_EMBED_MODEL=BAAI/bge-base-en-v1.5
+        PLESK_RERANKER_MODEL=cross-encoder/ms-marco-MiniLM-L-6-v2
+        PLESK_RERANKER_ENABLED=false
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+
+from plesk_unified.platform_utils import get_optimal_device, get_platform_info
+from plesk_unified.settings import settings
+
+logger = logging.getLogger("plesk_unified")
+
+# ---------------------------------------------------------------------------
+# Profile definitions
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class ModelProfile:
+    name: str
+    embed_model: str
+    embed_dim: int  # must match LanceDB vector column dimension
+    reranker_model: str | None
+    reranker_enabled: bool
+    description: str
+    approx_ram_mb: int
+    rerank_candidates: int = 35
+    use_turboquant: bool = False
+    tq_bits: int = 5
+    tq_top_k: int = 25
+
+
+_PROFILES: dict[str, ModelProfile] = {
+    "light": ModelProfile(
+        name="light",
+        embed_model="BAAI/bge-small-en-v1.5",
+        embed_dim=384,
+        reranker_model="cross-encoder/ms-marco-MiniLM-L4-v2",
+        reranker_enabled=True,
+        description=(
+            "~200 MB total. Ideal for M2 MacBook Air or any memory-constrained host."
+        ),
+        approx_ram_mb=200,
+        rerank_candidates=35,
+    ),
+    "medium": ModelProfile(
+        name="medium",
+        embed_model="BAAI/bge-base-en-v1.5",
+        embed_dim=768,
+        reranker_model="cross-encoder/ms-marco-MiniLM-L4-v2",
+        reranker_enabled=True,
+        description="~600 MB total. Good quality with moderate memory use.",
+        approx_ram_mb=600,
+        rerank_candidates=35,
+    ),
+    "full": ModelProfile(
+        name="full",
+        embed_model="BAAI/bge-m3",
+        embed_dim=1024,
+        reranker_model="BAAI/bge-reranker-base",
+        reranker_enabled=True,
+        description=(
+            "~1.8 GB total. Maximum quality. Recommended for RTX 4070 Super / CUDA."
+        ),
+        approx_ram_mb=1800,
+    ),
+    "full-tq": ModelProfile(
+        name="full-tq",
+        embed_model="BAAI/bge-m3",
+        embed_dim=1024,
+        reranker_model="BAAI/bge-reranker-base",
+        reranker_enabled=True,
+        description=(
+            "TurboQuant 4-bit profile with category-aware retrieval. "
+            "Quality parity target with significantly lower latency."
+        ),
+        approx_ram_mb=1300,
+        use_turboquant=True,
+        tq_bits=4,
+        tq_top_k=25,
+    ),
+}
+
+DEFAULT_PROFILE = "full-tq"
+
+
+# ---------------------------------------------------------------------------
+# Resolution logic (env vars  profile  individual overrides)
+# ---------------------------------------------------------------------------
+
+
+def get_active_profile() -> ModelProfile:
+    """
+    Resolve the active model profile from environment variables.
+
+        Priority (highest to lowest):
+            1. PLESK_EMBED_MODEL / PLESK_RERANKER_MODEL  (per-component overrides)
+            2. PLESK_MODEL_PROFILE                        (named profile)
+            3. Compiled-in default ("full-tq")
+    """
+    profile_name = settings.plesk_model_profile
+    profile_name = profile_name.lower().strip()
+
+    if profile_name not in _PROFILES:
+        logger.warning(
+            "Unknown PLESK_MODEL_PROFILE=%r. Valid options: %s. Falling back to '%s'.",
+            profile_name,
+            ", ".join(_PROFILES),
+            DEFAULT_PROFILE,
+        )
+        profile_name = DEFAULT_PROFILE
+
+    base = _PROFILES[profile_name]
+
+    # Apply per-component overrides on top of the profile
+    embed_model = (settings.plesk_embed_model or base.embed_model).strip()
+
+    # Handle reranker_model specifically to allow empty string as "none"
+    if settings.plesk_reranker_model is not None:
+        reranker_model = settings.plesk_reranker_model.strip() or None
+    else:
+        reranker_model = base.reranker_model
+
+    if settings.plesk_reranker_enabled is False:
+        reranker_enabled = False
+    elif settings.plesk_reranker_enabled is True:
+        reranker_enabled = True
+    else:
+        reranker_enabled = base.reranker_enabled
+
+    # Determine vector dimension  if the embed model changed, the user must
+    # also set PLESK_EMBED_DIM or we fall back to the profile default with a warning.
+    embed_dim = base.embed_dim
+    if embed_model != base.embed_model:
+        if settings.plesk_embed_dim:
+            embed_dim = settings.plesk_embed_dim
+        else:
+            logger.warning(
+                "PLESK_EMBED_MODEL overridden to %r but PLESK_EMBED_DIM not set. "
+                "Using profile default dim=%d. Set PLESK_EMBED_DIM if the model "
+                "uses a different dimension, then delete storage/lancedb and reindex.",
+                embed_model,
+                embed_dim,
+            )
+
+    active = ModelProfile(
+        name=profile_name,
+        embed_model=embed_model,
+        embed_dim=embed_dim,
+        reranker_model=reranker_model,
+        reranker_enabled=reranker_enabled and (reranker_model is not None),
+        description=base.description,
+        approx_ram_mb=base.approx_ram_mb,
+        rerank_candidates=settings.plesk_rerank_candidates or base.rerank_candidates,
+        use_turboquant=base.use_turboquant,
+        tq_bits=base.tq_bits,
+        tq_top_k=base.tq_top_k,
+    )
+
+    # VRAM Auto-tuning check
+    device = get_optimal_device()
+    if device == "cuda":
+        info = get_platform_info()
+        free_vram = info.get("vram_free_mb")
+        if free_vram and active.approx_ram_mb > free_vram:
+            logger.warning(
+                "VRAM Auto-Tune: Profile '%s' requires ~%d MB but only %d MB is free. "
+                "Consider switching to a lighter profile (e.g., 'medium' or 'light') "
+                "to avoid Out-Of-Memory (OOM) errors.",
+                active.name,
+                active.approx_ram_mb,
+                free_vram,
+            )
+
+    logger.info(
+        "Active model profile: %s | embed=%s (dim=%d) | reranker=%s "
+        "(enabled=%s) | ~%d MB",
+        active.name,
+        active.embed_model,
+        active.embed_dim,
+        active.reranker_model,
+        active.reranker_enabled,
+        active.approx_ram_mb,
+    )
+
+    return active
+
+
+def list_profiles() -> dict[str, dict]:
+    """Return a serialisable summary of all built-in profiles."""
+    return {
+        name: {
+            "embed_model": p.embed_model,
+            "embed_dim": p.embed_dim,
+            "reranker_model": p.reranker_model,
+            "reranker_enabled": p.reranker_enabled,
+            "approx_ram_mb": p.approx_ram_mb,
+            "use_turboquant": p.use_turboquant,
+            "tq_bits": p.tq_bits,
+            "tq_top_k": p.tq_top_k,
+            "description": p.description,
+        }
+        for name, p in _PROFILES.items()
+    }

plesk_unified/platform_utils.py

@@ -0,0 +1,214 @@
+"""
+Platform detection and GPU configuration utilities.
+
+Provides cross-platform support for:
+- Windows: CUDA GPU acceleration (if available)
+- macOS: Apple Silicon MPS acceleration (M1/M2/M3) or CPU fallback
+- Linux: CUDA or CPU fallback
+"""
+
+import logging
+import os
+import platform
+import sys
+from typing import Any, Optional
+
+# Lazy import for torch to avoid heavy import at module level
+
+_torch: Optional[Any] = None
+
+# Inherit logger from the main application (configured in server.py)
+logger = logging.getLogger("plesk_unified")
+
+
+def _get_torch() -> Any:
+    """Lazy load torch to avoid import overhead."""
+    global _torch
+    if _torch is None:
+        try:
+            import torch
+
+            _torch = torch
+        except ImportError:
+            logger.warning(
+                "PyTorch import failed. GPU acceleration will be unavailable."
+            )
+            raise
+    return _torch
+
+
+def get_platform_info() -> dict:
+    """
+    Returns a dictionary with detailed platform information.
+    """
+    info: dict[str, Any] = {
+        "system": platform.system(),
+        "machine": platform.machine(),
+        "python_version": platform.python_version(),
+        "python_executable": sys.executable,
+    }
+
+    # Try to get PyTorch info
+    try:
+        torch = _get_torch()
+        info["torch_version"] = str(torch.__version__)
+        info["cuda_available"] = torch.cuda.is_available()
+        # Check MPS availability on macOS
+        info["mps_available"] = (
+            torch.backends.mps.is_available()
+            if platform.system() == "Darwin" and hasattr(torch.backends, "mps")
+            else False
+        )
+
+        if torch.cuda.is_available():
+            info["cuda_version"] = str(torch.version.cuda)
+            info["gpu_count"] = torch.cuda.device_count()
+            if torch.cuda.device_count() > 0:
+                info["gpu_name"] = str(torch.cuda.get_device_name(0))
+                try:
+                    free_vram, total_vram = torch.cuda.mem_get_info()
+                    info["vram_free_mb"] = free_vram // (1024**2)
+                    info["vram_total_mb"] = total_vram // (1024**2)
+                except Exception:
+                    pass
+
+    except ImportError:
+        info["torch_available"] = False
+    except Exception as e:
+        info["torch_error"] = str(e)
+        logger.debug("Error gathering detailed platform info: %s", e)
+
+    return info
+
+
+def get_optimal_device() -> str:
+    """
+    Determine the optimal compute device based on platform and hardware.
+    Priority: Environment Variable -> MPS (macOS) -> CUDA (Win/Linux) -> CPU
+    """
+    # Check for forced device via environment variable
+    forced_device = os.environ.get("FORCE_DEVICE", "").lower().strip()
+    if forced_device in ("cuda", "mps", "cpu"):
+        logger.info("Device forced via env var: %s", forced_device)
+        return forced_device
+
+    system = platform.system()
+
+    # macOS: Check for Apple Silicon MPS
+    if system == "Darwin":
+        try:
+            torch = _get_torch()
+            if hasattr(torch.backends, "mps") and torch.backends.mps.is_available():
+                return "mps"
+        except Exception:
+            pass
+        return "cpu"
+
+    # Windows/Linux: Check for CUDA
+    if system in ("Windows", "Linux"):
+        try:
+            torch = _get_torch()
+            if torch.cuda.is_available():
+                return "cuda"
+        except Exception:
+            pass
+
+    return "cpu"
+
+
+def log_hardware_degradation(
+    failed_device: str, reason: Exception | str, fallback: str = "cpu"
+) -> None:
+    """
+    Log a WARNING when a hardware accelerator (CUDA/MPS) fails and falls back to CPU.
+    T05 (M1) Implementation.
+    """
+    logger.warning(
+        "Hardware acceleration failure: %s initialization failed (%s). "
+        "Falling back to %s. Performance may be degraded.",
+        failed_device.upper(),
+        str(reason),
+        fallback.upper(),
+    )
+
+
+def get_device_config() -> dict:
+    """
+    Get comprehensive device configuration for model initialization.
+    """
+    device = get_optimal_device()
+    config: dict[str, Any] = {
+        "device": device,
+        "precision": "float32",
+    }
+
+    try:
+        if device == "cuda":
+            torch = _get_torch()
+            if torch.cuda.is_available():
+                config["precision"] = "float16"
+                config["torch_dtype"] = "float16"
+        elif device == "mps":
+            config["precision"] = "float16"
+            config["torch_dtype"] = "float16"
+    except Exception as e:
+        logger.debug("Failed to set precision config: %s", e)
+
+    return config
+
+
+def log_platform_info() -> None:
+    """Logs platform information to the shared logger."""
+    info = get_platform_info()
+    device = get_optimal_device()
+
+    # Construct a concise summary for the log
+    summary = [
+        f"OS: {info.get('system')} {info.get('machine')}",
+        f"Python: {info.get('python_version')}",
+        f"Device: {device.upper()}",
+    ]
+
+    if info.get("cuda_available"):
+        summary.append(
+            f"GPU: {info.get('gpu_name', 'Unknown')} (CUDA {info.get('cuda_version')})"
+        )
+    elif info.get("mps_available"):
+        summary.append("GPU: Apple Silicon (MPS)")
+
+    logger.info("Platform Check: " + " | ".join(summary))
+
+
+def is_apple_silicon() -> bool:
+    """Check if running on Apple Silicon (M1/M2/M3)."""
+    return platform.system() == "Darwin" and platform.machine() == "arm64"
+
+
+def is_windows() -> bool:
+    """Check if running on Windows."""
+    return platform.system() == "Windows"
+
+
+def is_linux() -> bool:
+    """Check if running on Linux."""
+    return platform.system() == "Linux"
+
+
+def is_macos() -> bool:
+    """Check if running on macOS."""
+    return platform.system() == "Darwin"
+
+
+def get_model_cache_dir() -> str:
+    """
+    Get the appropriate model cache directory for the platform.
+    """
+    import tempfile
+
+    if is_windows():
+        base = os.environ.get("LOCALAPPDATA", tempfile.gettempdir())
+        return os.path.join(base, "huggingface", "hub")
+    elif is_macos():
+        return os.path.expanduser("~/Library/Caches/huggingface/hub")
+    else:
+        return os.path.expanduser("~/.cache/huggingface/hub")

plesk_unified/settings.py

@@ -0,0 +1,93 @@
+import os
+from pathlib import Path
+from typing import Literal, Optional
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class PleskSettings(BaseSettings):
+    """
+    Configuration settings for mcp-plesk-dev-docs.
+
+    Fields map to environment variables (e.g., log_level maps to LOG_LEVEL).
+    """
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    # Logging
+    log_level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] = "INFO"
+    log_file: Optional[str] = None
+    log_handler: Literal["os", "file", "both"] = "os"
+
+    # Model Profile & Overrides
+    plesk_model_profile: str = "full-tq"
+    plesk_embed_model: Optional[str] = None
+    plesk_reranker_model: Optional[str] = None
+    plesk_reranker_enabled: Optional[bool] = None
+    plesk_embed_dim: Optional[int] = None
+
+    # Operational Behaviors
+    plesk_daemon_auto_warmup: bool = False
+    plesk_auto_refresh_on_startup: bool = True
+    plesk_index_summaries: bool = False
+    plesk_enable_fts: bool = True
+    plesk_enable_ast_chunking: bool = False
+    plesk_enable_sampling: bool = False
+    # Default number of candidates to send to the reranker when not overridden.
+    # Historically this default was 50; keep that default for backward compatibility.
+    plesk_rerank_candidates: Optional[int] = 50
+    plesk_min_relevance_threshold: Optional[float] = None
+
+    # External APIs & Hardware
+    openrouter_api_key: str = ""
+    force_device: Optional[str] = None
+    plesk_html_llm_table_normalize: bool = False
+
+    # Third-party library silencing
+    tqdm_disable: bool = True
+    transformers_verbosity: str = "error"
+
+    @property
+    def effective_log_file(self) -> str:
+        """Resolve the log file path, ensuring the parent directory exists."""
+        if self.log_file:
+            return self.log_file
+        base_dir = Path(__file__).parent.parent
+        log_dir = base_dir / "storage" / "logs"
+        log_dir.mkdir(parents=True, exist_ok=True)
+        return str(log_dir / "plesk_unified.log")
+
+    @property
+    def embedding_model_dimensions(self) -> int:
+        """Return embedding vector dimension: explicit override or profile default.
+
+        Priority: `plesk_embed_dim` (explicit env override) -> profile default.
+        Lazy-imports model_config to avoid expensive imports at module load time.
+        """
+        if self.plesk_embed_dim:
+            return self.plesk_embed_dim
+        # Lazy import so we don't cause circular imports at module import time.
+        from plesk_unified.model_config import get_active_profile
+
+        return get_active_profile().embed_dim
+
+
+# Allow tests to suppress .env loading by setting PLESK_ENV_FILE="" or to another file.
+_env_file = os.environ.get("PLESK_ENV_FILE", ".env")
+if not _env_file:
+    _env_file = None
+
+# Update the class-level model_config before instantiating the settings singleton.
+# We intentionally set `env_file` even when `_env_file` is `None` so tests can
+# suppress .env loading by setting `PLESK_ENV_FILE=""` in the environment.
+PleskSettings.model_config = SettingsConfigDict(
+    env_file=_env_file,
+    env_file_encoding="utf-8",
+    extra="ignore",
+)
+
+settings = PleskSettings()

plesk_unified/summary_cache.py

@@ -0,0 +1,55 @@
+import json
+import logging
+import hashlib
+from pathlib import Path
+from typing import Dict, Optional
+
+logger = logging.getLogger(__name__)
+
+CACHE_FILE = Path("storage/summaries_cache.json")
+
+
+class SummaryCache:
+    """A persistent cache for AI-generated summaries indexed by file content hash."""
+
+    def __init__(self):
+        self.cache: Dict[str, str] = {}
+        self._load()
+
+    def _get_file_hash(self, file_path: Path) -> str:
+        """Computes MD5 hash of file content."""
+        hasher = hashlib.md5()
+        with open(file_path, "rb") as f:
+            for chunk in iter(lambda: f.read(4096), b""):
+                hasher.update(chunk)
+        return hasher.hexdigest()
+
+    def _load(self):
+        """Loads cache from disk."""
+        if CACHE_FILE.exists():
+            try:
+                with open(CACHE_FILE, "r", encoding="utf-8") as f:
+                    self.cache = json.load(f)
+                logger.info("Loaded %d summaries from cache.", len(self.cache))
+            except Exception as e:
+                logger.error("Failed to load summary cache: %s", e)
+                self.cache = {}
+
+    def save(self):
+        """Saves cache to disk."""
+        try:
+            CACHE_FILE.parent.mkdir(parents=True, exist_ok=True)
+            with open(CACHE_FILE, "w", encoding="utf-8") as f:
+                json.dump(self.cache, f, indent=2, ensure_ascii=False)
+        except Exception as e:
+            logger.error("Failed to save summary cache: %s", e)
+
+    def get(self, file_path: Path) -> Optional[str]:
+        """Retrieves a cached summary if the file hasn't changed."""
+        file_hash = self._get_file_hash(file_path)
+        return self.cache.get(file_hash)
+
+    def set(self, file_path: Path, summary: str):
+        """Stores a summary in the cache."""
+        file_hash = self._get_file_hash(file_path)
+        self.cache[file_hash] = summary

plesk_unified/tq_index.py

@@ -0,0 +1,85 @@
+"""TurboQuantIndex loading strategy."""
+
+from __future__ import annotations
+
+import numpy as np
+import torch
+
+from plesk_unified.turboquant import TurboQuantProd
+
+
+class TurboQuantIndex:
+    def __init__(self, dim: int, bits: int = 3, device: str = "cpu"):
+        self.dim = dim
+        self.bits = bits
+        self.device = device
+        self.quantizer = TurboQuantProd(dim, bits, device=device)
+
+        # Batched tensors for compressed vectors.
+        self.compressed_db = None
+        self._meta = []
+        self._category_to_indices: dict[str, list[int]] = {}
+
+    def add(self, vecs: np.ndarray, metas: list[dict]) -> None:
+        # 1. L2-Normalize the input vectors (Critical for TurboQuant accuracy)
+        norms = np.linalg.norm(vecs, axis=-1, keepdims=True)
+        vecs_normalized = vecs / np.maximum(norms, 1e-12)
+
+        # 2. Quantize the entire batch at once
+        x = torch.from_numpy(vecs_normalized).to(self.device)
+        compressed = self.quantizer.quantize(x)
+
+        # 3. Store or append to the batched tensors in CPU memory
+        if self.compressed_db is None:
+            self.compressed_db = {k: v.cpu() for k, v in compressed.items()}
+        else:
+            for k in self.compressed_db:
+                self.compressed_db[k] = torch.cat(
+                    [self.compressed_db[k], compressed[k].cpu()], dim=0
+                )
+
+        start_idx = len(self._meta)
+        self._meta.extend(metas)
+        for offset, meta in enumerate(metas):
+            category = meta.get("category")
+            if isinstance(category, str) and category:
+                index = start_idx + offset
+                self._category_to_indices.setdefault(category, []).append(index)
+
+    def search(
+        self, query_vec: np.ndarray, top_k: int = 25, category: str | None = None
+    ):
+        if self.compressed_db is None:
+            return []
+
+        selected_indices: list[int]
+        if category:
+            selected_indices = self._category_to_indices.get(category, [])
+            if not selected_indices:
+                return []
+        else:
+            selected_indices = list(range(len(self._meta)))
+
+        # 1. L2-Normalize the query
+        norm = np.linalg.norm(query_vec)
+        query_normalized = query_vec / max(norm, 1e-12)
+
+        # 2. Prepare query as a batched tensor (1, dim)
+        q = torch.from_numpy(query_normalized).to(self.device).unsqueeze(0)
+
+        # 3. Slice candidates and move them to the target device.
+        selected_tensor = torch.as_tensor(selected_indices, dtype=torch.long)
+        db_on_device = {
+            k: v.index_select(0, selected_tensor).to(self.device)
+            for k, v in self.compressed_db.items()
+        }
+
+        # 4. Perform a SINGLE batched inner product calculation
+        with torch.no_grad():
+            scores = self.quantizer.inner_product(q, db_on_device).squeeze(0)
+
+        # 5. Sort and return
+        scores_np = scores.cpu().numpy()
+        idx = np.argsort(-scores_np)[:top_k]
+
+        return [(self._meta[selected_indices[i]], float(scores_np[i])) for i in idx]

plesk_unified/turboquant/__init__.py

@@ -0,0 +1,21 @@
+"""TurboQuant helpers used by the unified retrieval path.
+
+Base implementation: https://github.com/tonbistudio/turboquant-pytorch
+"""
+
+from __future__ import annotations
+
+from .compressors import TurboQuantCompressorMSE, TurboQuantCompressorV2
+from .lloyd_max import LloydMaxCodebook, compute_expected_distortion, solve_lloyd_max
+from .turboquant import TurboQuantKVCache, TurboQuantMSE, TurboQuantProd
+
+__all__ = [
+    "TurboQuantCompressorMSE",
+    "TurboQuantCompressorV2",
+    "TurboQuantKVCache",
+    "TurboQuantMSE",
+    "TurboQuantProd",
+    "LloydMaxCodebook",
+    "compute_expected_distortion",
+    "solve_lloyd_max",
+]