brainwires-knowledge 0.9.0

Knowledge layer — knowledge graphs, adaptive prompting, RAG, spectral math, and code analysis for the Brainwires Agent Framework
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124

//! Core library client for brainwires-rag
//!
//! This module provides the main client interface for using brainwires-rag
//! as a library in your own Rust applications.
//!
//! # Structure
//!
//! The implementation is split across focused submodules:
//!
//! - [`constructor`] — constructors, basic utilities, path helpers
//! - [`locking`] — two-layer index locking (filesystem + in-process broadcast)
//! - [`search`] — indexing dispatch, semantic search, filtered search, statistics, clear, git history
//! - [`ensemble`] — multi-strategy ensemble query with Reciprocal Rank Fusion
//! - [`reranking`] — pluggable diversity/relevance reranking (`spectral-select` feature)
//! - `code_analysis` — find definition, find references, call graph (`code-analysis` feature)

#[cfg(feature = "code-analysis")]
use crate::code_analysis::HybridRelationsProvider;
use crate::rag::cache::HashCache;
use crate::rag::config::Config;
use crate::rag::embedding::FastEmbedManager;
use crate::rag::git_cache::GitCache;
use crate::rag::indexer::CodeChunker;
use brainwires_storage::databases::VectorDatabase;

use std::collections::HashMap;
use std::path::PathBuf;
use std::sync::Arc;
use tokio::sync::RwLock;

// Filesystem locking for cross-process coordination
mod fs_lock;
pub(crate) use fs_lock::FsLockGuard;

// Index locking mechanism (uses fs_lock for cross-process, broadcast for in-process)
mod index_lock;
pub(crate) use index_lock::{IndexLockGuard, IndexLockResult, IndexingOperation};

// ── impl blocks, split by concern ────────────────────────────────────────────

/// Constructor methods and utility helpers.
mod constructor;

/// Two-layer index locking.
mod locking;

/// Indexing dispatch, search, statistics, clear, and git-history search.
mod search;

/// Multi-strategy ensemble query with RRF fusion.
mod ensemble;

/// Pluggable diversity/relevance reranking (requires `spectral-select`).
mod reranking;

/// Code-navigation: find definition, find references, call graph (requires `code-analysis`).
#[cfg(feature = "code-analysis")]
mod code_analysis;

// ── existing public submodules ────────────────────────────────────────────────

/// Indexing operations (public for MCP server binary).
pub mod indexing;

// Git indexing operations module
pub(crate) mod git_indexing;

#[cfg(test)]
mod tests;

// ── Re-exports (keeps all existing call sites working) ────────────────────────

// All public types from `types` are already glob-imported above via `use crate::rag::types::*`.
// The public API surface of RagClient itself is fully re-exported through the struct below.

/// Main client for interacting with the RAG system
///
/// This client provides a high-level API for indexing codebases and performing
/// semantic searches. It contains all the core functionality and can be used
/// directly as a library or wrapped by the MCP server.
///
/// # Example
///
/// ```ignore
/// use crate::rag::{RagClient, IndexRequest, QueryRequest};
///
/// #[tokio::main]
/// async fn main() -> anyhow::Result<()> {
///     // Create client with default configuration
///     let client = RagClient::new().await?;
///
///     // Index a codebase
///     let index_req = IndexRequest {
///         path: "/path/to/code".to_string(),
///         project: Some("my-project".to_string()),
///         include_patterns: vec!["**/*.rs".to_string()],
///         exclude_patterns: vec!["**/target/**".to_string()],
///         max_file_size: 1_048_576,
///     };
///     let response = client.index_codebase(index_req).await?;
///     println!("Indexed {} files", response.files_indexed);
///
///     Ok(())
/// }
/// ```
#[derive(Clone)]
pub struct RagClient {
    pub(crate) embedding_provider: Arc<FastEmbedManager>,
    pub(crate) vector_db: Arc<dyn VectorDatabase>,
    pub(crate) chunker: Arc<CodeChunker>,
    // Persistent hash cache for incremental updates
    pub(crate) hash_cache: Arc<RwLock<HashCache>>,
    pub(crate) cache_path: PathBuf,
    // Git cache for git history indexing
    pub(crate) git_cache: Arc<RwLock<GitCache>>,
    pub(crate) git_cache_path: PathBuf,
    // Configuration (for accessing batch sizes, timeouts, etc.)
    pub(crate) config: Arc<Config>,
    // In-progress indexing operations (prevents concurrent indexing and allows result sharing)
    pub(crate) indexing_ops: Arc<RwLock<HashMap<String, IndexingOperation>>>,
    // Relations provider for code navigation (find definition, references, call graph)
    #[cfg(feature = "code-analysis")]
    pub(crate) relations_provider: Arc<HybridRelationsProvider>,
}