vectra 0.12.2 → 0.14.0

package/lib/templates/templates/csharp/VectraClient.cs

@@ -0,0 +1,234 @@
+// Vectra gRPC client — thin idiomatic wrapper over generated stubs.
+//
+// Usage:
+//   using var client = new VectraClient();
+//   var results = await client.QueryDocumentsAsync("my-index", "search query");
+//
+// Generate stubs first (see README.md).
+
+using System.Text.Json;
+using Grpc.Net.Client;
+using Vectra;
+
+namespace Vectra.Client;
+
+/// <summary>Idiomatic C# client for the Vectra gRPC server.</summary>
+public sealed class VectraClient : IDisposable
+{
+    private readonly GrpcChannel _channel;
+    private readonly VectraService.VectraServiceClient _stub;
+
+    public VectraClient(string host = "127.0.0.1", int port = 50051)
+    {
+        _channel = GrpcChannel.ForAddress($"http://{host}:{port}");
+        _stub = new VectraService.VectraServiceClient(_channel);
+    }
+
+    public void Dispose() => _channel.Dispose();
+
+    // ── Index Management ──────────────────────────────────
+
+    public async Task CreateIndexAsync(
+        string name,
+        string format = "json",
+        bool isDocumentIndex = false,
+        uint chunkSize = 512,
+        uint chunkOverlap = 0)
+    {
+        var req = new CreateIndexRequest
+        {
+            IndexName = name,
+            Format = format,
+            IsDocumentIndex = isDocumentIndex,
+        };
+        if (isDocumentIndex)
+        {
+            req.DocumentConfig = new DocumentIndexConfig
+            {
+                Version = 1,
+                ChunkSize = chunkSize,
+                ChunkOverlap = chunkOverlap,
+            };
+        }
+        await _stub.CreateIndexAsync(req);
+    }
+
+    public async Task DeleteIndexAsync(string name)
+        => await _stub.DeleteIndexAsync(new DeleteIndexRequest { IndexName = name });
+
+    public async Task<List<IndexInfo>> ListIndexesAsync()
+    {
+        var resp = await _stub.ListIndexesAsync(new ListIndexesRequest());
+        return resp.Indexes.ToList();
+    }
+
+    // ── Item Operations ───────────────────────────────────
+
+    public async Task<string> InsertItemAsync(
+        string index,
+        string text = "",
+        IEnumerable<float>? vector = null,
+        Dictionary<string, object>? metadata = null,
+        string id = "")
+    {
+        var req = new InsertItemRequest
+        {
+            IndexName = index,
+            Text = text,
+            Id = id,
+        };
+        if (vector != null) req.Vector.AddRange(vector);
+        if (metadata != null) SetMetadata(req.Metadata, metadata);
+        var resp = await _stub.InsertItemAsync(req);
+        return resp.Id;
+    }
+
+    public async Task<string> UpsertItemAsync(
+        string index,
+        string id,
+        string text = "",
+        IEnumerable<float>? vector = null,
+        Dictionary<string, object>? metadata = null)
+    {
+        var req = new UpsertItemRequest
+        {
+            IndexName = index,
+            Id = id,
+            Text = text,
+        };
+        if (vector != null) req.Vector.AddRange(vector);
+        if (metadata != null) SetMetadata(req.Metadata, metadata);
+        var resp = await _stub.UpsertItemAsync(req);
+        return resp.Id;
+    }
+
+    public async Task<ItemResult?> GetItemAsync(string index, string id)
+    {
+        var resp = await _stub.GetItemAsync(new GetItemRequest { IndexName = index, Id = id });
+        return resp.Item;
+    }
+
+    public async Task DeleteItemAsync(string index, string id)
+        => await _stub.DeleteItemAsync(new DeleteItemRequest { IndexName = index, Id = id });
+
+    public async Task<List<ItemResult>> ListItemsAsync(
+        string index,
+        Dictionary<string, object>? filter = null)
+    {
+        var req = new ListItemsRequest { IndexName = index };
+        if (filter != null)
+            req.Filter = new MetadataFilter { FilterJson = JsonSerializer.Serialize(filter) };
+        var resp = await _stub.ListItemsAsync(req);
+        return resp.Items.ToList();
+    }
+
+    // ── Query ─────────────────────────────────────────────
+
+    public async Task<List<ItemResult>> QueryItemsAsync(
+        string index,
+        string text = "",
+        IEnumerable<float>? vector = null,
+        uint topK = 10,
+        Dictionary<string, object>? filter = null)
+    {
+        var req = new QueryItemsRequest
+        {
+            IndexName = index,
+            Text = text,
+            TopK = topK,
+        };
+        if (vector != null) req.Vector.AddRange(vector);
+        if (filter != null)
+            req.Filter = new MetadataFilter { FilterJson = JsonSerializer.Serialize(filter) };
+        var resp = await _stub.QueryItemsAsync(req);
+        return resp.Results.ToList();
+    }
+
+    public async Task<List<DocumentResult>> QueryDocumentsAsync(
+        string index,
+        string query,
+        uint maxDocuments = 10,
+        uint maxChunks = 50,
+        Dictionary<string, object>? filter = null,
+        bool useBm25 = false)
+    {
+        var req = new QueryDocumentsRequest
+        {
+            IndexName = index,
+            Query = query,
+            MaxDocuments = maxDocuments,
+            MaxChunks = maxChunks,
+            UseBm25 = useBm25,
+        };
+        if (filter != null)
+            req.Filter = new MetadataFilter { FilterJson = JsonSerializer.Serialize(filter) };
+        var resp = await _stub.QueryDocumentsAsync(req);
+        return resp.Results.ToList();
+    }
+
+    // ── Document Operations ───────────────────────────────
+
+    public async Task<string> UpsertDocumentAsync(
+        string index,
+        string uri,
+        string text,
+        string docType = "",
+        Dictionary<string, object>? metadata = null)
+    {
+        var req = new UpsertDocumentRequest
+        {
+            IndexName = index,
+            Uri = uri,
+            Text = text,
+            DocType = docType,
+        };
+        if (metadata != null) SetMetadata(req.Metadata, metadata);
+        var resp = await _stub.UpsertDocumentAsync(req);
+        return resp.DocumentId;
+    }
+
+    public async Task DeleteDocumentAsync(string index, string uri)
+        => await _stub.DeleteDocumentAsync(new DeleteDocumentRequest { IndexName = index, Uri = uri });
+
+    public async Task<List<DocumentInfo>> ListDocumentsAsync(string index)
+    {
+        var resp = await _stub.ListDocumentsAsync(new ListDocumentsRequest { IndexName = index });
+        return resp.Documents.ToList();
+    }
+
+    // ── Stats ─────────────────────────────────────────────
+
+    public async Task<GetIndexStatsResponse> GetIndexStatsAsync(string index)
+        => await _stub.GetIndexStatsAsync(new GetIndexStatsRequest { IndexName = index });
+
+    public async Task<GetCatalogStatsResponse> GetCatalogStatsAsync(string index)
+        => await _stub.GetCatalogStatsAsync(new GetCatalogStatsRequest { IndexName = index });
+
+    // ── Lifecycle ─────────────────────────────────────────
+
+    public async Task<HealthcheckResponse> HealthcheckAsync()
+        => await _stub.HealthcheckAsync(new HealthcheckRequest());
+
+    public async Task ShutdownAsync()
+        => await _stub.ShutdownAsync(new ShutdownRequest());
+
+    // ── Helpers ───────────────────────────────────────────
+
+    private static void SetMetadata(
+        Google.Protobuf.Collections.MapField<string, MetadataValue> protoMap,
+        Dictionary<string, object> metadata)
+    {
+        foreach (var (key, value) in metadata)
+        {
+            protoMap[key] = value switch
+            {
+                bool b => new MetadataValue { BoolValue = b },
+                int i => new MetadataValue { NumberValue = i },
+                long l => new MetadataValue { NumberValue = l },
+                float f => new MetadataValue { NumberValue = f },
+                double d => new MetadataValue { NumberValue = d },
+                _ => new MetadataValue { StringValue = value?.ToString() ?? "" },
+            };
+        }
+    }
+}

package/lib/templates/templates/go/README.md

@@ -0,0 +1,71 @@
+# Vectra Go Client
+
+Thin idiomatic Go wrapper over the Vectra gRPC service.
+
+## Prerequisites
+
+- Go 1.21+
+- `protoc` (Protocol Buffers compiler) — install via your package manager
+
+```bash
+go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
+go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
+```
+
+## Generate gRPC stubs
+
+```bash
+protoc --go_out=. --go-grpc_out=. vectra_service.proto
+```
+
+This produces `vectra_service.pb.go` and `vectra_service_grpc.pb.go` in the `vectra_service/` directory.
+
+## Setup
+
+1. Update the import path in `vectra_client.go` to match your module (replace `your_module/vectra_service`).
+2. Run `go mod init` if you haven't already, then `go mod tidy` to fetch dependencies.
+
+## Usage
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+
+    vectra "your_module/vectra" // adjust import path
+)
+
+func main() {
+    client, err := vectra.NewClient("127.0.0.1:50051")
+    if err != nil {
+        log.Fatal(err)
+    }
+    defer client.Close()
+
+    ctx := context.Background()
+
+    // Create a document index
+    err = client.CreateIndex(ctx, "my-index", "json", true)
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    // Add a document
+    _, err = client.UpsertDocument(ctx, "my-index", "doc1.txt", "Hello world...", "", nil)
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    // Query
+    results, err := client.QueryDocuments(ctx, "my-index", "hello", nil)
+    if err != nil {
+        log.Fatal(err)
+    }
+    for _, doc := range results {
+        fmt.Printf("%s (score: %.3f)\n", doc.Uri, doc.Score)
+    }
+}
+```

package/lib/templates/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/lib/templates/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())));
+        }
+    }
+}
+```