@mastra/upstash 1.0.0-beta.8 → 1.0.0

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

@@ -0,0 +1,233 @@
+# Vectors API Reference
+
+> API reference for vectors - 1 entries
+
+
+---
+
+## Reference: Upstash Vector Store
+
+> Documentation for the UpstashVector class in Mastra, which provides vector search using Upstash Vector.
+
+The UpstashVector class provides vector search using [Upstash Vector](https://upstash.com/vector), a serverless vector database service that provides vector similarity search with metadata filtering capabilities and hybrid search support.
+
+## Constructor Options
+
+## Methods
+
+### createIndex()
+
+Note: This method is a no-op for Upstash as indexes are created automatically.
+
+### upsert()
+
+### query()
+
+### listIndexes()
+
+Returns an array of index names (namespaces) as strings.
+
+### describeIndex()
+
+Returns:
+
+```typescript
+interface IndexStats {
+  dimension: number;
+  count: number;
+  metric: "cosine" | "euclidean" | "dotproduct";
+}
+```
+
+### deleteIndex()
+
+### updateVector()
+
+The `update` object can have the following properties:
+
+- `vector` (optional): An array of numbers representing the new dense vector.
+- `sparseVector` (optional): A sparse vector object with `indices` and `values` arrays for hybrid indexes.
+- `metadata` (optional): A record of key-value pairs for metadata.
+
+### deleteVector()
+
+Attempts to delete an item by its ID from the specified index. Logs an error message if the deletion fails.
+
+## Hybrid Vector Search
+
+Upstash Vector supports hybrid search that combines semantic search (dense vectors) with keyword-based search (sparse vectors) for improved relevance and accuracy.
+
+### Basic Hybrid Usage
+
+```typescript
+import { UpstashVector } from "@mastra/upstash";
+
+const vectorStore = new UpstashVector({
+  id: 'upstash-vector',
+  url: process.env.UPSTASH_VECTOR_URL,
+  token: process.env.UPSTASH_VECTOR_TOKEN,
+});
+
+// Upsert vectors with both dense and sparse components
+const denseVectors = [
+  [0.1, 0.2, 0.3],
+  [0.4, 0.5, 0.6],
+];
+const sparseVectors = [
+  { indices: [1, 5, 10], values: [0.8, 0.6, 0.4] },
+  { indices: [2, 6, 11], values: [0.7, 0.5, 0.3] },
+];
+
+await vectorStore.upsert({
+  indexName: "hybrid-index",
+  vectors: denseVectors,
+  sparseVectors: sparseVectors,
+  metadata: [{ title: "Document 1" }, { title: "Document 2" }],
+});
+
+// Query with hybrid search
+const results = await vectorStore.query({
+  indexName: "hybrid-index",
+  queryVector: [0.1, 0.2, 0.3],
+  sparseVector: { indices: [1, 5], values: [0.9, 0.7] },
+  topK: 10,
+});
+```
+
+### Advanced Hybrid Search Options
+
+```typescript
+import { FusionAlgorithm, QueryMode } from "@upstash/vector";
+
+// Query with specific fusion algorithm
+const fusionResults = await vectorStore.query({
+  indexName: "hybrid-index",
+  queryVector: [0.1, 0.2, 0.3],
+  sparseVector: { indices: [1, 5], values: [0.9, 0.7] },
+  fusionAlgorithm: FusionAlgorithm.RRF,
+  topK: 10,
+});
+
+// Dense-only search
+const denseResults = await vectorStore.query({
+  indexName: "hybrid-index",
+  queryVector: [0.1, 0.2, 0.3],
+  queryMode: QueryMode.DENSE,
+  topK: 10,
+});
+
+// Sparse-only search
+const sparseResults = await vectorStore.query({
+  indexName: "hybrid-index",
+  queryVector: [0.1, 0.2, 0.3], // Still required for index structure
+  sparseVector: { indices: [1, 5], values: [0.9, 0.7] },
+  queryMode: QueryMode.SPARSE,
+  topK: 10,
+});
+```
+
+### Updating Hybrid Vectors
+
+```typescript
+// Update both dense and sparse components
+await vectorStore.updateVector({
+  indexName: "hybrid-index",
+  id: "vector-id",
+  update: {
+    vector: [0.2, 0.3, 0.4],
+    sparseVector: { indices: [2, 7, 12], values: [0.9, 0.8, 0.6] },
+    metadata: { title: "Updated Document" },
+  },
+});
+```
+
+## 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
+}
+```
+
+## Error Handling
+
+The store throws typed errors that can be caught:
+
+```typescript
+try {
+  await store.query({
+    indexName: "index_name",
+    queryVector: queryVector,
+  });
+} catch (error) {
+  if (error instanceof VectorStoreError) {
+    console.log(error.code); // 'connection_failed' | 'invalid_dimension' | etc
+    console.log(error.details); // Additional error context
+  }
+}
+```
+
+## Environment Variables
+
+Required environment variables:
+
+- `UPSTASH_VECTOR_URL`: Your Upstash Vector database URL
+- `UPSTASH_VECTOR_TOKEN`: Your Upstash Vector API token
+
+## Usage Example
+
+### Local embeddings with fastembed
+
+Embeddings are numeric vectors used by memory's `semanticRecall` to retrieve related messages by meaning (not keywords). This setup uses `@mastra/fastembed` to generate vector embeddings.
+
+Install `fastembed` to get started:
+
+```bash
+npm install @mastra/fastembed@beta
+```
+
+Add the following to your agent:
+
+```typescript title="src/mastra/agents/example-upstash-agent.ts"
+import { Memory } from "@mastra/memory";
+import { Agent } from "@mastra/core/agent";
+import { UpstashStore, UpstashVector } from "@mastra/upstash";
+import { fastembed } from "@mastra/fastembed";
+
+export const upstashAgent = new Agent({
+  id: "upstash-agent",
+  name: "Upstash Agent",
+  instructions:
+    "You are an AI agent with the ability to automatically recall memories from previous interactions.",
+  model: "openai/gpt-5.1",
+  memory: new Memory({
+    storage: new UpstashStore({
+      id: 'upstash-agent-storage',
+      url: process.env.UPSTASH_REDIS_REST_URL!,
+      token: process.env.UPSTASH_REDIS_REST_TOKEN!,
+    }),
+    vector: new UpstashVector({
+      id: 'upstash-agent-vector',
+      url: process.env.UPSTASH_VECTOR_REST_URL!,
+      token: process.env.UPSTASH_VECTOR_REST_TOKEN!,
+    }),
+    embedder: fastembed,
+    options: {
+      lastMessages: 10,
+      semanticRecall: {
+        topK: 3,
+        messageRange: 2,
+      },
+    },
+  }),
+});
+```
+
+## Related
+
+- [Metadata Filters](../rag/metadata-filters)

package/dist/index.cjs

@@ -192,19 +192,34 @@ var StoreMemoryUpstash = class extends storage.MemoryStorage {
       );
     }
   }
-  async listThreadsByResourceId(args) {
-    const { resourceId, page = 0, perPage: perPageInput, orderBy } = args;
+  async listThreads(args) {
+    const { page = 0, perPage: perPageInput, orderBy, filter } = args;
     const { field, direction } = this.parseOrderBy(orderBy);
+    try {
+      this.validatePaginationInput(page, perPageInput ?? 100);
+    } catch (error$1) {
+      throw new error.MastraError(
+        {
+          id: storage.createStorageErrorId("UPSTASH", "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);
-    if (page < 0) {
+    try {
+      this.validateMetadataKeys(filter?.metadata);
+    } catch (error$1) {
       throw new error.MastraError(
         {
-          id: storage.createStorageErrorId("UPSTASH", "LIST_THREADS_BY_RESOURCE_ID", "INVALID_PAGE"),
+          id: storage.createStorageErrorId("UPSTASH", "LIST_THREADS", "INVALID_METADATA_KEY"),
           domain: error.ErrorDomain.STORAGE,
           category: error.ErrorCategory.USER,
-          details: { page }
+          details: { metadataKeys: filter?.metadata ? Object.keys(filter.metadata).join(", ") : "" }
         },
-        new Error("page must be >= 0")
+        error$1 instanceof Error ? error$1 : new Error("Invalid metadata key")
       );
     }
     const { offset, perPage: perPageForResponse } = storage.calculatePagination(page, perPageInput, perPage);
@@ -212,19 +227,35 @@ var StoreMemoryUpstash = class extends storage.MemoryStorage {
       let allThreads = [];
       const pattern = `${storage.TABLE_THREADS}:*`;
       const keys = await this.#db.scanKeys(pattern);
+      if (keys.length === 0) {
+        return {
+          threads: [],
+          total: 0,
+          page,
+          perPage: perPageForResponse,
+          hasMore: false
+        };
+      }
       const pipeline = this.client.pipeline();
       keys.forEach((key) => pipeline.get(key));
       const results = await pipeline.exec();
       for (let i = 0; i < results.length; i++) {
         const thread = results[i];
-        if (thread && thread.resourceId === resourceId) {
-          allThreads.push({
-            ...thread,
-            createdAt: storage.ensureDate(thread.createdAt),
-            updatedAt: storage.ensureDate(thread.updatedAt),
-            metadata: typeof thread.metadata === "string" ? JSON.parse(thread.metadata) : thread.metadata
-          });
+        if (!thread) continue;
+        if (filter?.resourceId && thread.resourceId !== filter.resourceId) {
+          continue;
         }
+        if (filter?.metadata && Object.keys(filter.metadata).length > 0) {
+          const threadMetadata = typeof thread.metadata === "string" ? JSON.parse(thread.metadata) : thread.metadata;
+          const matches = Object.entries(filter.metadata).every(([key, value]) => threadMetadata?.[key] === value);
+          if (!matches) continue;
+        }
+        allThreads.push({
+          ...thread,
+          createdAt: storage.ensureDate(thread.createdAt),
+          updatedAt: storage.ensureDate(thread.updatedAt),
+          metadata: typeof thread.metadata === "string" ? JSON.parse(thread.metadata) : thread.metadata
+        });
       }
       const sortedThreads = this.sortThreads(allThreads, field, direction);
       const total = sortedThreads.length;
@@ -241,11 +272,12 @@ var StoreMemoryUpstash = class extends storage.MemoryStorage {
     } catch (error$1) {
       const mastraError = new error.MastraError(
         {
-          id: storage.createStorageErrorId("UPSTASH", "LIST_THREADS_BY_RESOURCE_ID", "FAILED"),
+          id: storage.createStorageErrorId("UPSTASH", "LIST_THREADS", "FAILED"),
           domain: error.ErrorDomain.STORAGE,
           category: error.ErrorCategory.THIRD_PARTY,
           details: {
-            resourceId,
+            ...filter?.resourceId && { resourceId: filter.resourceId },
+            hasMetadataFilter: !!filter?.metadata,
             page,
             perPage
           }
@@ -637,15 +669,11 @@ var StoreMemoryUpstash = class extends storage.MemoryStorage {
       if (resourceId) {
         messagesData = messagesData.filter((msg) => msg.resourceId === resourceId);
       }
-      const dateRange = filter?.dateRange;
-      if (dateRange?.start) {
-        const fromDate = dateRange.start;
-        messagesData = messagesData.filter((msg) => new Date(msg.createdAt).getTime() >= fromDate.getTime());
-      }
-      if (dateRange?.end) {
-        const toDate = dateRange.end;
-        messagesData = messagesData.filter((msg) => new Date(msg.createdAt).getTime() <= toDate.getTime());
-      }
+      messagesData = storage.filterByDateRange(
+        messagesData,
+        (msg) => new Date(msg.createdAt),
+        filter?.dateRange
+      );
       const { field, direction } = this.parseOrderBy(orderBy, "ASC");
       const getFieldValue = (msg) => {
         if (field === "createdAt") {
@@ -993,6 +1021,118 @@ var StoreMemoryUpstash = class extends storage.MemoryStorage {
       }
     });
   }
+  async cloneThread(args) {
+    const { sourceThreadId, newThreadId: providedThreadId, resourceId, title, metadata, options } = args;
+    const sourceThread = await this.getThreadById({ threadId: sourceThreadId });
+    if (!sourceThread) {
+      throw new error.MastraError({
+        id: storage.createStorageErrorId("UPSTASH", "CLONE_THREAD", "SOURCE_NOT_FOUND"),
+        domain: error.ErrorDomain.STORAGE,
+        category: error.ErrorCategory.USER,
+        text: `Source thread with id ${sourceThreadId} not found`,
+        details: { sourceThreadId }
+      });
+    }
+    const newThreadId = providedThreadId || crypto.randomUUID();
+    const existingThread = await this.getThreadById({ threadId: newThreadId });
+    if (existingThread) {
+      throw new error.MastraError({
+        id: storage.createStorageErrorId("UPSTASH", "CLONE_THREAD", "THREAD_EXISTS"),
+        domain: error.ErrorDomain.STORAGE,
+        category: error.ErrorCategory.USER,
+        text: `Thread with id ${newThreadId} already exists`,
+        details: { newThreadId }
+      });
+    }
+    try {
+      const threadMessagesKey = getThreadMessagesKey(sourceThreadId);
+      const messageIds = await this.client.zrange(threadMessagesKey, 0, -1);
+      const pipeline = this.client.pipeline();
+      for (const mid of messageIds) {
+        pipeline.get(getMessageKey(sourceThreadId, mid));
+      }
+      const results = await pipeline.exec();
+      let sourceMessages = results.filter((msg) => msg !== null).map((msg) => ({
+        ...msg,
+        createdAt: new Date(msg.createdAt)
+      }));
+      if (options?.messageFilter?.startDate || options?.messageFilter?.endDate) {
+        sourceMessages = storage.filterByDateRange(sourceMessages, (msg) => new Date(msg.createdAt), {
+          start: options.messageFilter?.startDate,
+          end: options.messageFilter?.endDate
+        });
+      }
+      if (options?.messageFilter?.messageIds && options.messageFilter.messageIds.length > 0) {
+        const messageIdSet = new Set(options.messageFilter.messageIds);
+        sourceMessages = sourceMessages.filter((msg) => messageIdSet.has(msg.id));
+      }
+      sourceMessages.sort((a, b) => new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime());
+      if (options?.messageLimit && options.messageLimit > 0 && sourceMessages.length > options.messageLimit) {
+        sourceMessages = sourceMessages.slice(-options.messageLimit);
+      }
+      const now = /* @__PURE__ */ new Date();
+      const lastMessageId = sourceMessages.length > 0 ? sourceMessages[sourceMessages.length - 1].id : void 0;
+      const cloneMetadata = {
+        sourceThreadId,
+        clonedAt: now,
+        ...lastMessageId && { lastMessageId }
+      };
+      const newThread = {
+        id: newThreadId,
+        resourceId: resourceId || sourceThread.resourceId,
+        title: title || (sourceThread.title ? `Clone of ${sourceThread.title}` : void 0),
+        metadata: {
+          ...metadata,
+          clone: cloneMetadata
+        },
+        createdAt: now,
+        updatedAt: now
+      };
+      const writePipeline = this.client.pipeline();
+      const threadKey = getKey(storage.TABLE_THREADS, { id: newThreadId });
+      writePipeline.set(threadKey, processRecord(storage.TABLE_THREADS, newThread).processedRecord);
+      const clonedMessages = [];
+      const targetResourceId = resourceId || sourceThread.resourceId;
+      const newThreadMessagesKey = getThreadMessagesKey(newThreadId);
+      for (let i = 0; i < sourceMessages.length; i++) {
+        const sourceMsg = sourceMessages[i];
+        const newMessageId = crypto.randomUUID();
+        const { _index, ...restMsg } = sourceMsg;
+        const newMessage = {
+          ...restMsg,
+          id: newMessageId,
+          threadId: newThreadId,
+          resourceId: targetResourceId
+        };
+        const messageKey = getMessageKey(newThreadId, newMessageId);
+        writePipeline.set(messageKey, newMessage);
+        writePipeline.set(getMessageIndexKey(newMessageId), newThreadId);
+        writePipeline.zadd(newThreadMessagesKey, {
+          score: i,
+          member: newMessageId
+        });
+        clonedMessages.push(newMessage);
+      }
+      await writePipeline.exec();
+      return {
+        thread: newThread,
+        clonedMessages
+      };
+    } catch (error$1) {
+      if (error$1 instanceof error.MastraError) {
+        throw error$1;
+      }
+      throw new error.MastraError(
+        {
+          id: storage.createStorageErrorId("UPSTASH", "CLONE_THREAD", "FAILED"),
+          domain: error.ErrorDomain.STORAGE,
+          category: error.ErrorCategory.THIRD_PARTY,
+          details: { sourceThreadId, newThreadId }
+        },
+        error$1
+      );
+    }
+  }
 };
 function transformScoreRow(row) {
   return storage.transformScoreRow(row);
@@ -1273,24 +1413,6 @@ var ScoresUpstash = class extends storage.ScoresStorage {
     };
   }
 };
-function parseWorkflowRun(row) {
-  let parsedSnapshot = row.snapshot;
-  if (typeof parsedSnapshot === "string") {
-    try {
-      parsedSnapshot = JSON.parse(row.snapshot);
-    } catch (e) {
-      console.warn(`Failed to parse snapshot for workflow ${row.workflow_name}: ${e}`);
-    }
-  }
-  return {
-    workflowName: row.workflow_name,
-    runId: row.run_id,
-    snapshot: parsedSnapshot,
-    createdAt: storage.ensureDate(row.createdAt),
-    updatedAt: storage.ensureDate(row.updatedAt),
-    resourceId: row.resourceId
-  };
-}
 var WorkflowsUpstash = class extends storage.WorkflowsStorage {
   client;
   #db;
@@ -1300,6 +1422,24 @@ var WorkflowsUpstash = class extends storage.WorkflowsStorage {
     this.client = client;
     this.#db = new UpstashDB({ client });
   }
+  parseWorkflowRun(row) {
+    let parsedSnapshot = row.snapshot;
+    if (typeof parsedSnapshot === "string") {
+      try {
+        parsedSnapshot = JSON.parse(row.snapshot);
+      } catch (e) {
+        this.logger.warn(`Failed to parse snapshot for workflow ${row.workflow_name}: ${e}`);
+      }
+    }
+    return {
+      workflowName: row.workflow_name,
+      runId: row.run_id,
+      snapshot: parsedSnapshot,
+      createdAt: storage.ensureDate(row.createdAt),
+      updatedAt: storage.ensureDate(row.updatedAt),
+      resourceId: row.resourceId
+    };
+  }
   async dangerouslyClearAll() {
     await this.#db.deleteData({ tableName: storage.TABLE_WORKFLOW_SNAPSHOT });
   }
@@ -1465,7 +1605,7 @@ var WorkflowsUpstash = class extends storage.WorkflowsStorage {
       );
       const data = workflows.find((w) => w?.run_id === runId && w?.workflow_name === workflowName);
       if (!data) return null;
-      return parseWorkflowRun(data);
+      return this.parseWorkflowRun(data);
     } catch (error$1) {
       throw new error.MastraError(
         {
@@ -1550,7 +1690,7 @@ var WorkflowsUpstash = class extends storage.WorkflowsStorage {
       const results = await pipeline.exec();
       let runs = results.map((result) => result).filter(
         (record) => record !== null && record !== void 0 && typeof record === "object" && "workflow_name" in record
-      ).filter((record) => !workflowName || record.workflow_name === workflowName).map((w) => parseWorkflowRun(w)).filter((w) => {
+      ).filter((record) => !workflowName || record.workflow_name === workflowName).map((w) => this.parseWorkflowRun(w)).filter((w) => {
         if (fromDate && w.createdAt < fromDate) return false;
         if (toDate && w.createdAt > toDate) return false;
         if (status) {
@@ -1559,7 +1699,7 @@ var WorkflowsUpstash = class extends storage.WorkflowsStorage {
             try {
               snapshot = JSON.parse(snapshot);
             } catch (e) {
-              console.warn(`Failed to parse snapshot for workflow ${w.workflowName}: ${e}`);
+              this.logger.warn(`Failed to parse snapshot for workflow ${w.workflowName}: ${e}`);
               return false;
             }
           }
@@ -1597,7 +1737,7 @@ var WorkflowsUpstash = class extends storage.WorkflowsStorage {
 var isClientConfig = (config) => {
   return "client" in config;
 };
-var UpstashStore = class extends storage.MastraStorage {
+var UpstashStore = class extends storage.MastraCompositeStore {
   redis;
   stores;
   constructor(config) {
@@ -1625,19 +1765,6 @@ var UpstashStore = class extends storage.MastraStorage {
       memory
     };
   }
-  get supports() {
-    return {
-      selectByIncludeResourceScope: true,
-      resourceWorkingMemory: true,
-      hasColumn: false,
-      createTable: false,
-      deleteMessages: true,
-      observability: false,
-      indexManagement: false,
-      listScoresBySpan: true,
-      agents: false
-    };
-  }
   async close() {
   }
 };
@@ -2332,8 +2459,11 @@ Example Complex Query:
   ]
 }`;
 
+exports.ScoresUpstash = ScoresUpstash;
+exports.StoreMemoryUpstash = StoreMemoryUpstash;
 exports.UPSTASH_PROMPT = UPSTASH_PROMPT;
 exports.UpstashStore = UpstashStore;
 exports.UpstashVector = UpstashVector;
+exports.WorkflowsUpstash = WorkflowsUpstash;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map