@mastra/qdrant 0.11.8 → 0.11.9-alpha.0

package/src/vector/index.ts

@@ -1,396 +0,0 @@
-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 { QdrantClient } from '@qdrant/js-client-rest';
-import type { Schemas } from '@qdrant/js-client-rest';
-
-import { QdrantFilterTranslator } from './filter';
-import type { QdrantVectorFilter } from './filter';
-
-const BATCH_SIZE = 256;
-const DISTANCE_MAPPING: Record<string, Schemas['Distance']> = {
-  cosine: 'Cosine',
-  euclidean: 'Euclid',
-  dotproduct: 'Dot',
-};
-
-type QdrantQueryVectorParams = QueryVectorParams<QdrantVectorFilter>;
-
-export class QdrantVector extends MastraVector {
-  private client: QdrantClient;
-
-  /**
-   * Creates a new QdrantVector client.
-   * @param url - The URL of the Qdrant server.
-   * @param apiKey - The API key for Qdrant.
-   * @param https - Whether to use HTTPS.
-   */
-  constructor({ url, apiKey, https }: { url: string; apiKey?: string; https?: boolean }) {
-    super();
-    const baseClient = new QdrantClient({
-      url,
-      apiKey,
-      https,
-    });
-    const telemetry = this.__getTelemetry();
-    this.client =
-      telemetry?.traceClass(baseClient, {
-        spanNamePrefix: 'qdrant-vector',
-        attributes: {
-          'vector.type': 'qdrant',
-        },
-      }) ?? baseClient;
-  }
-
-  async upsert({ indexName, vectors, metadata, ids }: UpsertVectorParams): Promise<string[]> {
-    const pointIds = ids || vectors.map(() => crypto.randomUUID());
-
-    const records = vectors.map((vector, i) => ({
-      id: pointIds[i],
-      vector: vector,
-      payload: metadata?.[i] || {},
-    }));
-
-    try {
-      for (let i = 0; i < records.length; i += BATCH_SIZE) {
-        const batch = records.slice(i, i + BATCH_SIZE);
-        await this.client.upsert(indexName, {
-          // @ts-expect-error
-          points: batch,
-          wait: true,
-        });
-      }
-
-      return pointIds;
-    } catch (error) {
-      throw new MastraError(
-        {
-          id: 'STORAGE_QDRANT_VECTOR_UPSERT_FAILED',
-          domain: ErrorDomain.STORAGE,
-          category: ErrorCategory.THIRD_PARTY,
-          details: { indexName, vectorCount: vectors.length },
-        },
-        error,
-      );
-    }
-  }
-
-  async createIndex({ indexName, dimension, metric = 'cosine' }: CreateIndexParams): Promise<void> {
-    try {
-      if (!Number.isInteger(dimension) || dimension <= 0) {
-        throw new Error('Dimension must be a positive integer');
-      }
-      if (!DISTANCE_MAPPING[metric]) {
-        throw new Error(`Invalid metric: "${metric}". Must be one of: cosine, euclidean, dotproduct`);
-      }
-    } catch (validationError) {
-      throw new MastraError(
-        {
-          id: 'STORAGE_QDRANT_VECTOR_CREATE_INDEX_INVALID_ARGS',
-          domain: ErrorDomain.STORAGE,
-          category: ErrorCategory.USER,
-          details: { indexName, dimension, metric },
-        },
-        validationError,
-      );
-    }
-
-    try {
-      await this.client.createCollection(indexName, {
-        vectors: {
-          size: dimension,
-          distance: DISTANCE_MAPPING[metric],
-        },
-      });
-    } catch (error: any) {
-      const message = error?.message || error?.toString();
-      // Qdrant typically returns 409 for existing collection
-      if (error?.status === 409 || (typeof message === 'string' && message.toLowerCase().includes('exists'))) {
-        // Fetch collection info and check dimension
-        await this.validateExistingIndex(indexName, dimension, metric);
-        return;
-      }
-
-      throw new MastraError(
-        {
-          id: 'STORAGE_QDRANT_VECTOR_CREATE_INDEX_FAILED',
-          domain: ErrorDomain.STORAGE,
-          category: ErrorCategory.THIRD_PARTY,
-          details: { indexName, dimension, metric },
-        },
-        error,
-      );
-    }
-  }
-
-  transformFilter(filter?: QdrantVectorFilter) {
-    const translator = new QdrantFilterTranslator();
-    return translator.translate(filter);
-  }
-
-  async query({
-    indexName,
-    queryVector,
-    topK = 10,
-    filter,
-    includeVector = false,
-  }: QdrantQueryVectorParams): Promise<QueryResult[]> {
-    const translatedFilter = this.transformFilter(filter) ?? {};
-
-    try {
-      const results = (
-        await this.client.query(indexName, {
-          query: queryVector,
-          limit: topK,
-          filter: translatedFilter,
-          with_payload: true,
-          with_vector: includeVector,
-        })
-      ).points;
-
-      return results.map(match => {
-        let vector: number[] = [];
-        if (includeVector) {
-          if (Array.isArray(match.vector)) {
-            // If it's already an array of numbers
-            vector = match.vector as number[];
-          } else if (typeof match.vector === 'object' && match.vector !== null) {
-            // If it's an object with vector data
-            vector = Object.values(match.vector).filter(v => typeof v === 'number');
-          }
-        }
-
-        return {
-          id: match.id as string,
-          score: match.score || 0,
-          metadata: match.payload as Record<string, any>,
-          ...(includeVector && { vector }),
-        };
-      });
-    } catch (error) {
-      throw new MastraError(
-        {
-          id: 'STORAGE_QDRANT_VECTOR_QUERY_FAILED',
-          domain: ErrorDomain.STORAGE,
-          category: ErrorCategory.THIRD_PARTY,
-          details: { indexName, topK },
-        },
-        error,
-      );
-    }
-  }
-
-  async listIndexes(): Promise<string[]> {
-    try {
-      const response = await this.client.getCollections();
-      return response.collections.map(collection => collection.name) || [];
-    } catch (error) {
-      throw new MastraError(
-        {
-          id: 'STORAGE_QDRANT_VECTOR_LIST_INDEXES_FAILED',
-          domain: ErrorDomain.STORAGE,
-          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> {
-    try {
-      const { config, points_count } = await this.client.getCollection(indexName);
-
-      const distance = config.params.vectors?.distance as Schemas['Distance'];
-      return {
-        dimension: config.params.vectors?.size as number,
-        count: points_count || 0,
-        // @ts-expect-error
-        metric: Object.keys(DISTANCE_MAPPING).find(key => DISTANCE_MAPPING[key] === distance),
-      };
-    } catch (error) {
-      throw new MastraError(
-        {
-          id: 'STORAGE_QDRANT_VECTOR_DESCRIBE_INDEX_FAILED',
-          domain: ErrorDomain.STORAGE,
-          category: ErrorCategory.THIRD_PARTY,
-          details: { indexName },
-        },
-        error,
-      );
-    }
-  }
-
-  async deleteIndex({ indexName }: DeleteIndexParams): Promise<void> {
-    try {
-      await this.client.deleteCollection(indexName);
-    } catch (error) {
-      throw new MastraError(
-        {
-          id: 'STORAGE_QDRANT_VECTOR_DELETE_INDEX_FAILED',
-          domain: ErrorDomain.STORAGE,
-          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> {
-    try {
-      if (!update.vector && !update.metadata) {
-        throw new Error('No updates provided');
-      }
-    } catch (validationError) {
-      throw new MastraError(
-        {
-          id: 'STORAGE_QDRANT_VECTOR_UPDATE_VECTOR_INVALID_ARGS',
-          domain: ErrorDomain.STORAGE,
-          category: ErrorCategory.USER,
-          details: { indexName, id },
-        },
-        validationError,
-      );
-    }
-
-    const pointId = this.parsePointId(id);
-
-    try {
-      // Handle metadata-only update
-      if (update.metadata && !update.vector) {
-        // For metadata-only updates, use the setPayload method
-        await this.client.setPayload(indexName, { payload: update.metadata, points: [pointId] });
-        return;
-      }
-
-      // Handle vector-only update
-      if (update.vector && !update.metadata) {
-        await this.client.updateVectors(indexName, {
-          points: [
-            {
-              id: pointId,
-              vector: update.vector,
-            },
-          ],
-        });
-        return;
-      }
-
-      // Handle both vector and metadata update
-      if (update.vector && update.metadata) {
-        const point = {
-          id: pointId,
-          vector: update.vector,
-          payload: update.metadata,
-        };
-
-        await this.client.upsert(indexName, {
-          points: [point],
-        });
-        return;
-      }
-    } catch (error) {
-      throw new MastraError(
-        {
-          id: 'STORAGE_QDRANT_VECTOR_UPDATE_VECTOR_FAILED',
-          domain: ErrorDomain.STORAGE,
-          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 {
-      // Parse the ID - Qdrant supports both string and numeric IDs
-      const pointId = this.parsePointId(id);
-
-      // Use the Qdrant client to delete the point from the collection
-      await this.client.delete(indexName, {
-        points: [pointId],
-      });
-    } catch (error) {
-      throw new MastraError(
-        {
-          id: 'STORAGE_QDRANT_VECTOR_DELETE_VECTOR_FAILED',
-          domain: ErrorDomain.STORAGE,
-          category: ErrorCategory.THIRD_PARTY,
-          details: { indexName, id },
-        },
-        error,
-      );
-    }
-  }
-
-  /**
-   * Parses and converts a string ID to the appropriate type (string or number) for Qdrant point operations.
-   *
-   * Qdrant supports both numeric and string IDs. This helper method ensures IDs are in the correct format
-   * before sending them to the Qdrant client API.
-   *
-   * @param id - The ID string to parse
-   * @returns The parsed ID as either a number (if string contains only digits) or the original string
-   *
-   * @example
-   * // Numeric ID strings are converted to numbers
-   * parsePointId("123") => 123
-   * parsePointId("42") => 42
-   * parsePointId("0") => 0
-   *
-   * // String IDs containing any non-digit characters remain as strings
-   * parsePointId("doc-123") => "doc-123"
-   * parsePointId("user_42") => "user_42"
-   * parsePointId("abc123") => "abc123"
-   * parsePointId("123abc") => "123abc"
-   * parsePointId("") => ""
-   * parsePointId("uuid-5678-xyz") => "uuid-5678-xyz"
-   *
-   * @remarks
-   * - This conversion is important because Qdrant treats numeric and string IDs differently
-   * - Only positive integers are converted to numbers (negative numbers with minus signs remain strings)
-   * - The method uses base-10 parsing, so leading zeros will be dropped in numeric conversions
-   * - reference: https://qdrant.tech/documentation/concepts/points/?q=qdrant+point+id#point-ids
-   */
-  private parsePointId(id: string): string | number {
-    // Try to parse as number if it looks like one
-    if (/^\d+$/.test(id)) {
-      return parseInt(id, 10);
-    }
-    return id;
-  }
-}

package/src/vector/prompt.ts

@@ -1,85 +0,0 @@
-/**
- * Vector store specific prompt that details supported operators and examples.
- * This prompt helps users construct valid filters for Qdrant Vector.
- */
-export const QDRANT_PROMPT = `When querying Qdrant, 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"] } }
-
-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 } }
-- $match: Match text using full-text search
-  Example: { "description": { "$match": "gaming laptop" } }
-- $null: Check if field is null
-  Example: { "rating": { "$null": true } }
-
-Restrictions:
-- Regex patterns are not supported
-- Only $and, $or, and $not logical operators are supported at the top level
-- Empty arrays in $in/$nin will return no results
-- Nested fields are supported using dot notation
-- Multiple conditions on the same field are supported with both implicit and explicit $and
-- 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, $not):
-  - 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 } },
-    { "description": { "$match": "gaming laptop" } },
-    { "rating": { "$exists": true, "$gt": 4 } },
-    { "$or": [
-      { "stock": { "$gt": 0 } },
-      { "preorder": { "$null": false } }
-    ]},
-    { "$not": { "status": "discontinued" } }
-  ]
-}`;

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'],
-    },
-  },
-});