@mastra/core/dist/vector/index.cjs.map

{"version":3,"file":"index.cjs","names":["MastraBase","MastraError","ErrorDomain","ErrorCategory","MastraError","createVectorErrorId","ErrorDomain","ErrorCategory"],"sources":["../../src/vector/vector.ts","../../src/vector/validation.ts"],"sourcesContent":["import type {\n  EmbeddingModel as EmbeddingModelV1,\n  ProviderOptions as ProviderOptionsV1,\n  TelemetrySettings as TelemetrySettingsV1,\n} from '@internal/ai-sdk-v4';\nimport type {\n  EmbeddingModel,\n  TelemetrySettings as TelemetrySettingsV5,\n  ProviderOptions as ProviderOptionsV5,\n} from '@internal/ai-sdk-v5';\n\ntype EmbeddingModelV2<T> = Exclude<EmbeddingModel<T>, string>;\nimport type {\n  EmbeddingModelV3,\n  TelemetrySettings as TelemetrySettingsV6,\n  ProviderOptions as ProviderOptionsV6,\n} from '@internal/ai-v6';\nimport { MastraBase } from '../base';\nimport { MastraError, ErrorDomain, ErrorCategory } from '../error';\nimport type { VectorFilter } from './filter';\nimport type {\n  CreateIndexParams,\n  UpsertVectorParams,\n  QueryVectorParams,\n  IndexStats,\n  QueryResult,\n  UpdateVectorParams,\n  DeleteVectorParams,\n  DeleteVectorsParams,\n  DescribeIndexParams,\n  DeleteIndexParams,\n} from './types';\n\n/** Legacy embedding model (V1) - use embedV1 function */\nexport type MastraLegacyEmbeddingModel<T> = EmbeddingModelV1<T>;\n\n/** Modern embedding model (V2/V3) - use embedV2 for V2 models, embedV3 for V3 models */\nexport type MastraSupportedEmbeddingModel<T> = EmbeddingModelV2<T> | EmbeddingModelV3;\n\n/** All supported embedding model types */\nexport type MastraEmbeddingModel<T> = MastraLegacyEmbeddingModel<T> | MastraSupportedEmbeddingModel<T>;\n\nexport type MastraEmbeddingOptions = {\n  maxRetries?: number;\n\n  headers?: Record<string, string>;\n  /**\n   * Optional telemetry configuration (experimental).\n   */\n  telemetry?: TelemetrySettingsV1 | TelemetrySettingsV5 | TelemetrySettingsV6;\n\n  providerOptions?: ProviderOptionsV1 | ProviderOptionsV5 | ProviderOptionsV6;\n\n  maxParallelCalls?: number;\n};\n\n/** Specification versions for supported (modern) embedding models */\nexport const supportedEmbeddingModelSpecifications = ['v2', 'v3'] as const;\n\n/**\n * Type guard to check if an embedding model is a supported modern version (V2 or V3).\n * Use embedV2 for V2 models, embedV3 for V3 models, and embedV1 for legacy V1 models.\n */\nexport const isSupportedEmbeddingModel = <T>(\n  model: MastraEmbeddingModel<T>,\n): model is MastraSupportedEmbeddingModel<T> => {\n  return supportedEmbeddingModelSpecifications.includes(\n    model.specificationVersion as (typeof supportedEmbeddingModelSpecifications)[number],\n  );\n};\n\nexport abstract class MastraVector<Filter = VectorFilter> extends MastraBase {\n  id: string;\n  disableInit: boolean = false;\n\n  constructor({ id, disableInit }: { id: string; disableInit?: boolean }) {\n    if (!id || typeof id !== 'string' || id.trim() === '') {\n      throw new MastraError({\n        id: 'VECTOR_INVALID_ID',\n        text: 'Vector id must be provided and cannot be empty',\n        domain: ErrorDomain.MASTRA_VECTOR,\n        category: ErrorCategory.USER,\n      });\n    }\n    super({ name: 'MastraVector', component: 'VECTOR' });\n    this.id = id;\n    this.disableInit = disableInit ?? false;\n  }\n\n  get indexSeparator(): string {\n    return '_';\n  }\n\n  abstract query(params: QueryVectorParams<Filter>): Promise<QueryResult[]>;\n  // Adds type checks for positional arguments if used\n  abstract upsert(params: UpsertVectorParams): Promise<string[]>;\n  // Adds type checks for positional arguments if used\n  abstract createIndex(params: CreateIndexParams): Promise<void>;\n\n  abstract listIndexes(): Promise<string[]>;\n\n  abstract describeIndex(params: DescribeIndexParams): Promise<IndexStats>;\n\n  abstract deleteIndex(params: DeleteIndexParams): Promise<void>;\n\n  abstract updateVector(params: UpdateVectorParams<Filter>): Promise<void>;\n\n  abstract deleteVector(params: DeleteVectorParams): Promise<void>;\n\n  /**\n   * Delete multiple vectors by IDs or metadata filter.\n   *\n   * This enables bulk deletion and source-based vector management.\n   * Implementations should throw MastraError with appropriate error code\n   * if the operation is not supported.\n   *\n   * @param params - Parameters including indexName and either ids or filter (mutually exclusive)\n   * @throws {MastraError} If operation is not supported or parameters are invalid\n   *\n   * @example\n   * ```ts\n   * // Delete all chunks from a document\n   * await vectorStore.deleteVectors({\n   *   indexName: 'docs',\n   *   filter: { source_id: 'manual.pdf' }\n   * });\n   *\n   * // Delete multiple vectors by ID\n   * await vectorStore.deleteVectors({\n   *   indexName: 'docs',\n   *   ids: ['vec_1', 'vec_2', 'vec_3']\n   * });\n   *\n   * // Delete old temporary documents\n   * await vectorStore.deleteVectors({\n   *   indexName: 'docs',\n   *   filter: {\n   *     $and: [\n   *       { bucket: 'temp' },\n   *       { indexed_at: { $lt: '2025-01-01' } }\n   *     ]\n   *   }\n   * });\n   * ```\n   */\n  abstract deleteVectors(params: DeleteVectorsParams<Filter>): Promise<void>;\n\n  protected async validateExistingIndex(indexName: string, dimension: number, metric: string) {\n    let info: IndexStats;\n    try {\n      info = await this.describeIndex({ indexName });\n    } catch (infoError) {\n      const mastraError = new MastraError(\n        {\n          id: 'VECTOR_VALIDATE_INDEX_FETCH_FAILED',\n          text: `Index \"${indexName}\" already exists, but failed to fetch index info for dimension check.`,\n          domain: ErrorDomain.MASTRA_VECTOR,\n          category: ErrorCategory.SYSTEM,\n          details: { indexName },\n        },\n        infoError,\n      );\n      this.logger?.trackException(mastraError);\n      throw mastraError;\n    }\n    const existingDim = info?.dimension;\n    const existingMetric = info?.metric;\n    if (existingDim === dimension) {\n      this.logger?.info(\n        `Index \"${indexName}\" already exists with ${existingDim} dimensions and metric ${existingMetric}, skipping creation.`,\n      );\n      if (existingMetric !== metric) {\n        this.logger?.warn(\n          `Attempted to create index with metric \"${metric}\", but index already exists with metric \"${existingMetric}\". To use a different metric, delete and recreate the index.`,\n        );\n      }\n    } else if (info) {\n      const mastraError = new MastraError({\n        id: 'VECTOR_VALIDATE_INDEX_DIMENSION_MISMATCH',\n        text: `Index \"${indexName}\" already exists with ${existingDim} dimensions, but ${dimension} dimensions were requested`,\n        domain: ErrorDomain.MASTRA_VECTOR,\n        category: ErrorCategory.USER,\n        details: { indexName, existingDim, requestedDim: dimension },\n      });\n      this.logger?.trackException(mastraError);\n      throw mastraError;\n    } else {\n      const mastraError = new MastraError({\n        id: 'VECTOR_VALIDATE_INDEX_NO_DIMENSION',\n        text: `Index \"${indexName}\" already exists, but could not retrieve its dimensions for validation.`,\n        domain: ErrorDomain.MASTRA_VECTOR,\n        category: ErrorCategory.SYSTEM,\n        details: { indexName },\n      });\n      this.logger?.trackException(mastraError);\n      throw mastraError;\n    }\n  }\n}\n","/**\n * Shared validation helpers for vector store implementations\n *\n * These helpers provide consistent validation across all vector stores,\n * reducing code duplication and ensuring uniform error handling.\n */\n\nimport { MastraError, ErrorDomain, ErrorCategory } from '../error';\nimport { createVectorErrorId } from '../storage';\n\n/**\n * Validates upsert input parameters\n *\n * @param storeName - Name of the vector store (e.g., 'PG', 'CHROMA')\n * @param vectors - Array of vectors to upsert\n * @param metadata - Optional metadata array\n * @param ids - Optional ids array\n * @throws MastraError if validation fails\n */\nexport function validateUpsertInput(\n  storeName: string,\n  vectors: number[][] | undefined | null,\n  metadata?: Record<string, any>[] | null,\n  ids?: string[] | null,\n): void {\n  // Validate vectors array is not empty\n  if (!vectors || vectors.length === 0) {\n    throw new MastraError({\n      id: createVectorErrorId(storeName, 'UPSERT', 'EMPTY_VECTORS'),\n      domain: ErrorDomain.MASTRA_VECTOR,\n      category: ErrorCategory.USER,\n      details: {\n        message: 'Vectors array cannot be empty',\n      },\n    });\n  }\n\n  // Validate metadata length matches vectors length (skip if metadata is empty/not provided)\n  if (metadata && metadata.length > 0 && metadata.length !== vectors.length) {\n    throw new MastraError({\n      id: createVectorErrorId(storeName, 'UPSERT', 'METADATA_LENGTH_MISMATCH'),\n      domain: ErrorDomain.MASTRA_VECTOR,\n      category: ErrorCategory.USER,\n      details: {\n        message: 'Metadata array length must match vectors array length',\n        vectorsLength: vectors.length,\n        metadataLength: metadata.length,\n      },\n    });\n  }\n\n  // Validate ids length matches vectors length\n  if (ids && ids.length !== vectors.length) {\n    throw new MastraError({\n      id: createVectorErrorId(storeName, 'UPSERT', 'IDS_LENGTH_MISMATCH'),\n      domain: ErrorDomain.MASTRA_VECTOR,\n      category: ErrorCategory.USER,\n      details: {\n        message: 'IDs array length must match vectors array length',\n        vectorsLength: vectors.length,\n        idsLength: ids.length,\n      },\n    });\n  }\n}\n\n/**\n * Validates topK parameter for queries\n *\n * @param storeName - Name of the vector store (e.g., 'PG', 'CHROMA')\n * @param topK - Number of results to return\n * @throws MastraError if topK is not a positive integer\n */\nexport function validateTopK(storeName: string, topK: number): void {\n  if (!Number.isInteger(topK) || topK <= 0) {\n    throw new MastraError({\n      id: createVectorErrorId(storeName, 'QUERY', 'INVALID_TOP_K'),\n      domain: ErrorDomain.MASTRA_VECTOR,\n      category: ErrorCategory.USER,\n      details: {\n        message: 'topK must be a positive integer',\n        topK,\n      },\n    });\n  }\n}\n\n/**\n * Validates vector components for NaN/Infinity values\n *\n * @param storeName - Name of the vector store (e.g., 'PG', 'CHROMA')\n * @param vectors - Array of vectors to validate\n * @throws MastraError if any vector contains NaN, Infinity, null, or undefined\n */\nexport function validateVectorValues(storeName: string, vectors: number[][]): void {\n  for (let i = 0; i < vectors.length; i++) {\n    const vector = vectors[i];\n\n    if (!vector) {\n      throw new MastraError({\n        id: createVectorErrorId(storeName, 'UPSERT', 'INVALID_VECTOR'),\n        domain: ErrorDomain.MASTRA_VECTOR,\n        category: ErrorCategory.USER,\n        details: {\n          message: `Vector at index ${i} is null or undefined`,\n          vectorIndex: i,\n        },\n      });\n    }\n\n    for (let j = 0; j < vector.length; j++) {\n      const value = vector[j];\n\n      if (value === null || value === undefined || !Number.isFinite(value)) {\n        throw new MastraError({\n          id: createVectorErrorId(storeName, 'UPSERT', 'INVALID_VECTOR_VALUE'),\n          domain: ErrorDomain.MASTRA_VECTOR,\n          category: ErrorCategory.USER,\n          details: {\n            message: `Vector contains invalid value (null, undefined, NaN, or Infinity) at position [${i}][${j}]`,\n            vectorIndex: i,\n            componentIndex: j,\n            value: String(value),\n          },\n        });\n      }\n    }\n  }\n}\n\n/**\n * Validates all upsert inputs including vector values\n * Combines validateUpsertInput and validateVectorValues\n *\n * @param storeName - Name of the vector store (e.g., 'PG', 'CHROMA')\n * @param vectors - Array of vectors to upsert\n * @param metadata - Optional metadata array\n * @param ids - Optional ids array\n * @param validateValues - Whether to validate vector values for NaN/Infinity (default: false)\n * @throws MastraError if validation fails\n */\nexport function validateUpsert(\n  storeName: string,\n  vectors: number[][] | undefined | null,\n  metadata?: Record<string, any>[] | null,\n  ids?: string[] | null,\n  validateValues = false,\n): void {\n  validateUpsertInput(storeName, vectors, metadata, ids);\n\n  if (validateValues && vectors) {\n    validateVectorValues(storeName, vectors);\n  }\n}\n"],"mappings":"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"}