client.datasets

Bases: SyncResource

Sync datasets namespace (client.datasets).

create

create(*, name: str, description: str | None = None) -> Dataset

Create an image dataset (201).

Parameters:

Name	Type	Description	Default
name	str	display name, unique within the tenant (1..NAME_MAX chars).	required
description	str | None	optional free text (cleared later with "").	None

Raises:

Type	Description
ConflictError	name already taken (DATASET_NAME_TAKEN).
ConflictError	tenant dataset cap reached (RESOURCE_LIMIT_EXCEEDED).
UnprocessableError	blank/over-long name or description (VALIDATION_ERROR).
ForbiddenError	caller is not a workspace admin (AUTH_FORBIDDEN).

list

list(*, q: str | None = None, created_at_from: datetime | str | None = None, created_at_to: datetime | str | None = None, include_total: bool = False, limit: int | None = None, cursor: str | None = None) -> Page[UnifiedDataset]

List datasets across kinds, newest first (cursor-paginated; iterate for all pages). This is the unified GET /datasets surface.

Parameters:

Name	Type	Description	Default
q	str | None	case-insensitive substring on the name (LIKE wildcards escaped).	None
created_at_from	datetime | str | None	keep only datasets created at/after this instant (inclusive lower bound; datetime or ISO-8601 string).	None
created_at_to	datetime | str | None	keep only datasets created at/before this instant (inclusive upper bound; datetime or ISO-8601 string).	None
include_total	bool	also populate page.total (costs a COUNT).	False

Raises:

Type	Description
BadRequestError	malformed cursor (INVALID_CURSOR).

get

get(dataset_id: UUID | str) -> Dataset

Fetch one image dataset.

Raises:

Type	Description
NotFoundError	unknown dataset in this tenant (DATASET_NOT_FOUND).

update

update(dataset_id: UUID | str, *, name: str | None = None, description: str | None = None) -> Dataset

Partial update — pass only the fields you want to change. Pass description="" to clear it (None means "leave unchanged").

Raises:

Type	Description
BadRequestError	no updatable fields supplied (BAD_REQUEST).
ConflictError	new name already taken (DATASET_NAME_TAKEN).
NotFoundError	unknown dataset (DATASET_NOT_FOUND).
ForbiddenError	caller is not a workspace admin (AUTH_FORBIDDEN).

delete

delete(dataset_id: UUID | str) -> None

Hard-delete a dataset and all its assets (ADR-0051). Returns nothing — the server responds 204. S3 byte-cleanup is swept asynchronously.

Raises:

Type	Description
NotFoundError	unknown dataset (DATASET_NOT_FOUND).
ForbiddenError	caller is not a workspace admin (AUTH_FORBIDDEN).

stats

stats(dataset_id: UUID | str) -> DatasetStats

Asset counts + embedding coverage — a complete snapshot, not a page.

Raises:

Type	Description
NotFoundError	unknown dataset (DATASET_NOT_FOUND).

embed

embed(dataset_id: UUID | str, *, idempotency_key: str | None = None) -> JobHandle

Kick off a dataset-wide embedding pass (ADR-0033); returns a :class:JobHandle (202) — call .wait() to poll to terminal. Embeds every active asset that lacks a ready embedding; already-embedded assets are skipped. Auto-generates an idempotency key when you don't pass one, so a retried call replays the same job rather than duplicating.

Progress is coarse: the heavy lifting runs as one opaque GPU batch, so processed stays 0 for most of the run and jumps to total at ingest — don't build a progress bar on on_progress for this job kind; expect ~10–20 min for a few thousand images. Track completion instead via wait() or datasets.stats(...).embedding.

Raises:

Type	Description
NotFoundError	unknown dataset (DATASET_NOT_FOUND).
RateLimitError	per-tenant cap of 3 active jobs reached (JOB_PER_TENANT_CAP).
ConflictError	idempotency key reused with a different dataset (IDEMPOTENCY_REPLAY).
ForbiddenError	caller is not a workspace admin (AUTH_FORBIDDEN).

Response models

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

Dataset domain models (image datasets + the unified cross-kind list).

The platform is image-only today, so client.datasets reads/writes image datasets; the unified list (datasets.list) carries a kind discriminator so the shape survives a future second dataset kind. Enums come from common — never re-declared here.

Dataset

Bases: BaseModel

One image dataset row (the kind-specific create/get/update response).

UnifiedDataset

Bases: BaseModel

A dataset as returned by the cross-kind list (GET /datasets). kind tells the caller which kind-specific endpoints to use for follow-up calls. Carries no updated_at — the unified projection omits it (server contract).

DatasetStats

Bases: BaseModel

Asset counts for a dataset (the FE grid header). by_status sums to total; embedding reports semantic-search coverage (ADR-0033) and its values also sum to total — use it for a "1872 / 2000 embedded" badge. embedding is None on datasets that predate embedding tracking.