OptimizationCandidate Class

Aggregated evaluation result for a single candidate agent configuration across all tasks.

Constructor

OptimizationCandidate(*args: Any, **kwargs: Any)

Variables

Name	Description
candidate_id	str Server-assigned candidate identifier. Use with GET /candidates/{id} sub-endpoints.
name	str Display name of the candidate (e.g., 'baseline', 'instruction-v2'). Required.
config	OptimizationAgentDefinition The agent configuration that produced this candidate. Required.
mutations	dict[str, any] What was mutated from the baseline (e.g., {system_prompt: 'new prompt'}). Required.
avg_score	float Average composite score across all tasks. Required.
avg_tokens	float Average token usage across all tasks. Required.
pass_rate	float Fraction of tasks that met the pass threshold. Required.
task_scores	list[OptimizationTaskResult] Individual task-level scores. Required.
is_pareto_optimal	bool Whether this candidate is on the Pareto frontier (score vs cost). Required.
eval_id	str Foundry evaluation identifier used to score this candidate.
eval_run_id	str Foundry evaluation run identifier for this candidate's scoring run.
promotion	PromotionInfo Promotion metadata. Null if the candidate has not been promoted.

Methods

as_dict	Return a dict that can be turned into json using json.dump.
clear	Remove all items from D.
copy
get	Get the value for key if key is in the dictionary, else default. :param str key: The key to look up. :param any default: The value to return if key is not in the dictionary. Defaults to None :returns: D[k] if k in D, else d. :rtype: any
items
keys
pop	Removes specified key and return the corresponding value. :param str key: The key to pop. :param any default: The value to return if key is not in the dictionary :returns: The value corresponding to the key. :rtype: any :raises KeyError: If key is not found and default is not given.
popitem	Removes and returns some (key, value) pair :returns: The (key, value) pair. :rtype: tuple :raises KeyError: if D is empty.
setdefault	Same as calling D.get(k, d), and setting D[k]=d if k not found :param str key: The key to look up. :param any default: The value to set if key is not in the dictionary :returns: D[k] if k in D, else d. :rtype: any
update	Updates D from mapping/iterable E and F. :param any args: Either a mapping object or an iterable of key-value pairs.
values

as_dict

Return a dict that can be turned into json using json.dump.

as_dict(*, exclude_readonly: bool = False) -> dict[str, Any]

Keyword-Only Parameters

Name	Description
exclude_readonly	bool Whether to remove the readonly properties. Default value: False

Returns

Type	Description
dict	A dict JSON compatible object

clear

Remove all items from D.

clear() -> None

copy

copy() -> Model

get

Get the value for key if key is in the dictionary, else default. :param str key: The key to look up. :param any default: The value to return if key is not in the dictionary. Defaults to None :returns: D[k] if k in D, else d. :rtype: any

get(key: str, default: Any = None) -> Any

Parameters

Name	Description
key Required
default	Default value: None

items

items() -> ItemsView[str, Any]

Returns

Type	Description
ItemsView	set-like object providing a view on D's items

keys

keys() -> KeysView[str]

Returns

Type	Description
KeysView	a set-like object providing a view on D's keys

pop

Removes specified key and return the corresponding value. :param str key: The key to pop. :param any default: The value to return if key is not in the dictionary :returns: The value corresponding to the key. :rtype: any :raises KeyError: If key is not found and default is not given.

pop(key: str, default: ~typing.Any = <object object>) -> Any

Parameters

Name	Description
key Required
default

popitem

Removes and returns some (key, value) pair :returns: The (key, value) pair. :rtype: tuple :raises KeyError: if D is empty.

popitem() -> tuple[str, Any]

setdefault

Same as calling D.get(k, d), and setting D[k]=d if k not found :param str key: The key to look up. :param any default: The value to set if key is not in the dictionary :returns: D[k] if k in D, else d. :rtype: any

setdefault(key: str, default: ~typing.Any = <object object>) -> Any

Parameters

Name	Description
key Required
default

update

Updates D from mapping/iterable E and F. :param any args: Either a mapping object or an iterable of key-value pairs.

update(*args: Any, **kwargs: Any) -> None

values

values() -> ValuesView[Any]

Returns

Type	Description
ValuesView	an object providing a view on D's values

Attributes

avg_score

Average composite score across all tasks. Required.

avg_score: float

avg_tokens

Average token usage across all tasks. Required.

avg_tokens: float

candidate_id

Server-assigned candidate identifier. Use with GET /candidates/{id} sub-endpoints.

candidate_id: str | None

config

The agent configuration that produced this candidate. Required.

config: _models.OptimizationAgentDefinition

eval_id

Foundry evaluation identifier used to score this candidate.

eval_id: str | None

eval_run_id

Foundry evaluation run identifier for this candidate's scoring run.

eval_run_id: str | None

is_pareto_optimal

Whether this candidate is on the Pareto frontier (score vs cost). Required.

is_pareto_optimal: bool

mutations

'new prompt'}). Required.

mutations: dict[str, Any]

name

Display name of the candidate (e.g., 'baseline', 'instruction-v2'). Required.

name: str

pass_rate

Fraction of tasks that met the pass threshold. Required.

pass_rate: float

promotion

Promotion metadata. Null if the candidate has not been promoted.

promotion: _models.PromotionInfo | None

task_scores

Individual task-level scores. Required.

task_scores: list['_models.OptimizationTaskResult']