nirs4all.pipeline.engine module

Execution-engine selector for the nirs4all core (V1 native cutover posture).

Seam for the nirs4all-core → native migration. The default strict/product profile is native. The general nirs4all.run() API additionally performs declaration-only capability selection when no selector is supplied: portable requests use native, other requests use DAG-ML. It never retries execution on another engine. The in-process legacy orchestrator (PipelineRunner) remains available as an explicit compatibility path via the public engine="legacy" selector only. The explicit engine="native" lane is the fail-closed Archive V2/N4MM producer for the portable Methods subset; it never falls back to PipelineRunner.

The side-by-side comparison mode ("dual") is intentionally limited to the strict nirs4all.run() oracle subset; other public operations remain unavailable.

Selection precedence: explicit argument > $N4A_ENGINE env var > DEFAULT_ENGINE (native). Ambient legacy/dual selection is rejected: pass engine="legacy" explicitly for compatibility runs. See dag-ml/docs/migration-nirs4all/.

Product-owned internal boundaries resolve with execution_profile="strict". That profile is deliberately not ambient-configurable: it rejects both direct and environment-selected legacy execution, the dual legacy oracle, and opt-in legacy fallback. The default "rollback-capable" profile keeps the frozen public Python run contract and explicit compatibility lane available until the R4 removal decision.

exception nirs4all.pipeline.engine.ExecutionProfileError(code: str, message: str)

Bases: ValueError

A fail-closed execution-profile preflight rejected the requested path.

exception nirs4all.pipeline.engine.LegacyEngineUsageWarning(*, engine: Literal['legacy', 'dag-ml', 'native', 'dual'], operation: str)

Bases: UserWarning

Stable structured warning for an explicit legacy-bearing API request.

nirs4all.pipeline.engine.get_legacy_engine_usage_counts() → dict[str, int]

Return a data-free snapshot of the opt-in process-local support counter.

nirs4all.pipeline.engine.legacy_fallback_metrics() → dict[str, int]

Return the frozen fallback telemetry shape for compatibility checks.

V1 has no implicit fallback path, so these counters deliberately remain at zero. Keeping the published snapshot API lets migration preflights prove that a refusal did not silently execute a legacy retry.

nirs4all.pipeline.engine.require_legacy_engine(operation: str, engine: str | None = None) → Literal['legacy', 'dag-ml', 'native', 'dual']

Resolve engine and require the explicit compatibility lane.

This helper preserves the published transition API without weakening the V1 native default or introducing any implicit fallback.