feat: implement document graph functionality for cross-document relationships

- Add DocumentGraph and related types (DocumentGraphNode, GraphEdge, etc.)
- Create graph module with builder, config, and type definitions
- Move graph builder from src/index to src/graph module
- Implement automatic graph rebuilding after document indexing
- Add graph-aware retrieval with boost factor support
- Integrate document graph into query pipeline context
- Add graph configuration options to main Config struct
- Implement keyword extraction from ReasoningIndex for graph building
- Add workspace methods to persist/load document graph
- Update retrieval strategies to utilize graph connections
- Add validation for graph configuration parameters

Author: zTgx

rust/src/client/engine.rs

@@ -35,6 +35,7 @@
 //! # }
 //! ```
 
+use std::collections::HashMap;
 use std::sync::Arc;
 
 use futures::StreamExt;
@@ -45,7 +46,7 @@ use crate::error::Result;
 use crate::index::PipelineOptions;
 use crate::index::incremental::{self, IndexAction};
 use crate::retrieval::{PipelineRetriever, RetrieveEventReceiver};
-use crate::storage::Workspace;
+use crate::storage::{PersistedDocument, Workspace};
 use crate::utils::fingerprint::Fingerprint;
 use crate::{DocumentTree, Error};
 
@@ -166,6 +167,11 @@ impl Engine {
                     failed.len()
                 )));
             }
+            if !items.is_empty() {
+                if let Err(e) = self.rebuild_graph().await {
+                    tracing::warn!("Graph rebuild failed: {}", e);
+                }
+            }
             return Ok(IndexResult::with_partial(items, failed));
         }
 
@@ -200,6 +206,13 @@ impl Engine {
             )));
         }
 
+        // Rebuild document graph after successful batch index
+        if !items.is_empty() {
+            if let Err(e) = self.rebuild_graph().await {
+                tracing::warn!("Graph rebuild failed: {}", e);
+            }
+        }
+
         Ok(IndexResult::with_partial(items, failed))
     }
 
@@ -345,7 +358,16 @@ impl Engine {
     /// ```
     pub async fn query(&self, ctx: QueryContext) -> Result<QueryResult> {
         let doc_ids = self.resolve_scope(&ctx.scope).await?;
-        let options = ctx.to_retrieve_options(&self.config);
+        let mut options = ctx.to_retrieve_options(&self.config);
+
+        // Load document graph for graph-aware retrieval (if enabled)
+        if self.config.graph.enabled {
+            if let Some(ref workspace) = self.workspace {
+                if let Ok(Some(graph)) = workspace.get_graph().await {
+                    options = options.with_document_graph(Arc::new(graph));
+                }
+            }
+        }
 
         let mut items = Vec::with_capacity(doc_ids.len());
         let mut failed = Vec::new();
@@ -508,6 +530,51 @@ impl Engine {
         }
     }
 
+    /// Rebuild the document graph after indexing, if graph is enabled.
+    async fn rebuild_graph(&self) -> Result<()> {
+        if !self.config.graph.enabled {
+            return Ok(());
+        }
+        let workspace = match self.workspace {
+            Some(ref ws) => ws,
+            None => return Ok(()),
+        };
+
+        // Load all documents and extract keyword profiles
+        let doc_ids = workspace.inner().list_documents().await;
+        let mut builder = crate::graph::DocumentGraphBuilder::new(self.config.graph.clone());
+
+        for doc_id in &doc_ids {
+            if let Some(doc) = workspace.load(doc_id).await? {
+                let keywords = Self::extract_keywords_from_doc(&doc);
+                builder.add_document(
+                    &doc.meta.id,
+                    &doc.meta.name,
+                    &doc.meta.format,
+                    doc.meta.node_count,
+                    keywords,
+                );
+            }
+        }
+
+        let graph = builder.build();
+        workspace.set_graph(&graph).await?;
+        Ok(())
+    }
+
+    /// Extract keyword → weight map from a persisted document's ReasoningIndex.
+    fn extract_keywords_from_doc(doc: &PersistedDocument) -> HashMap<String, f32> {
+        let mut keywords = HashMap::new();
+        if let Some(ref ri) = doc.reasoning_index {
+            for (kw, entries) in ri.all_topic_entries() {
+                let weight: f32 =
+                    entries.iter().map(|e| e.weight).sum::<f32>() / entries.len().max(1) as f32;
+                keywords.insert(kw.clone(), weight);
+            }
+        }
+        keywords
+    }
+
     /// Resolve what action to take for a source.
     async fn resolve_index_action(
         &self,

rust/src/client/workspace.rs

@@ -299,6 +299,16 @@ impl WorkspaceClient {
     pub async fn find_by_source_path(&self, path: &std::path::Path) -> Option<String> {
         self.workspace.find_by_source_path(path).await
     }
+
+    /// Get the document graph, loading from backend if not cached.
+    pub async fn get_graph(&self) -> Result<Option<crate::graph::DocumentGraph>> {
+        self.workspace.get_graph().await
+    }
+
+    /// Persist the document graph to the backend.
+    pub async fn set_graph(&self, graph: &crate::graph::DocumentGraph) -> Result<()> {
+        self.workspace.set_graph(graph).await
+    }
 }
 
 /// Workspace statistics.

rust/src/config/types/mod.rs

@@ -68,6 +68,10 @@ pub struct Config {
     #[serde(default)]
     pub concurrency: ConcurrencyConfig,
 
+    /// Document graph configuration.
+    #[serde(default)]
+    pub graph: crate::graph::DocumentGraphConfig,
+
     /// Fallback/error recovery configuration (legacy, prefer llm.fallback).
     #[serde(default)]
     pub fallback: FallbackConfig,
@@ -83,6 +87,7 @@ impl Default for Config {
             retrieval: RetrievalConfig::default(),
             storage: StorageConfig::default(),
             concurrency: ConcurrencyConfig::default(),
+            graph: crate::graph::DocumentGraphConfig::default(),
             fallback: FallbackConfig::default(),
         }
     }
@@ -136,6 +141,12 @@ impl Config {
         self
     }
 
+    /// Set the document graph configuration.
+    pub fn with_graph(mut self, graph: crate::graph::DocumentGraphConfig) -> Self {
+        self.graph = graph;
+        self
+    }
+
     /// Set the fallback configuration.
     pub fn with_fallback(mut self, fallback: FallbackConfig) -> Self {
         self.fallback = fallback;
@@ -209,6 +220,20 @@ impl Config {
             ));
         }
 
+        // Validate graph
+        if self.graph.min_keyword_jaccard < 0.0 || self.graph.min_keyword_jaccard > 1.0 {
+            errors.push(ValidationError::error(
+                "graph.min_keyword_jaccard",
+                "Must be between 0.0 and 1.0",
+            ));
+        }
+        if self.graph.max_edges_per_node == 0 {
+            errors.push(ValidationError::error(
+                "graph.max_edges_per_node",
+                "Must be greater than 0",
+            ));
+        }
+
         // Validate fallback
         if self.fallback.enabled && self.fallback.models.is_empty() {
             errors.push(ValidationError::warning(