Knowledge Rag

Hybrid search combining semantic search + BM25 keyword search with cross-encoder reranking. Read-only. No side effects. Args: query: Search query text (1–3 keywords recommended; phrase queries also work) max_results: Maximum number of results (default: 5, max: 20) category: Optional category filter — one of: security, ctf, logscale, development, general, redteam, blueteam. Call list_categories() first to see available categories and counts. hybrid_alpha: Balance between semantic and keyword search. 0.0 = keyword-only (best for exact technical terms like CVE IDs or tool names), 0.3 = balanced default, 1.0 = semantic-only (best for conceptual or natural-language queries). min_score: Minimum normalized relevance score (0.0–1.0) to include a result. Results scoring below this threshold are discarded. Default 0.0 returns all results. Use 0.2–0.4 to cut low-relevance noise. snippet_mode: When true (default), truncates content to ~500 characters at a natural break point and adds a content_length field with the original size. Use get_document() to fetch full content when needed. Set to false to return full chunk content. search_method: Dispatch selector (v4.8.2+). One of ``"auto"`` (router picks FTS5 fast-path for lexical queries when enabled, hybrid otherwise), ``"hybrid"`` (force hybrid path — kill switch for suspected router misclassification), or ``"fts5"`` (force FTS5 fast-path — debug/testing; errors out when the feature is disabled or the index is not ready). Default ``"auto"`` preserves pre-v4.8.2 behavior byte-for-byte when the fast-path is disabled in config. Returns: JSON string with results including content chunks, source filepath, relevance score, and search method used. Returns chunks, not full document content. Usage: Primary search tool — use for any topic or keyword lookup. Prefer search_similar() when you already have a reference document and want more like it. Prefer get_document() when you already know the exact filepath and need the full content.

Get the full content of a specific document by filepath. Read-only. No side effects. Args: filepath: Relative path to the document within the documents directory (e.g., "security/technique.md"). Must be an indexed file — use list_documents() to browse available paths, or search_knowledge() to find the filepath by topic first. Returns: JSON string with full document content and metadata (filepath, category, size). Usage: Use when you need the complete text of a known file — search_knowledge() returns chunks, not full docs. Use search_knowledge() first to find the filepath if unknown. Use list_documents() to browse all available files by category.

Index or reindex all documents in the knowledge base (runs in background). ``force`` — smart reindex (detect changed files + rebuild BM25). Use after filesystem edits outside add_document/update_document. ``full_rebuild`` — nuclear rebuild (delete + re-embed). Use only after embedding-model change or index corruption. Mutually exclusive with resume. ``resume`` — pick up an interrupted smart reindex from ``data/reindex_checkpoint.json``. Falls back to a fresh smart run silently if the checkpoint is missing/corrupt/drifted (v4.8.0 Fase 4). Returns a JSON envelope. Poll ``get_reindex_status()`` until ``reindex.active`` becomes false. Add/update/URL tools already auto-index — use these flags only for the recovery/rebuild scenarios above.

Get the current status of a background reindex operation. Lightweight — does not compute full index statistics. Use this to poll progress after calling reindex_documents(). Returns: JSON string with reindex status. When active: operation name, progress (processed/total), percent complete, indexed/skipped/errors counts, and start time. When inactive: active=false, plus last_result or last_error from the most recent completed reindex. Usage: Call repeatedly after reindex_documents() to monitor progress. When reindex.active becomes false, the operation is complete. Use get_index_stats() for full index health metrics.

List all document categories with their document counts. Read-only. No side effects. Reflects the live index state. Returns: JSON string with category names, document counts per category, and total document count. Usage: Use before filtering search_knowledge() or list_documents() by category to see which categories exist and how many documents each contains. Use get_index_stats() instead for broader system health metrics (model name, cache hit rate, BM25 status).

List all indexed documents, optionally filtered by category. Read-only. No side effects. Args: category: Optional category filter. Must be a valid category name — call list_categories() to see available options (e.g., security, ctf, logscale, development, general, redteam, blueteam). Returns: JSON string with list of document filepaths, categories, and metadata for each indexed file. Usage: Use to browse what's in the index or verify a specific file is indexed. Use list_categories() first to see valid category names. Use search_knowledge() when you want to find documents by topic rather than browsing the full list. Use get_document() to read a specific file once you have its filepath.