@ductape/sdk 0.1.8 → 0.1.9

package/dist/vector/vector-database.service.d.ts

@@ -0,0 +1,511 @@
+/**
+ * VectorDatabaseService - Product-level Vector Database Management
+ *
+ * This service provides a unified interface for managing vector database configurations
+ * at the product level and executing vector operations.
+ *
+ * Access via: ductape.vector
+ *
+ * @example
+ * ```typescript
+ * // Create a vector database configuration
+ * await ductape.vector.create({
+ *   product: 'my-product',
+ *   tag: 'embeddings',
+ *   name: 'Document Embeddings',
+ *   type: VectorDBType.PINECONE,
+ *   dimensions: 1536,
+ *   metric: DistanceMetric.COSINE,
+ *   envs: [
+ *     {
+ *       slug: 'prd',
+ *       apiKey: 'pk-xxx',
+ *       endpoint: 'https://my-index.svc.pinecone.io',
+ *       index: 'my-index',
+ *     },
+ *   ],
+ * });
+ *
+ * // Query vectors
+ * const results = await ductape.vector.query({
+ *   product: 'my-product',
+ *   env: 'prd',
+ *   tag: 'embeddings',
+ *   vector: [...],
+ *   topK: 10,
+ * });
+ *
+ * // Upsert vectors
+ * await ductape.vector.upsert({
+ *   product: 'my-product',
+ *   env: 'prd',
+ *   tag: 'embeddings',
+ *   vectors: [
+ *     { id: 'doc1', values: [...], metadata: { title: 'Hello' } },
+ *   ],
+ * });
+ * ```
+ */
+import { IProductVector } from '../types/productsBuilder.types';
+import type { Redis as IORedisClient } from 'ioredis';
+import { VectorService, VectorDBType, DistanceMetric, IQueryVectorsOptions, IQueryVectorsResult, IUpsertVectorsOptions, IUpsertVectorsResult, IFetchVectorsOptions, IFetchVectorsResult, IDeleteVectorsOptions, IDeleteVectorsResult, IListNamespacesResult, IVectorIndexInfo, IVectorIndexStats } from './index';
+import { VectorActionManager } from './actions/action-manager';
+import { IVectorMetadataSchema } from './utils';
+/**
+ * Configuration for VectorDatabaseService
+ */
+export interface IVectorDatabaseServiceConfig {
+    workspace_id: string;
+    public_key: string;
+    user_id: string;
+    token: string;
+    env_type: string;
+    /** Optional Redis client for caching */
+    redis_client?: IORedisClient;
+    default_product?: string;
+    default_env?: string;
+}
+/**
+ * Options for creating a vector database configuration
+ */
+export interface ICreateVectorDbOptions {
+    /** Product tag */
+    product: string;
+    /** Unique tag for this vector config */
+    tag: string;
+    /** Human-readable name */
+    name: string;
+    /** Description */
+    description?: string;
+    /** Vector database type */
+    type: VectorDBType;
+    /** Vector dimensions */
+    dimensions: number;
+    /** Distance metric */
+    metric?: DistanceMetric;
+    /** Environment configurations */
+    envs: IVectorDbEnvConfig[];
+}
+/**
+ * Environment-specific vector configuration
+ */
+export interface IVectorDbEnvConfig {
+    /** Environment slug */
+    slug: string;
+    /** API key (will be encrypted) */
+    apiKey?: string;
+    /** API endpoint */
+    endpoint?: string;
+    /** Index/collection name */
+    index?: string;
+    /** Cloud region */
+    region?: string;
+    /** Default namespace */
+    namespace?: string;
+    /** Additional options */
+    options?: Record<string, unknown>;
+}
+/**
+ * Options for updating a vector database configuration
+ */
+export interface IUpdateVectorDbOptions {
+    /** Product tag */
+    product: string;
+    /** Vector config tag */
+    tag: string;
+    /** Updated name */
+    name?: string;
+    /** Updated description */
+    description?: string;
+    /** Updated dimensions */
+    dimensions?: number;
+    /** Updated metric */
+    metric?: DistanceMetric;
+    /** Updated environment configurations */
+    envs?: Partial<IVectorDbEnvConfig>[];
+}
+/**
+ * Options for fetching vector configurations
+ */
+export interface IFetchVectorOptions {
+    /** Product tag */
+    product: string;
+    /** Vector config tag (optional - fetch all if not provided) */
+    tag?: string;
+}
+/**
+ * Options for deleting a vector configuration
+ */
+export interface IDeleteVectorConfigOptions {
+    /** Product tag */
+    product: string;
+    /** Vector config tag */
+    tag: string;
+}
+/**
+ * Options for vector query operation
+ */
+export interface IProductVectorQueryOptions extends Omit<IQueryVectorsOptions, 'vector'> {
+    /** Product tag */
+    product: string;
+    /** Environment slug */
+    env: string;
+    /** Vector config tag */
+    tag: string;
+    /** Query vector */
+    vector: number[];
+    /** Cache tag for result caching */
+    cache?: string;
+}
+/**
+ * Options for vector upsert operation
+ */
+export interface IProductVectorUpsertOptions extends IUpsertVectorsOptions {
+    /** Product tag */
+    product: string;
+    /** Environment slug */
+    env: string;
+    /** Vector config tag */
+    tag: string;
+    /** Session token for authentication and logging */
+    session?: string;
+}
+/**
+ * Options for vector fetch operation
+ */
+export interface IProductVectorFetchOptions extends IFetchVectorsOptions {
+    /** Product tag */
+    product: string;
+    /** Environment slug */
+    env: string;
+    /** Vector config tag */
+    vector: string;
+    /** Cache tag for result caching */
+    cache?: string;
+}
+/**
+ * Options for vector delete operation
+ */
+export interface IProductVectorDeleteOptions extends IDeleteVectorsOptions {
+    /** Product tag */
+    product: string;
+    /** Environment slug */
+    env: string;
+    /** Vector config tag */
+    tag: string;
+}
+export interface IVectorSchemaSnapshotOptions {
+    product: string;
+    env: string;
+    tag: string;
+    namespace?: string;
+    sampleSize?: number;
+    includeNamespaces?: boolean;
+}
+export interface IVectorSchemaSnapshot {
+    vectorTag: string;
+    env: string;
+    index: IVectorIndexInfo;
+    stats: IVectorIndexStats;
+    namespaces?: IListNamespacesResult['namespaces'];
+    metadataSchema: IVectorMetadataSchema;
+    generatedAt: string;
+}
+/**
+ * VectorDatabaseService
+ *
+ * Provides unified access to vector database management and operations.
+ */
+export declare class VectorDatabaseService {
+    private config;
+    private runtimeDefaults;
+    /** Workspace private key for log encryption. Stored at init to avoid config type narrowing. */
+    private _workspacePrivateKey;
+    private productBuilders;
+    private vectorServices;
+    /** CacheManager for two-tier caching (Redis + remote) */
+    private cacheManager;
+    /** Private keys cache for products (keyed by product tag) */
+    private privateKeys;
+    /** LogService instance for logging operations */
+    private logService;
+    /** Current product ID for logging */
+    private productId;
+    /** Vector Action Manager for managing reusable vector actions */
+    actions: VectorActionManager;
+    constructor(config: IVectorDatabaseServiceConfig & {
+        private_key: string;
+        access_key: string;
+    });
+    /**
+     * Update auth configuration (called after Ductape auth)
+     */
+    updateConfig(updates: Partial<IVectorDatabaseServiceConfig>): void;
+    private mergeVectorConnectOptions;
+    private createProductBuilder;
+    private getProductBuilder;
+    /**
+     * Initialize logging service
+     * Re-creates the service if productId has changed
+     */
+    private initializeLogService;
+    private getVectorServiceKey;
+    private getVectorService;
+    /**
+     * Disconnect any existing connection to this vector from the SDK (shared registry and this instance) before creating a fresh one.
+     */
+    private disconnectExistingForResource;
+    private createAndRegisterVectorShared;
+    private createVectorServiceAndCache;
+    /**
+     * Connect to a vector database
+     *
+     * @example
+     * ```typescript
+     * await ductape.vector.connect({
+     *   product: 'my-product',
+     *   env: 'prd',
+     *   tag: 'embeddings',
+     * });
+     * ```
+     */
+    connect(options: {
+        product: string;
+        env: string;
+        vector: string;
+    }): Promise<VectorService>;
+    /**
+     * Disconnect from a specific vector database
+     */
+    disconnect(options: {
+        product: string;
+        env: string;
+        vector: string;
+    }): Promise<void>;
+    /**
+     * Create a new vector database configuration
+     *
+     * @example
+     * ```typescript
+     * await ductape.vector.create({
+     *   product: 'my-product',
+     *   tag: 'embeddings',
+     *   name: 'Document Embeddings',
+     *   type: VectorDBType.PINECONE,
+     *   dimensions: 1536,
+     *   metric: DistanceMetric.COSINE,
+     *   envs: [
+     *     {
+     *       slug: 'prd',
+     *       apiKey: 'pk-xxx',
+     *       endpoint: 'https://my-index.svc.pinecone.io',
+     *       index: 'my-index',
+     *     },
+     *   ],
+     * });
+     * ```
+     */
+    create(options: ICreateVectorDbOptions): Promise<void>;
+    /**
+     * Update an existing vector database configuration
+     *
+     * @example
+     * ```typescript
+     * await ductape.vector.update({
+     *   product: 'my-product',
+     *   tag: 'embeddings',
+     *   name: 'Updated Embeddings',
+     *   envs: [
+     *     {
+     *       slug: 'prd',
+     *       apiKey: 'new-api-key',
+     *     },
+     *   ],
+     * });
+     * ```
+     */
+    update(options: IUpdateVectorDbOptions): Promise<void>;
+    /**
+     * Fetch a vector database configuration
+     *
+     * @example
+     * ```typescript
+     * const config = await ductape.vector.fetch({
+     *   product: 'my-product',
+     *   tag: 'embeddings',
+     * });
+     * ```
+     */
+    fetch(options: IFetchVectorOptions): Promise<IProductVector | null>;
+    /**
+     * Fetch all vector database configurations for a product
+     *
+     * @example
+     * ```typescript
+     * const configs = await ductape.vector.fetchAll({
+     *   product: 'my-product',
+     * });
+     * ```
+     */
+    fetchAll(options: {
+        product: string;
+    }): Promise<IProductVector[]>;
+    /**
+     * Delete a vector database configuration
+     *
+     * @example
+     * ```typescript
+     * await ductape.vector.delete({
+     *   product: 'my-product',
+     *   tag: 'embeddings',
+     * });
+     * ```
+     */
+    delete(options: IDeleteVectorConfigOptions): Promise<void>;
+    /**
+     * Query vectors by similarity
+     *
+     * @example
+     * ```typescript
+     * const results = await ductape.vector.query({
+     *   product: 'my-product',
+     *   env: 'prd',
+     *   tag: 'embeddings',
+     *   vector: embeddingVector,
+     *   topK: 10,
+     *   filter: { field: 'category', operator: '$eq', value: 'tech' },
+     * });
+     * ```
+     */
+    query(options: IProductVectorQueryOptions): Promise<IQueryVectorsResult>;
+    /**
+     * Upsert vectors (insert or update)
+     *
+     * @example
+     * ```typescript
+     * await ductape.vector.upsert({
+     *   product: 'my-product',
+     *   env: 'prd',
+     *   tag: 'embeddings',
+     *   vectors: [
+     *     { id: 'doc1', values: [...], metadata: { title: 'Hello' } },
+     *     { id: 'doc2', values: [...], metadata: { title: 'World' } },
+     *   ],
+     * });
+     * ```
+     */
+    upsert(options: IProductVectorUpsertOptions): Promise<IUpsertVectorsResult>;
+    /**
+     * Fetch vectors by IDs
+     *
+     * @example
+     * ```typescript
+     * const vectors = await ductape.vector.fetchVectors({
+     *   product: 'my-product',
+     *   env: 'prd',
+     *   tag: 'embeddings',
+     *   ids: ['doc1', 'doc2'],
+     * });
+     * ```
+     */
+    fetchVectors(options: IProductVectorFetchOptions): Promise<IFetchVectorsResult>;
+    /**
+     * Delete vectors
+     *
+     * @example
+     * ```typescript
+     * await ductape.vector.deleteVectors({
+     *   product: 'my-product',
+     *   env: 'prd',
+     *   tag: 'embeddings',
+     *   ids: ['doc1', 'doc2'],
+     * });
+     * ```
+     */
+    deleteVectors(options: IProductVectorDeleteOptions): Promise<IDeleteVectorsResult>;
+    /**
+     * List all namespaces/collections in the vector database
+     *
+     * @example
+     * ```typescript
+     * const result = await ductape.vector.listNamespaces({
+     *   product: 'my-product',
+     *   env: 'prd',
+     *   tag: 'embeddings',
+     * });
+     * console.log(result.namespaces);
+     * ```
+     */
+    listNamespaces(options: {
+        product: string;
+        env: string;
+        tag: string;
+    }): Promise<IListNamespacesResult>;
+    /**
+     * Get statistics about the vector index
+     *
+     * @example
+     * ```typescript
+     * const stats = await ductape.vector.getStats({
+     *   product: 'my-product',
+     *   env: 'prd',
+     *   tag: 'embeddings',
+     * });
+     * console.log(stats.vectorCount, stats.dimensions);
+     * ```
+     */
+    getStats(options: {
+        product: string;
+        env: string;
+        tag: string;
+    }): Promise<IVectorIndexStats>;
+    /**
+     * Describe the vector index configuration
+     *
+     * @example
+     * ```typescript
+     * const info = await ductape.vector.describeIndex({
+     *   product: 'my-product',
+     *   env: 'prd',
+     *   tag: 'embeddings',
+     * });
+     * console.log(info.name, info.dimensions, info.metric);
+     * ```
+     */
+    describeIndex(options: {
+        product: string;
+        env: string;
+        tag: string;
+    }): Promise<IVectorIndexInfo>;
+    /**
+     * Return a normalized schema snapshot for a vector config, including inferred metadata schema.
+     * This allows payload/metadata generators to build accurate filters and payload fields.
+     */
+    getSchemaSnapshot(options: IVectorSchemaSnapshotOptions): Promise<IVectorSchemaSnapshot>;
+    /**
+     * Get the raw VectorService for advanced operations
+     *
+     * @example
+     * ```typescript
+     * const service = await ductape.vector.getService({
+     *   product: 'my-product',
+     *   env: 'prd',
+     *   tag: 'embeddings',
+     * });
+     *
+     * // Use VectorService directly
+     * const stats = await service.getStats();
+     * const namespaces = await service.listNamespaces();
+     * ```
+     */
+    getService(options: {
+        product: string;
+        env: string;
+        tag: string;
+    }): Promise<VectorService>;
+    /**
+     * Disconnect all cached vector services
+     */
+    disconnectAll(): Promise<void>;
+}
+export default VectorDatabaseService;