Design
Bases: StrEnum
Wire method value for a design-run request.
Attributes:
| Name | Type | Description |
|---|---|---|
GENERATE |
|
|
SPACE_FILLING |
|
Bases: StrEnum
Structured preflight failure codes returned by design-run validation.
Attributes:
Bases: BaseAlbertModel
A single validation failure for a design-run configuration.
Show JSON schema:
{
"$defs": {
"DesignRunViolationCode": {
"description": "Structured preflight failure codes returned by design-run validation.",
"enum": [
"invalid_settings",
"dataset_not_ready",
"objective_out_of_scope",
"no_performance_targets",
"invalid_objective",
"insufficient_training_data",
"infeasible_design_space",
"model_training_error",
"optimization_system_mismatch",
"internal",
"job_timeout"
],
"title": "DesignRunViolationCode",
"type": "string"
}
},
"description": "A single validation failure for a design-run configuration.",
"properties": {
"code": {
"$ref": "#/$defs/DesignRunViolationCode",
"description": "Machine-readable violation category."
},
"message": {
"description": "Human-readable explanation of the failure.",
"title": "Message",
"type": "string"
},
"targetId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Target id when the violation is scoped to one performance target.",
"title": "Targetid"
}
},
"required": [
"code",
"message"
],
"title": "DesignRunViolation",
"type": "object"
}
Fields:
target_id: str | None = None
Target id when the violation is scoped to one performance target.
Bases: BaseAlbertModel
Preflight result for a design-run configuration.
Show JSON schema:
{
"$defs": {
"DesignRunViolation": {
"description": "A single validation failure for a design-run configuration.",
"properties": {
"code": {
"$ref": "#/$defs/DesignRunViolationCode",
"description": "Machine-readable violation category."
},
"message": {
"description": "Human-readable explanation of the failure.",
"title": "Message",
"type": "string"
},
"targetId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Target id when the violation is scoped to one performance target.",
"title": "Targetid"
}
},
"required": [
"code",
"message"
],
"title": "DesignRunViolation",
"type": "object"
},
"DesignRunViolationCode": {
"description": "Structured preflight failure codes returned by design-run validation.",
"enum": [
"invalid_settings",
"dataset_not_ready",
"objective_out_of_scope",
"no_performance_targets",
"invalid_objective",
"insufficient_training_data",
"infeasible_design_space",
"model_training_error",
"optimization_system_mismatch",
"internal",
"job_timeout"
],
"title": "DesignRunViolationCode",
"type": "string"
}
},
"description": "Preflight result for a design-run configuration.",
"properties": {
"valid": {
"description": "Whether the configuration passed validation.",
"title": "Valid",
"type": "boolean"
},
"violations": {
"description": "Structured failures when ``valid`` is ``False``.",
"items": {
"$ref": "#/$defs/DesignRunViolation"
},
"title": "Violations",
"type": "array"
},
"targetSampleCounts": {
"anyOf": [
{
"additionalProperties": {
"type": "integer"
},
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Non-null measurement count per performance target in the dataset scope.",
"title": "Targetsamplecounts"
}
},
"required": [
"valid"
],
"title": "DesignRunValidationResponse",
"type": "object"
}
Fields:
-
valid(bool) -
violations(list[DesignRunViolation]) -
target_sample_counts(dict[str, int] | None)
Bases: BaseAlbertModel
Settings for a model-guided optimization design run.
All fields are optional; omit a field (or pass None) to use the platform
default for that knob. Values outside the allowed ranges are rejected before
the run is submitted.
Notes
These two settings work together: candidate generation produces up to
num_candidates_generated candidates, then the top num_candidates_selected
diverse formulations are kept as the result batch.
Show JSON schema:
{
"description": "Settings for a model-guided optimization design run.\n\nAll fields are optional; omit a field (or pass ``None``) to use the platform\ndefault for that knob. Values outside the allowed ranges are rejected before\nthe run is submitted.\n\nNotes\n-----\nThese two settings work together: candidate generation produces up to\n``num_candidates_generated`` candidates, then the top ``num_candidates_selected``\ndiverse formulations are kept as the result batch.",
"properties": {
"numCandidatesGenerated": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Total candidates to generate before diversity selection (default ``100000``, range ``1``\u2013``100000``).",
"title": "Numcandidatesgenerated"
},
"numCandidatesSelected": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Top diverse candidates to return after ranking (default ``20``, range ``1``\u2013``100``).",
"title": "Numcandidatesselected"
}
},
"title": "OptimizationRunSettings",
"type": "object"
}
Fields:
-
num_candidates_generated(int | None) -
num_candidates_selected(int | None)
Bases: Criterion
A per-run optimization goal: a success criterion plus how much it matters.
A Criterion states what good looks like.
weight states how much that goal counts relative to the other objectives on the
same run, and belongs to the run rather than to the Target. A Target carries no
priority of its own, so the same targets can be reweighted from one run to the next
to see how the trade-off moves the candidates.
A plain Criterion is accepted anywhere a DesignObjective is expected and
takes the default weight.
Example
Show JSON schema:
{
"$defs": {
"ComparisonOperator": {
"description": "How a measured value is compared against a target value.\n\nAttributes\n----------\nEQ : str\n Equal to the target value.\nGT : str\n Strictly greater than the target value.\nGTE : str\n Greater than or equal to the target value.\nLT : str\n Strictly less than the target value.\nLTE : str\n Less than or equal to the target value.\nBETWEEN : str\n Within an inclusive range; pairs with a [`NumericRange`][albert.resources.targets.NumericRange] value.\nIN_SET : str\n Among a set of allowed values; pairs with a list value.",
"enum": [
"eq",
"gt",
"gte",
"lt",
"lte",
"between",
"in-set"
],
"title": "ComparisonOperator",
"type": "string"
},
"NumericRange": {
"description": "An inclusive numeric range, used with the ``between`` operator.",
"properties": {
"min": {
"description": "The lower bound of the range.",
"title": "Min",
"type": "number"
},
"max": {
"description": "The upper bound of the range.",
"title": "Max",
"type": "number"
}
},
"required": [
"min",
"max"
],
"title": "NumericRange",
"type": "object"
}
},
"description": "A per-run optimization goal: a success criterion plus how much it matters.\n\nA [`Criterion`][albert.resources.targets.Criterion] states what good looks like.\n``weight`` states how much that goal counts relative to the other objectives on the\nsame run, and belongs to the run rather than to the Target. A Target carries no\npriority of its own, so the same targets can be reweighted from one run to the next\nto see how the trade-off moves the candidates.\n\nA plain ``Criterion`` is accepted anywhere a ``DesignObjective`` is expected and\ntakes the default weight.\n\n!!! example\n ```python\n from albert.resources.design import DesignObjective\n\n # a hard specification that should not be traded away\n DesignObjective(operator=\"gte\", value=95, weight=3.0)\n\n # the same goal at the default weight\n DesignObjective(operator=\"gte\", value=95)\n ```",
"properties": {
"operator": {
"$ref": "#/$defs/ComparisonOperator",
"description": "How the measured value is compared against ``value``."
},
"value": {
"anyOf": [
{
"$ref": "#/$defs/NumericRange"
},
{
"type": "string"
},
{
"type": "number"
},
{
"items": {},
"type": "array"
}
],
"description": "The value being compared against. Use a [`NumericRange`][albert.resources.targets.NumericRange] with the ``between`` operator, a list with the ``in-set`` operator, or a single number/string for the scalar operators.",
"title": "Value"
},
"weight": {
"default": 1.0,
"description": "How much this objective counts relative to the others on the same run.\n\nCandidate scores are combined as a product of each objective's score raised to its\nweight, so a weight above ``1.0`` makes the objective harder to trade away and a\nweight below ``1.0`` makes it easier. Must be positive; to ignore an objective,\nleave it out.\n\nAlways a float, never ``None``: an unweighted objective is ``1.0``, which weighs it\nequally against the others. Omitting the field, or passing an explicit ``None``,\nboth give ``1.0``.",
"exclusiveMinimum": 0,
"title": "Weight",
"type": "number"
}
},
"required": [
"operator",
"value"
],
"title": "DesignObjective",
"type": "object"
}
Fields:
-
operator(ComparisonOperator) -
value(NumericRange | str | float | list) -
weight(float)
Validators:
-
_accept_plain_criterion -
_null_weight_is_unweighted→weight
weight: float = 1.0
How much this objective counts relative to the others on the same run.
Candidate scores are combined as a product of each objective's score raised to its
weight, so a weight above 1.0 makes the objective harder to trade away and a
weight below 1.0 makes it easier. Must be positive; to ignore an objective,
leave it out.
Always a float, never None: an unweighted objective is 1.0, which weighs it
equally against the others. Omitting the field, or passing an explicit None,
both give 1.0.
Bases: BaseAlbertModel
Request body for a model-guided optimization design run.
Show JSON schema:
{
"$defs": {
"ChatSessionRef": {
"description": "A chat session to notify when an asynchronous job finishes.\n\nBoth identifiers are required. They are issued by the chat platform and\nare normally supplied automatically by the agent runtime; a script calling the\nSDK directly has no reason to construct one.",
"properties": {
"sourceSessionId": {
"description": "The originating frontend session identifier.",
"format": "uuid",
"title": "Sourcesessionid",
"type": "string"
},
"chatSessionId": {
"description": "The chat session identifier (``SES\u2026``) that receives the completion message.",
"title": "Chatsessionid",
"type": "string"
}
},
"required": [
"sourceSessionId",
"chatSessionId"
],
"title": "ChatSessionRef",
"type": "object"
},
"ComparisonOperator": {
"description": "How a measured value is compared against a target value.\n\nAttributes\n----------\nEQ : str\n Equal to the target value.\nGT : str\n Strictly greater than the target value.\nGTE : str\n Greater than or equal to the target value.\nLT : str\n Strictly less than the target value.\nLTE : str\n Less than or equal to the target value.\nBETWEEN : str\n Within an inclusive range; pairs with a [`NumericRange`][albert.resources.targets.NumericRange] value.\nIN_SET : str\n Among a set of allowed values; pairs with a list value.",
"enum": [
"eq",
"gt",
"gte",
"lt",
"lte",
"between",
"in-set"
],
"title": "ComparisonOperator",
"type": "string"
},
"DesignObjective": {
"description": "A per-run optimization goal: a success criterion plus how much it matters.\n\nA [`Criterion`][albert.resources.targets.Criterion] states what good looks like.\n``weight`` states how much that goal counts relative to the other objectives on the\nsame run, and belongs to the run rather than to the Target. A Target carries no\npriority of its own, so the same targets can be reweighted from one run to the next\nto see how the trade-off moves the candidates.\n\nA plain ``Criterion`` is accepted anywhere a ``DesignObjective`` is expected and\ntakes the default weight.\n\n!!! example\n ```python\n from albert.resources.design import DesignObjective\n\n # a hard specification that should not be traded away\n DesignObjective(operator=\"gte\", value=95, weight=3.0)\n\n # the same goal at the default weight\n DesignObjective(operator=\"gte\", value=95)\n ```",
"properties": {
"operator": {
"$ref": "#/$defs/ComparisonOperator",
"description": "How the measured value is compared against ``value``."
},
"value": {
"anyOf": [
{
"$ref": "#/$defs/NumericRange"
},
{
"type": "string"
},
{
"type": "number"
},
{
"items": {},
"type": "array"
}
],
"description": "The value being compared against. Use a [`NumericRange`][albert.resources.targets.NumericRange] with the ``between`` operator, a list with the ``in-set`` operator, or a single number/string for the scalar operators.",
"title": "Value"
},
"weight": {
"default": 1.0,
"description": "How much this objective counts relative to the others on the same run.\n\nCandidate scores are combined as a product of each objective's score raised to its\nweight, so a weight above ``1.0`` makes the objective harder to trade away and a\nweight below ``1.0`` makes it easier. Must be positive; to ignore an objective,\nleave it out.\n\nAlways a float, never ``None``: an unweighted objective is ``1.0``, which weighs it\nequally against the others. Omitting the field, or passing an explicit ``None``,\nboth give ``1.0``.",
"exclusiveMinimum": 0,
"title": "Weight",
"type": "number"
}
},
"required": [
"operator",
"value"
],
"title": "DesignObjective",
"type": "object"
},
"NumericRange": {
"description": "An inclusive numeric range, used with the ``between`` operator.",
"properties": {
"min": {
"description": "The lower bound of the range.",
"title": "Min",
"type": "number"
},
"max": {
"description": "The upper bound of the range.",
"title": "Max",
"type": "number"
}
},
"required": [
"min",
"max"
],
"title": "NumericRange",
"type": "object"
},
"OptimizationRunSettings": {
"description": "Settings for a model-guided optimization design run.\n\nAll fields are optional; omit a field (or pass ``None``) to use the platform\ndefault for that knob. Values outside the allowed ranges are rejected before\nthe run is submitted.\n\nNotes\n-----\nThese two settings work together: candidate generation produces up to\n``num_candidates_generated`` candidates, then the top ``num_candidates_selected``\ndiverse formulations are kept as the result batch.",
"properties": {
"numCandidatesGenerated": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Total candidates to generate before diversity selection (default ``100000``, range ``1``\u2013``100000``).",
"title": "Numcandidatesgenerated"
},
"numCandidatesSelected": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Top diverse candidates to return after ranking (default ``20``, range ``1``\u2013``100``).",
"title": "Numcandidatesselected"
}
},
"title": "OptimizationRunSettings",
"type": "object"
}
},
"description": "Request body for a model-guided optimization design run.",
"properties": {
"method": {
"const": "generate",
"default": "generate",
"description": "Design-run kind; fixed to ``generate`` for optimization runs.",
"title": "Method",
"type": "string"
},
"smartDatasetId": {
"description": "Smart dataset whose experiment history anchors the run.",
"title": "Smartdatasetid",
"type": "string"
},
"name": {
"anyOf": [
{
"maxLength": 255,
"minLength": 1,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Display name for the resulting insight; a name is generated when omitted.",
"title": "Name"
},
"objectives": {
"anyOf": [
{
"additionalProperties": {
"$ref": "#/$defs/DesignObjective"
},
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Per-target objectives, each with its weight; omitted to optimize every scoped target.",
"title": "Objectives"
},
"settings": {
"anyOf": [
{
"$ref": "#/$defs/OptimizationRunSettings"
},
{
"type": "null"
}
],
"default": null,
"description": "Settings for a model-guided optimization design run."
},
"session": {
"anyOf": [
{
"$ref": "#/$defs/ChatSessionRef"
},
{
"type": "null"
}
],
"default": null,
"description": "Chat session to notify when the run completes; create-only."
}
},
"required": [
"smartDatasetId"
],
"title": "OptimizationDesignRunRequest",
"type": "object"
}
Fields:
-
method(Literal[GENERATE]) -
smart_dataset_id(SmartDatasetId) -
name(str | None) -
objectives(dict[TargetId, DesignObjective] | None) -
settings(OptimizationRunSettings | None) -
session(ChatSessionRef | None)
method: Literal[GENERATE] = DesignMethod.GENERATE
Design-run kind; fixed to generate for optimization runs.
smart_dataset_id: SmartDatasetId
Smart dataset whose experiment history anchors the run.
name: str | None = None
Display name for the resulting insight; a name is generated when omitted.
objectives: dict[TargetId, DesignObjective] | None = None
Per-target objectives, each with its weight; omitted to optimize every scoped target.
settings: OptimizationRunSettings | None = None
Settings for a model-guided optimization design run.
session: ChatSessionRef | None = None
Chat session to notify when the run completes; create-only.
Bases: BaseAlbertModel
Settings for a space-filling DOE design run.
All fields are optional; omit a field (or pass None) to use the platform
default for that knob. Values outside the allowed ranges are rejected before
the run is submitted.
Notes
These two settings work together: up to num_candidates_generated candidates
are sampled from the design space, then a space-filling subset of size
num_candidates_selected is returned.
Show JSON schema:
{
"description": "Settings for a space-filling DOE design run.\n\nAll fields are optional; omit a field (or pass ``None``) to use the platform\ndefault for that knob. Values outside the allowed ranges are rejected before\nthe run is submitted.\n\nNotes\n-----\nThese two settings work together: up to ``num_candidates_generated`` candidates\nare sampled from the design space, then a space-filling subset of size\n``num_candidates_selected`` is returned.",
"properties": {
"numCandidatesGenerated": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Maximum candidates to sample before downsampling (default ``10000``, range ``1``\u2013unbounded).",
"title": "Numcandidatesgenerated"
},
"numCandidatesSelected": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Size of the space-filling subset returned (default ``20``, range ``1``\u2013``100``).",
"title": "Numcandidatesselected"
}
},
"title": "DOERunSettings",
"type": "object"
}
Fields:
-
num_candidates_generated(int | None) -
num_candidates_selected(int | None)
Bases: BaseAlbertModel
Request body for a space-filling DOE design run.
Show JSON schema:
{
"$defs": {
"ChatSessionRef": {
"description": "A chat session to notify when an asynchronous job finishes.\n\nBoth identifiers are required. They are issued by the chat platform and\nare normally supplied automatically by the agent runtime; a script calling the\nSDK directly has no reason to construct one.",
"properties": {
"sourceSessionId": {
"description": "The originating frontend session identifier.",
"format": "uuid",
"title": "Sourcesessionid",
"type": "string"
},
"chatSessionId": {
"description": "The chat session identifier (``SES\u2026``) that receives the completion message.",
"title": "Chatsessionid",
"type": "string"
}
},
"required": [
"sourceSessionId",
"chatSessionId"
],
"title": "ChatSessionRef",
"type": "object"
},
"DOERunSettings": {
"description": "Settings for a space-filling DOE design run.\n\nAll fields are optional; omit a field (or pass ``None``) to use the platform\ndefault for that knob. Values outside the allowed ranges are rejected before\nthe run is submitted.\n\nNotes\n-----\nThese two settings work together: up to ``num_candidates_generated`` candidates\nare sampled from the design space, then a space-filling subset of size\n``num_candidates_selected`` is returned.",
"properties": {
"numCandidatesGenerated": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Maximum candidates to sample before downsampling (default ``10000``, range ``1``\u2013unbounded).",
"title": "Numcandidatesgenerated"
},
"numCandidatesSelected": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Size of the space-filling subset returned (default ``20``, range ``1``\u2013``100``).",
"title": "Numcandidatesselected"
}
},
"title": "DOERunSettings",
"type": "object"
}
},
"description": "Request body for a space-filling DOE design run.",
"properties": {
"method": {
"const": "space_filling",
"default": "space_filling",
"description": "Design-run kind; fixed to ``space_filling`` for DOE runs.",
"title": "Method",
"type": "string"
},
"smartDatasetId": {
"description": "Smart dataset whose experiment history anchors the run.",
"title": "Smartdatasetid",
"type": "string"
},
"name": {
"anyOf": [
{
"maxLength": 255,
"minLength": 1,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Display name for the resulting insight; a name is generated when omitted.",
"title": "Name"
},
"anchorTargets": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Target ids that narrow which existing rows count as historical anchors.",
"title": "Anchortargets"
},
"settings": {
"anyOf": [
{
"$ref": "#/$defs/DOERunSettings"
},
{
"type": "null"
}
],
"default": null,
"description": "Settings for a space-filling DOE design run."
},
"session": {
"anyOf": [
{
"$ref": "#/$defs/ChatSessionRef"
},
{
"type": "null"
}
],
"default": null,
"description": "Chat session to notify when the run completes; create-only."
}
},
"required": [
"smartDatasetId"
],
"title": "DOEDesignRunRequest",
"type": "object"
}
Fields:
-
method(Literal[SPACE_FILLING]) -
smart_dataset_id(SmartDatasetId) -
name(str | None) -
anchor_targets(list[TargetId] | None) -
settings(DOERunSettings | None) -
session(ChatSessionRef | None)
method: Literal[SPACE_FILLING] = DesignMethod.SPACE_FILLING
Design-run kind; fixed to space_filling for DOE runs.
smart_dataset_id: SmartDatasetId
Smart dataset whose experiment history anchors the run.
name: str | None = None
Display name for the resulting insight; a name is generated when omitted.
Target ids that narrow which existing rows count as historical anchors.
session: ChatSessionRef | None = None
Chat session to notify when the run completes; create-only.