opik 1.9.49 → 1.9.51

package/dist/index.d.cts

@@ -10324,6 +10324,307 @@ interface ConstructorOpikConfig extends OpikConfig {
     headers?: Record<string, string>;
 }
 
+/**
+ * Supported template engine types for prompts
+ * Re-exported from REST API with uppercase values for consistency
+ */
+declare const PromptType: {
+    /** Mustache template syntax with {{variable}} placeholders */
+    readonly MUSTACHE: "mustache";
+    /** Jinja2 template syntax with {% %} blocks and {{ }} variables */
+    readonly JINJA2: "jinja2";
+};
+type PromptType = (typeof PromptType)[keyof typeof PromptType];
+/**
+ * Configuration options for creating a new prompt
+ * Extends REST API PromptWrite with renamed 'prompt' field
+ */
+interface CreatePromptOptions {
+    /** Name of the prompt (unique identifier) */
+    name: string;
+    /** Template text content with placeholders */
+    prompt: string;
+    /** Optional prompt ID (generated if not provided) */
+    promptId?: string;
+    /** Optional description for the prompt */
+    description?: string;
+    /** Optional metadata for tracking and filtering */
+    metadata?: JsonNodeWrite;
+    /** Optional change description for version tracking */
+    changeDescription?: string;
+    /** Template engine type, defaults to mustache */
+    type?: PromptType;
+    /** Optional tags for categorization */
+    tags?: string[];
+}
+/**
+ * Options for retrieving a specific prompt version
+ * Re-exported from REST API PromptVersionRetrieveDetail
+ */
+type GetPromptOptions = PromptVersionRetrieveDetail;
+/**
+ * Variables to be substituted into prompt template.
+ */
+type PromptVariables = Record<string, unknown>;
+/**
+ * Data structure for creating a PromptVersion instance
+ */
+interface PromptVersionData {
+    name: string;
+    prompt: string;
+    commit: string;
+    promptId: string;
+    versionId: string;
+    type: PromptType;
+    metadata?: JsonNode;
+    changeDescription?: string;
+    createdAt?: Date;
+    createdBy?: string;
+}
+
+/**
+ * Represents a specific immutable snapshot of a prompt template at a point in time.
+ * Pure data object with formatting capabilities.
+ */
+declare class PromptVersion {
+    readonly id: string;
+    readonly name: string;
+    readonly prompt: string;
+    readonly commit: string;
+    readonly type: PromptType;
+    readonly metadata?: JsonNode;
+    readonly changeDescription?: string;
+    readonly createdAt?: Date;
+    readonly createdBy?: string;
+    constructor(data: PromptVersionData);
+    /**
+     * Format the prompt template with the provided variables
+     */
+    format(variables: PromptVariables): string;
+    /**
+     * Get human-readable version age (e.g., "2 days ago", "Today")
+     */
+    getVersionAge(): string;
+    /**
+     * Get formatted version information string
+     * Format: "[commitHash] YYYY-MM-DD by user@email.com - Change description"
+     */
+    getVersionInfo(): string;
+    /**
+     * Compare this version's template with another version and return a formatted diff.
+     * Displays a git-style unified diff showing additions, deletions, and changes.
+     * The diff is automatically logged to the terminal and also returned as a string.
+     * The output is colored and formatted for terminal display.
+     *
+     * @param other - The version to compare against
+     * @returns A formatted string showing the differences between versions
+     *
+     * @example
+     * ```typescript
+     * const currentVersion = await prompt.getVersion("commit123");
+     * const previousVersion = await prompt.getVersion("commit456");
+     *
+     * // Logs diff to terminal and returns it
+     * const diff = currentVersion.compareTo(previousVersion);
+     * ```
+     */
+    compareTo(other: PromptVersion): string;
+    /**
+     * Factory method to create PromptVersion from API response
+     */
+    static fromApiResponse(name: string, apiResponse: PromptVersionDetail): PromptVersion;
+}
+
+interface PromptData {
+    promptId: string;
+    versionId: string;
+    name: string;
+    prompt: string;
+    commit?: string;
+    metadata?: JsonNode;
+    type?: PromptType;
+    changeDescription?: string;
+    description?: string;
+    tags?: string[];
+}
+/**
+ * Domain object representing a versioned prompt template.
+ * Provides immutable access to prompt properties and template formatting.
+ * Integrates with backend for persistence and version management.
+ */
+declare class Prompt {
+    private opik;
+    readonly id: string;
+    readonly versionId: string;
+    readonly prompt: string;
+    readonly commit: string | undefined;
+    readonly type: PromptType;
+    readonly changeDescription: string | undefined;
+    private _name;
+    private _description;
+    private _tags;
+    private readonly _metadata;
+    /**
+     * Creates a new Prompt instance.
+     * This should not be created directly, use OpikClient.createPrompt() instead.
+     */
+    constructor({ promptId, versionId, name, prompt, commit, metadata, type, changeDescription, description, tags, }: PromptData, opik: OpikClient);
+    get name(): string;
+    get description(): string | undefined;
+    get tags(): readonly string[] | undefined;
+    /**
+     * Read-only metadata property.
+     * Returns deep copy to prevent external mutation.
+     */
+    get metadata(): JsonNode | undefined;
+    /**
+     * Formats prompt template by substituting variables.
+     * Validates that all template placeholders are provided (for Mustache templates).
+     *
+     * @param variables - Object with values to substitute into template
+     * @returns Formatted prompt text with variables substituted
+     * @throws PromptValidationError if template processing or validation fails
+     *
+     * @example
+     * ```typescript
+     * const prompt = new Prompt({
+     *   name: "greeting",
+     *   prompt: "Hello {{name}}, your score is {{score}}",
+     *   type: "mustache"
+     * }, client);
+     *
+     * // Valid - all placeholders provided
+     * prompt.format({ name: "Alice", score: 95 });
+     * // Returns: "Hello Alice, your score is 95"
+     *
+     * // Invalid - missing 'score' placeholder
+     * prompt.format({ name: "Alice" });
+     * // Throws: PromptValidationError
+     * ```
+     */
+    format(variables: PromptVariables): string;
+    /**
+     * Static factory method to create Prompt from backend API response.
+     *
+     * @param name - Name of the prompt
+     * @param apiResponse - REST API PromptVersionDetail response
+     * @param opik - OpikClient instance
+     * @param promptPublicData - Optional PromptPublic data containing description and tags
+     * @returns Prompt instance constructed from response data
+     * @throws PromptValidationError if response structure invalid
+     */
+    static fromApiResponse(promptData: PromptPublic, apiResponse: PromptVersionDetail, opik: OpikClient): Prompt;
+    /**
+     * Updates prompt properties (name, description, and/or tags).
+     * Performs immediate update (no batching).
+     *
+     * @param updates - Partial updates with optional name, description, and tags
+     * @returns Promise resolving to this Prompt instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * const prompt = await client.getPrompt({ name: "my-prompt" });
+     * await prompt.updateProperties({
+     *   name: "renamed-prompt",
+     *   description: "Updated description",
+     *   tags: ["tag1", "tag2"]
+     * });
+     * ```
+     */
+    updateProperties(updates: {
+        name?: string;
+        description?: string;
+        tags?: string[];
+    }): Promise<this>;
+    /**
+     * Deletes this prompt from the backend.
+     * Performs immediate deletion (no batching).
+     */
+    delete(): Promise<void>;
+    /**
+     * Retrieves all version history for this prompt.
+     * Fetches and returns complete version history, sorted by creation date (newest first).
+     * Automatically handles pagination to fetch all versions.
+     *
+     * @returns Promise resolving to array of all PromptVersion instances for this prompt
+     * @throws OpikApiError if REST API call fails
+     *
+     * @example
+     * ```typescript
+     * const prompt = await client.getPrompt({ name: "my-prompt" });
+     * const versions = await prompt.getVersions();
+     *
+     * console.log(`Found ${versions.length} versions`);
+     * versions.forEach(v => {
+     *   console.log(`Commit: ${v.commit}, Age: ${v.getVersionAge()}`);
+     * });
+     * ```
+     */
+    getVersions(): Promise<PromptVersion[]>;
+    /**
+     * Restores a specific version by creating a new version with content from the specified version.
+     * The version must be obtained from the backend (e.g., via getVersions()).
+     * Returns a new Prompt instance with the restored content as the latest version.
+     *
+     * @param version - PromptVersion object to restore (must be from backend)
+     * @returns Promise resolving to a new Prompt instance with the restored version
+     * @throws OpikApiError if REST API call fails
+     *
+     * @example
+     * ```typescript
+     * const prompt = await client.getPrompt({ name: "my-prompt" });
+     *
+     * // Get all versions
+     * const versions = await prompt.getVersions();
+     *
+     * // Restore a specific version
+     * const targetVersion = versions.find(v => v.commit === "abc123de");
+     * if (targetVersion) {
+     *   const restoredPrompt = await prompt.useVersion(targetVersion);
+     *   console.log(`Restored to commit: ${restoredPrompt.commit}`);
+     *   console.log(`New template: ${restoredPrompt.prompt}`);
+     *
+     *   // Continue using the restored prompt
+     *   const formatted = restoredPrompt.format({ name: "World" });
+     * }
+     * ```
+     */
+    useVersion(version: PromptVersion): Promise<Prompt>;
+    /**
+     * Get a Prompt with a specific version by commit hash.
+     *
+     * @param commit - Commit hash (8-char short form or full)
+     * @returns Prompt instance representing that version, or null if not found
+     *
+     * @example
+     * ```typescript
+     * const prompt = await client.getPrompt({ name: "greeting" });
+     *
+     * // Get a specific version directly as a Prompt
+     * const versionedPrompt = await prompt.getVersion("abc123de");
+     * if (versionedPrompt) {
+     *   const text = versionedPrompt.format({ name: "Alice" });
+     * }
+     * ```
+     */
+    getVersion(commit: string): Promise<Prompt | null>;
+}
+
+/**
+ * Extended TraceUpdate type that includes prompts field.
+ * Allows associating prompt versions with trace updates.
+ */
+interface TraceUpdateData extends Omit<TraceUpdate, "projectId"> {
+    prompts?: Prompt[];
+}
+/**
+ * Extended SpanUpdate type that includes prompts field.
+ * Allows associating prompt versions with span updates.
+ */
+interface SpanUpdateData extends Omit<SpanUpdate$1, "traceId" | "parentSpanId" | "projectId" | "projectName"> {
+    prompts?: Prompt[];
+}
+
 interface SavedSpan extends Span$1 {
     id: string;
 }
@@ -10339,7 +10640,7 @@ declare class Span {
         value: number;
         reason?: string;
     }) => void;
-    update: (updates: Omit<SpanUpdate$1, "traceId" | "parentSpanId" | "projectId" | "projectName">) => this;
+    update: (updates: SpanUpdateData) => this;
     span: (spanData: Omit<Span$1, "startTime" | "traceId" | "parentSpanId" | "projectId" | "projectName" | "id"> & {
         startTime?: Date;
     }) => Span;
@@ -10364,7 +10665,7 @@ declare class Trace {
         reason?: string;
     }) => void;
     span: (spanData: SpanData) => Span;
-    update: (updates: Omit<TraceUpdate, "projectId">) => this;
+    update: (updates: TraceUpdateData) => this;
 }
 
 interface BatchQueueOptions {
@@ -10487,433 +10788,147 @@ declare class DatasetBatchQueue extends BatchQueue<DatasetWrite> {
      * @param datasets The array of datasets to create
      */
     protected createEntities(datasets: DatasetWrite[]): Promise<void>;
-    /**
-     * Retrieves a dataset by its ID.
-     *
-     * @param id The ID of the dataset to retrieve
-     * @returns The retrieved dataset or undefined if not found
-     */
-    protected getEntity(id: string): Promise<DatasetPublic | undefined>;
-    /**
-     * Updates a dataset by its ID with the provided updates.
-     *
-     * @param id The ID of the dataset to update
-     * @param updates Partial dataset properties to update
-     */
-    protected updateEntity(id: string, updates: Partial<DatasetWrite>): Promise<void>;
-    /**
-     * Deletes multiple datasets by their IDs.
-     *
-     * @param ids Array of dataset IDs to delete
-     */
-    protected deleteEntities(ids: string[]): Promise<void>;
-}
-
-type DatasetItemData = JsonNode & {
-    id?: string;
-};
-
-interface DatasetData {
-    name: string;
-    description?: string;
-    id?: string;
-}
-declare class Dataset<T extends DatasetItemData = DatasetItemData> {
-    private opik;
-    readonly id: string;
-    readonly name: string;
-    readonly description?: string;
-    private idToHash;
-    private hashes;
-    /**
-     * Configuration object for creating a new Dataset instance.
-     * This should not be created directly, use static factory methods instead.
-     */
-    constructor({ name, description, id }: DatasetData, opik: OpikClient);
-    /**
-     * Insert new items into the dataset.
-     *
-     * @param items List of objects to add to the dataset
-     */
-    insert(items: T[]): Promise<void>;
-    /**
-     * Update existing items in the dataset.
-     * You need to provide the full item object as it will override what has been supplied previously.
-     *
-     * @param items List of objects to update in the dataset
-     */
-    update(items: T[]): Promise<void>;
-    /**
-     * Delete items from the dataset.
-     *
-     * @param itemIds List of item ids to delete
-     */
-    delete(itemIds: string[]): Promise<void>;
-    /**
-     * Delete all items from the dataset.
-     */
-    clear(): Promise<void>;
-    /**
-     * Retrieve a fixed number of dataset items.
-     *
-     * @param nbSamples The number of samples to retrieve. If not set - all items are returned
-     * @param lastRetrievedId Optional ID of the last retrieved item for pagination
-     * @returns A list of objects representing the dataset items
-     */
-    getItems(nbSamples?: number, lastRetrievedId?: string): Promise<(T & {
-        id: string;
-    })[]>;
-    private getItemsAsDataclasses;
-    /**
-     * Insert items from a JSON string array into the dataset.
-     *
-     * @param jsonArray JSON string of format: "[{...}, {...}, {...}]" where every object is transformed into a dataset item
-     * @param keysMapping Optional dictionary that maps JSON keys to dataset item field names (e.g., {'Expected output': 'expected_output'})
-     * @param ignoreKeys Optional array of keys that should be ignored when constructing dataset items
-     */
-    insertFromJson(jsonArray: string, keysMapping?: Record<string, string>, ignoreKeys?: string[]): Promise<void>;
-    /**
-     * Convert the dataset to a JSON string.
-     *
-     * @param keysMapping Optional dictionary that maps dataset item field names to output JSON keys
-     * @returns A JSON string representation of all items in the dataset
-     */
-    toJson(keysMapping?: Record<string, string>): Promise<string>;
-    /**
-     * Retrieves all items from the dataset, deduplicates them, and returns them.
-     *
-     * @returns A list of deduplicated dataset items
-     */
-    private getDeduplicatedItems;
-    /**
-     * Clears both hash tracking data structures
-     */
-    private clearHashState;
-    syncHashes(): Promise<void>;
-}
-
-/**
- * References to a dataset item and trace in an experiment.
- */
-declare class ExperimentItemReferences {
-    readonly datasetItemId: string;
-    readonly traceId: string;
-    constructor(params: {
-        datasetItemId: string;
-        traceId: string;
-    });
-}
-/**
- * Content of an experiment item including evaluation data and feedback scores.
- */
-declare class ExperimentItemContent {
-    readonly id?: string;
-    readonly datasetItemId: string;
-    readonly traceId: string;
-    readonly datasetItemData?: JsonListStringCompare;
-    readonly evaluationTaskOutput?: JsonListStringCompare;
-    readonly feedbackScores: FeedbackScore[];
-    constructor(params: {
-        id?: string;
-        datasetItemId: string;
-        traceId: string;
-        datasetItemData?: JsonListStringCompare;
-        evaluationTaskOutput?: JsonListStringCompare;
-        feedbackScores: FeedbackScore[];
-    });
-    /**
-     * Creates an ExperimentItemContent from a REST API ExperimentItemCompare object.
-     *
-     * @param value The REST API ExperimentItemCompare object
-     * @returns A new ExperimentItemContent instance
-     */
-    static fromRestExperimentItemCompare(value: ExperimentItemCompare): ExperimentItemContent;
-}
-
-/**
- * Supported template engine types for prompts
- * Re-exported from REST API with uppercase values for consistency
- */
-declare const PromptType: {
-    /** Mustache template syntax with {{variable}} placeholders */
-    readonly MUSTACHE: "mustache";
-    /** Jinja2 template syntax with {% %} blocks and {{ }} variables */
-    readonly JINJA2: "jinja2";
-};
-type PromptType = (typeof PromptType)[keyof typeof PromptType];
-/**
- * Configuration options for creating a new prompt
- * Extends REST API PromptWrite with renamed 'prompt' field
- */
-interface CreatePromptOptions {
-    /** Name of the prompt (unique identifier) */
-    name: string;
-    /** Template text content with placeholders */
-    prompt: string;
-    /** Optional prompt ID (generated if not provided) */
-    promptId?: string;
-    /** Optional description for the prompt */
-    description?: string;
-    /** Optional metadata for tracking and filtering */
-    metadata?: JsonNodeWrite;
-    /** Optional change description for version tracking */
-    changeDescription?: string;
-    /** Template engine type, defaults to mustache */
-    type?: PromptType;
-    /** Optional tags for categorization */
-    tags?: string[];
-}
-/**
- * Options for retrieving a specific prompt version
- * Re-exported from REST API PromptVersionRetrieveDetail
- */
-type GetPromptOptions = PromptVersionRetrieveDetail;
-/**
- * Variables to be substituted into prompt template.
- */
-type PromptVariables = Record<string, unknown>;
-/**
- * Data structure for creating a PromptVersion instance
- */
-interface PromptVersionData {
-    name: string;
-    prompt: string;
-    commit: string;
-    promptId: string;
-    versionId: string;
-    type: PromptType;
-    metadata?: JsonNode;
-    changeDescription?: string;
-    createdAt?: Date;
-    createdBy?: string;
-}
-
-/**
- * Represents a specific immutable snapshot of a prompt template at a point in time.
- * Pure data object with formatting capabilities.
- */
-declare class PromptVersion {
-    readonly id: string;
-    readonly name: string;
-    readonly prompt: string;
-    readonly commit: string;
-    readonly type: PromptType;
-    readonly metadata?: JsonNode;
-    readonly changeDescription?: string;
-    readonly createdAt?: Date;
-    readonly createdBy?: string;
-    constructor(data: PromptVersionData);
-    /**
-     * Format the prompt template with the provided variables
-     */
-    format(variables: PromptVariables): string;
-    /**
-     * Get human-readable version age (e.g., "2 days ago", "Today")
-     */
-    getVersionAge(): string;
-    /**
-     * Get formatted version information string
-     * Format: "[commitHash] YYYY-MM-DD by user@email.com - Change description"
-     */
-    getVersionInfo(): string;
-    /**
-     * Compare this version's template with another version and return a formatted diff.
-     * Displays a git-style unified diff showing additions, deletions, and changes.
-     * The diff is automatically logged to the terminal and also returned as a string.
-     * The output is colored and formatted for terminal display.
-     *
-     * @param other - The version to compare against
-     * @returns A formatted string showing the differences between versions
-     *
-     * @example
-     * ```typescript
-     * const currentVersion = await prompt.getVersion("commit123");
-     * const previousVersion = await prompt.getVersion("commit456");
+    /**
+     * Retrieves a dataset by its ID.
      *
-     * // Logs diff to terminal and returns it
-     * const diff = currentVersion.compareTo(previousVersion);
-     * ```
+     * @param id The ID of the dataset to retrieve
+     * @returns The retrieved dataset or undefined if not found
      */
-    compareTo(other: PromptVersion): string;
+    protected getEntity(id: string): Promise<DatasetPublic | undefined>;
     /**
-     * Factory method to create PromptVersion from API response
+     * Updates a dataset by its ID with the provided updates.
+     *
+     * @param id The ID of the dataset to update
+     * @param updates Partial dataset properties to update
      */
-    static fromApiResponse(name: string, apiResponse: PromptVersionDetail): PromptVersion;
+    protected updateEntity(id: string, updates: Partial<DatasetWrite>): Promise<void>;
+    /**
+     * Deletes multiple datasets by their IDs.
+     *
+     * @param ids Array of dataset IDs to delete
+     */
+    protected deleteEntities(ids: string[]): Promise<void>;
 }
 
-interface PromptData {
-    promptId: string;
-    versionId: string;
+type DatasetItemData = JsonNode & {
+    id?: string;
+};
+
+interface DatasetData {
     name: string;
-    prompt: string;
-    commit?: string;
-    metadata?: JsonNode;
-    type?: PromptType;
-    changeDescription?: string;
     description?: string;
-    tags?: string[];
+    id?: string;
 }
-/**
- * Domain object representing a versioned prompt template.
- * Provides immutable access to prompt properties and template formatting.
- * Integrates with backend for persistence and version management.
- */
-declare class Prompt {
+declare class Dataset<T extends DatasetItemData = DatasetItemData> {
     private opik;
     readonly id: string;
-    readonly versionId: string;
-    readonly prompt: string;
-    readonly commit: string | undefined;
-    readonly type: PromptType;
-    readonly changeDescription: string | undefined;
-    private _name;
-    private _description;
-    private _tags;
-    private readonly _metadata;
-    /**
-     * Creates a new Prompt instance.
-     * This should not be created directly, use OpikClient.createPrompt() instead.
-     */
-    constructor({ promptId, versionId, name, prompt, commit, metadata, type, changeDescription, description, tags, }: PromptData, opik: OpikClient);
-    get name(): string;
-    get description(): string | undefined;
-    get tags(): readonly string[] | undefined;
+    readonly name: string;
+    readonly description?: string;
+    private idToHash;
+    private hashes;
     /**
-     * Read-only metadata property.
-     * Returns deep copy to prevent external mutation.
+     * Configuration object for creating a new Dataset instance.
+     * This should not be created directly, use static factory methods instead.
      */
-    get metadata(): JsonNode | undefined;
+    constructor({ name, description, id }: DatasetData, opik: OpikClient);
     /**
-     * Formats prompt template by substituting variables.
-     * Validates that all template placeholders are provided (for Mustache templates).
-     *
-     * @param variables - Object with values to substitute into template
-     * @returns Formatted prompt text with variables substituted
-     * @throws PromptValidationError if template processing or validation fails
-     *
-     * @example
-     * ```typescript
-     * const prompt = new Prompt({
-     *   name: "greeting",
-     *   prompt: "Hello {{name}}, your score is {{score}}",
-     *   type: "mustache"
-     * }, client);
-     *
-     * // Valid - all placeholders provided
-     * prompt.format({ name: "Alice", score: 95 });
-     * // Returns: "Hello Alice, your score is 95"
+     * Insert new items into the dataset.
      *
-     * // Invalid - missing 'score' placeholder
-     * prompt.format({ name: "Alice" });
-     * // Throws: PromptValidationError
-     * ```
+     * @param items List of objects to add to the dataset
      */
-    format(variables: PromptVariables): string;
+    insert(items: T[]): Promise<void>;
     /**
-     * Static factory method to create Prompt from backend API response.
+     * Update existing items in the dataset.
+     * You need to provide the full item object as it will override what has been supplied previously.
      *
-     * @param name - Name of the prompt
-     * @param apiResponse - REST API PromptVersionDetail response
-     * @param opik - OpikClient instance
-     * @param promptPublicData - Optional PromptPublic data containing description and tags
-     * @returns Prompt instance constructed from response data
-     * @throws PromptValidationError if response structure invalid
+     * @param items List of objects to update in the dataset
      */
-    static fromApiResponse(promptData: PromptPublic, apiResponse: PromptVersionDetail, opik: OpikClient): Prompt;
+    update(items: T[]): Promise<void>;
     /**
-     * Updates prompt properties (name, description, and/or tags).
-     * Performs immediate update (no batching).
-     *
-     * @param updates - Partial updates with optional name, description, and tags
-     * @returns Promise resolving to this Prompt instance for method chaining
+     * Delete items from the dataset.
      *
-     * @example
-     * ```typescript
-     * const prompt = await client.getPrompt({ name: "my-prompt" });
-     * await prompt.updateProperties({
-     *   name: "renamed-prompt",
-     *   description: "Updated description",
-     *   tags: ["tag1", "tag2"]
-     * });
-     * ```
+     * @param itemIds List of item ids to delete
      */
-    updateProperties(updates: {
-        name?: string;
-        description?: string;
-        tags?: string[];
-    }): Promise<this>;
+    delete(itemIds: string[]): Promise<void>;
     /**
-     * Deletes this prompt from the backend.
-     * Performs immediate deletion (no batching).
+     * Delete all items from the dataset.
      */
-    delete(): Promise<void>;
+    clear(): Promise<void>;
     /**
-     * Retrieves all version history for this prompt.
-     * Fetches and returns complete version history, sorted by creation date (newest first).
-     * Automatically handles pagination to fetch all versions.
-     *
-     * @returns Promise resolving to array of all PromptVersion instances for this prompt
-     * @throws OpikApiError if REST API call fails
-     *
-     * @example
-     * ```typescript
-     * const prompt = await client.getPrompt({ name: "my-prompt" });
-     * const versions = await prompt.getVersions();
+     * Retrieve a fixed number of dataset items.
      *
-     * console.log(`Found ${versions.length} versions`);
-     * versions.forEach(v => {
-     *   console.log(`Commit: ${v.commit}, Age: ${v.getVersionAge()}`);
-     * });
-     * ```
+     * @param nbSamples The number of samples to retrieve. If not set - all items are returned
+     * @param lastRetrievedId Optional ID of the last retrieved item for pagination
+     * @returns A list of objects representing the dataset items
      */
-    getVersions(): Promise<PromptVersion[]>;
+    getItems(nbSamples?: number, lastRetrievedId?: string): Promise<(T & {
+        id: string;
+    })[]>;
+    private getItemsAsDataclasses;
     /**
-     * Restores a specific version by creating a new version with content from the specified version.
-     * The version must be obtained from the backend (e.g., via getVersions()).
-     * Returns a new Prompt instance with the restored content as the latest version.
-     *
-     * @param version - PromptVersion object to restore (must be from backend)
-     * @returns Promise resolving to a new Prompt instance with the restored version
-     * @throws OpikApiError if REST API call fails
-     *
-     * @example
-     * ```typescript
-     * const prompt = await client.getPrompt({ name: "my-prompt" });
-     *
-     * // Get all versions
-     * const versions = await prompt.getVersions();
-     *
-     * // Restore a specific version
-     * const targetVersion = versions.find(v => v.commit === "abc123de");
-     * if (targetVersion) {
-     *   const restoredPrompt = await prompt.useVersion(targetVersion);
-     *   console.log(`Restored to commit: ${restoredPrompt.commit}`);
-     *   console.log(`New template: ${restoredPrompt.prompt}`);
+     * Insert items from a JSON string array into the dataset.
      *
-     *   // Continue using the restored prompt
-     *   const formatted = restoredPrompt.format({ name: "World" });
-     * }
-     * ```
+     * @param jsonArray JSON string of format: "[{...}, {...}, {...}]" where every object is transformed into a dataset item
+     * @param keysMapping Optional dictionary that maps JSON keys to dataset item field names (e.g., {'Expected output': 'expected_output'})
+     * @param ignoreKeys Optional array of keys that should be ignored when constructing dataset items
      */
-    useVersion(version: PromptVersion): Promise<Prompt>;
+    insertFromJson(jsonArray: string, keysMapping?: Record<string, string>, ignoreKeys?: string[]): Promise<void>;
     /**
-     * Get a Prompt with a specific version by commit hash.
+     * Convert the dataset to a JSON string.
      *
-     * @param commit - Commit hash (8-char short form or full)
-     * @returns Prompt instance representing that version, or null if not found
+     * @param keysMapping Optional dictionary that maps dataset item field names to output JSON keys
+     * @returns A JSON string representation of all items in the dataset
+     */
+    toJson(keysMapping?: Record<string, string>): Promise<string>;
+    /**
+     * Retrieves all items from the dataset, deduplicates them, and returns them.
      *
-     * @example
-     * ```typescript
-     * const prompt = await client.getPrompt({ name: "greeting" });
+     * @returns A list of deduplicated dataset items
+     */
+    private getDeduplicatedItems;
+    /**
+     * Clears both hash tracking data structures
+     */
+    private clearHashState;
+    syncHashes(): Promise<void>;
+}
+
+/**
+ * References to a dataset item and trace in an experiment.
+ */
+declare class ExperimentItemReferences {
+    readonly datasetItemId: string;
+    readonly traceId: string;
+    constructor(params: {
+        datasetItemId: string;
+        traceId: string;
+    });
+}
+/**
+ * Content of an experiment item including evaluation data and feedback scores.
+ */
+declare class ExperimentItemContent {
+    readonly id?: string;
+    readonly datasetItemId: string;
+    readonly traceId: string;
+    readonly datasetItemData?: JsonListStringCompare;
+    readonly evaluationTaskOutput?: JsonListStringCompare;
+    readonly feedbackScores: FeedbackScore[];
+    constructor(params: {
+        id?: string;
+        datasetItemId: string;
+        traceId: string;
+        datasetItemData?: JsonListStringCompare;
+        evaluationTaskOutput?: JsonListStringCompare;
+        feedbackScores: FeedbackScore[];
+    });
+    /**
+     * Creates an ExperimentItemContent from a REST API ExperimentItemCompare object.
      *
-     * // Get a specific version directly as a Prompt
-     * const versionedPrompt = await prompt.getVersion("abc123de");
-     * if (versionedPrompt) {
-     *   const text = versionedPrompt.format({ name: "Alice" });
-     * }
-     * ```
+     * @param value The REST API ExperimentItemCompare object
+     * @returns A new ExperimentItemContent instance
      */
-    getVersion(commit: string): Promise<Prompt | null>;
+    static fromRestExperimentItemCompare(value: ExperimentItemCompare): ExperimentItemContent;
 }
 
 interface ExperimentData {