client.auto_label¶
Bases: SyncResource
Sync auto-label namespace (client.auto_label).
get_config ¶
Fetch the project's auto-label policy + live readiness (manager). config
is null when unconfigured. A complete snapshot, not a page.
Raises:
| Type | Description |
|---|---|
ForbiddenError
|
caller is not a project manager (AUTH_FORBIDDEN). |
put_config ¶
put_config(project_id: UUID | str, *, model_ref: ModelRef | dict[str, Any], class_map: dict[str, UUID | str] | None = None, confidence_threshold: float | None = None, labeler_assist_enabled: bool | None = None, auto_advance_all_high_conf: bool | None = None) -> AutoLabelConfigResponse
Set the project's auto-label policy (manager). The deployment need not be ready at config time (it can be brought up later).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
model_ref
|
ModelRef | dict[str, Any]
|
which model — |
required |
class_map
|
dict[str, UUID | str] | None
|
model-class-id (string) → project-class-id. Omit to auto-derive by matching class names 1:1 (works when the model was trained from this project's version). |
None
|
confidence_threshold
|
float | None
|
default triage threshold (0..1); omit for the server default. |
None
|
labeler_assist_enabled
|
bool | None
|
enable the in-editor :meth: |
None
|
auto_advance_all_high_conf
|
bool | None
|
workflow policy — when True, a batch-labeled asset whose predictions are all at/above the confidence threshold is auto-advanced past review (treated as done); assets with any below-threshold prediction still route to a human. Omit for the server default (off). |
None
|
Raises:
| Type | Description |
|---|---|
NotFoundError
|
the deployment (or its model) doesn't exist (DEPLOYMENT_NOT_FOUND / UNCATEGORIZED). |
UnprocessableError
|
foundation-model refs (not supported yet), a class_map targeting classes not in this project, a model whose geometry isn't in a mapped class's allowed_types (or that class is archived), or a class_map that couldn't be auto-derived (VALIDATION_ERROR). |
ForbiddenError
|
caller is not a project manager (AUTH_FORBIDDEN). |
create_run ¶
create_run(project_id: UUID | str, *, asset_ids: list[UUID | str] | None = None, all: bool | None = None, confidence_threshold: float | None = None, skip_annotated: bool | None = None, on_existing: Literal['overwrite', 'append'] | str | None = None, on_overlap: Literal['respect', 'replace'] | str | None = None, idempotency_key: str | None = None) -> JobHandle
Start a batch pre-label run over a scope (manager); returns a
:class:JobHandle (202, kind="auto_label_project"). Pass EXACTLY ONE of
asset_ids (≤ 20,000) or all=True (the whole project).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
confidence_threshold
|
float | None
|
override the project's configured triage threshold for this run only (0..1); omit to use the configured default. |
None
|
Existing-annotation policy (human work is always protected):
skip_annotated: default True — only label assets with zero annotations.
on_existing: for already-annotated assets when skip_annotated is False —
"overwrite" (clear the asset's AI labels, rewrite; humans kept) or
"append" (default, keep everything, add new AI).
on_overlap: for an appended prediction overlapping an existing annotation —
"respect" (default, drop it) or "replace" (win over an
overlapping AI annotation; always yields to a human one).
Raises:
| Type | Description |
|---|---|
ConflictError
|
idempotency key reused with a different body (IDEMPOTENCY_REPLAY). |
RateLimitError
|
per-tenant active-job cap reached (JOB_PER_TENANT_CAP). |
NotFoundError
|
the configured model no longer exists (MODEL_NOT_FOUND). |
UnprocessableError
|
auto-label not configured, a non-deployment config, more than 20,000 asset_ids, or not-exactly-one scope (VALIDATION_ERROR). |
ForbiddenError
|
caller is not a project manager (AUTH_FORBIDDEN). |
list_runs ¶
list_runs(project_id: UUID | str, *, limit: int | None = None, cursor: str | None = None) -> Page[Job]
List this project's auto-label runs, newest first (cursor-paginated;
iterate for all pages). Each item is a kind="auto_label_project" Job.
Raises:
| Type | Description |
|---|---|
BadRequestError
|
malformed |
ForbiddenError
|
caller is not a project manager (AUTH_FORBIDDEN). |
cancel_run ¶
Cancel an in-flight run — the worker honors the terminal canceled status
at the next chunk boundary. Returns the updated Job; a run that is already
terminal is returned unchanged (idempotent, no error).
Raises:
| Type | Description |
|---|---|
NotFoundError
|
unknown run for this project (JOB_NOT_FOUND). |
ForbiddenError
|
caller is not a project manager (AUTH_FORBIDDEN). |
suggest ¶
suggest(project_id: UUID | str, asset_id: UUID | str, *, confidence: float | None = None) -> AutoLabelSuggestResponse
In-editor assist on one image (any project member) — runs the configured deployment and returns suggestions (NOT persisted; accept/edit, then commit via the normal annotation-create path).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
confidence
|
float | None
|
override the project's threshold for this call only (0..1). |
None
|
Raises:
| Type | Description |
|---|---|
ForbiddenError
|
assist not enabled for this project (PROJECT_STATE_FORBIDDEN), or caller is not a project member (AUTH_FORBIDDEN). |
ConflictError
|
the configured model is not ready (UNCATEGORIZED). |
NotFoundError
|
asset not in this project's dataset (ASSET_NOT_FOUND). |
RateLimitError
|
inference rate limit exceeded (RATE_LIMITED). |
UnavailableError
|
the model is warming (MODEL_LOADING / MODEL_STARTING — retry) or inference failed (DEPENDENCY_UNAVAILABLE). |
Response models¶
Models returned by client.auto_label methods (fields, types, and what each means).
Model-assisted auto-labeling domain models (ADR-0075).
Two surfaces over one engine:
- config (manager): the per-project policy — which model, class map, thresholds.
- batch run (manager): an async :class:~superb_ai.types.jobs.Job
(kind="auto_label_project") — created/listed/canceled here, polled via a
:class:~superb_ai._jobs.JobHandle.
- in-editor assist (labeler): sync single-image suggestions, NOT persisted.
Response models are tolerant readers (extra="allow"); enums + read-side geometry
come from common (never re-declared). ModelRef is also a request model —
callers construct it to set the config.
ModelRef ¶
Bases: BaseModel
Which model backs auto-label. kind="deployment" → a trained-model
SageMaker endpoint (batch + assist); kind="foundation" → an open-vocab model
(assist only). A deployment ref needs deployment_id; a foundation ref
needs foundation_key (the server validates coherence, 422 otherwise).
Doubles as the request shape callers build for :meth:AutoLabel.put_config.
AutoLabelConfig ¶
Bases: BaseModel
The stored per-project auto-label policy. class_map maps the model's class
id (string key) → a project class id; it is the server-resolved map (auto-derived
from matching class names when omitted at write time).
AutoLabelConfigResponse ¶
Bases: BaseModel
The config + live readiness. ready is True only when the configured model
is usable right now (deployment ready); ready_reason explains a False.
AutoLabelSuggestion ¶
Bases: BaseModel
One predicted object from in-editor assist. class_id is null when the model
class couldn't be mapped to a project class (assign one before committing).
geometry is the same read-side shape annotation.geometry carries, so an
accepted suggestion commits through the normal annotation-create path.
AutoLabelSuggestResponse ¶
Bases: BaseModel
Assist result for one image — zero or more suggestions, none persisted.