@mastra/core 1.7.0 → 1.8.0

package/dist/docs/references/reference-core-setLogger.md

@@ -0,0 +1,26 @@
+# Mastra.setLogger()
+
+The `.setLogger()` method is used to set the logger for all components (agents, workflows, etc.) in the Mastra instance. This method accepts a single object parameter with a logger property.
+
+## Usage example
+
+```typescript
+mastra.setLogger({ logger: new PinoLogger({ name: 'testLogger' }) })
+```
+
+## Parameters
+
+**options:** (`{ logger: TLogger }`): An object containing the logger instance to set for all components.
+
+### Options
+
+**logger:** (`TLogger`): The logger instance to set for all components (agents, workflows, etc.).
+
+## Returns
+
+This method does not return a value.
+
+## Related
+
+- [Logging overview](https://mastra.ai/docs/observability/logging)
+- [Logger reference](https://mastra.ai/reference/logging/pino-logger)

package/dist/docs/references/reference-core-setStorage.md

@@ -0,0 +1,27 @@
+# Mastra.setStorage()
+
+The `.setStorage()` method is used to set the storage instance for the Mastra instance. This method accepts a single `MastraCompositeStore` parameter.
+
+## Usage example
+
+```typescript
+mastra.setStorage(
+  new LibSQLStore({
+    id: 'mastra-storage',
+    url: ':memory:',
+  }),
+)
+```
+
+## Parameters
+
+**storage:** (`MastraCompositeStore`): The storage instance to set for the Mastra instance.
+
+## Returns
+
+This method does not return a value.
+
+## Related
+
+- [Storage overview](https://mastra.ai/reference/storage/overview)
+- [Storage reference](https://mastra.ai/reference/storage/libsql)

package/dist/docs/references/reference-datasets-addItem.md

@@ -0,0 +1,37 @@
+# dataset.addItem()
+
+**Added in:** `@mastra/core@1.4.0`
+
+Adds a single item to the dataset. Each item has an input, optional ground truth, and optional metadata.
+
+## Usage example
+
+```typescript
+import { Mastra } from '@mastra/core'
+
+const mastra = new Mastra({
+  /* storage config */
+})
+
+const dataset = await mastra.datasets.get({ id: 'dataset-id' })
+
+const item = await dataset.addItem({
+  input: { question: 'What is TypeScript?' },
+  groundTruth: { answer: 'A typed superset of JavaScript' },
+  metadata: { source: 'manual' },
+})
+
+console.log(item.id)
+```
+
+## Parameters
+
+**input:** (`unknown`): Input data for the item.
+
+**groundTruth?:** (`unknown`): Expected output or ground truth for scoring.
+
+**metadata?:** (`Record<string, unknown>`): Arbitrary metadata for the item.
+
+## Returns
+
+**result:** (`Promise<DatasetItem>`): DatasetItemid:stringUnique identifier of the item.datasetId:stringID of the parent dataset.datasetVersion:numberDataset version when the item was created.input:unknownInput data.groundTruth?:unknownGround truth data.metadata?:Record\<string, unknown>Item metadata.createdAt:DateWhen the item was created.updatedAt:DateWhen the item was last updated.

package/dist/docs/references/reference-datasets-addItems.md

@@ -0,0 +1,35 @@
+# dataset.addItems()
+
+**Added in:** `@mastra/core@1.4.0`
+
+Adds multiple items to the dataset in a single bulk operation.
+
+## Usage example
+
+```typescript
+import { Mastra } from '@mastra/core'
+
+const mastra = new Mastra({
+  /* storage config */
+})
+
+const dataset = await mastra.datasets.get({ id: 'dataset-id' })
+
+const items = await dataset.addItems({
+  items: [
+    { input: { question: 'What is AI?' }, groundTruth: { answer: 'Artificial Intelligence' } },
+    { input: { question: 'What is ML?' }, groundTruth: { answer: 'Machine Learning' } },
+    { input: { question: 'What is DL?' }, metadata: { category: 'deep-learning' } },
+  ],
+})
+
+console.log(`Added ${items.length} items`)
+```
+
+## Parameters
+
+**items:** (`Array<object>`): DatasetIteminput:unknownInput data for the item.groundTruth?:unknownExpected output or ground truth.metadata?:Record\<string, unknown>Arbitrary metadata.
+
+## Returns
+
+**result:** (`Promise<DatasetItem[]>`): Array of created dataset items. See dataset.addItem() for the item shape.

package/dist/docs/references/reference-datasets-compareExperiments.md

@@ -0,0 +1,52 @@
+# DatasetsManager.compareExperiments()
+
+**Added in:** `@mastra/core@1.4.0`
+
+Compares two or more experiments, producing per-item and per-scorer comparisons. Requires at least two experiment IDs.
+
+## Usage example
+
+```typescript
+import { Mastra } from '@mastra/core'
+
+const mastra = new Mastra({
+  /* storage config */
+})
+
+const comparison = await mastra.datasets.compareExperiments({
+  experimentIds: ['exp-baseline', 'exp-new'],
+  baselineId: 'exp-baseline',
+})
+
+console.log(`Baseline: ${comparison.baselineId}`)
+
+for (const item of comparison.items) {
+  console.log(`Item ${item.itemId}:`)
+  console.log(`  Input: ${JSON.stringify(item.input)}`)
+
+  for (const [expId, result] of Object.entries(item.results)) {
+    if (result) {
+      console.log(
+        `  ${expId}: output=${JSON.stringify(result.output)}, scores=${JSON.stringify(result.scores)}`,
+      )
+    }
+  }
+}
+```
+
+## Parameters
+
+**experimentIds:** (`string[]`): Array of experiment IDs to compare. Must contain at least 2.
+
+**baselineId?:** (`string`): ID of the baseline experiment. Defaults to the first ID in \`experimentIds\`.
+
+## Returns
+
+Throws `MastraError` if fewer than 2 experiment IDs are provided.
+
+**result:** (`Promise<object>`): objectbaselineId:stringID of the baseline experiment used for comparison.items:Array\<object>Per-item comparison data.objectitemId:stringID of the dataset item.input:unknown | nullInput data for the item.groundTruth:unknown | nullGround truth for the item.results:Record\<string, { output: unknown; scores: Record\<string, number | null> } | null>Results keyed by experiment ID. Each entry contains the output and scorer results for that experiment.
+
+## Related
+
+- [dataset.startExperiment()](https://mastra.ai/reference/datasets/startExperiment)
+- [dataset.listExperiments()](https://mastra.ai/reference/datasets/listExperiments)

package/dist/docs/references/reference-datasets-create.md

@@ -0,0 +1,51 @@
+# DatasetsManager.create()
+
+**Added in:** `@mastra/core@1.4.0`
+
+Creates a new dataset. Zod schemas passed as `inputSchema` or `groundTruthSchema` are automatically converted to JSON Schema.
+
+## Usage example
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { z } from 'zod'
+
+const mastra = new Mastra({
+  /* storage config */
+})
+
+// Create with metadata
+const dataset = await mastra.datasets.create({
+  name: 'QA evaluation set',
+  description: 'Question-answer pairs for testing',
+  metadata: { team: 'ml' },
+})
+
+// Create with Zod schemas
+const typedDataset = await mastra.datasets.create({
+  name: 'Typed QA set',
+  inputSchema: z.object({
+    question: z.string(),
+    context: z.string().optional(),
+  }),
+  groundTruthSchema: z.object({
+    answer: z.string(),
+  }),
+})
+```
+
+## Parameters
+
+**name:** (`string`): Display name for the dataset.
+
+**description?:** (`string`): Description of the dataset.
+
+**inputSchema?:** (`unknown`): JSON Schema or Zod schema for item inputs. Zod schemas are auto-converted.
+
+**groundTruthSchema?:** (`unknown`): JSON Schema or Zod schema for item ground truths. Zod schemas are auto-converted.
+
+**metadata?:** (`Record<string, unknown>`): Arbitrary metadata.
+
+## Returns
+
+**result:** (`Promise<Dataset>`): A Dataset instance for the newly created dataset.

package/dist/docs/references/reference-datasets-dataset.md

@@ -0,0 +1,82 @@
+# Dataset Class
+
+**Added in:** `@mastra/core@1.4.0`
+
+The `Dataset` class provides methods for item CRUD, versioning, and experiment management on a single dataset. Obtained via `mastra.datasets.get()` or `mastra.datasets.create()`.
+
+## Usage examples
+
+### Add items and run an experiment
+
+```typescript
+import { Mastra } from '@mastra/core'
+
+const mastra = new Mastra({
+  /* storage config */
+})
+
+const dataset = await mastra.datasets.create({
+  name: 'QA pairs',
+})
+
+// Add items
+await dataset.addItems({
+  items: [
+    { input: { question: 'What is AI?' }, groundTruth: { answer: 'Artificial Intelligence' } },
+    { input: { question: 'What is ML?' }, groundTruth: { answer: 'Machine Learning' } },
+  ],
+})
+
+// Run an experiment
+const summary = await dataset.startExperiment({
+  targetType: 'agent',
+  targetId: 'my-agent',
+  scorers: ['accuracy'],
+})
+
+console.log(`${summary.succeededCount}/${summary.totalItems} succeeded`)
+```
+
+### Manage versions and history
+
+```typescript
+import { Mastra } from '@mastra/core'
+
+const mastra = new Mastra({
+  /* storage config */
+})
+
+const dataset = await mastra.datasets.get({ id: 'dataset-id' })
+
+// List versions
+const { versions } = await dataset.listVersions()
+
+// List items at a specific version
+const items = await dataset.listItems({ version: 2 })
+
+// Get item change history
+const history = await dataset.getItemHistory({ itemId: 'item-id' })
+```
+
+## Access
+
+`Dataset` is not instantiated directly. Obtain one via `DatasetsManager`:
+
+```typescript
+const dataset = await mastra.datasets.get({ id: 'dataset-id' })
+// or
+const dataset = await mastra.datasets.create({ name: 'My dataset' })
+```
+
+## Properties
+
+For the full dataset record (name, description, schemas, version, timestamps), call [`dataset.getDetails()`](https://mastra.ai/reference/datasets/getDetails).
+
+**id:** (`string`): The unique identifier of the dataset. Read-only.
+
+## Related
+
+- [DatasetsManager class](https://mastra.ai/reference/datasets/datasets-manager)
+- [dataset.startExperiment()](https://mastra.ai/reference/datasets/startExperiment)
+- [dataset.addItems()](https://mastra.ai/reference/datasets/addItems)
+- [dataset.listVersions()](https://mastra.ai/reference/datasets/listVersions)

package/dist/docs/references/reference-datasets-datasets-manager.md

@@ -0,0 +1,94 @@
+# DatasetsManager
+
+**Added in:** `@mastra/core@1.4.0`
+
+The `DatasetsManager` class provides the public API for managing datasets, including CRUD operations and cross-dataset experiment comparisons. Access it via `mastra.datasets`.
+
+## Usage examples
+
+### Create and list datasets
+
+```typescript
+import { Mastra } from '@mastra/core'
+
+const mastra = new Mastra({
+  /* storage config */
+})
+
+// Create a dataset
+const dataset = await mastra.datasets.create({
+  name: 'QA pairs',
+  description: 'Question-answer evaluation set',
+})
+
+// List all datasets
+const { datasets } = await mastra.datasets.list()
+```
+
+### Get and delete a dataset
+
+```typescript
+import { Mastra } from '@mastra/core'
+
+const mastra = new Mastra({
+  /* storage config */
+})
+
+// Get by ID
+const dataset = await mastra.datasets.get({ id: 'dataset-id' })
+
+// Delete by ID
+await mastra.datasets.delete({ id: 'dataset-id' })
+```
+
+### Get experiment
+
+Retrieves a specific experiment (run) by ID. Unlike `dataset.getExperiment()`, this works across all datasets without needing a dataset reference first.
+
+```typescript
+import { Mastra } from '@mastra/core'
+
+const mastra = new Mastra({
+  /* storage config */
+})
+
+// Get experiment directly without knowing the dataset
+const experiment = await mastra.datasets.getExperiment({
+  experimentId: 'exp-id',
+})
+
+console.log(`Dataset: ${experiment.datasetId}`)
+console.log(`Status: ${experiment.status}`)
+```
+
+### Compare experiments
+
+```typescript
+import { Mastra } from '@mastra/core'
+
+const mastra = new Mastra({
+  /* storage config */
+})
+
+const comparison = await mastra.datasets.compareExperiments({
+  experimentIds: ['exp-1', 'exp-2'],
+  baselineId: 'exp-1',
+})
+```
+
+## Access
+
+`DatasetsManager` is not instantiated directly. Access it from a `Mastra` instance:
+
+```typescript
+const mastra = new Mastra({
+  /* storage config */
+})
+const datasetsManager = mastra.datasets
+```
+
+## Related
+
+- [Dataset class](https://mastra.ai/reference/datasets/dataset)
+- [DatasetsManager.create()](https://mastra.ai/reference/datasets/create)
+- [DatasetsManager.compareExperiments()](https://mastra.ai/reference/datasets/compareExperiments)

package/dist/docs/references/reference-datasets-delete.md

@@ -0,0 +1,25 @@
+# DatasetsManager.delete()
+
+**Added in:** `@mastra/core@1.4.0`
+
+Deletes a dataset by ID, including all items, versions, and experiments.
+
+## Usage example
+
+```typescript
+import { Mastra } from '@mastra/core'
+
+const mastra = new Mastra({
+  /* storage config */
+})
+
+await mastra.datasets.delete({ id: 'dataset-id' })
+```
+
+## Parameters
+
+**id:** (`string`): ID of the dataset to delete.
+
+## Returns
+
+**result:** (`Promise<void>`): Resolves when the dataset is deleted.

package/dist/docs/references/reference-datasets-deleteExperiment.md

@@ -0,0 +1,27 @@
+# dataset.deleteExperiment()
+
+**Added in:** `@mastra/core@1.4.0`
+
+Deletes an experiment (run) by ID, including all associated results.
+
+## Usage example
+
+```typescript
+import { Mastra } from '@mastra/core'
+
+const mastra = new Mastra({
+  /* storage config */
+})
+
+const dataset = await mastra.datasets.get({ id: 'dataset-id' })
+
+await dataset.deleteExperiment({ experimentId: 'exp-id' })
+```
+
+## Parameters
+
+**experimentId:** (`string`): ID of the experiment to delete.
+
+## Returns
+
+**result:** (`Promise<void>`): Resolves when the experiment and its results are deleted.

package/dist/docs/references/reference-datasets-deleteItem.md

@@ -0,0 +1,27 @@
+# dataset.deleteItem()
+
+**Added in:** `@mastra/core@1.4.0`
+
+Deletes a single item from the dataset by ID.
+
+## Usage example
+
+```typescript
+import { Mastra } from '@mastra/core'
+
+const mastra = new Mastra({
+  /* storage config */
+})
+
+const dataset = await mastra.datasets.get({ id: 'dataset-id' })
+
+await dataset.deleteItem({ itemId: 'item-id' })
+```
+
+## Parameters
+
+**itemId:** (`string`): ID of the item to delete.
+
+## Returns
+
+**result:** (`Promise<void>`): Resolves when the item is deleted.

package/dist/docs/references/reference-datasets-deleteItems.md

@@ -0,0 +1,29 @@
+# dataset.deleteItems()
+
+**Added in:** `@mastra/core@1.4.0`
+
+Deletes multiple items from the dataset in a single bulk operation.
+
+## Usage example
+
+```typescript
+import { Mastra } from '@mastra/core'
+
+const mastra = new Mastra({
+  /* storage config */
+})
+
+const dataset = await mastra.datasets.get({ id: 'dataset-id' })
+
+await dataset.deleteItems({
+  itemIds: ['item-1', 'item-2', 'item-3'],
+})
+```
+
+## Parameters
+
+**itemIds:** (`string[]`): Array of item IDs to delete.
+
+## Returns
+
+**result:** (`Promise<void>`): Resolves when all items are deleted.

package/dist/docs/references/reference-datasets-get.md

@@ -0,0 +1,31 @@
+# DatasetsManager.get()
+
+**Added in:** `@mastra/core@1.4.0`
+
+Retrieves an existing dataset by ID. Throws a `MastraError` if the dataset does not exist.
+
+## Usage example
+
+```typescript
+import { Mastra } from '@mastra/core'
+
+const mastra = new Mastra({
+  /* storage config */
+})
+
+const dataset = await mastra.datasets.get({ id: 'dataset-id' })
+
+// Now use the dataset
+const details = await dataset.getDetails()
+console.log(details.name)
+```
+
+## Parameters
+
+**id:** (`string`): Unique identifier of the dataset.
+
+## Returns
+
+Throws `MastraError` if the dataset is not found.
+
+**result:** (`Promise<Dataset>`): A Dataset instance.

package/dist/docs/references/reference-datasets-getDetails.md

@@ -0,0 +1,47 @@
+# dataset.getDetails()
+
+**Added in:** `@mastra/core@1.4.0`
+
+Retrieves the full dataset record from storage, including metadata, schemas, and version information.
+
+## Usage example
+
+```typescript
+import { Mastra } from '@mastra/core'
+
+const mastra = new Mastra({
+  /* storage config */
+})
+
+const dataset = await mastra.datasets.get({ id: 'dataset-id' })
+
+// Get dataset details
+const details = await dataset.getDetails()
+console.log(details.name, details.version)
+```
+
+## Parameters
+
+This method takes no parameters.
+
+## Returns
+
+Returns a `Promise<DatasetRecord>`. Throws `MastraError` if the dataset is not found.
+
+**id:** (`string`): Unique identifier of the dataset.
+
+**name:** (`string`): Display name of the dataset.
+
+**description?:** (`string`): Description of the dataset.
+
+**metadata?:** (`Record<string, unknown>`): Arbitrary metadata associated with the dataset.
+
+**inputSchema?:** (`Record<string, unknown>`): JSON Schema for item inputs.
+
+**groundTruthSchema?:** (`Record<string, unknown>`): JSON Schema for item ground truths.
+
+**version:** (`number`): Current version number of the dataset.
+
+**createdAt:** (`Date`): When the dataset was created.
+
+**updatedAt:** (`Date`): When the dataset was last updated.

package/dist/docs/references/reference-datasets-getExperiment.md

@@ -0,0 +1,30 @@
+# dataset.getExperiment()
+
+**Added in:** `@mastra/core@1.4.0`
+
+Retrieves a specific experiment (run) by its ID.
+
+## Usage example
+
+```typescript
+import { Mastra } from '@mastra/core'
+
+const mastra = new Mastra({
+  /* storage config */
+})
+
+const dataset = await mastra.datasets.get({ id: 'dataset-id' })
+
+const experiment = await dataset.getExperiment({ experimentId: 'exp-id' })
+
+console.log(`Status: ${experiment.status}`)
+console.log(`${experiment.succeededCount}/${experiment.totalItems} succeeded`)
+```
+
+## Parameters
+
+**experimentId:** (`string`): ID of the experiment to retrieve.
+
+## Returns
+
+**result:** (`Promise<Experiment>`): The experiment record. See dataset.listExperiments() for the full shape.

package/dist/docs/references/reference-datasets-getItem.md

@@ -0,0 +1,33 @@
+# dataset.getItem()
+
+**Added in:** `@mastra/core@1.4.0`
+
+Retrieves a single dataset item by ID, optionally at a specific dataset version.
+
+## Usage example
+
+```typescript
+import { Mastra } from '@mastra/core'
+
+const mastra = new Mastra({
+  /* storage config */
+})
+
+const dataset = await mastra.datasets.get({ id: 'dataset-id' })
+
+// Get latest version of an item
+const item = await dataset.getItem({ itemId: 'item-id' })
+
+// Get item at a specific dataset version
+const versionedItem = await dataset.getItem({ itemId: 'item-id', version: 2 })
+```
+
+## Parameters
+
+**itemId:** (`string`): The unique identifier of the item.
+
+**version?:** (`number`): Dataset version to retrieve the item at. Defaults to the latest version.
+
+## Returns
+
+**result:** (`Promise<DatasetItem | null>`): The dataset item, or null if not found. See dataset.addItem() for the item shape.