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. is_external: If this is an external rule. is_live: If set to True then this rule will be evaluated on live data, otherwise live rule evaluation will be disabled. This rule can still be used, however, in report generation.

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]
is_external	TYPE: NotRequired[bool]
is_live	TYPE: NotRequired[bool]
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]

is_external instance-attribute

is_external: NotRequired[bool]

is_live instance-attribute

is_live: NotRequired[bool]

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.