Opik¶

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

Bases: object

__init__(project_name: str | None = None, workspace: str | None = None, host: str | None = None, api_key: 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.
api_key – The API key for Opik. This parameter is ignored for local installations.
_use_batching – intended for internal usage in specific conditions only. Enabling it is unsafe and can lead to data loss.

Returns:

None

property config: OpikConfig¶: Returns: config.OpikConfig: Read-only copy of the configuration of the Opik client.

auth_check() → None¶: Checks if current API key user has an access to the configured workspace and its content.

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.
error_info – The dictionary with error information (typically used when the trace function has failed).

Returns:

The created trace object.

Return type:

trace.Trace

copy_traces(project_name: str, destination_project_name: str, delete_original_project: bool = False) → None¶

Copy traces from one project to another. This method will copy all traces in a source project to the destination project. Optionally, you can also delete these traces from the source project.

As the traces are copied, the IDs for both traces and spans will be updated as part of the copy process.

Note: This method is not optimized for large projects, if you run into any issues please raise an issue on GitHub. In addition, be aware that deleting traces that are linked to experiments will lead to inconsistancies in the UI.

Parameters:

project_name – The name of the project to copy traces from.
destination_project_name – The name of the project to copy traces to.
delete_original_project – Whether to delete the original project. Defaults to False.

Returns:

None

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.
model – The name of LLM (in this case type parameter should be == llm)
provider – The provider of LLM.
error_info – The dictionary with error information (typically used when the span function has failed).
total_cost – The cost of the span in USD. This value takes priority over the cost calculated by Opik from the usage.

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

get_datasets(max_results: int = 100, sync_items: bool = True) → List[Dataset]¶

Returns all datasets up to the specified limit.

Parameters:

max_results – The maximum number of datasets to return.
sync_items – Whether to sync the hashes of the dataset items. This is used to deduplicate items when fetching the dataset but it can be an expensive operation.

Returns:

A list of dataset objects that match the filter string.

Return type:

List[dataset.Dataset]

get_dataset_experiments(dataset_name: str, max_results: int = 100) → List[Experiment]¶

Returns all experiments up to the specified limit.

Parameters:

dataset_name – The name of the dataset
max_results – The maximum number of experiments to return.

Returns:

A list of experiment objects.

Return type:

List[experiment.Experiment]

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, prompts: List[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. Deprecated, use prompts argument instead.
prompts – List of Prompt objects to associate with the experiment.

Returns:

The newly created experiment object.

Return type:

experiment.Experiment

get_experiment_by_name(name: str) → Experiment¶

Returns an existing experiment by its name.

Parameters:: name – The name of the experiment.
Returns:: the API object for an existing experiment.
Return type:: experiment.Experiment

get_experiment_by_id(id: str) → Experiment¶

Returns an existing experiment by its id.

Parameters:: id – The id of the experiment.
Returns:: the API object for an existing experiment.
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, truncate: bool = True) → 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.
truncate – Whether to truncate image data stored in input, output or metadata

search_spans(project_name: str | None = None, trace_id: str | None = None, filter_string: str | None = None, max_results: int = 1000, truncate: bool = True) → 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.
truncate – Whether to truncate image data stored in input, output or metadata

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

get_project_url(project_name: str | None = None) → str¶

Returns a URL to the project in the current workspace. This method does not make any requests or perform any checks (e.g. that the project exists). It only builds a URL string based on the data provided.

Parameters:: project_name (str) – project name to return URL for. If not provided, a default project name for the current Opik instance will be used.
Returns:: URL
Return type:: str

create_prompt(name: str, prompt: str, metadata: Dict[str, Any] | None = None) → 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