@mastra/libsql 0.0.0-agui-20250501182100

package/CHANGELOG.md

@@ -0,0 +1,127 @@
+# @mastra/libsql
+
+## 0.0.0-agui-20250501182100
+
+### Patch Changes
+
+- Updated dependencies [967b41c]
+- Updated dependencies [26738f4]
+- Updated dependencies [b804723]
+- Updated dependencies [0097d50]
+  - @mastra/core@0.0.0-agui-20250501182100
+
+## 0.0.2-alpha.2
+
+### Patch Changes
+
+- Updated dependencies [26738f4]
+  - @mastra/core@0.9.2-alpha.2
+
+## 0.0.2-alpha.1
+
+### Patch Changes
+
+- Updated dependencies [b804723]
+  - @mastra/core@0.9.2-alpha.1
+
+## 0.0.2-alpha.0
+
+### Patch Changes
+
+- Updated dependencies [0097d50]
+  - @mastra/core@0.9.2-alpha.0
+
+## 0.0.1
+
+### Patch Changes
+
+- 479f490: [MASTRA-3131] Add getWorkflowRunByID and add resourceId as filter for getWorkflowRuns
+- 5f826d9: Moved vector store specific prompts from @mastra/rag to be exported from the store that the prompt belongs to, ie @mastra/pg
+- 2d4001d: Add new @msstra/libsql package and use it in create-mastra
+- Updated dependencies [405b63d]
+- Updated dependencies [81fb7f6]
+- Updated dependencies [20275d4]
+- Updated dependencies [7d1892c]
+- Updated dependencies [a90a082]
+- Updated dependencies [2d17c73]
+- Updated dependencies [61e92f5]
+- Updated dependencies [35955b0]
+- Updated dependencies [6262bd5]
+- Updated dependencies [c1409ef]
+- Updated dependencies [3e7b69d]
+- Updated dependencies [e4943b8]
+- Updated dependencies [11d4485]
+- Updated dependencies [479f490]
+- Updated dependencies [c23a81c]
+- Updated dependencies [2d4001d]
+- Updated dependencies [c71013a]
+- Updated dependencies [1d3b1cd]
+  - @mastra/core@0.9.1
+
+## 0.0.1-alpha.8
+
+### Patch Changes
+
+- Updated dependencies [2d17c73]
+  - @mastra/core@0.9.1-alpha.8
+
+## 0.0.1-alpha.7
+
+### Patch Changes
+
+- Updated dependencies [1d3b1cd]
+  - @mastra/core@0.9.1-alpha.7
+
+## 0.0.1-alpha.6
+
+### Patch Changes
+
+- Updated dependencies [c23a81c]
+  - @mastra/core@0.9.1-alpha.6
+
+## 0.0.1-alpha.5
+
+### Patch Changes
+
+- 5f826d9: Moved vector store specific prompts from @mastra/rag to be exported from the store that the prompt belongs to, ie @mastra/pg
+- Updated dependencies [3e7b69d]
+  - @mastra/core@0.9.1-alpha.5
+
+## 0.0.1-alpha.4
+
+### Patch Changes
+
+- 479f490: [MASTRA-3131] Add getWorkflowRunByID and add resourceId as filter for getWorkflowRuns
+- Updated dependencies [e4943b8]
+- Updated dependencies [479f490]
+  - @mastra/core@0.9.1-alpha.4
+
+## 0.0.1-alpha.3
+
+### Patch Changes
+
+- Updated dependencies [6262bd5]
+  - @mastra/core@0.9.1-alpha.3
+
+## 0.0.1-alpha.2
+
+### Patch Changes
+
+- Updated dependencies [405b63d]
+- Updated dependencies [61e92f5]
+- Updated dependencies [c71013a]
+  - @mastra/core@0.9.1-alpha.2
+
+## 0.0.1-alpha.1
+
+### Patch Changes
+
+- 2d4001d: Add new @msstra/libsql package and use it in create-mastra
+- Updated dependencies [20275d4]
+- Updated dependencies [7d1892c]
+- Updated dependencies [a90a082]
+- Updated dependencies [35955b0]
+- Updated dependencies [c1409ef]
+- Updated dependencies [11d4485]
+- Updated dependencies [2d4001d]
+  - @mastra/core@0.9.1-alpha.1

package/LICENSE.md

@@ -0,0 +1,7 @@
+Copyright 2025 Mastra AI, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,144 @@
+# @mastra/pg
+
+SQLite implementation for Mastra, providing both vector similarity search and general storage capabilities with connection pooling and transaction support.
+
+## Installation
+
+```bash
+npm install @mastra/libsql
+```
+
+## Usage
+
+### Vector Store
+
+```typescript
+import { LibSQLVector } from '@mastra/libsql';
+
+const vectorStore = new LibSQLVector({
+  url: 'file:./my-db.db'
+});
+
+// Create a new table with vector support
+await vectorStore.createIndex({
+  indexName: 'my_vectors',
+  dimension: 1536,
+  metric: 'cosine',
+});
+
+// Add vectors
+const ids = await vectorStore.upsert({
+  indexName: 'my_vectors',
+  vectors: [[0.1, 0.2, ...], [0.3, 0.4, ...]],
+  metadata: [{ text: 'doc1' }, { text: 'doc2' }],
+});
+
+// Query vectors
+const results = await vectorStore.query({
+  indexName: 'my_vectors',
+  queryVector: [0.1, 0.2, ...],
+  topK: 10, // topK
+  filter: { text: 'doc1' }, // filter
+  includeVector: false, // includeVector
+  minScore: 0.5, // minScore
+});
+```
+
+### Storage
+
+```typescript
+import { LibSQLStore } from '@mastra/pg';
+
+const store = new LibSQLStore({
+  url: 'file:./my-db.db',
+});
+
+// Create a thread
+await store.saveThread({
+  id: 'thread-123',
+  resourceId: 'resource-456',
+  title: 'My Thread',
+  metadata: { key: 'value' },
+});
+
+// Add messages to thread
+await store.saveMessages([
+  {
+    id: 'msg-789',
+    threadId: 'thread-123',
+    role: 'user',
+    type: 'text',
+    content: [{ type: 'text', text: 'Hello' }],
+  },
+]);
+
+// Query threads and messages
+const savedThread = await store.getThread('thread-123');
+const messages = await store.getMessages('thread-123');
+```
+
+## Configuration
+
+The LibSQLStore store can be initialized with:
+
+- Configuration object with url and auth. Auth is only necessary when using a provider like [Turso](https://turso.tech/)
+
+## Features
+
+### Vector Store Features
+
+- Vector similarity search with cosine, euclidean, and dot product metrics
+- Advanced metadata filtering with MongoDB-like query syntax
+- Minimum score threshold for queries
+- Automatic UUID generation for vectors
+- Table management (create, list, describe, delete, truncate)
+
+### Storage Features
+
+- Thread and message storage with JSON support
+- Atomic transactions for data consistency
+- Efficient batch operations
+- Rich metadata support
+- Timestamp tracking
+- Cascading deletes
+
+## Supported Filter Operators
+
+The following filter operators are supported for metadata queries:
+
+- Comparison: `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`
+- Logical: `$and`, `$or`
+- Array: `$in`, `$nin`
+- Text: `$regex`, `$like`
+
+Example filter:
+
+```typescript
+{
+  $and: [{ age: { $gt: 25 } }, { tags: { $in: ['tag1', 'tag2'] } }];
+}
+```
+
+## Vector Store Methods
+
+- `createIndex({indexName, dimension, metric?, indexConfig?, defineIndex?})`: Create a new table with vector support
+- `upsert({indexName, vectors, metadata?, ids?})`: Add or update vectors
+- `query({indexName, queryVector, topK?, filter?, includeVector?, minScore?})`: Search for similar vectors
+- `defineIndex({indexName, metric?, indexConfig?})`: Define an index
+- `listIndexes()`: List all vector-enabled tables
+- `describeIndex(indexName)`: Get table statistics
+- `deleteIndex(indexName)`: Delete a table
+- `truncateIndex(indexName)`: Remove all data from a table
+
+## Storage Methods
+
+- `saveThread(thread)`: Create or update a thread
+- `getThread(threadId)`: Get a thread by ID
+- `deleteThread(threadId)`: Delete a thread and its messages
+- `saveMessages(messages)`: Save multiple messages in a transaction
+- `getMessages(threadId)`: Get all messages for a thread
+- `deleteMessages(messageIds)`: Delete specific messages
+
+## Related Links
+
+- [LibSQL Documentation](https://docs.turso.tech/sdk/introductionh)

package/dist/_tsup-dts-rollup.d.cts

@@ -0,0 +1,199 @@
+import type { ArrayOperator } from '@mastra/core/vector/filter';
+import { BaseFilterTranslator } from '@mastra/core/vector/filter';
+import type { BasicOperator } from '@mastra/core/vector/filter';
+import type { CreateIndexParams } from '@mastra/core/vector';
+import type { ElementOperator } from '@mastra/core/vector/filter';
+import type { EvalRow } from '@mastra/core/storage';
+import type { IndexStats } from '@mastra/core/vector';
+import type { InValue } from '@libsql/client';
+import type { LogicalOperator } from '@mastra/core/vector/filter';
+import { MastraStorage } from '@mastra/core/storage';
+import { MastraVector } from '@mastra/core/vector';
+import type { MessageType } from '@mastra/core/memory';
+import type { NumericOperator } from '@mastra/core/vector/filter';
+import type { OperatorSupport } from '@mastra/core/vector/filter';
+import type { ParamsToArgs } from '@mastra/core/vector';
+import type { QueryResult } from '@mastra/core/vector';
+import type { QueryVectorArgs } from '@mastra/core/vector';
+import type { QueryVectorParams } from '@mastra/core/vector';
+import type { RegexOperator } from '@mastra/core/vector/filter';
+import type { StorageColumn } from '@mastra/core/storage';
+import type { StorageGetMessagesArg } from '@mastra/core/storage';
+import type { StorageThreadType } from '@mastra/core/memory';
+import type { TABLE_NAMES } from '@mastra/core/storage';
+import type { UpsertVectorParams } from '@mastra/core/vector';
+import type { VectorFilter } from '@mastra/core/vector/filter';
+import type { WorkflowRun } from '@mastra/core/storage';
+import type { WorkflowRuns } from '@mastra/core/storage';
+
+export declare function buildFilterQuery(filter: VectorFilter): FilterResult;
+
+export declare const FILTER_OPERATORS: Record<string, OperatorFn>;
+
+declare type FilterOperator = {
+    sql: string;
+    needsValue: boolean;
+    transformValue?: (value: any) => any;
+};
+
+export declare interface FilterResult {
+    sql: string;
+    values: InValue[];
+}
+
+export declare const handleKey: (key: string) => string;
+
+/**
+ * Vector store specific prompt that details supported operators and examples.
+ * This prompt helps users construct valid filters for LibSQL Vector.
+ */
+declare const LIBSQL_PROMPT = "When querying LibSQL Vector, you can ONLY use the operators listed below. Any other operators will be rejected.\nImportant: Don't explain how to construct the filter - use the specified operators and fields to search the content and return relevant results.\nIf a user tries to give an explicit operator that is not supported, reject the filter entirely and let them know that the operator is not supported.\n\nBasic Comparison Operators:\n- $eq: Exact match (default when using field: value)\n  Example: { \"category\": \"electronics\" }\n- $ne: Not equal\n  Example: { \"category\": { \"$ne\": \"electronics\" } }\n- $gt: Greater than\n  Example: { \"price\": { \"$gt\": 100 } }\n- $gte: Greater than or equal\n  Example: { \"price\": { \"$gte\": 100 } }\n- $lt: Less than\n  Example: { \"price\": { \"$lt\": 100 } }\n- $lte: Less than or equal\n  Example: { \"price\": { \"$lte\": 100 } }\n\nArray Operators:\n- $in: Match any value in array\n  Example: { \"category\": { \"$in\": [\"electronics\", \"books\"] } }\n- $nin: Does not match any value in array\n  Example: { \"category\": { \"$nin\": [\"electronics\", \"books\"] } }\n- $all: Match all values in array\n  Example: { \"tags\": { \"$all\": [\"premium\", \"sale\"] } }\n- $elemMatch: Match array elements that meet all specified conditions\n  Example: { \"items\": { \"$elemMatch\": { \"price\": { \"$gt\": 100 } } } }\n- $contains: Check if array contains value\n  Example: { \"tags\": { \"$contains\": \"premium\" } }\n\nLogical Operators:\n- $and: Logical AND (implicit when using multiple conditions)\n  Example: { \"$and\": [{ \"price\": { \"$gt\": 100 } }, { \"category\": \"electronics\" }] }\n- $or: Logical OR\n  Example: { \"$or\": [{ \"price\": { \"$lt\": 50 } }, { \"category\": \"books\" }] }\n- $not: Logical NOT\n  Example: { \"$not\": { \"category\": \"electronics\" } }\n- $nor: Logical NOR\n  Example: { \"$nor\": [{ \"price\": { \"$lt\": 50 } }, { \"category\": \"books\" }] }\n\nElement Operators:\n- $exists: Check if field exists\n  Example: { \"rating\": { \"$exists\": true } }\n\nSpecial Operators:\n- $size: Array length check\n  Example: { \"tags\": { \"$size\": 2 } }\n\nRestrictions:\n- Regex patterns are not supported\n- Direct RegExp patterns will throw an error\n- Nested fields are supported using dot notation\n- Multiple conditions on the same field are supported with both implicit and explicit $and\n- Array operations work on array fields only\n- Basic operators handle array values as JSON strings\n- Empty arrays in conditions are handled gracefully\n- Only logical operators ($and, $or, $not, $nor) can be used at the top level\n- All other operators must be used within a field condition\n  Valid: { \"field\": { \"$gt\": 100 } }\n  Valid: { \"$and\": [...] }\n  Invalid: { \"$gt\": 100 }\n  Invalid: { \"$contains\": \"value\" }\n- Logical operators must contain field conditions, not direct operators\n  Valid: { \"$and\": [{ \"field\": { \"$gt\": 100 } }] }\n  Invalid: { \"$and\": [{ \"$gt\": 100 }] }\n- $not operator:\n  - Must be an object\n  - Cannot be empty\n  - Can be used at field level or top level\n  - Valid: { \"$not\": { \"field\": \"value\" } }\n  - Valid: { \"field\": { \"$not\": { \"$eq\": \"value\" } } }\n- Other logical operators ($and, $or, $nor):\n  - Can only be used at top level or nested within other logical operators\n  - Can not be used on a field level, or be nested inside a field\n  - Can not be used inside an operator\n  - Valid: { \"$and\": [{ \"field\": { \"$gt\": 100 } }] }\n  - Valid: { \"$or\": [{ \"$and\": [{ \"field\": { \"$gt\": 100 } }] }] }\n  - Invalid: { \"field\": { \"$and\": [{ \"$gt\": 100 }] } }\n  - Invalid: { \"field\": { \"$or\": [{ \"$gt\": 100 }] } }\n  - Invalid: { \"field\": { \"$gt\": { \"$and\": [{...}] } } }\n- $elemMatch requires an object with conditions\n  Valid: { \"array\": { \"$elemMatch\": { \"field\": \"value\" } } }\n  Invalid: { \"array\": { \"$elemMatch\": \"value\" } }\n\nExample Complex Query:\n{\n  \"$and\": [\n    { \"category\": { \"$in\": [\"electronics\", \"computers\"] } },\n    { \"price\": { \"$gte\": 100, \"$lte\": 1000 } },\n    { \"tags\": { \"$all\": [\"premium\", \"sale\"] } },\n    { \"items\": { \"$elemMatch\": { \"price\": { \"$gt\": 50 }, \"inStock\": true } } },\n    { \"$or\": [\n      { \"stock\": { \"$gt\": 0 } },\n      { \"preorder\": true }\n    ]}\n  ]\n}";
+export { LIBSQL_PROMPT }
+export { LIBSQL_PROMPT as LIBSQL_PROMPT_alias_1 }
+
+declare interface LibSQLConfig {
+    url: string;
+    authToken?: string;
+}
+export { LibSQLConfig }
+export { LibSQLConfig as LibSQLConfig_alias_1 }
+
+/**
+ * Translates MongoDB-style filters to LibSQL compatible filters.
+ *
+ * Key differences from MongoDB:
+ *
+ * Logical Operators ($and, $or, $nor):
+ * - Can be used at the top level or nested within fields
+ * - Can take either a single condition or an array of conditions
+ *
+ */
+export declare class LibSQLFilterTranslator extends BaseFilterTranslator {
+    protected getSupportedOperators(): OperatorSupport;
+    translate(filter?: VectorFilter): VectorFilter;
+    private translateNode;
+}
+
+declare type LibSQLQueryArgs = [...QueryVectorArgs, number?];
+
+declare interface LibSQLQueryParams extends QueryVectorParams {
+    minScore?: number;
+}
+
+declare class LibSQLStore extends MastraStorage {
+    private client;
+    constructor(config: LibSQLConfig);
+    private getCreateTableSQL;
+    createTable({ tableName, schema, }: {
+        tableName: TABLE_NAMES;
+        schema: Record<string, StorageColumn>;
+    }): Promise<void>;
+    clearTable({ tableName }: {
+        tableName: TABLE_NAMES;
+    }): Promise<void>;
+    private prepareStatement;
+    insert({ tableName, record }: {
+        tableName: TABLE_NAMES;
+        record: Record<string, any>;
+    }): Promise<void>;
+    batchInsert({ tableName, records }: {
+        tableName: TABLE_NAMES;
+        records: Record<string, any>[];
+    }): Promise<void>;
+    load<R>({ tableName, keys }: {
+        tableName: TABLE_NAMES;
+        keys: Record<string, string>;
+    }): Promise<R | null>;
+    getThreadById({ threadId }: {
+        threadId: string;
+    }): Promise<StorageThreadType | null>;
+    getThreadsByResourceId({ resourceId }: {
+        resourceId: string;
+    }): Promise<StorageThreadType[]>;
+    saveThread({ thread }: {
+        thread: StorageThreadType;
+    }): Promise<StorageThreadType>;
+    updateThread({ id, title, metadata, }: {
+        id: string;
+        title: string;
+        metadata: Record<string, unknown>;
+    }): Promise<StorageThreadType>;
+    deleteThread({ threadId }: {
+        threadId: string;
+    }): Promise<void>;
+    private parseRow;
+    getMessages<T extends MessageType[]>({ threadId, selectBy }: StorageGetMessagesArg): Promise<T>;
+    saveMessages({ messages }: {
+        messages: MessageType[];
+    }): Promise<MessageType[]>;
+    private transformEvalRow;
+    getEvalsByAgentName(agentName: string, type?: 'test' | 'live'): Promise<EvalRow[]>;
+    getTraces({ name, scope, page, perPage, attributes, filters, }?: {
+        name?: string;
+        scope?: string;
+        page: number;
+        perPage: number;
+        attributes?: Record<string, string>;
+        filters?: Record<string, any>;
+    }): Promise<any[]>;
+    getWorkflowRuns({ workflowName, fromDate, toDate, limit, offset, resourceId, }?: {
+        workflowName?: string;
+        fromDate?: Date;
+        toDate?: Date;
+        limit?: number;
+        offset?: number;
+        resourceId?: string;
+    }): Promise<WorkflowRuns>;
+    getWorkflowRunById({ runId, workflowName, }: {
+        runId: string;
+        workflowName?: string;
+    }): Promise<WorkflowRun | null>;
+    private hasColumn;
+    private parseWorkflowRun;
+}
+export { LibSQLStore as DefaultStorage }
+export { LibSQLStore as DefaultStorage_alias_1 }
+export { LibSQLStore }
+export { LibSQLStore as LibSQLStore_alias_1 }
+
+declare class LibSQLVector extends MastraVector {
+    private turso;
+    constructor({ connectionUrl, authToken, syncUrl, syncInterval, }: {
+        connectionUrl: string;
+        authToken?: string;
+        syncUrl?: string;
+        syncInterval?: number;
+    });
+    transformFilter(filter?: VectorFilter): VectorFilter;
+    query(...args: ParamsToArgs<LibSQLQueryParams> | LibSQLQueryArgs): Promise<QueryResult[]>;
+    upsert(...args: ParamsToArgs<UpsertVectorParams>): Promise<string[]>;
+    createIndex(...args: ParamsToArgs<CreateIndexParams>): Promise<void>;
+    deleteIndex(indexName: string): Promise<void>;
+    listIndexes(): Promise<string[]>;
+    describeIndex(indexName: string): Promise<IndexStats>;
+    /**
+     * Updates an index entry by its ID with the provided vector and/or metadata.
+     *
+     * @param indexName - The name of the index to update.
+     * @param id - The ID of the index entry to update.
+     * @param update - An object containing the vector and/or metadata to update.
+     * @param update.vector - An optional array of numbers representing the new vector.
+     * @param update.metadata - An optional record containing the new metadata.
+     * @returns A promise that resolves when the update is complete.
+     * @throws Will throw an error if no updates are provided or if the update operation fails.
+     */
+    updateIndexById(indexName: string, id: string, update: {
+        vector?: number[];
+        metadata?: Record<string, any>;
+    }): Promise<void>;
+    deleteIndexById(indexName: string, id: string): Promise<void>;
+    truncateIndex(indexName: string): Promise<void>;
+}
+export { LibSQLVector }
+export { LibSQLVector as LibSQLVector_alias_1 }
+
+declare type OperatorFn = (key: string, value?: any) => FilterOperator;
+
+export declare type OperatorType = BasicOperator | NumericOperator | ArrayOperator | ElementOperator | LogicalOperator | '$contains' | Exclude<RegexOperator, '$options'>;
+
+export { }