@mastra/core
Version:
193 lines • 7.67 kB
TypeScript
import type { Mastra } from '../mastra/index.js';
import type { DatasetRecord, DatasetItem, DatasetItemPayload, DatasetItemRow, DatasetTenancyFilters, DatasetVersion, ExperimentResultStatus, ExperimentStatus, ExperimentTenancyFilters, ListDatasetItemsOutput, ListExperimentResultsOutput, ListExperimentsOutput, TargetType, UpdateDatasetInput, UpdateExperimentResultInput } from '../storage/types.js';
import type { StartExperimentConfig, ExperimentSummary } from './experiment/types.js';
/**
* Public API for interacting with a single dataset.
*
* Provides methods for item CRUD, versioning, and experiment management.
* Obtained via `DatasetsManager.get()` or `DatasetsManager.create()`.
*/
export declare class Dataset {
#private;
readonly id: string;
constructor(id: string, mastra: Mastra, scope?: DatasetTenancyFilters);
/**
* Get the full dataset record from storage.
*/
getDetails(): Promise<DatasetRecord>;
/**
* Update dataset metadata and/or schemas.
*
* Accepts Zod schemas for `inputSchema` / `groundTruthSchema` (widened to
* `unknown`); they are normalized to JSON Schema before being forwarded to
* the storage-canonical {@link UpdateDatasetInput} shape. All other fields
* mirror {@link UpdateDatasetInput} exactly (minus `id`, which is supplied
* from `this.id`).
*/
update(input: Omit<UpdateDatasetInput, 'id' | 'inputSchema' | 'groundTruthSchema'> & {
inputSchema?: unknown;
groundTruthSchema?: unknown;
}): Promise<DatasetRecord>;
/**
* Add a single item to the dataset.
*/
addItem(input: DatasetItemPayload): Promise<DatasetItem>;
/**
* Add multiple items to the dataset in bulk.
*/
addItems(input: {
items: DatasetItemPayload[];
}): Promise<DatasetItem[]>;
/**
* Get a single item by ID, optionally at a specific version.
*/
getItem(args: {
itemId: string;
version?: number;
}): Promise<DatasetItem | null>;
/**
* List items in the dataset, optionally at a specific version, with
* optional substring search and pagination.
*
* Return shape depends on the arguments:
*
* - When `version` is the only argument provided (no `search`, `page`, or
* `perPage`), returns a bare `DatasetItem[]` snapshot of every item at
* that version. This shape is retained for callers that predate
* server-side pagination on the versioned path; new code should pass
* `page` / `perPage` (or `search`) to opt into the paginated shape.
* - In all other cases (no arguments, or `search` / `page` / `perPage`
* provided with or without `version`), returns the paginated
* `{ items, pagination }` shape.
*
* @deprecated The `DatasetItem[]` branch of the return type is retained
* for backwards compatibility with the `version`-only call form; pass
* `page` / `perPage` (or `search`) to always receive the paginated
* `{ items, pagination }` shape.
*/
listItems(args?: {
version?: number;
page?: number;
perPage?: number;
search?: string;
}): Promise<DatasetItem[] | ListDatasetItemsOutput>;
/**
* Update an existing item in the dataset. Only the provided payload fields
* are patched.
*/
updateItem(input: {
itemId: string;
} & Partial<DatasetItemPayload>): Promise<DatasetItem>;
/**
* Delete a single item from the dataset.
*/
deleteItem(args: {
itemId: string;
}): Promise<void>;
/**
* Delete multiple items from the dataset in bulk.
*/
deleteItems(args: {
itemIds: string[];
}): Promise<void>;
/**
* List all versions of this dataset.
*/
listVersions(args?: {
page?: number;
perPage?: number;
}): Promise<{
versions: DatasetVersion[];
pagination: {
total: number;
page: number;
perPage: number | false;
hasMore: boolean;
};
}>;
/**
* Get full SCD-2 history of a specific item across all dataset versions.
*/
getItemHistory(args: {
itemId: string;
}): Promise<DatasetItemRow[]>;
/**
* Run an experiment on this dataset and wait for completion.
*/
startExperiment<I = unknown, O = unknown, E = unknown>(config: StartExperimentConfig<I, O, E>): Promise<ExperimentSummary>;
/**
* Start an experiment asynchronously (fire-and-forget).
* Returns immediately with the experiment ID and pending status.
*/
startExperimentAsync<I = unknown, O = unknown, E = unknown>(config: StartExperimentConfig<I, O, E>): Promise<{
experimentId: string;
status: 'pending';
totalItems: number;
}>;
/**
* List experiments (runs) for this dataset, with optional filters and
* pagination. All filters are pushed to the storage layer.
*
* @param args.targetType Restrict to a specific target type (e.g. `agent`).
* @param args.targetId Restrict to a specific target ID.
* @param args.agentVersion Restrict to a specific agent version — useful for
* baseline vs variant read patterns.
* @param args.status Restrict to a specific experiment status.
* @param args.filters Multi-tenant scoping filters (organization/project).
* @param args.page Page number. Defaults to `0`.
* @param args.perPage Page size. Defaults to `20`.
*/
listExperiments(args?: {
targetType?: TargetType;
targetId?: string;
agentVersion?: string;
status?: ExperimentStatus;
filters?: ExperimentTenancyFilters;
page?: number;
perPage?: number;
}): Promise<ListExperimentsOutput>;
/**
* Get a specific experiment (run) by ID.
*/
getExperiment(args: {
experimentId: string;
}): Promise<import("../storage/types.js").Experiment | null>;
/**
* List results for a specific experiment, with optional filters and
* pagination. All filters are pushed to the storage layer.
*
* @param args.experimentId The experiment whose results to list.
* @param args.traceId Restrict to results linked to a specific trace.
* @param args.status Restrict to a specific per-result review status.
* @param args.filters Multi-tenant scoping filters (organization/project).
* @param args.page Page number. Defaults to `0`.
* @param args.perPage Page size. Defaults to `20`.
*/
listExperimentResults(args: {
experimentId: string;
traceId?: string;
status?: ExperimentResultStatus;
filters?: ExperimentTenancyFilters;
page?: number;
perPage?: number;
}): Promise<ListExperimentResultsOutput>;
/**
* Update an experiment result's status or tags.
*/
updateExperimentResult(input: UpdateExperimentResultInput & {
experimentId: string;
}): Promise<import("../storage/types.js").ExperimentResult>;
/**
* Delete an experiment (run) by ID.
*
* The ownership check above already refuses cross-tenant / cross-dataset
* requests, but we still forward `this.#scope` to storage so the delete
* is defense-in-depth: a leaked handle or race that skipped the assertion
* still cannot delete another tenant's experiment (storage silently no-ops
* on tenancy mismatch).
*/
deleteExperiment(args: {
experimentId: string;
}): Promise<void>;
}
//# sourceMappingURL=dataset.d.ts.map