vectra 0.12.2 → 0.14.0

package/lib/templates/templates/typescript/VectraClient.ts

@@ -0,0 +1,374 @@
+/**
+ * Vectra gRPC client — thin idiomatic wrapper over generated stubs.
+ *
+ * Usage:
+ *   import { VectraClient } from './VectraClient';
+ *
+ *   const client = new VectraClient();
+ *   const results = await client.queryDocuments('my-index', 'search query');
+ *   client.close();
+ *
+ * Generate stubs first:
+ *   npm install @grpc/grpc-js @grpc/proto-loader
+ *   // Proto is loaded dynamically — no separate codegen step required.
+ */
+
+import * as grpc from '@grpc/grpc-js';
+import * as protoLoader from '@grpc/proto-loader';
+import * as path from 'path';
+
+// Load proto definition dynamically
+const PROTO_PATH = path.join(__dirname, 'vectra_service.proto');
+const packageDefinition = protoLoader.loadSync(PROTO_PATH, {
+    keepCase: false,
+    longs: Number,
+    enums: String,
+    defaults: true,
+    oneofs: true,
+});
+const protoDescriptor = grpc.loadPackageDefinition(packageDefinition) as any;
+const vectra = protoDescriptor.vectra;
+
+// ── Types ────────────────────────────────────────────────
+
+export interface MetadataValue {
+    stringValue?: string;
+    numberValue?: number;
+    boolValue?: boolean;
+}
+
+export interface ItemResult {
+    id: string;
+    metadata: Record<string, string | number | boolean>;
+    vector: number[];
+    norm: number;
+    score: number;
+}
+
+export interface DocumentResult {
+    uri: string;
+    documentId: string;
+    score: number;
+    chunks: Array<{ text: string; score: number; tokenCount: number }>;
+}
+
+export interface IndexInfo {
+    name: string;
+    format: string;
+    isDocumentIndex: boolean;
+}
+
+export interface IndexStats {
+    version: number;
+    format: string;
+    itemCount: number;
+    metadataConfigCount: number;
+}
+
+export interface CatalogStats {
+    version: number;
+    documentCount: number;
+    chunkCount: number;
+    metadataCounts: Record<string, number>;
+}
+
+export interface HealthcheckResult {
+    status: string;
+    uptimeSeconds: number;
+    loadedIndexes: string[];
+}
+
+export interface QueryDocumentsOptions {
+    maxDocuments?: number;
+    maxChunks?: number;
+    filter?: Record<string, any>;
+    useBm25?: boolean;
+}
+
+export interface QueryItemsOptions {
+    text?: string;
+    vector?: number[];
+    topK?: number;
+    filter?: Record<string, any>;
+}
+
+// ── Client ───────────────────────────────────────────────
+
+export class VectraClient {
+    private readonly _client: any;
+
+    constructor(host: string = '127.0.0.1', port: number = 50051) {
+        this._client = new vectra.VectraService(
+            `${host}:${port}`,
+            grpc.credentials.createInsecure()
+        );
+    }
+
+    public close(): void {
+        this._client.close();
+    }
+
+    // ── Index Management ─────────────────────────────────
+
+    public createIndex(
+        name: string,
+        options?: {
+            format?: string;
+            isDocumentIndex?: boolean;
+            chunkSize?: number;
+            chunkOverlap?: number;
+        }
+    ): Promise<void> {
+        const req: any = { indexName: name, format: options?.format ?? 'json' };
+        if (options?.isDocumentIndex) {
+            req.isDocumentIndex = true;
+            req.documentConfig = {
+                version: 1,
+                chunkSize: options.chunkSize ?? 512,
+                chunkOverlap: options.chunkOverlap ?? 0,
+            };
+        }
+        return this._unary('createIndex', req);
+    }
+
+    public deleteIndex(name: string): Promise<void> {
+        return this._unary('deleteIndex', { indexName: name });
+    }
+
+    public async listIndexes(): Promise<IndexInfo[]> {
+        const resp = await this._unary('listIndexes', {});
+        return (resp.indexes ?? []).map((idx: any) => ({
+            name: idx.name,
+            format: idx.format,
+            isDocumentIndex: idx.isDocumentIndex,
+        }));
+    }
+
+    // ── Item Operations ──────────────────────────────────
+
+    public async insertItem(
+        index: string,
+        options: {
+            text?: string;
+            vector?: number[];
+            metadata?: Record<string, string | number | boolean>;
+            id?: string;
+        }
+    ): Promise<string> {
+        const req: any = {
+            indexName: index,
+            text: options.text ?? '',
+            id: options.id ?? '',
+        };
+        if (options.vector) req.vector = options.vector;
+        if (options.metadata) req.metadata = toProtoMetadata(options.metadata);
+        const resp = await this._unary('insertItem', req);
+        return resp.id;
+    }
+
+    public async upsertItem(
+        index: string,
+        id: string,
+        options: {
+            text?: string;
+            vector?: number[];
+            metadata?: Record<string, string | number | boolean>;
+        }
+    ): Promise<string> {
+        const req: any = {
+            indexName: index,
+            id,
+            text: options.text ?? '',
+        };
+        if (options.vector) req.vector = options.vector;
+        if (options.metadata) req.metadata = toProtoMetadata(options.metadata);
+        const resp = await this._unary('upsertItem', req);
+        return resp.id;
+    }
+
+    public async getItem(index: string, id: string): Promise<ItemResult | null> {
+        const resp = await this._unary('getItem', { indexName: index, id });
+        return resp.item ? itemToResult(resp.item) : null;
+    }
+
+    public deleteItem(index: string, id: string): Promise<void> {
+        return this._unary('deleteItem', { indexName: index, id });
+    }
+
+    public async listItems(
+        index: string,
+        filter?: Record<string, any>
+    ): Promise<ItemResult[]> {
+        const req: any = { indexName: index };
+        if (filter) req.filter = { filterJson: JSON.stringify(filter) };
+        const resp = await this._unary('listItems', req);
+        return (resp.items ?? []).map(itemToResult);
+    }
+
+    // ── Query ────────────────────────────────────────────
+
+    public async queryItems(
+        index: string,
+        options: QueryItemsOptions
+    ): Promise<ItemResult[]> {
+        const req: any = {
+            indexName: index,
+            text: options.text ?? '',
+            topK: options.topK ?? 10,
+        };
+        if (options.vector) req.vector = options.vector;
+        if (options.filter) req.filter = { filterJson: JSON.stringify(options.filter) };
+        const resp = await this._unary('queryItems', req);
+        return (resp.results ?? []).map(itemToResult);
+    }
+
+    public async queryDocuments(
+        index: string,
+        query: string,
+        options?: QueryDocumentsOptions
+    ): Promise<DocumentResult[]> {
+        const req: any = {
+            indexName: index,
+            query,
+            maxDocuments: options?.maxDocuments ?? 10,
+            maxChunks: options?.maxChunks ?? 50,
+            useBm25: options?.useBm25 ?? false,
+        };
+        if (options?.filter) req.filter = { filterJson: JSON.stringify(options.filter) };
+        const resp = await this._unary('queryDocuments', req);
+        return (resp.results ?? []).map((doc: any) => ({
+            uri: doc.uri,
+            documentId: doc.documentId,
+            score: doc.score,
+            chunks: (doc.chunks ?? []).map((c: any) => ({
+                text: c.text,
+                score: c.score,
+                tokenCount: c.tokenCount,
+            })),
+        }));
+    }
+
+    // ── Document Operations ──────────────────────────────
+
+    public async upsertDocument(
+        index: string,
+        uri: string,
+        text: string,
+        options?: {
+            docType?: string;
+            metadata?: Record<string, string | number | boolean>;
+        }
+    ): Promise<string> {
+        const req: any = {
+            indexName: index,
+            uri,
+            text,
+            docType: options?.docType ?? '',
+        };
+        if (options?.metadata) req.metadata = toProtoMetadata(options.metadata);
+        const resp = await this._unary('upsertDocument', req);
+        return resp.documentId;
+    }
+
+    public deleteDocument(index: string, uri: string): Promise<void> {
+        return this._unary('deleteDocument', { indexName: index, uri });
+    }
+
+    public async listDocuments(
+        index: string
+    ): Promise<Array<{ uri: string; documentId: string }>> {
+        const resp = await this._unary('listDocuments', { indexName: index });
+        return (resp.documents ?? []).map((d: any) => ({
+            uri: d.uri,
+            documentId: d.documentId,
+        }));
+    }
+
+    // ── Stats ────────────────────────────────────────────
+
+    public async getIndexStats(index: string): Promise<IndexStats> {
+        const resp = await this._unary('getIndexStats', { indexName: index });
+        return {
+            version: resp.version,
+            format: resp.format,
+            itemCount: resp.itemCount,
+            metadataConfigCount: resp.metadataConfigCount,
+        };
+    }
+
+    public async getCatalogStats(index: string): Promise<CatalogStats> {
+        const resp = await this._unary('getCatalogStats', { indexName: index });
+        return {
+            version: resp.version,
+            documentCount: resp.documentCount,
+            chunkCount: resp.chunkCount,
+            metadataCounts: resp.metadataCounts ?? {},
+        };
+    }
+
+    // ── Lifecycle ────────────────────────────────────────
+
+    public async healthcheck(): Promise<HealthcheckResult> {
+        const resp = await this._unary('healthcheck', {});
+        return {
+            status: resp.status,
+            uptimeSeconds: resp.uptimeSeconds,
+            loadedIndexes: resp.loadedIndexes ?? [],
+        };
+    }
+
+    public shutdown(): Promise<void> {
+        return this._unary('shutdown', {});
+    }
+
+    // ── Internals ────────────────────────────────────────
+
+    private _unary(method: string, request: any): Promise<any> {
+        return new Promise((resolve, reject) => {
+            this._client[method](request, (err: grpc.ServiceError | null, response: any) => {
+                if (err) reject(err);
+                else resolve(response);
+            });
+        });
+    }
+}
+
+// ── Helpers ──────────────────────────────────────────────
+
+function toProtoMetadata(
+    metadata: Record<string, string | number | boolean>
+): Record<string, MetadataValue> {
+    const result: Record<string, MetadataValue> = {};
+    for (const [key, value] of Object.entries(metadata)) {
+        if (typeof value === 'boolean') {
+            result[key] = { boolValue: value };
+        } else if (typeof value === 'number') {
+            result[key] = { numberValue: value };
+        } else {
+            result[key] = { stringValue: String(value) };
+        }
+    }
+    return result;
+}
+
+function itemToResult(item: any): ItemResult {
+    const metadata: Record<string, string | number | boolean> = {};
+    if (item.metadata) {
+        for (const [key, val] of Object.entries<any>(item.metadata)) {
+            if (val.stringValue !== undefined && val.stringValue !== '') {
+                metadata[key] = val.stringValue;
+            } else if (val.numberValue !== undefined && val.numberValue !== 0) {
+                metadata[key] = val.numberValue;
+            } else if (val.boolValue !== undefined) {
+                metadata[key] = val.boolValue;
+            }
+        }
+    }
+    return {
+        id: item.id,
+        metadata,
+        vector: item.vector ?? [],
+        norm: item.norm,
+        score: item.score,
+    };
+}

package/lib/templates/typescript/VectraClient.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Vectra gRPC client — thin idiomatic wrapper over generated stubs.
+ *
+ * Usage:
+ *   import { VectraClient } from './VectraClient';
+ *
+ *   const client = new VectraClient();
+ *   const results = await client.queryDocuments('my-index', 'search query');
+ *   client.close();
+ *
+ * Generate stubs first:
+ *   npm install @grpc/grpc-js @grpc/proto-loader
+ *   // Proto is loaded dynamically — no separate codegen step required.
+ */
+export interface MetadataValue {
+    stringValue?: string;
+    numberValue?: number;
+    boolValue?: boolean;
+}
+export interface ItemResult {
+    id: string;
+    metadata: Record<string, string | number | boolean>;
+    vector: number[];
+    norm: number;
+    score: number;
+}
+export interface DocumentResult {
+    uri: string;
+    documentId: string;
+    score: number;
+    chunks: Array<{
+        text: string;
+        score: number;
+        tokenCount: number;
+    }>;
+}
+export interface IndexInfo {
+    name: string;
+    format: string;
+    isDocumentIndex: boolean;
+}
+export interface IndexStats {
+    version: number;
+    format: string;
+    itemCount: number;
+    metadataConfigCount: number;
+}
+export interface CatalogStats {
+    version: number;
+    documentCount: number;
+    chunkCount: number;
+    metadataCounts: Record<string, number>;
+}
+export interface HealthcheckResult {
+    status: string;
+    uptimeSeconds: number;
+    loadedIndexes: string[];
+}
+export interface QueryDocumentsOptions {
+    maxDocuments?: number;
+    maxChunks?: number;
+    filter?: Record<string, any>;
+    useBm25?: boolean;
+}
+export interface QueryItemsOptions {
+    text?: string;
+    vector?: number[];
+    topK?: number;
+    filter?: Record<string, any>;
+}
+export declare class VectraClient {
+    private readonly _client;
+    constructor(host?: string, port?: number);
+    close(): void;
+    createIndex(name: string, options?: {
+        format?: string;
+        isDocumentIndex?: boolean;
+        chunkSize?: number;
+        chunkOverlap?: number;
+    }): Promise<void>;
+    deleteIndex(name: string): Promise<void>;
+    listIndexes(): Promise<IndexInfo[]>;
+    insertItem(index: string, options: {
+        text?: string;
+        vector?: number[];
+        metadata?: Record<string, string | number | boolean>;
+        id?: string;
+    }): Promise<string>;
+    upsertItem(index: string, id: string, options: {
+        text?: string;
+        vector?: number[];
+        metadata?: Record<string, string | number | boolean>;
+    }): Promise<string>;
+    getItem(index: string, id: string): Promise<ItemResult | null>;
+    deleteItem(index: string, id: string): Promise<void>;
+    listItems(index: string, filter?: Record<string, any>): Promise<ItemResult[]>;
+    queryItems(index: string, options: QueryItemsOptions): Promise<ItemResult[]>;
+    queryDocuments(index: string, query: string, options?: QueryDocumentsOptions): Promise<DocumentResult[]>;
+    upsertDocument(index: string, uri: string, text: string, options?: {
+        docType?: string;
+        metadata?: Record<string, string | number | boolean>;
+    }): Promise<string>;
+    deleteDocument(index: string, uri: string): Promise<void>;
+    listDocuments(index: string): Promise<Array<{
+        uri: string;
+        documentId: string;
+    }>>;
+    getIndexStats(index: string): Promise<IndexStats>;
+    getCatalogStats(index: string): Promise<CatalogStats>;
+    healthcheck(): Promise<HealthcheckResult>;
+    shutdown(): Promise<void>;
+    private _unary;
+}
+//# sourceMappingURL=VectraClient.d.ts.map

package/lib/templates/typescript/VectraClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VectraClient.d.ts","sourceRoot":"","sources":["../../../src/templates/typescript/VectraClient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAoBH,MAAM,WAAW,aAAa;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,UAAU;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;IACpD,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACtE;AAED,MAAM,WAAW,SAAS;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,UAAU;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,mBAAmB,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,YAAY;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC1C;AAED,MAAM,WAAW,iBAAiB;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,qBAAqB;IAClC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC7B,OAAO,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,iBAAiB;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAChC;AAID,qBAAa,YAAY;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAM;gBAElB,IAAI,GAAE,MAAoB,EAAE,IAAI,GAAE,MAAc;IAOrD,KAAK,IAAI,IAAI;IAMb,WAAW,CACd,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QACN,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,eAAe,CAAC,EAAE,OAAO,CAAC;QAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,YAAY,CAAC,EAAE,MAAM,CAAC;KACzB,GACF,OAAO,CAAC,IAAI,CAAC;IAaT,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlC,WAAW,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;IAWnC,UAAU,CACnB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE;QACL,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;QAClB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;QACrD,EAAE,CAAC,EAAE,MAAM,CAAC;KACf,GACF,OAAO,CAAC,MAAM,CAAC;IAYL,UAAU,CACnB,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,MAAM,EACV,OAAO,EAAE;QACL,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;QAClB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;KACxD,GACF,OAAO,CAAC,MAAM,CAAC;IAYL,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAKpE,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI9C,SAAS,CAClB,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC7B,OAAO,CAAC,UAAU,EAAE,CAAC;IASX,UAAU,CACnB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,iBAAiB,GAC3B,OAAO,CAAC,UAAU,EAAE,CAAC;IAYX,cAAc,CACvB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,qBAAqB,GAChC,OAAO,CAAC,cAAc,EAAE,CAAC;IAwBf,cAAc,CACvB,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QACN,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;KACxD,GACF,OAAO,CAAC,MAAM,CAAC;IAYX,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAInD,aAAa,CACtB,KAAK,EAAE,MAAM,GACd,OAAO,CAAC,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAUzC,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAUjD,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAYrD,WAAW,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAS/C,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAMhC,OAAO,CAAC,MAAM;CAQjB"}