@mastra/convex 0.0.0-new-button-export-20251219133013 → 0.0.0-salesman-20260127182805

package/dist/docs/vectors/01-reference.md

@@ -0,0 +1,240 @@
+# Vectors API Reference
+
+> API reference for vectors - 1 entries
+
+
+---
+
+## Reference: Convex Vector Store
+
+> Documentation for the ConvexVector class in Mastra, which provides vector search using Convex.
+
+The ConvexVector class provides vector storage and similarity search using [Convex](https://convex.dev). It stores embeddings inside Convex and performs cosine similarity search.
+
+## Installation
+
+```bash npm2yarn
+npm install @mastra/convex@latest
+```
+
+## Convex Setup
+
+Before using `ConvexVector`, you need to set up the Convex schema and storage handler. See [Convex Storage Setup](../storage/convex#convex-setup) for setup instructions.
+
+## Constructor Options
+
+## Constructor Examples
+
+### Basic Configuration
+
+```ts
+import { ConvexVector } from "@mastra/convex";
+
+const vectorStore = new ConvexVector({
+  id: 'convex-vectors',
+  deploymentUrl: "https://your-project.convex.cloud",
+  adminAuthToken: "your-admin-token",
+});
+```
+
+### Custom Storage Function
+
+```ts
+const vectorStore = new ConvexVector({
+  id: 'convex-vectors',
+  deploymentUrl: "https://your-project.convex.cloud",
+  adminAuthToken: "your-admin-token",
+  storageFunction: "custom/path:handler",
+});
+```
+
+## Methods
+
+### createIndex()
+
+```typescript
+await vectorStore.createIndex({
+  indexName: "my_vectors",
+  dimension: 1536,
+});
+```
+
+### upsert()
+
+```typescript
+await vectorStore.upsert({
+  indexName: "my_vectors",
+  vectors: [[0.1, 0.2, 0.3, ...]],
+  metadata: [{ label: "example" }],
+  ids: ["vec-1"],
+});
+```
+
+### query()
+
+```typescript
+const results = await vectorStore.query({
+  indexName: "my_vectors",
+  queryVector: [0.1, 0.2, 0.3, ...],
+  topK: 5,
+  filter: { category: "documents" },
+});
+```
+
+### listIndexes()
+
+Returns an array of index names as strings.
+
+```typescript
+const indexes = await vectorStore.listIndexes();
+// ["my_vectors", "embeddings", ...]
+```
+
+### describeIndex()
+
+Returns:
+
+```typescript
+interface IndexStats {
+  dimension: number;
+  count: number;
+  metric: "cosine" | "euclidean" | "dotproduct";
+}
+```
+
+### deleteIndex()
+
+Deletes the index and all its vectors.
+
+```typescript
+await vectorStore.deleteIndex({ indexName: "my_vectors" });
+```
+
+### updateVector()
+
+Update a single vector by ID or by metadata filter. Either `id` or `filter` must be provided, but not both.
+
+```typescript
+// Update by ID
+await vectorStore.updateVector({
+  indexName: "my_vectors",
+  id: "vector123",
+  update: {
+    vector: [0.1, 0.2, 0.3],
+    metadata: { label: "updated" },
+  },
+});
+
+// Update by filter
+await vectorStore.updateVector({
+  indexName: "my_vectors",
+  filter: { category: "product" },
+  update: {
+    metadata: { status: "reviewed" },
+  },
+});
+```
+
+### deleteVector()
+
+```typescript
+await vectorStore.deleteVector({ indexName: "my_vectors", id: "vector123" });
+```
+
+### deleteVectors()
+
+Delete multiple vectors by IDs or by metadata filter. Either `ids` or `filter` must be provided, but not both.
+
+```typescript
+// Delete by IDs
+await vectorStore.deleteVectors({
+  indexName: "my_vectors",
+  ids: ["vec1", "vec2", "vec3"],
+});
+
+// Delete by filter
+await vectorStore.deleteVectors({
+  indexName: "my_vectors",
+  filter: { status: "archived" },
+});
+```
+
+## Response Types
+
+Query results are returned in this format:
+
+```typescript
+interface QueryResult {
+  id: string;
+  score: number;
+  metadata: Record<string, any>;
+  vector?: number[]; // Only included if includeVector is true
+}
+```
+
+## Metadata Filtering
+
+ConvexVector supports metadata filtering with various operators:
+
+```typescript
+// Simple equality
+const results = await vectorStore.query({
+  indexName: "my_vectors",
+  queryVector: embedding,
+  filter: { category: "documents" },
+});
+
+// Comparison operators
+const results = await vectorStore.query({
+  indexName: "my_vectors",
+  queryVector: embedding,
+  filter: {
+    price: { $gt: 100 },
+    status: { $in: ["active", "pending"] },
+  },
+});
+
+// Logical operators
+const results = await vectorStore.query({
+  indexName: "my_vectors",
+  queryVector: embedding,
+  filter: {
+    $and: [
+      { category: "electronics" },
+      { price: { $lte: 500 } },
+    ],
+  },
+});
+```
+
+### Supported Filter Operators
+
+| Operator | Description |
+| -------- | ----------- |
+| `$eq` | Equal to |
+| `$ne` | Not equal to |
+| `$gt` | Greater than |
+| `$gte` | Greater than or equal |
+| `$lt` | Less than |
+| `$lte` | Less than or equal |
+| `$in` | In array |
+| `$nin` | Not in array |
+| `$and` | Logical AND |
+| `$or` | Logical OR |
+
+## Architecture
+
+ConvexVector stores vectors in the `mastra_vectors` table with the following structure:
+
+- `id`: Unique vector identifier
+- `indexName`: Name of the index
+- `embedding`: The vector data (array of floats)
+- `metadata`: Optional JSON metadata
+
+Vector similarity search is performed using cosine similarity, computed in the Convex function.
+
+## Related
+
+- [Convex Storage](../storage/convex)
+- [Metadata Filters](../rag/metadata-filters)
+- [Convex Documentation](https://docs.convex.dev/)

package/dist/index.cjs

@@ -1,7 +1,7 @@
 'use strict';
 
 var chunkBKVR7SL7_cjs = require('./chunk-BKVR7SL7.cjs');
-var chunkZBUP3DS6_cjs = require('./chunk-ZBUP3DS6.cjs');
+var chunkFTVDAP6U_cjs = require('./chunk-FTVDAP6U.cjs');
 var storage = require('@mastra/core/storage');
 var agent = require('@mastra/core/agent');
 var error = require('@mastra/core/error');
@@ -90,6 +90,19 @@ var ConvexDB = class extends base.MastraBase {
   async hasColumn(_table, _column) {
     return true;
   }
+  async createTable({
+    tableName,
+    schema: _schema
+  }) {
+    this.logger.debug(`ConvexDB: createTable called for ${tableName} (schema managed server-side)`);
+  }
+  async alterTable({
+    tableName,
+    schema: _schema,
+    ifNotExists: _ifNotExists
+  }) {
+    this.logger.debug(`ConvexDB: alterTable called for ${tableName} (schema managed server-side)`);
+  }
   async clearTable({ tableName }) {
     let hasMore = true;
     while (hasMore) {
@@ -241,18 +254,41 @@ var MemoryConvex = class extends storage.MemoryStorage {
     );
     await this.#db.deleteMany(storage.TABLE_THREADS, [threadId]);
   }
-  async listThreadsByResourceId(args) {
-    const { resourceId, page = 0, perPage: perPageInput, orderBy } = args;
+  async listThreads(args) {
+    const { page = 0, perPage: perPageInput, orderBy, filter } = args;
+    try {
+      this.validatePaginationInput(page, perPageInput ?? 100);
+    } catch (error$1) {
+      throw new error.MastraError(
+        {
+          id: storage.createStorageErrorId("CONVEX", "LIST_THREADS", "INVALID_PAGE"),
+          domain: error.ErrorDomain.STORAGE,
+          category: error.ErrorCategory.USER,
+          details: { page, ...perPageInput !== void 0 && { perPage: perPageInput } }
+        },
+        error$1 instanceof Error ? error$1 : new Error("Invalid pagination parameters")
+      );
+    }
     const perPage = storage.normalizePerPage(perPageInput, 100);
     const { field, direction } = this.parseOrderBy(orderBy);
     const { offset, perPage: perPageForResponse } = storage.calculatePagination(page, perPageInput, perPage);
-    const rows = await this.#db.queryTable(storage.TABLE_THREADS, [{ field: "resourceId", value: resourceId }]);
-    const threads = rows.map((row) => ({
+    const queryFilters = [];
+    if (filter?.resourceId) {
+      queryFilters.push({ field: "resourceId", value: filter.resourceId });
+    }
+    const rows = await this.#db.queryTable(storage.TABLE_THREADS, queryFilters);
+    let threads = rows.map((row) => ({
       ...row,
       metadata: typeof row.metadata === "string" ? JSON.parse(row.metadata) : row.metadata,
       createdAt: new Date(row.createdAt),
       updatedAt: new Date(row.updatedAt)
     }));
+    if (filter?.metadata && Object.keys(filter.metadata).length > 0) {
+      threads = threads.filter((thread) => {
+        if (!thread.metadata) return false;
+        return Object.entries(filter.metadata).every(([key, value]) => thread.metadata[key] === value);
+      });
+    }
     threads.sort((a, b) => {
       const aValue = a[field];
       const bValue = b[field];
@@ -295,15 +331,7 @@ var MemoryConvex = class extends storage.MemoryStorage {
     if (resourceId) {
       rows = rows.filter((row) => row.resourceId === resourceId);
     }
-    if (filter?.dateRange) {
-      const { start, end } = filter.dateRange;
-      rows = rows.filter((row) => {
-        const created = new Date(row.createdAt).getTime();
-        if (start && created < start.getTime()) return false;
-        if (end && created > end.getTime()) return false;
-        return true;
-      });
-    }
+    rows = storage.filterByDateRange(rows, (row) => new Date(row.createdAt), filter?.dateRange);
     rows.sort((a, b) => {
       const aValue = field === "createdAt" || field === "updatedAt" ? new Date(a[field]).getTime() : a[field];
       const bValue = field === "createdAt" || field === "updatedAt" ? new Date(b[field]).getTime() : b[field];
@@ -859,143 +887,23 @@ var WorkflowsConvex = class extends storage.WorkflowsStorage {
 };
 
 // src/storage/index.ts
-var ConvexStore = class extends storage.MastraStorage {
-  memory;
-  workflows;
-  scores;
+var isClientConfig = (config) => {
+  return "client" in config;
+};
+var ConvexStore = class extends storage.MastraCompositeStore {
   constructor(config) {
     super({ id: config.id, name: config.name ?? "ConvexStore", disableInit: config.disableInit });
-    const client = new ConvexAdminClient(config);
+    const client = isClientConfig(config) ? config.client : new ConvexAdminClient(config);
     const domainConfig = { client };
-    this.memory = new MemoryConvex(domainConfig);
-    this.workflows = new WorkflowsConvex(domainConfig);
-    this.scores = new ScoresConvex(domainConfig);
+    const memory = new MemoryConvex(domainConfig);
+    const workflows = new WorkflowsConvex(domainConfig);
+    const scores = new ScoresConvex(domainConfig);
     this.stores = {
-      memory: this.memory,
-      workflows: this.workflows,
-      scores: this.scores
-    };
-  }
-  get supports() {
-    return {
-      selectByIncludeResourceScope: true,
-      resourceWorkingMemory: true,
-      hasColumn: false,
-      createTable: false,
-      deleteMessages: true,
-      observabilityInstance: false,
-      listScoresBySpan: false
+      memory,
+      workflows,
+      scores
     };
   }
-  async getThreadById({ threadId }) {
-    return this.memory.getThreadById({ threadId });
-  }
-  async saveThread({ thread }) {
-    return this.memory.saveThread({ thread });
-  }
-  async updateThread({
-    id,
-    title,
-    metadata
-  }) {
-    return this.memory.updateThread({ id, title, metadata });
-  }
-  async deleteThread({ threadId }) {
-    await this.memory.deleteThread({ threadId });
-  }
-  async listMessages(args) {
-    return this.memory.listMessages(args);
-  }
-  async listMessagesById({ messageIds }) {
-    return this.memory.listMessagesById({ messageIds });
-  }
-  async saveMessages(args) {
-    return this.memory.saveMessages(args);
-  }
-  async updateMessages({
-    messages
-  }) {
-    return this.memory.updateMessages({ messages });
-  }
-  async deleteMessages(messageIds) {
-    await this.memory.deleteMessages(messageIds);
-  }
-  async listThreadsByResourceId(args) {
-    return this.memory.listThreadsByResourceId(args);
-  }
-  async getResourceById({ resourceId }) {
-    return this.memory.getResourceById({ resourceId });
-  }
-  async saveResource({ resource }) {
-    return this.memory.saveResource({ resource });
-  }
-  async updateResource({
-    resourceId,
-    workingMemory,
-    metadata
-  }) {
-    return this.memory.updateResource({ resourceId, workingMemory, metadata });
-  }
-  async updateWorkflowResults(params) {
-    return this.workflows.updateWorkflowResults(params);
-  }
-  async updateWorkflowState(params) {
-    return this.workflows.updateWorkflowState(params);
-  }
-  async persistWorkflowSnapshot({
-    workflowName,
-    runId,
-    resourceId,
-    snapshot
-  }) {
-    await this.workflows.persistWorkflowSnapshot({ workflowName, runId, resourceId, snapshot });
-  }
-  async loadWorkflowSnapshot({
-    workflowName,
-    runId
-  }) {
-    return this.workflows.loadWorkflowSnapshot({ workflowName, runId });
-  }
-  async listWorkflowRuns(args) {
-    return this.workflows.listWorkflowRuns(args);
-  }
-  async getWorkflowRunById({
-    runId,
-    workflowName
-  }) {
-    return this.workflows.getWorkflowRunById({ runId, workflowName });
-  }
-  async deleteWorkflowRunById({ runId, workflowName }) {
-    return this.workflows.deleteWorkflowRunById({ runId, workflowName });
-  }
-  async getScoreById({ id }) {
-    return this.scores.getScoreById({ id });
-  }
-  async saveScore(score) {
-    return this.scores.saveScore(score);
-  }
-  async listScoresByScorerId({
-    scorerId,
-    pagination,
-    entityId,
-    entityType,
-    source
-  }) {
-    return this.scores.listScoresByScorerId({ scorerId, pagination, entityId, entityType, source });
-  }
-  async listScoresByRunId({
-    runId,
-    pagination
-  }) {
-    return this.scores.listScoresByRunId({ runId, pagination });
-  }
-  async listScoresByEntityId({
-    entityId,
-    entityType,
-    pagination
-  }) {
-    return this.scores.listScoresByEntityId({ entityId, entityType, pagination });
-  }
 };
 var INDEX_METADATA_TABLE = "mastra_vector_indexes";
 var ConvexVector = class extends vector.MastraVector {
@@ -1306,55 +1214,55 @@ Object.defineProperty(exports, "mastraStorage", {
 });
 Object.defineProperty(exports, "TABLE_MESSAGES", {
   enumerable: true,
-  get: function () { return chunkZBUP3DS6_cjs.TABLE_MESSAGES; }
+  get: function () { return chunkFTVDAP6U_cjs.TABLE_MESSAGES; }
 });
 Object.defineProperty(exports, "TABLE_RESOURCES", {
   enumerable: true,
-  get: function () { return chunkZBUP3DS6_cjs.TABLE_RESOURCES; }
+  get: function () { return chunkFTVDAP6U_cjs.TABLE_RESOURCES; }
 });
 Object.defineProperty(exports, "TABLE_SCORERS", {
   enumerable: true,
-  get: function () { return chunkZBUP3DS6_cjs.TABLE_SCORERS; }
+  get: function () { return chunkFTVDAP6U_cjs.TABLE_SCORERS; }
 });
 Object.defineProperty(exports, "TABLE_THREADS", {
   enumerable: true,
-  get: function () { return chunkZBUP3DS6_cjs.TABLE_THREADS; }
+  get: function () { return chunkFTVDAP6U_cjs.TABLE_THREADS; }
 });
 Object.defineProperty(exports, "TABLE_WORKFLOW_SNAPSHOT", {
   enumerable: true,
-  get: function () { return chunkZBUP3DS6_cjs.TABLE_WORKFLOW_SNAPSHOT; }
+  get: function () { return chunkFTVDAP6U_cjs.TABLE_WORKFLOW_SNAPSHOT; }
 });
 Object.defineProperty(exports, "mastraDocumentsTable", {
   enumerable: true,
-  get: function () { return chunkZBUP3DS6_cjs.mastraDocumentsTable; }
+  get: function () { return chunkFTVDAP6U_cjs.mastraDocumentsTable; }
 });
 Object.defineProperty(exports, "mastraMessagesTable", {
   enumerable: true,
-  get: function () { return chunkZBUP3DS6_cjs.mastraMessagesTable; }
+  get: function () { return chunkFTVDAP6U_cjs.mastraMessagesTable; }
 });
 Object.defineProperty(exports, "mastraResourcesTable", {
   enumerable: true,
-  get: function () { return chunkZBUP3DS6_cjs.mastraResourcesTable; }
+  get: function () { return chunkFTVDAP6U_cjs.mastraResourcesTable; }
 });
 Object.defineProperty(exports, "mastraScoresTable", {
   enumerable: true,
-  get: function () { return chunkZBUP3DS6_cjs.mastraScoresTable; }
+  get: function () { return chunkFTVDAP6U_cjs.mastraScoresTable; }
 });
 Object.defineProperty(exports, "mastraThreadsTable", {
   enumerable: true,
-  get: function () { return chunkZBUP3DS6_cjs.mastraThreadsTable; }
+  get: function () { return chunkFTVDAP6U_cjs.mastraThreadsTable; }
 });
 Object.defineProperty(exports, "mastraVectorIndexesTable", {
   enumerable: true,
-  get: function () { return chunkZBUP3DS6_cjs.mastraVectorIndexesTable; }
+  get: function () { return chunkFTVDAP6U_cjs.mastraVectorIndexesTable; }
 });
 Object.defineProperty(exports, "mastraVectorsTable", {
   enumerable: true,
-  get: function () { return chunkZBUP3DS6_cjs.mastraVectorsTable; }
+  get: function () { return chunkFTVDAP6U_cjs.mastraVectorsTable; }
 });
 Object.defineProperty(exports, "mastraWorkflowSnapshotsTable", {
   enumerable: true,
-  get: function () { return chunkZBUP3DS6_cjs.mastraWorkflowSnapshotsTable; }
+  get: function () { return chunkFTVDAP6U_cjs.mastraWorkflowSnapshotsTable; }
 });
 exports.ConvexStore = ConvexStore;
 exports.ConvexVector = ConvexVector;