@mastra/mcp-docs-server 1.0.0-beta.4 → 1.0.0-beta.6

package/.docs/raw/reference/tools/vector-query-tool.mdx

@@ -13,13 +13,13 @@ The `createVectorQueryTool()` function creates a tool for semantic search over v
 ## Basic Usage
 
 ```typescript
-import { openai } from "@ai-sdk/openai";
 import { createVectorQueryTool } from "@mastra/rag";
+import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
 
 const queryTool = createVectorQueryTool({
   vectorStoreName: "pinecone",
   indexName: "docs",
-  model: openai.embedding("text-embedding-3-small"),
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
 });
 ```
 
@@ -303,7 +303,7 @@ The tool determines the number of results to return based on the user's query, w
 const queryTool = createVectorQueryTool({
   vectorStoreName: "pinecone",
   indexName: "docs",
-  model: openai.embedding("text-embedding-3-small"),
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
   enableFilter: true,
 });
 ```
@@ -334,9 +334,9 @@ For an example of how agent-driven filtering works, see the [Agent-Driven Metada
 const queryTool = createVectorQueryTool({
   vectorStoreName: "milvus",
   indexName: "documentation",
-  model: openai.embedding("text-embedding-3-small"),
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
   reranker: {
-    model: openai("gpt-4o-mini"),
+    model: "openai/gpt-5.1",
     options: {
       weights: {
         semantic: 0.5, // Semantic relevance weight
@@ -364,7 +364,7 @@ The reranker processes the initial vector search results and returns a reordered
 const queryTool = createVectorQueryTool({
   vectorStoreName: "pinecone",
   indexName: "docs",
-  model: openai.embedding("text-embedding-3-small"),
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
   description:
     "Search through document archives to find relevant information for answering questions about company policies and procedures",
 });
@@ -384,7 +384,7 @@ The `databaseConfig` parameter allows you to leverage unique features and optimi
     const pineconeQueryTool = createVectorQueryTool({
       vectorStoreName: "pinecone",
       indexName: "docs",
-      model: openai.embedding("text-embedding-3-small"),
+      model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
       databaseConfig: {
         pinecone: {
           namespace: "production",  // Organize vectors by environment
@@ -411,7 +411,7 @@ The `databaseConfig` parameter allows you to leverage unique features and optimi
     const pgVectorQueryTool = createVectorQueryTool({
       vectorStoreName: "postgres",
       indexName: "embeddings",
-      model: openai.embedding("text-embedding-3-small"),
+      model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
       databaseConfig: {
         pgvector: {
           minScore: 0.7,    // Only return results above 70% similarity
@@ -437,7 +437,7 @@ The `databaseConfig` parameter allows you to leverage unique features and optimi
     const chromaQueryTool = createVectorQueryTool({
       vectorStoreName: "chroma",
       indexName: "documents",
-      model: openai.embedding("text-embedding-3-small"),
+      model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
       databaseConfig: {
         chroma: {
           where: {                    // Metadata filtering
@@ -467,7 +467,7 @@ The `databaseConfig` parameter allows you to leverage unique features and optimi
     const multiDbQueryTool = createVectorQueryTool({
       vectorStoreName: "dynamic-store", // Will be set at runtime
       indexName: "docs",
-      model: openai.embedding("text-embedding-3-small"),
+      model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
       databaseConfig: {
         pinecone: {
           namespace: "default"
@@ -501,7 +501,7 @@ import { RequestContext } from "@mastra/core/request-context";
 const queryTool = createVectorQueryTool({
   vectorStoreName: "pinecone",
   indexName: "docs",
-  model: openai.embedding("text-embedding-3-small"),
+      model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
   databaseConfig: {
     pinecone: {
       namespace: "development",
@@ -534,7 +534,7 @@ This approach allows you to:
 const queryTool = createVectorQueryTool({
   vectorStoreName: "pinecone",
   indexName: "docs",
-  model: openai.embedding("text-embedding-3-small"),
+      model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
 });
 ```
 
@@ -555,7 +555,7 @@ requestContext.set("filter", { category: "docs" });
 requestContext.set("databaseConfig", {
   pinecone: { namespace: "runtime-namespace" },
 });
-requestContext.set("model", openai.embedding("text-embedding-3-small"));
+requestContext.set("model", "openai/text-embedding-3-small");
 
 const response = await agent.generate(
   "Find documentation from the knowledge base.",
@@ -575,7 +575,6 @@ For more information on request context, please see:
 The tool can be used by itself to retrieve documents matching a query:
 
 ```typescript copy showLineNumbers title="src/index.ts"
-import { openai } from "@ai-sdk/openai";
 import { RequestContext } from "@mastra/core/request-context";
 import { createVectorQueryTool } from "@mastra/rag";
 import { PgVector } from "@mastra/pg";
@@ -589,7 +588,7 @@ const vectorQueryTool = createVectorQueryTool({
   vectorStoreName: "pgVector", // optional since we're passing in a store
   vectorStore: pgVector,
   indexName: "embeddings",
-  model: openai.embedding("text-embedding-3-small"),
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
 });
 
 const requestContext = new RequestContext();

package/.docs/raw/reference/vectors/chroma.mdx

@@ -335,6 +335,8 @@ interface IndexStats {
 
 ### updateVector()
 
+Update a single vector by ID or by metadata filter. Either `id` or `filter` must be provided, but not both.
+
 <PropertiesTable
   content={[
     {
@@ -345,7 +347,14 @@ interface IndexStats {
     {
       name: "id",
       type: "string",
-      description: "ID of the vector to update",
+      isOptional: true,
+      description: "ID of the vector to update (mutually exclusive with filter)",
+    },
+    {
+      name: "filter",
+      type: "Record<string, any>",
+      isOptional: true,
+      description: "Metadata filter to identify vector(s) to update (mutually exclusive with id)",
     },
     {
       name: "update",
@@ -374,6 +383,24 @@ The `update` object can contain:
   ]}
 />
 
+Example:
+
+```typescript
+// Update by ID
+await vectorStore.updateVector({
+  indexName: 'docs',
+  id: 'vec_123',
+  update: { metadata: { status: 'reviewed' } }
+});
+
+// Update by filter
+await vectorStore.updateVector({
+  indexName: 'docs',
+  filter: { source_id: 'manual.pdf' },
+  update: { metadata: { version: 2 } }
+});
+```
+
 ### deleteVector()
 
 <PropertiesTable
@@ -391,6 +418,59 @@ The `update` object can contain:
   ]}
 />
 
+### deleteVectors()
+
+Delete multiple vectors by IDs or by metadata filter. This method enables bulk deletion and source-based vector management. Either `ids` or `filter` must be provided, but not both.
+
+<PropertiesTable
+  content={[
+    {
+      name: "indexName",
+      type: "string",
+      description: "Name of the index containing the vectors to delete",
+    },
+    {
+      name: "ids",
+      type: "string[]",
+      isOptional: true,
+      description: "Array of vector IDs to delete (mutually exclusive with filter)",
+    },
+    {
+      name: "filter",
+      type: "Record<string, any>",
+      isOptional: true,
+      description: "Metadata filter to identify vectors to delete (mutually exclusive with ids)",
+    },
+  ]}
+/>
+
+Example:
+
+```typescript
+// Delete all chunks from a document
+await vectorStore.deleteVectors({
+  indexName: 'docs',
+  filter: { source_id: 'manual.pdf' }
+});
+
+// Delete multiple vectors by ID
+await vectorStore.deleteVectors({
+  indexName: 'docs',
+  ids: ['vec_1', 'vec_2', 'vec_3']
+});
+
+// Delete old temporary documents
+await vectorStore.deleteVectors({
+  indexName: 'docs',
+  filter: {
+    $and: [
+      { bucket: 'temp' },
+      { indexed_at: { $lt: '2025-01-01' } }
+    ]
+  }
+});
+```
+
 ## Response Types
 
 Query results are returned in this format:

package/.docs/raw/reference/vectors/convex.mdx

@@ -0,0 +1,429 @@
+---
+title: "Reference: Convex Vector Store | Vectors"
+description: Documentation for the ConvexVector class in Mastra, which provides vector search using Convex.
+---
+
+# Convex Vector Store
+
+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 copy
+npm install @mastra/convex@beta
+```
+
+## 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
+
+<PropertiesTable
+  content={[
+    {
+      name: "deploymentUrl",
+      type: "string",
+      description: "Convex deployment URL (e.g., https://your-project.convex.cloud)",
+      isOptional: false,
+    },
+    {
+      name: "adminAuthToken",
+      type: "string",
+      description: "Convex admin authentication token",
+      isOptional: false,
+    },
+    {
+      name: "storageFunction",
+      type: "string",
+      description: "Path to the storage mutation function",
+      isOptional: true,
+      defaultValue: "mastra/storage:handle",
+    },
+  ]}
+/>
+
+## 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()
+
+<PropertiesTable
+  content={[
+    {
+      name: "indexName",
+      type: "string",
+      description: "Name of the index to create",
+    },
+    {
+      name: "dimension",
+      type: "number",
+      description: "Vector dimension (must match your embedding model)",
+    },
+    {
+      name: "metric",
+      type: "'cosine' | 'euclidean' | 'dotproduct'",
+      isOptional: true,
+      defaultValue: "cosine",
+      description: "Distance metric for similarity search (only cosine is currently supported)",
+    },
+  ]}
+/>
+
+```typescript copy
+await vectorStore.createIndex({
+  indexName: "my_vectors",
+  dimension: 1536,
+});
+```
+
+### upsert()
+
+<PropertiesTable
+  content={[
+    {
+      name: "indexName",
+      type: "string",
+      description: "Name of the index to upsert vectors into",
+    },
+    {
+      name: "vectors",
+      type: "number[][]",
+      description: "Array of embedding vectors",
+    },
+    {
+      name: "metadata",
+      type: "Record<string, any>[]",
+      isOptional: true,
+      description: "Metadata for each vector",
+    },
+    {
+      name: "ids",
+      type: "string[]",
+      isOptional: true,
+      description: "Optional vector IDs (auto-generated if not provided)",
+    },
+  ]}
+/>
+
+```typescript copy
+await vectorStore.upsert({
+  indexName: "my_vectors",
+  vectors: [[0.1, 0.2, 0.3, ...]],
+  metadata: [{ label: "example" }],
+  ids: ["vec-1"],
+});
+```
+
+### query()
+
+<PropertiesTable
+  content={[
+    {
+      name: "indexName",
+      type: "string",
+      description: "Name of the index to query",
+    },
+    {
+      name: "queryVector",
+      type: "number[]",
+      description: "Query vector",
+    },
+    {
+      name: "topK",
+      type: "number",
+      isOptional: true,
+      defaultValue: "10",
+      description: "Number of results to return",
+    },
+    {
+      name: "filter",
+      type: "Record<string, any>",
+      isOptional: true,
+      description: "Metadata filters",
+    },
+    {
+      name: "includeVector",
+      type: "boolean",
+      isOptional: true,
+      defaultValue: "false",
+      description: "Whether to include the vector in the result",
+    },
+  ]}
+/>
+
+```typescript copy
+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 copy
+const indexes = await vectorStore.listIndexes();
+// ["my_vectors", "embeddings", ...]
+```
+
+### describeIndex()
+
+<PropertiesTable
+  content={[
+    {
+      name: "indexName",
+      type: "string",
+      description: "Name of the index to describe",
+    },
+  ]}
+/>
+
+Returns:
+
+```typescript copy
+interface IndexStats {
+  dimension: number;
+  count: number;
+  metric: "cosine" | "euclidean" | "dotproduct";
+}
+```
+
+### deleteIndex()
+
+<PropertiesTable
+  content={[
+    {
+      name: "indexName",
+      type: "string",
+      description: "Name of the index to delete",
+    },
+  ]}
+/>
+
+Deletes the index and all its vectors.
+
+```typescript copy
+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.
+
+<PropertiesTable
+  content={[
+    {
+      name: "indexName",
+      type: "string",
+      description: "Name of the index containing the vector",
+    },
+    {
+      name: "id",
+      type: "string",
+      isOptional: true,
+      description: "ID of the vector to update (mutually exclusive with filter)",
+    },
+    {
+      name: "filter",
+      type: "Record<string, any>",
+      isOptional: true,
+      description: "Metadata filter to identify vector(s) to update (mutually exclusive with id)",
+    },
+    {
+      name: "update",
+      type: "{ vector?: number[]; metadata?: Record<string, any>; }",
+      description: "Object containing the vector and/or metadata to update",
+    },
+  ]}
+/>
+
+```typescript copy
+// 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()
+
+<PropertiesTable
+  content={[
+    {
+      name: "indexName",
+      type: "string",
+      description: "Name of the index containing the vector",
+    },
+    {
+      name: "id",
+      type: "string",
+      description: "ID of the vector to delete",
+    },
+  ]}
+/>
+
+```typescript copy
+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.
+
+<PropertiesTable
+  content={[
+    {
+      name: "indexName",
+      type: "string",
+      description: "Name of the index containing the vectors to delete",
+    },
+    {
+      name: "ids",
+      type: "string[]",
+      isOptional: true,
+      description: "Array of vector IDs to delete (mutually exclusive with filter)",
+    },
+    {
+      name: "filter",
+      type: "Record<string, any>",
+      isOptional: true,
+      description: "Metadata filter to identify vectors to delete (mutually exclusive with ids)",
+    },
+  ]}
+/>
+
+```typescript copy
+// 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 copy
+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 copy
+// 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/)
+