sift_py.yaml.rule

CLASS	DESCRIPTION
NamedExpressionYamlSpec	A named expression. This class is the formal definition of what a named expression
RuleModuleYamlSpec	The formal definition of what a rule module looks like in YAML.
RuleYamlSpec	The formal definition of what a single rule looks like in YAML.

FUNCTION	DESCRIPTION
load_named_expression_modules	Takes in a list of paths to YAML files which contains named expressions and processes them into a dict.
load_rule_modules	Takes in a list of paths which may either be directories or files containing rule module YAML files,

NamedExpressionYamlSpec

Bases: TypedDict

A named expression. This class is the formal definition of what a named expression should look like in YAML. The value of name may contain a mix of channel references and channel identifiers.

For a formal definition of channel references and channel identifiers see the following: sift_py.ingestion.config.yaml.spec.RuleYamlSpec.

ATTRIBUTE	DESCRIPTION
name	TYPE: str

name instance-attribute

name: str

RuleModuleYamlSpec

Bases: TypedDict

The formal definition of what a rule module looks like in YAML.

rules: A list of rules that belong to the module.

ATTRIBUTE	DESCRIPTION
rules	TYPE: List[RuleYamlSpec]

rules instance-attribute

rules: List[RuleYamlSpec]

RuleYamlSpec

Bases: TypedDict

The formal definition of what a single rule looks like in YAML.

name: Name of the rule. rule_client_key: User-defined string-key that uniquely identifies this rule config. description: Description of rule. expression: Either an expression-string or a sift_py.ingestion.config.yaml.spec.NamedExpressionYamlSpec referencing a named expression. type: Determines the action to perform if a rule gets evaluated to true. assignee: If type is review, determines who to notify. Expects an email. tags: Tags to associate with the rule. channel_references: A list of channel references that maps to an actual channel. More below. contextual_channels: A list of channel configs that provide context but aren't directly used in the expression. sub_expressions: A list of sub-expressions which is a mapping of place-holders to sub-expressions. Only used if using named expressions. asset_names: A list of asset names that this rule should be applied to. ONLY VALID if defining rules outside of a telemetry config. tag_names: A list of tag names that this rule should be applied to. ONLY VALID if defining rules outside of a telemetry config.

Channel references: A channel reference is a string containing a numerical value prefixed with "$". Examples include "$1", "$2", "$11", and so on. The channel reference is mapped to an actual channel config. In YAML it would look something like this:

channel_references:
  - $1: *vehicle_state_channel
  - $2: *voltage_channel
contextual_channels:
  - name: log

Sub-expressions: A sub-expression is made up of two components: A reference and the actual sub-expression. The sub-expression reference is a string with a "$" prepended to another string comprised of characters in the following character set: [a-zA-Z0-9_]. This reference should be mapped to the actual sub-expression. For example, say you have kinematic equations in kinematics.yml, and the equation you're interested in using looks like the following:

kinetic_energy_gt:
  0.5 * $mass * $1 * $1 > $threshold

To properly use kinetic_energy_gt in your rule, it would look like the following:

rules:
  - name: kinetic_energy
    description: Tracks high energy output while in motion
    type: review
    assignee: bob@example.com
    expression:
      name: kinetic_energy_gt
    channel_references:
      - $1: *velocity_channel
    sub_expressions:
      - $mass: 10
      - $threshold: 470
    tags:
        - nostromo

ATTRIBUTE	DESCRIPTION
asset_names	TYPE: NotRequired[List[str]]
assignee	TYPE: NotRequired[str]
channel_references	TYPE: NotRequired[List[Dict[str, ChannelConfigYamlSpec]]]
contextual_channels	TYPE: NotRequired[List[str]]
description	TYPE: NotRequired[str]
expression	TYPE: Union[str, NamedExpressionYamlSpec]
name	TYPE: str
rule_client_key	TYPE: NotRequired[str]
sub_expressions	TYPE: NotRequired[List[Dict[str, str]]]
tag_names	TYPE: NotRequired[List[str]]
tags	TYPE: NotRequired[List[str]]
type	TYPE: Union[Literal['phase'], Literal['review']]

asset_names instance-attribute

asset_names: NotRequired[List[str]]

assignee instance-attribute

assignee: NotRequired[str]

channel_references instance-attribute

channel_references: NotRequired[
    List[Dict[str, ChannelConfigYamlSpec]]
]

contextual_channels instance-attribute

contextual_channels: NotRequired[List[str]]

description instance-attribute

description: NotRequired[str]

expression instance-attribute

expression: Union[str, NamedExpressionYamlSpec]

name instance-attribute

name: str

rule_client_key instance-attribute

rule_client_key: NotRequired[str]

sub_expressions instance-attribute

sub_expressions: NotRequired[List[Dict[str, str]]]

tag_names instance-attribute

tag_names: NotRequired[List[str]]

tags instance-attribute

tags: NotRequired[List[str]]

type instance-attribute

type: Union[Literal['phase'], Literal['review']]

load_named_expression_modules

load_named_expression_modules(
    paths: List[Path],
) -> Dict[str, str]

Takes in a list of paths to YAML files which contains named expressions and processes them into a dict. The key is the name of the expression and the value is the expression itself. For more information on named expression modules see sift_py/yaml/rule.py.

load_rule_modules

load_rule_modules(paths: List[Path]) -> List[RuleYamlSpec]

Takes in a list of paths which may either be directories or files containing rule module YAML files, and processes them into a list. For more information on rule modules see RulemoduleYamlSpec in sift_py/yaml/rule.py.