vectra 0.12.2 → 0.14.0

package/src/templates/python/vectra_client.py

@@ -0,0 +1,279 @@
+"""Vectra gRPC client — thin idiomatic wrapper over generated stubs.
+
+Usage:
+    from vectra_client import VectraClient
+
+    client = VectraClient()  # localhost:50051
+    results = client.query_documents("my-index", "search query")
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import grpc
+
+# Generated stubs — run `python -m grpc_tools.protoc` to produce these:
+#   python -m grpc_tools.protoc -I. --python_out=. --grpc_python_out=. vectra_service.proto
+import vectra_service_pb2 as pb2
+import vectra_service_pb2_grpc as pb2_grpc
+
+
+class VectraClient:
+    """Idiomatic Python client for the Vectra gRPC server."""
+
+    def __init__(self, host: str = "127.0.0.1", port: int = 50051):
+        self._channel = grpc.insecure_channel(f"{host}:{port}")
+        self._stub = pb2_grpc.VectraServiceStub(self._channel)
+
+    def close(self) -> None:
+        self._channel.close()
+
+    def __enter__(self) -> VectraClient:
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()
+
+    # ── Index Management ──────────────────────────────────
+
+    def create_index(
+        self,
+        name: str,
+        *,
+        format: str = "json",
+        is_document_index: bool = False,
+        chunk_size: int = 512,
+        chunk_overlap: int = 0,
+    ) -> None:
+        doc_config = pb2.DocumentIndexConfig(
+            version=1,
+            chunk_size=chunk_size,
+            chunk_overlap=chunk_overlap,
+        ) if is_document_index else None
+        self._stub.CreateIndex(pb2.CreateIndexRequest(
+            index_name=name,
+            format=format,
+            is_document_index=is_document_index,
+            document_config=doc_config,
+        ))
+
+    def delete_index(self, name: str) -> None:
+        self._stub.DeleteIndex(pb2.DeleteIndexRequest(index_name=name))
+
+    def list_indexes(self) -> list[dict[str, Any]]:
+        resp = self._stub.ListIndexes(pb2.ListIndexesRequest())
+        return [
+            {"name": idx.name, "format": idx.format, "is_document_index": idx.is_document_index}
+            for idx in resp.indexes
+        ]
+
+    # ── Item Operations ───────────────────────────────────
+
+    def insert_item(
+        self,
+        index: str,
+        *,
+        text: str = "",
+        vector: list[float] | None = None,
+        metadata: dict[str, Any] | None = None,
+        id: str = "",
+    ) -> str:
+        req = pb2.InsertItemRequest(
+            index_name=index,
+            text=text,
+            id=id,
+        )
+        if vector:
+            req.vector.extend(vector)
+        if metadata:
+            _set_metadata(req.metadata, metadata)
+        return self._stub.InsertItem(req).id
+
+    def upsert_item(
+        self,
+        index: str,
+        id: str,
+        *,
+        text: str = "",
+        vector: list[float] | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> str:
+        req = pb2.UpsertItemRequest(
+            index_name=index,
+            id=id,
+            text=text,
+        )
+        if vector:
+            req.vector.extend(vector)
+        if metadata:
+            _set_metadata(req.metadata, metadata)
+        return self._stub.UpsertItem(req).id
+
+    def get_item(self, index: str, id: str) -> dict[str, Any] | None:
+        resp = self._stub.GetItem(pb2.GetItemRequest(index_name=index, id=id))
+        return _item_to_dict(resp.item) if resp.HasField("item") else None
+
+    def delete_item(self, index: str, id: str) -> None:
+        self._stub.DeleteItem(pb2.DeleteItemRequest(index_name=index, id=id))
+
+    def list_items(
+        self, index: str, *, filter: dict[str, Any] | None = None
+    ) -> list[dict[str, Any]]:
+        req = pb2.ListItemsRequest(index_name=index)
+        if filter:
+            req.filter.CopyFrom(pb2.MetadataFilter(filter_json=json.dumps(filter)))
+        resp = self._stub.ListItems(req)
+        return [_item_to_dict(item) for item in resp.items]
+
+    # ── Query ─────────────────────────────────────────────
+
+    def query_items(
+        self,
+        index: str,
+        *,
+        text: str = "",
+        vector: list[float] | None = None,
+        top_k: int = 10,
+        filter: dict[str, Any] | None = None,
+    ) -> list[dict[str, Any]]:
+        req = pb2.QueryItemsRequest(
+            index_name=index,
+            text=text,
+            top_k=top_k,
+        )
+        if vector:
+            req.vector.extend(vector)
+        if filter:
+            req.filter.CopyFrom(pb2.MetadataFilter(filter_json=json.dumps(filter)))
+        resp = self._stub.QueryItems(req)
+        return [_item_to_dict(r) for r in resp.results]
+
+    def query_documents(
+        self,
+        index: str,
+        query: str,
+        *,
+        max_documents: int = 10,
+        max_chunks: int = 50,
+        filter: dict[str, Any] | None = None,
+        use_bm25: bool = False,
+    ) -> list[dict[str, Any]]:
+        req = pb2.QueryDocumentsRequest(
+            index_name=index,
+            query=query,
+            max_documents=max_documents,
+            max_chunks=max_chunks,
+            use_bm25=use_bm25,
+        )
+        if filter:
+            req.filter.CopyFrom(pb2.MetadataFilter(filter_json=json.dumps(filter)))
+        resp = self._stub.QueryDocuments(req)
+        return [
+            {
+                "uri": doc.uri,
+                "document_id": doc.document_id,
+                "score": doc.score,
+                "chunks": [
+                    {"text": c.text, "score": c.score, "token_count": c.token_count}
+                    for c in doc.chunks
+                ],
+            }
+            for doc in resp.results
+        ]
+
+    # ── Document Operations ───────────────────────────────
+
+    def upsert_document(
+        self,
+        index: str,
+        uri: str,
+        text: str,
+        *,
+        doc_type: str = "",
+        metadata: dict[str, Any] | None = None,
+    ) -> str:
+        req = pb2.UpsertDocumentRequest(
+            index_name=index,
+            uri=uri,
+            text=text,
+            doc_type=doc_type,
+        )
+        if metadata:
+            _set_metadata(req.metadata, metadata)
+        return self._stub.UpsertDocument(req).document_id
+
+    def delete_document(self, index: str, uri: str) -> None:
+        self._stub.DeleteDocument(pb2.DeleteDocumentRequest(index_name=index, uri=uri))
+
+    def list_documents(self, index: str) -> list[dict[str, Any]]:
+        resp = self._stub.ListDocuments(pb2.ListDocumentsRequest(index_name=index))
+        return [{"uri": d.uri, "document_id": d.document_id} for d in resp.documents]
+
+    # ── Stats ─────────────────────────────────────────────
+
+    def get_index_stats(self, index: str) -> dict[str, Any]:
+        resp = self._stub.GetIndexStats(pb2.GetIndexStatsRequest(index_name=index))
+        return {
+            "version": resp.version,
+            "format": resp.format,
+            "item_count": resp.item_count,
+            "metadata_config_count": resp.metadata_config_count,
+        }
+
+    def get_catalog_stats(self, index: str) -> dict[str, Any]:
+        resp = self._stub.GetCatalogStats(pb2.GetCatalogStatsRequest(index_name=index))
+        return {
+            "version": resp.version,
+            "document_count": resp.document_count,
+            "chunk_count": resp.chunk_count,
+            "metadata_counts": dict(resp.metadata_counts),
+        }
+
+    # ── Lifecycle ─────────────────────────────────────────
+
+    def healthcheck(self) -> dict[str, Any]:
+        resp = self._stub.Healthcheck(pb2.HealthcheckRequest())
+        return {
+            "status": resp.status,
+            "uptime_seconds": resp.uptime_seconds,
+            "loaded_indexes": resp.loaded_indexes,
+        }
+
+    def shutdown(self) -> None:
+        self._stub.Shutdown(pb2.ShutdownRequest())
+
+
+# ── Helpers ───────────────────────────────────────────────
+
+
+def _set_metadata(
+    proto_map: Any, metadata: dict[str, Any]
+) -> None:
+    for key, value in metadata.items():
+        if isinstance(value, bool):
+            proto_map[key].CopyFrom(pb2.MetadataValue(bool_value=value))
+        elif isinstance(value, (int, float)):
+            proto_map[key].CopyFrom(pb2.MetadataValue(number_value=value))
+        else:
+            proto_map[key].CopyFrom(pb2.MetadataValue(string_value=str(value)))
+
+
+def _item_to_dict(item: Any) -> dict[str, Any]:
+    metadata: dict[str, Any] = {}
+    for key, val in item.metadata.items():
+        which = val.WhichOneof("value")
+        if which == "string_value":
+            metadata[key] = val.string_value
+        elif which == "number_value":
+            metadata[key] = val.number_value
+        elif which == "bool_value":
+            metadata[key] = val.bool_value
+    return {
+        "id": item.id,
+        "metadata": metadata,
+        "vector": list(item.vector),
+        "norm": item.norm,
+        "score": item.score,
+    }

package/src/templates/rust/Cargo.toml

@@ -0,0 +1,14 @@
+[package]
+name = "vectra-client"
+version = "0.1.0"
+edition = "2021"
+description = "Vectra gRPC client for Rust"
+license = "MIT"
+
+[dependencies]
+tonic = "0.12"
+prost = "0.13"
+tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
+
+[build-dependencies]
+tonic-build = "0.12"

package/src/templates/rust/README.md

@@ -0,0 +1,39 @@
+# Vectra Rust Client
+
+Thin idiomatic Rust wrapper over the Vectra gRPC service.
+
+## Prerequisites
+
+- Rust toolchain (`rustup`)
+- `protoc` (Protocol Buffers compiler) — install via your package manager
+
+## Setup
+
+1. Copy the generated files (`vectra_service.proto`, `build.rs`, `Cargo.toml`, `lib.rs`) into your project.
+2. Place `vectra_service.proto` in the crate root (next to `Cargo.toml`).
+3. `tonic-build` in `build.rs` generates the stubs at compile time.
+
+## Usage
+
+```rust
+use vectra_client::VectraClient;
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let mut client = VectraClient::connect("http://127.0.0.1:50051").await?;
+
+    // Create a document index
+    client.create_index("my-index", "json", true).await?;
+
+    // Add a document
+    client.upsert_document("my-index", "doc1.txt", "Hello world...", None, None).await?;
+
+    // Query
+    let results = client.query_documents("my-index", "hello", None).await?;
+    for doc in &results {
+        println!("{} (score: {:.3})", doc.uri, doc.score);
+    }
+
+    Ok(())
+}
+```

package/src/templates/rust/build.rs

@@ -0,0 +1,4 @@
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    tonic_build::compile_protos("vectra_service.proto")?;
+    Ok(())
+}

package/src/templates/rust/lib.rs

@@ -0,0 +1,284 @@
+//! Vectra gRPC client — thin idiomatic wrapper over generated stubs.
+//!
+//! # Usage
+//!
+//! ```rust,no_run
+//! use vectra_client::VectraClient;
+//!
+//! #[tokio::main]
+//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
+//!     let mut client = VectraClient::connect("http://127.0.0.1:50051").await?;
+//!     let results = client.query_documents("my-index", "search query", None).await?;
+//!     for doc in &results {
+//!         println!("{} (score: {:.3})", doc.uri, doc.score);
+//!     }
+//!     Ok(())
+//! }
+//! ```
+
+pub mod vectra_service {
+    tonic::include_proto!("vectra");
+}
+
+use std::collections::HashMap;
+use vectra_service::vectra_service_client::VectraServiceClient;
+use vectra_service::*;
+
+/// Idiomatic Rust client for the Vectra gRPC server.
+pub struct VectraClient {
+    inner: VectraServiceClient<tonic::transport::Channel>,
+}
+
+impl VectraClient {
+    /// Connect to a Vectra gRPC server.
+    pub async fn connect(addr: &str) -> Result<Self, tonic::transport::Error> {
+        let inner = VectraServiceClient::connect(addr.to_string()).await?;
+        Ok(Self { inner })
+    }
+
+    // ── Index Management ──────────────────────────────────
+
+    pub async fn create_index(
+        &mut self,
+        name: &str,
+        format: &str,
+        is_document_index: bool,
+    ) -> Result<(), tonic::Status> {
+        let document_config = if is_document_index {
+            Some(DocumentIndexConfig {
+                version: 1,
+                chunk_size: 512,
+                chunk_overlap: 0,
+                embeddings_model: String::new(),
+            })
+        } else {
+            None
+        };
+        self.inner
+            .create_index(CreateIndexRequest {
+                index_name: name.to_string(),
+                format: format.to_string(),
+                is_document_index,
+                document_config,
+            })
+            .await?;
+        Ok(())
+    }
+
+    pub async fn delete_index(&mut self, name: &str) -> Result<(), tonic::Status> {
+        self.inner
+            .delete_index(DeleteIndexRequest {
+                index_name: name.to_string(),
+            })
+            .await?;
+        Ok(())
+    }
+
+    pub async fn list_indexes(&mut self) -> Result<Vec<IndexInfo>, tonic::Status> {
+        let resp = self.inner.list_indexes(ListIndexesRequest {}).await?;
+        Ok(resp.into_inner().indexes)
+    }
+
+    // ── Item Operations ───────────────────────────────────
+
+    pub async fn insert_item(
+        &mut self,
+        index: &str,
+        text: &str,
+        vector: Option<Vec<f32>>,
+        metadata: Option<HashMap<String, MetadataValue>>,
+        id: Option<&str>,
+    ) -> Result<String, tonic::Status> {
+        let resp = self
+            .inner
+            .insert_item(InsertItemRequest {
+                index_name: index.to_string(),
+                text: text.to_string(),
+                vector: vector.unwrap_or_default(),
+                metadata: metadata.unwrap_or_default(),
+                id: id.unwrap_or_default().to_string(),
+            })
+            .await?;
+        Ok(resp.into_inner().id)
+    }
+
+    pub async fn get_item(
+        &mut self,
+        index: &str,
+        id: &str,
+    ) -> Result<Option<ItemResult>, tonic::Status> {
+        let resp = self
+            .inner
+            .get_item(GetItemRequest {
+                index_name: index.to_string(),
+                id: id.to_string(),
+            })
+            .await?;
+        Ok(resp.into_inner().item)
+    }
+
+    pub async fn delete_item(&mut self, index: &str, id: &str) -> Result<(), tonic::Status> {
+        self.inner
+            .delete_item(DeleteItemRequest {
+                index_name: index.to_string(),
+                id: id.to_string(),
+            })
+            .await?;
+        Ok(())
+    }
+
+    // ── Query ─────────────────────────────────────────────
+
+    pub async fn query_items(
+        &mut self,
+        index: &str,
+        text: &str,
+        top_k: u32,
+        filter: Option<&str>,
+    ) -> Result<Vec<ItemResult>, tonic::Status> {
+        let resp = self
+            .inner
+            .query_items(QueryItemsRequest {
+                index_name: index.to_string(),
+                text: text.to_string(),
+                vector: vec![],
+                top_k,
+                filter: filter.map(|f| MetadataFilter {
+                    filter_json: f.to_string(),
+                }),
+            })
+            .await?;
+        Ok(resp.into_inner().results)
+    }
+
+    pub async fn query_documents(
+        &mut self,
+        index: &str,
+        query: &str,
+        filter: Option<&str>,
+    ) -> Result<Vec<DocumentResult>, tonic::Status> {
+        self.query_documents_opts(index, query, 10, 50, filter, false)
+            .await
+    }
+
+    pub async fn query_documents_opts(
+        &mut self,
+        index: &str,
+        query: &str,
+        max_documents: u32,
+        max_chunks: u32,
+        filter: Option<&str>,
+        use_bm25: bool,
+    ) -> Result<Vec<DocumentResult>, tonic::Status> {
+        let resp = self
+            .inner
+            .query_documents(QueryDocumentsRequest {
+                index_name: index.to_string(),
+                query: query.to_string(),
+                max_documents,
+                max_chunks,
+                filter: filter.map(|f| MetadataFilter {
+                    filter_json: f.to_string(),
+                }),
+                use_bm25,
+            })
+            .await?;
+        Ok(resp.into_inner().results)
+    }
+
+    // ── Document Operations ───────────────────────────────
+
+    pub async fn upsert_document(
+        &mut self,
+        index: &str,
+        uri: &str,
+        text: &str,
+        doc_type: Option<&str>,
+        metadata: Option<HashMap<String, MetadataValue>>,
+    ) -> Result<String, tonic::Status> {
+        let resp = self
+            .inner
+            .upsert_document(UpsertDocumentRequest {
+                index_name: index.to_string(),
+                uri: uri.to_string(),
+                text: text.to_string(),
+                doc_type: doc_type.unwrap_or_default().to_string(),
+                metadata: metadata.unwrap_or_default(),
+            })
+            .await?;
+        Ok(resp.into_inner().document_id)
+    }
+
+    pub async fn delete_document(&mut self, index: &str, uri: &str) -> Result<(), tonic::Status> {
+        self.inner
+            .delete_document(DeleteDocumentRequest {
+                index_name: index.to_string(),
+                uri: uri.to_string(),
+            })
+            .await?;
+        Ok(())
+    }
+
+    pub async fn list_documents(
+        &mut self,
+        index: &str,
+    ) -> Result<Vec<DocumentInfo>, tonic::Status> {
+        let resp = self
+            .inner
+            .list_documents(ListDocumentsRequest {
+                index_name: index.to_string(),
+            })
+            .await?;
+        Ok(resp.into_inner().documents)
+    }
+
+    // ── Stats ─────────────────────────────────────────────
+
+    pub async fn get_index_stats(
+        &mut self,
+        index: &str,
+    ) -> Result<GetIndexStatsResponse, tonic::Status> {
+        let resp = self
+            .inner
+            .get_index_stats(GetIndexStatsRequest {
+                index_name: index.to_string(),
+            })
+            .await?;
+        Ok(resp.into_inner())
+    }
+
+    // ── Lifecycle ─────────────────────────────────────────
+
+    pub async fn healthcheck(&mut self) -> Result<HealthcheckResponse, tonic::Status> {
+        let resp = self.inner.healthcheck(HealthcheckRequest {}).await?;
+        Ok(resp.into_inner())
+    }
+
+    pub async fn shutdown(&mut self) -> Result<(), tonic::Status> {
+        self.inner.shutdown(ShutdownRequest {}).await?;
+        Ok(())
+    }
+}
+
+// ── Helpers ───────────────────────────────────────────────
+
+/// Create a string metadata value.
+pub fn meta_string(s: &str) -> MetadataValue {
+    MetadataValue {
+        value: Some(metadata_value::Value::StringValue(s.to_string())),
+    }
+}
+
+/// Create a numeric metadata value.
+pub fn meta_number(n: f64) -> MetadataValue {
+    MetadataValue {
+        value: Some(metadata_value::Value::NumberValue(n)),
+    }
+}
+
+/// Create a boolean metadata value.
+pub fn meta_bool(b: bool) -> MetadataValue {
+    MetadataValue {
+        value: Some(metadata_value::Value::BoolValue(b)),
+    }
+}