@mastra/dynamodb 0.0.0-add-libsql-changeset-20250910154739

package/LICENSE.md

@@ -0,0 +1,15 @@
+# Apache License 2.0
+
+Copyright (c) 2025 Kepler Software, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,144 @@
+# @mastra/dynamodb
+
+A DynamoDB storage implementation for Mastra using a single-table design pattern with ElectroDB.
+
+## Features
+
+- Efficient single-table design for all Mastra storage needs
+- Based on ElectroDB for type-safe DynamoDB access
+- Support for AWS credentials, regions, and endpoints
+- Compatible with AWS DynamoDB Local for development
+- Thread, Message, Trace, Eval, and Workflow operations
+- Optimized for serverless environments
+
+## Installation
+
+```bash
+npm install @mastra/dynamodb
+# or
+pnpm add @mastra/dynamodb
+# or
+yarn add @mastra/dynamodb
+```
+
+## Prerequisites
+
+Before using this package, you need to create a DynamoDB table with the required structure. See [TABLE_SETUP.md](./TABLE_SETUP.md) for detailed instructions on how to set up the table using CloudFormation or AWS CDK.
+
+## Usage
+
+### Basic Usage
+
+```typescript
+import { Memory } from '@mastra/memory';
+import { DynamoDBStore } from '@mastra/dynamodb';
+import { PineconeVector } from '@mastra/pinecone';
+
+// Initialize the DynamoDB storage
+const storage = new DynamoDBStore({
+  name: 'dynamodb',
+  config: {
+    region: 'us-east-1',
+    tableName: 'mastra-single-table', // Name of your DynamoDB table
+  },
+});
+
+// Initialize vector store (if using semantic recall)
+const vector = new PineconeVector({
+  apiKey: process.env.PINECONE_API_KEY,
+  environment: process.env.PINECONE_ENVIRONMENT,
+  index: process.env.PINECONE_INDEX,
+});
+
+// Memory combines storage (like DynamoDBStore) with an optional vector store for recall
+// Create memory with DynamoDB storage
+const memory = new Memory({
+  storage,
+  vector,
+  options: {
+    lastMessages: 10,
+    semanticRecall: true,
+  },
+});
+```
+
+### Local Development
+
+For local development, you can use DynamoDB Local:
+
+```typescript
+const storage = new DynamoDBStore({
+  name: 'dynamodb',
+  config: {
+    region: 'us-east-1',
+    tableName: 'mastra-single-table',
+    endpoint: 'http://localhost:8000', // Local DynamoDB endpoint
+  },
+});
+```
+
+### AWS IAM Permissions
+
+The IAM role or user used by this package needs the following permissions:
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": [
+        "dynamodb:DescribeTable",
+        "dynamodb:GetItem",
+        "dynamodb:PutItem",
+        "dynamodb:UpdateItem",
+        "dynamodb:DeleteItem",
+        "dynamodb:Query",
+        "dynamodb:Scan",
+        "dynamodb:BatchGetItem",
+        "dynamodb:BatchWriteItem"
+      ],
+      "Resource": [
+        "arn:aws:dynamodb:*:*:table/${YOUR_TABLE_NAME}",
+        "arn:aws:dynamodb:*:*:table/${YOUR_TABLE_NAME}/index/*"
+      ]
+    }
+  ]
+}
+```
+
+## Configuration Options
+
+The `DynamoDBStore` constructor accepts the following configuration options:
+
+| Option               | Type   | Required | Description                                                |
+| -------------------- | ------ | -------- | ---------------------------------------------------------- |
+| `name`               | string | Yes      | A name for the storage instance                            |
+| `config.region`      | string | No       | AWS region (default: 'us-east-1')                          |
+| `config.tableName`   | string | Yes      | The name of your DynamoDB table                            |
+| `config.endpoint`    | string | No       | Custom endpoint for DynamoDB (e.g., for local development) |
+| `config.credentials` | object | No       | AWS credentials (accessKeyId, secretAccessKey)             |
+
+## Architectural Approach
+
+This storage adapter utilizes a **single-table design pattern** leveraging [ElectroDB](https://electrodb.dev/), which is a common and recommended approach for DynamoDB. This differs architecturally from relational database adapters (like `@mastra/pg` or `@mastra/libsql`) that typically use multiple tables, each dedicated to a specific entity (threads, messages, etc.).
+
+Key aspects of this approach:
+
+- **DynamoDB Native:** The single-table design is optimized for DynamoDB's key-value and query capabilities, often leading to better performance and scalability compared to mimicking relational models.
+- **External Table Management:** Unlike some adapters that might offer helper functions to create tables via code, this adapter **expects the DynamoDB table and its associated Global Secondary Indexes (GSIs) to be provisioned externally** before use. Please refer to `TABLE_SETUP.md` for detailed instructions using tools like AWS CloudFormation or CDK. The adapter focuses solely on interacting with the pre-existing table structure.
+- **Consistency via Interface:** While the underlying storage model differs, this adapter adheres to the same `MastraStorage` interface as other adapters, ensuring it can be used interchangeably within the Mastra `Memory` component.
+
+## Advantage of Single-Table Design
+
+This implementation uses a single-table design pattern with ElectroDB, which offers several advantages within the context of DynamoDB:
+
+1. **Lower cost**: One table means fewer read/write capacity units to provision
+2. **Better performance**: Related data is stored together for faster access
+3. **Simplified administration**: Only one table to monitor and back up
+4. **Reduced complexity**: Consistent access patterns across entities
+5. **Transaction support**: Atomic operations across different entity types
+
+## License
+
+MIT

package/dist/entities/eval.d.ts

@@ -0,0 +1,102 @@
+import { Entity } from 'electrodb';
+export declare const evalEntity: Entity<string, string, string, {
+    model: {
+        entity: string;
+        version: string;
+        service: string;
+    };
+    attributes: {
+        input: {
+            type: "string";
+            required: true;
+        };
+        output: {
+            type: "string";
+            required: true;
+        };
+        result: {
+            type: "string";
+            required: true;
+            set: (value?: any) => any;
+            get: (value?: string) => any;
+        };
+        agent_name: {
+            type: "string";
+            required: true;
+        };
+        metric_name: {
+            type: "string";
+            required: true;
+        };
+        instructions: {
+            type: "string";
+            required: true;
+        };
+        test_info: {
+            type: "string";
+            required: false;
+            set: (value?: any) => any;
+            get: (value?: string) => string | undefined;
+        };
+        global_run_id: {
+            type: "string";
+            required: true;
+        };
+        run_id: {
+            type: "string";
+            required: true;
+        };
+        created_at: {
+            type: "string";
+            required: true;
+            default: () => string;
+            set: (value?: Date | string) => string;
+        };
+        createdAt: {
+            readonly type: "string";
+            readonly required: true;
+            readonly readOnly: true;
+            readonly set: (value?: Date | string) => string;
+            readonly default: () => string;
+        };
+        updatedAt: {
+            readonly type: "string";
+            readonly required: true;
+            readonly set: (value?: Date | string) => string;
+            readonly default: () => string;
+        };
+        metadata: {
+            readonly type: "string";
+            readonly set: (value?: Record<string, unknown> | string) => string | undefined;
+            readonly get: (value?: string) => any;
+        };
+        entity: {
+            type: "string";
+            required: true;
+        };
+    };
+    indexes: {
+        primary: {
+            pk: {
+                field: string;
+                composite: ("entity" | "run_id")[];
+            };
+            sk: {
+                field: string;
+                composite: never[];
+            };
+        };
+        byAgent: {
+            index: string;
+            pk: {
+                field: string;
+                composite: ("entity" | "agent_name")[];
+            };
+            sk: {
+                field: string;
+                composite: "created_at"[];
+            };
+        };
+    };
+}>;
+//# sourceMappingURL=eval.d.ts.map

package/dist/entities/eval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eval.d.ts","sourceRoot":"","sources":["../../src/entities/eval.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAGnC,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;0BAwBH,GAAG;0BAOH,MAAM;;;;;;;;;;;;;;;;;0BAuBN,GAAG;0BAOH,MAAM;;;;;;;;;;;;;;0BAkBN,IAAI,GAAG,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAmB/B,CAAC"}