@mastra/libsql 1.21.1-alpha.0 → 1.21.1-alpha.1

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # @mastra/libsql
 
+## 1.21.1-alpha.1
+
+### Patch Changes
+
+- Added HTTP endpoints for caller-driven experiments: `POST /datasets/:datasetId/experiments` now accepts `start: false` to create an experiment without spawning the runner (with an optional target and run-level `scorerIds`), and new routes `POST /datasets/:datasetId/experiments/:experimentId/items/:itemId/run`, `POST /datasets/:datasetId/experiments/:experimentId/results`, and `POST /datasets/:datasetId/experiments/:experimentId/finalize` let external orchestrators run one item server-side, submit externally computed per-item results (idempotent upsert on retries), and finalize the run with server-computed counts. ([#21888](https://github.com/mastra-ai/mastra/pull/21888))
+
+- Added `createDatasetExperiment()`, `runExperimentItem()`, `submitExperimentResult()`, and `finalizeExperiment()` methods so a caller-owned orchestrator (for example Temporal) can drive an experiment loop while Mastra either executes each item server-side or ingests externally computed results. ([#21888](https://github.com/mastra-ai/mastra/pull/21888))
+
+- Fixed versioned dataset item lookups to return the item visible in the requested dataset snapshot. ([#21979](https://github.com/mastra-ai/mastra/pull/21979))
+
+- Added `upsertExperimentResult()` to the experiments storage domain plus an `attempt` column on experiment results and a nullable target with an optional `scorerIds` column on experiments, enabling retry-safe result writes for caller-driven experiments (retried submissions with the same `(experimentId, itemId, attempt)` key converge on a single row). `saveScore()` now accepts an optional caller-supplied `id` and upserts on it, so retried experiment submissions replace their previous score rows (latest wins) instead of accumulating duplicates. ([#21888](https://github.com/mastra-ai/mastra/pull/21888))
+
+- Added caller-driven experiments so an external orchestrator (for example Temporal workers) can own the experiment loop while Mastra stays the system of record. ([#21888](https://github.com/mastra-ai/mastra/pull/21888))
+
+  Create an experiment with `dataset.createExperiment()` (idempotent when you pass your own id). With a target, Mastra runs each item for you: call `dataset.runExperimentItem()` per item and Mastra executes the registered agent or workflow, resolves scorers (experiment `scorers`, falling back to item `scorerIds`, then dataset `scorerIds`), and upserts the result. Without a target, run everything yourself and report per-item results with `dataset.submitExperimentResult()` (upsert semantics on `(experimentId, itemId, attempt)` so retried workers converge on a single row). Either way, close the run with `dataset.finalizeExperiment()` and Mastra computes per-item succeeded/failed/skipped counts from the persisted rows. Results go into the same storage as native runs, so Studio views, comparisons, and review summaries work unchanged.
+
+  ```typescript
+  // Caller drives the loop, Mastra runs each item
+  const { experimentId } = await dataset.createExperiment({
+    id: workflowRunId,
+    targetType: 'agent',
+    targetId: 'support-agent',
+    scorers: ['accuracy'],
+  });
+
+  await dataset.runExperimentItem({ experimentId, itemId });
+
+  // Or: caller runs everything, Mastra ingests results
+  const ingest = await dataset.createExperiment({ id: workflowRunId });
+  await dataset.submitExperimentResult({
+    experimentId: ingest.experimentId,
+    itemId,
+    output,
+    scores: [{ scorerId: 'accuracy', score: 0.92 }],
+  });
+
+  const experiment = await dataset.finalizeExperiment({ experimentId });
+  ```
+
+- Updated dependencies [[`9267e9b`](https://github.com/mastra-ai/mastra/commit/9267e9b3d9c2fcf16936050495a787054c2431ab), [`acc3471`](https://github.com/mastra-ai/mastra/commit/acc3471de5f3fde8027ee4e355af292b2bc1bc30), [`b6a771e`](https://github.com/mastra-ai/mastra/commit/b6a771ef23d203ddb348efca8065eff65def8191), [`9267e9b`](https://github.com/mastra-ai/mastra/commit/9267e9b3d9c2fcf16936050495a787054c2431ab), [`26d4016`](https://github.com/mastra-ai/mastra/commit/26d40160ff7f7d8bf95fee2039a52cbc83863533), [`9267e9b`](https://github.com/mastra-ai/mastra/commit/9267e9b3d9c2fcf16936050495a787054c2431ab), [`9267e9b`](https://github.com/mastra-ai/mastra/commit/9267e9b3d9c2fcf16936050495a787054c2431ab), [`57c5103`](https://github.com/mastra-ai/mastra/commit/57c51035a2a36e3df3c4f32f46bb789a66ed5946)]:
+  - @mastra/core@1.61.0-alpha.3
+
 ## 1.21.1-alpha.0
 
 ### Patch Changes

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-libsql
 description: Documentation for @mastra/libsql. Use when working with @mastra/libsql APIs, configuration, or implementation.
 metadata:
   package: "@mastra/libsql"
-  version: "1.21.1-alpha.0"
+  version: "1.21.1-alpha.1"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.21.1-alpha.0",
+  "version": "1.21.1-alpha.1",
   "package": "@mastra/libsql",
   "exports": {},
   "modules": {}

package/dist/docs/references/reference-rag-retrieval.md

@@ -77,9 +77,19 @@ For detailed information about available operators and syntax, see the [Metadata
 
 Basic filtering examples:
 
+**MongoDB**:
+
 ```ts
+import { MongoDBVector } from '@mastra/mongodb'
+
+const mongoVector = new MongoDBVector({
+  id: 'mongodb-vector',
+  uri: process.env.MONGODB_URI,
+  dbName: process.env.MONGODB_DB_NAME,
+})
+
 // Simple equality filter
-const results = await pgVector.query({
+const equalityResults = await mongoVector.query({
   indexName: 'embeddings',
   queryVector: embedding,
   topK: 10,
@@ -89,7 +99,7 @@ const results = await pgVector.query({
 })
 
 // Numeric comparison
-const results = await pgVector.query({
+const priceResults = await mongoVector.query({
   indexName: 'embeddings',
   queryVector: embedding,
   topK: 10,
@@ -99,7 +109,7 @@ const results = await pgVector.query({
 })
 
 // Multiple conditions
-const results = await pgVector.query({
+const compoundResults = await mongoVector.query({
   indexName: 'embeddings',
   queryVector: embedding,
   topK: 10,
@@ -111,7 +121,7 @@ const results = await pgVector.query({
 })
 
 // Array operations
-const results = await pgVector.query({
+const tagResults = await mongoVector.query({
   indexName: 'embeddings',
   queryVector: embedding,
   topK: 10,
@@ -121,7 +131,64 @@ const results = await pgVector.query({
 })
 
 // Logical operators
-const results = await pgVector.query({
+const categoryResults = await mongoVector.query({
+  indexName: 'embeddings',
+  queryVector: embedding,
+  topK: 10,
+  filter: {
+    $or: [{ category: 'electronics' }, { category: 'accessories' }],
+    $and: [{ price: { $gt: 50 } }, { price: { $lt: 200 } }],
+  },
+})
+```
+
+**pgVector**:
+
+```ts
+// Simple equality filter
+const equalityResults = await pgVector.query({
+  indexName: 'embeddings',
+  queryVector: embedding,
+  topK: 10,
+  filter: {
+    source: 'article1.txt',
+  },
+})
+
+// Numeric comparison
+const priceResults = await pgVector.query({
+  indexName: 'embeddings',
+  queryVector: embedding,
+  topK: 10,
+  filter: {
+    price: { $gt: 100 },
+  },
+})
+
+// Multiple conditions
+const compoundResults = await pgVector.query({
+  indexName: 'embeddings',
+  queryVector: embedding,
+  topK: 10,
+  filter: {
+    category: 'electronics',
+    price: { $lt: 1000 },
+    inStock: true,
+  },
+})
+
+// Array operations
+const tagResults = await pgVector.query({
+  indexName: 'embeddings',
+  queryVector: embedding,
+  topK: 10,
+  filter: {
+    tags: { $in: ['sale', 'new'] },
+  },
+})
+
+// Logical operators
+const categoryResults = await pgVector.query({
   indexName: 'embeddings',
   queryVector: embedding,
   topK: 10,
@@ -141,6 +208,47 @@ Common use cases for metadata filtering:
 - Combine multiple conditions for precise querying
 - Filter by document attributes (e.g., language, author)
 
+### Where the filter is applied
+
+Vector stores differ in _when_ they apply a metadata filter, which affects how filtered queries scale.
+
+MongoDB can evaluate the filter inside the vector index itself. This keeps the query on a single round trip to `$vectorSearch`, so it avoids the pre-filter pass that collects matching document IDs and the 16 MB BSON limit that pass is subject to. Declaring the fields you filter on in `filterFields` when you create the index is what enables it:
+
+```ts
+// Declare the metadata fields you want to filter on
+await mongoVector.createIndex({
+  indexName: 'embeddings',
+  dimension: 1536,
+  filterFields: ['source', 'price', 'category', 'inStock', 'tags'],
+})
+
+// createIndex() returns before the index finishes building
+await mongoVector.waitForIndexReady({ indexName: 'embeddings' })
+
+// The filter is applied during the index search
+const results = await mongoVector.query({
+  indexName: 'embeddings',
+  queryVector: embedding,
+  topK: 10,
+  filter: { source: 'article1.txt' },
+})
+```
+
+Mastra passes the filter to the index only when every field it references is declared in `filterFields` and every operator is one the index accepts: `$and`, `$or`, `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, and `$nin`. A filter that uses an undeclared field or any other operator takes a fallback path: Mastra matches the collection first and passes the matching document IDs into the vector search. That fallback holds only while the ID set fits within MongoDB's 16 MB BSON document limit. On large collections the query fails once that limit is exceeded, so declare your filter fields when you expect selective filters over large data sets.
+
+pgVector applies the filter as an ordinary query condition:
+
+```ts
+const results = await pgVector.query({
+  indexName: 'embeddings',
+  queryVector: embedding,
+  topK: 10,
+  filter: { source: 'article1.txt' },
+})
+```
+
+Postgres vector indexes (HNSW and IVFFlat) can't restrict that search to rows matching a condition. When a filter is present, pgVector instead compares the query vector against every matching row and returns the closest `topK`. Results are exact, but the work grows with the number of rows the filter matches. Indexing the metadata column speeds up row retrieval. The distance comparisons still happen per row.
+
 ### Vector Query Tool
 
 Sometimes you want to give your agent the ability to query a vector database directly. The Vector Query Tool allows your agent to be in charge of retrieval decisions, combining semantic search with optional filtering and reranking based on the agent's understanding of the user's needs.

package/dist/index.cjs

@@ -4136,8 +4136,12 @@ var DatasetsLibSQL = class extends _mastra_core_storage.DatasetsStorage {
 		try {
 			let result;
 			if (args.datasetVersion !== void 0) result = await this.#client.execute({
-				sql: `SELECT ${buildSelectColumns(_mastra_core_storage.TABLE_DATASET_ITEMS)} FROM ${_mastra_core_storage.TABLE_DATASET_ITEMS} WHERE id = ? AND datasetVersion = ? AND isDeleted = 0`,
-				args: [args.id, args.datasetVersion]
+				sql: `SELECT ${buildSelectColumns(_mastra_core_storage.TABLE_DATASET_ITEMS)} FROM ${_mastra_core_storage.TABLE_DATASET_ITEMS} WHERE id = ? AND datasetVersion <= ? AND (validTo IS NULL OR validTo > ?) AND isDeleted = 0 ORDER BY datasetVersion DESC LIMIT 1`,
+				args: [
+					args.id,
+					args.datasetVersion,
+					args.datasetVersion
+				]
 			});
 			else result = await this.#client.execute({
 				sql: `SELECT ${buildSelectColumns(_mastra_core_storage.TABLE_DATASET_ITEMS)} FROM ${_mastra_core_storage.TABLE_DATASET_ITEMS} WHERE id = ? AND validTo IS NULL AND isDeleted = 0`,
@@ -4601,7 +4605,8 @@ var ExperimentsLibSQL = class extends _mastra_core_storage.ExperimentsStorage {
 				"experimentSetId",
 				"comparisonId",
 				"variantId",
-				"trialIndex"
+				"trialIndex",
+				"scorerIds"
 			]
 		});
 		await this.#db.alterTable({
@@ -4613,7 +4618,8 @@ var ExperimentsLibSQL = class extends _mastra_core_storage.ExperimentsStorage {
 				"comment",
 				"toolMockReport",
 				"organizationId",
-				"projectId"
+				"projectId",
+				"attempt"
 			]
 		});
 		await this.#client.batch([
@@ -4630,7 +4636,11 @@ var ExperimentsLibSQL = class extends _mastra_core_storage.ExperimentsStorage {
 				args: []
 			},
 			{
-				sql: `CREATE UNIQUE INDEX IF NOT EXISTS idx_experiment_results_exp_item ON "${_mastra_core_storage.TABLE_EXPERIMENT_RESULTS}" ("experimentId", "itemId")`,
+				sql: `DROP INDEX IF EXISTS idx_experiment_results_exp_item`,
+				args: []
+			},
+			{
+				sql: `CREATE UNIQUE INDEX IF NOT EXISTS idx_experiment_results_exp_item_attempt ON "${_mastra_core_storage.TABLE_EXPERIMENT_RESULTS}" ("experimentId", "itemId", "attempt")`,
 				args: []
 			},
 			{
@@ -4719,8 +4729,9 @@ var ExperimentsLibSQL = class extends _mastra_core_storage.ExperimentsStorage {
 			agentVersion: row.agentVersion ?? null,
 			organizationId: row.organizationId ?? null,
 			projectId: row.projectId ?? null,
-			targetType: row.targetType,
-			targetId: row.targetId,
+			targetType: row.targetType ?? null,
+			targetId: row.targetId ?? null,
+			scorerIds: row.scorerIds ? (0, _mastra_core_storage.safelyParseJSON)(row.scorerIds) : null,
 			name: row.name ?? void 0,
 			description: row.description ?? void 0,
 			metadata: row.metadata ? (0, _mastra_core_storage.safelyParseJSON)(row.metadata) : void 0,
@@ -4756,6 +4767,7 @@ var ExperimentsLibSQL = class extends _mastra_core_storage.ExperimentsStorage {
 			startedAt: (0, _mastra_core_storage.ensureDate)(row.startedAt),
 			completedAt: (0, _mastra_core_storage.ensureDate)(row.completedAt),
 			retryCount: row.retryCount,
+			attempt: row.attempt != null ? Number(row.attempt) : 0,
 			traceId: row.traceId ?? null,
 			status: row.status ?? null,
 			tags: row.tags ? (0, _mastra_core_storage.safelyParseJSON)(row.tags) : null,
@@ -4778,8 +4790,9 @@ var ExperimentsLibSQL = class extends _mastra_core_storage.ExperimentsStorage {
 					agentVersion: input.agentVersion ?? null,
 					organizationId: input.organizationId ?? null,
 					projectId: input.projectId ?? null,
-					targetType: input.targetType,
-					targetId: input.targetId,
+					targetType: input.targetType ?? null,
+					targetId: input.targetId ?? null,
+					scorerIds: input.scorerIds ?? null,
 					name: input.name ?? null,
 					description: input.description ?? null,
 					metadata: input.metadata ?? null,
@@ -4807,8 +4820,9 @@ var ExperimentsLibSQL = class extends _mastra_core_storage.ExperimentsStorage {
 				agentVersion: input.agentVersion ?? null,
 				organizationId: input.organizationId ?? null,
 				projectId: input.projectId ?? null,
-				targetType: input.targetType,
-				targetId: input.targetId,
+				targetType: input.targetType ?? null,
+				targetId: input.targetId ?? null,
+				scorerIds: input.scorerIds ?? null,
 				name: input.name,
 				description: input.description,
 				metadata: input.metadata,
@@ -5055,6 +5069,7 @@ var ExperimentsLibSQL = class extends _mastra_core_storage.ExperimentsStorage {
 					startedAt: input.startedAt.toISOString(),
 					completedAt: input.completedAt.toISOString(),
 					retryCount: input.retryCount,
+					attempt: input.attempt ?? 0,
 					traceId: input.traceId ?? null,
 					status: input.status ?? null,
 					tags: input.tags !== void 0 && input.tags !== null ? JSON.stringify(input.tags) : null,
@@ -5076,6 +5091,7 @@ var ExperimentsLibSQL = class extends _mastra_core_storage.ExperimentsStorage {
 				startedAt: input.startedAt,
 				completedAt: input.completedAt,
 				retryCount: input.retryCount,
+				attempt: input.attempt ?? 0,
 				traceId: input.traceId ?? null,
 				status: input.status ?? null,
 				tags: input.tags ?? null,
@@ -5090,6 +5106,81 @@ var ExperimentsLibSQL = class extends _mastra_core_storage.ExperimentsStorage {
 			}, error);
 		}
 	}
+	async upsertExperimentResult(input) {
+		try {
+			const attempt = input.attempt ?? 0;
+			let existingId = (await this.#client.execute({
+				sql: `SELECT "id" FROM ${_mastra_core_storage.TABLE_EXPERIMENT_RESULTS} WHERE "experimentId" = ? AND "itemId" = ? AND COALESCE("attempt", 0) = ?`,
+				args: [
+					input.experimentId,
+					input.itemId,
+					attempt
+				]
+			})).rows[0]?.id;
+			if (!existingId) try {
+				return await this.addExperimentResult({
+					...input,
+					attempt
+				});
+			} catch (insertError) {
+				if (!(0, _mastra_core_storage.hasErrorCode)(insertError, /* @__PURE__ */ new Set([
+					"SQLITE_CONSTRAINT",
+					"SQLITE_CONSTRAINT_PRIMARYKEY",
+					"SQLITE_CONSTRAINT_UNIQUE"
+				]))) throw insertError;
+				existingId = (await this.#client.execute({
+					sql: `SELECT "id" FROM ${_mastra_core_storage.TABLE_EXPERIMENT_RESULTS} WHERE "experimentId" = ? AND "itemId" = ? AND COALESCE("attempt", 0) = ?`,
+					args: [
+						input.experimentId,
+						input.itemId,
+						attempt
+					]
+				})).rows[0]?.id;
+				if (!existingId) throw insertError;
+			}
+			await this.#client.execute({
+				sql: `UPDATE ${_mastra_core_storage.TABLE_EXPERIMENT_RESULTS} SET
+          "itemDatasetVersion" = ?, "organizationId" = ?, "projectId" = ?,
+          "input" = ?, "output" = ?, "groundTruth" = ?, "error" = ?,
+          "startedAt" = ?, "completedAt" = ?, "retryCount" = ?, "attempt" = ?,
+          "traceId" = ?, "status" = ?, "tags" = ?, "toolMockReport" = ?
+        WHERE "id" = ?`,
+				args: [
+					input.itemDatasetVersion ?? null,
+					input.organizationId ?? null,
+					input.projectId ?? null,
+					JSON.stringify(input.input),
+					input.output != null ? JSON.stringify(input.output) : null,
+					input.groundTruth != null ? JSON.stringify(input.groundTruth) : null,
+					input.error != null ? JSON.stringify(input.error) : null,
+					input.startedAt.toISOString(),
+					input.completedAt.toISOString(),
+					input.retryCount,
+					attempt,
+					input.traceId ?? null,
+					input.status ?? null,
+					input.tags != null ? JSON.stringify(input.tags) : null,
+					input.toolMockReport != null ? JSON.stringify(input.toolMockReport) : null,
+					existingId
+				]
+			});
+			const result = await this.getExperimentResultById({ id: existingId });
+			if (!result) throw new _mastra_core_error.MastraError({
+				id: (0, _mastra_core_storage.createStorageErrorId)("LIBSQL", "UPSERT_EXPERIMENT_RESULT", "NOT_FOUND"),
+				domain: _mastra_core_error.ErrorDomain.STORAGE,
+				category: _mastra_core_error.ErrorCategory.USER,
+				details: { resultId: existingId }
+			});
+			return result;
+		} catch (error) {
+			if (error instanceof _mastra_core_error.MastraError) throw error;
+			throw new _mastra_core_error.MastraError({
+				id: (0, _mastra_core_storage.createStorageErrorId)("LIBSQL", "UPSERT_EXPERIMENT_RESULT", "FAILED"),
+				domain: _mastra_core_error.ErrorDomain.STORAGE,
+				category: _mastra_core_error.ErrorCategory.THIRD_PARTY
+			}, error);
+		}
+	}
 	async updateExperimentResult(input) {
 		try {
 			const setClauses = [];
@@ -11609,8 +11700,13 @@ var ScoresLibSQL = class ScoresLibSQL extends _mastra_core_storage.ScoresStorage
 			}, error);
 		}
 		try {
-			const id = crypto.randomUUID();
+			const suppliedId = parsedScore.id;
+			const id = suppliedId ?? crypto.randomUUID();
 			const now = /* @__PURE__ */ new Date();
+			if (suppliedId) await this.#client.execute({
+				sql: `DELETE FROM ${_mastra_core_storage.TABLE_SCORERS} WHERE id = ?`,
+				args: [suppliedId]
+			});
 			await this.#db.insert({
 				tableName: _mastra_core_storage.TABLE_SCORERS,
 				record: {