@mastra/libsql 1.0.0-beta.9 → 1.0.0

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

@@ -0,0 +1,213 @@
+# Vectors API Reference
+
+> API reference for vectors - 1 entries
+
+
+---
+
+## Reference: libSQL Vector Store
+
+> Documentation for the LibSQLVector class in Mastra, which provides vector search using libSQL with vector extensions.
+
+The libSQL storage implementation provides a SQLite-compatible vector search [libSQL](https://github.com/tursodatabase/libsql), a fork of SQLite with vector extensions, and [Turso](https://turso.tech/) with vector extensions, offering a lightweight and efficient vector database solution.
+It's part of the `@mastra/libsql` package and offers efficient vector similarity search with metadata filtering.
+
+## Installation
+
+```bash
+npm install @mastra/libsql@beta
+```
+
+## Usage
+
+```typescript
+import { LibSQLVector } from "@mastra/libsql";
+
+// Create a new vector store instance
+const store = new LibSQLVector({
+  id: 'libsql-vector',
+  url: process.env.DATABASE_URL,
+  // Optional: for Turso cloud databases
+  authToken: process.env.DATABASE_AUTH_TOKEN,
+});
+
+// Create an index
+await store.createIndex({
+  indexName: "myCollection",
+  dimension: 1536,
+});
+
+// Add vectors with metadata
+const vectors = [[0.1, 0.2, ...], [0.3, 0.4, ...]];
+const metadata = [
+  { text: "first document", category: "A" },
+  { text: "second document", category: "B" }
+];
+await store.upsert({
+  indexName: "myCollection",
+  vectors,
+  metadata,
+});
+
+// Query similar vectors
+const queryVector = [0.1, 0.2, ...];
+const results = await store.query({
+  indexName: "myCollection",
+  queryVector,
+  topK: 10, // top K results
+  filter: { category: "A" } // optional metadata filter
+});
+```
+
+## Constructor Options
+
+## Methods
+
+### createIndex()
+
+Creates a new vector collection. The index name must start with a letter or underscore and can only contain letters, numbers, and underscores. The dimension must be a positive integer.
+
+### upsert()
+
+Adds or updates vectors and their metadata in the index. Uses a transaction to ensure all vectors are inserted atomically - if any insert fails, the entire operation is rolled back.
+
+### query()
+
+Searches for similar vectors with optional metadata filtering.
+
+### describeIndex()
+
+Gets information about an index.
+
+Returns:
+
+```typescript
+interface IndexStats {
+  dimension: number;
+  count: number;
+  metric: "cosine" | "euclidean" | "dotproduct";
+}
+```
+
+### deleteIndex()
+
+Deletes an index and all its data.
+
+### listIndexes()
+
+Lists all vector indexes in the database.
+
+Returns: `Promise<string[]>`
+
+### truncateIndex()
+
+Removes all vectors from an index while keeping the index structure.
+
+### updateVector()
+
+Update a single vector by ID or by metadata filter. Either `id` or `filter` must be provided, but not both.
+
+### deleteVector()
+
+Deletes a specific vector entry from an index by its ID.
+
+### deleteVectors()
+
+Delete multiple vectors by IDs or by metadata filter. Either `ids` or `filter` must be provided, but not both.
+
+## 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 specific errors for different failure cases:
+
+```typescript
+try {
+  await store.query({
+    indexName: "my-collection",
+    queryVector: queryVector,
+  });
+} catch (error) {
+  // Handle specific error cases
+  if (error.message.includes("Invalid index name format")) {
+    console.error(
+      "Index name must start with a letter/underscore and contain only alphanumeric characters",
+    );
+  } else if (error.message.includes("Table not found")) {
+    console.error("The specified index does not exist");
+  } else {
+    console.error("Vector store error:", error.message);
+  }
+}
+```
+
+Common error cases include:
+
+- Invalid index name format
+- Invalid vector dimensions
+- Table/index not found
+- Database connection issues
+- Transaction failures during upsert
+
+## 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-libsql-agent.ts"
+import { Memory } from "@mastra/memory";
+import { Agent } from "@mastra/core/agent";
+import { LibSQLStore, LibSQLVector } from "@mastra/libsql";
+import { fastembed } from "@mastra/fastembed";
+
+export const libsqlAgent = new Agent({
+  id: "libsql-agent",
+  name: "libSQL 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 LibSQLStore({
+      id: 'libsql-agent-storage',
+      url: "file:libsql-agent.db",
+    }),
+    vector: new LibSQLVector({
+      id: 'libsql-agent-vector',
+      url: "file:libsql-agent.db",
+    }),
+    embedder: fastembed,
+    options: {
+      lastMessages: 10,
+      semanticRecall: {
+        topK: 3,
+        messageRange: 2,
+      },
+      generateTitle: true, // Explicitly enable automatic title generation
+    },
+  }),
+});
+```
+
+## Related
+
+- [Metadata Filters](../rag/metadata-filters)

package/dist/docs/workflows/01-snapshots.md

@@ -0,0 +1,240 @@
+> Learn how to save and resume workflow execution state with snapshots in Mastra
+
+# Snapshots
+
+In Mastra, a snapshot is a serializable representation of a workflow's complete execution state at a specific point in time. Snapshots capture all the information needed to resume a workflow from exactly where it left off, including:
+
+- The current state of each step in the workflow
+- The outputs of completed steps
+- The execution path taken through the workflow
+- Any suspended steps and their metadata
+- The remaining retry attempts for each step
+- Additional contextual data needed to resume execution
+
+Snapshots are automatically created and managed by Mastra whenever a workflow is suspended, and are persisted to the configured storage system.
+
+## The role of snapshots in suspend and resume
+
+Snapshots are the key mechanism enabling Mastra's suspend and resume capabilities. When a workflow step calls `await suspend()`:
+
+1. The workflow execution is paused at that exact point
+2. The current state of the workflow is captured as a snapshot
+3. The snapshot is persisted to storage
+4. The workflow step is marked as "suspended" with a status of `'suspended'`
+5. Later, when `resume()` is called on the suspended step, the snapshot is retrieved
+6. The workflow execution resumes from exactly where it left off
+
+This mechanism provides a powerful way to implement human-in-the-loop workflows, handle rate limiting, wait for external resources, and implement complex branching workflows that may need to pause for extended periods.
+
+## Snapshot anatomy
+
+Each snapshot includes the `runId`, input, step status (`success`, `suspended`, etc.), any suspend and resume payloads, and the final output. This ensures full context is available when resuming execution.
+
+```json
+{
+  "runId": "34904c14-e79e-4a12-9804-9655d4616c50",
+  "status": "success",
+  "value": {},
+  "context": {
+    "input": {
+      "value": 100,
+      "user": "Michael",
+      "requiredApprovers": ["manager", "finance"]
+    },
+    "approval-step": {
+      "payload": {
+        "value": 100,
+        "user": "Michael",
+        "requiredApprovers": ["manager", "finance"]
+      },
+      "startedAt": 1758027577955,
+      "status": "success",
+      "suspendPayload": {
+        "message": "Workflow suspended",
+        "requestedBy": "Michael",
+        "approvers": ["manager", "finance"]
+      },
+      "suspendedAt": 1758027578065,
+      "resumePayload": { "confirm": true, "approver": "manager" },
+      "resumedAt": 1758027578517,
+      "output": { "value": 100, "approved": true },
+      "endedAt": 1758027578634
+    }
+  },
+  "activePaths": [],
+  "serializedStepGraph": [
+    {
+      "type": "step",
+      "step": {
+        "id": "approval-step",
+        "description": "Accepts a value, waits for confirmation"
+      }
+    }
+  ],
+  "suspendedPaths": {},
+  "waitingPaths": {},
+  "result": { "value": 100, "approved": true },
+  "requestContext": {},
+  "timestamp": 1758027578740
+}
+```
+
+## How snapshots are saved and retrieved
+
+Snapshots are saved to the configured storage system. By default, they use libSQL, but you can configure Upstash or PostgreSQL instead. Each snapshot is saved in the `workflow_snapshots` table and identified by the workflow's `runId`.
+
+Read more about:
+
+- [libSQL Storage](https://mastra.ai/reference/v1/storage/libsql)
+- [Upstash Storage](https://mastra.ai/reference/v1/storage/upstash)
+- [PostgreSQL Storage](https://mastra.ai/reference/v1/storage/postgresql)
+
+### Saving snapshots
+
+When a workflow is suspended, Mastra automatically persists the workflow snapshot with these steps:
+
+1. The `suspend()` function in a step execution triggers the snapshot process
+2. The `WorkflowInstance.suspend()` method records the suspended machine
+3. `persistWorkflowSnapshot()` is called to save the current state
+4. The snapshot is serialized and stored in the configured database in the `workflow_snapshots` table
+5. The storage record includes the workflow name, run ID, and the serialized snapshot
+
+### Retrieving snapshots
+
+When a workflow is resumed, Mastra retrieves the persisted snapshot with these steps:
+
+1. The `resume()` method is called with a specific step ID
+2. The snapshot is loaded from storage using `loadWorkflowSnapshot()`
+3. The snapshot is parsed and prepared for resumption
+4. The workflow execution is recreated with the snapshot state
+5. The suspended step is resumed, and execution continues
+
+```typescript
+const storage = mastra.getStorage();
+const workflowStore = await storage?.getStore('workflows');
+
+const snapshot = await workflowStore?.loadWorkflowSnapshot({
+  runId: "<run-id>",
+  workflowName: "<workflow-id>",
+});
+
+console.log(snapshot);
+```
+
+## Storage options for snapshots
+
+Snapshots are persisted using a `storage` instance configured on the `Mastra` class. This storage layer is shared across all workflows registered to that instance. Mastra supports multiple storage options for flexibility in different environments.
+
+```typescript title="src/mastra/index.ts" 
+import { Mastra } from "@mastra/core";
+import { LibSQLStore } from "@mastra/libsql";
+import { approvalWorkflow } from "./workflows";
+
+export const mastra = new Mastra({
+  storage: new LibSQLStore({
+    id: 'mastra-storage',
+    url: ":memory:",
+  }),
+  workflows: { approvalWorkflow },
+});
+```
+
+- [libSQL Storage](https://mastra.ai/reference/v1/storage/libsql)
+- [PostgreSQL Storage](https://mastra.ai/reference/v1/storage/postgresql)
+- [MongoDB Storage](https://mastra.ai/reference/v1/storage/mongodb)
+- [Upstash Storage](https://mastra.ai/reference/v1/storage/upstash)
+- [Cloudflare D1](https://mastra.ai/reference/v1/storage/cloudflare-d1)
+- [DynamoDB](https://mastra.ai/reference/v1/storage/dynamodb)
+- [More storage providers](https://mastra.ai/docs/v1/memory/storage)
+
+## Best practices
+
+1. **Ensure Serializability**: Any data that needs to be included in the snapshot must be serializable (convertible to JSON).
+2. **Minimize Snapshot Size**: Avoid storing large data objects directly in the workflow context. Instead, store references to them (like IDs) and retrieve the data when needed.
+3. **Handle Resume Context Carefully**: When resuming a workflow, carefully consider what context to provide. This will be merged with the existing snapshot data.
+4. **Set Up Proper Monitoring**: Implement monitoring for suspended workflows, especially long-running ones, to ensure they are properly resumed.
+5. **Consider Storage Scaling**: For applications with many suspended workflows, ensure your storage solution is appropriately scaled.
+
+## Custom snapshot metadata
+
+You can attach custom metadata when suspending a workflow by defining a `suspendSchema`. This metadata is stored in the snapshot and made available when the workflow is resumed.
+
+```typescript {30-34} title="src/mastra/workflows/test-workflow.ts"
+import { createWorkflow, createStep } from "@mastra/core/workflows";
+import { z } from "zod";
+
+const approvalStep = createStep({
+  id: "approval-step",
+  description: "Accepts a value, waits for confirmation",
+  inputSchema: z.object({
+    value: z.number(),
+    user: z.string(),
+    requiredApprovers: z.array(z.string()),
+  }),
+  suspendSchema: z.object({
+    message: z.string(),
+    requestedBy: z.string(),
+    approvers: z.array(z.string()),
+  }),
+  resumeSchema: z.object({
+    confirm: z.boolean(),
+    approver: z.string(),
+  }),
+  outputSchema: z.object({
+    value: z.number(),
+    approved: z.boolean(),
+  }),
+  execute: async ({ inputData, resumeData, suspend }) => {
+    const { value, user, requiredApprovers } = inputData;
+    const { confirm } = resumeData ?? {};
+
+    if (!confirm) {
+      return await suspend({
+        message: "Workflow suspended",
+        requestedBy: user,
+        approvers: [...requiredApprovers],
+      });
+    }
+
+    return {
+      value,
+      approved: confirm,
+    };
+  },
+});
+```
+
+### Providing resume data
+
+Use `resumeData` to pass structured input when resuming a suspended step. It must match the step’s `resumeSchema`.
+
+```typescript {14-20}
+const workflow = mastra.getWorkflow("approvalWorkflow");
+
+const run = await workflow.createRun();
+
+const result = await run.start({
+  inputData: {
+    value: 100,
+    user: "Michael",
+    requiredApprovers: ["manager", "finance"],
+  },
+});
+
+if (result.status === "suspended") {
+  const resumedResult = await run.resume({
+    step: "approval-step",
+    resumeData: {
+      confirm: true,
+      approver: "manager",
+    },
+  });
+}
+```
+
+## Related
+
+- [Control Flow](https://mastra.ai/docs/v1/workflows/control-flow)
+- [Suspend & Resume](https://mastra.ai/docs/v1/workflows/suspend-and-resume)
+- [Time Travel](https://mastra.ai/docs/v1/workflows/time-travel)
+- [Human-in-the-loop](https://mastra.ai/docs/v1/workflows/human-in-the-loop)