knowledge-rag 3.8.1 → 3.9.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +51 -4
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -11,6 +11,7 @@
|
|
|
11
11
|
|
|
12
12
|
[](https://github.com/lyonzin/knowledge-rag/actions/workflows/ci.yml)
|
|
13
13
|
[](https://github.com/lyonzin/knowledge-rag/actions/workflows/security.yml)
|
|
14
|
+
[](https://github.com/lyonzin/knowledge-rag/actions/workflows/quality-gate.yml)
|
|
14
15
|
[](https://glama.ai/mcp/servers/lyonzin/knowledge-rag)
|
|
15
16
|
|
|
16
17
|
### Your docs, your machine, zero cloud. Claude Code searches them natively.
|
|
@@ -27,19 +28,41 @@ pip install knowledge-rag → restart Claude Code → search_knowledge("your que
|
|
|
27
28
|
|
|
28
29
|
**12 MCP Tools** | **Hybrid Search + Reranking** | **20 File Formats** | **Optional NVIDIA GPU** | **100% Local**
|
|
29
30
|
|
|
30
|
-
[What's New](#whats-new-in-
|
|
31
|
+
[What's New](#whats-new-in-v390) | [Supported Formats](#supported-formats) | [Installation](#installation) | [Configuration](#configuration) | [API Reference](#api-reference) | [Architecture](#architecture)
|
|
31
32
|
|
|
32
33
|
</div>
|
|
33
34
|
|
|
34
35
|
---
|
|
35
36
|
|
|
36
|
-
## What's New in v3.
|
|
37
|
+
## What's New in v3.9.0
|
|
37
38
|
|
|
38
|
-
###
|
|
39
|
+
### Quality Gate — 7-Pillar PR Validation
|
|
40
|
+
|
|
41
|
+
knowledge-rag is now used daily by 70+ enterprise teams. Every PR (including dependabot bumps and one-line fixes) is now evaluated against **35+ automated checks** spread across 7 pillars before any human review:
|
|
42
|
+
|
|
43
|
+
| Pillar | What it enforces | Tools |
|
|
44
|
+
|---|---|---|
|
|
45
|
+
| **1 Security** | SAST, secrets, CVEs, supply chain | bandit, semgrep, gitleaks, pip-audit, dependency-review, Snyk, CodeQL, Socket |
|
|
46
|
+
| **2 Stability** | Flake detection, coverage trend, test count, deterministic runs | pytest-rerunfailures, codecov ±0.5pp, test-count guard |
|
|
47
|
+
| **3 Memory Leak** | RSS bounded under 1000-query load, no idle bloat | psutil-based baseline tests + nightly 50K-iteration soak |
|
|
48
|
+
| **4 Versatility** | 9 OS×Python combos, 14 format parsers, 4 config presets, locale tolerance, property-based fuzzing | matrix CI on Linux+Windows+macOS × 3.11+3.12+3.13, Hypothesis |
|
|
49
|
+
| **5 Scalability** | Performance regression > 10% blocks merge, public bench dashboard | pytest-benchmark, GH Pages chart |
|
|
50
|
+
| **6 Versioning** | Atomic version sync, API surface diff, conventional commits, CHANGELOG enforcement, backwards compat | griffe-style AST diff, custom guards |
|
|
51
|
+
| **7 Quality** | Type strictness, docstring coverage, complexity, dead code | mypy strict, interrogate ≥80%, radon, vulture |
|
|
52
|
+
|
|
53
|
+
Plus a **nightly resilience workflow** that runs chaos failure-injection (HF down, ChromaDB corruption, watchdog crash, ONNX zero-byte replay), determinism check (full suite × 3), and mutation testing on selected modules.
|
|
54
|
+
|
|
55
|
+
Read the full philosophy in [CONTRIBUTING.md](CONTRIBUTING.md). Report bugs via [SECURITY.md](SECURITY.md) or the [issue templates](.github/ISSUE_TEMPLATE/).
|
|
56
|
+
|
|
57
|
+
### Critical Hotfix — No More Silent Zero-Vector Corruption (v3.8.1)
|
|
58
|
+
|
|
59
|
+
`FastEmbedEmbeddings.__call__` no longer swallows exceptions and returns `[[0.0]*dim, ...]` when the ONNX model fails to load. That bug pre-existed in master but was silent: ChromaDB happily stored zero embeddings, `count()` reported normal numbers, smart-reindex skipped them as "already indexed", and queries returned garbage similarity with no error visible. Now raises `EmbeddingModelLoadError` / `EmbeddingError` loudly. **All v3.8.0 users should upgrade.** Full details in [Changelog](#v381-2026-05-10--hotfix).
|
|
60
|
+
|
|
61
|
+
### Lazy-Loaded Embeddings — Cheaper Idle Processes (v3.8.0)
|
|
39
62
|
|
|
40
63
|
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.
|
|
41
64
|
|
|
42
|
-
### Opt-In Single-Instance Guard
|
|
65
|
+
### Opt-In Single-Instance Guard (v3.8.0)
|
|
43
66
|
|
|
44
67
|
For users who measured their setup and want a hard cap of one server per `data_dir`:
|
|
45
68
|
|
|
@@ -63,6 +86,8 @@ All methods produce the same MCP server. See [Installation](#installation) for f
|
|
|
63
86
|
|
|
64
87
|
### Recent Highlights
|
|
65
88
|
|
|
89
|
+
- **v3.9.0** — **Quality Gate** activated: 35+ automated PR checks across 7 pillars (Security, Stability, Memory Leak, Versatility, Scalability, Versioning, Quality) + nightly resilience suite (chaos, soak, determinism, mutation)
|
|
90
|
+
- **v3.8.1** — Critical hotfix: loud-fail embeddings (no more silent zero-vector corruption); Windows CI flake erradicated (HF_HUB_OFFLINE + shell:bash + atexit wrapper)
|
|
66
91
|
- **v3.8.0** — Lazy-load embeddings, opt-in single-instance guard, version sync across PyPI/NPM/Docker
|
|
67
92
|
- **v3.6.0** — Multi-language code parsing (C/C++/JS/TS/XML), NPM wrapper, Docker image, automated release pipeline
|
|
68
93
|
- **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
|
|
@@ -1077,6 +1102,28 @@ A second instance exits immediately with code 75. Default is OFF (multi-client f
|
|
|
1077
1102
|
|
|
1078
1103
|
## Changelog
|
|
1079
1104
|
|
|
1105
|
+
### v3.9.0 (2026-05-10) — Quality Gate
|
|
1106
|
+
|
|
1107
|
+
**Major governance + CI hardening release. No runtime behavior change in `mcp_server/`. Public API surface unchanged from v3.8.1.**
|
|
1108
|
+
|
|
1109
|
+
- **NEW** Quality Gate workflow (`.github/workflows/quality-gate.yml`) enforcing the 7 pillars on every PR: Security, Stability, Memory Leak, Versatility, Scalability, Versioning, Quality. 35+ status checks total.
|
|
1110
|
+
- **NEW** Nightly resilience workflow (`.github/workflows/nightly.yml`): chaos suite (failure injection), 1h soak test (50K-iteration loop), determinism check (full suite × 3), mutation testing (mutmut). Auto-opens GitHub issue on any nightly failure.
|
|
1111
|
+
- **NEW** Performance benchmark suite under `bench/` (12 microbenchmarks, pytest-benchmark) with 10% regression gate on every PR.
|
|
1112
|
+
- **NEW** Public performance dashboard via GitHub Pages (`.github/workflows/bench-pages.yml`) — chart of latency/throughput per commit. Dormant until repo Pages is enabled.
|
|
1113
|
+
- **NEW** Property-based fuzzing of all parsers via Hypothesis (`tests/test_ingestion_property.py`) — 200 random examples per CI run.
|
|
1114
|
+
- **NEW** Memory baseline regression tests (`tests/test_memory_baseline.py`, cross-platform via psutil) — RSS bounded under 1000 queries; nightly soak amplifies to 50K iterations.
|
|
1115
|
+
- **NEW** Property/locale/format/preset matrices (`tests/test_presets.py`, `tests/test_locale.py`, `tests/test_format_smoke.py`).
|
|
1116
|
+
- **NEW** Backwards-compatibility regression tests (`tests/test_backwards_compat.py`) — legacy YAML configs from v3.6.0 / v3.7.0 still parse; all 12 MCP tool parameter names frozen.
|
|
1117
|
+
- **NEW** AST-based public API surface diff (`scripts/check_api_surface.py`) — any breaking change blocks merge, baseline at `.github/api-surface-baseline.json`.
|
|
1118
|
+
- **NEW** CHANGELOG enforcement (`scripts/check_changelog.py`) — user-facing PRs must add a bullet under `## Unreleased`; bypass via `skip-changelog` label.
|
|
1119
|
+
- **NEW** Test count anti-regression (`scripts/check_test_count.py`) — guards against silent test deletion.
|
|
1120
|
+
- **NEW** Conventional commits required on every PR title (commitlint via `amannn/action-semantic-pull-request`).
|
|
1121
|
+
- **NEW** mypy `--strict` rolling out per-module (currently `instance_lock.py` + `preflight.py` + `scripts/`); interrogate docstring coverage ≥ 80%; radon, vulture, PR-size guard report-only.
|
|
1122
|
+
- **NEW** CI matrix expanded to 9 cells: Linux + Windows + **macOS** × 3.11 + 3.12 + **3.13** (all required at v3.9.0; macOS / 3.13 promoted from experimental after two clean cycles).
|
|
1123
|
+
- **NEW** Governance docs: `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md`, `.github/PULL_REQUEST_TEMPLATE.md`, 3 issue templates, expanded `CODEOWNERS`.
|
|
1124
|
+
- **NEW** Pre-commit hooks: ruff, gitleaks, version-sync, conventional commits.
|
|
1125
|
+
- **CHORE** `.github/codecov.yml` enforcing coverage trend gate (-0.5pp blocks; new code ≥ 70%).
|
|
1126
|
+
|
|
1080
1127
|
### v3.8.1 (2026-05-10) — hotfix
|
|
1081
1128
|
|
|
1082
1129
|
- **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)
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "knowledge-rag",
|
|
3
|
-
"version": "3.
|
|
3
|
+
"version": "3.9.0",
|
|
4
4
|
"description": "Local RAG System for Claude Code — Hybrid search + Cross-encoder Reranking + 12 MCP Tools + 20 Format Parsers. Zero external servers.",
|
|
5
5
|
"bin": {
|
|
6
6
|
"knowledge-rag": "./bin/cli.js"
|