vectra 0.12.2 → 0.14.0

package/src/storage/VirtualFileStorage.ts

@@ -0,0 +1,169 @@
+import { FileDetails, FileStorage, ListFilesFilter } from "./FileStorage";
+import { pathUtils as path } from '../utils/pathUtils';
+import { FileStorageUtilities } from "./FileStorageUtilities";
+
+/**
+ * An in-memory `FileStorage` implementation.
+ */
+export class VirtualFileStorage implements FileStorage {
+  private readonly _entries: Map<string, StoredFile> = new Map();
+
+  // Normalize keys consistently across all operations:
+  // - path.normalize to resolve dot segments
+  // - remove trailing separator (except for root) so 'a' and 'a/' match
+  // - preserve '' to represent the root namespace in this storage
+  private normalizeKey(key: string): string {
+    if (key.length === 0) return "";
+    let normalized = path.normalize(key);
+    if (normalized.endsWith(path.sep) && normalized !== path.sep) {
+      normalized = normalized.slice(0, -1);
+    }
+    return normalized;
+  }
+
+  public async createFile(filePath: string, content: Buffer | string): Promise<void> {
+    const key = this.normalizeKey(filePath);
+    if (this._entries.has(key)) {
+      throw new Error(`File already exists: ${key}`);
+    }
+    const buffer = typeof content === "string" ? Buffer.from(content, "utf8") : content;
+    this._entries.set(key, {
+      details: {
+        name: path.basename(key),
+        path: key,
+        isFolder: false,
+        fileType: FileStorageUtilities.getFileType(key),
+      },
+      // Clone to avoid external mutation of stored buffers (and keep Buffer type)
+      content: Buffer.from(buffer),
+    });
+  }
+
+  public async createFolder(folderPath: string): Promise<void> {
+    const key = this.normalizeKey(folderPath);
+    const existing = this._entries.get(key);
+    if (existing) {
+      if (!existing.details.isFolder) {
+        throw new Error(`Cannot create folder: ${key} is a file`);
+      }
+      // Idempotent if the folder already exists
+      return;
+    }
+    this._entries.set(key, {
+      details: {
+        name: path.basename(key),
+        path: key,
+        isFolder: true,
+        fileType: undefined,
+      },
+    });
+  }
+
+  public async deleteFile(filePath: string): Promise<void> {
+    const key = this.normalizeKey(filePath);
+    const existing = this._entries.get(key);
+    if (!existing) {
+      // no-op if not exists
+      return;
+    }
+    if (existing.details.isFolder) {
+      throw new Error(`Cannot delete file: ${key} is a folder`);
+    }
+    this._entries.delete(key);
+  }
+
+  public async deleteFolder(folderPath: string): Promise<void> {
+    const key = this.normalizeKey(folderPath);
+    const existing = this._entries.get(key);
+    if (!existing) {
+      // no-op if not exists
+      return;
+    }
+    if (!existing.details.isFolder) {
+      throw new Error(`Cannot delete folder: ${key} is a file`);
+    }
+    // Note: does not cascade delete children per current implementation
+    this._entries.delete(key);
+  }
+
+  public async getDetails(fileOrFolderPath: string): Promise<FileDetails> {
+    const key = this.normalizeKey(fileOrFolderPath);
+    const existing = this._entries.get(key);
+    if (!existing) {
+      throw new Error(`Path not found: ${key}`);
+    }
+    // Return a shallow copy to avoid external mutation of returned metadata
+    return { ...existing.details };
+  }
+
+  public async listFiles(
+    folderPath: string,
+    filter: ListFilesFilter = "all"
+  ): Promise<FileDetails[]> {
+    const baseFolder = this.normalizeKey(folderPath);
+
+    const results: FileDetails[] = [];
+    for (const [, entry] of this._entries) {
+      const parts = entry.details.path.split(path.sep);
+      const parentFolder =
+        parts.length > 1 ? parts.slice(0, parts.length - 1).join(path.sep) : "";
+      if (parentFolder === baseFolder) {
+        if (
+          filter === "all" ||
+          (filter === "files" && !entry.details.isFolder) ||
+          (filter === "folders" && entry.details.isFolder)
+        ) {
+          // Return a shallow copy to avoid external mutation of returned metadata
+          results.push({ ...entry.details });
+        }
+      }
+    }
+    return results;
+  }
+
+  public async pathExists(fileOrFolderPath: string): Promise<boolean> {
+    const key = this.normalizeKey(fileOrFolderPath);
+    return this._entries.has(key);
+  }
+
+  public async readFile(filePath: string): Promise<Buffer> {
+    const key = this.normalizeKey(filePath);
+    const existing = this._entries.get(key);
+    if (!existing) {
+      throw new Error(`File not found: ${key}`);
+    }
+    if (existing.details.isFolder) {
+      throw new Error(`Cannot read file: ${key} is a folder`);
+    }
+    // Return a copy of the buffer to protect internal buffer from external mutation; fall back to empty buffer
+    const content = existing.content ?? Buffer.from("", "utf8");
+    return Buffer.from(content);
+  }
+
+  public async upsertFile(filePath: string, content: Buffer | string): Promise<void> {
+    const key = this.normalizeKey(filePath);
+    const existing = this._entries.get(key);
+    if (existing && existing.details.isFolder) {
+      throw new Error(`Cannot write file: ${key} is a folder`);
+    }
+    const buffer = typeof content === "string" ? Buffer.from(content, "utf8") : content;
+    this._entries.set(key, {
+      details: {
+        name: path.basename(key),
+        path: key,
+        isFolder: false,
+        fileType: FileStorageUtilities.getFileType(key),
+      },
+      // Clone to avoid external mutation of stored buffers (and keep Buffer type)
+      content: Buffer.from(buffer),
+    });
+  }
+}
+
+/**
+ * @private
+ */
+interface StoredFile {
+  details: FileDetails;
+  content?: Buffer;
+}

package/src/storage/index.ts

@@ -0,0 +1,5 @@
+export * from "./FileStorage";
+export * from "./FileStorageUtilities";
+export * from "./FileType";
+export * from "./LocalFileStorage";
+export * from "./VirtualFileStorage";

package/src/templates/csharp/README.md

@@ -0,0 +1,48 @@
+# Vectra C# Client
+
+Thin idiomatic C# wrapper over the Vectra gRPC service.
+
+## Prerequisites
+
+Add these NuGet packages to your project:
+
+```bash
+dotnet add package Grpc.Net.Client
+dotnet add package Google.Protobuf
+dotnet add package Grpc.Tools
+```
+
+## Generate gRPC stubs
+
+Add to your `.csproj`:
+
+```xml
+<ItemGroup>
+  <Protobuf Include="vectra_service.proto" GrpcServices="Client" />
+</ItemGroup>
+```
+
+The stubs are generated automatically at build time by `Grpc.Tools`.
+
+## Usage
+
+```csharp
+using Vectra.Client;
+
+using var client = new VectraClient();
+
+// Create a document index
+await client.CreateIndexAsync("my-index", isDocumentIndex: true);
+
+// Add a document
+await client.UpsertDocumentAsync("my-index", "doc1.txt", "Hello world...");
+
+// Query
+var results = await client.QueryDocumentsAsync("my-index", "hello");
+foreach (var doc in results)
+{
+    Console.WriteLine($"{doc.Uri} (score: {doc.Score:F3})");
+    foreach (var chunk in doc.Chunks)
+        Console.WriteLine($"  {chunk.Text[..Math.Min(80, chunk.Text.Length)]}...");
+}
+```

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