nirs4all.pipeline.dagml.estimator module

sklearn-cloneable DAG-ML training estimator seam for nirs4all.

NIRSPipeline is a prediction-only wrapper around already-trained nirs4all bundles. DagMLPipelineEstimator is the separate W2-PY training estimator: it owns no compilation logic itself, but it can call native DAG-ML training and replay once the nirs4all→DAG-ML contract compiler is supplied.

class nirs4all.pipeline.dagml.estimator.DagMLFitIdentityFrame(n_samples: int, sample_ids: tuple[str, ...], groups: tuple[str | None, ...], metadata_rows: tuple[dict[str, Any], ...], explicit_sample_ids: bool, fingerprint: str)[source]

Bases: object

Normalized row-aligned identities for one estimator fit call.

explicit_sample_ids: bool
fingerprint: str
group_by_sample_int() → dict[int, str][source]

Return non-null groups keyed by sample position.

groups: tuple[str | None, ...]
metadata_by_sample_id() → dict[str, dict[str, Any]][source]

Return row metadata keyed by the normalized sample id.

metadata_by_sample_int() → dict[str, dict[int, Any]][source]

Return {column: {sample_position: value}} for envelope builders.

metadata_rows: tuple[dict[str, Any], ...]
n_samples: int
sample_ids: tuple[str, ...]
class nirs4all.pipeline.dagml.estimator.DagMLPipelineEstimator(pipeline: Any = None, *, task_type: str = 'auto', selection_output_id: str | None = None, package_id: str | None = None, dagml_module: str = 'dag_ml', native_client: Any = None, training_compiler: Any = None, prediction_compiler: Any = None, prediction_decoder: Any = None, prediction_identity_decoder: Any = None, probability_decoder: Any = None, require_explicit_sample_ids: bool = False)[source]

Bases: BaseEstimator

sklearn-compatible estimator backed by native DAG-ML training contracts.

The estimator is intentionally constructor-only and cloneable. It does not compile nirs4all syntax yet; callers must provide a training_compiler and, for prediction, a prediction_compiler plus explicit decoders. Missing pieces raise DagMLNativeCoverageError instead of falling back or fabricating predictions.

detach_native_training_result() → bool[source]

Release attached DAG-ML execution resources without losing portable state.

fit_native_pipeline is public and returns this estimator directly, so callers need a deterministic lifecycle operation independent of the higher-level NativeMethodsRunResult. DAG-ML’s TrainingResult.detach() preserves the signed outcome and portable predictor package used by later native replay/export.

Returns:

True only when this call performed the attached-to-detached transition. Repeated calls are harmless and return False.

execute_compiled_replay(replay: DagMLReplayExecution) → Any[source]

Execute one already-compiled native replay exactly once.

Compilation owns request, relation and identity attestation. This method only transports that exact contract to DAG-ML and guarantees the compiler’s cleanup hook executes on both success and failure. It is public so higher-level native operations can retain the same replay evidence for a later DAG-ML attachment rather than compiling a second, potentially distinct request.

export_native_archive(archive_path: str | Path, *, archive_id: str) → dict[str, str][source]

Write this fitted native predictor as a portable Archive V2.

The archive consists solely of the exact native TrainingOutcome and Package V2 emitted by DAG-ML. Assembly remains owned by DAG-ML and ZIP persistence by Core; this method neither serializes a Python estimator nor retrains through PipelineRunner.

Parameters:

  • archive_path – New .n4a Archive V2 destination.

  • archive_id – Explicit stable archive identity for the closed DAG-ML/Core archive contract.

Returns:

The Core-issued archive id and SHA-256 reference.

Raises:

DagMLNativeCoverageError – If fit did not retain an exportable portable predictor package.

fit(X: Any, y: Any, *, sample_ids: Any = None, groups: Any = None, metadata: Any = None) → DagMLPipelineEstimator[source]

Fit the pipeline through native DAG-ML training contracts.

native_runtime_client() → DagMLNativeClient[source]

Return the client selected for this attached native result.

predict(X: Any) → ndarray[source]

Predict via native loaded-package replay.

No Python pseudo-prediction path exists here. Until the replay compiler and decoder are supplied, this method fails with a typed coverage error.

predict_proba(X: Any) → ndarray[source]

Predict class probabilities via native loaded-package replay.

This method never creates one-hot pseudo-probabilities. A native replay decoder for probability outputs must be supplied explicitly.

predict_with_identity(X: Any, *, sample_ids: Any, groups: Any = None, metadata: Any = None) → ndarray[source]

Predict through native replay with an explicit X-only identity frame.

Persisted or relation-sensitive packages should use this method rather than sklearn’s positional predict(X) surface: it gives the replay compiler the exact row identities it must bind into the target-free PREDICT envelope. The method never accepts or creates targets.

replay_with_identity(X: Any, *, sample_ids: Any, groups: Any = None, metadata: Any = None) → Any[source]

Return the native PREDICT replay for an explicitly identified cohort.

This is the evidence-preserving counterpart of predict_with_identity(). It intentionally returns the DAG-ML replay contract rather than decoding it into a NumPy array, so callers such as the conformal attachment lane can bind the exact replay to identity-keyed truth in DAG-ML. It never supplies targets, computes provenance, or invokes a legacy runner.

select_portable_output(binding_id: str) → dict[str, Any][source]

Select one named output from the fitted portable predictor package.

DAG-ML validates the package fingerprint and resolves the binding. The retained package is not narrowed or mutated, so a later replay can still request every independently captured output.

Parameters:

binding_id – Exact portable output binding identifier.

Returns:

DAG-ML’s validated package/output selection view.

set_fit_request(*, groups: bool | None | str = '$UNCHANGED$', metadata: bool | None | str = '$UNCHANGED$', sample_ids: bool | None | str = '$UNCHANGED$') → DagMLPipelineEstimator

Configure whether metadata should be requested to be passed to the fit method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the User Guide on how the routing mechanism works.

The options for each parameter are:

  • True: metadata is requested, and passed to fit if provided. The request is ignored if metadata is not provided.

  • False: metadata is not requested and the meta-estimator will not pass it to fit.

  • None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.

  • str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

Added in version 1.3.

Parameters:

  • groups (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for groups parameter in fit.

  • metadata (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for metadata parameter in fit.

  • sample_ids (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for sample_ids parameter in fit.

Returns:

self – The updated object.

Return type:

object

class nirs4all.pipeline.dagml.estimator.DagMLPredictIdentityFrame(n_samples: int, sample_ids: tuple[str, ...], groups: tuple[str | None, ...], metadata_rows: tuple[dict[str, Any], ...], explicit_sample_ids: bool, data_content_fingerprint: str, fingerprint: str)[source]

Bases: object

Normalized identity and feature-content proof for one X-only replay.

PREDICT must not manufacture target data merely to reuse a training identity. This frame therefore binds exactly the supplied feature rows, stable sample ids and optional group/metadata columns, and deliberately has no target fingerprint.

data_content_fingerprint: str
explicit_sample_ids: bool
fingerprint: str
group_by_sample_id() → dict[str, str][source]

Return non-null groups keyed by the exact public sample id.

groups: tuple[str | None, ...]
metadata_by_sample_id() → dict[str, dict[str, Any]][source]

Return row metadata keyed by the exact public sample id.

metadata_rows: tuple[dict[str, Any], ...]
n_samples: int
sample_ids: tuple[str, ...]
class nirs4all.pipeline.dagml.estimator.DagMLReplayCompiler(*args, **kwargs)[source]

Bases: Protocol

Protocol for future nirs4all→DAG-ML predict/proba replay compilers.

compile_replay(estimator: DagMLPipelineEstimator, X: Any, *, mode: str, identity_frame: DagMLPredictIdentityFrame) → DagMLReplayExecution[source]
class nirs4all.pipeline.dagml.estimator.DagMLReplayExecution(request: Any, data_envelopes: Any, artifact_handles: Any, op_callback: Any, outcome_id: str, run_id: str, artifact_callback: Any = None, cleanup: Any = None, warnings: Any = (), diagnostics: Any = None, methods_inputs: Any = None, methods_library_path: str | None = None)[source]

Bases: object

Already-compiled native loaded-package replay call inputs.

artifact_callback: Any = None
artifact_handles: Any
cleanup: Any = None
data_envelopes: Any
diagnostics: Any = None
methods_inputs: Any = None
methods_library_path: str | None = None
op_callback: Any
outcome_id: str
request: Any
run_id: str
warnings: Any = ()
class nirs4all.pipeline.dagml.estimator.DagMLTrainingCompiler(*args, **kwargs)[source]

Bases: Protocol

Protocol for future nirs4all→DAG-ML fit contract compilers.

compile_fit(estimator: DagMLPipelineEstimator, X: Any, y: Any, *, sample_ids: Any = None, groups: Any = None, metadata: Any = None, identity_frame: DagMLFitIdentityFrame) → DagMLTrainingExecution[source]
class nirs4all.pipeline.dagml.estimator.DagMLTrainingExecution(request: Any, data_envelopes: Any, relations: Any, training_influence: Any, op_callback: Any, outcome_id: str, run_id: str, bundle_id: str, warnings: Any = (), diagnostics: Any = None, methods_inputs: Any = None, methods_library_path: str | None = None)[source]

Bases: object

Already-compiled native training call inputs.

These fields map one-to-one to dag_ml.execute_training(...). The class intentionally carries contracts and callbacks as opaque values; validation remains owned by DAG-ML.

bundle_id: str
data_envelopes: Any
diagnostics: Any = None
methods_inputs: Any = None
methods_library_path: str | None = None
op_callback: Any
outcome_id: str
relations: Any
request: Any
run_id: str
training_influence: Any
warnings: Any = ()