Skip to content

Design Candidates (🧪Beta)

albert.resources.design_candidates

Attributes:

Name Type Description
CandidateInput

One sampled design variable: an ingredient amount or a parameter value. A kind this

CandidateInput

CandidateInput = Annotated[
    Annotated[
        IngredientAmountInput | ParameterInput,
        Field(discriminator="type"),
    ]
    | UnknownDescriptor,
    Field(union_mode="left_to_right"),
]

One sampled design variable: an ingredient amount or a parameter value. A kind this version does not know yet parses to UnknownDescriptor instead of failing the read.

PredictionDataType

Bases: StrEnum

The kind of prediction a model made for a target.

Attributes:

Name Type Description
NUMERIC
CATEGORICAL

NUMERIC

NUMERIC = 'numeric'

CATEGORICAL

CATEGORICAL = 'categorical'

IngredientAmountInput

Bases: IngredientAmountOperand

The sampled amount of one ingredient. Fields this version does not model are kept.

Show JSON schema:
{
  "additionalProperties": true,
  "description": "The sampled amount of one ingredient. Fields this version does not model are kept.",
  "properties": {
    "type": {
      "const": "ingredientAmount",
      "default": "ingredientAmount",
      "description": "Descriptor kind; fixed to ``ingredientAmount``.",
      "title": "Type",
      "type": "string"
    },
    "ingredient": {
      "description": "The inventory ID (format ``INV...``) of the ingredient.",
      "title": "Ingredient",
      "type": "string"
    },
    "value": {
      "description": "The sampled amount.",
      "title": "Value",
      "type": "number"
    }
  },
  "required": [
    "ingredient",
    "value"
  ],
  "title": "IngredientAmountInput",
  "type": "object"
}

Config:

  • extra: allow

Fields:

model_config

model_config = ConfigDict(extra='allow')

value

value: float

The sampled amount.

ParameterInput

Bases: ParameterOperand

The sampled value of one parameter. Fields this version does not model are kept.

Show JSON schema:
{
  "$defs": {
    "ParameterRef": {
      "description": "The structured identity of a parameter: where it lives, and in what unit.",
      "properties": {
        "parameterId": {
          "description": "The parameter (format ``PRM...``).",
          "title": "Parameterid",
          "type": "string"
        },
        "dataTemplateId": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "The data template (format ``DAT...``) the parameter belongs to. Exactly one of\n``data_template_id`` / ``parameter_group_id`` is set.",
          "title": "Datatemplateid"
        },
        "parameterGroupId": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "The parameter group (format ``PRG...``) the parameter belongs to. Exactly one of\n``data_template_id`` / ``parameter_group_id`` is set.",
          "title": "Parametergroupid"
        },
        "unitId": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "The unit (format ``UNI...``) the parameter is expressed in; ``None`` when the\nparameter is unit-less.",
          "title": "Unitid"
        }
      },
      "required": [
        "parameterId"
      ],
      "title": "ParameterRef",
      "type": "object"
    }
  },
  "additionalProperties": true,
  "description": "The sampled value of one parameter. Fields this version does not model are kept.",
  "properties": {
    "type": {
      "const": "parameter",
      "default": "parameter",
      "description": "Descriptor kind; fixed to ``parameter``.",
      "title": "Type",
      "type": "string"
    },
    "parameter": {
      "description": "The composite parameter key, ``{DAT|PRG}#PRM[#UNI]``.",
      "title": "Parameter",
      "type": "string"
    },
    "ref": {
      "$ref": "#/$defs/ParameterRef",
      "description": "The structured parts of the parameter key."
    },
    "value": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string"
        }
      ],
      "description": "The sampled value.",
      "title": "Value"
    }
  },
  "required": [
    "parameter",
    "ref",
    "value"
  ],
  "title": "ParameterInput",
  "type": "object"
}

Config:

  • extra: allow

Fields:

model_config

model_config = ConfigDict(extra='allow')

ref

The structured parts of the parameter key.

value

value: float | str

The sampled value.

Quantiles

Bases: BaseAlbertModel

The full predicted distribution of a numeric prediction.

Show JSON schema:
{
  "description": "The full predicted distribution of a numeric prediction.",
  "properties": {
    "levels": {
      "description": "The quantile levels.",
      "items": {
        "type": "number"
      },
      "title": "Levels",
      "type": "array"
    },
    "values": {
      "description": "The predicted value at each level.",
      "items": {
        "type": "number"
      },
      "title": "Values",
      "type": "array"
    }
  },
  "required": [
    "levels",
    "values"
  ],
  "title": "Quantiles",
  "type": "object"
}

Fields:

levels

levels: list[float]

The quantile levels.

values

values: list[float]

The predicted value at each level.

Prediction

Bases: BaseAlbertModel

A model's prediction for one target.

Show JSON schema:
{
  "$defs": {
    "PredictionDataType": {
      "description": "The kind of prediction a model made for a target.",
      "enum": [
        "numeric",
        "categorical"
      ],
      "title": "PredictionDataType",
      "type": "string"
    },
    "Quantiles": {
      "description": "The full predicted distribution of a numeric prediction.",
      "properties": {
        "levels": {
          "description": "The quantile levels.",
          "items": {
            "type": "number"
          },
          "title": "Levels",
          "type": "array"
        },
        "values": {
          "description": "The predicted value at each level.",
          "items": {
            "type": "number"
          },
          "title": "Values",
          "type": "array"
        }
      },
      "required": [
        "levels",
        "values"
      ],
      "title": "Quantiles",
      "type": "object"
    }
  },
  "description": "A model's prediction for one target.",
  "properties": {
    "value": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string"
        }
      ],
      "description": "The predicted value.",
      "title": "Value"
    },
    "uncertainty": {
      "description": "The uncertainty of the prediction.",
      "title": "Uncertainty",
      "type": "number"
    },
    "dataType": {
      "$ref": "#/$defs/PredictionDataType",
      "description": "Whether the prediction is ``numeric`` or ``categorical``."
    },
    "quantiles": {
      "anyOf": [
        {
          "$ref": "#/$defs/Quantiles"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The predicted distribution. Numeric predictions only."
    }
  },
  "required": [
    "value",
    "uncertainty",
    "dataType"
  ],
  "title": "Prediction",
  "type": "object"
}

Fields:

value

value: float | str

The predicted value.

uncertainty

uncertainty: float

The uncertainty of the prediction.

data_type

data_type: PredictionDataType

Whether the prediction is numeric or categorical.

quantiles

quantiles: Quantiles | None = None

The predicted distribution. Numeric predictions only.

Acquisition

Bases: BaseAlbertModel

How well a candidate scored against the run's objectives.

Show JSON schema:
{
  "description": "How well a candidate scored against the run's objectives.",
  "properties": {
    "score": {
      "description": "The overall score.",
      "title": "Score",
      "type": "number"
    },
    "perObjective": {
      "anyOf": [
        {
          "additionalProperties": {
            "type": "number"
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Raw, unweighted score per objective, keyed by target ID.",
      "title": "Perobjective"
    }
  },
  "required": [
    "score"
  ],
  "title": "Acquisition",
  "type": "object"
}

Fields:

score

score: float

The overall score.

per_objective

per_objective: dict[str, float] | None = None

Raw, unweighted score per objective, keyed by target ID.

DesignCandidate

Bases: BaseResource

One candidate formulation of a candidate set. Candidates are read-only.

Show JSON schema:
{
  "$defs": {
    "Acquisition": {
      "description": "How well a candidate scored against the run's objectives.",
      "properties": {
        "score": {
          "description": "The overall score.",
          "title": "Score",
          "type": "number"
        },
        "perObjective": {
          "anyOf": [
            {
              "additionalProperties": {
                "type": "number"
              },
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Raw, unweighted score per objective, keyed by target ID.",
          "title": "Perobjective"
        }
      },
      "required": [
        "score"
      ],
      "title": "Acquisition",
      "type": "object"
    },
    "AuditFields": {
      "description": "The audit fields for a resource",
      "properties": {
        "by": {
          "default": null,
          "title": "By",
          "type": "string"
        },
        "byName": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Byname"
        },
        "at": {
          "anyOf": [
            {
              "format": "date-time",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "At"
        }
      },
      "title": "AuditFields",
      "type": "object"
    },
    "IngredientAmountInput": {
      "additionalProperties": true,
      "description": "The sampled amount of one ingredient. Fields this version does not model are kept.",
      "properties": {
        "type": {
          "const": "ingredientAmount",
          "default": "ingredientAmount",
          "description": "Descriptor kind; fixed to ``ingredientAmount``.",
          "title": "Type",
          "type": "string"
        },
        "ingredient": {
          "description": "The inventory ID (format ``INV...``) of the ingredient.",
          "title": "Ingredient",
          "type": "string"
        },
        "value": {
          "description": "The sampled amount.",
          "title": "Value",
          "type": "number"
        }
      },
      "required": [
        "ingredient",
        "value"
      ],
      "title": "IngredientAmountInput",
      "type": "object"
    },
    "ParameterInput": {
      "additionalProperties": true,
      "description": "The sampled value of one parameter. Fields this version does not model are kept.",
      "properties": {
        "type": {
          "const": "parameter",
          "default": "parameter",
          "description": "Descriptor kind; fixed to ``parameter``.",
          "title": "Type",
          "type": "string"
        },
        "parameter": {
          "description": "The composite parameter key, ``{DAT|PRG}#PRM[#UNI]``.",
          "title": "Parameter",
          "type": "string"
        },
        "ref": {
          "$ref": "#/$defs/ParameterRef",
          "description": "The structured parts of the parameter key."
        },
        "value": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "string"
            }
          ],
          "description": "The sampled value.",
          "title": "Value"
        }
      },
      "required": [
        "parameter",
        "ref",
        "value"
      ],
      "title": "ParameterInput",
      "type": "object"
    },
    "ParameterRef": {
      "description": "The structured identity of a parameter: where it lives, and in what unit.",
      "properties": {
        "parameterId": {
          "description": "The parameter (format ``PRM...``).",
          "title": "Parameterid",
          "type": "string"
        },
        "dataTemplateId": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "The data template (format ``DAT...``) the parameter belongs to. Exactly one of\n``data_template_id`` / ``parameter_group_id`` is set.",
          "title": "Datatemplateid"
        },
        "parameterGroupId": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "The parameter group (format ``PRG...``) the parameter belongs to. Exactly one of\n``data_template_id`` / ``parameter_group_id`` is set.",
          "title": "Parametergroupid"
        },
        "unitId": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "The unit (format ``UNI...``) the parameter is expressed in; ``None`` when the\nparameter is unit-less.",
          "title": "Unitid"
        }
      },
      "required": [
        "parameterId"
      ],
      "title": "ParameterRef",
      "type": "object"
    },
    "Prediction": {
      "description": "A model's prediction for one target.",
      "properties": {
        "value": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "string"
            }
          ],
          "description": "The predicted value.",
          "title": "Value"
        },
        "uncertainty": {
          "description": "The uncertainty of the prediction.",
          "title": "Uncertainty",
          "type": "number"
        },
        "dataType": {
          "$ref": "#/$defs/PredictionDataType",
          "description": "Whether the prediction is ``numeric`` or ``categorical``."
        },
        "quantiles": {
          "anyOf": [
            {
              "$ref": "#/$defs/Quantiles"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "The predicted distribution. Numeric predictions only."
        }
      },
      "required": [
        "value",
        "uncertainty",
        "dataType"
      ],
      "title": "Prediction",
      "type": "object"
    },
    "PredictionDataType": {
      "description": "The kind of prediction a model made for a target.",
      "enum": [
        "numeric",
        "categorical"
      ],
      "title": "PredictionDataType",
      "type": "string"
    },
    "Quantiles": {
      "description": "The full predicted distribution of a numeric prediction.",
      "properties": {
        "levels": {
          "description": "The quantile levels.",
          "items": {
            "type": "number"
          },
          "title": "Levels",
          "type": "array"
        },
        "values": {
          "description": "The predicted value at each level.",
          "items": {
            "type": "number"
          },
          "title": "Values",
          "type": "array"
        }
      },
      "required": [
        "levels",
        "values"
      ],
      "title": "Quantiles",
      "type": "object"
    },
    "Status": {
      "description": "The status of a resource.\n\nAttributes\n----------\nACTIVE : str\n    The resource is fully operational and visible in normal operations.\nINACTIVE : str\n    The resource is hidden from normal operations and disabled from use.",
      "enum": [
        "active",
        "inactive"
      ],
      "title": "Status",
      "type": "string"
    },
    "UnknownDescriptor": {
      "additionalProperties": true,
      "description": "A descriptor or mask entry of a kind this SDK version does not know yet.\n\nOnly appears in records read from the service. An entry written by a newer service\nversion parses into this model instead of failing, and keeps every key it carried.\nRequests never accept it.",
      "properties": {
        "type": {
          "description": "The kind the service reported.",
          "title": "Type",
          "type": "string"
        }
      },
      "required": [
        "type"
      ],
      "title": "UnknownDescriptor",
      "type": "object"
    }
  },
  "description": "One candidate formulation of a candidate set. Candidates are read-only.",
  "properties": {
    "status": {
      "anyOf": [
        {
          "$ref": "#/$defs/Status"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The status of the resource, optional."
    },
    "created": {
      "anyOf": [
        {
          "$ref": "#/$defs/AuditFields"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Audit fields for the creation of the candidate."
    },
    "updated": {
      "anyOf": [
        {
          "$ref": "#/$defs/AuditFields"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Audit fields for the last update of the candidate."
    },
    "id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The unique identifier of the candidate (format ``DCN...``).",
      "title": "Id"
    },
    "schemaVersion": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The version of the candidate record layout.",
      "title": "Schemaversion"
    },
    "candidateSetId": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The candidate set (format ``DCS...``) the candidate belongs to.",
      "title": "Candidatesetid"
    },
    "parentId": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The project (format ``PRO...``) that controls access to the candidate.",
      "title": "Parentid"
    },
    "inputs": {
      "description": "Every sampled design variable, zero values included.",
      "items": {
        "anyOf": [
          {
            "discriminator": {
              "mapping": {
                "ingredientAmount": "#/$defs/IngredientAmountInput",
                "parameter": "#/$defs/ParameterInput"
              },
              "propertyName": "type"
            },
            "oneOf": [
              {
                "$ref": "#/$defs/IngredientAmountInput"
              },
              {
                "$ref": "#/$defs/ParameterInput"
              }
            ]
          },
          {
            "$ref": "#/$defs/UnknownDescriptor"
          }
        ]
      },
      "title": "Inputs",
      "type": "array"
    },
    "predictions": {
      "anyOf": [
        {
          "additionalProperties": {
            "$ref": "#/$defs/Prediction"
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Predictions keyed by target ID. Absent on space-filling candidates.",
      "title": "Predictions"
    },
    "acquisition": {
      "anyOf": [
        {
          "$ref": "#/$defs/Acquisition"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The candidate's score. Absent when nothing scored it."
    },
    "rank": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Position within the set by descending acquisition score, starting at 1.\n\nOnly returned when listing candidates, and only for scored sets; ``None`` from a\nsingle-candidate read.",
      "title": "Rank"
    },
    "version": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Version counter of the record.",
      "title": "Version"
    }
  },
  "title": "DesignCandidate",
  "type": "object"
}

Fields:

id

id: DesignCandidateId | None = None

The unique identifier of the candidate (format DCN...).

schema_version

schema_version: int | None = None

The version of the candidate record layout.

candidate_set_id

candidate_set_id: DesignCandidateSetId | None = None

The candidate set (format DCS...) the candidate belongs to.

parent_id

parent_id: ProjectId | None = None

The project (format PRO...) that controls access to the candidate.

inputs

Every sampled design variable, zero values included.

predictions

predictions: dict[TargetId, Prediction] | None = None

Predictions keyed by target ID. Absent on space-filling candidates.

acquisition

acquisition: Acquisition | None = None

The candidate's score. Absent when nothing scored it.

rank

rank: int | None = None

Position within the set by descending acquisition score, starting at 1.

Only returned when listing candidates, and only for scored sets; None from a single-candidate read.

version

version: int | None = None

Version counter of the record.

created

created: AuditFields | None = None

Audit fields for the creation of the candidate.

updated

updated: AuditFields | None = None

Audit fields for the last update of the candidate.