@mastra/s3vectors 0.0.0-add-libsql-changeset-20250910154739

package/dist/index.cjs

@@ -0,0 +1,750 @@
+'use strict';
+
+var clientS3vectors = require('@aws-sdk/client-s3vectors');
+var error = require('@mastra/core/error');
+var vector = require('@mastra/core/vector');
+var uuid = require('uuid');
+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;
+  }
+};
+
+// 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();
+    if (!opts?.vectorBucketName) {
+      throw new error.MastraError(
+        {
+          id: "STORAGE_S3VECTORS_VECTOR_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_S3VECTORS_VECTOR_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_S3VECTORS_VECTOR_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_S3VECTORS_VECTOR_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_S3VECTORS_VECTOR_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);
+    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 missingKeys = vectors.filter((v) => !v.data?.float32 && v.key).map((v) => v.key);
+        if (missingKeys.length > 0) {
+          const got = await this.client.send(
+            new clientS3vectors.GetVectorsCommand({
+              ...this.bucketParams(),
+              indexName,
+              keys: missingKeys,
+              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 = v.data?.float32 ?? dataMap?.[id];
+          if (vec !== void 0) result.vector = vec;
+        }
+        return result;
+      });
+    } catch (error$1) {
+      throw new error.MastraError(
+        {
+          id: "STORAGE_S3VECTORS_VECTOR_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_S3VECTORS_VECTOR_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_S3VECTORS_VECTOR_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_S3VECTORS_VECTOR_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 }) {
+    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_S3VECTORS_VECTOR_UPDATE_VECTOR_FAILED",
+          domain: error.ErrorDomain.STORAGE,
+          category: error.ErrorCategory.THIRD_PARTY,
+          details: { indexName, 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_S3VECTORS_VECTOR_DELETE_VECTOR_FAILED",
+          domain: error.ErrorDomain.STORAGE,
+          category: error.ErrorCategory.THIRD_PARTY,
+          details: { indexName, id }
+        },
+        error$1
+      );
+    }
+  }
+  // -------- 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);
+  }
+};
+function assertPositiveInteger(value, name) {
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new Error(`${name} must be a positive integer`);
+  }
+}
+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.`);
+    }
+  }
+}
+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;
+}
+function normalizeIndexName(str) {
+  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.
+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.
+
+Basic Comparison Operators:
+- $eq: Exact match (default when using field: value)
+  Example: { "category": "electronics" }
+- $ne: Not equal
+  Example: { "category": { "$ne": "electronics" } }
+- $gt: Greater than
+  Example: { "price": { "$gt": 100 } }
+- $gte: Greater than or equal
+  Example: { "price": { "$gte": 100 } }
+- $lt: Less than
+  Example: { "price": { "$lt": 100 } }
+- $lte: Less than or equal
+  Example: { "price": { "$lte": 100 } }
+
+Array Operators (non-empty arrays of string | number | boolean):
+- $in: Match any value in array
+  Example: { "category": { "$in": ["electronics", "books"] } }
+- $nin: Does not match any value in array
+  Example: { "category": { "$nin": ["electronics", "books"] } }
+
+Logical Operators:
+- $and: Logical AND (can be implicit or explicit)
+  Implicit Example: { "price": { "$gt": 100 }, "category": "electronics" }
+  Explicit Example: { "$and": [{ "price": { "$gt": 100 } }, { "category": "electronics" }] }
+- $or: Logical OR
+  Example: { "$or": [{ "price": { "$lt": 50 } }, { "category": "books" }] }
+
+Element Operators:
+- $exists: Check if field exists
+  Example: { "rating": { "$exists": true } }
+
+Unsupported / Disallowed Operators (REJECT if present):
+- $not, $nor, $regex, $all, $elemMatch, $size, $text (and any operator not listed as supported)
+
+Restrictions:
+- Only logical operators ($and, $or) can be used at the top level
+- Empty arrays for $and / $or / $in / $nin are NOT allowed
+- Nested fields are supported using dot notation
+- Multiple conditions on the same field are supported
+- At least one key-value pair is required in filter object
+- Empty objects and undefined values are treated as no filter
+- Invalid types in comparison operators will throw errors
+- All non-logical operators must be used within a field condition
+  Valid: { "field": { "$gt": 100 } }
+  Valid: { "$and": [...] }
+  Invalid: { "$gt": 100 }
+- Logical operators must contain field conditions, not direct operators
+  Valid: { "$and": [{ "field": { "$gt": 100 } }] }
+  Invalid: { "$and": [{ "$gt": 100 }] }
+- Logical operators ($and, $or):
+  - Can only be used at top level or nested within other logical operators
+  - Can not be used on a field level, or be nested inside a field
+  - Can not be used inside an operator
+  - Valid: { "$and": [{ "field": { "$gt": 100 } }] }
+  - Valid: { "$or": [{ "$and": [{ "field": { "$gt": 100 } }] }] }
+  - Invalid: { "field": { "$and": [{ "$gt": 100 }] } }
+  - Invalid: { "field": { "$or": [{ "$gt": 100 }] } }
+  - Invalid: { "field": { "$gt": { "$and": [{...}] } } }
+- Equality values must be string, number, or boolean (arrays and objects are not allowed for equality)
+- Filters operate only on filterable metadata keys; using a non-filterable key will fail
+- Filterable metadata values are primitives (string/number/boolean) or arrays of primitives; large/long-text fields should be non-filterable and are not usable in filters
+
+Example Complex Query:
+{
+  "$and": [
+    { "category": { "$in": ["electronics", "computers"] } },
+    { "price": { "$gte": 100, "$lte": 1000 } },
+    { "$or": [
+      { "stock": { "$gt": 0 } },
+      { "preorder": true }
+    ] }
+  ]
+}`;
+
+exports.S3VECTORS_PROMPT = S3VECTORS_PROMPT;
+exports.S3Vectors = S3Vectors;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map