Recipe Nodes

To see examples on how to get and set values in your recipe, see the Access and Manipulation quick guide. The complete API references are shown below.

RecipeNode

RecipeNode(recipiece_uuid: str, recipe_cache: IngredientCache, parent=None, parent_slot=None, given_name=None)

Bases: Node

The core class that represents an ingredient node.

Attributes:

• ingredient_uuid (str) –

  The ingredient's UUID in the source pantry.

• ingredient_meta (Dict[str, Any]) –

  The ingredient metadata.

• isa (str) –

  A category (taxonomy) of the ingredient.

• version (str) –

  A version of the ingredient.

• ingredient_constraints (List[Dict]) –

  Constraints that are introduced by the ingredient recipiece.

• path (List[str]) –

  A path to the current ingredient with respect to the root node.

• visible_name (str) –

  A descriptive ingredient name.

• value_slots (List[str]) –

  A list of ingredient direct slots that are terminal nodes.

• config_slots (List[str]) –

  A list of ingredient direct slots that require further components to be assigned.

• slots (List[str]) –

  A list of ingredient direct slots.

• given_name (Optional[str]) –

  A unique name that is used to distinguish elements in the multi-ingredient list.

• execution_contexts (Dict[str, str]) –

  Metadata of the execution contexts that the recipe is compatible with.

Methods:

• assign_ingredients –

  Find and assign ingredients to slots that match a specific synonym.

• check_constraints –

  Check for potential conflicts within the provided recipe.

• duplicate –

  Create a copy of the ingredient node and its child components.

• fill_empty_recursively –

  Recursively find empty slots under the provided node and fill them in with preferred ingredients.

• iterate_matches –

  Find all matching nodes and their corresponding child slots based on the specific synonym.

• options –

  List available choices and display specifications of the provided slot.

• to_pickle –

  Create a pickle of the recipe and its ingredients and save to disk.

• to_sppr –

  Create a base64 stream from the recipe and its ingredients.

assign_ingredients

assign_ingredients(synonym: str, regex: Union[Optional[str], Dict[str, Optional[str]]] = None, choose_first_if_several: bool = False) -> List[Dict[str, str]]

Find and assign ingredients to slots that match a specific synonym.

This method searches for slots within the given node that match a particular synonym. It then goes over the matches and assigns a compatible ingredient, possibly using a regular expression.

Parameters:

• synonym (str) –

  The direct synonym name or regular expression to match the synonym.

• regex (Union[Optional[str], Dict[str, Optional[str]]], default: None ) –

  In case, you're assigning a single ingredient, you should provide a regular expression to match against ingredient names. If you're assigning an ingredient to the multi-component slot, you should provide a mapping with a name and a regular expression for each ingredient to be added.

• choose_first_if_several (bool, default: False ) –

  If True, the first returned ingredient is assigned in case multiple compatible options are available.

Returns:

• choices_made ( List[Dict[str, str]] ) –

  A summary of all ingrediends that were assigned.

Examples:

Assign an EfficientDet model.

>>> recipe.assign_ingredients(synonym="model", regex="eff.*")

Assign data augmentations that include a flip transformation.

>>> recipe.assign_ingredients(
...     synonym="data.augmentation.*"
...     regex="Flip",
...     choose_first_if_several=True,
... )

Assign multiple callbacks.

>>> recipe.assign_ingredients(
...     synonym="callbacks",
...     regex={"my_progress_bar": "^Progress Bar$", "my_checkpoint": "^Checkpointing$"}
... )

check_constraints

check_constraints(show: bool = True) -> Dict[str, Dict]

Check for potential conflicts within the provided recipe.

The choice of particular ingredients or their values can lead to conflicts within the recipe. However, those can be readily resolved by following the guidance provided in the constraint validation summary. To examine the sources of violations or simply display the constraints summary make sure the show flag is set to True.

Note: Constraint validation is applied to the entire recipe rather than individual components.

Parameters:

• show (bool, default: True ) –

  If True, the constraints summary is displayed.

Returns:

• value_violations ( Dict[str, Dict] ) –

  Violations of the specific slots that indicate conflicts among selected values.

duplicate

duplicate() -> RecipeNode

Create a copy of the ingredient node and its child components.

Returns:

• node_copy ( RecipeNode ) –

  A deep copy of the node.

fill_empty_recursively

fill_empty_recursively(req_map: Optional[Dict] = None, match_categories: bool = False, match_synonyms: bool = True) -> List[Dict[str, Union[str, list]]]

Recursively find empty slots under the provided node and fill them in with preferred ingredients.

If the mapping for preferred ingredients was not provided or the ingredient regex matched multiple choices, the first returned entry that is compatible with the slot is assigned. Additionally, the multi-ingredient slots are populated only if the corresponding entries are provided in the ingredients mapping.

Parameters:

• req_map (Optional[Dict], default: None ) –

  A mapping of the preferred ingredients to be chosen for specific slots. The keys correspond to slot matches (based on category or synonym regex) and values correspond to ingredient names.

  For single-ingredient slots the following format is used:

  regex_slot_synonym/category: regex_ingredient_name
  

  while for multi-ingredient slots:

  regex_slot_synonym/category: {regex_subcategory: regex_ingredient_name}.
  

• match_categories (bool, default: False ) –

  If True, the req_map keys are matched based on categories.

• match_synonyms (bool, default: True ) –

  If True, the req_map keys are matched based on synonyms (default).

Returns:

• choices_made ( List[Dict[str, Union[str, list]]] ) –

  A summary of all ingrediends that were filled in.

Examples:

Fill in data augmentations based on the slot synonym and ingredient name regex.

>>> data_generator.fill_empty_recursively(
...     req_map={"data.augmentation.*": "^Flip, Resize and Normalize$"},
... )

Fill in checkpointing and early termination callbacks.

>>> recipe.fill_empty_recursively(
...     req_map={"^callbacks$": {"termination": "stopping", "checkpoint": "checkpointing"}},
... )

iterate_matches

iterate_matches(key: str) -> List[Tuple[RecipeNode, str]]

Find all matching nodes and their corresponding child slots based on the specific synonym.

Parameters:

• key (str) –

  The direct synonym name or regular expression to match the synonym.

Returns:

• items ( List[Tuple[RecipeNode, str]] ) –

  A list of nodes and corresponding direct slots that match the provided synonym.

Examples:

Find and display all data augmentations.

>>> for node, direct_slot in recipe.iterate_matches("data.augmentation.*"):
...     print(node[direct_slot])

options

options(slot_name: str) -> SlotOptions

List available choices and display specifications of the provided slot.

Parameters:

• slot_name (str) –

  The direct synonym name or regular expression to match the synonym.

Returns:

• options ( SlotOptions ) –

  For specific types, a list of permissible values for the provided slot. For choice and multi-choice slot types, the list contains the scalar choices. For all ingredient-typed slots, it consists of objects containing the ingredient name, id and category.

Examples:

List the potential models and assign one of the candidates to the recipe.

>>> choices = recipe.options("model")
>>> print(choices)
>>> recipe["model"] = choices[0]

List the potential backbones, filter out by the regex and assign it to the recipe.

>>> choices = recipe.options("model.backbone")
>>> print(choices)
>>> filtered = choices.search("mobile")
>>> recipe["model.backbone"] = filtered[0]

to_pickle

to_pickle(path=Union[str, Path])

Create a pickle of the recipe and its ingredients and save to disk.

Besides the recipe itself, the serialization includes all necessary pantry items, which allows to work with recipes in a distributed manner. Serialization is also useful when there is a need to transfer a recipe through a text or binary channel or store it in a compact format.

Parameters:

• path –

  Location on disk to save the pickle .

Returns:

• path –

  Return the path where the recipe pickle was saved.

to_sppr

to_sppr(task: Optional[str] = None, include_soft_influencers: bool = True)

Create a base64 stream from the recipe and its ingredients. Besides the recipe itself, the serialization includes all necessary pantry items, which allows to work with recipes in a distributed manner. Serialization is also useful when there is a need to transfer a recipe through a text or binary channel or store it in a compact format.

Parameters:

• task (Optional[str], default: None ) –

  Only serialize fields required for this task.

• include_soft_influencers (bool, default: True ) –

  If True, includes non-significant fields when a task is specified. This is only applied when a task is provided.

Returns:

• serialized –

  A compressed and encoded recipe representation.