feat: update API to return IndexResult and add QueryContext

- Change Python Engine.index() to return IndexResult instead of doc_id string
- Add new PyIndexResult and PyIndexItem classes for better indexing feedback
- Update Python examples to handle IndexResult and extract doc_id
- Introduce QueryContext for structured query parameters
- Rename Python list_docs() method to list() for consistency
- Remove deprecated len() method from Python Engine
- Update README and all Rust examples to use new API patterns
- Replace direct doc_id parameter with QueryContext in query methods

Author: zTgx

README.md

@@ -43,7 +43,8 @@ from vectorless import Engine, IndexContext
 engine = Engine(workspace="./data")
 
 # Index a document (PDF, Markdown, DOCX, HTML)
-doc_id = engine.index(IndexContext.from_file("./report.pdf"))
+result = engine.index(IndexContext.from_file("./report.pdf"))
+doc_id = result.doc_id
 
 # Query
 result = engine.query(doc_id, "What is the total revenue?")
@@ -60,7 +61,7 @@ vectorless = "0.1"
 ```
 
 ```rust
-use vectorless::client::{EngineBuilder, IndexContext};
+use vectorless::client::{EngineBuilder, IndexContext, QueryContext};
 
 #[tokio::main]
 async fn main() -> vectorless::Result<()> {
@@ -70,10 +71,13 @@ async fn main() -> vectorless::Result<()> {
         .await?;
 
     // Index
-    let doc_id = engine.index(IndexContext::from_path("./report.pdf")).await?;
+    let result = engine.index(IndexContext::from_path("./report.pdf")).await?;
+    let doc_id = result.doc_id().unwrap();
 
     // Query
-    let result = engine.query(&doc_id, "What is the total revenue?").await?;
+    let result = engine.query(
+        QueryContext::new("What is the total revenue?").with_doc_id(doc_id)
+    ).await?;
     println!("Answer: {}", result.content);
 
     Ok(())

examples/rust/advanced.rs

@@ -16,7 +16,7 @@
 //! cargo run --example advanced
 //! ```
 
-use vectorless::{EngineBuilder, IndexContext};
+use vectorless::{EngineBuilder, IndexContext, QueryContext};
 
 #[tokio::main]
 async fn main() -> vectorless::Result<()> {
@@ -33,11 +33,14 @@ async fn main() -> vectorless::Result<()> {
     println!("✓ Client created with config file\n");
 
     // Index a document
-    let doc_id = client.index(IndexContext::from_path("./README.md")).await?;
+    let result = client.index(IndexContext::from_path("./README.md")).await?;
+    let doc_id = result.doc_id().unwrap().to_string();
     println!("✓ Indexed: {}\n", doc_id);
 
     // Query
-    let result = client.query(&doc_id, "What features does Vectorless provide?").await?;
+    let result = client
+        .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() {

examples/rust/basic.rs

@@ -3,44 +3,46 @@
 
 //! Basic usage example for Vectorless.
 //!
-//! This example demonstrates the core API in ~30 lines.
-//!
 //! # Usage
 //!
 //! ```bash
 //! cargo run --example basic
 //! ```
 
-use vectorless::{EngineBuilder, IndexContext};
+use vectorless::{EngineBuilder, IndexContext, QueryContext};
 
 #[tokio::main]
 async fn main() -> vectorless::Result<()> {
     println!("=== Vectorless Basic Example ===\n");
 
-    // 1. Create a client
-    let client = EngineBuilder::new()
+    // 1. Create an engine
+    let engine = EngineBuilder::new()
         .with_workspace("./workspace")
         .build()
         .await
         .map_err(|e: vectorless::BuildError| vectorless::Error::Config(e.to_string()))?;
 
-    println!("✓ Client created\n");
+    println!("Engine created\n");
 
     // 2. Index a document
-    let doc_id = client.index(IndexContext::from_path("./README.md")).await?;
-    println!("✓ Indexed: {}\n", doc_id);
+    let result = engine.index(IndexContext::from_path("./README.md")).await?;
+    let doc_id = result.doc_id().unwrap().to_string();
+    println!("Indexed: {}\n", doc_id);
 
     // 3. List documents
     println!("Documents:");
-    for doc in client.list_documents().await? {
+    for doc in engine.list().await? {
         println!("  - {} ({})", doc.name, doc.id);
     }
     println!();
 
     // 4. Query
-    match client.query(&doc_id, "What is vectorless?").await {
+    match engine
+        .query(QueryContext::new("What is vectorless?").with_doc_id(&doc_id))
+        .await
+    {
         Ok(result) => {
-            println!("Query score: {:.2}", result.score);
+            println!("Score: {:.2}", result.score);
             if !result.content.is_empty() {
                 let preview: String = result.content.chars().take(150).collect();
                 println!("Result: {}...", preview);
@@ -50,14 +52,9 @@ async fn main() -> vectorless::Result<()> {
     }
     println!();
 
-    // 5. Clone for concurrent use (client is Clone + Send + Sync)
-    let _client1 = client.clone();
-    let _client2 = client.clone();
-    println!("✓ Client cloned for concurrent use\n");
-
-    // 6. Cleanup
-    client.remove(&doc_id).await?;
-    println!("✓ Removed: {}", doc_id);
+    // 5. Cleanup
+    engine.remove(&doc_id).await?;
+    println!("Removed: {}", doc_id);
 
     println!("\n=== Done ===");
     Ok(())

examples/rust/batch_processing.rs

@@ -4,30 +4,29 @@
 //! Batch document processing example.
 //!
 //! This example demonstrates how to efficiently process
-//! multiple documents in batch mode using sessions.
+//! multiple documents in batch mode.
 //!
 //! # Usage
 //!
 //! ```bash
 //! cargo run --example batch_processing
 //! ```
 
-use vectorless::client::{EngineBuilder, IndexContext};
+use vectorless::client::{EngineBuilder, IndexContext, QueryContext};
 
 #[tokio::main]
 async fn main() -> Result<(), Box<dyn std::error::Error>> {
     println!("=== Batch Document Processing Example ===\n");
 
-    // 1. Create engine and session
+    // 1. Create engine
     println!("Step 1: Setting up...");
     let engine = EngineBuilder::new()
         .with_workspace("./workspace_batch_example")
         .build()
         .await
         .map_err(|e: vectorless::BuildError| vectorless::Error::Config(e.to_string()))?;
 
-    let session = engine.session().await;
-    println!("  ✓ Session created: {}\n", session.id());
+    println!("  ✓ Engine created\n");
 
     // 2. Create sample documents
     println!("Step 2: Creating sample documents...");
@@ -1059,8 +1058,9 @@ Implement authentication for production.
 
     for (name, _) in &documents {
         let path = temp_dir.path().join(name);
-        match session.index(IndexContext::from_path(&path)).await {
-            Ok(doc_id) => {
+        match engine.index(IndexContext::from_path(&path)).await {
+            Ok(result) => {
+                let doc_id = result.doc_id().unwrap().to_string();
                 doc_ids.push(doc_id);
             }
             Err(e) => {
@@ -1077,14 +1077,13 @@ Implement authentication for production.
     );
     println!();
 
-    // 4. Show session stats
-    println!("Step 4: Session statistics:");
-    let stats = session.stats();
+    // 4. Show indexed documents
+    println!("Step 4: Indexed documents:");
+    let docs = engine.list().await?;
     println!(
-        "  - Documents in session: {}",
-        session.list_documents().len()
+        "  - Documents indexed: {}",
+        docs.len()
     );
-    println!("  - Queries: {}", stats.query_count.get());
     println!();
 
     // 5. Batch query with progress
@@ -1106,16 +1105,22 @@ Implement authentication for production.
     let mut success_count = 0;
 
     for query in &queries {
-        match session.query_all(query).await {
-            Ok(results) => {
-                if !results.is_empty() {
-                    success_count += 1;
+        // Query against each indexed document, count as success if any returns content
+        let mut found = false;
+        for doc_id in &doc_ids {
+            match engine.query(QueryContext::new(*query).with_doc_id(doc_id)).await {
+                Ok(result) => {
+                    if !result.content.is_empty() {
+                        found = true;
+                        break;
+                    }
                 }
-            }
-            Err(e) => {
-                eprintln!("  ✗ Query failed: {}", e);
+                Err(_) => {}
             }
         }
+        if found {
+            success_count += 1;
+        }
     }
 
     let elapsed = start.elapsed();
@@ -1132,16 +1137,8 @@ Implement authentication for production.
 
     // 6. Final statistics
     println!("Step 6: Final statistics:");
-    let stats = session.stats();
-    println!("  - Total documents: {}", session.list_documents().len());
-    println!("  - Total queries: {}", stats.query_count.get());
-    println!("  - Cache hits: {}", stats.cache_hits.get());
-    println!("  - Cache misses: {}", stats.cache_misses.get());
-    println!("  - Cache hit rate: {:.1}%", stats.cache_hit_rate() * 100.0);
-    if let Some(avg_time) = stats.avg_query_time() {
-        println!("  - Avg query time: {:?}", avg_time);
-    }
-    println!("  - Session age: {:?}", session.age());
+    let docs = engine.list().await?;
+    println!("  - Total documents: {}", docs.len());
     println!();
 
     // 7. Cleanup

examples/rust/custom_config.rs

@@ -12,7 +12,7 @@
 //! cargo run --example custom_config
 //! ```
 
-use vectorless::{EngineBuilder, IndexContext};
+use vectorless::{EngineBuilder, IndexContext, QueryContext};
 
 #[tokio::main]
 async fn main() -> vectorless::Result<()> {
@@ -43,11 +43,14 @@ async fn main() -> vectorless::Result<()> {
     println!("✓ Client created with custom settings\n");
 
     // Index a document
-    let doc_id = client.index(IndexContext::from_path("./README.md")).await?;
+    let index_result = client.index(IndexContext::from_path("./README.md")).await?;
+    let doc_id = index_result.doc_id().unwrap().to_string();
     println!("✓ Indexed: {}\n", doc_id);
 
     // Query
-    let result = client.query(&doc_id, "What is Vectorless?").await?;
+    let result = client
+        .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() {

examples/rust/events.rs

@@ -17,7 +17,7 @@
 use std::sync::Arc;
 use std::sync::atomic::{AtomicUsize, Ordering};
 
-use vectorless::client::{EngineBuilder, EventEmitter, IndexContext, IndexEvent, QueryEvent};
+use vectorless::client::{EngineBuilder, EventEmitter, IndexContext, IndexEvent, QueryContext, QueryEvent};
 
 #[tokio::main]
 async fn main() -> Result<(), Box<dyn std::error::Error>> {
@@ -123,14 +123,15 @@ The event system uses handlers that can be attached to the engine builder.
     let doc_path = temp_dir.path().join("example.md");
     tokio::fs::write(&doc_path, doc_content).await?;
 
-    let doc_id = engine.index(IndexContext::from_path(&doc_path)).await?;
+    let index_result = engine.index(IndexContext::from_path(&doc_path)).await?;
+    let doc_id = index_result.doc_id().unwrap().to_string();
     println!();
 
     // 4. Query the document (events will fire)
     println!("Step 4: Querying document (watch events)...\n");
 
     let result = engine
-        .query(&doc_id, "What features are available?")
+        .query(QueryContext::new("What features are available?").with_doc_id(&doc_id))
         .await?;
     println!();
 

examples/rust/html_parser.rs

@@ -244,7 +244,7 @@ fn demo_engine_integration() {
     println!("Integration with Engine:\n");
 
     println!("```rust");
-    println!("use vectorless::{{EngineBuilder, IndexContext}};");
+    println!("use vectorless::{{EngineBuilder, IndexContext, QueryContext}};");
     println!("use vectorless::parser::DocumentFormat;");
     println!();
     println!("# #[tokio::main]");
@@ -255,9 +255,10 @@ fn demo_engine_integration() {
     println!("        .await?;");
     println!();
     println!("    // Method 1: From HTML file");
-    println!("    let doc_id = engine.index(");
+    println!("    let result = engine.index(");
     println!("        IndexContext::from_path(\"./documentation.html\")");
     println!("    ).await?;");
+    println!("    let doc_id = result.doc_id().unwrap().to_string();");
     println!();
     println!("    // Method 2: From HTML content");
     println!("    let html = r#\"");
@@ -270,13 +271,16 @@ fn demo_engine_integration() {
     println!("</html>");
     println!("\"#;");
     println!();
-    println!("    let doc_id = engine.index(");
+    println!("    let result = engine.index(");
     println!("        IndexContext::from_content(html, DocumentFormat::Html)");
     println!("            .with_name(\"my-document\")");
     println!("    ).await?;");
+    println!("    let doc_id = result.doc_id().unwrap().to_string();");
     println!();
     println!("    // Query the indexed document");
-    println!("    let result = engine.query(&doc_id, \"What is the introduction?\").await?;");
+    println!("    let result = engine.query(");
+    println!("        QueryContext::new(\"What is the introduction?\").with_doc_id(&doc_id)");
+    println!("    ).await?;");
     println!("    println!(\"{{}}\", result.content);");
     println!();
     println!("    Ok(())");

examples/rust/markdownflow.rs

@@ -20,7 +20,7 @@
 //! ```
 
 use vectorless::EngineBuilder;
-use vectorless::client::{IndexContext, IndexOptions};
+use vectorless::client::{IndexContext, IndexOptions, QueryContext};
 
 /// Sample markdown content for demonstration.
 const SAMPLE_MARKDOWN: &str = r#"
@@ -62,29 +62,19 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
 
     // Check if we should generate summaries (requires API key)
     println!("  - API key detected, generating summaries...");
-    let doc_id = client
+    let index_result = client
         .index(IndexContext::from_path(&md_path).with_options(IndexOptions::new().with_summaries()))
         .await?;
+    let doc_id = index_result.doc_id().unwrap().to_string();
 
     println!("  - Document indexed successfully");
     println!("  - Document ID: {}", doc_id);
     println!();
 
-    // Step 3: Show document structure in JSON format
-    println!("Step 3: Document structure (JSON):");
-    println!();
-
-    match client.get_structure(&doc_id).await {
-        Ok(tree) => {
-            // Export to JSON format (PageIndex compatible)
-            let structure = tree.to_structure_json("sample.md");
-            let json = serde_json::to_string_pretty(&structure)
-                .unwrap_or_else(|_| "Failed to serialize".to_string());
-            println!("{}", json);
-        }
-        Err(e) => {
-            println!("  - Error getting structure: {}", e);
-        }
+    // Step 3: List indexed documents
+    println!("Step 3: Indexed documents:");
+    for doc in client.list().await? {
+        println!("  - {} ({})", doc.name, doc.id);
     }
     println!();
 
@@ -96,7 +86,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
     for query in queries {
         println!("  Query: \"{}\"", query);
 
-        match client.query(&doc_id, query).await {
+        match client.query(QueryContext::new(query).with_doc_id(&doc_id)).await {
             Ok(result) => {
                 if result.content.is_empty() {
                     println!("    - No relevant content found");