nirs4all.pipeline.dagml.errors module

Failure types and fail-loud guards for the dag-ml host backend.

DagMlUnsupported is the catchable error every unsupported-or-failed dag-ml shape raises; DagMlUnavailable is the narrow error a dag-ml-backend PREFLIGHT raises when NEITHER execution mechanism is installed (no in-process PyO3 extension AND no dag-ml-cli binary). DagMlMigrationRequired names a semantic boundary that deliberately cannot use automatic legacy rollback. _cli_child_error extracts the real cause from a dag-ml-cli failure; _raise_run_failure decides propagate-vs-fallback for a non-zero subprocess run from the adapter’s structured error_kind (_run_failure_kind()); _reject_multi_model rejects a multi-model pipeline UP FRONT.

exception nirs4all.pipeline.dagml.errors.DagMlExportRefusal(operation: str, reason: str, *, mitigation: str)[source]

Bases: RuntimeError

A completed native run cannot satisfy a requested export capability.

This error deliberately is not a DagMlUnsupported: export occurs after training, beyond run()’s compatibility fallback boundary. Re-running the pipeline through the legacy engine is available only through the explicit compatibility="legacy-refit" export opt-in.

exception nirs4all.pipeline.dagml.errors.DagMlMigrationRequired[source]

Bases: RuntimeError

A legacy semantic needs an explicit migration and may not auto-fallback.

allow_legacy_fallback is intentionally limited to ordinary capability and availability boundaries. It must not make a native request appear successful by silently changing its execution contract. Callers must either migrate the pipeline or select engine="legacy" explicitly. This stays outside the fallback catch hierarchy on purpose.

exception nirs4all.pipeline.dagml.errors.DagMlPipelinePreflightRequired[source]

Bases: DagMlMigrationRequired

A generator cannot prove whether it selects a stateful pre-CV concat.

exception nirs4all.pipeline.dagml.errors.DagMlStatefulConcatTransformMigrationRequired[source]

Bases: DagMlMigrationRequired

Legacy pre-CV stateful concat_transform semantics need an explicit migration.

exception nirs4all.pipeline.dagml.errors.DagMlUnavailable[source]

Bases: RuntimeError

NEITHER dag-ml execution mechanism is installed, so the dag-ml backend cannot run at all.

Raised by the dag-ml-backend availability probes: the run-level PREFLIGHT (preflight_dagml_backend()) when BOTH mechanisms are missing (the in-process PyO3 extension dag_ml._dag_ml does not import/load AND the dag-ml-cli binary does not exist), and the in-process/subprocess router’s SUBPROCESS branch when in-process is not selected and dag-ml-cli is absent. Since the ADR-17 cutover made dag-ml the default engine + a hard dependency, run() catches THIS (alongside DagMlUnsupported / NotImplementedError) and falls back to the legacy engine WITH A WARNING — so a wheel install that is somehow missing the native backend degrades transparently instead of hard-failing.

Deliberately NARROW: it is raised only by those explicit availability probes, NEVER by wrapping a run in a blanket except ImportError/FileNotFoundError (which would swallow a genuine dag-ml bug). A real dag-ml runtime/operator error is NOT this — it propagates untouched.

NOT a subclass of DagMlUnsupported/NotImplementedError: “the backend is not installed” is a distinct condition from “this pipeline shape is unsupported”, and run() catches it explicitly.

exception nirs4all.pipeline.dagml.errors.DagMlUnsupported[source]

Bases: NotImplementedError

A pipeline shape (or a dag-ml-cli run of one) the dag-ml backend cannot execute.

A subclass of NotImplementedError so the cutover fallback (try dag-ml; except NotImplementedError → legacy) catches it: an unsupported-or-failed dag-ml shape must NEVER escape run_via_dagml as a bare RuntimeError/ValueError (which the fallback would not catch and would hard-fail in production). Raised both for shapes rejected UP FRONT (no splitter, multiple model nodes, …) and for a dag-ml-cli run that failed mid-execution because the SHAPE is unsupported — in either case the fallback redirects the pipeline to the legacy engine. A GENUINE operator bug (a model fit failure) is NOT this — it propagates as a real error (see _raise_run_failure()).