Experiment

class opik.api_objects.experiment.experiment.Experiment(id: str, name: str | None, dataset_name: str, rest_client: OpikApi, streamer: Streamer, experiments_client: ExperimentsClient, prompts: List[BasePrompt] | None = None, tags: List[str] | None = None, project_name: str | None = None)

Bases: object

__init__(id: str, name: str | None, dataset_name: str, rest_client: OpikApi, streamer: Streamer, experiments_client: ExperimentsClient, prompts: List[BasePrompt] | None = None, tags: List[str] | None = None, project_name: str | None = None) → None

property project_name: str | None

property id: str

property dataset_name: str

property name: str

property tags: List[str] | None

property prompts: List[BasePrompt] | None

property dataset_id: str

property experiments_rest_client: ExperimentsClient

get_experiment_data() → ExperimentPublic

insert(experiment_items_references: List[ExperimentItemReferences]) → None

Creates a new experiment item by linking the existing trace and dataset item.

Parameters:

experiment_items_references – The list of ExperimentItemReferences objects, containing trace id and dataset item id to link together into experiment item.

Returns:

None

batch_upload_items(items: List[ExperimentItemBulkRecord], project_name: str | None = None, num_threads: int = 1) → None

Upload experiment items together with their traces, spans and feedback scores.

Unlike insert(), which only links already-existing traces to dataset items, this method creates the traces and spans as part of the same request.

Items are validated up front, split into batches that respect the backend’s 1000-item and 4MB-per-request limits, and sent with automatic retry on rate limiting (HTTP 429).

If a batch fails, the exception propagates and the remaining batches are not sent, leaving the experiment partially populated. Rate-limit retries re-send the identical payload, so they never duplicate anything. Calling this method again, however, mints new ids for any trace or span left without one, which would duplicate whatever the first call did manage to write — set id on the traces and spans you pass in if you intend to retry a failed upload.

Parameters:

• items – The experiment items to upload. Each item must provide exactly one of evaluate_task_result or trace.

• project_name – Project for traces auto-created from items that provide evaluate_task_result. Defaults to the experiment’s project; blank is treated as unset. When set, every item-level trace.project_name must match it.

• num_threads – Number of batches to upload concurrently. Defaults to 1 (sequential). Raising it trades ordering and a higher chance of being rate limited for throughput. Capped at the number of batches and at constants.EXPERIMENT_ITEMS_BULK_MAX_THREADS.

Returns:

None

Raises:

opik.exceptions.ValidationError – If any item fails validation, if a single item is too large to fit in one request, or if num_threads is less than 1.

get_items(max_results: int | None = 10000, truncate: bool = False) → List[ExperimentItemContent]

Retrieves and returns a list of experiment items for this experiment.

Parameters:

• max_results – Maximum number of experiment items to retrieve. Defaults to 10000 if not specified.

• truncate – Whether to truncate the items returned by the backend. Defaults to False.

Returns:

List of ExperimentItemContent objects for this experiment.

log_experiment_scores(score_results: List[score_result.ScoreResult]) → None

Log experiment-level scores to the backend.