Re-plug guide (host adoption)

Note

The Python snippets below use the Phase-1 MVP spelling (e.g. plan.accept(...)). The published wheel exposes plan.resolved_spec and the module-level nio.validate(spec) instead — see Getting started. The adoption sequence and ownership split are unchanged across both.

Story 5.3. nirs4all-io is a standalone externalization — it does not modify nirs4all or nirs4all-studio. Re-plugging the hosts onto it is a separate, user-owned effort. This guide documents the seam + a recommended sequence so that effort is cheap. Nothing here changes nirs4all/studio; it is a plan.

Why a clean seam exists

• nirs4all-io has no runtime dependency on nirs4all (the future re-plug — nirs4all calling io — would otherwise be circular). The only touch-point is a lazy import of the SpectroDataset class at materialization.

• The contract is the JSON DatasetSpec/DatasetPlan + infer/load/to_spec (see API.md), all versioned (schema_version).

• A parity oracle (tests/test_parity.py) proves io’s SpectroDataset equals nirs4all’s own loader output, so a swap is behavior-preserving for covered cases.

Recommended sequence (studio first)

1. Studio (lowest risk). Replace the studio backend’s dataset detection/loading delegation (api/datasets.py) with nio.infer(input).to_dict() for the wizard’s recommendation step, and nio.load(plan.accept(edits)) for the load step. The studio already buckets confidence (0.8/0.6) — feed it plan scores (labelled as scores, not probabilities, until the corpus is calibrated; see inference).

2. Run the parity oracle in the host’s CI on the host’s own fixtures (it imports both nirs4all and nirs4all-io read-only) to catch drift before switching the default.

3. nirs4all library. Once studio is stable on io, let nirs4all.DatasetConfigs accept dataset=<DatasetSpec | DatasetPlan | nirs4all-io result> by delegating to nio.load(...). Keep the legacy path until parity is green across the host’s corpus.

4. De-duplicate (host-owned, last). Only after parity holds, the host may remove its now-duplicated detection/loader code. That deletion is out of scope for nirs4all-io.

What stays in nirs4all-io vs the host

• io owns: resolve, infer, conventions, the DatasetSpec IR, join/merge, tabular loading, and SpectroDataset materialization.

• host keeps: the pipeline/runtime, UI, workspace/storage — everything downstream of a built SpectroDataset.

Copy provenance & license

io copies CeCILL-2.1 logic from nirs4all and is dual-licensed CeCILL-2.1 OR AGPL-3.0-or-later to stay compatible (see ../COPY_PROVENANCE.md, ../LICENSE). The re-plug introduces no new license obligation on the hosts.