@mastra/core
Version:
Mastra is a framework for building AI-powered applications and agents with a modern TypeScript stack.
1 lines • 17.2 kB
Source Map (JSON)
{"version":3,"sources":["../../src/vector/vector.ts","../../src/vector/validation.ts"],"names":["MastraBase","MastraError","createVectorErrorId"],"mappings":"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","file":"index.cjs","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\n constructor({ id }: { id: string }) {\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 }\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"]}