nirs4all.api.session module

Session context manager for nirs4all API.

A Session maintains shared resources across multiple nirs4all operations, including a reusable PipelineRunner instance, consistent workspace paths, and shared logging configuration.

Two usage patterns:

1. Context manager for shared runner (resource reuse):

   >>> with nirs4all.session(verbose=2, save_artifacts=True) as s:
   ...     r1 = nirs4all.run(pipeline1, data1, session=s)
   ...     r2 = nirs4all.run(pipeline2, data2, session=s)
   ...     # Both runs share workspace and configuration
   

2. Stateful session with pipeline (training workflow):

   >>> session = nirs4all.Session(pipeline=pipeline, name="MyModel")
   >>> result = session.run(dataset)
   >>> predictions = session.predict(new_data)
   >>> session.save("model.n4a")
   

exception nirs4all.api.session.SessionClosedError

Bases: RuntimeError

An operation was attempted on a terminally closed Session.

nirs4all.api.session.load_native_archive_session(path: str | Path, *, methods_library_path: str | Path | None = None) → NativeArchiveSession

Open a validated portable Archive V2/V3 session without a legacy fallback.

nirs4all.api.session.load_session(path: str | Path, *, engine: str | None = None, methods_library_path: str | Path | None = None) → Session | NativeArchiveSession

Load a session from a saved bundle file.

Parameters:

• path – Path to a legacy .n4a bundle or Core Archive V2.

• methods_library_path – Optional exact Methods runtime used by a Core Archive V2 session. Use the same runtime path for training and loading within a process; native identity checks remain enforced.

Returns:

Session ready for prediction.

Notes

Core Archive V2 is hashed immediately before and after Core derives its native predictor descriptors. Prediction hashes the source once more before it inspects input data, binding the cached package, descriptor set and libn4m identity to the exact archive bytes.

Example

>>> session = nirs4all.load_session("exports/model.n4a")
>>> predictions = session.predict(new_data)

nirs4all.api.session.session(pipeline: list[Any] | None = None, name: str = '', **kwargs: Any) → Generator[Session, None, None]

Create an execution session context manager.

This is a convenience function that creates a Session and yields it within a context manager block.

Parameters:

• pipeline – Optional pipeline definition for stateful mode.

• name – Name for the session/pipeline.

• **kwargs – Arguments passed to Session (and ultimately PipelineRunner). Common options: - verbose (int): Verbosity level (0-3). Default: 1 - save_artifacts (bool): Save model artifacts. Default: True - workspace_path (str|Path): Workspace directory. - random_state (int): Random seed for reproducibility.

Yields:

Session – The active session for use within the block.

Example (resource sharing):

>>> with nirs4all.session(verbose=2, save_artifacts=True) as s:
...     r1 = nirs4all.run(pipeline1, data1, session=s)
...     r2 = nirs4all.run(pipeline2, data2, session=s)
...     print(f"PLS: {r1.best_score:.4f}, RF: {r2.best_score:.4f}")

Example (stateful pipeline):

>>> with nirs4all.session(pipeline=my_pipeline, name="Demo") as s:
...     result = s.run("sample_data/regression")
...     print(f"Best score: {result.best_score:.4f}")