feat: add directory indexing example and enhance IndexContext

zTgx · zTgx · commit 782c3783b25e · 2026-04-15T10:11:53.000+08:00
- Add new example script examples/index_directory/main.py that
  demonstrates recursive directory indexing functionality
- The example supports command-line arguments for directory path
  and recursive/non-recursive scanning options
- Add environment variable support for LLM configuration
- Implement document listing, querying, and metrics reporting
- Add __len__ and is_empty methods to PyIndexContext for better
  Python integration
- Update IndexContext repr to show number of sources
diff --git a/examples/index_directory/main.py b/examples/index_directory/main.py
@@ -0,0 +1,100 @@
+"""
+Directory indexing example — recursively index all documents in a directory.
+
+Usage:
+    python index_directory.py /path/to/docs
+    python index_directory.py /path/to/docs --no-recursive
+
+Environment variables:
+    LLM_API_KEY    — Your LLM API key (required)
+    LLM_MODEL      — Model name (default: google/gemini-3-flash-preview)
+    LLM_ENDPOINT   — API endpoint (default: http://localhost:4000/api/v1)
+"""
+
+import argparse
+import asyncio
+import os
+
+from vectorless import Engine, IndexContext, QueryContext
+
+
+async def main():
+    parser = argparse.ArgumentParser(description="Index a directory of documents")
+    parser.add_argument("directory", help="Directory path to index")
+    parser.add_argument(
+        "--no-recursive",
+        action="store_true",
+        help="Only scan top-level files (default: recursive)",
+    )
+    args = parser.parse_args()
+
+    # Build engine
+    api_key = os.environ.get("LLM_API_KEY", "sk-or-v1-...")
+    model = os.environ.get("LLM_MODEL", "google/gemini-3-flash-preview")
+    endpoint = os.environ.get("LLM_ENDPOINT", "http://localhost:4000/api/v1")
+
+    engine = Engine(
+        workspace="./workspace_directory_example",
+        api_key=api_key,
+        model=model,
+        endpoint=endpoint,
+    )
+
+    recursive = not args.no_recursive
+
+    # Index directory
+    ctx = IndexContext.from_dir(args.directory, recursive=recursive)
+
+    if ctx.is_empty():
+        print(f"No supported files found in: {args.directory}")
+        return
+
+    print(f"{'Recursively scanning' if recursive else 'Scanning top-level files in'}: {args.directory}")
+    print(f"Found files to index")
+
+    result = await engine.index(ctx)
+
+    print(f"\nIndexed {len(result.items)} document(s):")
+    for item in result.items:
+        print(f"  {item.name} ({item.doc_id})")
+        if item.metrics:
+            print(f"    nodes: {item.metrics.nodes_processed}, time: {item.metrics.total_time_ms}ms")
+
+    if result.has_failures():
+        print("\nFailed:")
+        for f in result.failed:
+            print(f"  {f.source} — {f.error}")
+
+    # Query across all indexed documents
+    query = "What is this about?"
+    print(f'\nQuerying: "{query}"')
+
+    answer = await engine.query(QueryContext(query))
+    for item in answer.items:
+        print(f"  [{item.doc_id} score={item.score:.2f}]")
+        preview = item.content[:200]
+        print(f"  {preview}")
+        if len(item.content) > 200:
+            print("  ...")
+
+    # Metrics report
+    report = engine.metrics_report()
+    print("\nMetrics:")
+    print(
+        f"  LLM: {report.llm.total_calls} calls, "
+        f"{report.llm.total_tokens} tokens, "
+        f"${report.llm.estimated_cost_usd:.4f}"
+    )
+    print(
+        f"  Retrieval: {report.retrieval.total_queries} queries, "
+        f"avg score {report.retrieval.avg_path_score:.2f}"
+    )
+
+    # Cleanup
+    docs = await engine.list()
+    for doc in docs:
+        await engine.remove(doc.id)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
diff --git a/python/src/lib.rs b/python/src/lib.rs
@@ -283,8 +283,18 @@ impl PyIndexContext {
         Ok(Self { inner: ctx })
     }
 
+    /// Number of document sources.
+    fn __len__(&self) -> usize {
+        self.inner.len()
+    }
+
+    /// Whether no sources are present.
+    fn is_empty(&self) -> bool {
+        self.inner.is_empty()
+    }
+
     fn __repr__(&self) -> String {
-        "IndexContext(...)".to_string()
+        format!("IndexContext(sources={})", self.inner.len())
     }
 }
 

Original file line number	Diff line number	Diff line change
`@@ -283,8 +283,18 @@ impl PyIndexContext {`
`283`	`283`	`Ok(Self { inner: ctx })`
`284`	`284`	`}`
`285`	`285`
	`286`	`+ /// Number of document sources.`
	`287`	`+ fn __len__(&self) -> usize {`
	`288`	`+ self.inner.len()`
	`289`	`+ }`
	`290`	`+`
	`291`	`+ /// Whether no sources are present.`
	`292`	`+ fn is_empty(&self) -> bool {`
	`293`	`+ self.inner.is_empty()`
	`294`	`+ }`
	`295`	`+`
`286`	`296`	`fn __repr__(&self) -> String {`
`287`		`- "IndexContext(...)".to_string()`
	`297`	`+ format!("IndexContext(sources={})", self.inner.len())`
`288`	`298`	`}`
`289`	`299`	`}`
`290`	`300`