Opik Agent Optimizer API Reference

Technical SDK reference guide

The Opik Agent Optimizer SDK provides a set of tools for optimizing LLM prompts. This reference guide will help you understand the available APIs and how to use them effectively.

FewShotBayesianOptimizer

1FewShotBayesianOptimizer(
2 model: str,
3 project_name: Optional = 'Optimization',
4 min_examples: int = 2,
5 max_examples: int = 8,
6 seed: int = 42,
7 n_threads: int = 8,
8 verbose: int = 1,
9 model_kwargs: None
10)

Parameters:

model
str

The model to used to evaluate the prompt

project_name
Optional

Optional project name for tracking

min_examples
int

Minimum number of examples to include

max_examples
int

Maximum number of examples to include

seed
int

Random seed for reproducibility

n_threads
int

Number of threads for parallel evaluation

verbose
int

Controls internal logging/progress bars (0=off, 1=on).

model_kwargs
None

Methods

evaluate_prompt

1evaluate_prompt(
2 prompt: ChatPrompt,
3 dataset: Dataset,
4 metric: Callable,
5 dataset_item_ids: Optional = None,
6 experiment_config: Optional = None,
7 optimization_id: Optional = None,
8 n_samples: Optional = None
9)

Parameters:

prompt
ChatPrompt

The prompt to evaluate

dataset
Dataset

Opik Dataset to evaluate the prompt on

metric
Callable

Metric function to evaluate on, should have the arguments dataset_item and llm_output

dataset_item_ids
Optional

Optional list of dataset item IDs to evaluate

experiment_config
Optional

Optional configuration for the experiment

optimization_id
Optional

Optional ID of the optimization

n_samples
Optional

Optional number of items to test in the dataset

get_history

1get_history()

optimize_prompt

1optimize_prompt(
2 prompt: ChatPrompt,
3 dataset: Dataset,
4 metric: Callable,
5 n_trials: int = 10,
6 experiment_config: Optional = None,
7 n_samples: Optional = None
8)

Parameters:

prompt
ChatPrompt

The prompt to optimize

dataset
Dataset

Opik Dataset to optimize on

metric
Callable

Metric function to evaluate on

n_trials
int

Number of trials for Bayesian Optimization

experiment_config
Optional

Optional configuration for the experiment, useful to log additional metadata

n_samples
Optional

Optional number of items to test in the dataset

update_optimization

1update_optimization(
2 optimization: None,
3 status: str
4)

Parameters:

optimization
None
status
str

MetaPromptOptimizer

1MetaPromptOptimizer(
2 model: str,
3 reasoning_model: Optional = None,
4 rounds: int = 3,
5 num_prompts_per_round: int = 4,
6 num_threads: int = 12,
7 project_name: str = 'Optimization',
8 verbose: int = 1,
9 enable_context: bool = True,
10 model_kwargs: None
11)

Parameters:

model
str

The model to use for evaluation

reasoning_model
Optional

The model to use for reasoning and prompt generation

rounds
int

Number of optimization rounds

num_prompts_per_round
int

Number of prompts to generate per round

num_threads
int

Number of threads for parallel evaluation

project_name
str

Optional project name for tracking

verbose
int

Controls internal logging/progress bars (0=off, 1=on).

enable_context
bool

Whether to include task-specific context (metrics, examples) in the reasoning prompt.

model_kwargs
None

Methods

evaluate_prompt

1evaluate_prompt(
2 prompt: ChatPrompt,
3 dataset: Dataset,
4 metric: Callable,
5 use_full_dataset: bool = True,
6 experiment_config: Optional = None,
7 n_samples: Optional = None,
8 optimization_id: Optional = None,
9 verbose: int = 1
10)

Parameters:

prompt
ChatPrompt

The prompt to evaluate

dataset
Dataset

Opik Dataset to evaluate the prompt on

metric
Callable

Metric functions

use_full_dataset
bool

Whether to use the full dataset or a subset

experiment_config
Optional

Optional configuration for the experiment, useful to log additional metadata

n_samples
Optional

Optional number of items to test in the dataset

optimization_id
Optional

Optional ID of the optimization

verbose
int

Controls internal logging/progress bars (0=off, 1=on).

get_history

1get_history()

optimize_prompt

1optimize_prompt(
2 prompt: ChatPrompt,
3 dataset: Dataset,
4 metric: Callable,
5 experiment_config: Optional = None,
6 n_samples: Optional = None,
7 auto_continue: bool = False,
8 kwargs: None
9)

Parameters:

prompt
ChatPrompt

The prompt to optimize

dataset
Dataset

The dataset to evaluate against

metric
Callable

The metric to use for evaluation

experiment_config
Optional

A dictionary to log with the experiments

n_samples
Optional

The number of dataset items to use for evaluation

auto_continue
bool

If True, the algorithm may continue if goal not met

kwargs
None

update_optimization

1update_optimization(
2 optimization: None,
3 status: str
4)

Parameters:

optimization
None
status
str

EvolutionaryOptimizer

1EvolutionaryOptimizer(
2 model: str,
3 project_name: str = 'Optimization',
4 population_size: int = 30,
5 num_generations: int = 15,
6 mutation_rate: float = 0.2,
7 crossover_rate: float = 0.8,
8 tournament_size: int = 4,
9 num_threads: int = 12,
10 elitism_size: int = 3,
11 adaptive_mutation: bool = True,
12 enable_moo: bool = True,
13 enable_llm_crossover: bool = True,
14 seed: Optional = 42,
15 output_style_guidance: Optional = None,
16 infer_output_style: bool = False,
17 verbose: int = 1,
18 model_kwargs: None
19)

Parameters:

model
str

The model to use for evaluation

project_name
str

Optional project name for tracking

population_size
int

Number of prompts in the population

num_generations
int

Number of generations to run

mutation_rate
float

Mutation rate for genetic operations

crossover_rate
float

Crossover rate for genetic operations

tournament_size
int

Tournament size for selection

num_threads
int

Number of threads for parallel evaluation

elitism_size
int

Number of elitism prompts

adaptive_mutation
bool

Whether to use adaptive mutation

enable_moo
bool

Whether to enable multi-objective optimization - When enable optimizes for both the supplied metric and the length of the prompt

enable_llm_crossover
bool

Whether to enable LLM crossover

seed
Optional

Random seed for reproducibility

output_style_guidance
Optional

Output style guidance for prompts

infer_output_style
bool

Whether to infer output style

verbose
int

Controls internal logging/progress bars (0=off, 1=on).

model_kwargs
None

Methods

evaluate_prompt

1evaluate_prompt(
2 prompt: ChatPrompt,
3 dataset: Dataset,
4 metric: Callable,
5 n_samples: Optional = None,
6 dataset_item_ids: Optional = None,
7 experiment_config: Optional = None,
8 optimization_id: Optional = None,
9 verbose: int = 0
10)

Parameters:

prompt
ChatPrompt

The prompt to evaluate

dataset
Dataset

The dataset to use for evaluation

metric
Callable

Metric function to evaluate on, should have the arguments dataset_item and llm_output

n_samples
Optional

Optional number of samples to use

dataset_item_ids
Optional

Optional list of dataset item IDs to use

experiment_config
Optional

Optional experiment configuration

optimization_id
Optional

Optional optimization ID

verbose
int

Controls internal logging/progress bars (0=off, 1=on).

get_history

1get_history()

get_llm_crossover_system_prompt

1get_llm_crossover_system_prompt()

optimize_prompt

1optimize_prompt(
2 prompt: ChatPrompt,
3 dataset: Dataset,
4 metric: Callable,
5 experiment_config: Optional = None,
6 n_samples: Optional = None,
7 auto_continue: bool = False,
8 kwargs: None
9)

Parameters:

prompt
ChatPrompt

The prompt to optimize

dataset
Dataset

The dataset to use for evaluation

metric
Callable

Metric function to optimize with, should have the arguments dataset_item and llm_output

experiment_config
Optional

Optional experiment configuration

n_samples
Optional

Optional number of samples to use

auto_continue
bool

Whether to automatically continue optimization

kwargs
None

update_optimization

1update_optimization(
2 optimization: None,
3 status: str
4)

Parameters:

optimization
None
status
str

ChatPrompt

1ChatPrompt(
2 system: Optional = None,
3 prompt: Optional = None,
4 messages: Optional = None,
5 tools: Optional = None
6)

Parameters:

system
Optional
prompt
Optional
messages
Optional
tools
Optional

Methods

format

1format(
2 kwargs: Any
3)

Parameters:

kwargs
Any

to_dict

1to_dict()

OptimizationResult

1OptimizationResult(
2 optimizer: <class 'str'> = 'Optimizer',
3 prompt: List[Dict[Literal['role', 'content'], str]],
4 score: <class 'float'>,
5 metric_name: <class 'str'>,
6 initial_prompt: Optional[List[Dict[Literal['role', 'content'], str]]] = None,
7 initial_score: Optional[float] = None,
8 details: Dict[str, Any] = PydanticUndefined,
9 history: List[Dict[str, Any]] = [],
10 llm_calls: Optional[int] = None,
11 demonstrations: Optional[List[Dict[str, Any]]] = None,
12 mipro_prompt: Optional[str] = None,
13 tool_prompts: Optional[Dict[str, str]] = None
14)

Parameters:

optimizer
<class 'str'>
prompt
List[Dict[Literal['role', 'content'], str]]
score
<class 'float'>
metric_name
<class 'str'>
initial_prompt
Optional[List[Dict[Literal['role', 'content'], str]]]
initial_score
Optional[float]
details
Dict[str, Any]
history
List[Dict[str, Any]]
llm_calls
Optional[int]
demonstrations
Optional[List[Dict[str, Any]]]
mipro_prompt
Optional[str]
tool_prompts
Optional[Dict[str, str]]