nirs4all.api.native_result module

Native-only RunResult projection for the portable Methods lane.

This module is intentionally separate from the legacy workspace result path. It exposes the canonical DAG-ML score evidence and writes Archive V2 through the fitted native estimator; neither operation may materialize a PipelineRunner or a host-sidecar model.

class nirs4all.api.native_result.NativeMethodsRunResult(projected: RunResult, estimator: DagMLPipelineEstimator, *, archive_id: str, live_witness: _LiveMethodsWitness | _LiveMethodsTerminalWitness, _factory_capability: object)

Bases: RunResult

A RunResult backed only by a fitted portable Methods estimator.

The compatibility projection consumes the exact native ScoreSet. It does not reconstruct scores, attach a legacy workspace, or retain a Python model. Predictions on new cohorts are intentionally performed through native_estimator with explicit sample identities.

close() → None

Close ordinary result resources and detach the strict native facade.

detach() → None

Release legacy and strict native runtime resources deterministically.

export(output_path: str | Path, format: str = 'n4a', source: dict[str, Any] | None = None, chain_id: str | None = None, *, compatibility: str | None = None) → Path

Write Core Archive V2 directly from the fitted native package.

Legacy workspace selectors and compatibility='legacy-refit' are rejected: this result must never turn a native training request into a second host fit. Archive V2 preserves its ordinary manifest, signed outcome, Package V2 and validated cache members, but never writes, restores or forges a live terminal receipt.

export_model(output_path: str | Path, source: dict[str, Any] | None = None, format: str | None = None, fold: int | None = None, *, compatibility: str | None = None) → Path

Refuse legacy model export before it can create any side effect.

A strict Methods result is persistable only as its native Archive V2. The inherited compatibility exporter may refit through legacy paths, which would invalidate the execution claim.

classmethod from_estimator(estimator: DagMLPipelineEstimator, *, dataset_name: str, model_name: str, metric: str = 'rmse', task_type: str = 'regression') → NativeMethodsRunResult

Project a fitted estimator’s canonical ScoreSet without re-execution.

hpo_resume_package_json() → str

Return the complete signed package required to resume native HPO.

The package — not a free checkpoint or a Python trial list — is the portable resume carrier. Passing its exact JSON back as tuning={"engine": "methods-hpo", ..., "resume_package_json": ...} lets DAG-ML validate the checkpoint, terminal ledger, plan, fold set, identities, influence and SELECT binding before it requests another native trial. Results without a Methods HPO state cannot be used as a resume parent.

property native_archive_reference: dict[str, str] | None

The exact Core-issued reference from the last successful export.

property native_conformal_calibration: dict[str, Any] | None

Return the DAG-ML-attested conformal state, when calibration ran.

The mapping is the native contract emitted after the exact calibration replay was attached. No Python interval state is reconstructed here; Archive V2 and native PREDICT remain the authoritative persistence and materialization paths.

property native_estimator: DagMLPipelineEstimator

The fitted native estimator for identity-bound PREDICT replay.

property native_execution_claim: NativeMethodsExecutionClaim | NativeMethodsTerminalExecutionClaim

Return the current audit-only claim for attached strict execution.

This property fails closed once the result has been detached or closed. It intentionally exposes neither the raw PyO3 result nor native input buffers, callbacks, library paths, or controllers.

property native_execution_is_live: bool

Whether the strict process-local execution witness remains attached.

property native_methods_hpo_resume_state: dict[str, Any] | None

Return the attested native HPO checkpoint/evidence, when present.

The value is the exact DAG-ML durable state (including the opaque N4MOPT checkpoint and completed terminal trial ledger), copied only at the outer mapping boundary so callers cannot mutate the retained training outcome. Native public resume is intentionally not exposed yet: accepting an arbitrary checkpoint here would bypass the package binding and provenance validation owned by DAG-ML.

property native_retrain_lineage: dict[str, Any] | None

Return strict, durable parent evidence for a native full retrain.

property native_selected_variant_id: str | None

Return the scheduler-selected native variant identity, if any.

property terminal_prediction: dict[str, Any]

Return the non-attesting output snapshot of the terminal call.

Unlike terminal_receipt, this is ordinary prediction data and DAG-ML intentionally materializes a new mutable mapping for it.

property terminal_receipt: Any

Return the exact frozen native receipt for a terminal execution.

The receipt remains available after close() because only its companion TrainingResult lifecycle facade is detached. It is not written to or reconstructed from Archive V2/export/replay.