Skip to main content

validator

Validator for a parsed BackgroundDAG.

Validation is a separate pass after parsing so that errors are clearly attributed to missing registry entries or ordering violations rather than YAML syntax problems.

Two categories of check are performed:

Step-name checks (raise DuplicateStepNameError) Every step name must be unique within the DAG. Duplicate names would overwrite entries in the executor's results mapping and can cause ambiguous references.

Registry checks (raise StepNotFoundError) Every step's (task, version) pair must be present in the step registry. This catches typos in YAML task names and references to steps that haven't been implemented yet.

Reference-ordering checks (raise ReferenceOrderError) FromRef inputs must reference a step that appears earlier in the step list. Forward references are not allowed — the DAG is executed top-to-bottom and a step cannot depend on a result that hasn't been produced yet.

Output-field checks (raise OutputFieldNotFoundError) A FromRef/BackgroundRef names an attribute on the referenced step's result (ga_calculation.cache). The referenced step's registered Result class must actually expose it, otherwise the executor's getattr fails mid-run — after the expensive inference steps have already executed. Steps whose task registers no Result class cannot be checked and are skipped.

Known-provider checks (log warnings only) ContextRef inputs reference named context providers. If the provider name is not in the set of known providers, a warning is logged. This is a warning rather than an error because the set of providers is determined at runtime and may legitimately extend the built-in set.

Module​

Functions​

validate_background_dag​

def validate_background_dag(dag: BackgroundDAG) ‑> None:

Validate dag against the step registry and check reference ordering.

Iterates over every step in dag in declaration order, performing:

  1. A registry check — (step.task, step.version) must be present.
  2. An input-ref check — FromRef steps must already be declared; unknown ContextRef providers emit a warning.

Arguments

  • dag: A BackgroundDAG produced by parse_background_dag.

Raises

  • DuplicateStepNameError: If any step name appears more than once.
  • StepNotFoundError: If any step's (task, version) is not in the step registry.
  • ReferenceOrderError: If any FromRef references a step that has not yet been declared (forward reference).
  • OutputFieldNotFoundError: If any FromRef names an output field the referenced step's Result class does not expose.

validate_interactive_dag​

def validate_interactive_dag(dag: InteractiveDAG) ‑> None:

Validate an InteractiveDAG against the registry and reference rules.

Like validate_background_dag but additionally:

  • FromRef inputs (intra-phase) must reference an interactive step declared earlier — forward references are rejected.
  • BackgroundRef inputs (cross-phase) must reference a step that exists in the flow's background phase (dag.background_step_names).

Arguments

  • dag: An InteractiveDAG produced by parse_interactive_dag.

Raises

  • DuplicateStepNameError: If any interactive step name appears twice.
  • StepNotFoundError: If any step's (task, version) is not registered.
  • ReferenceOrderError: If any FromRef references a later interactive step (forward reference).
  • BackgroundStepNotFoundError: If any BackgroundRef references a step not declared in the background phase.
  • OutputFieldNotFoundError: If any FromRef/BackgroundRef names an output field the referenced step's Result class does not expose.

Classes​

BackgroundStepNotFoundError​

class BackgroundStepNotFoundError(*args, **kwargs):

Raised when an interactive BackgroundRef targets an unknown step.

Interactive steps may reference background step outputs (e.g. ga_inference.cache). The referenced step must be declared in the flow's worker.background phase; otherwise its results can never be resolved from the cache.

DuplicateStepNameError​

class DuplicateStepNameError(*args, **kwargs):

Raised when two or more steps share the same name.

Node names are used as keys in execution result mappings and for FromRef(step=...) lookups. Duplicate names are therefore ambiguous and must be rejected at validation time.

OutputFieldNotFoundError​

class OutputFieldNotFoundError(*args, **kwargs):

Raised when a ref names an output the referenced step's result lacks.

A ref such as ga_calculation.cache is resolvable only if the step's registered Result class exposes cache — as a pydantic field or a property. Otherwise the executor's getattr would raise part-way through the run, so the ref is rejected up front with the available fields listed.

ReferenceOrderError​

class ReferenceOrderError(*args, **kwargs):

Raised when a FromRef references a step declared later in the DAG.

The background DAG is executed in declaration order. A step cannot consume the output of a step that has not yet run.

StepNotFoundError​

class StepNotFoundError(*args, **kwargs):

Raised when a DAG step references a task that is not in the registry.

Includes the task name and version in the message so the user can identify which YAML entry needs correcting.