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: 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"
},
"Criterion": {
"description": "A target value constraint: an operator paired with a value to compare against.",
"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"
}
},
"required": [
"operator",
"value"
],
"title": "Criterion",
"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/Criterion"
},
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Per-target objectives; 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, Criterion] | 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.
Per-target objectives; 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.