vectra 0.12.2 → 0.14.0

package/lib/templates/templates/java/VectraClient.java

@@ -0,0 +1,232 @@
+// Vectra gRPC client — thin idiomatic wrapper over generated stubs.
+//
+// Usage:
+//   try (VectraClient client = new VectraClient()) {
+//       List<DocumentResult> results = client.queryDocuments("my-index", "search query");
+//   }
+//
+// Generate stubs first (see README.md).
+
+package io.github.vectra.client;
+
+import com.google.protobuf.util.JsonFormat;
+import io.grpc.ManagedChannel;
+import io.grpc.ManagedChannelBuilder;
+import vectra.VectraServiceGrpc;
+import vectra.VectraServiceProto.*;
+
+import java.util.*;
+import java.util.concurrent.TimeUnit;
+import java.util.stream.Collectors;
+
+/**
+ * Idiomatic Java client for the Vectra gRPC server.
+ */
+public class VectraClient implements AutoCloseable {
+    private final ManagedChannel channel;
+    private final VectraServiceGrpc.VectraServiceBlockingStub stub;
+
+    public VectraClient() {
+        this("127.0.0.1", 50051);
+    }
+
+    public VectraClient(String host, int port) {
+        this.channel = ManagedChannelBuilder.forAddress(host, port)
+                .usePlaintext()
+                .build();
+        this.stub = VectraServiceGrpc.newBlockingStub(channel);
+    }
+
+    @Override
+    public void close() {
+        try {
+            channel.shutdown().awaitTermination(5, TimeUnit.SECONDS);
+        } catch (InterruptedException e) {
+            channel.shutdownNow();
+            Thread.currentThread().interrupt();
+        }
+    }
+
+    // ── Index Management ──────────────────────────────────
+
+    public void createIndex(String name) {
+        createIndex(name, "json", false, 512, 0);
+    }
+
+    public void createIndex(String name, String format, boolean isDocumentIndex,
+                            int chunkSize, int chunkOverlap) {
+        CreateIndexRequest.Builder req = CreateIndexRequest.newBuilder()
+                .setIndexName(name)
+                .setFormat(format)
+                .setIsDocumentIndex(isDocumentIndex);
+        if (isDocumentIndex) {
+            req.setDocumentConfig(DocumentIndexConfig.newBuilder()
+                    .setVersion(1)
+                    .setChunkSize(chunkSize)
+                    .setChunkOverlap(chunkOverlap)
+                    .build());
+        }
+        stub.createIndex(req.build());
+    }
+
+    public void deleteIndex(String name) {
+        stub.deleteIndex(DeleteIndexRequest.newBuilder().setIndexName(name).build());
+    }
+
+    public List<IndexInfo> listIndexes() {
+        ListIndexesResponse resp = stub.listIndexes(ListIndexesRequest.getDefaultInstance());
+        return resp.getIndexesList();
+    }
+
+    // ── Item Operations ───────────────────────────────────
+
+    public String insertItem(String index, String text) {
+        return insertItem(index, text, null, null, "");
+    }
+
+    public String insertItem(String index, String text, List<Float> vector,
+                             Map<String, MetadataValue> metadata, String id) {
+        InsertItemRequest.Builder req = InsertItemRequest.newBuilder()
+                .setIndexName(index)
+                .setText(text)
+                .setId(id != null ? id : "");
+        if (vector != null) req.addAllVector(vector);
+        if (metadata != null) req.putAllMetadata(metadata);
+        return stub.insertItem(req.build()).getId();
+    }
+
+    public String upsertItem(String index, String id, String text, List<Float> vector,
+                             Map<String, MetadataValue> metadata) {
+        UpsertItemRequest.Builder req = UpsertItemRequest.newBuilder()
+                .setIndexName(index)
+                .setId(id)
+                .setText(text);
+        if (vector != null) req.addAllVector(vector);
+        if (metadata != null) req.putAllMetadata(metadata);
+        return stub.upsertItem(req.build()).getId();
+    }
+
+    public ItemResult getItem(String index, String id) {
+        GetItemResponse resp = stub.getItem(
+                GetItemRequest.newBuilder().setIndexName(index).setId(id).build());
+        return resp.hasItem() ? resp.getItem() : null;
+    }
+
+    public void deleteItem(String index, String id) {
+        stub.deleteItem(DeleteItemRequest.newBuilder().setIndexName(index).setId(id).build());
+    }
+
+    public List<ItemResult> listItems(String index) {
+        return listItems(index, null);
+    }
+
+    public List<ItemResult> listItems(String index, String filterJson) {
+        ListItemsRequest.Builder req = ListItemsRequest.newBuilder().setIndexName(index);
+        if (filterJson != null && !filterJson.isEmpty()) {
+            req.setFilter(MetadataFilter.newBuilder().setFilterJson(filterJson).build());
+        }
+        return stub.listItems(req.build()).getItemsList();
+    }
+
+    // ── Query ─────────────────────────────────────────────
+
+    public List<ItemResult> queryItems(String index, String text, int topK) {
+        return queryItems(index, text, topK, null);
+    }
+
+    public List<ItemResult> queryItems(String index, String text, int topK, String filterJson) {
+        QueryItemsRequest.Builder req = QueryItemsRequest.newBuilder()
+                .setIndexName(index)
+                .setText(text)
+                .setTopK(topK);
+        if (filterJson != null && !filterJson.isEmpty()) {
+            req.setFilter(MetadataFilter.newBuilder().setFilterJson(filterJson).build());
+        }
+        return stub.queryItems(req.build()).getResultsList();
+    }
+
+    public List<DocumentResult> queryDocuments(String index, String query) {
+        return queryDocuments(index, query, 10, 50, null, false);
+    }
+
+    public List<DocumentResult> queryDocuments(String index, String query,
+                                                int maxDocuments, int maxChunks,
+                                                String filterJson, boolean useBm25) {
+        QueryDocumentsRequest.Builder req = QueryDocumentsRequest.newBuilder()
+                .setIndexName(index)
+                .setQuery(query)
+                .setMaxDocuments(maxDocuments)
+                .setMaxChunks(maxChunks)
+                .setUseBm25(useBm25);
+        if (filterJson != null && !filterJson.isEmpty()) {
+            req.setFilter(MetadataFilter.newBuilder().setFilterJson(filterJson).build());
+        }
+        return stub.queryDocuments(req.build()).getResultsList();
+    }
+
+    // ── Document Operations ───────────────────────────────
+
+    public String upsertDocument(String index, String uri, String text) {
+        return upsertDocument(index, uri, text, "", null);
+    }
+
+    public String upsertDocument(String index, String uri, String text,
+                                  String docType, Map<String, MetadataValue> metadata) {
+        UpsertDocumentRequest.Builder req = UpsertDocumentRequest.newBuilder()
+                .setIndexName(index)
+                .setUri(uri)
+                .setText(text)
+                .setDocType(docType != null ? docType : "");
+        if (metadata != null) req.putAllMetadata(metadata);
+        return stub.upsertDocument(req.build()).getDocumentId();
+    }
+
+    public void deleteDocument(String index, String uri) {
+        stub.deleteDocument(DeleteDocumentRequest.newBuilder()
+                .setIndexName(index).setUri(uri).build());
+    }
+
+    public List<DocumentInfo> listDocuments(String index) {
+        return stub.listDocuments(ListDocumentsRequest.newBuilder()
+                .setIndexName(index).build()).getDocumentsList();
+    }
+
+    // ── Stats ─────────────────────────────────────────────
+
+    public GetIndexStatsResponse getIndexStats(String index) {
+        return stub.getIndexStats(
+                GetIndexStatsRequest.newBuilder().setIndexName(index).build());
+    }
+
+    public GetCatalogStatsResponse getCatalogStats(String index) {
+        return stub.getCatalogStats(
+                GetCatalogStatsRequest.newBuilder().setIndexName(index).build());
+    }
+
+    // ── Lifecycle ─────────────────────────────────────────
+
+    public HealthcheckResponse healthcheck() {
+        return stub.healthcheck(HealthcheckRequest.getDefaultInstance());
+    }
+
+    public void shutdown() {
+        stub.shutdown(ShutdownRequest.getDefaultInstance());
+    }
+
+    // ── Helpers ───────────────────────────────────────────
+
+    /** Create a string metadata value. */
+    public static MetadataValue metaString(String s) {
+        return MetadataValue.newBuilder().setStringValue(s).build();
+    }
+
+    /** Create a numeric metadata value. */
+    public static MetadataValue metaNumber(double n) {
+        return MetadataValue.newBuilder().setNumberValue(n).build();
+    }
+
+    /** Create a boolean metadata value. */
+    public static MetadataValue metaBool(boolean b) {
+        return MetadataValue.newBuilder().setBoolValue(b).build();
+    }
+}

package/lib/templates/templates/python/README.md

@@ -0,0 +1,37 @@
+# Vectra Python Client
+
+Thin idiomatic Python wrapper over the Vectra gRPC service.
+
+## Prerequisites
+
+```bash
+pip install grpcio grpcio-tools
+```
+
+## Generate gRPC stubs
+
+```bash
+python -m grpc_tools.protoc -I. --python_out=. --grpc_python_out=. vectra_service.proto
+```
+
+This produces `vectra_service_pb2.py` and `vectra_service_pb2_grpc.py`.
+
+## Usage
+
+```python
+from vectra_client import VectraClient
+
+with VectraClient() as client:
+    # Create a document index
+    client.create_index("my-index", is_document_index=True)
+
+    # Add a document
+    client.upsert_document("my-index", "doc1.txt", "Hello world...")
+
+    # Query
+    results = client.query_documents("my-index", "hello")
+    for doc in results:
+        print(f"{doc['uri']} (score: {doc['score']:.3f})")
+        for chunk in doc["chunks"]:
+            print(f"  {chunk['text'][:80]}...")
+```

package/lib/templates/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/lib/templates/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/lib/templates/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/lib/templates/templates/rust/build.rs

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