client.training

Bases: SyncResource

Sync training namespace (client.training).

catalog

catalog() -> list[CatalogEntry]

List the trainable RF-DETR variants + their knob schema (defaults/bounds).

Tenant-level and static — a plain authenticated read (any workspace role). Returns the full list (not paginated).

stats

stats(project_id: UUID | str, version_id: UUID | str, *, task: TrainingTask | str) -> TrainingStats

Pre-train readiness for one task on a frozen version — image/instance counts + per-class distribution (an O(1) read of the freeze-time snapshot).

Parameters:

Name	Type	Description	Default
task	TrainingTask | str	detection or segmentation.	required

Raises:

Type	Description
NotFoundError	unknown version in this project.
ConflictError	version is not ready, or predates the freeze-time stats snapshot (RESOURCE_NOT_READY) — delete and re-freeze it.
ForbiddenError	caller is not a workspace admin (AUTH_FORBIDDEN).
UnprocessableError	task is not a valid enum value (VALIDATION_ERROR).

create_run

create_run(project_id: UUID | str, version_id: UUID | str, *, name: str, task: TrainingTask | str, model: str, epochs: int | None = None, early_stopping: bool | None = None, patience: int | None = None, split: SplitConfigParam | None = None) -> TrainingRun

Create + dispatch a training run (202). NOT a platform Job — poll the returned run via :meth:get_run / :meth:wait_run.

Parameters:

Name	Type	Description	Default
name	str	display name for the run.	required
task	TrainingTask | str	detection or segmentation (must match the model's task).	required
model	str	catalog key (see :meth:catalog, e.g. 'rf-detr-nano').	required
epochs	int | None	training epochs; null uses the catalog default.	None
early_stopping	bool | None	stop on val-loss plateau; null uses the catalog default.	None
patience	int | None	epochs without improvement before early-stop; null uses the catalog default. Only enforced (patience <= epochs) when early stopping is on.	None
split	SplitConfigParam | None	train/val/test split config dict (strategy/train/val/ test/seed [+ train_tag/val_tag/test_tag for the tags-as-split of ADR-0065); null uses the catalog default.	None

Returns:

Type	Description
TrainingRun	The created run (status queued, or failed if Batch dispatch
TrainingRun	failed at submit time). An identical live/succeeded run for this version
TrainingRun	is returned instead of a duplicate (server-side config idempotency).

Raises:

Type	Description
UnprocessableError	unknown/task-mismatched model, no classes for the task, patience > epochs with early stopping on, invalid split tags, or the count floor blocks the run (VALIDATION_ERROR).
NotFoundError	unknown version in this project.
ConflictError	version not ready / missing stats snapshot (RESOURCE_NOT_READY), a run is already in progress for this tenant (JOB_ALREADY_RUNNING), or the trained-model cap is reached (RESOURCE_LIMIT_EXCEEDED).
ForbiddenError	caller is not a workspace admin (AUTH_FORBIDDEN).

get_run

get_run(project_id: UUID | str, version_id: UUID | str, run_id: UUID | str) -> TrainingRun

Fetch one training run (a complete snapshot, not a page).

Raises:

Type	Description
NotFoundError	unknown run for this version (JOB_NOT_FOUND).
ForbiddenError	caller is not a workspace admin (AUTH_FORBIDDEN).

list_runs

list_runs(project_id: UUID | str, version_id: UUID | str, *, limit: int | None = None, cursor: str | None = None) -> Page[TrainingRun]

List a version's training runs, newest first (cursor-paginated; iterate for all pages).

Raises:

Type	Description
BadRequestError	malformed cursor (INVALID_CURSOR).
ForbiddenError	caller is not a workspace admin (AUTH_FORBIDDEN).

metrics

metrics(project_id: UUID | str, version_id: UUID | str, run_id: UUID | str) -> list[MetricPoint]

The live per-epoch training curve — train/val loss + val mAP / mAP@50 / precision / recall, one point per completed epoch, ordered ascending. Poll alongside :meth:get_run while a run is running to draw the charts.

Returns the full list (not paginated).

Raises:

Type	Description
NotFoundError	unknown run for this version (JOB_NOT_FOUND).
ForbiddenError	caller is not a workspace admin (AUTH_FORBIDDEN).

cancel_run

cancel_run(project_id: UUID | str, version_id: UUID | str, run_id: UUID | str) -> TrainingRun

Cancel a queued/running run (202) — best-effort terminates the Batch job and marks the run canceled. Returns the updated run.

Raises:

Type	Description
NotFoundError	unknown run for this version (JOB_NOT_FOUND).
ConflictError	run is already terminal — only queued/running runs can be canceled (JOB_TERMINAL).
ForbiddenError	caller is not a workspace admin (AUTH_FORBIDDEN).

wait_run

wait_run(project_id: UUID | str, version_id: UUID | str, run_id: UUID | str, *, timeout: float = _DEFAULT_WAIT_TIMEOUT_S, poll_interval: float = _DEFAULT_WAIT_POLL_S) -> TrainingRun

Poll :meth:get_run until the run reaches a terminal status (succeeded / failed / canceled); returns the terminal run (inspect .status / .error). Does NOT raise on failed — the failure detail is on the run.

Training is minutes-to-hours, so the default timeout is generous (2h) and polling is coarse (15s). Raises :class:TimeoutError if the budget elapses before the run is terminal (it keeps running server-side — call again later).

Response models

Models returned by client.training methods (fields, types, and what each means).

Training domain models (ADR-0064) — RF-DETR runs, the model catalog, the live metrics curve, and pre-train readiness stats.

Response models only (extra="allow"); enums come from common. Training request bodies are built as plain dicts in resources.training — the server validates them. A training run is a first-class row polled directly (NOT a platform Job): create returns it 202, then poll training.get_run / training.wait_run (see the resource module).

CatalogEpochsKnob

Bases: BaseModel

Bounds for the epochs knob.

CatalogEarlyStoppingKnob

Bases: BaseModel

Default for the early_stopping toggle.

CatalogPatienceKnob

Bases: BaseModel

Bounds for the patience knob.

CatalogSplitDefault

Bases: BaseModel

The split applied when a run omits one.

CatalogSplitKnob

Bases: BaseModel

Split defaults + the accepted strategies.

CatalogOptions

Bases: BaseModel

The four configurable knobs (uniform across every variant).

CatalogEntry

Bases: BaseModel

One trainable catalog variant: a selection key + display name + task, plus the options knob schema (defaults/bounds) the create call validates against.

SplitConfig

Bases: BaseModel

The resolved train/val/test split a run trains on. *_tag fields are the tags-as-split names (ADR-0065); null unless the run named them.

TrainingRun

Bases: BaseModel

One RF-DETR training run over a frozen project version. Poll status / epochs_completed to a terminal state (succeeded/failed/canceled).

MetricPoint

Bases: BaseModel

One epoch on the live training curve (ADR-0064). Any field may be null (e.g. a run with no val split reports losses only).

TrainingStatsClass

Bases: BaseModel

Per-class instance and image counts within a frozen version, for one task.

TrainingStats

Bases: BaseModel

Pre-train readiness for one task on a frozen version (ADR-0064). Callers render this + raise their own advisory warnings; the server only hard-blocks genuine impossibility at create time.