knowledge-rag 3.3.0__tar.gz → 3.3.1__tar.gz

{knowledge_rag-3.3.0 → knowledge_rag-3.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: knowledge-rag
-Version: 3.3.0
+Version: 3.3.1
 Summary: Local RAG System for Claude Code — Hybrid search + Cross-encoder Reranking + 12 MCP Tools. Zero external servers.
 Project-URL: Homepage, https://github.com/lyonzin/knowledge-rag
 Project-URL: Repository, https://github.com/lyonzin/knowledge-rag
@@ -38,7 +38,7 @@ Description-Content-Type: text/markdown
 
 <div align="center">
 
-![Version](https://img.shields.io/badge/version-3.3.0-blue.svg)
+![Version](https://img.shields.io/badge/version-3.3.1-blue.svg)
 ![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12-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)
@@ -408,21 +408,23 @@ flowchart LR
 
 ### Quick Start (3 steps)
 
-**Step 1: Clone and install**
+**Step 1: Install**
 
 ```bash
-# Clone to your home directory
+# Option A: pip install (recommended)
+pip install knowledge-rag
+knowledge-rag init              # Exports config template, presets, creates documents/
+
+# Option B: Clone from source
 git clone https://github.com/lyonzin/knowledge-rag.git ~/knowledge-rag
 cd ~/knowledge-rag
-
-# Create virtual environment and install
 python3 -m venv venv
 source venv/bin/activate        # Linux/macOS
 # .\venv\Scripts\activate       # Windows
 pip install -r requirements.txt
 ```
 
-> **Windows users**: `~/knowledge-rag` becomes `C:\Users\YourName\knowledge-rag`. Use `python` instead of `python3`.
+> **Windows users**: Use `python` instead of `python3`.
 
 **Step 2: Configure Claude Code**
 
@@ -1193,6 +1195,12 @@ With ~200 documents, expect ~300-500MB RAM. The embedding model (~50MB) and rera
 
 ## Changelog
 
+### v3.3.1 (2026-04-06)
+
+- **FIX**: YAML null values (`category_mappings:` without value) no longer crash the server — falls back to defaults
+- **FIX**: Presets and config template now bundled in pip wheel (`knowledge-rag init` exports them)
+- **NEW**: `knowledge-rag init` CLI command — exports config template, presets, and creates documents/ in current directory
+
 ### v3.3.0 (2026-04-05)
 
 - **NEW**: YAML configuration system — fully customizable via `config.yaml`

{knowledge_rag-3.3.0 → knowledge_rag-3.3.1}/README.md

@@ -2,7 +2,7 @@
 
 <div align="center">
 
-![Version](https://img.shields.io/badge/version-3.3.0-blue.svg)
+![Version](https://img.shields.io/badge/version-3.3.1-blue.svg)
 ![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12-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)
@@ -372,21 +372,23 @@ flowchart LR
 
 ### Quick Start (3 steps)
 
-**Step 1: Clone and install**
+**Step 1: Install**
 
 ```bash
-# Clone to your home directory
+# Option A: pip install (recommended)
+pip install knowledge-rag
+knowledge-rag init              # Exports config template, presets, creates documents/
+
+# Option B: Clone from source
 git clone https://github.com/lyonzin/knowledge-rag.git ~/knowledge-rag
 cd ~/knowledge-rag
-
-# Create virtual environment and install
 python3 -m venv venv
 source venv/bin/activate        # Linux/macOS
 # .\venv\Scripts\activate       # Windows
 pip install -r requirements.txt
 ```
 
-> **Windows users**: `~/knowledge-rag` becomes `C:\Users\YourName\knowledge-rag`. Use `python` instead of `python3`.
+> **Windows users**: Use `python` instead of `python3`.
 
 **Step 2: Configure Claude Code**
 
@@ -1157,6 +1159,12 @@ With ~200 documents, expect ~300-500MB RAM. The embedding model (~50MB) and rera
 
 ## Changelog
 
+### v3.3.1 (2026-04-06)
+
+- **FIX**: YAML null values (`category_mappings:` without value) no longer crash the server — falls back to defaults
+- **FIX**: Presets and config template now bundled in pip wheel (`knowledge-rag init` exports them)
+- **NEW**: `knowledge-rag init` CLI command — exports config template, presets, and creates documents/ in current directory
+
 ### v3.3.0 (2026-04-05)
 
 - **NEW**: YAML configuration system — fully customizable via `config.yaml`

{knowledge_rag-3.3.0 → knowledge_rag-3.3.1}/mcp_server/config.py

@@ -44,6 +44,7 @@ else:
 # YAML CONFIG LOADER
 # ============================================================================
 
+
 def _load_yaml_config() -> dict:
     """Load config.yaml from BASE_DIR if it exists, otherwise return empty dict."""
     config_path = BASE_DIR / "config.yaml"
@@ -54,7 +55,7 @@ def _load_yaml_config() -> dict:
         with open(config_path, "r", encoding="utf-8") as f:
             data = yaml.safe_load(f)
         if not isinstance(data, dict):
-            print(f"[WARN] config.yaml is not a valid mapping, ignoring")
+            print("[WARN] config.yaml is not a valid mapping, ignoring")
             return {}
         print(f"[INFO] Loaded config from {config_path}")
         return data
@@ -75,6 +76,16 @@ def _get(section: str, key: str, default):
     return val if val is not None else default
 
 
+def _get_top(key: str, default):
+    """Get a top-level value from YAML, falling back to default if missing or None."""
+    val = _yaml.get(key)
+    if val is None:
+        return default
+    if not isinstance(val, type(default)):
+        return default
+    return val
+
+
 # ============================================================================
 # DEFAULTS (used when no config.yaml or field is omitted)
 # ============================================================================
@@ -92,44 +103,145 @@ _DEFAULT_CATEGORY_MAPPINGS = {
 
 _DEFAULT_KEYWORD_ROUTES = {
     "logscale": [
-        "logscale", "lql", "cql", "humio", "crowdstrike query",
-        "formattime", "groupby", "base64decode", "case{}", "regex",
+        "logscale",
+        "lql",
+        "cql",
+        "humio",
+        "crowdstrike query",
+        "formattime",
+        "groupby",
+        "base64decode",
+        "case{}",
+        "regex",
     ],
     "redteam": [
-        "pentest", "exploit", "payload", "reverse shell", "privilege escalation",
-        "lateral movement", "c2", "beacon", "cobalt strike", "metasploit",
-        "gtfobins", "lolbas", "lolbin", "suid", "sudo", "byovd", "lol driver",
-        "lolad", "lolapps", "hacktricks", "privesc", "kerberoast", "dcsync",
-        "golden ticket", "pass-the-hash", "bloodhound", "mimikatz", "rubeus",
-        "certipy", "adcs", "sqli", "xss", "ssti", "ssrf", "lfi", "rfi", "xxe",
-        "deserialization", "ysoserial", "upload bypass", "reverse shell",
-        "web shell", "hash cracking", "hashcat", "waf bypass", "amsi bypass",
-        "uac bypass", "potato", "searchsploit", "exploit-db", "cve",
+        "pentest",
+        "exploit",
+        "payload",
+        "reverse shell",
+        "privilege escalation",
+        "lateral movement",
+        "c2",
+        "beacon",
+        "cobalt strike",
+        "metasploit",
+        "gtfobins",
+        "lolbas",
+        "lolbin",
+        "suid",
+        "sudo",
+        "byovd",
+        "lol driver",
+        "lolad",
+        "lolapps",
+        "hacktricks",
+        "privesc",
+        "kerberoast",
+        "dcsync",
+        "golden ticket",
+        "pass-the-hash",
+        "bloodhound",
+        "mimikatz",
+        "rubeus",
+        "certipy",
+        "adcs",
+        "sqli",
+        "xss",
+        "ssti",
+        "ssrf",
+        "lfi",
+        "rfi",
+        "xxe",
+        "deserialization",
+        "ysoserial",
+        "upload bypass",
+        "reverse shell",
+        "web shell",
+        "hash cracking",
+        "hashcat",
+        "waf bypass",
+        "amsi bypass",
+        "uac bypass",
+        "potato",
+        "searchsploit",
+        "exploit-db",
+        "cve",
     ],
     "blueteam": [
-        "detection", "sigma", "yara", "ioc", "threat hunting",
-        "incident response", "forensics", "malware analysis",
+        "detection",
+        "sigma",
+        "yara",
+        "ioc",
+        "threat hunting",
+        "incident response",
+        "forensics",
+        "malware analysis",
     ],
     "ctf": [
-        "ctf", "flag", "hackthebox", "htb", "tryhackme",
-        "picoctf", "writeup", "challenge",
+        "ctf",
+        "flag",
+        "hackthebox",
+        "htb",
+        "tryhackme",
+        "picoctf",
+        "writeup",
+        "challenge",
     ],
     "development": [
-        "python", "typescript", "javascript", "api",
-        "fastapi", "django", "react", "nodejs",
+        "python",
+        "typescript",
+        "javascript",
+        "api",
+        "fastapi",
+        "django",
+        "react",
+        "nodejs",
     ],
     "security": [
-        "anti-bot", "antibot", "js challenge", "javascript challenge",
-        "cdp detection", "runtime.enable", "puppeteer", "playwright",
-        "selenium", "nodriver", "stealth", "undetected", "ja3", "ja4",
-        "tls fingerprint", "fingerprinting", "curl_cffi", "got-scraping",
-        "impersonate", "http/2 settings", "browser fingerprint",
-        "canvas fingerprint", "webgl fingerprint", "navigator.webdriver",
-        "audio context", "hardware concurrency", "waf bypass", "aws waf",
-        "cloudflare bypass", "akamai bypass", "datadome", "perimeterx",
-        "imperva bypass", "8kb bypass", "body size limit", "json sqli",
-        "behavioral", "mouse movement", "ghost-cursor", "humanized",
-        "flaresolverr", "turnstile", "rebrowser", "botbrowser",
+        "anti-bot",
+        "antibot",
+        "js challenge",
+        "javascript challenge",
+        "cdp detection",
+        "runtime.enable",
+        "puppeteer",
+        "playwright",
+        "selenium",
+        "nodriver",
+        "stealth",
+        "undetected",
+        "ja3",
+        "ja4",
+        "tls fingerprint",
+        "fingerprinting",
+        "curl_cffi",
+        "got-scraping",
+        "impersonate",
+        "http/2 settings",
+        "browser fingerprint",
+        "canvas fingerprint",
+        "webgl fingerprint",
+        "navigator.webdriver",
+        "audio context",
+        "hardware concurrency",
+        "waf bypass",
+        "aws waf",
+        "cloudflare bypass",
+        "akamai bypass",
+        "datadome",
+        "perimeterx",
+        "imperva bypass",
+        "8kb bypass",
+        "body size limit",
+        "json sqli",
+        "behavioral",
+        "mouse movement",
+        "ghost-cursor",
+        "humanized",
+        "flaresolverr",
+        "turnstile",
+        "rebrowser",
+        "botbrowser",
     ],
 }
 
@@ -210,6 +322,7 @@ _DEFAULT_QUERY_EXPANSIONS = {
 # CONFIG DATACLASS
 # ============================================================================
 
+
 def _resolve_path(raw, default: Path) -> Path:
     """Resolve a path from YAML (string) or use default (Path)."""
     if raw is None:
@@ -225,43 +338,93 @@ class Config:
     """Central configuration for the RAG system — loads from config.yaml when available."""
 
     # Paths
-    data_dir: Path = field(default_factory=lambda: _resolve_path(
-        _get("paths", "data_dir", None), BASE_DIR / "data"
-    ))
-    chroma_dir: Path = field(default_factory=lambda: _resolve_path(
-        _get("paths", "data_dir", None), BASE_DIR / "data"
-    ) / "chroma_db")
-    documents_dir: Path = field(default_factory=lambda: _resolve_path(
-        _get("paths", "documents_dir", None), BASE_DIR / "documents"
-    ))
+    data_dir: Path = field(default_factory=lambda: _resolve_path(_get("paths", "data_dir", None), BASE_DIR / "data"))
+    chroma_dir: Path = field(
+        default_factory=lambda: _resolve_path(_get("paths", "data_dir", None), BASE_DIR / "data") / "chroma_db"
+    )
+    documents_dir: Path = field(
+        default_factory=lambda: _resolve_path(_get("paths", "documents_dir", None), BASE_DIR / "documents")
+    )
 
     # Chunking
-    chunk_size: int = field(default_factory=lambda: _get("documents", "chunking", {}).get("chunk_size", 1000) if isinstance(_get("documents", "chunking", {}), dict) else 1000)
-    chunk_overlap: int = field(default_factory=lambda: _get("documents", "chunking", {}).get("chunk_overlap", 200) if isinstance(_get("documents", "chunking", {}), dict) else 200)
+    chunk_size: int = field(
+        default_factory=lambda: (
+            _get("documents", "chunking", {}).get("chunk_size", 1000)
+            if isinstance(_get("documents", "chunking", {}), dict)
+            else 1000
+        )
+    )
+    chunk_overlap: int = field(
+        default_factory=lambda: (
+            _get("documents", "chunking", {}).get("chunk_overlap", 200)
+            if isinstance(_get("documents", "chunking", {}), dict)
+            else 200
+        )
+    )
 
     # Embeddings
-    embedding_model: str = field(default_factory=lambda: _get("models", "embedding", {}).get("model", "BAAI/bge-small-en-v1.5") if isinstance(_get("models", "embedding", {}), dict) else "BAAI/bge-small-en-v1.5")
-    embedding_dim: int = field(default_factory=lambda: _get("models", "embedding", {}).get("dimensions", 384) if isinstance(_get("models", "embedding", {}), dict) else 384)
+    embedding_model: str = field(
+        default_factory=lambda: (
+            _get("models", "embedding", {}).get("model", "BAAI/bge-small-en-v1.5")
+            if isinstance(_get("models", "embedding", {}), dict)
+            else "BAAI/bge-small-en-v1.5"
+        )
+    )
+    embedding_dim: int = field(
+        default_factory=lambda: (
+            _get("models", "embedding", {}).get("dimensions", 384)
+            if isinstance(_get("models", "embedding", {}), dict)
+            else 384
+        )
+    )
 
     # Reranker
-    reranker_model: str = field(default_factory=lambda: _get("models", "reranker", {}).get("model", "Xenova/ms-marco-MiniLM-L-6-v2") if isinstance(_get("models", "reranker", {}), dict) else "Xenova/ms-marco-MiniLM-L-6-v2")
-    reranker_enabled: bool = field(default_factory=lambda: _get("models", "reranker", {}).get("enabled", True) if isinstance(_get("models", "reranker", {}), dict) else True)
-    reranker_top_k_multiplier: int = field(default_factory=lambda: _get("models", "reranker", {}).get("top_k_multiplier", 3) if isinstance(_get("models", "reranker", {}), dict) else 3)
+    reranker_model: str = field(
+        default_factory=lambda: (
+            _get("models", "reranker", {}).get("model", "Xenova/ms-marco-MiniLM-L-6-v2")
+            if isinstance(_get("models", "reranker", {}), dict)
+            else "Xenova/ms-marco-MiniLM-L-6-v2"
+        )
+    )
+    reranker_enabled: bool = field(
+        default_factory=lambda: (
+            _get("models", "reranker", {}).get("enabled", True)
+            if isinstance(_get("models", "reranker", {}), dict)
+            else True
+        )
+    )
+    reranker_top_k_multiplier: int = field(
+        default_factory=lambda: (
+            _get("models", "reranker", {}).get("top_k_multiplier", 3)
+            if isinstance(_get("models", "reranker", {}), dict)
+            else 3
+        )
+    )
 
     # ChromaDB
     collection_name: str = field(default_factory=lambda: _get("search", "collection_name", "knowledge_base"))
 
     # Supported formats
-    supported_formats: List[str] = field(default_factory=lambda: _get("documents", "supported_formats", [".md", ".txt", ".pdf", ".py", ".json", ".docx", ".xlsx", ".pptx", ".csv"]))
+    supported_formats: List[str] = field(
+        default_factory=lambda: _get(
+            "documents", "supported_formats", [".md", ".txt", ".pdf", ".py", ".json", ".docx", ".xlsx", ".pptx", ".csv"]
+        )
+    )
 
     # Category mappings
-    category_mappings: Dict[str, str] = field(default_factory=lambda: _yaml.get("category_mappings", _DEFAULT_CATEGORY_MAPPINGS))
+    category_mappings: Dict[str, str] = field(
+        default_factory=lambda: _get_top("category_mappings", _DEFAULT_CATEGORY_MAPPINGS)
+    )
 
     # Keyword routes
-    keyword_routes: Dict[str, List[str]] = field(default_factory=lambda: _yaml.get("keyword_routes", _DEFAULT_KEYWORD_ROUTES))
+    keyword_routes: Dict[str, List[str]] = field(
+        default_factory=lambda: _get_top("keyword_routes", _DEFAULT_KEYWORD_ROUTES)
+    )
 
     # Query expansions
-    query_expansions: Dict[str, List[str]] = field(default_factory=lambda: _yaml.get("query_expansions", _DEFAULT_QUERY_EXPANSIONS))
+    query_expansions: Dict[str, List[str]] = field(
+        default_factory=lambda: _get_top("query_expansions", _DEFAULT_QUERY_EXPANSIONS)
+    )
 
     # Search settings
     default_results: int = field(default_factory=lambda: _get("search", "default_results", 5))

{knowledge_rag-3.3.0 → knowledge_rag-3.3.1}/mcp_server/server.py

@@ -21,8 +21,6 @@ Features:
 Autor:   Lyon (Ailton Rocha)
 Versao:  3.0.0
 Data:    2026-03-19
-
-By Lyon :) Legal Ne?
 """
 
 import hashlib
@@ -1827,8 +1825,53 @@ def evaluate_retrieval(test_cases: str) -> str:
 # =============================================================================
 
 
+def _handle_init():
+    """Export config template and presets to current directory."""
+    import shutil
+
+    data_dir = Path(__file__).parent / "data"
+    if not data_dir.exists():
+        print("[ERROR] Bundled data not found. If installed from git, use presets/ directly.")
+        return
+
+    cwd = Path.cwd()
+
+    # Copy config.example.yaml
+    src = data_dir / "config.example.yaml"
+    if src.exists():
+        dst = cwd / "config.example.yaml"
+        shutil.copy2(src, dst)
+        print(f"[OK] {dst}")
+
+    # Copy presets
+    presets_dir = cwd / "presets"
+    presets_dir.mkdir(exist_ok=True)
+    for f in data_dir.glob("*.yaml"):
+        if f.name == "config.example.yaml":
+            continue
+        dst = presets_dir / f.name
+        shutil.copy2(f, dst)
+        print(f"[OK] {dst}")
+
+    # Create documents dir
+    docs_dir = cwd / "documents"
+    docs_dir.mkdir(exist_ok=True)
+    print(f"[OK] {docs_dir}/")
+
+    print("\nDone. Quick start:")
+    print("  cp presets/general.yaml config.yaml     # or cybersecurity, developer, research")
+    print("  # Add your documents to documents/")
+    print("  # Restart Claude Code")
+
+
 def main():
     """Run the MCP server"""
+    import sys
+
+    if len(sys.argv) > 1 and sys.argv[1] == "init":
+        _handle_init()
+        return
+
     orchestrator = get_orchestrator()
 
     # Migration: check dimension mismatch AFTER full init (avoids segfault during __init__)

{knowledge_rag-3.3.0 → knowledge_rag-3.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "knowledge-rag"
-version = "3.3.0"
+version = "3.3.1"
 description = "Local RAG System for Claude Code — Hybrid search + Cross-encoder Reranking + 12 MCP Tools. Zero external servers."
 readme = "README.md"
 license = {text = "MIT"}
@@ -55,6 +55,13 @@ knowledge-rag = "mcp_server.server:main"
 [tool.hatch.build.targets.wheel]
 packages = ["mcp_server"]
 
+[tool.hatch.build.targets.wheel.force-include]
+"config.example.yaml" = "mcp_server/data/config.example.yaml"
+"presets/cybersecurity.yaml" = "mcp_server/data/cybersecurity.yaml"
+"presets/developer.yaml" = "mcp_server/data/developer.yaml"
+"presets/research.yaml" = "mcp_server/data/research.yaml"
+"presets/general.yaml" = "mcp_server/data/general.yaml"
+
 [tool.hatch.build.targets.sdist]
 include = [
     "mcp_server/",