Opik¶

class opik.Opik(project_name: str | None = None, workspace: str | None = None, host: str | None = None, _use_batching: bool = False)¶

Bases: object

__init__(project_name: str | None = None, workspace: str | None = None, host: str | None = None, _use_batching: bool = False) → None¶

Initialize an Opik object that can be used to log traces and spans manually to Opik server.

Parameters:

project_name – The name of the project. If not provided, traces and spans will be logged to the Default Project.
workspace – The name of the workspace. If not provided, default will be used.
host – The host URL for the Opik server. If not provided, it will default to https://www.comet.com/opik/api.
_use_batching – intended for internal usage in specific conditions only. Enabling it is unsafe and can lead to data loss.

Returns:

None

Create and log a new trace.

Parameters:

id – The unique identifier for the trace, if not provided a new ID will be generated. Must be a valid [UUIDv8](https://uuid.ramsey.dev/en/stable/rfc4122/version8.html) ID.
name – The name of the trace.
start_time – The start time of the trace. If not provided, the current local time will be used.
end_time – The end time of the trace.
input – The input data for the trace. This can be any valid JSON serializable object.
output – The output data for the trace. This can be any valid JSON serializable object.
metadata – Additional metadata for the trace. This can be any valid JSON serializable object.
tags – Tags associated with the trace.
feedback_scores – The list of feedback score dicts associated with the trace. Dicts don’t require to have an id value.
project_name – The name of the project. If not set, the project name which was configured when Opik instance was created will be used.

Returns:

The created trace object.

Return type:

trace.Trace

Create and log a new span.

Parameters:

trace_id – The unique identifier for the trace. If not provided, a new ID will be generated. Must be a valid [UUIDv8](https://uuid.ramsey.dev/en/stable/rfc4122/version8.html) ID.
id – The unique identifier for the span. If not provided, a new ID will be generated. Must be a valid [UUIDv8](https://uuid.ramsey.dev/en/stable/rfc4122/version8.html) ID.
parent_span_id – The unique identifier for the parent span.
name – The name of the span.
type – The type of the span. Default is “general”.
start_time – The start time of the span. If not provided, the current local time will be used.
end_time – The end time of the span.
metadata – Additional metadata for the span. This can be any valid JSON serializable object.
input – The input data for the span. This can be any valid JSON serializable object.
output – The output data for the span. This can be any valid JSON serializable object.
tags – Tags associated with the span.
usage – Usage data for the span.
feedback_scores – The list of feedback score dicts associated with the span. Dicts don’t require to have an id value.
project_name – The name of the project. If not set, the project name which was configured when Opik instance was created will be used.

Returns:

The created span object.

Return type:

span.Span

log_spans_feedback_scores(scores: List[FeedbackScoreDict], project_name: str | None = None) → None¶

Log feedback scores for spans.

Parameters:

scores (List[FeedbackScoreDict]) – A list of feedback score dictionaries. Specifying a span id via id key for each score is mandatory.
project_name – The name of the project in which the spans are logged. If not set, the project name which was configured when Opik instance was created will be used.

Returns:

None

log_traces_feedback_scores(scores: List[FeedbackScoreDict], project_name: str | None = None) → None¶

Log feedback scores for traces.

Parameters:

scores (List[FeedbackScoreDict]) – A list of feedback score dictionaries. Specifying a trace id via id key for each score is mandatory.
project_name – The name of the project in which the traces are logged. If not set, the project name which was configured when Opik instance was created will be used.

Returns:

None

get_dataset(name: str) → Dataset¶

Get dataset by name

Parameters:: name – The name of the dataset
Returns:: dataset object associated with the name passed.
Return type:: dataset.Dataset

delete_dataset(name: str) → None¶

Delete dataset by name

Parameters:: name – The name of the dataset

create_dataset(name: str, description: str | None = None) → Dataset¶

Create a new dataset.

Parameters:

name – The name of the dataset.
description – An optional description of the dataset.

Returns:

The created dataset object.

Return type:

dataset.Dataset

get_or_create_dataset(name: str, description: str | None = None) → Dataset¶

Get an existing dataset by name or create a new one if it does not exist.

Parameters:

name – The name of the dataset.
description – An optional description of the dataset.

Returns:

The dataset object.

Return type:

dataset.Dataset

create_experiment(dataset_name: str, name: str | None = None, experiment_config: Dict[str, Any] | None = None, prompt: Prompt | None = None) → Experiment¶

Creates a new experiment using the given dataset name and optional parameters.

Parameters:

dataset_name – The name of the dataset to associate with the experiment.
name – The optional name for the experiment. If None, a generated name will be used.
experiment_config – Optional experiment configuration parameters. Must be a dictionary if provided.
prompt – Prompt object to associate with the experiment.

Returns:

The newly created experiment object.

Return type:

experiment.Experiment

end(timeout: int | None = None) → None¶

End the Opik session and submit all pending messages.

Parameters:: timeout (Optional[int]) – The timeout for closing the streamer. Once the timeout is reached, the streamer will be closed regardless of whether all messages have been sent. If no timeout is set, the default value from the Opik configuration will be used.
Returns:: None

flush(timeout: int | None = None) → None¶

Flush the streamer to ensure all messages are sent.

Parameters:: timeout (Optional[int]) – The timeout for flushing the streamer. Once the timeout is reached, the flush method will return regardless of whether all messages have been sent.
Returns:: None

search_traces(project_name: str | None = None, filter_string: str | None = None, max_results: int = 1000) → List[TracePublic]¶

Search for traces in the given project.

Parameters:

project_name – The name of the project to search traces in. If not provided, will search across the project name configured when the Client was created which defaults to the Default Project.
filter_string – A filter string to narrow down the search. If not provided, all traces in the project will be returned up to the limit.
max_results – The maximum number of traces to return.

search_spans(project_name: str | None = None, trace_id: str | None = None, filter_string: str | None = None, max_results: int = 1000) → List[SpanPublic]¶

Search for spans in the given trace. This allows you to search spans based on the span input, output, metadata, tags, etc or based on the trace ID.

Parameters:

project_name – The name of the project to search spans in. If not provided, will search across the project name configured when the Client was created which defaults to the Default Project.
trace_id – The ID of the trace to search spans in. If provided, the search will be limited to the spans in the given trace.
filter_string – A filter string to narrow down the search.
max_results – The maximum number of spans to return.

get_trace_content(id: str) → TracePublic¶

Parameters:: id (str) – trace id
Returns:: pydantic model object with all the data associated with the trace found. Raises an error if trace was not found.
Return type:: trace_public.TracePublic

get_span_content(id: str) → SpanPublic¶

Parameters:: id (str) – span id
Returns:: pydantic model object with all the data associated with the span found. Raises an error if span was not found.
Return type:: span_public.SpanPublic

get_project(id: str) → ProjectPublic¶

Fetches a project by its unique identifier.

Parameters:: id (str) – project if (uuid).
Returns:: pydantic model object with all the data associated with the project found. Raises an error if project was not found
Return type:: project_public.ProjectPublic

create_prompt(name: str, prompt: str) → Prompt¶

Creates a new prompt with the given name and template. If a prompt with the same name already exists, it will create a new version of the existing prompt if the templates differ.

Parameters:

name – The name of the prompt.
prompt – The template content of the prompt.

Returns:

A Prompt object containing details of the created or retrieved prompt.

Raises:

ApiError – If there is an error during the creation of the prompt and the status code is not 409.

get_prompt(name: str, commit: str | None = None) → Prompt | None¶

Retrieve the prompt detail for a given prompt name and commit version.

Parameters:

name – The name of the prompt.
commit – An optional commit version of the prompt. If not provided, the latest version is retrieved.

Returns:

The details of the specified prompt.

Return type:

Prompt