@mastra/s3vectors 1.1.0 → 1.1.1

package/dist/index.cjs

@@ -1,710 +1,659 @@
-'use strict';
-
-var clientS3vectors = require('@aws-sdk/client-s3vectors');
-var uuid = require('@lukeed/uuid');
-var error = require('@mastra/core/error');
-var storage = require('@mastra/core/storage');
-var vector = require('@mastra/core/vector');
-var filter = require('@mastra/core/vector/filter');
-
-// src/vector/index.ts
-var S3VectorsFilterTranslator = class extends filter.BaseFilterTranslator {
-  /** @inheritdoc */
-  getSupportedOperators() {
-    return {
-      logical: ["$and", "$or"],
-      basic: ["$eq", "$ne"],
-      numeric: ["$gt", "$gte", "$lt", "$lte"],
-      array: ["$in", "$nin"],
-      element: ["$exists"]
-    };
-  }
-  /**
-   * Translates and validates a filter.
-   * @param filter - Input filter; may be `undefined`, `null`, or `{}` (all treated as empty).
-   * @returns The translated filter (or the original value if empty).
-   */
-  translate(filter) {
-    if (this.isEmpty(filter)) return filter;
-    const translated = this.translateNode(filter, false);
-    this.validateFilter(translated);
-    return translated;
-  }
-  /**
-   * Recursively translates a node.
-   * @param node - Current node to translate.
-   * @param inFieldValue - When `true`, the node is the value of a field (i.e., equality context).
-   * @remarks
-   * - In a **field-value** context, only primitives or operator objects are allowed.
-   * - In a **non-field** context (root / logical branches), operator keys are processed;
-   *   plain keys become field equalities and are validated.
-   * - Implicit AND is canonicalized in non-field contexts when multiple non-logical keys exist.
-   */
-  translateNode(node, inFieldValue = false) {
-    if (this.isPrimitive(node) || node instanceof Date) {
-      return inFieldValue ? this.validateAndNormalizePrimitive(node) : node;
-    }
-    if (Array.isArray(node)) {
-      if (inFieldValue) {
-        throw new Error("Array equality is not supported in S3 Vectors. Use $in / $nin operators.");
-      }
-      return node;
-    }
-    const entries = Object.entries(node);
-    if (inFieldValue) {
-      if (entries.length === 0) {
-        throw new Error("Invalid equality value. Only string, number, or boolean are supported by S3 Vectors");
-      }
-      const allOperatorKeys = entries.every(([k]) => this.isOperator(k));
-      if (!allOperatorKeys) {
-        throw new Error("Invalid equality value. Only string, number, or boolean are supported by S3 Vectors");
-      }
-      const opEntries = entries.map(([key, value]) => [key, this.translateOperatorValue(key, value)]);
-      return Object.fromEntries(opEntries);
-    }
-    const translatedEntries = entries.map(([key, value]) => {
-      if (this.isOperator(key)) {
-        return [key, this.translateOperatorValue(key, value)];
-      }
-      return [key, this.translateNode(value, true)];
-    });
-    const obj = Object.fromEntries(translatedEntries);
-    const keys = Object.keys(obj);
-    const hasLogical = keys.some((k) => k === "$and" || k === "$or");
-    if (!hasLogical) {
-      const nonLogical = keys.filter((k) => k !== "$and" && k !== "$or");
-      if (nonLogical.length > 1) {
-        return { $and: nonLogical.map((k) => ({ [k]: obj[k] })) };
-      }
-    }
-    return obj;
-  }
-  /**
-   * Translates a single operator and validates its value.
-   * @param operator - One of the supported query operators.
-   * @param value - Operator value to normalize/validate.
-   */
-  translateOperatorValue(operator, value) {
-    if (operator === "$and" || operator === "$or") {
-      if (!Array.isArray(value) || value.length === 0) {
-        throw new Error(`Value for logical operator ${operator} must be a non-empty array`);
-      }
-      return value.map((item) => this.translateNode(item));
-    }
-    if (operator === "$eq" || operator === "$ne") {
-      if (value instanceof Date) {
-        throw new Error("Invalid equality value. Only string, number, or boolean are supported by S3 Vectors");
-      }
-      return this.toPrimitiveForS3(value, operator);
-    }
-    if (operator === "$gt" || operator === "$gte" || operator === "$lt" || operator === "$lte") {
-      const n = this.toNumberForRange(value, operator);
-      return n;
-    }
-    if (operator === "$in" || operator === "$nin") {
-      if (!Array.isArray(value) || value.length === 0) {
-        throw new Error(`Value for array operator ${operator} must be a non-empty array`);
-      }
-      return value.map((v) => this.toPrimitiveForS3(v, operator));
-    }
-    if (operator === "$exists") {
-      if (typeof value !== "boolean") {
-        throw new Error(`Value for $exists operator must be a boolean`);
-      }
-      return value;
-    }
-    throw new Error(`Unsupported operator: ${operator}`);
-  }
-  /**
-   * Normalizes a value to an S3-accepted primitive.
-   * @param value - String | Number | Boolean | Date.
-   * @param operatorForMessage - Operator name used in error messages.
-   * @returns The normalized primitive; `Date` becomes epoch milliseconds.
-   * @throws If the value is not a supported primitive or is null/undefined.
-   */
-  toPrimitiveForS3(value, operatorForMessage) {
-    if (value === null || value === void 0) {
-      if (operatorForMessage === "equality") {
-        throw new Error("S3 Vectors does not support null/undefined for equality");
-      }
-      throw new Error(`Value for ${operatorForMessage} must be string, number, or boolean`);
-    }
-    if (value instanceof Date) {
-      return value.getTime();
-    }
-    const t = typeof value;
-    if (t === "string" || t === "boolean") return value;
-    if (t === "number") return Object.is(value, -0) ? 0 : value;
-    throw new Error(`Value for ${operatorForMessage} must be string, number, or boolean`);
-  }
-  /**
-   * Ensures a numeric value for range operators; allows `Date` by converting to epoch ms.
-   * @param value - Candidate value.
-   * @param operatorForMessage - Operator name used in error messages.
-   * @throws If the value is not a number (or a Date).
-   */
-  toNumberForRange(value, operatorForMessage) {
-    if (value instanceof Date) return value.getTime();
-    if (typeof value === "number" && !Number.isNaN(value)) return Object.is(value, -0) ? 0 : value;
-    throw new Error(`Value for ${operatorForMessage} must be a number`);
-  }
-  /**
-   * Validates and normalizes a primitive used in field equality (implicit `$eq`).
-   * @param value - Candidate equality value.
-   * @throws If the value is a `Date` or not a supported primitive.
-   */
-  validateAndNormalizePrimitive(value) {
-    if (value instanceof Date) {
-      throw new Error("Invalid equality value. Only string, number, or boolean are supported by S3 Vectors");
-    }
-    return this.toPrimitiveForS3(value, "equality");
-  }
-  /**
-   * Determines whether a filter is considered empty.
-   * @param filter - Input filter.
-   */
-  isEmpty(filter) {
-    return filter === void 0 || filter === null || typeof filter === "object" && Object.keys(filter).length === 0;
-  }
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _aws_sdk_client_s3vectors = require("@aws-sdk/client-s3vectors");
+let _lukeed_uuid = require("@lukeed/uuid");
+let _mastra_core_error = require("@mastra/core/error");
+let _mastra_core_storage = require("@mastra/core/storage");
+let _mastra_core_vector = require("@mastra/core/vector");
+let _mastra_core_vector_filter = require("@mastra/core/vector/filter");
+//#region src/vector/filter.ts
+/**
+* Translates a high-level filter into the S3 Vectors filter shape.
+*
+* @remarks
+* - Canonicalizes **implicit AND** (e.g. `{a:1,b:2}`) into explicit `{$and:[{a:1},{b:2}]}` in any
+*   non-field context that lacks `$and/$or`.
+* - Normalizes `Date` values to epoch milliseconds where allowed (numeric comparisons and array elements).
+* - Disallows `Date` at equality positions (including implicit equality).
+* - Validates shapes using the base class after translation.
+*/
+var S3VectorsFilterTranslator = class extends _mastra_core_vector_filter.BaseFilterTranslator {
+	/** @inheritdoc */
+	getSupportedOperators() {
+		return {
+			logical: ["$and", "$or"],
+			basic: ["$eq", "$ne"],
+			numeric: [
+				"$gt",
+				"$gte",
+				"$lt",
+				"$lte"
+			],
+			array: ["$in", "$nin"],
+			element: ["$exists"]
+		};
+	}
+	/**
+	* Translates and validates a filter.
+	* @param filter - Input filter; may be `undefined`, `null`, or `{}` (all treated as empty).
+	* @returns The translated filter (or the original value if empty).
+	*/
+	translate(filter) {
+		if (this.isEmpty(filter)) return filter;
+		const translated = this.translateNode(filter, false);
+		this.validateFilter(translated);
+		return translated;
+	}
+	/**
+	* Recursively translates a node.
+	* @param node - Current node to translate.
+	* @param inFieldValue - When `true`, the node is the value of a field (i.e., equality context).
+	* @remarks
+	* - In a **field-value** context, only primitives or operator objects are allowed.
+	* - In a **non-field** context (root / logical branches), operator keys are processed;
+	*   plain keys become field equalities and are validated.
+	* - Implicit AND is canonicalized in non-field contexts when multiple non-logical keys exist.
+	*/
+	translateNode(node, inFieldValue = false) {
+		if (this.isPrimitive(node) || node instanceof Date) return inFieldValue ? this.validateAndNormalizePrimitive(node) : node;
+		if (Array.isArray(node)) {
+			if (inFieldValue) throw new Error("Array equality is not supported in S3 Vectors. Use $in / $nin operators.");
+			return node;
+		}
+		const entries = Object.entries(node);
+		if (inFieldValue) {
+			if (entries.length === 0) throw new Error("Invalid equality value. Only string, number, or boolean are supported by S3 Vectors");
+			if (!entries.every(([k]) => this.isOperator(k))) throw new Error("Invalid equality value. Only string, number, or boolean are supported by S3 Vectors");
+			const opEntries = entries.map(([key, value]) => [key, this.translateOperatorValue(key, value)]);
+			return Object.fromEntries(opEntries);
+		}
+		const translatedEntries = entries.map(([key, value]) => {
+			if (this.isOperator(key)) return [key, this.translateOperatorValue(key, value)];
+			return [key, this.translateNode(value, true)];
+		});
+		const obj = Object.fromEntries(translatedEntries);
+		const keys = Object.keys(obj);
+		if (!keys.some((k) => k === "$and" || k === "$or")) {
+			const nonLogical = keys.filter((k) => k !== "$and" && k !== "$or");
+			if (nonLogical.length > 1) return { $and: nonLogical.map((k) => ({ [k]: obj[k] })) };
+		}
+		return obj;
+	}
+	/**
+	* Translates a single operator and validates its value.
+	* @param operator - One of the supported query operators.
+	* @param value - Operator value to normalize/validate.
+	*/
+	translateOperatorValue(operator, value) {
+		if (operator === "$and" || operator === "$or") {
+			if (!Array.isArray(value) || value.length === 0) throw new Error(`Value for logical operator ${operator} must be a non-empty array`);
+			return value.map((item) => this.translateNode(item));
+		}
+		if (operator === "$eq" || operator === "$ne") {
+			if (value instanceof Date) throw new Error("Invalid equality value. Only string, number, or boolean are supported by S3 Vectors");
+			return this.toPrimitiveForS3(value, operator);
+		}
+		if (operator === "$gt" || operator === "$gte" || operator === "$lt" || operator === "$lte") return this.toNumberForRange(value, operator);
+		if (operator === "$in" || operator === "$nin") {
+			if (!Array.isArray(value) || value.length === 0) throw new Error(`Value for array operator ${operator} must be a non-empty array`);
+			return value.map((v) => this.toPrimitiveForS3(v, operator));
+		}
+		if (operator === "$exists") {
+			if (typeof value !== "boolean") throw new Error(`Value for $exists operator must be a boolean`);
+			return value;
+		}
+		throw new Error(`Unsupported operator: ${operator}`);
+	}
+	/**
+	* Normalizes a value to an S3-accepted primitive.
+	* @param value - String | Number | Boolean | Date.
+	* @param operatorForMessage - Operator name used in error messages.
+	* @returns The normalized primitive; `Date` becomes epoch milliseconds.
+	* @throws If the value is not a supported primitive or is null/undefined.
+	*/
+	toPrimitiveForS3(value, operatorForMessage) {
+		if (value === null || value === void 0) {
+			if (operatorForMessage === "equality") throw new Error("S3 Vectors does not support null/undefined for equality");
+			throw new Error(`Value for ${operatorForMessage} must be string, number, or boolean`);
+		}
+		if (value instanceof Date) return value.getTime();
+		const t = typeof value;
+		if (t === "string" || t === "boolean") return value;
+		if (t === "number") return Object.is(value, -0) ? 0 : value;
+		throw new Error(`Value for ${operatorForMessage} must be string, number, or boolean`);
+	}
+	/**
+	* Ensures a numeric value for range operators; allows `Date` by converting to epoch ms.
+	* @param value - Candidate value.
+	* @param operatorForMessage - Operator name used in error messages.
+	* @throws If the value is not a number (or a Date).
+	*/
+	toNumberForRange(value, operatorForMessage) {
+		if (value instanceof Date) return value.getTime();
+		if (typeof value === "number" && !Number.isNaN(value)) return Object.is(value, -0) ? 0 : value;
+		throw new Error(`Value for ${operatorForMessage} must be a number`);
+	}
+	/**
+	* Validates and normalizes a primitive used in field equality (implicit `$eq`).
+	* @param value - Candidate equality value.
+	* @throws If the value is a `Date` or not a supported primitive.
+	*/
+	validateAndNormalizePrimitive(value) {
+		if (value instanceof Date) throw new Error("Invalid equality value. Only string, number, or boolean are supported by S3 Vectors");
+		return this.toPrimitiveForS3(value, "equality");
+	}
+	/**
+	* Determines whether a filter is considered empty.
+	* @param filter - Input filter.
+	*/
+	isEmpty(filter) {
+		return filter === void 0 || filter === null || typeof filter === "object" && Object.keys(filter).length === 0;
+	}
 };
-
-// src/vector/index.ts
-var S3Vectors = class _S3Vectors extends vector.MastraVector {
-  client;
-  vectorBucketName;
-  nonFilterableMetadataKeys;
-  filterTranslator = new S3VectorsFilterTranslator();
-  static METRIC_MAP = {
-    cosine: "cosine",
-    euclidean: "euclidean"
-  };
-  constructor(opts) {
-    super({ id: opts.id });
-    if (!opts?.vectorBucketName) {
-      throw new error.MastraError(
-        {
-          id: storage.createVectorErrorId("S3VECTORS", "INITIALIZATION", "MISSING_BUCKET_NAME"),
-          domain: error.ErrorDomain.STORAGE,
-          category: error.ErrorCategory.USER
-        },
-        new Error("vectorBucketName is required")
-      );
-    }
-    this.vectorBucketName = opts.vectorBucketName;
-    this.nonFilterableMetadataKeys = opts.nonFilterableMetadataKeys;
-    this.client = new clientS3vectors.S3VectorsClient({ ...opts.clientConfig ?? {} });
-  }
-  /**
-   * No-op to satisfy the base interface.
-   *
-   * @remarks The AWS SDK manages HTTP per request; no persistent connection is needed.
-   */
-  async connect() {
-  }
-  /**
-   * Closes the underlying AWS SDK HTTP handler to free sockets.
-   */
-  async disconnect() {
-    try {
-      this.client.destroy();
-    } catch (error$1) {
-      throw new error.MastraError(
-        {
-          id: storage.createVectorErrorId("S3VECTORS", "DISCONNECT", "FAILED"),
-          domain: error.ErrorDomain.STORAGE,
-          category: error.ErrorCategory.THIRD_PARTY
-        },
-        error$1
-      );
-    }
-  }
-  /**
-   * Creates an index or validates an existing one.
-   *
-   * @param params.indexName - Logical index name; normalized internally.
-   * @param params.dimension - Vector dimension (must be a positive integer).
-   * @param params.metric - Distance metric (`cosine` | `euclidean`). Defaults to `cosine`.
-   * @throws {MastraError} If arguments are invalid or AWS returns an error.
-   * @remarks
-   * On `ConflictException`, we verify the existing index schema via the parent implementation
-   * and return if it matches.
-   */
-  async createIndex({ indexName, dimension, metric = "cosine" }) {
-    indexName = normalizeIndexName(indexName);
-    let s3Metric;
-    try {
-      assertPositiveInteger(dimension, "dimension");
-      s3Metric = _S3Vectors.toS3Metric(metric);
-    } catch (error$1) {
-      throw new error.MastraError(
-        {
-          id: storage.createVectorErrorId("S3VECTORS", "CREATE_INDEX", "INVALID_ARGS"),
-          domain: error.ErrorDomain.STORAGE,
-          category: error.ErrorCategory.USER,
-          details: { indexName, dimension, metric }
-        },
-        error$1
-      );
-    }
-    try {
-      const input = {
-        ...this.bucketParams(),
-        indexName,
-        dataType: "float32",
-        dimension,
-        distanceMetric: s3Metric
-      };
-      if (this.nonFilterableMetadataKeys?.length) {
-        input.metadataConfiguration = { nonFilterableMetadataKeys: this.nonFilterableMetadataKeys };
-      }
-      await this.client.send(new clientS3vectors.CreateIndexCommand(input));
-    } catch (error$1) {
-      if (error$1?.name === "ConflictException") {
-        await this.validateExistingIndex(indexName, dimension, metric);
-        return;
-      }
-      throw new error.MastraError(
-        {
-          id: storage.createVectorErrorId("S3VECTORS", "CREATE_INDEX", "FAILED"),
-          domain: error.ErrorDomain.STORAGE,
-          category: error.ErrorCategory.THIRD_PARTY,
-          details: { indexName, dimension, metric }
-        },
-        error$1
-      );
-    }
-  }
-  /**
-   * Upserts vectors in bulk.
-   *
-   * @param params.indexName - Index to write to.
-   * @param params.vectors - Array of vectors; each must match the index dimension.
-   * @param params.metadata - Optional metadata per vector; `Date` values are normalized to epoch ms.
-   * @param params.ids - Optional explicit IDs; if omitted, UUIDs are generated.
-   * @returns Array of IDs used for the upsert (explicit or generated).
-   * @throws {MastraError} If validation fails or AWS returns an error.
-   */
-  async upsert({ indexName, vectors, metadata, ids }) {
-    indexName = normalizeIndexName(indexName);
-    try {
-      const { dimension } = await this.getIndexInfo(indexName);
-      validateVectorDimensions(vectors, dimension);
-      const generatedIds = ids ?? vectors.map(() => uuid.v4());
-      const putInput = {
-        ...this.bucketParams(),
-        indexName,
-        vectors: vectors.map((vec, i) => ({
-          key: generatedIds[i],
-          data: { float32: vec },
-          metadata: normalizeMetadata(metadata?.[i])
-        }))
-      };
-      await this.client.send(new clientS3vectors.PutVectorsCommand(putInput));
-      return generatedIds;
-    } catch (error$1) {
-      throw new error.MastraError(
-        {
-          id: storage.createVectorErrorId("S3VECTORS", "UPSERT", "FAILED"),
-          domain: error.ErrorDomain.STORAGE,
-          category: error.ErrorCategory.THIRD_PARTY,
-          details: { indexName }
-        },
-        error$1
-      );
-    }
-  }
-  /**
-   * Queries nearest neighbors.
-   *
-   * @param params.indexName - Target index.
-   * @param params.queryVector - Query vector (non-empty float32 array).
-   * @param params.topK - Number of neighbors to return (positive integer). Defaults to 10.
-   * @param params.filter - Metadata filter using explicit `$and`/`$or` (translator canonicalizes implicit AND).
-   * @param params.includeVector - If `true`, fetches missing vector data in a second call.
-   * @returns Results sorted by `score` descending.
-   * @throws {MastraError} If validation fails or AWS returns an error.
-   * @remarks
-   * `score = 1/(1+distance)` (monotonic transform), so ranking matches the underlying distance.
-   */
-  async query({
-    indexName,
-    queryVector,
-    topK = 10,
-    filter,
-    includeVector = false
-  }) {
-    indexName = normalizeIndexName(indexName);
-    if (!queryVector) {
-      throw new error.MastraError({
-        id: storage.createVectorErrorId("S3VECTORS", "QUERY", "MISSING_VECTOR"),
-        text: "queryVector is required for S3 Vectors queries. Metadata-only queries are not supported by this vector store.",
-        domain: error.ErrorDomain.STORAGE,
-        category: error.ErrorCategory.USER,
-        details: { indexName }
-      });
-    }
-    try {
-      if (!Array.isArray(queryVector) || queryVector.length === 0) {
-        throw new Error("queryVector must be a non-empty float32 array");
-      }
-      assertPositiveInteger(topK, "topK");
-      const translated = this.transformFilter(filter);
-      const out = await this.client.send(
-        new clientS3vectors.QueryVectorsCommand({
-          ...this.bucketParams(),
-          indexName,
-          topK,
-          queryVector: { float32: queryVector },
-          filter: translated && Object.keys(translated).length > 0 ? translated : void 0,
-          returnMetadata: true,
-          returnDistance: true
-        })
-      );
-      const vectors = (out.vectors ?? []).filter((v) => !!v?.key);
-      let dataMap;
-      if (includeVector) {
-        const keys = vectors.filter((v) => v.key).map((v) => v.key);
-        if (keys.length > 0) {
-          const got = await this.client.send(
-            new clientS3vectors.GetVectorsCommand({
-              ...this.bucketParams(),
-              indexName,
-              keys,
-              returnData: true,
-              returnMetadata: false
-            })
-          );
-          dataMap = {};
-          for (const g of got.vectors ?? []) {
-            if (g.key) dataMap[g.key] = g.data?.float32;
-          }
-        }
-      }
-      return vectors.map((v) => {
-        const id = v.key;
-        const score = _S3Vectors.distanceToScore(v.distance ?? 0);
-        const result = { id, score };
-        const md = v.metadata;
-        if (md !== void 0) result.metadata = md;
-        if (includeVector) {
-          const vec = dataMap?.[id];
-          if (vec !== void 0) result.vector = vec;
-        }
-        return result;
-      });
-    } catch (error$1) {
-      throw new error.MastraError(
-        {
-          id: storage.createVectorErrorId("S3VECTORS", "QUERY", "FAILED"),
-          domain: error.ErrorDomain.STORAGE,
-          category: error.ErrorCategory.THIRD_PARTY,
-          details: { indexName }
-        },
-        error$1
-      );
-    }
-  }
-  /**
-   * Lists indexes within the configured bucket.
-   *
-   * @returns Array of index names.
-   * @throws {MastraError} On AWS errors.
-   */
-  async listIndexes() {
-    try {
-      const names = [];
-      let nextToken;
-      do {
-        const out = await this.client.send(
-          new clientS3vectors.ListIndexesCommand({
-            ...this.bucketParams(),
-            nextToken
-          })
-        );
-        for (const idx of out.indexes ?? []) {
-          if (idx.indexName) names.push(idx.indexName);
-        }
-        nextToken = out.nextToken;
-      } while (nextToken);
-      return names;
-    } catch (error$1) {
-      throw new error.MastraError(
-        {
-          id: storage.createVectorErrorId("S3VECTORS", "LIST_INDEXES", "FAILED"),
-          domain: error.ErrorDomain.STORAGE,
-          category: error.ErrorCategory.THIRD_PARTY
-        },
-        error$1
-      );
-    }
-  }
-  /**
-   * Returns index attributes.
-   *
-   * @param params.indexName - Index name.
-   * @returns Object containing `dimension`, `metric`, and `count`.
-   * @throws {MastraError} On AWS errors.
-   * @remarks
-   * `count` is computed via `ListVectors` pagination and may be costly (O(n)).
-   */
-  async describeIndex({ indexName }) {
-    indexName = normalizeIndexName(indexName);
-    try {
-      const { dimension, metric } = await this.getIndexInfo(indexName);
-      const count = await this.countVectors(indexName);
-      return { dimension, metric, count };
-    } catch (error$1) {
-      throw new error.MastraError(
-        {
-          id: storage.createVectorErrorId("S3VECTORS", "DESCRIBE_INDEX", "FAILED"),
-          domain: error.ErrorDomain.STORAGE,
-          category: error.ErrorCategory.THIRD_PARTY,
-          details: { indexName }
-        },
-        error$1
-      );
-    }
-  }
-  /**
-   * Deletes an index.
-   *
-   * @param params.indexName - Index name.
-   * @throws {MastraError} On AWS errors.
-   */
-  async deleteIndex({ indexName }) {
-    indexName = normalizeIndexName(indexName);
-    try {
-      await this.client.send(new clientS3vectors.DeleteIndexCommand({ ...this.bucketParams(), indexName }));
-    } catch (error$1) {
-      throw new error.MastraError(
-        {
-          id: storage.createVectorErrorId("S3VECTORS", "DELETE_INDEX", "FAILED"),
-          domain: error.ErrorDomain.STORAGE,
-          category: error.ErrorCategory.THIRD_PARTY,
-          details: { indexName }
-        },
-        error$1
-      );
-    }
-  }
-  /**
-   * Updates (replaces) a vector and/or its metadata by ID.
-   *
-   * @param params.indexName - Target index.
-   * @param params.id - Vector ID.
-   * @param params.update.vector - New vector; if omitted, the existing vector is reused.
-   * @param params.update.metadata - New metadata, merged with current metadata.
-   * @throws {MastraError} If the vector does not exist and `update.vector` is omitted, or on AWS error.
-   * @remarks
-   * S3 Vectors `PutVectors` is replace-all; we `Get` the current item, merge, then `Put`.
-   */
-  async updateVector({ indexName, id, update }) {
-    if (!id) {
-      throw new error.MastraError({
-        id: storage.createVectorErrorId("S3VECTORS", "UPDATE_VECTOR", "INVALID_ARGS"),
-        domain: error.ErrorDomain.STORAGE,
-        category: error.ErrorCategory.USER,
-        text: "id is required for S3Vectors updateVector",
-        details: { indexName }
-      });
-    }
-    indexName = normalizeIndexName(indexName);
-    try {
-      if (!update.vector && !update.metadata) {
-        throw new Error("No updates provided");
-      }
-      const got = await this.client.send(
-        new clientS3vectors.GetVectorsCommand({
-          ...this.bucketParams(),
-          indexName,
-          keys: [id],
-          returnData: true,
-          returnMetadata: true
-        })
-      );
-      const current = (got.vectors ?? [])[0];
-      const newVector = update.vector ?? current?.data?.float32;
-      if (!newVector) {
-        throw new Error(`Vector "${id}" not found. Provide update.vector to create it.`);
-      }
-      const newMetadata = update.metadata !== void 0 ? normalizeMetadata(update.metadata) : current?.metadata ?? {};
-      await this.client.send(
-        new clientS3vectors.PutVectorsCommand({
-          ...this.bucketParams(),
-          indexName,
-          vectors: [{ key: id, data: { float32: newVector }, metadata: newMetadata }]
-        })
-      );
-    } catch (error$1) {
-      throw new error.MastraError(
-        {
-          id: storage.createVectorErrorId("S3VECTORS", "UPDATE_VECTOR", "FAILED"),
-          domain: error.ErrorDomain.STORAGE,
-          category: error.ErrorCategory.THIRD_PARTY,
-          details: {
-            indexName,
-            ...id && { id }
-          }
-        },
-        error$1
-      );
-    }
-  }
-  /**
-   * Deletes a vector by ID.
-   *
-   * @param params.indexName - Target index.
-   * @param params.id - Vector ID to delete.
-   * @throws {MastraError} On AWS errors.
-   */
-  async deleteVector({ indexName, id }) {
-    indexName = normalizeIndexName(indexName);
-    try {
-      await this.client.send(
-        new clientS3vectors.DeleteVectorsCommand({
-          ...this.bucketParams(),
-          indexName,
-          keys: [id]
-        })
-      );
-    } catch (error$1) {
-      throw new error.MastraError(
-        {
-          id: storage.createVectorErrorId("S3VECTORS", "DELETE_VECTOR", "FAILED"),
-          domain: error.ErrorDomain.STORAGE,
-          category: error.ErrorCategory.THIRD_PARTY,
-          details: {
-            indexName,
-            ...id && { id }
-          }
-        },
-        error$1
-      );
-    }
-  }
-  async deleteVectors({ indexName, filter, ids }) {
-    throw new error.MastraError({
-      id: storage.createVectorErrorId("S3VECTORS", "DELETE_VECTORS", "NOT_SUPPORTED"),
-      text: "deleteVectors is not yet implemented for S3Vectors vector store",
-      domain: error.ErrorDomain.STORAGE,
-      category: error.ErrorCategory.SYSTEM,
-      details: {
-        indexName,
-        ...filter && { filter: JSON.stringify(filter) },
-        ...ids && { idsCount: ids.length }
-      }
-    });
-  }
-  // -------- internal helpers --------
-  /**
-   * Returns shared bucket parameters for AWS SDK calls.
-   * @internal
-   */
-  bucketParams() {
-    return { vectorBucketName: this.vectorBucketName };
-  }
-  /**
-   * Retrieves index dimension/metric via `GetIndex`.
-   * @internal
-   * @throws {Error} If the index does not exist.
-   * @returns `{ dimension, metric }`, where `metric` includes `'dotproduct'` to satisfy Mastra types (S3 never returns it).
-   */
-  async getIndexInfo(indexName) {
-    const out = await this.client.send(new clientS3vectors.GetIndexCommand({ ...this.bucketParams(), indexName }));
-    const idx = out.index;
-    if (!idx) throw new Error(`Index "${indexName}" not found`);
-    const metric = idx.distanceMetric ?? "cosine";
-    return {
-      dimension: idx.dimension ?? 0,
-      metric
-    };
-  }
-  /**
-   * Pages through `ListVectors` and counts total items.
-   * @internal
-   * @remarks O(n). Avoid calling on hot paths.
-   */
-  async countVectors(indexName) {
-    let total = 0;
-    let nextToken;
-    do {
-      const out = await this.client.send(
-        new clientS3vectors.ListVectorsCommand({
-          ...this.bucketParams(),
-          indexName,
-          maxResults: 1e3,
-          nextToken,
-          returnData: false,
-          returnMetadata: false
-        })
-      );
-      total += (out.vectors ?? []).length;
-      nextToken = out.nextToken;
-    } while (nextToken);
-    return total;
-  }
-  /**
-   * Translates a high-level filter to the S3 Vectors filter shape.
-   * @internal
-   * @remarks Implicit AND is canonicalized by the translator where permitted by spec.
-   */
-  transformFilter(filter) {
-    if (!filter) return void 0;
-    return this.filterTranslator.translate(filter);
-  }
-  /**
-   * Converts a Mastra metric to an S3 metric.
-   * @internal
-   * @throws {Error} If the metric is not supported by S3 Vectors.
-   */
-  static toS3Metric(metric) {
-    const m = _S3Vectors.METRIC_MAP[metric];
-    if (!m) {
-      throw new Error(`Invalid metric: "${metric}". S3 Vectors supports only: cosine, euclidean`);
-    }
-    return m;
-  }
-  /**
-   * Monotonic transform from distance (smaller is better) to score (larger is better).
-   * @returns Number in (0, 1], preserving ranking.
-   */
-  static distanceToScore(distance) {
-    return 1 / (1 + distance);
-  }
+//#endregion
+//#region src/vector/index.ts
+/**
+* Vector store backed by Amazon S3 Vectors.
+*
+* @remarks
+* - Supports `cosine` and `euclidean` distance metrics.
+* - Filters must use explicit logical operators (`$and` / `$or`). The attached translator
+*   canonicalizes implicit AND (e.g., `{a:1,b:2}` → `{ $and: [{a:1},{b:2}] }`) where permitted by spec.
+* - Methods wrap AWS errors in `MastraError` with domain/category metadata.
+*/
+var S3Vectors = class S3Vectors extends _mastra_core_vector.MastraVector {
+	client;
+	vectorBucketName;
+	nonFilterableMetadataKeys;
+	filterTranslator = new S3VectorsFilterTranslator();
+	static METRIC_MAP = {
+		cosine: "cosine",
+		euclidean: "euclidean"
+	};
+	constructor(opts) {
+		super({ id: opts.id });
+		if (!opts?.vectorBucketName) throw new _mastra_core_error.MastraError({
+			id: (0, _mastra_core_storage.createVectorErrorId)("S3VECTORS", "INITIALIZATION", "MISSING_BUCKET_NAME"),
+			domain: _mastra_core_error.ErrorDomain.STORAGE,
+			category: _mastra_core_error.ErrorCategory.USER
+		}, /* @__PURE__ */ new Error("vectorBucketName is required"));
+		this.vectorBucketName = opts.vectorBucketName;
+		this.nonFilterableMetadataKeys = opts.nonFilterableMetadataKeys;
+		this.client = new _aws_sdk_client_s3vectors.S3VectorsClient({ ...opts.clientConfig ?? {} });
+	}
+	/**
+	* No-op to satisfy the base interface.
+	*
+	* @remarks The AWS SDK manages HTTP per request; no persistent connection is needed.
+	*/
+	async connect() {}
+	/**
+	* Closes the underlying AWS SDK HTTP handler to free sockets.
+	*/
+	async disconnect() {
+		try {
+			this.client.destroy();
+		} catch (error) {
+			throw new _mastra_core_error.MastraError({
+				id: (0, _mastra_core_storage.createVectorErrorId)("S3VECTORS", "DISCONNECT", "FAILED"),
+				domain: _mastra_core_error.ErrorDomain.STORAGE,
+				category: _mastra_core_error.ErrorCategory.THIRD_PARTY
+			}, error);
+		}
+	}
+	/**
+	* Creates an index or validates an existing one.
+	*
+	* @param params.indexName - Logical index name; normalized internally.
+	* @param params.dimension - Vector dimension (must be a positive integer).
+	* @param params.metric - Distance metric (`cosine` | `euclidean`). Defaults to `cosine`.
+	* @throws {MastraError} If arguments are invalid or AWS returns an error.
+	* @remarks
+	* On `ConflictException`, we verify the existing index schema via the parent implementation
+	* and return if it matches.
+	*/
+	async createIndex({ indexName, dimension, metric = "cosine" }) {
+		indexName = normalizeIndexName(indexName);
+		let s3Metric;
+		try {
+			assertPositiveInteger(dimension, "dimension");
+			s3Metric = S3Vectors.toS3Metric(metric);
+		} catch (error) {
+			throw new _mastra_core_error.MastraError({
+				id: (0, _mastra_core_storage.createVectorErrorId)("S3VECTORS", "CREATE_INDEX", "INVALID_ARGS"),
+				domain: _mastra_core_error.ErrorDomain.STORAGE,
+				category: _mastra_core_error.ErrorCategory.USER,
+				details: {
+					indexName,
+					dimension,
+					metric
+				}
+			}, error);
+		}
+		try {
+			const input = {
+				...this.bucketParams(),
+				indexName,
+				dataType: "float32",
+				dimension,
+				distanceMetric: s3Metric
+			};
+			if (this.nonFilterableMetadataKeys?.length) input.metadataConfiguration = { nonFilterableMetadataKeys: this.nonFilterableMetadataKeys };
+			await this.client.send(new _aws_sdk_client_s3vectors.CreateIndexCommand(input));
+		} catch (error) {
+			if (error?.name === "ConflictException") {
+				await this.validateExistingIndex(indexName, dimension, metric);
+				return;
+			}
+			throw new _mastra_core_error.MastraError({
+				id: (0, _mastra_core_storage.createVectorErrorId)("S3VECTORS", "CREATE_INDEX", "FAILED"),
+				domain: _mastra_core_error.ErrorDomain.STORAGE,
+				category: _mastra_core_error.ErrorCategory.THIRD_PARTY,
+				details: {
+					indexName,
+					dimension,
+					metric
+				}
+			}, error);
+		}
+	}
+	/**
+	* Upserts vectors in bulk.
+	*
+	* @param params.indexName - Index to write to.
+	* @param params.vectors - Array of vectors; each must match the index dimension.
+	* @param params.metadata - Optional metadata per vector; `Date` values are normalized to epoch ms.
+	* @param params.ids - Optional explicit IDs; if omitted, UUIDs are generated.
+	* @returns Array of IDs used for the upsert (explicit or generated).
+	* @throws {MastraError} If validation fails or AWS returns an error.
+	*/
+	async upsert({ indexName, vectors, metadata, ids }) {
+		indexName = normalizeIndexName(indexName);
+		try {
+			const { dimension } = await this.getIndexInfo(indexName);
+			validateVectorDimensions(vectors, dimension);
+			const generatedIds = ids ?? vectors.map(() => (0, _lukeed_uuid.v4)());
+			const putInput = {
+				...this.bucketParams(),
+				indexName,
+				vectors: vectors.map((vec, i) => ({
+					key: generatedIds[i],
+					data: { float32: vec },
+					metadata: normalizeMetadata(metadata?.[i])
+				}))
+			};
+			await this.client.send(new _aws_sdk_client_s3vectors.PutVectorsCommand(putInput));
+			return generatedIds;
+		} catch (error) {
+			throw new _mastra_core_error.MastraError({
+				id: (0, _mastra_core_storage.createVectorErrorId)("S3VECTORS", "UPSERT", "FAILED"),
+				domain: _mastra_core_error.ErrorDomain.STORAGE,
+				category: _mastra_core_error.ErrorCategory.THIRD_PARTY,
+				details: { indexName }
+			}, error);
+		}
+	}
+	/**
+	* Queries nearest neighbors.
+	*
+	* @param params.indexName - Target index.
+	* @param params.queryVector - Query vector (non-empty float32 array).
+	* @param params.topK - Number of neighbors to return (positive integer). Defaults to 10.
+	* @param params.filter - Metadata filter using explicit `$and`/`$or` (translator canonicalizes implicit AND).
+	* @param params.includeVector - If `true`, fetches missing vector data in a second call.
+	* @returns Results sorted by `score` descending.
+	* @throws {MastraError} If validation fails or AWS returns an error.
+	* @remarks
+	* `score = 1/(1+distance)` (monotonic transform), so ranking matches the underlying distance.
+	*/
+	async query({ indexName, queryVector, topK = 10, filter, includeVector = false }) {
+		indexName = normalizeIndexName(indexName);
+		if (!queryVector) throw new _mastra_core_error.MastraError({
+			id: (0, _mastra_core_storage.createVectorErrorId)("S3VECTORS", "QUERY", "MISSING_VECTOR"),
+			text: "queryVector is required for S3 Vectors queries. Metadata-only queries are not supported by this vector store.",
+			domain: _mastra_core_error.ErrorDomain.STORAGE,
+			category: _mastra_core_error.ErrorCategory.USER,
+			details: { indexName }
+		});
+		try {
+			if (!Array.isArray(queryVector) || queryVector.length === 0) throw new Error("queryVector must be a non-empty float32 array");
+			assertPositiveInteger(topK, "topK");
+			const translated = this.transformFilter(filter);
+			const vectors = ((await this.client.send(new _aws_sdk_client_s3vectors.QueryVectorsCommand({
+				...this.bucketParams(),
+				indexName,
+				topK,
+				queryVector: { float32: queryVector },
+				filter: translated && Object.keys(translated).length > 0 ? translated : void 0,
+				returnMetadata: true,
+				returnDistance: true
+			}))).vectors ?? []).filter((v) => !!v?.key);
+			let dataMap;
+			if (includeVector) {
+				const keys = vectors.filter((v) => v.key).map((v) => v.key);
+				if (keys.length > 0) {
+					const got = await this.client.send(new _aws_sdk_client_s3vectors.GetVectorsCommand({
+						...this.bucketParams(),
+						indexName,
+						keys,
+						returnData: true,
+						returnMetadata: false
+					}));
+					dataMap = {};
+					for (const g of got.vectors ?? []) if (g.key) dataMap[g.key] = g.data?.float32;
+				}
+			}
+			return vectors.map((v) => {
+				const id = v.key;
+				const result = {
+					id,
+					score: S3Vectors.distanceToScore(v.distance ?? 0)
+				};
+				const md = v.metadata;
+				if (md !== void 0) result.metadata = md;
+				if (includeVector) {
+					const vec = dataMap?.[id];
+					if (vec !== void 0) result.vector = vec;
+				}
+				return result;
+			});
+		} catch (error) {
+			throw new _mastra_core_error.MastraError({
+				id: (0, _mastra_core_storage.createVectorErrorId)("S3VECTORS", "QUERY", "FAILED"),
+				domain: _mastra_core_error.ErrorDomain.STORAGE,
+				category: _mastra_core_error.ErrorCategory.THIRD_PARTY,
+				details: { indexName }
+			}, error);
+		}
+	}
+	/**
+	* Lists indexes within the configured bucket.
+	*
+	* @returns Array of index names.
+	* @throws {MastraError} On AWS errors.
+	*/
+	async listIndexes() {
+		try {
+			const names = [];
+			let nextToken;
+			do {
+				const out = await this.client.send(new _aws_sdk_client_s3vectors.ListIndexesCommand({
+					...this.bucketParams(),
+					nextToken
+				}));
+				for (const idx of out.indexes ?? []) if (idx.indexName) names.push(idx.indexName);
+				nextToken = out.nextToken;
+			} while (nextToken);
+			return names;
+		} catch (error) {
+			throw new _mastra_core_error.MastraError({
+				id: (0, _mastra_core_storage.createVectorErrorId)("S3VECTORS", "LIST_INDEXES", "FAILED"),
+				domain: _mastra_core_error.ErrorDomain.STORAGE,
+				category: _mastra_core_error.ErrorCategory.THIRD_PARTY
+			}, error);
+		}
+	}
+	/**
+	* Returns index attributes.
+	*
+	* @param params.indexName - Index name.
+	* @returns Object containing `dimension`, `metric`, and `count`.
+	* @throws {MastraError} On AWS errors.
+	* @remarks
+	* `count` is computed via `ListVectors` pagination and may be costly (O(n)).
+	*/
+	async describeIndex({ indexName }) {
+		indexName = normalizeIndexName(indexName);
+		try {
+			const { dimension, metric } = await this.getIndexInfo(indexName);
+			return {
+				dimension,
+				metric,
+				count: await this.countVectors(indexName)
+			};
+		} catch (error) {
+			throw new _mastra_core_error.MastraError({
+				id: (0, _mastra_core_storage.createVectorErrorId)("S3VECTORS", "DESCRIBE_INDEX", "FAILED"),
+				domain: _mastra_core_error.ErrorDomain.STORAGE,
+				category: _mastra_core_error.ErrorCategory.THIRD_PARTY,
+				details: { indexName }
+			}, error);
+		}
+	}
+	/**
+	* Deletes an index.
+	*
+	* @param params.indexName - Index name.
+	* @throws {MastraError} On AWS errors.
+	*/
+	async deleteIndex({ indexName }) {
+		indexName = normalizeIndexName(indexName);
+		try {
+			await this.client.send(new _aws_sdk_client_s3vectors.DeleteIndexCommand({
+				...this.bucketParams(),
+				indexName
+			}));
+		} catch (error) {
+			throw new _mastra_core_error.MastraError({
+				id: (0, _mastra_core_storage.createVectorErrorId)("S3VECTORS", "DELETE_INDEX", "FAILED"),
+				domain: _mastra_core_error.ErrorDomain.STORAGE,
+				category: _mastra_core_error.ErrorCategory.THIRD_PARTY,
+				details: { indexName }
+			}, error);
+		}
+	}
+	/**
+	* Updates (replaces) a vector and/or its metadata by ID.
+	*
+	* @param params.indexName - Target index.
+	* @param params.id - Vector ID.
+	* @param params.update.vector - New vector; if omitted, the existing vector is reused.
+	* @param params.update.metadata - New metadata, merged with current metadata.
+	* @throws {MastraError} If the vector does not exist and `update.vector` is omitted, or on AWS error.
+	* @remarks
+	* S3 Vectors `PutVectors` is replace-all; we `Get` the current item, merge, then `Put`.
+	*/
+	async updateVector({ indexName, id, update }) {
+		if (!id) throw new _mastra_core_error.MastraError({
+			id: (0, _mastra_core_storage.createVectorErrorId)("S3VECTORS", "UPDATE_VECTOR", "INVALID_ARGS"),
+			domain: _mastra_core_error.ErrorDomain.STORAGE,
+			category: _mastra_core_error.ErrorCategory.USER,
+			text: "id is required for S3Vectors updateVector",
+			details: { indexName }
+		});
+		indexName = normalizeIndexName(indexName);
+		try {
+			if (!update.vector && !update.metadata) throw new Error("No updates provided");
+			const current = ((await this.client.send(new _aws_sdk_client_s3vectors.GetVectorsCommand({
+				...this.bucketParams(),
+				indexName,
+				keys: [id],
+				returnData: true,
+				returnMetadata: true
+			}))).vectors ?? [])[0];
+			const newVector = update.vector ?? current?.data?.float32;
+			if (!newVector) throw new Error(`Vector "${id}" not found. Provide update.vector to create it.`);
+			const newMetadata = update.metadata !== void 0 ? normalizeMetadata(update.metadata) : current?.metadata ?? {};
+			await this.client.send(new _aws_sdk_client_s3vectors.PutVectorsCommand({
+				...this.bucketParams(),
+				indexName,
+				vectors: [{
+					key: id,
+					data: { float32: newVector },
+					metadata: newMetadata
+				}]
+			}));
+		} catch (error) {
+			throw new _mastra_core_error.MastraError({
+				id: (0, _mastra_core_storage.createVectorErrorId)("S3VECTORS", "UPDATE_VECTOR", "FAILED"),
+				domain: _mastra_core_error.ErrorDomain.STORAGE,
+				category: _mastra_core_error.ErrorCategory.THIRD_PARTY,
+				details: {
+					indexName,
+					...id && { id }
+				}
+			}, error);
+		}
+	}
+	/**
+	* Deletes a vector by ID.
+	*
+	* @param params.indexName - Target index.
+	* @param params.id - Vector ID to delete.
+	* @throws {MastraError} On AWS errors.
+	*/
+	async deleteVector({ indexName, id }) {
+		indexName = normalizeIndexName(indexName);
+		try {
+			await this.client.send(new _aws_sdk_client_s3vectors.DeleteVectorsCommand({
+				...this.bucketParams(),
+				indexName,
+				keys: [id]
+			}));
+		} catch (error) {
+			throw new _mastra_core_error.MastraError({
+				id: (0, _mastra_core_storage.createVectorErrorId)("S3VECTORS", "DELETE_VECTOR", "FAILED"),
+				domain: _mastra_core_error.ErrorDomain.STORAGE,
+				category: _mastra_core_error.ErrorCategory.THIRD_PARTY,
+				details: {
+					indexName,
+					...id && { id }
+				}
+			}, error);
+		}
+	}
+	async deleteVectors({ indexName, filter, ids }) {
+		throw new _mastra_core_error.MastraError({
+			id: (0, _mastra_core_storage.createVectorErrorId)("S3VECTORS", "DELETE_VECTORS", "NOT_SUPPORTED"),
+			text: "deleteVectors is not yet implemented for S3Vectors vector store",
+			domain: _mastra_core_error.ErrorDomain.STORAGE,
+			category: _mastra_core_error.ErrorCategory.SYSTEM,
+			details: {
+				indexName,
+				...filter && { filter: JSON.stringify(filter) },
+				...ids && { idsCount: ids.length }
+			}
+		});
+	}
+	/**
+	* Returns shared bucket parameters for AWS SDK calls.
+	* @internal
+	*/
+	bucketParams() {
+		return { vectorBucketName: this.vectorBucketName };
+	}
+	/**
+	* Retrieves index dimension/metric via `GetIndex`.
+	* @internal
+	* @throws {Error} If the index does not exist.
+	* @returns `{ dimension, metric }`, where `metric` includes `'dotproduct'` to satisfy Mastra types (S3 never returns it).
+	*/
+	async getIndexInfo(indexName) {
+		const idx = (await this.client.send(new _aws_sdk_client_s3vectors.GetIndexCommand({
+			...this.bucketParams(),
+			indexName
+		}))).index;
+		if (!idx) throw new Error(`Index "${indexName}" not found`);
+		const metric = idx.distanceMetric ?? "cosine";
+		return {
+			dimension: idx.dimension ?? 0,
+			metric
+		};
+	}
+	/**
+	* Pages through `ListVectors` and counts total items.
+	* @internal
+	* @remarks O(n). Avoid calling on hot paths.
+	*/
+	async countVectors(indexName) {
+		let total = 0;
+		let nextToken;
+		do {
+			const out = await this.client.send(new _aws_sdk_client_s3vectors.ListVectorsCommand({
+				...this.bucketParams(),
+				indexName,
+				maxResults: 1e3,
+				nextToken,
+				returnData: false,
+				returnMetadata: false
+			}));
+			total += (out.vectors ?? []).length;
+			nextToken = out.nextToken;
+		} while (nextToken);
+		return total;
+	}
+	/**
+	* Translates a high-level filter to the S3 Vectors filter shape.
+	* @internal
+	* @remarks Implicit AND is canonicalized by the translator where permitted by spec.
+	*/
+	transformFilter(filter) {
+		if (!filter) return void 0;
+		return this.filterTranslator.translate(filter);
+	}
+	/**
+	* Converts a Mastra metric to an S3 metric.
+	* @internal
+	* @throws {Error} If the metric is not supported by S3 Vectors.
+	*/
+	static toS3Metric(metric) {
+		const m = S3Vectors.METRIC_MAP[metric];
+		if (!m) throw new Error(`Invalid metric: "${metric}". S3 Vectors supports only: cosine, euclidean`);
+		return m;
+	}
+	/**
+	* Monotonic transform from distance (smaller is better) to score (larger is better).
+	* @returns Number in (0, 1], preserving ranking.
+	*/
+	static distanceToScore(distance) {
+		return 1 / (1 + distance);
+	}
 };
+/**
+* Ensures a value is a positive integer.
+* @throws {Error} If the value is not a positive integer.
+* @internal
+*/
 function assertPositiveInteger(value, name) {
-  if (!Number.isInteger(value) || value <= 0) {
-    throw new Error(`${name} must be a positive integer`);
-  }
+	if (!Number.isInteger(value) || value <= 0) throw new Error(`${name} must be a positive integer`);
 }
+/**
+* Validates that all vectors match the required dimension.
+* @throws {Error} If any vector length differs from `dimension`.
+* @internal
+*/
 function validateVectorDimensions(vectors, dimension) {
-  if (!Array.isArray(vectors) || vectors.length === 0) {
-    throw new Error("No vectors provided for validation");
-  }
-  for (let i = 0; i < vectors.length; i++) {
-    const len = vectors[i]?.length;
-    if (len !== dimension) {
-      throw new Error(`Vector at index ${i} has invalid dimension ${len}. Expected ${dimension} dimensions.`);
-    }
-  }
+	if (!Array.isArray(vectors) || vectors.length === 0) throw new Error("No vectors provided for validation");
+	for (let i = 0; i < vectors.length; i++) {
+		const len = vectors[i]?.length;
+		if (len !== dimension) throw new Error(`Vector at index ${i} has invalid dimension ${len}. Expected ${dimension} dimensions.`);
+	}
 }
+/**
+* Normalizes metadata values for S3 Vectors: `Date` → epoch ms.
+* @internal
+*/
 function normalizeMetadata(meta) {
-  if (!meta) return {};
-  const out = {};
-  for (const [k, v] of Object.entries(meta)) {
-    out[k] = v instanceof Date ? v.getTime() : v;
-  }
-  return out;
+	if (!meta) return {};
+	const out = {};
+	for (const [k, v] of Object.entries(meta)) out[k] = v instanceof Date ? v.getTime() : v;
+	return out;
 }
+/**
+* Normalizes an index name to this store's canonical form (underscore → hyphen, lowercase).
+* @internal
+* @throws {TypeError} If the provided name is not a string.
+*/
 function normalizeIndexName(str) {
-  if (typeof str !== "string") {
-    throw new TypeError("Index name must be a string");
-  }
-  return str.replace(/_/g, "-").toLowerCase();
+	if (typeof str !== "string") throw new TypeError("Index name must be a string");
+	return str.replace(/_/g, "-").toLowerCase();
 }
-
-// src/vector/prompt.ts
-var S3VECTORS_PROMPT = `When querying Amazon S3 Vectors, you can ONLY use the operators listed below. Any other operators will be rejected.
+//#endregion
+//#region src/vector/prompt.ts
+/**
+* Vector store specific prompt that details supported operators and examples.
+* This prompt helps users construct valid filters for Amazon S3 Vectors.
+*/
+const S3VECTORS_PROMPT = `When querying Amazon S3 Vectors, you can ONLY use the operators listed below. Any other operators will be rejected.
 Important: Don't explain how to construct the filter - use the specified operators and fields to search the content and return relevant results.
 If a user tries to give an explicit operator that is not supported, reject the filter entirely and let them know that the operator is not supported.
 
@@ -781,8 +730,8 @@ Example Complex Query:
     ] }
   ]
 }`;
-
+//#endregion
 exports.S3VECTORS_PROMPT = S3VECTORS_PROMPT;
 exports.S3Vectors = S3Vectors;
-//# sourceMappingURL=index.cjs.map
+
 //# sourceMappingURL=index.cjs.map