@mastra/astra 0.11.4 → 0.11.7-alpha.0

package/src/vector/index.ts

@@ -1,324 +0,0 @@
-import type { Db } from '@datastax/astra-db-ts';
-import { DataAPIClient, UUID } from '@datastax/astra-db-ts';
-import { MastraError, ErrorDomain, ErrorCategory } from '@mastra/core/error';
-import { MastraVector } from '@mastra/core/vector';
-import type {
-  QueryResult,
-  IndexStats,
-  CreateIndexParams,
-  UpsertVectorParams,
-  QueryVectorParams,
-  DescribeIndexParams,
-  DeleteIndexParams,
-  DeleteVectorParams,
-  UpdateVectorParams,
-} from '@mastra/core/vector';
-import type { AstraVectorFilter } from './filter';
-import { AstraFilterTranslator } from './filter';
-
-// Mastra and Astra DB agree on cosine and euclidean, but Astra DB uses dot_product instead of dotproduct.
-const metricMap = {
-  cosine: 'cosine',
-  euclidean: 'euclidean',
-  dotproduct: 'dot_product',
-} as const;
-
-export interface AstraDbOptions {
-  token: string;
-  endpoint: string;
-  keyspace?: string;
-}
-
-type AstraQueryVectorParams = QueryVectorParams<AstraVectorFilter>;
-
-export class AstraVector extends MastraVector<AstraVectorFilter> {
-  readonly #db: Db;
-
-  constructor({ token, endpoint, keyspace }: AstraDbOptions) {
-    super();
-    const client = new DataAPIClient(token);
-    this.#db = client.db(endpoint, { keyspace });
-  }
-
-  /**
-   * Creates a new collection with the specified configuration.
-   *
-   * @param {string} indexName - The name of the collection to create.
-   * @param {number} dimension - The dimension of the vectors to be stored in the collection.
-   * @param {'cosine' | 'euclidean' | 'dotproduct'} [metric=cosine] - The metric to use to sort vectors in the collection.
-   * @returns {Promise<void>} A promise that resolves when the collection is created.
-   */
-  async createIndex({ indexName, dimension, metric = 'cosine' }: CreateIndexParams): Promise<void> {
-    if (!Number.isInteger(dimension) || dimension <= 0) {
-      throw new MastraError({
-        id: 'ASTRA_VECTOR_CREATE_INDEX_INVALID_DIMENSION',
-        text: 'Dimension must be a positive integer',
-        domain: ErrorDomain.MASTRA_VECTOR,
-        category: ErrorCategory.USER,
-      });
-    }
-    try {
-      await this.#db.createCollection(indexName, {
-        vector: {
-          dimension,
-          metric: metricMap[metric],
-        },
-        checkExists: false,
-      });
-    } catch (error: any) {
-      new MastraError(
-        {
-          id: 'ASTRA_VECTOR_CREATE_INDEX_DB_ERROR',
-          domain: ErrorDomain.MASTRA_VECTOR,
-          category: ErrorCategory.THIRD_PARTY,
-          details: { indexName },
-        },
-        error,
-      );
-    }
-  }
-
-  /**
-   * Inserts or updates vectors in the specified collection.
-   *
-   * @param {string} indexName - The name of the collection to upsert into.
-   * @param {number[][]} vectors - An array of vectors to upsert.
-   * @param {Record<string, any>[]} [metadata] - An optional array of metadata objects corresponding to each vector.
-   * @param {string[]} [ids] - An optional array of IDs corresponding to each vector. If not provided, new IDs will be generated.
-   * @returns {Promise<string[]>} A promise that resolves to an array of IDs of the upserted vectors.
-   */
-  async upsert({ indexName, vectors, metadata, ids }: UpsertVectorParams): Promise<string[]> {
-    const collection = this.#db.collection(indexName);
-
-    // Generate IDs if not provided
-    const vectorIds = ids || vectors.map(() => UUID.v7().toString());
-
-    const records = vectors.map((vector, i) => ({
-      id: vectorIds[i],
-      $vector: vector,
-      metadata: metadata?.[i] || {},
-    }));
-
-    try {
-      await collection.insertMany(records);
-    } catch (error: any) {
-      throw new MastraError(
-        {
-          id: 'ASTRA_VECTOR_UPSERT_DB_ERROR',
-          domain: ErrorDomain.MASTRA_VECTOR,
-          category: ErrorCategory.THIRD_PARTY,
-          details: { indexName },
-        },
-        error,
-      );
-    }
-    return vectorIds;
-  }
-
-  transformFilter(filter?: AstraVectorFilter) {
-    const translator = new AstraFilterTranslator();
-    return translator.translate(filter);
-  }
-
-  /**
-   * Queries the specified collection using a vector and optional filter.
-   *
-   * @param {string} indexName - The name of the collection to query.
-   * @param {number[]} queryVector - The vector to query with.
-   * @param {number} [topK] - The maximum number of results to return.
-   * @param {Record<string, any>} [filter] - An optional filter to apply to the query. For more on filters in Astra DB, see the filtering reference: https://docs.datastax.com/en/astra-db-serverless/api-reference/documents.html#operators
-   * @param {boolean} [includeVectors=false] - Whether to include the vectors in the response.
-   * @returns {Promise<QueryResult[]>} A promise that resolves to an array of query results.
-   */
-  async query({
-    indexName,
-    queryVector,
-    topK = 10,
-    filter,
-    includeVector = false,
-  }: AstraQueryVectorParams): Promise<QueryResult[]> {
-    const collection = this.#db.collection(indexName);
-
-    const translatedFilter = this.transformFilter(filter);
-
-    try {
-      const cursor = collection.find(translatedFilter ?? {}, {
-        sort: { $vector: queryVector },
-        limit: topK,
-        includeSimilarity: true,
-        projection: {
-          $vector: includeVector ? true : false,
-        },
-      });
-
-      const results = await cursor.toArray();
-
-      return results.map(result => ({
-        id: result.id,
-        score: result.$similarity,
-        metadata: result.metadata,
-        ...(includeVector && { vector: result.$vector }),
-      }));
-    } catch (error: any) {
-      throw new MastraError(
-        {
-          id: 'ASTRA_VECTOR_QUERY_DB_ERROR',
-          domain: ErrorDomain.MASTRA_VECTOR,
-          category: ErrorCategory.THIRD_PARTY,
-          details: { indexName },
-        },
-        error,
-      );
-    }
-  }
-
-  /**
-   * Lists all collections in the database.
-   *
-   * @returns {Promise<string[]>} A promise that resolves to an array of collection names.
-   */
-  async listIndexes(): Promise<string[]> {
-    try {
-      return await this.#db.listCollections({ nameOnly: true });
-    } catch (error: any) {
-      throw new MastraError(
-        {
-          id: 'ASTRA_VECTOR_LIST_INDEXES_DB_ERROR',
-          domain: ErrorDomain.MASTRA_VECTOR,
-          category: ErrorCategory.THIRD_PARTY,
-        },
-        error,
-      );
-    }
-  }
-
-  /**
-   * Retrieves statistics about a vector index.
-   *
-   * @param {string} indexName - The name of the index to describe
-   * @returns A promise that resolves to the index statistics including dimension, count and metric
-   */
-  async describeIndex({ indexName }: DescribeIndexParams): Promise<IndexStats> {
-    const collection = this.#db.collection(indexName);
-    try {
-      const optionsPromise = collection.options();
-      const countPromise = collection.countDocuments({}, 100);
-      const [options, count] = await Promise.all([optionsPromise, countPromise]);
-
-      const keys = Object.keys(metricMap) as (keyof typeof metricMap)[];
-      const metric = keys.find(key => metricMap[key] === options.vector?.metric);
-      return {
-        dimension: options.vector?.dimension!,
-        metric,
-        count: count,
-      };
-    } catch (error: any) {
-      if (error instanceof MastraError) throw error;
-      throw new MastraError(
-        {
-          id: 'ASTRA_VECTOR_DESCRIBE_INDEX_DB_ERROR',
-          domain: ErrorDomain.MASTRA_VECTOR,
-          category: ErrorCategory.THIRD_PARTY,
-          details: { indexName },
-        },
-        error,
-      );
-    }
-  }
-
-  /**
-   * Deletes the specified collection.
-   *
-   * @param {string} indexName - The name of the collection to delete.
-   * @returns {Promise<void>} A promise that resolves when the collection is deleted.
-   */
-  async deleteIndex({ indexName }: DeleteIndexParams): Promise<void> {
-    const collection = this.#db.collection(indexName);
-    try {
-      await collection.drop();
-    } catch (error: any) {
-      throw new MastraError(
-        {
-          id: 'ASTRA_VECTOR_DELETE_INDEX_DB_ERROR',
-          domain: ErrorDomain.MASTRA_VECTOR,
-          category: ErrorCategory.THIRD_PARTY,
-          details: { indexName },
-        },
-        error,
-      );
-    }
-  }
-
-  /**
-   * Updates a vector by its ID with the provided vector and/or metadata.
-   * @param indexName - The name of the index containing the vector.
-   * @param id - The ID of the vector to update.
-   * @param update - An object containing the vector and/or metadata to update.
-   * @param update.vector - An optional array of numbers representing the new vector.
-   * @param update.metadata - An optional record containing the new metadata.
-   * @returns A promise that resolves when the update is complete.
-   * @throws Will throw an error if no updates are provided or if the update operation fails.
-   */
-  async updateVector({ indexName, id, update }: UpdateVectorParams): Promise<void> {
-    if (!update.vector && !update.metadata) {
-      throw new MastraError({
-        id: 'ASTRA_VECTOR_UPDATE_NO_PAYLOAD',
-        text: 'No updates provided for vector',
-        domain: ErrorDomain.MASTRA_VECTOR,
-        category: ErrorCategory.USER,
-        details: { indexName, id },
-      });
-    }
-
-    try {
-      const collection = this.#db.collection(indexName);
-      const updateDoc: Record<string, any> = {};
-
-      if (update.vector) {
-        updateDoc.$vector = update.vector;
-      }
-
-      if (update.metadata) {
-        updateDoc.metadata = update.metadata;
-      }
-
-      await collection.findOneAndUpdate({ id }, { $set: updateDoc });
-    } catch (error: any) {
-      if (error instanceof MastraError) throw error;
-      throw new MastraError(
-        {
-          id: 'ASTRA_VECTOR_UPDATE_FAILED_UNHANDLED',
-          domain: ErrorDomain.MASTRA_VECTOR,
-          category: ErrorCategory.THIRD_PARTY,
-          details: { indexName, id },
-        },
-        error,
-      );
-    }
-  }
-
-  /**
-   * Deletes a vector by its ID.
-   * @param indexName - The name of the index containing the vector.
-   * @param id - The ID of the vector to delete.
-   * @returns A promise that resolves when the deletion is complete.
-   * @throws Will throw an error if the deletion operation fails.
-   */
-  async deleteVector({ indexName, id }: DeleteVectorParams): Promise<void> {
-    try {
-      const collection = this.#db.collection(indexName);
-      await collection.deleteOne({ id });
-    } catch (error: any) {
-      if (error instanceof MastraError) throw error;
-      throw new MastraError(
-        {
-          id: 'ASTRA_VECTOR_DELETE_FAILED',
-          domain: ErrorDomain.MASTRA_VECTOR,
-          category: ErrorCategory.THIRD_PARTY,
-          details: { indexName, id },
-        },
-        error,
-      );
-    }
-  }
-}

package/src/vector/prompt.ts

@@ -1,91 +0,0 @@
-/**
- * Vector store specific prompt that details supported operators and examples.
- * This prompt helps users construct valid filters for Astra Vector.
- */
-export const ASTRA_PROMPT = `When querying Astra, 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:
-- $in: Match any value in array
-  Example: { "category": { "$in": ["electronics", "books"] } }
-- $nin: Does not match any value in array
-  Example: { "category": { "$nin": ["electronics", "books"] } }
-- $all: Match all values in array
-  Example: { "tags": { "$all": ["premium", "sale"] } }
-
-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" }] }
-- $not: Logical NOT
-  Example: { "$not": { "category": "electronics" } }
-
-Element Operators:
-- $exists: Check if field exists
-  Example: { "rating": { "$exists": true } }
-
-Special Operators:
-- $size: Array length check
-  Example: { "tags": { "$size": 2 } }
-
-Restrictions:
-- Regex patterns are not supported
-- Only $and, $or, and $not logical operators are supported
-- Nested fields are supported using dot notation
-- Multiple conditions on the same field are supported with both implicit and explicit $and
-- Empty arrays in $in/$nin will return no results
-- A non-empty array is required for $all operator
-- Only logical operators ($and, $or, $not) can be used at the top level
-- All other 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 }] }
-- $not operator:
-  - Must be an object
-  - Cannot be empty
-  - Can be used at field level or top level
-  - Valid: { "$not": { "field": "value" } }
-  - Valid: { "field": { "$not": { "$eq": "value" } } }
-- Other 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": [{...}] } } }
-
-Example Complex Query:
-{
-  "$and": [
-    { "category": { "$in": ["electronics", "computers"] } },
-    { "price": { "$gte": 100, "$lte": 1000 } },
-    { "tags": { "$all": ["premium"] } },
-    { "rating": { "$exists": true, "$gt": 4 } },
-    { "$or": [
-      { "stock": { "$gt": 0 } },
-      { "preorder": true }
-    ]}
-  ]
-}`;

package/tsconfig.build.json

@@ -1,9 +0,0 @@
-{
-  "extends": ["./tsconfig.json", "../../tsconfig.build.json"],
-  "compilerOptions": {
-    "outDir": "./dist",
-    "rootDir": "./src"
-  },
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "**/*.test.ts", "src/**/*.mock.ts"]
-}

package/tsconfig.json

@@ -1,5 +0,0 @@
-{
-  "extends": "../../tsconfig.node.json",
-  "include": ["src/**/*", "tsup.config.ts"],
-  "exclude": ["node_modules", "**/*.test.ts"]
-}

package/tsup.config.ts

@@ -1,17 +0,0 @@
-import { generateTypes } from '@internal/types-builder';
-import { defineConfig } from 'tsup';
-
-export default defineConfig({
-  entry: ['src/index.ts'],
-  format: ['esm', 'cjs'],
-  clean: true,
-  dts: false,
-  splitting: true,
-  treeshake: {
-    preset: 'smallest',
-  },
-  sourcemap: true,
-  onSuccess: async () => {
-    await generateTypes(process.cwd());
-  },
-});

package/vitest.config.ts

@@ -1,11 +0,0 @@
-import { defineConfig } from 'vitest/config';
-
-export default defineConfig({
-  test: {
-    environment: 'node',
-    include: ['src/**/*.test.ts'],
-    coverage: {
-      reporter: ['text', 'json', 'html'],
-    },
-  },
-});