Python SDK

ClusterClient is the public SDK. It speaks the REST API and nothing more — it never imports nirs4all.

from nirs4all_cluster import ClusterClient, build_nirs4all_run_request

with ClusterClient("http://host:8765", token=None) as client:
    job = client.submit_nirs4all_run(
        pipelines=["/shared/pls.yaml", "/shared/rf.yaml"],
        datasets=["/shared/corn", "/shared/wheat"],
        n_jobs=1,
        rank_metric="best_rmse", rank_mode="min",
    )
    job = client.wait(job.id)
    for row in job.aggregate.ranking:
        print(row["pipeline"], row["dataset"], row["metrics"])
    client.download_best_model(job.id, "best.n4a")

    # ops helpers
    print(client.stats())
    for j in client.list_jobs(status="running"):
        print(j.id, j.status)

    # Same request builder, useful for core / CLI callers that need to inspect or
    # persist the exact contract before submission.
    req = build_nirs4all_run_request(
        pipeline="/shared/pls.yaml",
        dataset="/shared/corn",
        params={"random_state": 42, "refit": True},
    )
    assert req.parity.scope == "atomic"

submit_run() remains as a compatibility alias. The core-facing adapter accepts local nirs4all.run vocabulary where it is meaningful: n_jobs is translated to the worker-local inner_n_jobs, while workspace_path is omitted because every distributed task gets an isolated workspace. The stored DistributedRunParity contract says the beta expects metric parity for whole-run tasks (atomic or explicit pipelines x datasets) and does not claim fine-grained DAG, variant, fold, subtree, or workspace parity.

If the server runs an incompatible protocol major the client raises nirs4all_cluster.versioning.ClusterVersionError; a compatible-but-different package version is logged once (see Version compatibility & pipeline fingerprints).

API

class nirs4all_cluster.ClusterClient

Bases: object

__init__(base_url, *, token=None, timeout=60.0, transport=None)

Parameters:

• base_url (str)

• token (str | None)

• timeout (float)

• transport (BaseTransport | None)

server_info()

Probe GET /version for reachability + protocol compatibility.

Call it once at startup to fail fast on an unreachable server (ClusterConnectionError) or an incompatible protocol major (compatible=False). /version is unauthenticated, so it does not validate the credential — the first authenticated call does that, raising ClusterAuthError / ClusterPermissionError as appropriate.

Return type:

ServerInfo

submit_nirs4all_run(*, pipeline=None, dataset=None, pipelines=None, datasets=None, params=None, n_jobs=None, inner_n_jobs=None, workspace_path=None, name=None, priority=0, requirements=None, outputs=None, retry=None, rank_metric='best_rmse', rank_mode='min', idempotency_key=None, metric_tolerance_abs=1e-06)

Submit a local nirs4all.run shaped job through the cluster adapter.

Parameters:

• pipeline (PipelineRef | dict | str | None)

• dataset (DatasetRef | dict | str | None)

• pipelines (list[PipelineRef | dict | str] | None)

• datasets (list[DatasetRef | dict | str] | None)

• params (dict[str, Any] | None)

• n_jobs (int | None)

• inner_n_jobs (int | None)

• workspace_path (str | Path | None)

• name (str | None)

• priority (int)

• requirements (dict[str, Any] | None)

• outputs (dict[str, Any] | None)

• retry (dict[str, Any] | None)

• rank_metric (str)

• rank_mode (str)

• idempotency_key (str | None)

• metric_tolerance_abs (float)

Return type:

JobView

upload_artifact(path, *, kind='input')

Upload an input file (pipeline YAML / dataset zip); returns artifact_id.

Parameters:

• path (str | Path)

• kind (str)

Return type:

str

get_result(job_id)

Alias for get_job — the aggregate (ranking, best model) lives on the view.

Parameters:

job_id (str)

Return type:

JobView