knowledge-rag 3.7.0__tar.gz → 3.8.1__tar.gz

{knowledge_rag-3.7.0 → knowledge_rag-3.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: knowledge-rag
-Version: 3.7.0
+Version: 3.8.1
 Summary: Local RAG System for Claude Code — Hybrid search + Cross-encoder Reranking + 12 MCP Tools + 20 Format Parsers. Zero external servers.
 Project-URL: Homepage, https://github.com/lyonzin/knowledge-rag
 Project-URL: Repository, https://github.com/lyonzin/knowledge-rag
@@ -42,7 +42,7 @@ Description-Content-Type: text/markdown
 
 [![PyPI](https://img.shields.io/pypi/v/knowledge-rag)](https://pypi.org/project/knowledge-rag/)
 [![NPM](https://img.shields.io/npm/v/knowledge-rag)](https://www.npmjs.com/package/knowledge-rag)
-[![Downloads](https://static.pepy.tech/badge/knowledge-rag/month)](https://pepy.tech/project/knowledge-rag)
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/knowledge-rag?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/knowledge-rag)
 ![Python](https://img.shields.io/badge/python-3.11%2B-green.svg)
 ![License](https://img.shields.io/badge/license-MIT-yellow.svg)
 ![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey.svg)
@@ -71,11 +71,21 @@ pip install knowledge-rag → restart Claude Code → search_knowledge("your que
 
 ---
 
-## What's New in v3.6.0
+## What's New in v3.8.0
 
-### Multi-Language Code Parsing
+### Lazy-Loaded Embeddings — Cheaper Idle Processes
 
-Language-aware extraction for **C**, **C++**, **JavaScript**, **TypeScript**, and **XML** — functions, classes, structs, interfaces, imports, and namespaces are captured as searchable metadata. Total supported formats: **20**.
+The FastEmbed ONNX model (~200MB resident) now loads on the **first query**, not at startup. Idle `knowledge-rag` processes are now genuinely cheap. Why this matters: MCP stdio is one-process-per-client by protocol — multiple Claude Code windows, Claude Desktop + IDE simultaneously, or review/approval flows that open extra connections all spawn their own processes. Before v3.8.0, every one of them paid the full embedding-model cost up front. Now only processes that actually serve queries load the model. Public API is unchanged.
+
+### Opt-In Single-Instance Guard
+
+For users who measured their setup and want a hard cap of one server per `data_dir`:
+
+```bash
+export KNOWLEDGE_RAG_SINGLE_INSTANCE=1
+```
+
+A second instance exits immediately with code 75. **OFF by default** so multi-client MCP usage continues to work unchanged. Stale-PID recovery + SIGINT/SIGTERM cleanup wired correctly. Full guide in [docs/single-instance.md](docs/single-instance.md). Sample MCP config in [examples/mcp-config-single-instance.json](examples/mcp-config-single-instance.json).
 
 ### 5 Ways to Install
 
@@ -91,6 +101,7 @@ All methods produce the same MCP server. See [Installation](#installation) for f
 
 ### Recent Highlights
 
+- **v3.8.0** — Lazy-load embeddings, opt-in single-instance guard, version sync across PyPI/NPM/Docker
 - **v3.6.0** — Multi-language code parsing (C/C++/JS/TS/XML), NPM wrapper, Docker image, automated release pipeline
 - **v3.5.2** — CUDA DLL auto-discovery from pip packages, graceful GPU→CPU fallback, explicit CPU provider (no CUDA noise when `gpu: false`), BASE_DIR resolution fix for editable installs
 - **v3.5.1** — Remove Python `<3.13` upper bound — 3.13 and 3.14 now supported
@@ -1088,12 +1099,41 @@ The cross-encoder reranker model is lazy-loaded on the first query. This adds a
 
 ### Memory usage
 
-With ~200 documents, expect ~300-500MB RAM. The embedding model (~50MB) and reranker (~25MB) are loaded into memory. For very large knowledge bases (1000+ documents), consider enabling GPU acceleration and using exclude patterns to limit index scope.
+With ~200 documents, expect ~300-500MB RAM. The embedding model (~200MB ONNX runtime resident, lazy-loaded on first query since v3.8.0) and reranker (~25MB, lazy-loaded) are loaded into memory only when actually used. For very large knowledge bases (1000+ documents), consider enabling GPU acceleration and using exclude patterns to limit index scope.
+
+### Multiple MCP clients spawn duplicate servers
+
+MCP stdio is one process per client by protocol — multiple Claude Code windows, Claude Desktop + IDE, etc. each spawn their own `knowledge-rag` process. Since v3.8.0 idle processes are cheap (no embedding model loaded until first query). If you've measured and want a hard cap of one server per data directory, opt in:
+
+```bash
+export KNOWLEDGE_RAG_SINGLE_INSTANCE=1
+```
+
+A second instance exits immediately with code 75. Default is OFF (multi-client friendly). Full guide: [docs/single-instance.md](docs/single-instance.md). Sample MCP config: [examples/mcp-config-single-instance.json](examples/mcp-config-single-instance.json).
 
 ---
 
 ## Changelog
 
+### v3.8.1 (2026-05-10) — hotfix
+
+- **FIX (critical)**: `FastEmbedEmbeddings.__call__` no longer returns vectors of zeros when the ONNX model fails to load or `embed()` raises. The previous behavior silently corrupted the index — ChromaDB stored zero embeddings, `count()` reported normal numbers, smart-reindex skipped the bad chunks, and queries returned garbage scores with no error visible. Now raises `EmbeddingModelLoadError` / `EmbeddingError`. (#36)
+- **FIX**: Sticky `_load_failed` flag — after a load failure, subsequent calls re-raise immediately instead of looping through HuggingFace download attempts (was the "frozen query" UX in v3.8.0).
+- **NEW**: Sanity checks in `__call__` — embed count and dim mismatches raise `EmbeddingError` instead of silently returning malformed vectors.
+- **TEST**: 7 new regression cases in `tests/test_lazy_embeddings.py`, including `test_does_not_return_zero_vectors_silently` as a guard for the whole class of bug.
+- **NOTE**: This is a pre-existing bug in master, not introduced by v3.8.0. v3.8.0 lazy-load expanded the impact (failures moved to query time). All v3.8.0 users should upgrade.
+
+### v3.8.0 (2026-05-10)
+
+- **NEW**: Lazy-load FastEmbed embedding model (~200MB ONNX runtime). Loads on first query instead of startup — idle `knowledge-rag` processes are now cheap, which matters when MCP stdio clients spawn parallel server processes (multiple Claude Code windows, Claude Desktop + IDE, etc.). Public API unchanged. (#32)
+- **NEW**: Opt-in single-instance guard via `KNOWLEDGE_RAG_SINGLE_INSTANCE=1` env var. **OFF by default** — multi-client MCP usage continues to work unchanged. When enabled, a second server process for the same `data_dir` exits with code 75 (`EX_TEMPFAIL`). Includes stale-PID recovery and SIGINT/SIGTERM handlers. See [docs/single-instance.md](docs/single-instance.md). (#33, original concept by @Hohlas in #31)
+- **NEW**: `examples/mcp-config-single-instance.json` — sample MCP client config for the opt-in guard.
+- **DOCS**: New `docs/single-instance.md` — when to use, when NOT to use, troubleshooting, full activation reference.
+- **DOCS**: README troubleshooting section for "Multiple MCP clients spawn duplicate servers" + memory-usage note for lazy embeddings.
+- **CHORE**: Sync version across `pyproject.toml`, `mcp_server/__init__.py`, and `npm/package.json` (was drifting since v3.5.x).
+- **CHORE**: pytest `tmp_path_retention_count=1` to avoid Windows atexit cleanup race in CI.
+- **ROADMAP**: Tracked v4.0 shared-service architecture (one daemon, many thin MCP clients) as the long-term fix for multi-process resource duplication. (#34)
+
 ### Unreleased
 
 - **FIX**: Startup preflight probes ChromaDB in a child process and moves crashing persistent indexes to `data/backups/auto-repair-*` before MCP initialization.

{knowledge_rag-3.7.0 → knowledge_rag-3.8.1}/README.md

@@ -4,7 +4,7 @@
 
 [![PyPI](https://img.shields.io/pypi/v/knowledge-rag)](https://pypi.org/project/knowledge-rag/)
 [![NPM](https://img.shields.io/npm/v/knowledge-rag)](https://www.npmjs.com/package/knowledge-rag)
-[![Downloads](https://static.pepy.tech/badge/knowledge-rag/month)](https://pepy.tech/project/knowledge-rag)
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/knowledge-rag?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/knowledge-rag)
 ![Python](https://img.shields.io/badge/python-3.11%2B-green.svg)
 ![License](https://img.shields.io/badge/license-MIT-yellow.svg)
 ![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey.svg)
@@ -33,11 +33,21 @@ pip install knowledge-rag → restart Claude Code → search_knowledge("your que
 
 ---
 
-## What's New in v3.6.0
+## What's New in v3.8.0
 
-### Multi-Language Code Parsing
+### Lazy-Loaded Embeddings — Cheaper Idle Processes
 
-Language-aware extraction for **C**, **C++**, **JavaScript**, **TypeScript**, and **XML** — functions, classes, structs, interfaces, imports, and namespaces are captured as searchable metadata. Total supported formats: **20**.
+The FastEmbed ONNX model (~200MB resident) now loads on the **first query**, not at startup. Idle `knowledge-rag` processes are now genuinely cheap. Why this matters: MCP stdio is one-process-per-client by protocol — multiple Claude Code windows, Claude Desktop + IDE simultaneously, or review/approval flows that open extra connections all spawn their own processes. Before v3.8.0, every one of them paid the full embedding-model cost up front. Now only processes that actually serve queries load the model. Public API is unchanged.
+
+### Opt-In Single-Instance Guard
+
+For users who measured their setup and want a hard cap of one server per `data_dir`:
+
+```bash
+export KNOWLEDGE_RAG_SINGLE_INSTANCE=1
+```
+
+A second instance exits immediately with code 75. **OFF by default** so multi-client MCP usage continues to work unchanged. Stale-PID recovery + SIGINT/SIGTERM cleanup wired correctly. Full guide in [docs/single-instance.md](docs/single-instance.md). Sample MCP config in [examples/mcp-config-single-instance.json](examples/mcp-config-single-instance.json).
 
 ### 5 Ways to Install
 
@@ -53,6 +63,7 @@ All methods produce the same MCP server. See [Installation](#installation) for f
 
 ### Recent Highlights
 
+- **v3.8.0** — Lazy-load embeddings, opt-in single-instance guard, version sync across PyPI/NPM/Docker
 - **v3.6.0** — Multi-language code parsing (C/C++/JS/TS/XML), NPM wrapper, Docker image, automated release pipeline
 - **v3.5.2** — CUDA DLL auto-discovery from pip packages, graceful GPU→CPU fallback, explicit CPU provider (no CUDA noise when `gpu: false`), BASE_DIR resolution fix for editable installs
 - **v3.5.1** — Remove Python `<3.13` upper bound — 3.13 and 3.14 now supported
@@ -1050,12 +1061,41 @@ The cross-encoder reranker model is lazy-loaded on the first query. This adds a
 
 ### Memory usage
 
-With ~200 documents, expect ~300-500MB RAM. The embedding model (~50MB) and reranker (~25MB) are loaded into memory. For very large knowledge bases (1000+ documents), consider enabling GPU acceleration and using exclude patterns to limit index scope.
+With ~200 documents, expect ~300-500MB RAM. The embedding model (~200MB ONNX runtime resident, lazy-loaded on first query since v3.8.0) and reranker (~25MB, lazy-loaded) are loaded into memory only when actually used. For very large knowledge bases (1000+ documents), consider enabling GPU acceleration and using exclude patterns to limit index scope.
+
+### Multiple MCP clients spawn duplicate servers
+
+MCP stdio is one process per client by protocol — multiple Claude Code windows, Claude Desktop + IDE, etc. each spawn their own `knowledge-rag` process. Since v3.8.0 idle processes are cheap (no embedding model loaded until first query). If you've measured and want a hard cap of one server per data directory, opt in:
+
+```bash
+export KNOWLEDGE_RAG_SINGLE_INSTANCE=1
+```
+
+A second instance exits immediately with code 75. Default is OFF (multi-client friendly). Full guide: [docs/single-instance.md](docs/single-instance.md). Sample MCP config: [examples/mcp-config-single-instance.json](examples/mcp-config-single-instance.json).
 
 ---
 
 ## Changelog
 
+### v3.8.1 (2026-05-10) — hotfix
+
+- **FIX (critical)**: `FastEmbedEmbeddings.__call__` no longer returns vectors of zeros when the ONNX model fails to load or `embed()` raises. The previous behavior silently corrupted the index — ChromaDB stored zero embeddings, `count()` reported normal numbers, smart-reindex skipped the bad chunks, and queries returned garbage scores with no error visible. Now raises `EmbeddingModelLoadError` / `EmbeddingError`. (#36)
+- **FIX**: Sticky `_load_failed` flag — after a load failure, subsequent calls re-raise immediately instead of looping through HuggingFace download attempts (was the "frozen query" UX in v3.8.0).
+- **NEW**: Sanity checks in `__call__` — embed count and dim mismatches raise `EmbeddingError` instead of silently returning malformed vectors.
+- **TEST**: 7 new regression cases in `tests/test_lazy_embeddings.py`, including `test_does_not_return_zero_vectors_silently` as a guard for the whole class of bug.
+- **NOTE**: This is a pre-existing bug in master, not introduced by v3.8.0. v3.8.0 lazy-load expanded the impact (failures moved to query time). All v3.8.0 users should upgrade.
+
+### v3.8.0 (2026-05-10)
+
+- **NEW**: Lazy-load FastEmbed embedding model (~200MB ONNX runtime). Loads on first query instead of startup — idle `knowledge-rag` processes are now cheap, which matters when MCP stdio clients spawn parallel server processes (multiple Claude Code windows, Claude Desktop + IDE, etc.). Public API unchanged. (#32)
+- **NEW**: Opt-in single-instance guard via `KNOWLEDGE_RAG_SINGLE_INSTANCE=1` env var. **OFF by default** — multi-client MCP usage continues to work unchanged. When enabled, a second server process for the same `data_dir` exits with code 75 (`EX_TEMPFAIL`). Includes stale-PID recovery and SIGINT/SIGTERM handlers. See [docs/single-instance.md](docs/single-instance.md). (#33, original concept by @Hohlas in #31)
+- **NEW**: `examples/mcp-config-single-instance.json` — sample MCP client config for the opt-in guard.
+- **DOCS**: New `docs/single-instance.md` — when to use, when NOT to use, troubleshooting, full activation reference.
+- **DOCS**: README troubleshooting section for "Multiple MCP clients spawn duplicate servers" + memory-usage note for lazy embeddings.
+- **CHORE**: Sync version across `pyproject.toml`, `mcp_server/__init__.py`, and `npm/package.json` (was drifting since v3.5.x).
+- **CHORE**: pytest `tmp_path_retention_count=1` to avoid Windows atexit cleanup race in CI.
+- **ROADMAP**: Tracked v4.0 shared-service architecture (one daemon, many thin MCP clients) as the long-term fix for multi-process resource duplication. (#34)
+
 ### Unreleased
 
 - **FIX**: Startup preflight probes ChromaDB in a child process and moves crashing persistent indexes to `data/backups/auto-repair-*` before MCP initialization.

{knowledge_rag-3.7.0 → knowledge_rag-3.8.1}/mcp_server/__init__.py

@@ -8,7 +8,7 @@ import sys  # noqa: I001
 _original_stdout = sys.stdout
 sys.stdout = sys.stderr
 
-__version__ = "3.5.2"
+__version__ = "3.8.1"
 __author__ = "Ailton Rocha (Lyon.)"
 
 from .config import Config  # noqa: E402

knowledge_rag-3.8.1/mcp_server/instance_lock.py

@@ -0,0 +1,188 @@
+"""Optional single-instance guard for the MCP server process.
+
+Background
+----------
+MCP stdio servers are 1-process-per-client by protocol design. Multiple
+Claude Code windows, Claude Desktop + IDE running simultaneously, or clients
+that open extra internal connections during approval/review flows will all
+spawn additional `knowledge-rag` processes. Each process holds its own
+embedding model, ChromaDB client, BM25 state, and file watcher.
+
+Lazy-loading the embedding model (v3.8.0) reduces idle cost dramatically,
+but some users still want a hard cap of one process per data directory.
+This module provides that cap as an OPT-IN, never as a default.
+
+Activation
+----------
+Set the environment variable in your MCP client config:
+
+    KNOWLEDGE_RAG_SINGLE_INSTANCE=1     # also accepts: true, yes, on (case-insensitive)
+
+When unset (default), `single_instance_lock()` is a no-op and the server
+behaves exactly as it did before this module existed.
+
+When enabled, the server creates `<data_dir>/knowledge-rag.lock` containing
+its PID. A second process starting against the same `data_dir` will detect
+the live PID and exit with code 75 (EX_TEMPFAIL). Stale locks (PID gone)
+are cleaned up automatically.
+
+Cleanup is wired in three places so the lock does not outlive the process:
+1. Normal exit: contextmanager `finally` block removes the lock.
+2. SIGINT / SIGTERM: handlers remove the lock and re-raise the default action.
+3. Crash / SIGKILL: stale-PID detection on the next startup removes it.
+
+Authors
+-------
+- Concept and original guard: Sergey Khokhlov (@Hohlas) in PR #31
+- Reworked as opt-in + signal handlers + tests: Lyon. (knowledge-rag maintainer)
+"""
+
+from __future__ import annotations
+
+import os
+import signal
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Iterator, Optional
+
+from .config import config
+
+LOCK_FILENAME = "knowledge-rag.lock"
+ALREADY_RUNNING_EXIT_CODE = 75  # EX_TEMPFAIL from sysexits.h
+ENV_VAR = "KNOWLEDGE_RAG_SINGLE_INSTANCE"
+_TRUTHY = {"1", "true", "yes", "on"}
+
+
+class AlreadyRunningError(RuntimeError):
+    """Raised when another knowledge-rag server instance already holds the lock."""
+
+
+def single_instance_enabled() -> bool:
+    """Return True if the user opted into the single-instance guard.
+
+    Reads `KNOWLEDGE_RAG_SINGLE_INSTANCE`. Accepts ``1``, ``true``, ``yes``, ``on``
+    (case-insensitive, surrounding whitespace ignored). Anything else — including
+    unset, empty, ``0``, ``false`` — leaves the guard disabled.
+    """
+    raw = os.environ.get(ENV_VAR, "").strip().lower()
+    return raw in _TRUTHY
+
+
+def _pid_is_running(pid: int) -> bool:
+    """Return True if a process with PID appears to be alive."""
+    if pid <= 0:
+        return False
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        # Process exists but is owned by another user / has tighter ACLs
+        return True
+    except OSError:
+        return False
+    return True
+
+
+def _read_lock_pid(lock_path: Path) -> Optional[int]:
+    try:
+        raw = lock_path.read_text(encoding="utf-8").strip().splitlines()[0]
+        return int(raw)
+    except (IndexError, OSError, ValueError):
+        return None
+
+
+def _lock_path() -> Path:
+    return config.data_dir / LOCK_FILENAME
+
+
+def _remove_if_ours(lock_path: Path) -> None:
+    """Remove the lock file ONLY if it still references our PID."""
+    if _read_lock_pid(lock_path) == os.getpid():
+        try:
+            lock_path.unlink()
+        except FileNotFoundError:
+            pass
+        except OSError:
+            # Best-effort; stale-PID check on next startup will recover
+            pass
+
+
+@contextmanager
+def single_instance_lock() -> Iterator[Optional[Path]]:
+    """Acquire the single-instance lock if opt-in flag is set.
+
+    No-op when ``KNOWLEDGE_RAG_SINGLE_INSTANCE`` is unset / falsy — yields ``None``
+    and the caller proceeds normally with no side effects on disk.
+
+    When enabled:
+      - Creates ``<data_dir>/knowledge-rag.lock`` containing this process's PID.
+      - Raises :class:`AlreadyRunningError` if another live PID already holds it.
+      - Recovers stale locks (PID no longer running).
+      - Registers SIGINT/SIGTERM handlers that remove the lock and re-raise.
+      - Removes the lock on normal exit via ``finally``.
+    """
+    if not single_instance_enabled():
+        yield None
+        return
+
+    config.data_dir.mkdir(parents=True, exist_ok=True)
+    lock_path = _lock_path()
+
+    while True:
+        try:
+            fd = os.open(lock_path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o644)
+        except FileExistsError:
+            pid = _read_lock_pid(lock_path)
+            if pid is not None and _pid_is_running(pid):
+                raise AlreadyRunningError(
+                    f"knowledge-rag MCP server is already running (pid {pid}). "
+                    f"Refusing to start a second instance because "
+                    f"{ENV_VAR} is enabled."
+                )
+            try:
+                lock_path.unlink()
+            except FileNotFoundError:
+                pass
+            except OSError as exc:
+                raise AlreadyRunningError(f"Failed to clear stale lock {lock_path}: {exc}") from exc
+            continue
+
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            f.write(f"{os.getpid()}\n")
+        break
+
+    # Wire signal handlers so SIGINT/SIGTERM cleanup the lock before exit
+    previous_handlers: dict[int, object] = {}
+
+    def _signal_cleanup(signum: int, frame) -> None:
+        _remove_if_ours(lock_path)
+        # Restore original handler and re-raise so default action runs
+        prev = previous_handlers.get(signum, signal.SIG_DFL)
+        try:
+            signal.signal(signum, prev)  # type: ignore[arg-type]
+        except (ValueError, OSError):
+            pass
+        # Re-send the signal to ourselves so the original disposition fires
+        os.kill(os.getpid(), signum)
+
+    for sig_name in ("SIGINT", "SIGTERM"):
+        sig = getattr(signal, sig_name, None)
+        if sig is None:
+            continue
+        try:
+            previous_handlers[sig] = signal.getsignal(sig)
+            signal.signal(sig, _signal_cleanup)
+        except (ValueError, OSError):
+            # signal.signal raises if not on the main thread; tests may hit this
+            pass
+
+    try:
+        yield lock_path
+    finally:
+        _remove_if_ours(lock_path)
+        for sig, prev in previous_handlers.items():
+            try:
+                signal.signal(sig, prev)  # type: ignore[arg-type]
+            except (ValueError, OSError):
+                pass

{knowledge_rag-3.7.0 → knowledge_rag-3.8.1}/mcp_server/server.py

@@ -129,6 +129,18 @@ class QueryCache:
 # =============================================================================
 
 
+class EmbeddingError(RuntimeError):
+    """Raised when embedding generation fails after a successful model load."""
+
+
+class EmbeddingModelLoadError(RuntimeError):
+    """Raised when the embedding model itself cannot be loaded.
+
+    Distinct from EmbeddingError so callers can decide whether to retry
+    (transient runtime failure) or surface a hard configuration problem.
+    """
+
+
 class FastEmbedEmbeddings:
     """
     FastEmbed-based embedding function for ChromaDB (v1.4.0+ compatible).
@@ -136,6 +148,17 @@ class FastEmbedEmbeddings:
     Uses ONNX Runtime in-process for embedding generation.
     No external server required (replaces Ollama).
     Model: BAAI/bge-small-en-v1.5 (384-dim, MTEB score 62.x)
+
+    Lazy-loading (since v3.8.0):
+        The ONNX model (~200MB resident) is NOT loaded in __init__.
+        It loads on the first call to __call__/embed_query/embed_documents.
+        This makes idle MCP server processes cheap, which matters when
+        multiple stdio clients spawn parallel knowledge-rag processes
+        (e.g. multiple Claude Code windows). The CrossEncoderReranker
+        already follows this same pattern.
+
+        Thread-safe: load is guarded by a lock so concurrent first-callers
+        don't double-initialize the model.
     """
 
     @staticmethod
@@ -174,24 +197,62 @@ class FastEmbedEmbeddings:
     def __init__(self, model: str = None):
         self.model_name = model or config.embedding_model
         self._dim = config.embedding_dim
-        kwargs = {"model_name": self.model_name, "cache_dir": str(config.models_cache_dir)}
-        if config.gpu_acceleration:
-            self._setup_cuda_dll_paths()
-            kwargs["providers"] = ["CUDAExecutionProvider", "CPUExecutionProvider"]
-            print(f"[INFO] Loading embedding model: {self.model_name} ({self._dim}D) [GPU accelerated]...")
+        # Build kwargs once; defer the heavy TextEmbedding(**kwargs) call to first use.
+        self._init_kwargs = {"model_name": self.model_name, "cache_dir": str(config.models_cache_dir)}
+        self._gpu = bool(config.gpu_acceleration)
+        self._model: Optional[TextEmbedding] = None
+        self._load_lock = threading.Lock()
+        # Sticky failure flag: once load fails, subsequent calls re-raise immediately
+        # instead of looping through download/retry. Same pattern as CrossEncoderReranker.
+        self._load_failed: Optional[Exception] = None
+
+    def _load_model(self) -> None:
+        """Load the ONNX model on demand. Idempotent and thread-safe.
+
+        Raises:
+            EmbeddingModelLoadError: when the underlying ONNX runtime cannot
+                instantiate the model (missing files, hash mismatch, etc.). The
+                exception is sticky — subsequent calls raise the same error
+                without retrying so callers do not loop through HF downloads.
+        """
+        if self._model is not None:
+            return
+        if self._load_failed is not None:
+            raise EmbeddingModelLoadError(
+                f"Embedding model previously failed to load: {self._load_failed}"
+            ) from self._load_failed
+        with self._load_lock:
+            if self._model is not None:  # double-checked under the lock
+                return
+            if self._load_failed is not None:
+                raise EmbeddingModelLoadError(
+                    f"Embedding model previously failed to load: {self._load_failed}"
+                ) from self._load_failed
+            kwargs = dict(self._init_kwargs)
             try:
-                self._model = TextEmbedding(**kwargs)
-                print("[INFO] Embedding model loaded successfully [GPU]")
-            except (ValueError, RuntimeError) as e:
-                print(f"[WARN] GPU init failed ({e}), falling back to CPU...")
-                kwargs["providers"] = ["CPUExecutionProvider"]
-                self._model = TextEmbedding(**kwargs)
-                print("[INFO] Embedding model loaded successfully [CPU fallback]")
-        else:
-            kwargs["providers"] = ["CPUExecutionProvider"]
-            print(f"[INFO] Loading embedding model: {self.model_name} ({self._dim}D)...")
-            self._model = TextEmbedding(**kwargs)
-            print("[INFO] Embedding model loaded successfully")
+                if self._gpu:
+                    self._setup_cuda_dll_paths()
+                    kwargs["providers"] = ["CUDAExecutionProvider", "CPUExecutionProvider"]
+                    print(f"[INFO] Loading embedding model: {self.model_name} ({self._dim}D) [GPU accelerated]...")
+                    try:
+                        self._model = TextEmbedding(**kwargs)
+                        print("[INFO] Embedding model loaded successfully [GPU]")
+                    except (ValueError, RuntimeError) as e:
+                        print(f"[WARN] GPU init failed ({e}), falling back to CPU...")
+                        kwargs["providers"] = ["CPUExecutionProvider"]
+                        self._model = TextEmbedding(**kwargs)
+                        print("[INFO] Embedding model loaded successfully [CPU fallback]")
+                else:
+                    kwargs["providers"] = ["CPUExecutionProvider"]
+                    print(f"[INFO] Loading embedding model: {self.model_name} ({self._dim}D)...")
+                    self._model = TextEmbedding(**kwargs)
+                    print("[INFO] Embedding model loaded successfully")
+            except Exception as exc:
+                # ONNXRuntimeError, FileNotFoundError, etc. — record and re-raise loud
+                self._load_failed = exc
+                self._model = None
+                print(f"[ERROR] Embedding model load FAILED: {exc}", file=sys.stderr)
+                raise EmbeddingModelLoadError(f"Failed to load embedding model: {exc}") from exc
 
     def __call__(self, input: List[str]) -> List[List[float]]:
         """
@@ -199,16 +260,38 @@ class FastEmbedEmbeddings:
 
         ChromaDB embedding_function interface: __call__(input: List[str]) -> List[List[float]]
         FastEmbed.embed() returns a generator, so we consume it into a list.
+
+        Raises:
+            EmbeddingModelLoadError: when the model could not be loaded.
+            EmbeddingError: when embedding generation fails after a successful load.
+
+        Behavior note (changed in v3.8.1):
+            Previously this method swallowed any exception and returned vectors
+            of zeros (``[[0.0]*dim for _ in input]``). That silently corrupted
+            the index — ChromaDB stored zero vectors as document embeddings,
+            ``count()`` returned the right number of chunks, smart-reindex
+            would skip them as "already indexed", and queries returned garbage
+            similarity scores. Failures are now LOUD: the caller (ChromaDB
+            ``add()``, MCP search tool, etc.) sees the real error and can
+            surface it to the user.
         """
         if not input:
             return []
 
+        self._load_model()  # may raise EmbeddingModelLoadError
         try:
             embeddings = list(self._model.embed(input))
-            return [emb.tolist() for emb in embeddings]
-        except Exception as e:
-            print(f"[WARN] Embedding failed: {e}")
-            return [[0.0] * self._dim for _ in input]
+        except Exception as exc:
+            print(f"[ERROR] Embedding generation FAILED: {exc}", file=sys.stderr)
+            raise EmbeddingError(f"Embedding generation failed: {exc}") from exc
+
+        # Sanity check: model returned the right number of vectors with the right dim
+        if len(embeddings) != len(input):
+            raise EmbeddingError(f"Embedding count mismatch: expected {len(input)}, got {len(embeddings)}")
+        result = [emb.tolist() for emb in embeddings]
+        if result and len(result[0]) != self._dim:
+            raise EmbeddingError(f"Embedding dim mismatch: expected {self._dim}, got {len(result[0])}")
+        return result
 
     def name(self) -> str:
         """Return embedding function name (required by ChromaDB v1.4.0+)"""
@@ -1934,48 +2017,58 @@ def main():
         _handle_init()
         return
 
+    from .instance_lock import (
+        ALREADY_RUNNING_EXIT_CODE,
+        AlreadyRunningError,
+        single_instance_lock,
+    )
     from .preflight import run_preflight
 
-    run_preflight()
+    try:
+        with single_instance_lock():
+            run_preflight()
 
-    orchestrator = get_orchestrator()
+            orchestrator = get_orchestrator()
 
-    # Migration: check dimension mismatch AFTER full init (avoids segfault during __init__)
-    orchestrator._needs_rebuild = orchestrator._check_dimension_mismatch()
-    if orchestrator._needs_rebuild:
-        print("[MIGRATION] Running nuclear rebuild for embedding model change...")
-        try:
-            stats = orchestrator.nuclear_rebuild()
-            print(
-                f"[MIGRATION] Rebuild complete: {stats['indexed']} docs, "
-                f"{stats['chunks_added']} chunks in {stats.get('elapsed_seconds', '?')}s"
-            )
-        except Exception as e:
-            print(f"[ERROR] Migration failed: {e}")
-            print("[FALLBACK] Attempting regular index instead...")
-            stats = orchestrator.index_all(force=True)
-    elif orchestrator.collection.count() == 0:
-        print("[INFO] No documents indexed. Running initial indexing...")
-        stats = orchestrator.index_all()
-        print(f"[INFO] Indexed {stats['indexed']} documents with {stats['chunks_added']} chunks")
+            # Migration: check dimension mismatch AFTER full init (avoids segfault during __init__)
+            orchestrator._needs_rebuild = orchestrator._check_dimension_mismatch()
+            if orchestrator._needs_rebuild:
+                print("[MIGRATION] Running nuclear rebuild for embedding model change...")
+                try:
+                    stats = orchestrator.nuclear_rebuild()
+                    print(
+                        f"[MIGRATION] Rebuild complete: {stats['indexed']} docs, "
+                        f"{stats['chunks_added']} chunks in {stats.get('elapsed_seconds', '?')}s"
+                    )
+                except Exception as e:
+                    print(f"[ERROR] Migration failed: {e}")
+                    print("[FALLBACK] Attempting regular index instead...")
+                    stats = orchestrator.index_all(force=True)
+            elif orchestrator.collection.count() == 0:
+                print("[INFO] No documents indexed. Running initial indexing...")
+                stats = orchestrator.index_all()
+                print(f"[INFO] Indexed {stats['indexed']} documents with {stats['chunks_added']} chunks")
+
+            # Start file watcher for auto-reindex on document changes
+            try:
+                watcher = DocumentWatcher(get_orchestrator, debounce_seconds=5.0)
+                observer = Observer()
+                observer.schedule(watcher, str(config.documents_dir), recursive=True)
+                observer.daemon = True
+                observer.start()
+                print(f"[WATCHER] Monitoring {config.documents_dir} for changes")
+            except Exception as e:
+                print(f"[WARN] Failed to start file watcher: {e}")
+                print("[WARN] Auto-reindexing disabled. Use reindex_documents tool manually.")
 
-    # Start file watcher for auto-reindex on document changes
-    try:
-        watcher = DocumentWatcher(get_orchestrator, debounce_seconds=5.0)
-        observer = Observer()
-        observer.schedule(watcher, str(config.documents_dir), recursive=True)
-        observer.daemon = True
-        observer.start()
-        print(f"[WATCHER] Monitoring {config.documents_dir} for changes")
-    except Exception as e:
-        print(f"[WARN] Failed to start file watcher: {e}")
-        print("[WARN] Auto-reindexing disabled. Use reindex_documents tool manually.")
-
-    # Restore real stdout for MCP JSON-RPC, keep print() going to stderr
-    from . import _original_stdout
-
-    sys.stdout = _original_stdout
-    mcp.run()
+            # Restore real stdout for MCP JSON-RPC, keep print() going to stderr
+            from . import _original_stdout
+
+            sys.stdout = _original_stdout
+            mcp.run()
+    except AlreadyRunningError as e:
+        print(f"[ERROR] {e}", file=sys.stderr)
+        raise SystemExit(ALREADY_RUNNING_EXIT_CODE) from e
 
 
 if __name__ == "__main__":

{knowledge_rag-3.7.0 → knowledge_rag-3.8.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "knowledge-rag"
-version = "3.7.0"
+version = "3.8.1"
 description = "Local RAG System for Claude Code — Hybrid search + Cross-encoder Reranking + 12 MCP Tools + 20 Format Parsers. Zero external servers."
 readme = "README.md"
 license = {text = "MIT"}
@@ -95,6 +95,11 @@ exclude = [
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 pythonpath = ["."]
+# Limit retained tmp_path directories to avoid pytest's atexit cleanup race
+# on Windows (cleanup_numbered_dir + pathlib.glob "garbage-*" can fail when
+# many tmp dirs accumulate). Tests run isolated; we don't need history.
+tmp_path_retention_count = 1
+tmp_path_retention_policy = "failed"
 
 [tool.ruff]
 target-version = "py311"