Dev

examples/python/advanced/main.py

@@ -91,8 +91,9 @@ def main():
     for q in questions:
         result = engine.query(doc_id, q)
         print(f"Q: {q}")
-        print(f"A: {result.content[:150]}...")
-        print(f"   Score: {result.score:.2f}\n")
+        if item := result.single():
+            print(f"A: {item.content[:150]}...")
+            print(f"   Score: {item.score:.2f}\n")
 
     # Cleanup
     engine.remove(doc_id)

examples/python/basic/main.py

@@ -59,8 +59,9 @@ def main():
         # Query
         result = engine.query(doc_id, "How do I install vectorless?")
         print("Query: How do I install vectorless?")
-        print(f"Score: {result.score:.2f}")
-        print(f"Result: {result.content[:200]}...\n")
+        if item := result.single():
+            print(f"Score: {item.score:.2f}")
+            print(f"Result: {item.content[:200]}...\n")
 
         # Cleanup
         engine.remove(doc_id)

examples/python/custom_config/main.py

@@ -94,14 +94,16 @@ def main():
     # Query
     result = engine.query(doc_id, "How do I install the product?")
     print("Query: How do I install the product?")
-    print(f"Score: {result.score:.2f}")
-    print(f"Result: {result.content}\n")
+    if item := result.single():
+        print(f"Score: {item.score:.2f}")
+        print(f"Result: {item.content}\n")
 
     # Another query
     result = engine.query(doc_id, "What features are available?")
     print("Query: What features are available?")
-    print(f"Score: {result.score:.2f}")
-    print(f"Result: {result.content}\n")
+    if item := result.single():
+        print(f"Score: {item.score:.2f}")
+        print(f"Result: {item.content}\n")
 
     # Cleanup
     engine.remove(doc_id)

examples/rust/advanced.rs

@@ -42,10 +42,12 @@ async fn main() -> vectorless::Result<()> {
         .query(QueryContext::new("What features does Vectorless provide?").with_doc_id(&doc_id))
         .await?;
     println!("Query: What features does Vectorless provide?");
-    println!("Score: {:.2}", result.score);
-    if !result.content.is_empty() {
-        let preview: String = result.content.chars().take(200).collect();
-        println!("Result: {}...\n", preview);
+    if let Some(item) = result.single() {
+        println!("Score: {:.2}", item.score);
+        if !item.content.is_empty() {
+            let preview: String = item.content.chars().take(200).collect();
+            println!("Result: {}...\n", preview);
+        }
     }
 
     // Cleanup

examples/rust/basic.rs

@@ -42,10 +42,12 @@ async fn main() -> vectorless::Result<()> {
         .await
     {
         Ok(result) => {
-            println!("Score: {:.2}", result.score);
-            if !result.content.is_empty() {
-                let preview: String = result.content.chars().take(150).collect();
-                println!("Result: {}...", preview);
+            if let Some(item) = result.single() {
+                println!("Score: {:.2}", item.score);
+                if !item.content.is_empty() {
+                    let preview: String = item.content.chars().take(150).collect();
+                    println!("Result: {}...", preview);
+                }
             }
         }
         Err(e) => println!("Query: {}", e),

examples/rust/custom_config.rs

@@ -53,10 +53,12 @@ async fn main() -> vectorless::Result<()> {
         .query(QueryContext::new("What is Vectorless?").with_doc_id(&doc_id))
         .await?;
     println!("Query: What is Vectorless?");
-    println!("Score: {:.2}", result.score);
-    if !result.content.is_empty() {
-        let preview: String = result.content.chars().take(200).collect();
-        println!("Result: {}...\n", preview);
+    if let Some(item) = result.single() {
+        println!("Score: {:.2}", item.score);
+        if !item.content.is_empty() {
+            let preview: String = item.content.chars().take(200).collect();
+            println!("Result: {}...\n", preview);
+        }
     }
 
     // Cleanup

examples/rust/events.rs

@@ -138,11 +138,13 @@ The event system uses handlers that can be attached to the engine builder.
 
     // 5. Show results
     println!("Step 5: Query result:");
-    println!("  - Score: {:.2}", result.score);
-    println!("  - Nodes: {}", result.node_ids.len());
-    if !result.content.is_empty() {
-        let preview: String = result.content.chars().take(100).collect();
-        println!("  - Content: {}...", preview);
+    if let Some(item) = result.single() {
+        println!("  - Score: {:.2}", item.score);
+        println!("  - Nodes: {}", item.node_ids.len());
+        if !item.content.is_empty() {
+            let preview: String = item.content.chars().take(100).collect();
+            println!("  - Content: {}...", preview);
+        }
     }
     println!();
 

examples/rust/graph.rs

@@ -0,0 +1,88 @@
+// Copyright (c) 2026 vectorless developers
+// SPDX-License-Identifier: Apache-2.0
+
+//! Document graph example for Vectorless.
+//!
+//! Demonstrates how to retrieve the cross-document relationship graph
+//! after indexing. The graph is automatically rebuilt after each index call,
+//! connecting documents that share keywords via Jaccard similarity.
+//!
+//! # Usage
+//!
+//! ```bash
+//! cargo run --example graph
+//! ```
+
+use vectorless::{EngineBuilder, IndexContext};
+
+#[tokio::main]
+async fn main() -> vectorless::Result<()> {
+    println!("=== Document Graph Example ===\n");
+
+    // 1. Create engine
+    let engine = EngineBuilder::new()
+        .with_workspace("./workspace_graph_example")
+        .build()
+        .await
+        .map_err(|e: vectorless::BuildError| vectorless::Error::Config(e.to_string()))?;
+
+    // 2. Index documents — graph is rebuilt automatically
+    let result = engine
+        .index(IndexContext::from_paths(&["./README.md", "./CLAUDE.md"]))
+        .await?;
+
+    println!("Indexed {} document(s)", result.items.len());
+    for item in &result.items {
+        println!("  - {} ({})", item.name, item.doc_id);
+    }
+    println!();
+
+    // 3. Get the document graph
+    match engine.get_graph().await? {
+        Some(graph) => {
+            println!(
+                "Document graph: {} nodes, {} edges",
+                graph.node_count(),
+                graph.edge_count()
+            );
+
+            // Show document nodes
+            for doc_id in graph.doc_ids() {
+                if let Some(node) = graph.get_node(doc_id) {
+                    println!(
+                        "  Node: {} — {} keyword(s), top: {:?}",
+                        node.title,
+                        node.top_keywords.len(),
+                        node.top_keywords.iter().take(3).map(|kw| &kw.keyword).collect::<Vec<_>>()
+                    );
+
+                    // Show edges (connected documents)
+                    let neighbors = graph.get_neighbors(doc_id);
+                    if !neighbors.is_empty() {
+                        for edge in neighbors {
+                            println!(
+                                "    → {} (weight={:.2}, jaccard={:.2}, shared={})",
+                                edge.target_doc_id,
+                                edge.weight,
+                                edge.evidence.keyword_jaccard,
+                                edge.evidence.shared_keyword_count,
+                            );
+                        }
+                    } else {
+                        println!("    (no connections)");
+                    }
+                }
+            }
+        }
+        None => println!("No graph available (no documents with reasoning index)"),
+    }
+
+    // 4. Cleanup
+    let docs = engine.list().await?;
+    for doc in &docs {
+        engine.remove(&doc.id).await?;
+    }
+
+    println!("\n=== Done ===");
+    Ok(())
+}

examples/rust/markdownflow.rs

@@ -88,19 +88,22 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
 
         match client.query(QueryContext::new(query).with_doc_id(&doc_id)).await {
             Ok(result) => {
-                if result.content.is_empty() {
-                    println!("    - No relevant content found");
-                } else {
-                    println!("    - Found relevant content:");
-                    // Print first 200 chars
-                    let preview = if result.content.len() > 200 {
-                        format!("{}...", &result.content[..200])
+                if let Some(item) = result.single() {
+                    if item.content.is_empty() {
+                        println!("    - No relevant content found");
                     } else {
-                        result.content.clone()
-                    };
-                    for line in preview.lines().take(5) {
-                        println!("      {}", line);
+                        println!("    - Found relevant content:");
+                        let preview = if item.content.len() > 200 {
+                            format!("{}...", &item.content[..200])
+                        } else {
+                            item.content.clone()
+                        };
+                        for line in preview.lines().take(5) {
+                            println!("      {}", line);
+                        }
                     }
+                } else {
+                    println!("    - No results");
                 }
             }
             Err(e) => {