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<Omit<DatasetItemPayload, 'externalId'>>): 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