Skip to content

Design Operands (🧪Beta)

albert.resources.design_operands

Quantity descriptors shared by design resources.

A descriptor names a quantity inline (an ingredient amount, a label fraction, a parameter value, or a property aggregation), and is shared by design resources such as the feature masks of design model configs.

The descriptor models are strict, so what a caller sends (and any schema generated from it) names exactly the fields and kinds the service accepts. Records read back from the service parse through the lenient variants instead (QuantityOperandRead), which keep fields and kinds a newer service version adds.

Attributes:

Name Type Description
QuantityOperand

A quantity descriptor: an ingredient amount, a label fraction, a parameter, or a

QuantityOperandRead

A quantity descriptor as read from the service. A known kind parses to its descriptor

QuantityOperand

A quantity descriptor: an ingredient amount, a label fraction, a parameter, or a property aggregation.

QuantityOperandRead

QuantityOperandRead = Annotated[
    Annotated[
        _ReadIngredientAmountOperand
        | _ReadLabelFractionOperand
        | _ReadParameterOperand
        | _ReadPropertyAggregationOperand,
        Field(discriminator="type"),
    ]
    | UnknownDescriptor,
    Field(union_mode="left_to_right"),
]

A quantity descriptor as read from the service. A known kind parses to its descriptor model (an instance of IngredientAmountOperand, LabelFractionOperand, ParameterOperand or PropertyAggregationOperand) and keeps fields this version does not model; an unknown kind parses to UnknownDescriptor.

AggregationBasis

Bases: StrEnum

How an aggregation combines the member values of its scope.

Attributes:

Name Type Description
MEAN
SUM

MEAN

MEAN = 'mean'

SUM

SUM = 'sum'

TypedDesignModel

Bases: BaseAlbertModel

Base for type-discriminated models, keeping type when unset fields are dropped.

Requests are serialized with exclude_unset=True, which would drop a defaulted type discriminator, and the service cannot read an entry that does not say which kind it is. Re-adding it here covers an entry nested in an operation.

Show JSON schema:
{
  "additionalProperties": false,
  "description": "Base for ``type``-discriminated models, keeping ``type`` when unset fields are dropped.\n\nRequests are serialized with ``exclude_unset=True``, which would drop a defaulted\n``type`` discriminator, and the service cannot read an entry that does not say which\nkind it is. Re-adding it here covers an entry nested in an operation.",
  "properties": {},
  "title": "TypedDesignModel",
  "type": "object"
}

model_config

model_config = ConfigDict(
    extra="forbid",
    revalidate_instances="subclass-instances",
)

IngredientAmountOperand

Bases: TypedDesignModel

The amount of one ingredient in the formulation.

Show JSON schema:
{
  "additionalProperties": false,
  "description": "The amount of one ingredient in the formulation.",
  "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"
    }
  },
  "required": [
    "ingredient"
  ],
  "title": "IngredientAmountOperand",
  "type": "object"
}

Fields:

type

type: Literal['ingredientAmount'] = 'ingredientAmount'

Descriptor kind; fixed to ingredientAmount.

ingredient

ingredient: InventoryId

The inventory ID (format INV...) of the ingredient.

LabelFractionOperand

Bases: TypedDesignModel

The summed fraction of a label's member ingredients.

Show JSON schema:
{
  "additionalProperties": false,
  "description": "The summed fraction of a label's member ingredients.",
  "properties": {
    "type": {
      "const": "labelFraction",
      "default": "labelFraction",
      "description": "Descriptor kind; fixed to ``labelFraction``.",
      "title": "Type",
      "type": "string"
    },
    "label": {
      "description": "A platform tag (format ``TAG...``) or a local label key (``local:...``).",
      "title": "Label",
      "type": "string"
    }
  },
  "required": [
    "label"
  ],
  "title": "LabelFractionOperand",
  "type": "object"
}

Fields:

type

type: Literal['labelFraction'] = 'labelFraction'

Descriptor kind; fixed to labelFraction.

label

label: str

A platform tag (format TAG...) or a local label key (local:...).

ParameterOperand

Bases: TypedDesignModel

The value of one parameter, addressed by its composite key.

Show JSON schema:
{
  "additionalProperties": false,
  "description": "The value of one parameter, addressed by its composite key.",
  "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"
    }
  },
  "required": [
    "parameter"
  ],
  "title": "ParameterOperand",
  "type": "object"
}

Fields:

type

type: Literal['parameter'] = 'parameter'

Descriptor kind; fixed to parameter.

parameter

parameter: str

The composite parameter key, {DAT|PRG}#PRM[#UNI].

PropertyAggregationOperand

Bases: TypedDesignModel

An aggregation of one inventory property over a scope of ingredients.

Show JSON schema:
{
  "$defs": {
    "AggregationBasis": {
      "description": "How an aggregation combines the member values of its scope.",
      "enum": [
        "mean",
        "sum"
      ],
      "title": "AggregationBasis",
      "type": "string"
    }
  },
  "additionalProperties": false,
  "description": "An aggregation of one inventory property over a scope of ingredients.",
  "properties": {
    "type": {
      "const": "propertyAggregation",
      "default": "propertyAggregation",
      "description": "Descriptor kind; fixed to ``propertyAggregation``.",
      "title": "Type",
      "type": "string"
    },
    "basis": {
      "$ref": "#/$defs/AggregationBasis",
      "description": "How the member values combine: ``mean`` or ``sum``."
    },
    "property": {
      "description": "Name of the aggregated inventory property.",
      "title": "Property",
      "type": "string"
    },
    "label": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Restrict the aggregation to a label's members. Omit to scope to all ingredients.",
      "title": "Label"
    },
    "impute": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "How missing property values are handled: ``True`` fills the column mean, a number\nfills that constant, ``False`` fails on a sparse table. Omit to leave it unstated.",
      "title": "Impute"
    }
  },
  "required": [
    "basis",
    "property"
  ],
  "title": "PropertyAggregationOperand",
  "type": "object"
}

Fields:

type

type: Literal["propertyAggregation"] = "propertyAggregation"

Descriptor kind; fixed to propertyAggregation.

basis

How the member values combine: mean or sum.

property

property: str

Name of the aggregated inventory property.

label

label: str | None = None

Restrict the aggregation to a label's members. Omit to scope to all ingredients.

impute

impute: bool | float | None = None

How missing property values are handled: True fills the column mean, a number fills that constant, False fails on a sparse table. Omit to leave it unstated.

UnknownDescriptor

Bases: BaseAlbertModel

A descriptor or mask entry of a kind this SDK version does not know yet.

Only appears in records read from the service. An entry written by a newer service version parses into this model instead of failing, and keeps every key it carried. Requests never accept it.

Show JSON schema:
{
  "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"
}

Config:

  • extra: allow

Fields:

Validators:

  • _only_unknown_kinds → type

model_config

model_config = ConfigDict(extra='allow')

type

type: str

The kind the service reported.