vectra 0.12.2 → 0.14.0

package/src/templates/go/vectra_client.go

@@ -0,0 +1,322 @@
+// Package vectra provides an idiomatic Go client for the Vectra gRPC server.
+//
+// Usage:
+//
+//	client, err := vectra.NewClient("127.0.0.1:50051")
+//	if err != nil {
+//	    log.Fatal(err)
+//	}
+//	defer client.Close()
+//
+//	results, err := client.QueryDocuments(ctx, "my-index", "search query", nil)
+package vectra
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+
+	pb "your_module/vectra_service" // replace with your actual module path
+
+	"google.golang.org/grpc"
+	"google.golang.org/grpc/credentials/insecure"
+)
+
+// Client is an idiomatic Go client for the Vectra gRPC server.
+type Client struct {
+	conn *grpc.ClientConn
+	stub pb.VectraServiceClient
+}
+
+// NewClient connects to a Vectra gRPC server at the given address.
+func NewClient(addr string) (*Client, error) {
+	conn, err := grpc.NewClient(addr, grpc.WithTransportCredentials(insecure.NewCredentials()))
+	if err != nil {
+		return nil, fmt.Errorf("vectra: dial %s: %w", addr, err)
+	}
+	return &Client{conn: conn, stub: pb.NewVectraServiceClient(conn)}, nil
+}
+
+// Close releases the underlying gRPC connection.
+func (c *Client) Close() error {
+	return c.conn.Close()
+}
+
+// ── Index Management ──────────────────────────────────
+
+// CreateIndex creates a new index on the server.
+func (c *Client) CreateIndex(ctx context.Context, name, format string, isDocumentIndex bool) error {
+	req := &pb.CreateIndexRequest{
+		IndexName:       name,
+		Format:          format,
+		IsDocumentIndex: isDocumentIndex,
+	}
+	if isDocumentIndex {
+		req.DocumentConfig = &pb.DocumentIndexConfig{
+			Version:   1,
+			ChunkSize: 512,
+		}
+	}
+	_, err := c.stub.CreateIndex(ctx, req)
+	return err
+}
+
+// DeleteIndex deletes an index from the server.
+func (c *Client) DeleteIndex(ctx context.Context, name string) error {
+	_, err := c.stub.DeleteIndex(ctx, &pb.DeleteIndexRequest{IndexName: name})
+	return err
+}
+
+// IndexInfo holds summary information about an index.
+type IndexInfo struct {
+	Name            string
+	Format          string
+	IsDocumentIndex bool
+}
+
+// ListIndexes returns all indexes managed by the server.
+func (c *Client) ListIndexes(ctx context.Context) ([]IndexInfo, error) {
+	resp, err := c.stub.ListIndexes(ctx, &pb.ListIndexesRequest{})
+	if err != nil {
+		return nil, err
+	}
+	out := make([]IndexInfo, len(resp.Indexes))
+	for i, idx := range resp.Indexes {
+		out[i] = IndexInfo{Name: idx.Name, Format: idx.Format, IsDocumentIndex: idx.IsDocumentIndex}
+	}
+	return out, nil
+}
+
+// ── Item Operations ───────────────────────────────────
+
+// InsertItem adds a new item to an index. Returns the assigned ID.
+func (c *Client) InsertItem(ctx context.Context, index, text string, vector []float32, metadata map[string]*pb.MetadataValue, id string) (string, error) {
+	req := &pb.InsertItemRequest{
+		IndexName: index,
+		Text:      text,
+		Vector:    vector,
+		Metadata:  metadata,
+		Id:        id,
+	}
+	resp, err := c.stub.InsertItem(ctx, req)
+	if err != nil {
+		return "", err
+	}
+	return resp.Id, nil
+}
+
+// UpsertItem inserts or updates an item. Returns the ID.
+func (c *Client) UpsertItem(ctx context.Context, index, id, text string, vector []float32, metadata map[string]*pb.MetadataValue) (string, error) {
+	req := &pb.UpsertItemRequest{
+		IndexName: index,
+		Id:        id,
+		Text:      text,
+		Vector:    vector,
+		Metadata:  metadata,
+	}
+	resp, err := c.stub.UpsertItem(ctx, req)
+	if err != nil {
+		return "", err
+	}
+	return resp.Id, nil
+}
+
+// GetItem retrieves a single item by ID.
+func (c *Client) GetItem(ctx context.Context, index, id string) (*pb.ItemResult, error) {
+	resp, err := c.stub.GetItem(ctx, &pb.GetItemRequest{IndexName: index, Id: id})
+	if err != nil {
+		return nil, err
+	}
+	return resp.Item, nil
+}
+
+// DeleteItem removes an item by ID.
+func (c *Client) DeleteItem(ctx context.Context, index, id string) error {
+	_, err := c.stub.DeleteItem(ctx, &pb.DeleteItemRequest{IndexName: index, Id: id})
+	return err
+}
+
+// ListItems returns items in an index, optionally filtered.
+// filterJSON should be a JSON string with MongoDB-style filter operators, or empty.
+func (c *Client) ListItems(ctx context.Context, index, filterJSON string) ([]*pb.ItemResult, error) {
+	req := &pb.ListItemsRequest{IndexName: index}
+	if filterJSON != "" {
+		req.Filter = &pb.MetadataFilter{FilterJson: filterJSON}
+	}
+	resp, err := c.stub.ListItems(ctx, req)
+	if err != nil {
+		return nil, err
+	}
+	return resp.Items, nil
+}
+
+// ── Query ─────────────────────────────────────────────
+
+// QueryItems performs a vector similarity query. Returns ranked results.
+func (c *Client) QueryItems(ctx context.Context, index, text string, topK uint32, filterJSON string) ([]*pb.ItemResult, error) {
+	req := &pb.QueryItemsRequest{
+		IndexName: index,
+		Text:      text,
+		TopK:      topK,
+	}
+	if filterJSON != "" {
+		req.Filter = &pb.MetadataFilter{FilterJson: filterJSON}
+	}
+	resp, err := c.stub.QueryItems(ctx, req)
+	if err != nil {
+		return nil, err
+	}
+	return resp.Results, nil
+}
+
+// QueryDocumentsOpts holds optional parameters for QueryDocuments.
+type QueryDocumentsOpts struct {
+	MaxDocuments uint32
+	MaxChunks    uint32
+	FilterJSON   string
+	UseBM25      bool
+}
+
+// QueryDocuments performs a document-level semantic search.
+func (c *Client) QueryDocuments(ctx context.Context, index, query string, opts *QueryDocumentsOpts) ([]*pb.DocumentResult, error) {
+	req := &pb.QueryDocumentsRequest{
+		IndexName:    index,
+		Query:        query,
+		MaxDocuments: 10,
+		MaxChunks:    50,
+	}
+	if opts != nil {
+		if opts.MaxDocuments > 0 {
+			req.MaxDocuments = opts.MaxDocuments
+		}
+		if opts.MaxChunks > 0 {
+			req.MaxChunks = opts.MaxChunks
+		}
+		if opts.FilterJSON != "" {
+			req.Filter = &pb.MetadataFilter{FilterJson: opts.FilterJSON}
+		}
+		req.UseBm25 = opts.UseBM25
+	}
+	resp, err := c.stub.QueryDocuments(ctx, req)
+	if err != nil {
+		return nil, err
+	}
+	return resp.Results, nil
+}
+
+// ── Document Operations ───────────────────────────────
+
+// UpsertDocument inserts or updates a document. Returns the document ID.
+func (c *Client) UpsertDocument(ctx context.Context, index, uri, text, docType string, metadata map[string]*pb.MetadataValue) (string, error) {
+	req := &pb.UpsertDocumentRequest{
+		IndexName: index,
+		Uri:       uri,
+		Text:      text,
+		DocType:   docType,
+		Metadata:  metadata,
+	}
+	resp, err := c.stub.UpsertDocument(ctx, req)
+	if err != nil {
+		return "", err
+	}
+	return resp.DocumentId, nil
+}
+
+// DeleteDocument removes a document by URI.
+func (c *Client) DeleteDocument(ctx context.Context, index, uri string) error {
+	_, err := c.stub.DeleteDocument(ctx, &pb.DeleteDocumentRequest{IndexName: index, Uri: uri})
+	return err
+}
+
+// DocumentInfo holds summary information about a document.
+type DocumentInfo struct {
+	URI        string
+	DocumentID string
+}
+
+// ListDocuments returns all documents in a document index.
+func (c *Client) ListDocuments(ctx context.Context, index string) ([]DocumentInfo, error) {
+	resp, err := c.stub.ListDocuments(ctx, &pb.ListDocumentsRequest{IndexName: index})
+	if err != nil {
+		return nil, err
+	}
+	out := make([]DocumentInfo, len(resp.Documents))
+	for i, d := range resp.Documents {
+		out[i] = DocumentInfo{URI: d.Uri, DocumentID: d.DocumentId}
+	}
+	return out, nil
+}
+
+// ── Stats ─────────────────────────────────────────────
+
+// GetIndexStats returns statistics for an index.
+func (c *Client) GetIndexStats(ctx context.Context, index string) (*pb.GetIndexStatsResponse, error) {
+	resp, err := c.stub.GetIndexStats(ctx, &pb.GetIndexStatsRequest{IndexName: index})
+	if err != nil {
+		return nil, err
+	}
+	return resp, nil
+}
+
+// GetCatalogStats returns catalog statistics for a document index.
+func (c *Client) GetCatalogStats(ctx context.Context, index string) (*pb.GetCatalogStatsResponse, error) {
+	resp, err := c.stub.GetCatalogStats(ctx, &pb.GetCatalogStatsRequest{IndexName: index})
+	if err != nil {
+		return nil, err
+	}
+	return resp, nil
+}
+
+// ── Lifecycle ─────────────────────────────────────────
+
+// HealthcheckResult holds the server health status.
+type HealthcheckResult struct {
+	Status        string
+	UptimeSeconds float64
+	LoadedIndexes int32
+}
+
+// Healthcheck returns the server's health status.
+func (c *Client) Healthcheck(ctx context.Context) (*HealthcheckResult, error) {
+	resp, err := c.stub.Healthcheck(ctx, &pb.HealthcheckRequest{})
+	if err != nil {
+		return nil, err
+	}
+	return &HealthcheckResult{
+		Status:        resp.Status,
+		UptimeSeconds: resp.UptimeSeconds,
+		LoadedIndexes: resp.LoadedIndexes,
+	}, nil
+}
+
+// Shutdown requests a graceful server shutdown.
+func (c *Client) Shutdown(ctx context.Context) error {
+	_, err := c.stub.Shutdown(ctx, &pb.ShutdownRequest{})
+	return err
+}
+
+// ── Helpers ───────────────────────────────────────────
+
+// MetaString creates a string metadata value.
+func MetaString(s string) *pb.MetadataValue {
+	return &pb.MetadataValue{Value: &pb.MetadataValue_StringValue{StringValue: s}}
+}
+
+// MetaNumber creates a numeric metadata value.
+func MetaNumber(n float64) *pb.MetadataValue {
+	return &pb.MetadataValue{Value: &pb.MetadataValue_NumberValue{NumberValue: n}}
+}
+
+// MetaBool creates a boolean metadata value.
+func MetaBool(b bool) *pb.MetadataValue {
+	return &pb.MetadataValue{Value: &pb.MetadataValue_BoolValue{BoolValue: b}}
+}
+
+// FilterJSON marshals a map into a JSON string suitable for filter parameters.
+func FilterJSON(filter map[string]interface{}) (string, error) {
+	b, err := json.Marshal(filter)
+	if err != nil {
+		return "", fmt.Errorf("vectra: marshal filter: %w", err)
+	}
+	return string(b), nil
+}

package/src/templates/java/README.md

@@ -0,0 +1,81 @@
+# Vectra Java Client
+
+Thin idiomatic Java wrapper over the Vectra gRPC service.
+
+## Prerequisites
+
+Add gRPC dependencies to your build tool.
+
+### Gradle
+
+```groovy
+plugins {
+    id 'com.google.protobuf' version '0.9.4'
+}
+
+dependencies {
+    implementation 'io.grpc:grpc-netty-shaded:1.65.0'
+    implementation 'io.grpc:grpc-protobuf:1.65.0'
+    implementation 'io.grpc:grpc-stub:1.65.0'
+    compileOnly 'javax.annotation:javax.annotation-api:1.3.2'
+}
+
+protobuf {
+    protoc { artifact = 'com.google.protobuf:protoc:3.25.3' }
+    plugins {
+        grpc { artifact = 'io.grpc:protoc-gen-grpc-java:1.65.0' }
+    }
+    generateProtoTasks {
+        all()*.plugins { grpc {} }
+    }
+}
+```
+
+### Maven
+
+```xml
+<dependencies>
+    <dependency>
+        <groupId>io.grpc</groupId>
+        <artifactId>grpc-netty-shaded</artifactId>
+        <version>1.65.0</version>
+    </dependency>
+    <dependency>
+        <groupId>io.grpc</groupId>
+        <artifactId>grpc-protobuf</artifactId>
+        <version>1.65.0</version>
+    </dependency>
+    <dependency>
+        <groupId>io.grpc</groupId>
+        <artifactId>grpc-stub</artifactId>
+        <version>1.65.0</version>
+    </dependency>
+</dependencies>
+```
+
+## Generate gRPC stubs
+
+Place `vectra_service.proto` in `src/main/proto/`. With the Gradle protobuf plugin or Maven gRPC plugin, stubs are generated automatically at build time.
+
+## Usage
+
+```java
+import io.github.vectra.client.VectraClient;
+
+try (VectraClient client = new VectraClient()) {
+    // Create a document index
+    client.createIndex("my-index", "json", true, 512, 0);
+
+    // Add a document
+    client.upsertDocument("my-index", "doc1.txt", "Hello world...");
+
+    // Query
+    var results = client.queryDocuments("my-index", "hello");
+    for (var doc : results) {
+        System.out.printf("%s (score: %.3f)%n", doc.getUri(), doc.getScore());
+        for (var chunk : doc.getChunksList()) {
+            System.out.printf("  %s...%n", chunk.getText().substring(0, Math.min(80, chunk.getText().length())));
+        }
+    }
+}
+```

package/src/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/src/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]}...")
+```