Python API

Reference documentation for the edgefirst_client Python module, generated from the installed package.

For hands-on examples, see the Python tutorials. IDE help is available via edgefirst_client.pyi stubs in the PyPI wheel.

EdgeFirst Studio Python client stubs.

Install: pip install edgefirst-client (includes the edgefirst-client CLI).

Tutorials: examples/README.md in the GitHub repository. CLI reference: CLI.md.

AnnotationSetUID `module-attribute`

AnnotationSetUID = Union[AnnotationSetID, int, str]

AppUID `module-attribute`

AppUID = Union[AppId, int, str]

DatasetUID `module-attribute`

DatasetUID = Union[DatasetID, int, str]

ExperimentUID `module-attribute`

ExperimentUID = Union[ExperimentID, int, str]

ImageUID `module-attribute`

ImageUID = Union[ImageId, int, str]

OrganizationUID `module-attribute`

OrganizationUID = Union[OrganizationID, int, str]

ParameterDict `module-attribute`

ParameterDict = Dict[
    str,
    Union[
        Parameter,
        ParameterValue,
        List[ParameterValue],
        Dict[str, ParameterValue],
    ],
]

ParameterValue `module-attribute`

ParameterValue = Union[str, float, bool]

Progress `module-attribute`

Progress = (
    Callable[[int, int], None]
    | Callable[[int, int, str | None], None]
)

ProjectUID `module-attribute`

ProjectUID = Union[ProjectID, int, str]

SampleUID `module-attribute`

SampleUID = Union[SampleID, int, str]

SequenceUID `module-attribute`

SequenceUID = Union[SequenceId, int, str]

SnapshotUID `module-attribute`

SnapshotUID = Union[SnapshotID, int, str]

TaskUID `module-attribute`

TaskUID = Union[TaskID, int, str]

TrainingSessionUID `module-attribute`

TrainingSessionUID = Union[TrainingSessionID, int, str]

ValidationSessionUID `module-attribute`

ValidationSessionUID = Union[ValidationSessionID, int, str]

all `module-attribute`

__all__ = edgefirst_client.__all__

doc `module-attribute`

__doc__ = edgefirst_client.__doc__

Annotation

Represents a single annotation associated with a sample in an EdgeFirst dataset.

An annotation may include sensor metadata such as (name, group, label, etc.) as well as 2D/3D bounding boxes and segmentation masks.

box2d `property`

box2d: Optional[Box2d]

The 2D bounding box associated with this annotation, if available.

Returns:

Optional[Box2d] –

Optional[Box2d]: The 2D bounding box or None.

box2d_score `property`

box2d_score: Optional[float]

Confidence score for the 2D bounding box.

Returns:

Optional[float] –

Optional[float]: The score or None.

box3d `property`

box3d: Optional[Box3d]

The 3D bounding box associated with this annotation, if available.

Returns:

Optional[Box3d] –

Optional[Box3d]: The 3D bounding box or None.

box3d_score `property`

box3d_score: Optional[float]

Confidence score for the 3D bounding box.

Returns:

Optional[float] –

Optional[float]: The score or None.

category_frequency `property`

category_frequency: Optional[str]

The category frequency label (e.g. "common", "rare"), if any.

frame_number `property`

frame_number: Optional[int]

The frame number within the annotation's sequence, if any.

group `property`

group: Optional[str]

The group this annotation belongs to, if specified. A group can be "train", "val", etc.

Returns:

Optional[str] –

Optional[str]: The group name or None.

iscrowd `property`

iscrowd: Optional[bool]

Whether this annotation marks a crowd region.

Returns:

Optional[bool] –

Optional[bool]: The iscrowd flag or None.

label `property`

label: Optional[str]

The semantic label (e.g., "car", "pedestrian") for this annotation.

Returns:

Optional[str] –

Optional[str]: The label or None.

label_index `property`

label_index: Optional[int]

The index of the label for this annotation.

Returns:

Optional[int] –

Optional[int]: The label index or None.

mask `property`

mask: Optional[bytes]

The raster mask as raw PNG bytes, if available.

Returns:

Optional[bytes] –

Optional[bytes]: PNG-encoded mask data or None.

mask_score `property`

mask_score: Optional[float]

Confidence score for the raster mask.

Returns:

Optional[float] –

Optional[float]: The score or None.

name `property`

name: Optional[str]

The name of the annotation instance, if specified. The name is derived from device hostname and the date and time and the specific frame from the recording "hostname_date_time_frame".

Returns:

Optional[str] –

Optional[str]: The instance name or None.

object_id `property`

object_id: Optional[str]

A unique identifier for the object associated with this annotation.

Returns:

Optional[str] –

Optional[str]: The object identifier or None.

polygon `property`

polygon: Optional[Polygon]

The polygon segmentation associated with this annotation, if available.

Returns:

Optional[Polygon] –

Optional[Polygon]: The polygon or None.

polygon_score `property`

polygon_score: Optional[float]

Confidence score for the polygon segmentation.

Returns:

Optional[float] –

Optional[float]: The score or None.

sample_id `property`

sample_id: Optional[SampleID]

The ID of the sample this annotation belongs to.

Returns:

Optional[SampleID] –

Optional[SampleID]: The sample ID, or None if not available.

sequence_name `property`

sequence_name: Optional[str]

The sequence name this annotation is part of, if any. The sequence name is derived from the device hostname and the date and time of the recording hostname_date_time.

Returns:

Optional[str] –

Optional[str]: The sequence name or None.

init

__init__() -> None

Create a new empty annotation.

set_box2d

set_box2d(box2d: Optional[Box2d]) -> None

Set the 2D bounding box for this annotation.

set_box2d_score

set_box2d_score(score: Optional[float]) -> None

Set the 2D bounding box confidence score.

set_box3d

set_box3d(box3d: Optional[Box3d]) -> None

Set the 3D bounding box for this annotation.

set_box3d_score

set_box3d_score(score: Optional[float]) -> None

Set the 3D bounding box confidence score.

set_category_frequency

set_category_frequency(
    category_frequency: Optional[str],
) -> None

Set the category frequency label (e.g. "common", "rare").

set_frame_number

set_frame_number(frame_number: Optional[int]) -> None

Set the frame number within the annotation's sequence.

set_iscrowd

set_iscrowd(iscrowd: Optional[bool]) -> None

Set the iscrowd flag for this annotation.

set_label

set_label(label: Optional[str]) -> None

Set the label for this annotation.

set_label_index

set_label_index(label_index: Optional[int]) -> None

Set the source-faithful label index for this annotation.

set_mask

set_mask(mask: Optional[bytes]) -> None

Set the raster mask (PNG bytes) for this annotation.

set_mask_score

set_mask_score(score: Optional[float]) -> None

Set the mask confidence score.

set_name

set_name(name: Optional[str]) -> None

Set the annotation's name (usually the sample's image filename).

set_object_id

set_object_id(object_id: Optional[str]) -> None

Set the object identifier for this annotation.

set_polygon

set_polygon(polygon: Optional[Polygon]) -> None

Set the polygon segmentation for this annotation.

set_polygon_score

set_polygon_score(score: Optional[float]) -> None

Set the polygon confidence score.

set_sample_id

set_sample_id(sample_id: Optional[SampleID]) -> None

Set the sample this annotation belongs to.

set_sequence_name

set_sequence_name(sequence_name: Optional[str]) -> None

Set the sequence name this annotation's sample belongs to.

AnnotationSet

The AnnotationSet class represents the collection of annotations for a given dataset. A dataset can have multiple annotation sets, each containing annotations for different tasks or purposes.

created `property`

created: Optional[datetime]

The creation date of the annotation set.

None if this annotation set was fetched via a tag-scoped query (the server's tag snapshot does not retain a creation timestamp).

dataset_id `property`

dataset_id: Optional[DatasetID]

The ID of the dataset that the annotation set belongs to.

None if this annotation set was fetched via a tag-scoped query where the server omitted dataset_id and no backfill was available.

description `property`

description: str

The description of the annotation set.

id `property`

id: AnnotationSetID

The ID of the annotation set.

name `property`

name: str

The name of the annotation set.

uid `property`

uid: str

The unique string identifier for the object.

.. deprecated:: Use str(AnnotationSet.id) instead. This property will be removed in a future version.

annotations

annotations(
    groups: List[str] = [],
    annotation_types: List[AnnotationType] = [],
    progress: Optional[Progress] = None,
    version: Optional[str] = None,
) -> List[Annotation]

Get annotations for this annotation set.

Parameters:

groups (List[str], default: [] ) –

List of dataset groups (train, val, test).
annotation_types (List[AnnotationType], default: [] ) –

List of annotation types to filter.
progress (Optional[Progress], default: None ) –

Optional progress callback. Supports two signatures: - callback(current, total) - basic progress - callback(current, total, status) - with status message (v2.8.0+)
version (Optional[str], default: None ) –

Optional version tag name to query data at that point in time. Defaults to the current (latest) state.

Progress

Reports progress with status=None as samples are fetched and processed for their annotations. Progress unit is samples processed (not individual annotations).

Returns:

List[Annotation] –

List[Annotation]: Annotations in this set.

Raises:

TypeError –

If annotation set has no client reference.

Example

annotations = annotation_set.annotations(groups=["train"]) annotations_v1 = annotation_set.annotations(version="v1.0")

delete

delete() -> None

Delete this annotation set.

Requires an embedded client reference (annotation sets returned by the client methods automatically have one).

Raises:

TypeError –

If annotation set has no client reference. Use client.delete_annotation_set(annotation_set.id) instead.

Example

annotation_set.delete()

AnnotationSetID

Unique identifier for an annotation set in EdgeFirst Studio.

Can be constructed from an integer, a prefixed hex string (e.g., "as-3d2c1b"), or another AnnotationSetID instance.

Examples:

>>> as_id = AnnotationSetID("as-3d2c1b")
>>> as_id = AnnotationSetID(0x3D2C1B)
>>> as_id = AnnotationSetID.from_str("as-3d2c1b")
>>> int(as_id)
4008987
>>> str(as_id)
'as-3d2c1b'

Note

Internally an AnnotationSetID is an unsigned 64-bit integer. This class handles translating between integer and string representations of annotation set IDs.

AnnotationType

Annotation types supported for labeling data in EdgeFirst Studio.

Represents the different types of annotations that can be applied to sensor data for machine learning tasks. Each type corresponds to a different annotation geometry and use case.

Examples:

>>> # Create annotation types
>>> box_2d = AnnotationType.Box2d
>>> polygon = AnnotationType.Polygon

>>> # Use in dataset queries
>>> annotations = dataset.get_annotations_by_type(AnnotationType.Box2d)

Members

Box2d: 2D bounding boxes for object detection in images Box3d: 3D bounding boxes for object detection in 3D space (LiDAR, etc.) Polygon: Polygonal segmentation boundaries for semantic/instance segmentation Mask: Pixel-level raster segmentation masks (PNG-encoded)

AppId

Unique identifier for an application in EdgeFirst Studio.

Can be constructed from an integer, a prefixed hex string (e.g., "app-2e1d0c"), or another AppId instance.

Examples:

>>> app_id = AppId("app-2e1d0c")
>>> app_id = AppId(0x2E1D0C)
>>> app_id = AppId.from_str("app-2e1d0c")
>>> int(app_id)
3022092
>>> str(app_id)
'app-2e1d0c'

Note

Internally an AppId is an unsigned 64-bit integer. This class handles translating between integer and string representations of application IDs.

Artifact

Represents an artifact produced by a training session.

model_type `property`

model_type: str

Returns the type of the model used in the artifact.

Returns:

str ( str ) –

The model type.

name `property`

name: str

Returns the name of the artifact.

Returns:

str ( str ) –

The artifact name.

BackgroundTaskID

A background task id in the bt- form used by Studio apps.

This is the same identity as :class:TaskID, written the way an app sees it. Studio launches every app with its own task id in the environment and uses the same form in log URLs (/logs/bt-55b5) and cloud-batch job names. Use :meth:to_task_id to get the form the task APIs accept, rather than decoding the hex by hand.

Can be constructed from an integer, a prefixed hex string (e.g., "bt-55b5"), or another BackgroundTaskID instance.

Examples:

>>> bt = BackgroundTaskID("bt-55b5")
>>> int(bt)
21941
>>> str(bt)
'bt-55b5'
>>> str(bt.to_task_id())
'task-55b5'

Note

Parsing is strict about the prefix: a "task-..." string is rejected here, and vice versa, even though both carry the same value. Convert explicitly rather than passing the strings around interchangeably.

Box2d

The Box2d is a representation of a single 2D bounding box annotation which is a pixel-based annotation for the image that is stored in EdgeFirst Datasets. The bounding boxes are normalized to the image dimensions (float32 values between 0 and 1). The width and height of the box are provided through the width and height properties while the position of the box can be represented in two ways: either through the left and top properties which represent the top-left corner of the box or through the cx and cy properties which represent the center of the box.

cx `property`

cx: float

Returns the x-center coordinate of the bounding box. This coordinate is normalized to the image width.

Returns:

float ( float ) –

The x-center coordinate of the bounding box.

cy `property`

cy: float

Returns the y-center coordinate of the bounding box. This coordinate is normalized to the image height.

Returns:

float ( float ) –

The y-center coordinate of the bounding box.

height `property`

height: float

Returns the height of the bounding box. This dimension is normalized to the image height.

Returns:

float ( float ) –

The height of the bounding box.

left `property`

left: float

Returns the left coordinate of the bounding box. This is either the x-center or xmin coordinate of the bounding box.

Returns:

float ( float ) –

The left coordinate of the bounding box.

top `property`

top: float

Returns the y-coordinate of the bounding box. This is either the y-center or ymin coordinate of the bounding box.

Returns:

float ( float ) –

The y-coordinate of the bounding box.

width `property`

width: float

Returns the width of the bounding box. This dimension is normalized to the image width.

Returns:

float ( float ) –

The width of the bounding box.

init

__init__(
    x: float, y: float, width: float, height: float
) -> None

Create a new bounding box representation given the coordinates [xc, yc, width, height] or [xmin, ymin, width, height] of the bounding box. The coordinates should be normalized to the image dimensions.

Parameters:

x (float) –

The normalized x-center or xmin coordinate of the bounding box.
y (float) –

The normalized y-center or ymin coordinate of the bounding box.
width (float) –

The normalized width of the bounding box.
height (float) –

The normalized height of the bounding box.

Box3d

The Box3d is a representation of a single 3D bounding box annotation which is based in meters. The bounding boxes are float32 values containing the fields [x, y, z, width, height, depth]. This follows the convention for the Sensor Coordinate Frame where the x-axis is forward, y-axis is left, and z-axis is up.

cx `property`

cx: float

The x-coordinate of the box center (forward direction).

Returns:

float ( float ) –

The x-coordinate in meters.

cy `property`

cy: float

The y-coordinate of the box center (left direction).

Returns:

float ( float ) –

The y-coordinate in meters.

cz `property`

cz: float

The z-coordinate of the box center (up direction).

Returns:

float ( float ) –

The z-coordinate in meters.

front `property`

front: float

The front coordinate of the bounding box along the x-axis.

Returns:

float ( float ) –

The front coordinate in meters.

height `property`

height: float

The height of the bounding box along the z-axis.

Returns:

float ( float ) –

The height in meters.

left `property`

left: float

The left coordinate of the bounding box along the y-axis.

Returns:

float ( float ) –

The left coordinate in meters.

length `property`

length: float

The length of the bounding box along the x-axis.

Returns:

float ( float ) –

The length in meters.

top `property`

top: float

The top coordinate of the bounding box along the z-axis.

Returns:

float ( float ) –

The top coordinate in meters.

width `property`

width: float

The width of the bounding box along the y-axis.

Returns:

float ( float ) –

The width in meters.

init

__init__(
    cx: float,
    cy: float,
    cz: float,
    width: float,
    height: float,
    length: float,
) -> None

Initialize a 3D bounding box with the given position and dimensions.

Parameters:

cx (float) –

The x-coordinate of the box center (forward).
cy (float) –

The y-coordinate of the box center (left).
cz (float) –

The z-coordinate of the box center (up).
width (float) –

The width of the box along the y-axis.
height (float) –

The height of the box along the z-axis.
length (float) –

The length of the box along the x-axis.

ChangelogEntry

A single entry in the dataset changelog, recording one modification.

change_data `property`

change_data: Any

The change details as a Python object (dict, list, or primitive).

created_at `property`

created_at: str

ISO 8601 timestamp of when this change was recorded.

dataset_id `property`

dataset_id: DatasetID

The dataset this entry belongs to.

entity_id `property`

entity_id: Optional[int]

The optional entity ID affected by this change.

entity_type `property`

entity_type: str

The entity type (image, annotation, label, etc.).

id `property`

id: int

The unique identifier for this changelog entry.

message `property`

message: str

Optional message associated with this change.

operation `property`

operation: str

The operation (create, update, delete, etc.).

organization_id `property`

organization_id: int

The organization ID.

s3_version_ids `property`

s3_version_ids: List[Any]

S3 version IDs associated with this change.

serial `property`

serial: int

The monotonic serial number for this change.

username `property`

username: str

The username that made this change.

ChangelogResponse

Paginated response from the version changelog endpoint.

continue_token `property`

continue_token: str

Token to pass for the next page of results.

count `property`

count: int

Total number of entries matching the query.

entries `property`

entries: List[ChangelogEntry]

The changelog entries in this page.

from_serial `property`

from_serial: Optional[int]

The starting serial number of the query range.

to_serial `property`

to_serial: Optional[int]

The ending serial number of the query range.

Client

Main client for interacting with EdgeFirst Studio Server.

The EdgeFirst Client handles the connection to the EdgeFirst Studio Server and manages authentication, RPC calls, and data operations. It provides methods for managing projects, datasets, experiments, training sessions, and various utility functions for data processing.

The client supports multiple authentication methods and can work with both SaaS and self-hosted EdgeFirst Studio instances.

Features

Authentication: Token-based authentication with automatic persistence
Dataset Management: Upload, download, and manipulate datasets
Project Operations: Create and manage projects and experiments
Training & Validation: Submit and monitor ML training jobs
Data Integration: Convert between EdgeFirst datasets and popular formats
Progress Tracking: Real-time progress updates for long-running operations

Examples:

Basic client setup and authentication:

>>> # Create a new client and authenticate (builder pattern)
>>> client = Client().with_login("your-email@example.com", "password")

>>> # Or use an existing token
>>> client = Client().with_token("your-token-here")

>>> # Get organization and list projects
>>> org = client.organization()
>>> projects = client.projects()  # Returns all projects
>>> filtered = client.projects("project-name")  # Filter by name

>>> # Work with datasets
>>> dataset = client.dataset("ds-abc123")
>>> datasets = client.datasets()  # List all datasets

See also

Repository examples: examples/01_authentication.py (auth), examples/04_polars_dataframe.py (DataFrames), examples/06_create_annotations.py (populate_samples).

Note

The client also provides various utility methods for interacting with datasets and converting them to and from Polars DataFrames.

server `property`

server: str

Return the server name for the current client.

Extracts the server name from the client's URL: - https://edgefirst.studio → "saas" - https://test.edgefirst.studio → "test" - https://{name}.edgefirst.studio → "{name}"

Returns:

str ( str ) –

The server name (e.g., "saas", "test", "stage").

token_expiration `property`

token_expiration: datetime

Return the expiration date of the token used to authenticate the client with the server.

Returns:

datetime ( datetime ) –

The expiration date of the token.

url `property`

url: str

Return the server URL associated with the current client.

Returns:

str ( str ) –

The server URL associated with the current client.

username `property`

username: str

Return the username associated with the current client.

Returns:

str ( str ) –

The username associated with the current client.

Raises:

Error –

If the username cannot be accessed.

init

__init__(
    token: Optional[str] = None,
    username: Optional[str] = None,
    password: Optional[str] = None,
    server: Optional[str] = None,
    use_token_file: bool = True,
) -> None

Create a new EdgeFirst client instance. The client has a few options for authentication. A token can be provided directly to the client which is used to authenticate the client with the server and includes the server instance information. Alternatively, a username and password can be provided to the client along with an optional server otherwise the default of "saas" is used. If none of these options are provided the client will use the local user's configuration file to read the last saved token unless the use_token_file parameter is set to false.

Parameters:

token (Optional[str], default: None ) –

The authentication token for the client. If provided, this is used to authenticate the client with the server.
username (Optional[str], default: None ) –

The username to log in to Studio.
password (Optional[str], default: None ) –

The password to log in to Studio.
server (Optional[str], default: None ) –

The server to connect to. If not provided, the default server "saas" is used.
use_token_file (bool, default: True ) –

Whether to use the local token file for authentication if no token, username, or password is provided. Defaults to true.

See also

After edgefirst-client login, Client() loads the cached token automatically. See examples/01_authentication.py.

add_annotations_bulk

add_annotations_bulk(
    annotation_set_id: AnnotationSetUID,
    annotations: List[ServerAnnotation],
) -> List[dict]

Add annotations in bulk to an existing annotation set.

Unlike populate_samples, this edits already-uploaded samples in place via annotation.add_bulk — each ServerAnnotation must reference an existing image_id.

Parameters:

annotation_set_id (AnnotationSetUID) –

The annotation set to add annotations to.
annotations (List[ServerAnnotation]) –

Server-format annotations to add.

Returns:

List[dict] –

List[dict]: The created annotation records from the server.

Example

label_id is required for the server to resolve the label;

label_name/label_index alone are not honored.

label_ids = { ... label.name: label.id ... for label in client.labels(dataset_id) ... } ann = ServerAnnotation( ... annotation_type="box", x=0.1, y=0.1, w=0.2, h=0.2, ... score=1.0, image_id=sample_id.value, ... annotation_set_id=annset_id.value, ... label_id=label_ids["circle"], label_name="circle", ... ) client.add_annotations_bulk(annset_id, [ann])

add_label

add_label(
    dataset_id: DatasetUID,
    name: str,
    index: Optional[int] = None,
) -> None

Add a label to the dataset, optionally preserving its source index.

When index is None, the server assigns the next available label_index. When set, the index is pinned via a two-pass label.update — use this to preserve COCO category_id or other non-contiguous source indices across upload/download round-trips.

Parameters:

dataset_id (DatasetUID) –

The dataset identifier (string, int, or DatasetID object).
name (str) –

Label name, must be unique within the dataset.
index (int, default: None ) –

Source-faithful label_index to assign. Defaults to None (server-assigned).

Raises:

Error –

If the requested index is already held by a different label.

Example

client.add_label(dataset_id, "person") client.add_label(dataset_id, "car", index=3)

add_labels

add_labels(
    dataset_id: DatasetUID,
    names: List[str],
    indices: Optional[List[Optional[int]]] = None,
) -> None

Add multiple labels in one request, optionally assigning source-faithful indices.

When indices is None, creates all labels with server-assigned indices in a single label.add2 request. When provided, each label is created then its index pinned via a two-pass label.update. Existing labels are skipped without error. The two-pass strategy avoids collisions when labels within the same batch would swap positions.

Parameters:

dataset_id (DatasetUID) –

The dataset identifier (string, int, or DatasetID object).
names (List[str]) –

Label names to create.
indices (List[Optional[int]], default: None ) –

Parallel list of label_index values. Must have the same length as names when provided. Use None entries to let the server assign specific labels. Defaults to None (all server-assigned).

Raises:

Error –

If indices length differs from names, or if any requested index conflicts with an existing unrelated label.

Example

client.add_labels(dataset_id, ["person", "car", "truck"]) client.add_labels(dataset_id, ["person", "car"], ... indices=[1, 3]) client.add_labels(dataset_id, ["a", "b"], indices=[None, 5])

annotation_set

annotation_set(
    annotation_set_id: AnnotationSetUID,
) -> AnnotationSet

Retrieve the annotation set with the specified ID.

Parameters:

annotation_set_id (AnnotationSetUID) –

Annotation set ID.

Returns:

AnnotationSet ( AnnotationSet ) –

The requested annotation set.

annotation_sets

annotation_sets(
    dataset_id: DatasetUID, version: Optional[str] = None
) -> List[AnnotationSet]

Retrieve the annotation sets associated with the specified dataset.

Parameters:

dataset_id (Union[DatasetID, int, str]) –

Dataset ID.
version (Optional[str], default: None ) –

Optional version tag name to query annotation sets at that point in time.

Returns:

List[AnnotationSet] –

List[AnnotationSet]: Annotation sets associated with the dataset.

annotations

annotations(
    annotation_set_id: AnnotationSetUID,
    groups: List[str] = [],
    annotation_types: List[AnnotationType] = [],
    progress: Optional[Progress] = None,
    version: Optional[str] = None,
) -> List[Annotation]

Get the annotations for the specified annotation set with the requested annotation types. The annotation types are used to filter the annotations returned. The groups parameter is used to filter for dataset groups (train, val, test). Images which do not have any annotations are also included in the result as long as they are in the requested groups (when specified).

The result is a vector of Annotations objects which contain the full dataset along with the annotations for the specified types.

To get the annotations as a DataFrame, use the samples_dataframe method instead.

Parameters:

annotation_set_id (AnnotationSetUID) –

The ID of the annotation set.
groups (List[str], default: [] ) –

Dataset groups to include.
annotation_types (List[AnnotationType], default: [] ) –

Types of annotations to include.
progress (Optional[Progress], default: None ) –

Optional progress callback. Supports: - callback(current, total) - basic progress - callback(current, total, status) - with status message (v2.8.0+)
version (Optional[str], default: None ) –

Optional version tag name to query annotations at that point in time.

Progress

Reports progress with status=None as samples are fetched and processed for their annotations. Progress unit is samples processed.

Returns:

List[Annotation] –

List[Annotation]: List of annotations.

artifacts

artifacts(
    training_session_id: TrainingSessionUID,
) -> List[Artifact]

List the artifacts for the specified training session. The artifacts are returned as a vector of strings.

Parameters:

training_session_id (TrainingSessionUID) –

The training session ID.

Returns:

List[Artifact] –

List[Artifact]: A list of artifact objects generated by the session.

Raises:

Error –

If the request fails.

backfill_sample_dimensions

backfill_sample_dimensions(
    dataset_id: DatasetUID,
    progress: Optional[Progress] = None,
) -> int

Backfill missing image dimensions for a dataset.

Downloads images for samples missing width/height, extracts dimensions, and updates the server with the computed values.

This is a one-time repair operation for legacy datasets uploaded before the client extracted dimensions at upload time. Samples that already have width/height are skipped; samples whose image URL is unavailable, returns a non-success HTTP status, or cannot be parsed as a recognized image format are skipped silently.

Parameters:

dataset_id (Union[DatasetID, int, str]) –

ID of the dataset.
progress (Optional[Progress], default: None ) –

Optional progress callback. Supports: - callback(current, total) - basic progress - callback(current, total, status) - with status message

The total reported is the number of samples missing dimensions (not the full dataset size). status is the literal string "Computing dimensions".

Returns:

int ( int ) –

Number of samples whose dimensions were updated. May be less than the progress total when some samples were skipped (missing URL, download failure, unparseable image).

Example

from edgefirst_client import Client client = Client() updated = client.backfill_sample_dimensions( ... "ds-12345", ... lambda curr, total, status: print( ... f"[{curr}/{total}] {status}" ... ), ... ) print(f"Backfilled {updated} samples")

create_annotation_set

create_annotation_set(
    dataset_id: DatasetUID,
    name: str,
    description: Optional[str] = None,
) -> str

Create a new annotation set for the specified dataset.

Parameters:

dataset_id (Union[DatasetID, int, str]) –

ID of the dataset to create the annotation set in.
name (str) –

Name of the new annotation set.
description (Optional[str], default: None ) –

Optional description for the annotation set. Defaults to None.

Returns:

str ( str ) –

Annotation set ID of the newly created annotation set.

create_dataset

create_dataset(
    project_id: str,
    name: str,
    description: Optional[str] = None,
) -> str

Create a new dataset in the specified project.

Parameters:

project_id (str) –

ID of the project to create the dataset in.
name (str) –

Name of the new dataset.
description (Optional[str], default: None ) –

Optional description for the dataset. Defaults to None.

Returns:

str ( str ) –

Dataset ID of the newly created dataset.

create_snapshot

create_snapshot(
    path: str, progress: Optional[Progress] = None
) -> Snapshot

Create a new snapshot from an MCAP file or EdgeFirst Dataset directory.

Parameters:

path (str) –

Local path to an MCAP file or a directory containing EdgeFirst Dataset Format files (Arrow/ZIP pairs).
progress (Optional[Progress], default: None ) –
Optional callback. Signatures supported:
- callback(current, total)
- callback(current, total, status) (v2.8.0+)
Units are bytes. status is always None for this operation (single-phase byte-level progress).

Returns:

Snapshot ( Snapshot ) –

The created snapshot with ID, description, status, and creation timestamp.

Raises:

Error –

If the path does not exist, the format is invalid, or the upload fails.

Example

snapshot = client.create_snapshot( ... "data.mcap", ... lambda cur, tot, s: print(f"{cur}/{tot} bytes — {s}") ... )

create_snapshot_edgefirst_format

create_snapshot_edgefirst_format(
    arrow_path: str,
    zip_path: str,
    description: str | None = None,
    progress: Optional[Progress] = None,
) -> Snapshot

Create a snapshot directly from EdgeFirst Dataset Format files.

Uploads an Arrow annotations file and a ZIP media archive as a new snapshot. This is faster than create_snapshot when you already have EDF files and want to avoid MCAP conversion.

Parameters:

arrow_path (str) –

Local path to the .arrow annotations file.
zip_path (str) –

Local path to the .zip media archive.
description (str | None, default: None ) –

Optional snapshot description. Defaults to the Arrow file stem if not provided.
progress (Optional[Progress], default: None ) –
Optional callback. Signatures supported:
- callback(current, total)
- callback(current, total, status) (v2.8.0+)
Units are bytes (combined across both files). status is always None for this operation (single-phase byte-level progress).

Returns:

Snapshot ( Snapshot ) –

The created snapshot with ID, description, status, and creation timestamp.

Raises:

Error –

If either file does not exist, the format is invalid, or the upload fails.

Example

snapshot = client.create_snapshot_edgefirst_format( ... "dataset.arrow", ... "dataset.zip", ... description="Training batch 42", ... progress=lambda c, t, s: print(f"{c}/{t} bytes — {s}"), ... )

create_snapshot_from_dataset

create_snapshot_from_dataset(
    dataset_id: DatasetUID,
    description: str,
    annotation_set_id: AnnotationSetUID | None = None,
) -> "SnapshotFromDatasetResult"

Create a snapshot from an existing dataset on the server.

Triggers server-side snapshot generation which exports the dataset's images and annotations into a downloadable EdgeFirst Dataset Format.

This is the inverse of restore_snapshot - while restore creates a dataset from a snapshot, this method creates a snapshot from a dataset.

Parameters:

dataset_id (DatasetUID) –

The dataset ID to create snapshot from.
description (str) –

Description for the created snapshot.
annotation_set_id (AnnotationSetUID | None, default: None ) –

Optional annotation set ID. If not provided, uses the "annotations" set or first available.

Returns:

SnapshotFromDatasetResult ( 'SnapshotFromDatasetResult' ) –

Result containing the snapshot ID and task ID for monitoring progress.

Raises:

Error –

If the dataset doesn't exist, user lacks permission, or the request fails.

Example

client = Client() result = client.create_snapshot_from_dataset( ... "ds-12345", "My Backup" ... ) print(f"Created snapshot: {result.id}") if result.task_id: ... # Monitor the creation task ... client.task(result.task_id, monitor=True)

dataset

dataset(dataset_id: DatasetUID) -> Dataset

Return the dataset with the specified dataset ID. If the dataset does not exist, an error is returned.

Parameters:

dataset_id (DatasetUID) –

The ID of the dataset.

Returns:

Dataset ( Dataset ) –

The requested dataset.

Raises:

Error –

If the dataset does not exist or cannot be accessed.

dataset_tags

dataset_tags(dataset_id: DatasetUID) -> List[Tag]

List the legacy free-form tags for a dataset.

Unrelated to dataset version tags — see version_tag_list for the dataset-versioning tag feature.

Parameters:

dataset_id (DatasetUID) –

The dataset identifier (string, int, or DatasetID).

Returns:

List[Tag] –

List[Tag]: The dataset's tags, creation-ordered (highest id
List[Tag] –

newest).

datasets

datasets(
    project_id: ProjectUID, name: Optional[str] = None
) -> List[Dataset]

Returns a list of datasets available to the user. The datasets are returned as a vector of Dataset objects. If a name is provided, only datasets with that name are returned.

Parameters:

project_id (ProjectUID) –

The project ID whose datasets to get.
name (Optional[str], default: None ) –

The name of the dataset to filter by.

Returns:

List[Dataset] –

List[Dataset]: A list of datasets.

delete_annotation_set

delete_annotation_set(
    annotation_set_id: AnnotationSetUID,
) -> None

Delete an annotation set by marking it as deleted.

Parameters:

annotation_set_id (Union[AnnotationSetID, int, str]) –

ID of the annotation set to delete.

delete_annotations_bulk

delete_annotations_bulk(
    annotation_set_id: AnnotationSetUID,
    annotation_types: List[str],
    sample_ids: List[SampleUID],
) -> None

Delete annotations in bulk from an existing annotation set.

Parameters:

annotation_set_id (AnnotationSetUID) –

The annotation set to delete annotations from.
annotation_types (List[str]) –

Annotation types to delete (e.g. ["box", "seg"]).
sample_ids (List[SampleUID]) –

The samples whose annotations of the given types should be deleted.

delete_dataset

delete_dataset(dataset_id: DatasetUID) -> None

Delete a dataset by marking it as deleted.

Parameters:

dataset_id (Union[DatasetID, int, str]) –

ID of the dataset to delete.

delete_samples

delete_samples(
    dataset_id: DatasetUID, sample_ids: List[SampleUID]
) -> None

Delete one or more samples (images) from a dataset.

Annotations belonging to the deleted samples are removed automatically by the server (cascade delete) — no separate step is needed. The underlying RPC is asynchronous on the server: it returns once the request is accepted, before the delete has actually completed. Callers needing to observe the effect must poll samples()/samples_count().

Parameters:

dataset_id (DatasetUID) –

The dataset the samples belong to.
sample_ids (List[SampleUID]) –

Sample IDs (image IDs) to delete.

delete_snapshot

delete_snapshot(snapshot_id: SnapshotUID) -> None

Delete a snapshot from EdgeFirst Studio.

Permanently removes a snapshot and its associated data. This operation cannot be undone.

Parameters:

snapshot_id (SnapshotUID) –

The snapshot ID to delete.

Raises:

Error –

If the snapshot doesn't exist, user lacks permission, or the request fails.

delete_training_sessions

delete_training_sessions(
    session_ids: List[TrainingSessionUID],
) -> None

Delete one or more training sessions (Studio trainer.session.delete).

The server cascades this delete: validation sessions attached to the deleted training sessions are removed as well, along with artifacts and checkpoints.

Parameters:

session_ids (List[TrainingSessionUID]) –

Sessions to remove; each accepts the data:TrainingSessionUID typing.

Raises:

Error –

If a session id cannot be resolved or the request fails.

delete_validation_sessions

delete_validation_sessions(
    session_ids: List[ValidationSessionUID],
) -> None

Delete one or more validation sessions (Studio validate.session.delete).

Idempotent against already-deleted ids on the server side. Only the validation sessions are removed; the parent training session is never affected.

Parameters:

session_ids (List[ValidationSessionUID]) –

Sessions to remove; each accepts the data:ValidationSessionUID typing.

Raises:

Error –

PermissionDenied if the caller lacks the TrainerWrite permission on at least one session.

download

download(url: str) -> bytes

Download raw bytes from an absolute URL.

Parameters:

url (str) –

Absolute URL (must start with "http://" or "https://").

Returns:

bytes ( bytes ) –

The downloaded content.

Raises:

Error –

If the URL is not absolute, or the request fails.

download_artifact

download_artifact(
    training_session_id: TrainingSessionUID,
    modelname: str,
    filename: Optional[Union[str, Path]] = None,
    progress: Optional[Progress] = None,
) -> None

Download the model artifact for the specified trainer session to the specified file path. A progress callback can be provided to monitor the progress of the download over a watch channel.

Parameters:

training_session_id (TrainingSessionUID) –

ID of the trainer session the model belongs to.
modelname (str) –

Name of the model file to download.
filename (Optional[Union[str, Path]], default: None ) –

Local file path to save the downloaded artifact. Accepts a str or pathlib.Path. If not specified, the modelname is used as the filename.
progress (Optional[Progress], default: None ) –

Optional progress callback.

Progress

Reports progress with status=None as file data is received. Progress unit is bytes downloaded. Total is determined from the HTTP Content-Length header (may be 0 if server doesn't provide it).

Raises:

Error –

If the download fails or cannot be written to disk.

download_checkpoint

download_checkpoint(
    training_session_id: TrainingSessionUID,
    checkpoint: str,
    filename: Optional[Union[str, Path]] = None,
    progress: Optional[Progress] = None,
) -> None

Download the checkpoint file for the specified trainer session to the specified file path. A progress callback can be provided to monitor the progress of the download over a watch channel.

Parameters:

training_session_id (TrainingSessionUID) –

ID of the trainer session the checkpoint belongs to.
checkpoint (str) –

Name of the checkpoint file to download.
filename (Optional[Union[str, Path]], default: None ) –

Local file path to save the downloaded checkpoint. Accepts a str or pathlib.Path. If not specified, the checkpoint name is used as the filename.
progress (Optional[Progress], default: None ) –

Optional progress callback.

Progress

Reports progress with status=None as file data is received. Progress unit is bytes downloaded. Total is determined from the HTTP Content-Length header (may be 0 if server doesn't provide it).

Raises:

Error –

If the download fails or cannot be written to disk.

download_dataset

download_dataset(
    dataset_id: DatasetUID,
    groups: List[str] = [],
    types: List[FileType] = [FileType.Image],
    output: str = ".",
    flatten: bool = False,
    progress: Optional[Progress] = None,
    version: Optional[str] = None,
) -> None

Download dataset samples matching specified groups and file types.

Parameters:

dataset_id (Union[DatasetID, int, str]) –

ID of the dataset.
groups (List[str], default: [] ) –

Dataset groups to include (train, val, etc).
types (List[FileType], default: [Image] ) –

File types to download.
output (str, default: '.' ) –

Output directory to save downloaded files.
flatten (bool, default: False ) –

Download all files to output root without sequence subdirectories. When True, filenames are automatically prefixed with sequence name and optionally frame number (when available) to avoid conflicts. Default: False (preserves sequence directory structure).
progress (Optional[Progress], default: None ) –

Optional progress callback. Supports: - callback(current, total) - basic progress - callback(current, total, status) - with status message (v2.8.0+)
version (Optional[str], default: None ) –

Optional version tag name to download files from a specific tagged state instead of HEAD.

Progress

This operation has two phases with distinct progress reporting:

Fetching metadata (status=None): Retrieves sample information from the server. Progress counts samples fetched.
Downloading files (status="Downloading"): Downloads actual files to disk. Progress counts samples completed.

Applications should detect the status change to reset their progress bar for the second phase.

Raises:

RuntimeError –

If types includes FileType.Image and a matched sample has a registered image but no fetchable image URL for it (a dataset integrity problem). Samples with no image at all (e.g. lidar-only or radar-only captures) are unaffected.

See also

examples/05_download_dataset.py and CLI download-dataset.

download_snapshot

download_snapshot(
    snapshot_id: SnapshotUID,
    output: str,
    progress: Optional[Progress] = None,
) -> None

Download a snapshot from EdgeFirst Studio to local storage.

Parameters:

snapshot_id (SnapshotUID) –

The snapshot ID to download (e.g., "ss-abc123").
output (str) –

Local directory path to save the downloaded files.
progress (Optional[Progress], default: None ) –
Optional callback. Signatures supported:
- callback(current, total)
- callback(current, total, status) (v2.8.0+)
Units are bytes. status is always None for this operation (single-phase byte-level progress). Providing a progress callback does not affect timeout configuration.

Timeout: Snapshot downloads use the bulk HTTP client with an idle per-chunk EDGEFIRST_READ_TIMEOUT (default 120 seconds). Bytes arriving reset the timer, so healthy large downloads are not interrupted. If the connection can stall longer than that idle window, set EDGEFIRST_READ_TIMEOUT (integer seconds) before creating the client, e.g. EDGEFIRST_READ_TIMEOUT=600. Do not raise EDGEFIRST_TIMEOUT for snapshot downloads — that env var only applies to fast metadata API calls.

Raises:

Error –

If the snapshot does not exist, the download fails, or the request times out.

Example

client.download_snapshot( ... "ss-abc123", ... "./output", ... lambda cur, tot, s: print(f"{cur}/{tot} bytes"), ... )

experiment

experiment(experiment_id: ExperimentUID) -> Experiment

Return the experiment with the specified experiment ID. If the experiment does not exist, an error is returned.

Parameters:

experiment_id (ExperimentUID) –

The ID of the experiment to fetch.

Returns:

Experiment ( Experiment ) –

The Experiment object corresponding to the given ID.

Raises:

Error –

If the experiment does not exist or request fails.

experiments

experiments(
    project_id: ProjectUID, name: Optional[str] = None
) -> List[Experiment]

Returns a list of experiments available to the user. The experiments are returned as a vector of Experiment objects. Experiments provide a method of organizing training and validation sessions together and are akin to an Experiment in MLFlow terminology. Each experiment can have multiple trainer sessions associated with it, these would be akin to runs in MLFlow terminology.

Parameters:

project_id (ProjectUID) –

The project ID for which to list experiments.
name (Optional[str], default: None ) –

The name of the experiment to filter by.

Returns:

List[Experiment] –

List[Experiment]: A list of Experiment objects associated with the project.

Raises:

Error –

If the server request fails.

get_or_create_group

get_or_create_group(
    dataset_id: DatasetUID, name: str
) -> int

Get an existing group by name or create a new one.

This method is idempotent: calling it multiple times with the same name returns the same group ID. This makes it safe to use in concurrent workflows without coordination between workers.

Parameters:

dataset_id (DatasetUID) –

The dataset identifier. Can be a string ID, integer, or DatasetID object.
name (str) –

The group name (e.g., "train", "val", "test"). Group names are case-sensitive and must be unique within the dataset.

Returns:

int ( int ) –

The group ID, which can be passed to :meth:set_sample_group_id.

Raises:

Error –

If the dataset does not exist or the group cannot be created.

Examples:

Create groups for a typical train/val/test split:

>>> train_id = client.get_or_create_group(dataset_id, "train")
>>> val_id = client.get_or_create_group(dataset_id, "val")
>>> test_id = client.get_or_create_group(dataset_id, "test")

Idempotent behavior - safe to call multiple times:

>>> id1 = client.get_or_create_group(dataset_id, "train")
>>> id2 = client.get_or_create_group(dataset_id, "train")
>>> assert id1 == id2  # Same ID returned

Assign samples after creating groups:

>>> train_id = client.get_or_create_group(dataset_id, "train")
>>> for sample in training_samples:
...     client.set_sample_group_id(sample.id, train_id)

See Also

groups: List all groups for a dataset. set_sample_group_id: Assign a sample to a group.

groups

groups(dataset_id: DatasetUID) -> List[Group]

List all groups for a dataset.

Groups organize samples into logical subsets such as "train", "val", and "test". This method retrieves all groups that have been created for the specified dataset.

Parameters:

dataset_id (DatasetUID) –

The dataset identifier. Can be a string ID, integer, or DatasetID object.

Returns:

List[Group] –

List[Group]: All groups associated with this dataset. Returns an empty list if no groups have been created.

Raises:

Error –

If the dataset does not exist or cannot be accessed.

Examples:

List all groups in a dataset:

>>> groups = client.groups(dataset_id)
>>> for group in groups:
...     print(f"{group.name} (id={group.id})")
train (id=1)
val (id=2)
test (id=3)

Check if a specific group exists:

>>> groups = client.groups(dataset_id)
>>> group_names = [g.name for g in groups]
>>> if "train" in group_names:
...     print("Training group exists")

See Also

get_or_create_group: Create or retrieve a group by name. Group: The group class with id and name properties.

job_run

job_run(
    app_name: str,
    job_name: str,
    env: Optional[Dict[str, str]] = None,
    data: Optional[Dict[str, Parameter]] = None,
) -> Job

Launch a job (app run) on EdgeFirst Studio.

Parameters:

app_name (str) –

The app code to run (e.g. "edgefirst-validator").
job_name (str) –

A user-supplied label for this job run.
env (Optional[Dict[str, str]], default: None ) –

Optional environment variables to pass to the job.
data (Optional[Dict[str, Parameter]], default: None ) –

Optional data parameters for the job (arbitrary JSON via Parameter).

Returns:

Job ( Job ) –

The full job record returned by the server (BK_BATCH wrapper),
Job –

including AWS Batch job ID, state, and the linked task ID. Call
Job –

.task_id() on the result to obtain a TaskID for use with
Job –

client.task_info(task_id).

Raises:

RuntimeError –

If the server rejects the request.

job_stop

job_stop(task_id: TaskUID) -> None

Request that a running job task be stopped.

Parameters:

task_id (Union[TaskID, int, str]) –

The task ID of the job to stop (from job_run or jobs).

Raises:

RuntimeError –

If the server rejects the request.

jobs

jobs(name: Optional[str] = None) -> List[Job]

List job (app-run) entries visible to the authenticated user.

Parameters:

name (Optional[str], default: None ) –

Optional substring filter applied client-side against each job's job_name.

Returns:

List[Job] –

List[Job]: Jobs visible to the current user.

Raises:

RuntimeError –

If the server returns an error.

labels

labels(
    dataset_id: DatasetUID, version: Optional[str] = None
) -> List[Label]

Get the labels associated with the dataset.

Parameters:

dataset_id (DatasetUID) –

The dataset identifier.
version (Optional[str], default: None ) –

Optional version tag name to query labels at that point in time. When omitted, returns labels at HEAD.

Returns:

List[Label] –

List[Label]: Labels defined for the dataset.

logout

logout() -> None

Logout from the server and clear the stored token.

Clears both the in-memory token and any persisted token in storage. After calling this method, the client will need to authenticate again before making API calls that require authentication.

Examples:

>>> client = Client().with_login("user@example.com", "password")
>>> client.logout()  # Token is cleared from memory and storage

organization

organization() -> Organization

Return the organization associated with the current user. The organization is the top-level entity in EdgeFirst Studio and contains projects, datasets, trainers, and trainer sessions.

Returns:

Organization ( Organization ) –

The organization associated with the current user.

Raises:

Error –

If the organization cannot be accessed.

populate_samples

populate_samples(
    dataset_id: DatasetUID,
    annotation_set_id: AnnotationSetUID,
    samples: List[Sample],
    progress: Optional[Progress] = None,
) -> List[SamplesPopulateResult]

Populate samples into a dataset with automatic file uploads.

This method creates new samples in the specified dataset and automatically uploads their associated files (images, LiDAR, etc.) to S3 using presigned URLs.

The server will auto-generate UUIDs and extract image dimensions for samples that don't have them specified.

Parameters:

dataset_id (DatasetUID) –

ID of the dataset to populate
annotation_set_id (AnnotationSetUID) –

ID of the annotation set for sample annotations
samples (List[Sample]) –

List of Sample objects to create (with files and annotations)
progress (Optional[Progress], default: None ) –

Optional progress callback. Supports two signatures: - callback(current, total) - basic progress - callback(current, total, status) - with status message (v2.8.0+)

Progress

Reports progress with status=None as each sample's files are uploaded. Progress unit is samples (not individual files). Each sample may contain multiple files (image, lidar, radar, etc.) which are all uploaded before the sample is counted as complete.

Returns:

List[SamplesPopulateResult] –

List[SamplesPopulateResult]: List of results with UUIDs and presigned URLs

Example

from edgefirst_client import ( ... Client, Sample, SampleFile, Annotation, Box2d ... ) client = Client() sample = Sample() sample.set_image_name("test.png") sample.add_file(SampleFile("image", "path/to/test.png")) annotation = Annotation() annotation.set_label("car") annotation.set_box2d(Box2d(10.0, 20.0, 100.0, 50.0)) sample.add_annotation(annotation) results = client.populate_samples( ... dataset_id, ... annotation_set_id, ... [sample], ... lambda curr, total: print(f"{curr}/{total}") ... )

See also

examples/06_create_annotations.py.

populate_samples_with_concurrency

populate_samples_with_concurrency(
    dataset_id: DatasetUID,
    samples: List[Sample],
    annotation_set_id: AnnotationSetUID | None = None,
    progress: Optional[Progress] = None,
    concurrency: int | None = None,
) -> List[SamplesPopulateResult]

Populate samples with configurable upload concurrency.

Identical to populate_samples but exposes the concurrency knob that controls how many S3 file uploads run in parallel. The default (None) uses the server-side maximum (32).

Also accepts an optional annotation_set_id (vs. required in populate_samples).

Parameters:

dataset_id (DatasetUID) –

Target dataset.
samples (List[Sample]) –

List of Sample objects to create.
annotation_set_id (AnnotationSetUID | None, default: None ) –

Optional annotation set for sample annotations.
progress (Optional[Progress], default: None ) –
Optional callback. Signatures supported:
- callback(current, total)
- callback(current, total, status) (v2.8.0+)
Unit is samples (not bytes). status is always None for this operation.
concurrency (int | None, default: None ) –

Max parallel S3 uploads. None uses the default (32). Lower values reduce memory pressure on constrained hosts.

Returns:

List[SamplesPopulateResult] –

List[SamplesPopulateResult]: Results with UUIDs and presigned URLs.

Raises:

Error –

If the dataset does not exist or upload fails.

Example

results = client.populate_samples_with_concurrency( ... "ds-12345", ... samples, ... concurrency=8, ... progress=lambda cur, tot, s: print(f"{cur}/{tot} — {s}") ... )

project

project(project_id: ProjectUID) -> Project

Return the project with the specified project ID. If the project does not exist, an error is returned.

Parameters:

project_id (ProjectUID) –

The ID of the project to retrieve.

Returns:

Project ( Project ) –

The requested project.

Raises:

Error –

If the project does not exist or cannot be accessed.

projects

projects(name: Optional[str] = None) -> List[Project]

Returns a list of projects available to the user. The projects are returned as a vector of Project objects. If the name parameter is provided, only projects containing the specified name will be returned.

Projects are the top-level organizational unit in EdgeFirst Studio. Projects contain datasets, trainers, and trainer sessions. Projects are used to group related datasets and trainers together.

Parameters:

name (Optional[str], default: None ) –

The name of the project to filter by.

Returns:

List[Project] –

List[Project]: A list of accessible projects.

remove_label

remove_label(label_id: int) -> None

Remove a label from the dataset.

renew_token

renew_token()

Renew the token used to authenticate the client with the server. This method is used to extend the expiration time of the token. If the token is invalid or expired, the server will return an error and the client will need to login again.

Raises:

Error –

If the token is invalid or expired.

restore_snapshot

restore_snapshot(
    project_id: ProjectUID,
    snapshot_id: SnapshotUID,
    topics: List[str],
    autolabel: List[str],
    autodepth: bool,
    dataset_name: Optional[str] = None,
    dataset_description: Optional[str] = None,
) -> "SnapshotRestoreResult"

Restore a snapshot to a dataset in EdgeFirst Studio with optional AGTG.

Restores a snapshot (MCAP file or EdgeFirst Dataset) into a dataset in the specified project. For MCAP files, supports:

AGTG (Automatic Ground Truth Generation): Automatically annotate detected objects
Auto-depth: Generate depthmaps (Maivin/Raivin cameras only)
Topic filtering: Select specific MCAP topics to restore

Parameters:

project_id (ProjectUID) –

Target project ID.
snapshot_id (SnapshotUID) –

Snapshot ID to restore.
topics (List[str]) –

MCAP topics to include (empty = all topics).
autolabel (List[str]) –

Object labels for AGTG (empty = no auto-annotation).
autodepth (bool) –

Generate depthmaps (Maivin/Raivin only).
dataset_name (Optional[str], default: None ) –

Optional custom dataset name.
dataset_description (Optional[str], default: None ) –

Optional dataset description.

Returns:

SnapshotRestoreResult ( 'SnapshotRestoreResult' ) –

Result with the new dataset ID and status.

Raises:

Error –

If snapshot or project doesn't exist, or restoration fails.

Example

client = Client() result = client.restore_snapshot( ... "p-1", ... "ss-abc123", ... [], # All topics ... ["person", "car"], # AGTG labels ... True, # Auto-depth ... "Highway Dataset", ... "Collected on I-95", ... ) print(f"Restored to dataset: {result.dataset_id}")

sample_names

sample_names(
    dataset_id: DatasetUID,
    groups: List[str] = [],
    progress: Optional[Progress] = None,
    version: Optional[str] = None,
) -> set[str]

Return the set of sample names in a dataset.

Names are normalised (file extension stripped). This is a lightweight alternative to samples() when only names are needed.

Parameters:

dataset_id (DatasetUID) –

Dataset to query.
groups (List[str], default: [] ) –

Optional list of group names to filter by. Defaults to all groups.
progress (Optional[Progress], default: None ) –
Optional callback. Signatures supported:
- callback(current, total)
- callback(current, total, status) (v2.8.0+)
Units are sample count. status is always None for this operation.
version (Optional[str], default: None ) –

Optional version tag name to query sample names at that point in time. When omitted, returns names at HEAD.

Returns:

set[str] –

set[str]: Set of normalised sample names.

Raises:

Error –

If the dataset does not exist or the request fails.

Example

names = client.sample_names( ... "ds-12345", ... groups=["train"], ... progress=lambda cur, tot, s: print(f"{cur}/{tot} — {s}") ... ) print(len(names))

samples

samples(
    dataset_id: DatasetUID,
    annotation_set_id: Optional[AnnotationSetUID] = None,
    annotation_types: List[AnnotationType] = [],
    groups: List[str] = [],
    types: List[FileType] = [FileType.Image],
    progress: Optional[Progress] = None,
    version: Optional[str] = None,
) -> List[Sample]

Retrieve sample metadata and annotations for a dataset.

Parameters:

dataset_id (Union[DatasetID, int, str]) –

ID of the dataset.
annotation_set_id (AnnotationSetUID, default: None ) –

The ID of the annotation set to fetch.
annotation_types (List[AnnotationType], default: [] ) –

Types of annotations to include.
groups (List[str], default: [] ) –

Dataset groups to include.
types (List[FileType], default: [Image] ) –

Type of files to include.
progress (Optional[Progress], default: None ) –

Optional progress callback. Supports: - callback(current, total) - basic progress - callback(current, total, status) - with status message (v2.8.0+)
version (Optional[str], default: None ) –

Optional version tag name to query samples at that point in time.

Progress

Reports progress with status=None as samples are fetched from the server in paginated batches. Progress unit is samples fetched.

Returns:

List[Sample] –

List[Sample]: A list of sample objects.

samples_count

samples_count(
    dataset_id: DatasetUID,
    annotation_set_id: Optional[AnnotationSetUID] = None,
    annotation_types: List[AnnotationType] = [],
    groups: List[str] = [],
    types: List[FileType] = [FileType.Image],
    version: Optional[str] = None,
) -> SamplesCountResult

Count samples in a dataset without fetching them.

This method returns only the total count of samples matching the specified criteria, which is much faster than fetching all samples when you only need to know how many exist.

Parameters:

dataset_id (Union[DatasetID, int, str]) –

ID of the dataset.
annotation_set_id (AnnotationSetUID, default: None ) –

The ID of the annotation set to filter by.
annotation_types (List[AnnotationType], default: [] ) –

Types of annotations to include.
groups (List[str], default: [] ) –

Dataset groups to include.
types (List[FileType], default: [Image] ) –

Type of files to include.
version (Optional[str], default: None ) –

Optional version tag name to count samples at that point in time.

Returns:

SamplesCountResult ( SamplesCountResult ) –

Object with total count of matching samples.

samples_dataframe

samples_dataframe(
    dataset_id: DatasetUID,
    annotation_set_id: Optional[AnnotationSetUID] = None,
    groups: List[str] = [],
    annotation_types: List[AnnotationType] = [],
    progress: Optional[Progress] = None,
    version: Optional[str] = None,
) -> DataFrame

Get samples as a DataFrame with complete 2025.10 schema.

This method returns a DataFrame with 13 columns following the EdgeFirst Dataset Format 2025.10 specification, including optional metadata columns (size, location, pose, degradation) that may be populated from sample sensor data.

Parameters:

dataset_id (Union[DatasetID, int, str]) –

ID of the dataset.
annotation_set_id (AnnotationSetUID, default: None ) –

Optional annotation set filter.
groups (List[str], default: [] ) –

Dataset groups to include.
annotation_types (List[AnnotationType], default: [] ) –

Types of annotations to include.
progress (Optional[Progress], default: None ) –

Optional progress callback. Supports: - callback(current, total) - basic progress - callback(current, total, status) - with status message (v2.8.0+)
version (Optional[str], default: None ) –

Optional version tag name to fetch samples at that point in time instead of HEAD.

Progress

Reports progress with status=None as samples are fetched from the server in paginated batches. Progress unit is samples fetched.

Returns:

DataFrame ( DataFrame ) –

A Polars DataFrame with 13 columns (name, frame, object_id, label, label_index, group, mask, box2d, box3d, size, location, pose, degradation).

See also

CLI download-annotations exports Arrow for polars.read_ipc. examples/04_polars_dataframe.py.

save_token

save_token() -> None

Persist the current authentication token to the configured storage.

The token is written using the client's configured storage backend. When no custom storage has been configured, the token is saved to an OS-appropriate default location determined at runtime. Use :class:FileTokenStorage to discover the default path for the current platform rather than hard-coding it.

Raises:

Error –

If the token cannot be written to storage.

Example

client = Client().with_login("user@example.com", "password") client.save_token()

set_sample_group_id

set_sample_group_id(
    sample_id: SampleUID, group_id: int
) -> None

Set the group for a sample.

Assigns a sample to a group, replacing any existing group assignment. Each sample can belong to at most one group at a time.

Parameters:

sample_id (SampleUID) –

The sample identifier. Can be a string ID, integer, or SampleID object.
group_id (int) –

The group ID to assign. Obtain this from :meth:get_or_create_group or from a :class:Group object's id property.

Raises:

Error –

If the sample or group does not exist.

Examples:

Assign a sample to the training group:

>>> train_id = client.get_or_create_group(dataset_id, "train")
>>> client.set_sample_group_id(sample_id, train_id)

Batch assign samples to groups:

>>> train_id = client.get_or_create_group(dataset_id, "train")
>>> val_id = client.get_or_create_group(dataset_id, "val")
>>>
>>> for sample in samples[:800]:  # 80% for training
...     client.set_sample_group_id(sample.id, train_id)
>>> for sample in samples[800:]:  # 20% for validation
...     client.set_sample_group_id(sample.id, val_id)

See Also

get_or_create_group: Create or retrieve a group by name. groups: List all groups for a dataset.

set_stages

set_stages(
    task_id: TaskUID, stages: List[Tuple[str, str]]
) -> None

Configures the task stages. Stages are used to show various steps in the task execution process.

Parameters:

task_id (Union[TaskID, int, str]) –

The ID of the task to update.
stages (List[Tuple[str, str]]) –

A list of (name, description) tuples representing the new stages for the task.

Returns:

None –

None

Raises:

Error –

If the task does not exist or the request fails.

snapshot

snapshot(snapshot_id: SnapshotUID) -> Snapshot

Returns the snapshot with the specified ID.

Parameters:

snapshot_id (SnapshotUID) –

The snapshot ID.

Returns:

Snapshot ( Snapshot ) –

The snapshot object.

Raises:

Error –

If the snapshot does not exist or the request fails.

snapshots

snapshots() -> List[Snapshot]

Returns a list of all snapshots available to the user.

Returns:

List[Snapshot] –

List[Snapshot]: A list of snapshot objects.

Raises:

Error –

If the request fails.

start_training_session

start_training_session(
    project_id: ProjectUID,
    name: str,
    experiment_id: ExperimentUID,
    trainer_type: str,
    dataset_id: DatasetUID,
    annotation_set_id: AnnotationSetUID,
    params: Dict[str, Any] = {},
    tag_name: Optional[str] = None,
    train_group: Optional[str] = None,
    val_group: Optional[str] = None,
    session_name: Optional[str] = None,
    session_description: Optional[str] = None,
    weights_session: Optional[TrainingSessionUID] = None,
    is_local: bool = False,
    is_kubernetes: bool = False,
) -> "NewTrainingSession"

Launch a new training session (Studio cloud.server.start).

The session trains on a single dataset using group-based train/validation splits. tag_name defaults to the dataset's latest tag (it is an error if the dataset has no tags and no tag is named); train_group / val_group default to the dataset's standard train / val groups.

Pass is_local=True to create a user-managed session: the DB row is created but no cloud instance is provisioned — the caller runs the training loop and uploads artifacts/metrics. Cleanup is via meth:delete_training_sessions.

Parameters:

project_id (ProjectUID) –

Project owning the experiment and dataset.
name (str) –

Name for the training task.
experiment_id (ExperimentUID) –

Experiment the session belongs to.
trainer_type (str) –

Trainer schema type from meth:trainer_schemas (e.g. "modelpack").
dataset_id (DatasetUID) –

Dataset to train on.
annotation_set_id (AnnotationSetUID) –

Annotation set providing the ground-truth labels.
params (Dict[str, Any], default: {} ) –

Trainer hyperparameters keyed by schema parameter name; see meth:trainer_schema.
tag_name (Optional[str], default: None ) –

Dataset tag to train against; defaults to the latest tag.
train_group (Optional[str], default: None ) –

Training split group name; defaults to "train".
val_group (Optional[str], default: None ) –

Validation split group name; defaults to "val".
session_name (Optional[str], default: None ) –

Optional display name for the session.
session_description (Optional[str], default: None ) –

Optional session description.
weights_session (Optional[TrainingSessionUID], default: None ) –

Optional source training session for transfer-learning weights.
is_local (bool, default: False ) –

True for a user-managed session with no cloud provisioning.
is_kubernetes (bool, default: False ) –

True to schedule onto the organization's Kubernetes runner.

Returns:

NewTrainingSession ( 'NewTrainingSession' ) –

Backing task id and the freshly-minted
'NewTrainingSession' –

TrainingSessionID.

Raises:

Error –

InvalidParameters if the dataset has no tags and no tag_name was provided; PermissionDenied if the caller can't write to the target project.

start_validation_session

start_validation_session(
    project_id: ProjectUID,
    name: str,
    training_session_id: TrainingSessionUID,
    model_file: str,
    val_type: str,
    params: Dict[str, Any] = {},
    is_local: bool = False,
    is_kubernetes: bool = False,
    description: Optional[str] = None,
    dataset_id: Optional[DatasetUID] = None,
    annotation_set_id: Optional[AnnotationSetUID] = None,
    snapshot_id: Optional[SnapshotUID] = None,
) -> "NewValidationSession"

Create a new validation session (Studio cloud.server.start).

Pass is_local=True to create a user-managed session: the DB row is created and the session is fully usable for data uploads / downloads / metric updates, but no EC2 instance is provisioned and no automated validator pipeline runs. That is the mode the integration tests use — the caller is responsible for cleanup via meth:delete_validation_sessions.

Parameters:

project_id (ProjectUID) –

Project that owns the new session.
name (str) –

Session display name.
training_session_id (TrainingSessionUID) –

Source training session (the session being validated).
model_file (str) –

Path/name of the model artifact relative to the training session's artifacts.
val_type (str) –

Validator schema name, e.g. "modelpack".
params (Dict[str, Any], default: {} ) –

Inner params.params dict the validator schema consumes; pass an empty dict for the default config.
is_local (bool, default: False ) –

True for a user-managed session with no cloud EC2/Kubernetes provisioning.
is_kubernetes (bool, default: False ) –

True to route the session to a Kubernetes worker pool instead of EC2.
description (Optional[str], default: None ) –

Optional session description.
dataset_id (Optional[DatasetUID], default: None ) –

Validation dataset id (one of dataset_id+ annotation_set_id or snapshot_id is required).
annotation_set_id (Optional[AnnotationSetUID], default: None ) –

Annotation set on the dataset to validate against.
snapshot_id (Optional[SnapshotUID], default: None ) –

Snapshot id (alternative to dataset_id/ annotation_set_id when the validator runs against a frozen snapshot).

Returns:

NewValidationSession ( 'NewValidationSession' ) –

Backing task id and the freshly-minted
'NewValidationSession' –

ValidationSessionID.

Raises:

Error –

RpcError(101, ...) if a referenced entity is missing; PermissionDenied if the caller can't write to the target project.

task_info

task_info(task_id: TaskUID) -> TaskInfo

Returns detailed information about a specific task.

Parameters:

task_id (Union[TaskID, int, str]) –

The ID of the task to retrieve.

Returns:

TaskInfo ( TaskInfo ) –

The TaskInfo object containing detailed information.

Raises:

Error –

If the task does not exist or the request fails.

task_status

task_status(task_id: TaskUID, status: str) -> Task

Updates the task status.

Parameters:

task_id (Union[TaskID, int, str]) –

The ID of the task to update.
status (str) –

The new status to set for the task.

Returns:

Task ( Task ) –

The updated Task object.

Raises:

Error –

If the task does not exist or the request fails.

tasks

tasks(
    name: Optional[str] = None,
    workflow: Optional[str] = None,
    status: Optional[str] = None,
    manager: Optional[str] = None,
) -> List[Task]

Returns a list of tasks available to the user. The tasks are returned as a vector of Task objects. Tasks represent some workflow within EdgeFirst Studio such as trainer or validation sessions. The managers represent where the task is run such as cloud, or user-managed, or kubernetes for on-premise installations.

Parameters:

name (Optional[str], default: None ) –

Task name filter (client-side substring).
workflow (Optional[str], default: None ) –

Workflow type filter. Values: "trainer", "validation", "snapshot-create", "snapshot-restore", "copyds", "upload", "auto-ann", "auto-seg", "aigt", "import", "export", "convertor", "twostage".
status (Optional[str], default: None ) –

Status filter ("running", "complete", etc).
manager (Optional[str], default: None ) –

Manager filter ("aws", "user", etc).

Returns:

List[Task] –

List[Task]: A list of Task objects.

Raises:

Error –

If the server request fails.

token

token() -> str

Return the token used to authenticate the client with the server. When logging into the server using a username and password, the token is returned by the server and stored in the client for future interactions.

Returns:

str ( str ) –

The token used to authenticate the client with the server.

trainer_schema

trainer_schema(schema_type: str) -> List[SchemaField]

Fetch the parameter schema for a specific trainer type.

The returned fields describe the hyperparameters the trainer accepts — names, defaults, ranges and nested groups — which map onto the params dict of meth:start_training_session.

Parameters:

schema_type (str) –

Trainer schema type from meth:trainer_schemas.

Returns:

List[SchemaField] –

List[SchemaField]: The parameter field descriptors.

Raises:

Error –

If the schema type is unknown or the request fails.

trainer_schemas

trainer_schemas() -> List[TrainerSchemaInfo]

List the trainer types available on the server.

Pass a returned schema_type to meth:trainer_schema for the full parameter schema, or to meth:start_training_session when launching.

Returns:

List[TrainerSchemaInfo] –

List[TrainerSchemaInfo]: The trainer type catalog.

Raises:

Error –

If the request fails.

training_session

training_session(
    training_session_id: TrainingSessionUID,
) -> TrainingSession

Return the training session with the specified training session ID. If the training session does not exist, an error is returned.

Parameters:

training_session_id (TrainingSessionUID) –

The training session ID.

Returns:

TrainingSession ( TrainingSession ) –

The training session with the specified ID.

Raises:

Error –

If the session does not exist or the request fails.

training_sessions

training_sessions(
    experiment_id: ExperimentUID, name: Optional[str] = None
) -> List[TrainingSession]

Returns a list of trainer sessions available to the user. The trainer sessions are returned as a vector of TrainingSession objects. Trainer sessions are akin to runs in MLFlow terminology. These represent an actual training session which will produce metrics and model artifacts.

Parameters:

experiment_id (ExperimentUID) –

The ID of the experiment.
name (Optional[str], default: None ) –

The name of the trainer session to filter by.

Returns:

List[TrainingSession] –

List[TrainingSession]: A list of trainer sessions under the experiment.

Raises:

Error –

If the request fails.

update_label

update_label(label: Label) -> None

Update the properties of a label.

Parameters:

label (Label) –

The label to update with modified properties.

Raises:

Error –

If the label does not exist or cannot be updated.

update_sample_dimensions

update_sample_dimensions(
    dataset_id: DatasetUID,
    updates: List[tuple[SampleUID, int, int]],
) -> int

Update image dimensions for existing samples in a dataset.

Use this when you already know the width and height for each sample (for example, from a sidecar manifest or from a local scan of the image files). To compute dimensions from the server-hosted images, use backfill_sample_dimensions instead.

Updates are sent to the server in batches of 500 via the samples.update_dimensions JSON-RPC method.

Parameters:

dataset_id (Union[DatasetID, int, str]) –

ID of the dataset.
updates (List[tuple[SampleUID, int, int]]) –

List of (sample_id, width, height) tuples where sample_id is a SampleUID/int/str and width/height are pixel dimensions.

Returns:

int ( int ) –

Number of samples successfully updated.

Example

from edgefirst_client import Client client = Client() updates = [ ... ("smpl-abc123", 1920, 1080), ... ("smpl-def456", 1280, 720), ... ] updated = client.update_sample_dimensions( ... "ds-12345", updates ... ) print(f"Updated {updated} samples")

update_stage

update_stage(
    task_id: TaskUID,
    stage: str,
    status: str,
    message: str,
    percentage: int,
) -> None

Updates a specific stage of a task.

Parameters:

task_id (Union[TaskID, int, str]) –

The ID of the task to update.
stage (str) –

The name of the stage to update.
status (str) –

The new status of the stage.
message (str) –

A message describing the current state of the stage.
percentage (int) –

The completion percentage of the stage (0-100).

Returns:

None –

None

Raises:

Error –

If the task or stage does not exist or the request fails.

update_training_session

update_training_session(
    session_id: TrainingSessionUID,
    name: Optional[str] = None,
    description: Optional[str] = None,
) -> TrainingSession

Update the name and/or description of a training session.

Fields left as None are not modified; at least one must be provided.

Parameters:

session_id (TrainingSessionUID) –

The training session to update.
name (Optional[str], default: None ) –

New session name.
description (Optional[str], default: None ) –

New session description.

Returns:

TrainingSession ( TrainingSession ) –

The refreshed session after the update.

Raises:

Error –

InvalidParameters when both name and description are None (no request is made); PermissionDenied if the caller lacks the TrainerWrite permission on the session.

update_validation_session

update_validation_session(
    session_id: ValidationSessionUID,
    name: Optional[str] = None,
    description: Optional[str] = None,
) -> ValidationSession

Update the name and/or description of a validation session.

Fields left as None are not modified; at least one must be provided. Renaming a validation session also renames its associated background task on the server.

Parameters:

session_id (ValidationSessionUID) –

The validation session to update.
name (Optional[str], default: None ) –

New session name.
description (Optional[str], default: None ) –

New session description.

Returns:

ValidationSession ( ValidationSession ) –

The refreshed session after the update.

Raises:

Error –

InvalidParameters when both name and description are None (no request is made); PermissionDenied if the caller lacks the TrainerWrite permission on the session.

usage_summary

usage_summary() -> UsageSummary

Get the billing usage summary for the authenticated organization.

Returns:

UsageSummary ( UsageSummary ) –

Credits, funds, and total spendable balance.

validation_session

validation_session(
    session_id: ValidationSessionUID,
) -> ValidationSession

Return the validation session with the specified ID.

Parameters:

session_id (ValidationSessionUID) –

The validation session ID.

Returns:

ValidationSession ( ValidationSession ) –

The validation session with the specified ID.

Raises:

Error –

If the validation session does not exist or the request fails.

validation_sessions

validation_sessions(
    project_id: ProjectUID,
) -> List[ValidationSession]

Returns a list of validation sessions associated with the specified project.

Parameters:

project_id (ProjectUID) –

The project ID to retrieve validation sessions for.

Returns:

List[ValidationSession] –

List[ValidationSession]: A list of validation session objects.

Raises:

Error –

If the request fails.

validator_schemas

validator_schemas() -> List[ValidatorSchema]

List the validator schemas available on the server.

Each schema carries its parameter field descriptors inline; select the schema whose schema_type matches the model's trainer type.

Returns:

List[ValidatorSchema] –

List[ValidatorSchema]: The validator schema catalog.

Raises:

Error –

If the request fails.

verify_token

verify_token()

Verify the token used to authenticate the client with the server. This method is used to ensure that the token is still valid and has not expired. If the token is invalid, the server will return an error and the client will need to login again.

Raises:

Error –

If the token is invalid or expired.

version

version() -> str

Return the version of the EdgeFirst Studio server for the current client connection.

Returns:

str ( str ) –

The version of the server.

version_changelog

version_changelog(
    dataset_id: DatasetUID,
    from_version: Optional[str] = None,
    to_version: Optional[str] = None,
    entity_types: Optional[List[str]] = None,
    limit: Optional[int] = None,
    continue_token: Optional[str] = None,
) -> ChangelogResponse

Get the changelog for a dataset between two versions.

Returns a paginated list of changelog entries describing every modification to the dataset in the specified range.

Parameters:

dataset_id (DatasetUID) –

The dataset identifier.
from_version (Optional[str], default: None ) –

Optional starting version tag name (None = beginning).
to_version (Optional[str], default: None ) –

Optional ending version tag name (None = current).
entity_types (Optional[List[str]], default: None ) –

Optional filter for entity types (e.g., ["image", "annotation"]).
limit (Optional[int], default: None ) –

Optional limit on the number of entries per page.
continue_token (Optional[str], default: None ) –

Optional continuation token for pagination.

Returns:

ChangelogResponse ( ChangelogResponse ) –

Paginated changelog entries with continuation support.

Example

changelog = client.version_changelog( ... dataset.id, ... from_version="v1.0", ... to_version="v2.0", ... ) for entry in changelog.entries: ... print(f"{entry.operation} {entry.entity_type}")

version_changelog_count

version_changelog_count(
    dataset_id: DatasetUID,
    from_version: Optional[str] = None,
    to_version: Optional[str] = None,
    entity_types: Optional[List[str]] = None,
) -> int

Get the count of changelog entries between two versions.

Parameters:

dataset_id (DatasetUID) –

The dataset identifier.
from_version (Optional[str], default: None ) –

Optional starting version tag name.
to_version (Optional[str], default: None ) –

Optional ending version tag name.
entity_types (Optional[List[str]], default: None ) –

Optional filter for entity types.

Returns:

int ( int ) –

The number of changelog entries matching the criteria.

version_current

version_current(
    dataset_id: DatasetUID,
) -> VersionCurrentResponse

Get the current version information for a dataset.

Returns the current serial number, all tags, and an optional summary of the dataset's current state.

Parameters:

dataset_id (DatasetUID) –

The dataset identifier.

Returns:

VersionCurrentResponse ( VersionCurrentResponse ) –

Current version state including serial, tags, and summary.

Example

current = client.version_current(dataset.id) print(f"Serial: {current.current_serial}") if current.latest_tag: ... print(f"Latest tag: {current.latest_tag.name}")

version_summary

version_summary(dataset_id: DatasetUID) -> DatasetSummary

Get the version summary for a dataset.

Returns cached metrics about the dataset's current state including image count, annotation counts, and label count.

Parameters:

dataset_id (DatasetUID) –

The dataset identifier.

Returns:

DatasetSummary ( DatasetSummary ) –

Summary metrics for the dataset.

version_summary_recalculate

version_summary_recalculate(
    dataset_id: DatasetUID,
) -> DatasetSummary

Recalculate the version summary for a dataset.

Forces a fresh calculation of all dataset metrics. Use this if the cached summary appears stale.

Parameters:

dataset_id (DatasetUID) –

The dataset identifier.

Returns:

DatasetSummary ( DatasetSummary ) –

Freshly calculated summary metrics.

version_tag_create

version_tag_create(
    dataset_id: DatasetUID,
    name: str,
    description: Optional[str] = None,
) -> VersionTag

Create a new version tag for a dataset.

A version tag captures the current changelog serial and records dataset metrics (image count, annotation counts, etc.) at the time of creation.

Parameters:

dataset_id (DatasetUID) –

The dataset identifier.
name (str) –

The name for the version tag (e.g., "v1.0").
description (Optional[str], default: None ) –

Optional description for the tag.

Returns:

VersionTag ( VersionTag ) –

The newly created version tag.

Example

tag = client.version_tag_create(dataset.id, "v1.0", ... description="Initial release")

version_tag_delete

version_tag_delete(
    dataset_id: DatasetUID, name: str
) -> str

Delete a version tag.

Parameters:

dataset_id (DatasetUID) –

The dataset identifier.
name (str) –

The name of the version tag to delete.

Returns:

str ( str ) –

Confirmation message.

Raises:

Error –

If the tag does not exist.

version_tag_get

version_tag_get(
    dataset_id: DatasetUID, name: str
) -> VersionTag

Get a specific version tag by name.

Parameters:

dataset_id (DatasetUID) –

The dataset identifier.
name (str) –

The name of the version tag to retrieve.

Returns:

VersionTag ( VersionTag ) –

The requested version tag.

Raises:

Error –

If the tag does not exist.

version_tag_list

version_tag_list(
    dataset_id: DatasetUID,
) -> List[VersionTag]

List all version tags for a dataset.

Parameters:

dataset_id (DatasetUID) –

The dataset identifier.

Returns:

List[VersionTag] –

List[VersionTag]: All version tags, ordered by serial.

version_tag_restore

version_tag_restore(
    dataset_id: DatasetUID, name: str
) -> RestoreResult

Restore a dataset to the state at a specific version tag.

This creates new changelog entries that undo changes made after the tag was created, effectively rolling back the dataset.

Parameters:

dataset_id (DatasetUID) –

The dataset identifier.
name (str) –

The name of the version tag to restore to.

Returns:

RestoreResult ( RestoreResult ) –

Details of the restore operation including counts of restored entities.

Example

result = client.version_tag_restore(dataset.id, "v1.0") print(f"Restored {result.restored_counts_images} images")

with_login

with_login(username: str, password: str) -> 'Client'

Returns a new client authenticated with the specified credentials.

This is a builder-style alternative to calling login() after creating the client. The token is stored in the configured storage.

Parameters:

username (str) –

The username to log in to EdgeFirst Studio.
password (str) –

The password to log in to EdgeFirst Studio.

Returns:

'Client' –

A new Client authenticated with the specified credentials.

Raises:

RuntimeError –

If authentication fails.

Examples:

>>> client = (Client()
...     .with_server("test")
...     .with_login("user@example.com", "password"))

with_memory_storage

with_memory_storage() -> 'Client'

Returns a new client with in-memory token storage (no persistence).

Tokens stored in memory are lost when the application exits. This is useful for testing or when persistence is handled externally.

Returns:

'Client' –

A new Client with memory-only token storage.

Examples:

>>> client = (
...     Client()
...     .with_memory_storage()
...     .with_login("user@example.com", "password")
... )
>>> # Token is stored in memory only, not persisted to disk

with_no_storage

with_no_storage() -> 'Client'

Returns a new client with no token storage.

Tokens are not persisted and the client starts without any stored token. Use this when you want full control over token management.

Returns:

'Client' –

A new Client with no token storage.

Examples:

>>> client = Client().with_no_storage()

with_server

with_server(server: str) -> 'Client'

Returns a new client connected to the specified server instance.

The server parameter is an instance name that maps to a URL:

"" or "saas" → https://edgefirst.studio (default)
"test" → https://test.edgefirst.studio
"stage" → https://stage.edgefirst.studio
"dev" → https://dev.edgefirst.studio
"{name}" → https://{name}.edgefirst.studio

Server Selection Priority

Token's server (highest) - JWT tokens encode their server.
with_server() - Used when logging in or no token exists.
Default "saas" - If no token and no server specified.

Important

If a token is already set, calling this method will drop it as tokens are server-specific. Use parse_token_server() to check a token's server before calling this method.

Parameters:

server (str) –

The server instance name.

Returns:

'Client' –

A new Client configured for the specified server.

Examples:

>>> client = Client().with_server("test")
>>> print(client.url)  # https://test.edgefirst.studio

with_storage

with_storage(
    storage: Union[
        FileTokenStorage, MemoryTokenStorage, Any
    ],
) -> "Client"

Returns a new client with the specified token storage backend.

Use this to configure custom token storage, such as platform-specific secure storage (iOS Keychain, Android EncryptedSharedPreferences).

The storage can be a built-in storage class (FileTokenStorage, MemoryTokenStorage) or any Python object that implements the storage protocol with store(token: str), load() -> Optional[str], and clear() methods.

Parameters:

storage (Union[FileTokenStorage, MemoryTokenStorage, Any]) –

The token storage backend to use.

Returns:

'Client' –

A new Client configured with the specified storage.

Examples:

Using built-in storage:

>>> storage = FileTokenStorage.with_path("/custom/path/token")
>>> client = Client().with_storage(storage)

Using custom Python storage:

>>> class MyStorage:
...     def __init__(self):
...         self._token = None
...     def store(self, token):
...         self._token = token
...     def load(self):
...         return self._token
...     def clear(self):
...         self._token = None
>>> client = Client().with_storage(MyStorage())

with_token

with_token(token: str) -> 'Client'

Returns a new client authenticated with the specified token.

This is a builder-style way to provide an existing authentication token. The token is stored in the configured storage.

Parameters:

token (str) –

The authentication token.

Returns:

'Client' –

A new Client authenticated with the specified token.

Examples:

>>> client = Client().with_token("eyJ...")

with_url

with_url(url: str) -> 'Client'

Returns a new client pointed at an explicit URL.

Parameters:

url (str) –

Full base URL (e.g. "https://studio.example.com").

Returns:

Client ( 'Client' ) –

A new client connected to the specified URL.

Raises:

Error –

If the URL is malformed or insecure (plain http:// to a non-loopback host).

Example

client = Client().with_url("https://studio.example.com")

Dataset

A dataset in EdgeFirst Studio containing sensor data and annotations.

Datasets are collections of multi-modal sensor data (images, LiDAR, radar) along with their corresponding annotations (bounding boxes, segmentation masks, 3D annotations). Datasets belong to projects and can be used for training and validation of machine learning models.

Features

Multi-modal Data: Support for images, LiDAR point clouds, radar data
Rich Annotations: 2D/3D bounding boxes, segmentation masks
Metadata: Timestamps, sensor configurations, calibration data
Version Control: Track changes and maintain data lineage
Format Conversion: Export to popular ML frameworks

Examples:

Basic dataset operations:

>>> # Get dataset information
>>> dataset = client.dataset("ds-abc123")
>>> print(f"Dataset: {dataset.name}")
>>> print(f"Created: {dataset.created}")
>>> print(f"Description: {dataset.description}")

>>> # Access dataset contents through client
>>> samples = client.samples(dataset.id)
>>> annotations = client.annotation_sets(dataset.id)

>>> # Manage dataset labels
>>> dataset.add_label(client, "training")
>>> labels = dataset.labels(client)

Note

The dataset class represents a dataset in EdgeFirst Studio. A dataset is a collection of sensor data such as images, lidar, radar along with annotations for bounding boxes, masks, or 3d bounding boxes.

created `property`

created: datetime

The creation date of the dataset.

description `property`

description: str

The description of the dataset.

id `property`

id: DatasetID

The ID of the dataset.

name `property`

name: str

The name of the dataset.

tag `property`

tag: str

The name of this dataset's current version tag, or an empty string if none is set.

tag_description `property`

tag_description: str

The description of this dataset's current version tag, or an empty string if none is set.

tag_id `property`

tag_id: Optional[int]

The ID of this dataset's current version tag, if one has been set (via tag creation or restore).

uid `property`

uid: str

The unique string identifier for the object.

.. deprecated:: Use str(Dataset.id) instead. This property will be removed in a future version.

add_label

add_label(name: str, index: Optional[int] = None) -> None

add_label(client: Client, name: str) -> None

add_label(
    name_or_client: Union[str, Client],
    name: Optional[str] = None,
    index: Optional[int] = None,
) -> None

Add a label to the dataset.

annotation_sets

annotation_sets(
    version: Optional[str] = None,
) -> List[AnnotationSet]

Get annotation sets for this dataset.

Parameters:

version (Optional[str], default: None ) –

Optional version tag name to query annotation sets at that point in time.

Returns:

List[AnnotationSet] –

List[AnnotationSet]: Annotation sets for this dataset.

Raises:

TypeError –

If dataset has no client reference.

Example

annotation_sets = dataset.annotation_sets() annotation_sets_v1 = dataset.annotation_sets(version="v1.0")

create_annotation_set

create_annotation_set(
    name: str, description: Optional[str] = None
) -> str

Create a new annotation set in this dataset.

Requires an embedded client reference (datasets returned by the client methods automatically have one).

Parameters:

name (str) –

Name for the new annotation set.
description (Optional[str], default: None ) –

Optional description for the annotation set.

Returns:

str ( str ) –

The ID of the newly created annotation set (e.g., "as-abc123").

Raises:

TypeError –

If dataset has no client reference. Use client.create_annotation_set(dataset.id, name) instead.

Example

as_id = dataset.create_annotation_set("my-annotations")

delete

delete() -> None

Delete this dataset.

Requires an embedded client reference (datasets returned by the client methods automatically have one).

Raises:

TypeError –

If dataset has no client reference. Use client.delete_dataset(dataset.id) instead.

Example

dataset.delete()

delete_samples

delete_samples(sample_ids: List[SampleUID]) -> None

Delete one or more samples (images) from this dataset.

Annotations belonging to the deleted samples are removed automatically by the server (cascade delete) — no separate step is needed. The underlying RPC is asynchronous on the server: it returns once the request is accepted, before the delete has actually completed. Callers needing to observe the effect must poll samples()/samples_count().

Requires an embedded client reference (datasets returned by the client methods automatically have one).

Parameters:

sample_ids (List[SampleUID]) –

Sample IDs (image IDs) to delete.

Raises:

TypeError –

If dataset has no client reference. Use client.delete_samples(dataset.id, sample_ids) instead.

Example

dataset.delete_samples([sample.id for sample in samples[:2]])

download

download(
    output: str = ".",
    groups: List[str] = ...,
    types: List[FileType] = ...,
    flatten: bool = False,
    progress: Optional[Progress] = None,
    version: Optional[str] = None,
) -> None

Download dataset files.

Downloads sample files matching the specified groups and file types. This is the recommended method for bulk downloads as it's significantly faster than downloading samples individually.

Parameters:

output (str, default: '.' ) –

Output directory path. Defaults to current directory.
groups (List[str], default: ... ) –

List of dataset groups (train, val, test, etc.).
types (List[FileType], default: ... ) –

List of file types to download. Defaults to [FileType.Image].
flatten (bool, default: False ) –

If True, download all files to output root without sequence subdirectories.
progress (Optional[Progress], default: None ) –

Optional progress callback. Supports two signatures: - callback(current, total) - basic progress - callback(current, total, status) - with status message (v2.8.0+)

Progress

This operation has two phases with distinct progress reporting:

Fetching metadata (status=None): Retrieves sample information from the server. Progress counts samples fetched.
Downloading files (status="Downloading"): Downloads actual files to disk. Progress counts samples completed.

Applications should detect the status change to reset their progress bar for the second phase.

Raises:

TypeError –

If dataset has no client reference.
RuntimeError –

If types includes FileType.Image and a matched sample has a registered image but no fetchable image URL for it (a dataset integrity problem). Samples with no image at all (e.g. lidar-only or radar-only captures) are unaffected.

Example

dataset.download("./data", ["train"], [FileType.Image])

groups

groups() -> List[Group]

List groups for this dataset.

Groups organize samples into splits such as "train", "val", and "test".

Requires an embedded client reference (datasets returned by the client methods automatically have one).

Returns:

List[Group] –

List[Group]: Groups in this dataset.

Raises:

TypeError –

If dataset has no client reference. Use client.groups(dataset.id) instead.

Example

for group in dataset.groups(): ... print(group.name, group.id)

labels

labels(*, version: Optional[str] = None) -> List[Label]

labels(
    client: Client, version: Optional[str] = None
) -> List[Label]

labels(
    client: Optional[Client] = None,
    version: Optional[str] = None,
) -> List[Label]

Get labels for this dataset.

remove_label

remove_label(name: str) -> None

remove_label(client: Client, name: str) -> None

remove_label(
    name_or_client: Union[str, Client],
    name: Optional[str] = None,
) -> None

Remove a label from the dataset.

samples

samples(
    annotation_set_id: Optional[AnnotationSetUID] = None,
    annotation_types: List[AnnotationType] = [],
    groups: List[str] = [],
    types: List[FileType] = [FileType.Image],
    progress: Optional[Progress] = None,
    version: Optional[str] = None,
) -> List[Sample]

Get samples for this dataset.

Parameters:

annotation_set_id (Optional[AnnotationSetUID], default: None ) –

Optional annotation set filter.
annotation_types (List[AnnotationType], default: [] ) –

List of annotation types to filter.
groups (List[str], default: [] ) –

List of dataset groups (train, val, test).
types (List[FileType], default: [Image] ) –

List of file types. Defaults to [FileType.Image].
progress (Optional[Progress], default: None ) –

Optional progress callback. Supports two signatures: - callback(current, total) - basic progress - callback(current, total, status) - with status message (v2.8.0+)
version (Optional[str], default: None ) –

Optional version tag name to query samples at that point in time.

Progress

Reports progress with status=None as samples are fetched from the server in paginated batches. Progress unit is samples fetched.

Returns:

List[Sample] –

List[Sample]: Samples matching the criteria.

Raises:

TypeError –

If dataset has no client reference.

Example

samples = dataset.samples(groups=["train"]) samples_v1 = dataset.samples(version="v1.0")

samples_count

samples_count(
    annotation_set_id: Optional[AnnotationSetUID] = None,
    annotation_types: List[AnnotationType] = [],
    groups: List[str] = [],
    types: List[FileType] = [FileType.Image],
    version: Optional[str] = None,
) -> SamplesCountResult

Get samples count for this dataset.

Parameters:

annotation_set_id (Optional[AnnotationSetUID], default: None ) –

Optional annotation set filter.
annotation_types (List[AnnotationType], default: [] ) –

List of annotation types.
groups (List[str], default: [] ) –

List of dataset groups.
types (List[FileType], default: [Image] ) –

List of file types.
version (Optional[str], default: None ) –

Optional version tag name to query counts at that point in time.

Returns:

SamplesCountResult ( SamplesCountResult ) –

Count information.

Raises:

TypeError –

If dataset has no client reference.

Example

count = dataset.samples_count(groups=["train"]) count_v1 = dataset.samples_count(version="v1.0")

version_changelog

version_changelog(
    from_version: Optional[str] = None,
    to_version: Optional[str] = None,
    entity_types: Optional[List[str]] = None,
    limit: Optional[int] = None,
    continue_token: Optional[str] = None,
) -> ChangelogResponse

Get the changelog for this dataset between two versions.

Requires an embedded client reference (datasets returned by the client methods automatically have one).

Parameters:

from_version (Optional[str], default: None ) –

Optional starting version tag name.
to_version (Optional[str], default: None ) –

Optional ending version tag name.
entity_types (Optional[List[str]], default: None ) –

Optional filter for entity types.
limit (Optional[int], default: None ) –

Optional limit on the number of entries.
continue_token (Optional[str], default: None ) –

Optional continuation token for pagination.

Returns:

ChangelogResponse ( ChangelogResponse ) –

Paginated changelog entries.

Raises:

TypeError –

If dataset has no client reference. Use client.version_changelog(dataset.id, ...) instead.

Example

changelog = dataset.version_changelog(from_version="v1.0")

version_changelog_count

version_changelog_count(
    from_version: Optional[str] = None,
    to_version: Optional[str] = None,
    entity_types: Optional[List[str]] = None,
) -> int

Get the count of changelog entries for this dataset between two versions.

Requires an embedded client reference (datasets returned by the client methods automatically have one).

Parameters:

from_version (Optional[str], default: None ) –

Optional starting version tag name.
to_version (Optional[str], default: None ) –

Optional ending version tag name.
entity_types (Optional[List[str]], default: None ) –

Optional filter for entity types.

Returns:

int ( int ) –

The number of changelog entries.

Raises:

TypeError –

If dataset has no client reference. Use client.version_changelog_count(dataset.id, ...) instead.

Example

count = dataset.version_changelog_count(from_version="v1.0")

version_current

version_current() -> VersionCurrentResponse

Get the current version information for this dataset.

Requires an embedded client reference (datasets returned by the client methods automatically have one).

Returns:

VersionCurrentResponse ( VersionCurrentResponse ) –

Current version state.

Raises:

TypeError –

If dataset has no client reference. Use client.version_current(dataset.id) instead.

Example

current = dataset.version_current()

version_summary

version_summary() -> DatasetSummary

Get the version summary for this dataset.

Requires an embedded client reference (datasets returned by the client methods automatically have one).

Returns:

DatasetSummary ( DatasetSummary ) –

Summary metrics for the dataset.

Raises:

TypeError –

If dataset has no client reference. Use client.version_summary(dataset.id) instead.

Example

summary = dataset.version_summary()

version_summary_recalculate

version_summary_recalculate() -> DatasetSummary

Recalculate the version summary for this dataset.

Requires an embedded client reference (datasets returned by the client methods automatically have one).

Returns:

DatasetSummary ( DatasetSummary ) –

Recalculated summary metrics.

Raises:

TypeError –

If dataset has no client reference. Use client.version_summary_recalculate(dataset.id) instead.

Example

summary = dataset.version_summary_recalculate()

version_tag_create

version_tag_create(
    name: str, description: Optional[str] = None
) -> VersionTag

Create a new version tag for this dataset.

Requires an embedded client reference (datasets returned by the client methods automatically have one).

Parameters:

name (str) –

The name for the version tag.
description (Optional[str], default: None ) –

Optional description for the tag.

Returns:

VersionTag ( VersionTag ) –

The newly created version tag.

Raises:

TypeError –

If dataset has no client reference. Use client.version_tag_create(dataset.id, ...) instead.

Example

tag = dataset.version_tag_create( ... "v1.0", description="Initial release" ... )

version_tag_delete

version_tag_delete(name: str) -> str

Delete a version tag from this dataset.

Requires an embedded client reference (datasets returned by the client methods automatically have one).

Parameters:

name (str) –

The name of the version tag to delete.

Returns:

str ( str ) –

Confirmation message.

Raises:

TypeError –

If dataset has no client reference. Use client.version_tag_delete(dataset.id, ...) instead.

Example

dataset.version_tag_delete("v1.0")

version_tag_get

version_tag_get(name: str) -> VersionTag

Get a specific version tag by name.

Requires an embedded client reference (datasets returned by the client methods automatically have one).

Parameters:

name (str) –

The name of the version tag to retrieve.

Returns:

VersionTag ( VersionTag ) –

The requested version tag.

Raises:

TypeError –

If dataset has no client reference. Use client.version_tag_get(dataset.id, ...) instead.

Example

tag = dataset.version_tag_get("v1.0")

version_tag_list

version_tag_list() -> List[VersionTag]

List all version tags for this dataset.

Requires an embedded client reference (datasets returned by the client methods automatically have one).

Returns:

List[VersionTag] –

List[VersionTag]: All version tags for the dataset.

Raises:

TypeError –

If dataset has no client reference. Use client.version_tag_list(dataset.id) instead.

Example

for tag in dataset.version_tag_list(): ... print(tag.name, tag.serial)

version_tag_restore

version_tag_restore(name: str) -> RestoreResult

Restore this dataset to a specific version tag.

Requires an embedded client reference (datasets returned by the client methods automatically have one).

Parameters:

name (str) –

The name of the version tag to restore to.

Returns:

RestoreResult ( RestoreResult ) –

Result of the restore operation.

Raises:

TypeError –

If dataset has no client reference. Use client.version_tag_restore(dataset.id, ...) instead.

Example

result = dataset.version_tag_restore("v1.0")

DatasetID

Unique identifier for a dataset within a project.

Datasets contain collections of images, annotations, and other data used for machine learning experiments. Can be constructed from an integer, a prefixed hex string (e.g., "ds-456def"), or another DatasetID instance.

Examples:

>>> dataset_id = DatasetID("ds-456def")
>>> dataset_id = DatasetID(0x456DEF)
>>> dataset_id = DatasetID.from_str("ds-456def")
>>> int(dataset_id)
4550127
>>> str(dataset_id)
'ds-456def'

Note

Internally a DatasetID is an unsigned 64-bit integer. This class handles translating between integer and string representations of dataset IDs.

DatasetParams

Represents the parameters for a dataset used in a training session.

annotation_set_id `property`

annotation_set_id: AnnotationSetID

Returns the ID of the annotation set associated with these parameters.

Returns:

AnnotationSetID ( AnnotationSetID ) –

The annotation set ID.

dataset_id `property`

dataset_id: DatasetID

Returns the ID of the dataset associated with these parameters.

Returns:

DatasetID ( DatasetID ) –

The dataset ID.

train_group `property`

train_group: str

Returns the name of the selected training group.

Returns:

str ( str ) –

The training group name.

val_group `property`

val_group: str

Returns the name of the selected validation group.

Returns:

str ( str ) –

The validation group name.

DatasetSummary

Cached metrics summary for a dataset's current state.

annotation_counts `property`

annotation_counts: Dict[str, int]

Annotation counts by type.

annotation_set_count `property`

annotation_set_count: int

Total number of annotation sets.

current_serial `property`

current_serial: int

The current changelog serial number.

dataset_id `property`

dataset_id: DatasetID

The dataset ID.

image_count `property`

image_count: int

Total number of images.

label_count `property`

label_count: int

Total number of labels.

last_updated `property`

last_updated: str

ISO 8601 timestamp of the last summary update.

sensor_counts `property`

sensor_counts: Dict[str, int]

Sensor data counts by type.

Error

Experiment

Represents an experiment in EdgeFirst Studio which are used to organize training and validation sessions.

description `property`

description: Optional[str]

Returns the description of the experiment, if any.

Returns:

Optional[str] –

Optional[str]: The experiment description or None.

id `property`

id: ExperimentID

Returns the unique identifier of the experiment.

Returns:

ID ( ExperimentID ) –

The experiment ID.

name `property`

name: str

Returns the name of the experiment.

Returns:

str ( str ) –

The experiment name.

uid `property`

uid: str

The unique string identifier for the object.

.. deprecated:: Use str(Experiment.id) instead. This property will be removed in a future version.

training_sessions

training_sessions(
    name: Optional[str] = None,
) -> List[TrainingSession]

Get training sessions for this experiment.

Parameters:

name (Optional[str], default: None ) –

Optional filter by name.

Returns:

List[TrainingSession] –

List[TrainingSession]: Training sessions in this experiment.

Raises:

TypeError –

If experiment has no client reference.

Example

sessions = experiment.training_sessions()

ExperimentID

Unique identifier for an experiment within a project.

Experiments represent individual machine learning experiments with specific configurations, datasets, and results. Can be constructed from an integer, a prefixed hex string (e.g., "exp-456def"), or another ExperimentID instance.

Examples:

>>> exp_id = ExperimentID("exp-456def")
>>> exp_id = ExperimentID(0x456DEF)
>>> exp_id = ExperimentID.from_str("exp-456def")
>>> int(exp_id)
4550127
>>> str(exp_id)
'exp-456def'

Note

Internally an ExperimentID is an unsigned 64-bit integer. This class handles translating between integer and string representations of experiment IDs.

FileTokenStorage

File-based token storage for desktop platforms.

Stores the authentication token in a file on the local filesystem. By default, uses the platform-specific config directory:

Linux: ~/.config/EdgeFirst Studio/token
macOS: ~/Library/Application Support/ai.EdgeFirst.EdgeFirst-Studio/ token
Windows: C:\Users\<User>\AppData\Roaming\EdgeFirst\ EdgeFirst Studio\token

Examples:

Using default path:

>>> storage = FileTokenStorage()
>>> print(storage.path)  # Platform-specific default path

Using custom path:

>>> storage = FileTokenStorage.with_path("/custom/path/token")
>>> storage.store("my-token")
>>> token = storage.load()  # Returns "my-token"
>>> storage.clear()  # Removes the token file

path `property`

path: Path

Returns the path where the token is stored.

Returns:

Path –

The file path used for token storage.

init

__init__() -> None

Create a new FileTokenStorage using the default platform config directory.

Raises:

RuntimeError –

If the config directory cannot be determined.

repr

__repr__() -> str

Return a string representation of the storage.

clear

clear() -> None

Clear the stored authentication token by removing the file.

Does not raise an error if the file doesn't exist.

Raises:

RuntimeError –

If the file exists but cannot be removed.

load

load() -> Optional[str]

Load the stored authentication token from the file.

Returns:

Optional[str] –

The stored token string, or None if no token is stored.

Raises:

RuntimeError –

If the token file exists but cannot be read.

store

store(token: str) -> None

Store the authentication token to the file.

Creates parent directories if they don't exist.

Parameters:

token (str) –

The token string to store.

Raises:

RuntimeError –

If the token cannot be written.

with_path `staticmethod`

with_path(path: str) -> 'FileTokenStorage'

Create a new FileTokenStorage with a custom file path.

Parameters:

path (str) –

The file path where the token will be stored.

Returns:

'FileTokenStorage' –

A new FileTokenStorage instance using the specified path.

Examples:

>>> storage = FileTokenStorage.with_path("/tmp/my_token")
>>> storage.store("test-token")

FileType

File types supported in EdgeFirst Studio datasets.

Represents the different types of sensor data files that can be stored and processed in a dataset. EdgeFirst Studio supports various modalities including visual images and different forms of LiDAR and radar data.

Examples:

>>> # Create file types from strings
>>> image_type = FileType.Image
>>> lidar_type = FileType.LidarPcd

>>> # Use in dataset operations
>>> files_by_type = dataset.get_files_by_type(FileType.Image)

Members

Image: Standard image files (JPEG, PNG, etc.). A file with extension .image.jpeg that stores the image. LidarPcd: LiDAR point cloud data files (.pcd format). A file with extension .lidar.pcd that stores [x, y, z] Cartesian coordinates from the LiDAR sensor. LidarDepth: LiDAR depth images (.png format). A file with extension .lidar.png that stores per-pixel depth values captured by the LiDAR sensor. LidarReflect: LiDAR reflectance images (.jpg format). A file with extension .lidar.jpeg that stores reflectance data from the LiDAR sensor. RadarPcd: Radar point cloud data files (.pcd format). A file with extension .radar.pcd that stores [x, y, z] Cartesian coordinates in meters from the Radar sensor, along with speed m/s, power, noise, and radar cross-section (RCS). RadarCube: Radar cube data files (.png format). A file with extension .radar.png that stores a range-doppler radar cube. The cube has dimensions: sequence, rx_antenna, range_bins, doppler_bins — encoded in a 16-bit PNG.

All `instance-attribute`

All: 'FileType'

Download all file types. Not valid for single-file operations.

GpsData

GPS location data for a sample.

lat `property`

lat: float

Latitude in decimal degrees.

lon `property`

lon: float

Longitude in decimal degrees.

init

__init__(lat: float, lon: float) -> None

Create GPS metadata from latitude and longitude.

Raises:

ValueError –

If latitude is outside [-90, 90] or longitude is outside [-180, 180], or either value is non-finite.

Group

A dataset group for organizing samples into logical subsets.

Groups partition samples within a dataset for purposes such as training, validation, and testing. Common group names include "train", "val", and "test", following conventions from datasets like COCO and ImageNet.

Each sample can belong to at most one group. Groups are managed at the dataset level and can be created, listed, and assigned to samples through the Client.

Attributes:

id (int) –

The unique numeric identifier for this group.
name (str) –

The human-readable name of the group.

Examples:

List and inspect groups:

>>> groups = client.groups(dataset_id)
>>> for group in groups:
...     print(f"{group.name}: {group.id}")
train: 1
val: 2
test: 3

Filter samples by group:

>>> train_group = next(g for g in groups if g.name == "train")
>>> train_samples = client.samples(dataset_id, group_id=train_group.id)

See Also

Client.groups: List all groups for a dataset. Client.get_or_create_group: Create or retrieve a group by name. Client.set_sample_group_id: Assign a sample to a group.

id `property`

id: int

The unique numeric identifier for this group.

This ID is used when assigning samples to groups via :meth:Client.set_sample_group_id.

Returns:

int ( int ) –

The group's unique identifier.

name `property`

name: str

The human-readable name of the group.

Common names include "train", "val", and "test". Group names are unique within a dataset.

Returns:

str ( str ) –

The group name (e.g., "train", "val", "test").

ImageId

Unique identifier for an image in EdgeFirst Studio.

Can be constructed from an integer, a prefixed hex string (e.g., "im-4c3b2a"), or another ImageId instance.

Examples:

>>> image_id = ImageId("im-4c3b2a")
>>> image_id = ImageId(0x4C3B2A)
>>> image_id = ImageId.from_str("im-4c3b2a")
>>> int(image_id)
4995882
>>> str(image_id)
'im-4c3b2a'

Note

Internally an ImageId is an unsigned 64-bit integer. This class handles translating between integer and string representations of image IDs.

ImuData

IMU orientation data for a sample.

pitch `property`

pitch: float

Pitch angle in degrees.

roll `property`

roll: float

Roll angle in degrees.

yaw `property`

yaw: float

Yaw angle in degrees.

init

__init__(roll: float, pitch: float, yaw: float) -> None

Create IMU metadata from roll, pitch, and yaw angles.

Raises:

ValueError –

If roll/yaw are outside [-180, 180], pitch is outside [-90, 90], or any value is non-finite.

Job

A job (app run) entry returned by Client.job_run and Client.jobs.

The task_id field links back to the underlying task that can be polled via Client.task_info.

Note

The launch timestamp present on the underlying Rust Job struct is not exposed in the Python bindings. Use state to distinguish completed runs.

code `property`

code: str

App code (e.g. "edgefirst-validator:2.9.5").

Returns:

str ( str ) –

The app code.

job_id `property`

job_id: str

Cloud-batch job identifier (e.g. AWS Batch job ID). Opaque string.

Returns:

str ( str ) –

The batch job identifier.

job_name `property`

job_name: str

User-supplied job label provided at job_run time.

Returns:

str ( str ) –

The job name.

state `property`

state: str

Cloud-batch state (e.g. "RUNNING", "SUCCEEDED", "FAILED").

Returns:

str ( str ) –

The current job state.

title `property`

title: str

Display title from the app definition.

Returns:

str ( str ) –

The job title.

task_id

task_id() -> TaskID

Returns the TaskID corresponding to this job.

Use with Client.task_info to fetch the underlying task details.

Returns:

TaskID ( TaskID ) –

The task ID linked to this job.

Label

Representation of a label in EdgeFirst Studio. Labels are used to identify annotations in a dataset.

color `property`

color: Optional[int]

The label's display color as a packed RGB integer, if the server returned one. Populated on both HEAD and tag-scoped reads.

dataset_id `property`

dataset_id: Optional[DatasetID]

The ID of the dataset that the label belongs to.

None if this label was fetched via a tag-scoped query where the server omitted dataset_id and no backfill was available.

id `property`

id: int

The ID of the label.

index `property`

index: int

The index of the label.

name `property`

name: str

The name of the label.

uid `property`

uid: str

The unique string identifier for the object.

.. deprecated:: Use str(Label.id) instead. This property will be removed in a future version.

remove

remove(client: Client) -> None

Remove the label from the dataset.

set_index

set_index(client: Client, index: int) -> None

Set the index of the label.

set_name

set_name(client: Client, name: str) -> None

Set the name of the label.

MemoryTokenStorage

In-memory token storage (no persistence).

Stores the authentication token in memory only. The token is lost when the application exits. This is useful for:

Testing
Mobile platforms that use custom secure storage
Applications that don't need token persistence

Examples:

>>> storage = MemoryTokenStorage()
>>> storage.store("my-token")
>>> token = storage.load()  # Returns "my-token"
>>> storage.clear()
>>> token = storage.load()  # Returns None

init

__init__() -> None

Create a new MemoryTokenStorage.

repr

__repr__() -> str

Return a string representation of the storage.

clear

clear() -> None

Clear the stored authentication token from memory.

load

load() -> Optional[str]

Load the stored authentication token from memory.

Returns:

Optional[str] –

The stored token string, or None if no token is stored.

store

store(token: str) -> None

Store the authentication token in memory.

Parameters:

token (str) –

The token string to store.

NewTrainingSession

Result of meth:Client.start_training_session.

The handle returned when a training session is freshly created via cloud.server.start. The task_id can be polled with meth:Client.task_info; the session_id is the handle for meth:Client.training_session, meth:Client.update_training_session and meth:Client.delete_training_sessions.

session_id `property`

session_id: Optional[TrainingSessionID]

Freshly-minted training session id.

Optional because the underlying cloud.server.start endpoint also returns non-trainer tasks. For a trainer start request this is always populated.

task_id `property`

task_id: TaskID

Backing BackgroundTask row id (acceptable to task_info / task_status / job_stop).

NewValidationSession

Result of meth:Client.start_validation_session.

The handle returned when a session is freshly created via cloud.server.start. The session_id is what downstream data uploads / metrics use and what meth:Client. delete_validation_sessions consumes in test teardown.

session_id `property`

session_id: Optional[ValidationSessionID]

Freshly-minted validation session id.

Optional because the underlying cloud.server.start endpoint also returns non-validation tasks (e.g. trainer). For a validation start request this is always populated.

task_id `property`

task_id: TaskID

Backing BackgroundTask row id (acceptable to task_info / task_status / job_stop).

Organization

Organization information and metadata.

Each user belongs to an organization which contains projects, datasets, and other resources. Organizations provide isolated workspaces for teams and manage resource quotas and billing.

Examples:

>>> # Access organization details
>>> org = client.organization()
>>> print(f"Organization: {org.name} (ID: {org.id})")
>>> print(f"Available credits: {org.credits}")

credits `property`

credits: float

The organization's most recent monthly credit.

A float, matching the server's own type. Note this is not the spendable balance -- see Client.usage_summary() for that.

id `property`

id: OrganizationID

The unique identifier for the organization.

name `property`

name: str

The name of the organization.

OrganizationID

Unique identifier for an organization in EdgeFirst Studio.

Organizations are the top-level containers for users, projects, and resources in EdgeFirst Studio. Can be constructed from an integer, a prefixed hex string (e.g., "org-abc123"), or another OrganizationID instance.

Examples:

>>> org_id = OrganizationID("org-abc123")
>>> org_id = OrganizationID(0xABC123)
>>> org_id = OrganizationID.from_str("org-abc123")
>>> int(org_id)
11256099
>>> str(org_id)
'org-abc123'

Note

Internally an OrganizationID is an unsigned 64-bit integer. This class handles translating between integer and string representations of organization IDs.

Parameter

Represents a parameter value that can be an integer, float, boolean, string, array, or object (dictionary).

This class provides Python magic methods for type conversions and comparisons, making it behave like native Python types.

Examples:

>>> # Create Parameters using static constructors
>>> p_int = Parameter.integer(42)
>>> p_real = Parameter.real(3.14)
>>> p_bool = Parameter.boolean(True)
>>> p_str = Parameter.string("hello")
>>> p_array = Parameter.array([1, 2, 3])
>>> p_obj = Parameter.object({"key": "value"})
>>>
>>> # Type conversions
>>> int(p_int)  # Returns: 42
>>> float(p_int)  # Returns: 42.0
>>> float(p_real)  # Returns: 3.14
>>> int(p_real)  # Returns: 3
>>>
>>> # Type checking
>>> p_real.is_real()  # Returns: True
>>> p_real.type_name()  # Returns: "Real"
>>>
>>> # Equality with tolerance for floats
>>> p_real = Parameter.real(0.75)
>>> p_real == 0.75  # Returns: True (with tolerance)
>>> p_real == 0.75000000001  # Returns: True (within epsilon)

bool

__bool__() -> bool

Convert to Python bool (works for all types).

eq

__eq__(other: Any) -> bool

Equality comparison with type coercion.

For numeric types (Integer, Real), compares with tolerance (epsilon=1e-9).

float

__float__() -> float

Convert to Python float (works for Integer, Real, Boolean).

int

__int__() -> int

Convert to Python int (works for Integer, Real, Boolean).

repr

__repr__() -> str

Python representation (always descriptive).

Examples:

>>> repr(Parameter.string("hello"))  # Returns: "String(hello)"
>>> repr(Parameter.integer(42))      # Returns: "Integer(42)"

str

__str__() -> str

Convert to Python string.

For String parameters, returns the plain string value without decoration. For other types, returns a descriptive representation.

Examples:

>>> str(Parameter.string("hello"))  # Returns: "hello"
>>> str(Parameter.integer(42))      # Returns: "Integer(42)"

array `staticmethod`

array(values: List[Any]) -> 'Parameter'

Create an Array parameter from a Python list.

Values in the list will be converted to Parameters recursively.

as_array

as_array() -> Optional[List[Any]]

Extract as Python list if this is an Array parameter.

Returns None if this is not an Array parameter. Elements are converted to native Python types recursively.

Examples:

>>> p = Parameter.array([
...     Parameter.integer(1),
...     Parameter.real(2.5),
...     Parameter.string("test")
... ])
>>> p.as_array()  # Returns: [1, 2.5, "test"]
>>> Parameter.integer(42).as_array()  # Returns: None

as_boolean

as_boolean() -> Optional[bool]

Extract as Python bool if this is a Boolean parameter.

Returns None if this is not a Boolean parameter.

Examples:

>>> p = Parameter.boolean(True)
>>> p.as_boolean()  # Returns: True
>>> Parameter.integer(1).as_boolean()  # Returns: None

as_integer

as_integer() -> Optional[int]

Extract as Python int if this is an Integer parameter.

Returns None if this is not an Integer parameter.

Examples:

>>> p = Parameter.integer(42)
>>> p.as_integer()  # Returns: 42
>>> Parameter.real(3.14).as_integer()  # Returns: None

as_object

as_object() -> Optional[Dict[str, Any]]

Extract as Python dict if this is an Object parameter.

Returns None if this is not an Object parameter. Values are converted to native Python types recursively.

Examples:

>>> p = Parameter.object({
...     "count": Parameter.integer(42),
...     "ratio": Parameter.real(3.14)
... })
>>> p.as_object()  # Returns: {"count": 42, "ratio": 3.14}
>>> Parameter.integer(42).as_object()  # Returns: None

as_real

as_real() -> Optional[float]

Extract as Python float if this is a Real parameter.

Returns None if this is not a Real parameter.

Examples:

>>> p = Parameter.real(3.14)
>>> p.as_real()  # Returns: 3.14
>>> Parameter.integer(42).as_real()  # Returns: None

as_string

as_string() -> Optional[str]

Extract as Python str if this is a String parameter.

Returns None if this is not a String parameter.

Examples:

>>> p = Parameter.string("hello")
>>> p.as_string()  # Returns: "hello"
>>> Parameter.integer(42).as_string()  # Returns: None

boolean `staticmethod`

boolean(value: bool) -> 'Parameter'

Create a Boolean parameter.

get

get(key: str, default: Any = None) -> Any

Get value by key with optional default (Object only).

Works like dict.get() - returns the value if key exists, otherwise returns the default value.

Parameters:

key (str) –

The key to lookup
default (Any, default: None ) –

Value to return if key doesn't exist (default: None)

Returns:

Any –

The value converted to native Python types, or default if
Any –

key not found

Raises:

TypeError –

If parameter is not an Object

Examples:

>>> obj = Parameter.object({"model": Parameter.string("yolo")})
>>> obj.get("model")  # Returns: "yolo"
>>> obj.get("missing")  # Returns: None
>>> obj.get("missing", "default")  # Returns: "default"

integer `staticmethod`

integer(value: int) -> 'Parameter'

Create an Integer parameter.

is_array

is_array() -> bool

Check if this is an Array parameter.

is_boolean

is_boolean() -> bool

Check if this is a Boolean parameter.

is_integer

is_integer() -> bool

Check if this is an Integer parameter.

is_object

is_object() -> bool

Check if this is an Object parameter.

is_real

is_real() -> bool

Check if this is a Real parameter.

is_string

is_string() -> bool

Check if this is a String parameter.

items

items() -> List[Tuple[str, Any]]

Get dictionary items as (key, value) tuples (Object only).

Returns:

List[Tuple[str, Any]] –

List of (key, value) tuples with values converted to
List[Tuple[str, Any]] –

native Python types

Raises:

TypeError –

If parameter is not an Object

Examples:

>>> obj = Parameter.object({
...     "a": Parameter.integer(1),
...     "b": Parameter.integer(2)
... })
>>> obj.items()  # Returns: [("a", 1), ("b", 2)]

keys

keys() -> List[str]

Get dictionary keys (Object only).

Returns:

List[str] –

List of keys in the object

Raises:

TypeError –

If parameter is not an Object

Examples:

>>> obj = Parameter.object({"a": 1, "b": 2})
>>> obj.keys()  # Returns: ["a", "b"]

object `staticmethod`

object(values: Dict[str, Any]) -> 'Parameter'

Create an Object parameter from a Python dictionary.

Values in the dict will be converted to Parameters recursively.

real `staticmethod`

real(value: float) -> 'Parameter'

Create a Real (float) parameter.

string `staticmethod`

string(value: str) -> 'Parameter'

Create a String parameter.

type_name

type_name() -> str

Get the variant type name.

Returns one of: "Integer", "Real", "Boolean", "String", "Array", "Object"

values

values() -> List[Any]

Get dictionary values (Object only).

Returns:

List[Any] –

List of values converted to native Python types

Raises:

TypeError –

If parameter is not an Object

Examples:

>>> obj = Parameter.object({
...     "a": Parameter.integer(1),
...     "b": Parameter.integer(2)
... })
>>> obj.values()  # Returns: [1, 2]

variant_type

variant_type() -> str

Get the variant type name.

Returns one of: "Integer", "Real", "Boolean", "String", "Array", "Object"

This is an alias for type_name() for consistency with Rust API.

Polygon

Represents a polygonal segmentation annotation.

A polygon is defined by one or more rings, where each ring is a list of (x, y) coordinate tuples normalized to the image dimensions. All coordinates are float32 values between 0 and 1.

rings `property`

rings: List[List[Tuple[float, float]]]

Returns the ring data defining the polygon.

Each ring is a list of (x, y) coordinate tuples, with values normalized to the image dimensions.

Returns:

List[List[Tuple[float, float]]] –

List[List[Tuple[float, float]]]: The polygon rings.

init

__init__(rings: List[List[Tuple[float, float]]]) -> None

Initializes a new Polygon from a list of rings.

Parameters:

rings (List[List[Tuple[float, float]]]) –

A list of rings, where each ring is a list of (x, y) float tuples normalized to the image dimensions.

PresignedUrl

A presigned URL for uploading a file to S3.

Returned by populate_samples to indicate where files should be uploaded.

filename `property`

filename: str

The filename as specified in the sample.

key `property`

key: str

The S3 key path.

url `property`

url: str

The presigned URL for uploading (use PUT request).

Project

The project class represents a project in the EdgeFirst Studio. A project contains datasets, experiments, and other resources related to a specific task or workflow.

description `property`

description: str

The description of the project.

id `property`

id: ProjectID

The unique identifier for the project.

name `property`

name: str

The name of the project.

uid `property`

uid: str

The unique string identifier for the object.

.. deprecated:: Use str(Project.id) instead. This property will be removed in a future version.

datasets

datasets(
    client_or_name: Optional[Union[Client, str]] = None,
    name: Optional[str] = None,
) -> List[Dataset]

List the datasets in the project.

New API (v2.6.0+): Uses embedded client reference.

Parameters:

client_or_name (Optional[Union[Client, str]], default: None ) –

Deprecated client, or a dataset name filter string.
name (Optional[str], default: None ) –

The name of the dataset to filter by.

Returns:

List[Dataset] –

A list of datasets in the project.

.. deprecated:: Passing client parameter is deprecated. Use project.datasets() directly instead.

experiments

experiments(
    client_or_name: Optional[Union[Client, str]] = None,
    name: Optional[str] = None,
) -> List[Experiment]

List the experiments in the project.

New API (v2.6.0+): Uses embedded client reference.

Parameters:

client_or_name (Optional[Union[Client, str]], default: None ) –

Deprecated client, or an experiment name filter string.
name (Optional[str], default: None ) –

The name of the experiment to filter by.

Returns:

List[Experiment] –

A list of experiments in the project.

.. deprecated:: Passing client parameter is deprecated. Use project.experiments() directly instead.

validation_sessions

validation_sessions(
    client: Optional[Client] = None,
) -> List[ValidationSession]

List the validation sessions in the project.

New API (v2.6.0+): Uses embedded client reference.

Parameters:

client (Optional[Client], default: None ) –

Deprecated. The client to use for the request.

Returns:

List[ValidationSession] –

A list of validation sessions in the project.

.. deprecated:: Passing client parameter is deprecated. Use project.validation_sessions() directly instead.

ProjectID

Unique identifier for a project within EdgeFirst Studio.

Projects contain datasets, experiments, and models within an organization. Can be constructed from an integer, a prefixed hex string (e.g., "p-def456"), or another ProjectID instance.

Examples:

>>> project_id = ProjectID("p-def456")
>>> project_id = ProjectID(0xDEF456)
>>> project_id = ProjectID.from_str("p-def456")
>>> int(project_id)
14611542
>>> str(project_id)
'p-def456'

Note

Internally a ProjectID is an unsigned 64-bit integer. This class handles translating between integer and string representations of project IDs.

RestoreResult

Result from restoring a dataset to a specific version tag.

message `property`

message: str

A human-readable message about the restore operation.

new_serial `property`

new_serial: int

The new changelog serial number after restore.

restored_counts_annotation_sets `property`

restored_counts_annotation_sets: int

Number of annotation sets restored.

restored_counts_images `property`

restored_counts_images: int

Number of images restored.

restored_counts_labels `property`

restored_counts_labels: int

Number of labels restored.

restored_from_serial `property`

restored_from_serial: int

The serial number of the tag that was restored from.

restored_from_tag `property`

restored_from_tag: str

The name of the tag that was restored from.

success `property`

success: bool

Whether the restore was successful.

Sample

Represents a single data sample in the EdgeFirst dataset. A sample includes metadata and associated annotations, and can be used to download file content for different sensor modalities.

annotations `property`

annotations: List[Annotation]

Returns the list of annotations associated with this sample.

Returns:

List[Annotation] –

List[Annotation]: A list of annotation objects.

date `property`

date: Optional[str]

Returns the timestamp when this sample was captured, in RFC3339 format.

Returns:

Optional[str] –

Optional[str]: The timestamp as an ISO 8601 string or None.

files `property`

files: List[SampleFile]

Returns the list of files associated with this sample.

Returns:

List[SampleFile] –

List[SampleFile]: A list of sample file objects.

frame_number `property`

frame_number: Optional[int]

Returns the frame number of this sample within its sequence, if any.

Returns:

Optional[int] –

Optional[int]: The frame number or None.

group `property`

group: Optional[str]

Returns the group name of the sample, if any.

Returns:

Optional[str] –

Optional[str]: The group name or None.

height `property`

height: Optional[int]

Returns the height of the image in pixels.

Returns:

Optional[int] –

Optional[int]: The image height or None.

id `property`

id: Optional[SampleID]

Returns the unique identifier of the sample.

Returns:

Optional[SampleID] –

Optional[SampleID]: The sample ID, or None if not set.

image_name `property`

image_name: Optional[str]

Returns the image filename for this sample.

Returns:

Optional[str] –

Optional[str]: The image filename or None.

image_url `property`

image_url: Optional[str]

Returns the URL of the image for this sample.

Returns:

Optional[str] –

Optional[str]: The image URL or None.

location `property`

location: Optional[GpsData]

Returns GPS location metadata for this sample, if available.

Returns:

Optional[GpsData] –

Optional[GpsData]: Sample GPS metadata or None.

name `property`

name: Optional[str]

Returns the name of the sample.

Returns:

Optional[str] –

Optional[str]: The sample name, or None if not set.

pose `property`

pose: Optional[ImuData]

Returns IMU pose metadata for this sample, if available.

Returns:

Optional[ImuData] –

Optional[ImuData]: Sample IMU metadata or None.

sequence_description `property`

sequence_description: Optional[str]

Returns the description of the sequence to which this sample belongs, if any.

Returns:

Optional[str] –

Optional[str]: The sequence description or None.

sequence_name `property`

sequence_name: Optional[str]

Returns the sequence name to which this sample belongs, if any.

Returns:

Optional[str] –

Optional[str]: The sequence name or None.

sequence_uuid `property`

sequence_uuid: Optional[str]

Returns the UUID of the sequence to which this sample belongs, if any.

Returns:

Optional[str] –

Optional[str]: The sequence UUID or None.

source `property`

source: Optional[str]

Returns the source identifier for this sample.

Returns:

Optional[str] –

Optional[str]: The source identifier or None.

timing `property`

timing: Optional[Dict[str, Optional[int]]]

Pipeline timing measurements in nanoseconds, if available.

Returns a dict with keys load, preprocess, inference, decode, each Optional[int].

Returns:

Optional[Dict[str, Optional[int]]] –

Optional[Dict[str, Optional[int]]]: Timing dict or None.

uid `property`

uid: Optional[str]

The unique string identifier for the object.

.. deprecated:: Use str(Sample.id) if id is not None. This property will be removed in a future version.

Returns:

Optional[str] –

Optional[str]: The UID, or None if not set.

uuid `property`

uuid: Optional[str]

Returns the UUID of this sample.

Returns:

Optional[str] –

Optional[str]: The sample UUID or None.

width `property`

width: Optional[int]

Returns the width of the image in pixels.

Returns:

Optional[int] –

Optional[int]: The image width or None.

init

__init__() -> None

Create a new empty sample.

add_annotation

add_annotation(annotation: Annotation) -> None

Add an annotation to this sample.

add_file

add_file(file: SampleFile) -> None

Add a file (image, LiDAR, etc.) to this sample.

assign_group

assign_group(group_id: int) -> None

Assign this sample to a server-side group.

Groups organize samples into splits such as "train", "val", and "test". Use :meth:Dataset.groups to list available groups, or :meth:Client.get_or_create_group to create one.

Requires an embedded client reference (samples returned by the client methods automatically have one).

Note

This updates the group assignment on the server. To set the local in-memory group name when building new samples, use :meth:set_group instead.

Parameters:

group_id (int) –

Numeric group ID returned by :meth:Dataset.groups, :meth:Client.groups, or :meth:Client.get_or_create_group.

Raises:

TypeError –

If sample has no client reference or no ID. Use client.set_sample_group_id(sample.id, group_id) instead.

Example

groups = client.groups(dataset_id) train_group = next(g for g in groups if g.name == "train") sample.assign_group(train_group.id)

download

download(
    file_type_or_client: Optional[
        Union[FileType, Client]
    ] = None,
    file_type: Optional[FileType] = None,
) -> Optional[bytes]

Download sample file data.

Downloads a file associated with this sample. For downloading many samples, use dataset.download() or client.download_dataset() which downloads in bulk and is significantly faster.

New API (v2.6.0+): >>> data = sample.download() # Uses embedded client reference >>> lidar = sample.download(file_type=FileType.LidarPcd)

Deprecated API

data = sample.download(client) # Passing client explicitly

Parameters:

file_type_or_client (Optional[Union[FileType, Client]], default: None ) –

Deprecated client, or a file type when used as the first positional argument.
file_type (Optional[FileType], default: None ) –

Type of file to download. Defaults to FileType.Image. Other options: LidarPcd, LidarDepth, LidarReflect, RadarPcd, RadarCube.

Returns:

Optional[bytes] –

Optional[bytes]: The file data, or None if no file exists for the requested type -- including a sample with no image at all (e.g. a lidar-only or radar-only capture). For FileType.Image specifically, a sample whose record has a registered image but no fetchable URL for it is a dataset integrity problem rather than an absent optional file, so that case raises instead of returning None (see Raises).

Raises:

TypeError –

If sample has no client reference and client is not provided.
RuntimeError –

If file_type is FileType.Image and the sample has a registered image (an image name is present) but no fetchable image URL for it (missing, empty, or malformed).

.. deprecated:: Passing client parameter is deprecated since v2.6.0. Use sample.download(file_type=...) instead.

set_frame_number

set_frame_number(frame_number: Optional[int]) -> None

Set the frame number for this sample.

set_group

set_group(group: Optional[str]) -> None

Set the dataset split (train/val/test) for this sample.

set_image_name

set_image_name(image_name: Optional[str]) -> None

Set the image filename for this sample.

set_location

set_location(location: Optional[GpsData]) -> None

Set GPS location metadata for this sample.

This metadata is uploaded with the sample itself, not stored on individual annotations.

set_pose

set_pose(pose: Optional[ImuData]) -> None

Set IMU pose metadata for this sample.

This metadata is uploaded with the sample itself, not stored on individual annotations.

set_sequence_description

set_sequence_description(
    sequence_description: Optional[str],
) -> None

Set the sequence description for this sample.

set_sequence_name

set_sequence_name(sequence_name: Optional[str]) -> None

Set the sequence name for this sample.

set_sequence_uuid

set_sequence_uuid(sequence_uuid: Optional[str]) -> None

Set the unique sequence identifier for this sample.

SampleFile

Represents a file associated with a sample (e.g., LiDAR, radar, depth map).

For uploading samples, create a SampleFile with a type and local filename. For downloaded samples, the file will have a type and URL.

file_type `property`

file_type: str

The type of file (e.g., "image", "lidar").

filename `property`

filename: Optional[str]

Local filename for upload, or None if downloaded.

url `property`

url: Optional[str]

URL for downloaded files, or None if for upload.

init

__init__(file_type: str, filename: str) -> None

Create a new sample file for upload.

Parameters:

file_type (str) –

Type of file (e.g., "image", "lidar", "depth")
filename (str) –

Path to the local file to upload

SampleID

Unique identifier for a sample in EdgeFirst Studio.

Can be constructed from an integer, a prefixed hex string (e.g., "s-6c5b4a"), or another SampleID instance.

Examples:

>>> sample_id = SampleID("s-6c5b4a")
>>> sample_id = SampleID(0x6C5B4A)
>>> sample_id = SampleID.from_str("s-6c5b4a")
>>> int(sample_id)
7101258
>>> str(sample_id)
's-6c5b4a'

Note

Internally a SampleID is an unsigned 64-bit integer. This class handles translating between integer and string representations of sample IDs.

SamplesCountResult

Result of counting samples in a dataset.

Contains the total number of samples matching the specified criteria.

total `property`

total: int

The total number of samples.

SamplesPopulateResult

Result of populating a sample into a dataset.

Contains the UUID assigned to the sample and presigned URLs for uploading associated files.

urls `property`

urls: List[PresignedUrl]

Presigned URLs for uploading files associated with this sample.

uuid `property`

uuid: str

The UUID assigned to the sample by the server.

SchemaField

A single field descriptor from a trainer or validator schema.

Describes one hyperparameter: its name, type, default and constraints. Nested parameter groups are exposed via children. Use the descriptors to build the params dict for meth:Client.start_training_session.

children `property`

children: List[SchemaField]

Nested fields (group fields, or bool fields that reveal sub-parameters when enabled).

default `property`

default: Optional[Parameter]

Default value applied when the parameter is omitted.

description `property`

description: Optional[str]

Longer description of the parameter.

enable_annotation_set_selection `property`

enable_annotation_set_selection: bool

Dataset fields: enable annotation set selection.

enable_tags_selection `property`

enable_tags_selection: bool

Dataset fields: enable dataset tag selection.

field_type `property`

field_type: Optional[str]

Field type as a lowercase string ("int", "group", "select", ...); "unknown" for types this client version does not recognize, None when the server omits the type.

hidden `property`

hidden: bool

Mask the text input (passwords).

is_dropdown `property`

is_dropdown: bool

Render the select as a dropdown.

is_multi_line `property`

is_multi_line: bool

Render the text input as multi-line.

label `property`

label: Optional[str]

Human-readable label.

max `property`

max: Optional[float]

Maximum value (numeric fields).

min `property`

min: Optional[float]

Minimum value (numeric fields).

multi_select `property`

multi_select: bool

Allow selecting multiple options.

name `property`

name: Optional[str]

Parameter name — the key to use in the launch params dict.

numeric_only `property`

numeric_only: bool

Restrict text input to numeric characters.

options `property`

options: List[SchemaOption]

Selectable options (select fields).

required `property`

required: bool

Whether a value is required to launch.

step `property`

step: Optional[float]

Step size (numeric fields).

values `property`

values: Optional[List[Parameter]]

Slider fields: number of slider handles (1 = value, 2 = range).

SchemaOption

One selectable option of a select schema field.

children `property`

children: List[SchemaField]

Nested fields revealed when this option is selected.

label `property`

label: Optional[str]

Human-readable label.

name `property`

name: Optional[Parameter]

Option value; may be any JSON scalar (string, number, ...).

SequenceId

Unique identifier for a sequence in EdgeFirst Studio.

Can be constructed from an integer, a prefixed hex string (e.g., "se-7f6e5d"), or another SequenceId instance.

Examples:

>>> seq_id = SequenceId("se-7f6e5d")
>>> seq_id = SequenceId(0x7F6E5D)
>>> seq_id = SequenceId.from_str("se-7f6e5d")
>>> int(seq_id)
8351325
>>> str(seq_id)
'se-7f6e5d'

Note

Internally a SequenceId is an unsigned 64-bit integer. This class handles translating between integer and string representations of sequence IDs.

ServerAnnotation

A single annotation in server wire format, for use with Client.add_annotations_bulk.

Unlike Annotation (used with populate_samples), this maps directly to the annotation.add_bulk RPC's expected shape and edits an already-uploaded sample in place — it requires an existing image_id, not a new one created via upload.

label_id, label_index, and label_name are not interchangeable: the server's annotation.add_bulk RPC only resolves the label from label_id. Set label_id to a real label ID (e.g. looked up via Client.labels) whenever the annotation should carry a label — passing only label_name and/or label_index will silently fail to resolve a label. This matches the CLI's import-coco --update path (edgefirst_client::coco::studio::update_coco_annotations), which always sets label_id alongside label_name.

init

__init__(
    annotation_type: str,
    x: float,
    y: float,
    w: float,
    h: float,
    score: float,
    image_id: int,
    annotation_set_id: int,
    label_id: Optional[int] = None,
    label_index: Optional[int] = None,
    label_name: Optional[str] = None,
    polygon: Optional[str] = None,
    object_reference: Optional[str] = None,
) -> None

Parameters:

annotation_type (str) –

"box" for bounding box, "seg" for segmentation.
x (float) –

Bounding box X coordinate (normalized 0-1, left/top origin).
y (float) –

Bounding box Y coordinate (normalized 0-1, left/top origin).
w (float) –

Bounding box width (normalized 0-1).
h (float) –

Bounding box height (normalized 0-1).
score (float) –

Confidence score (0-1).
image_id (int) –

Image/sample ID in the database.
annotation_set_id (int) –

Annotation set ID.
label_id (Optional[int], default: None ) –

Label ID. This is the only field the server's annotation.add_bulk RPC uses to resolve a label; set it (e.g. from Client.labels) whenever the annotation should carry a label.
label_index (Optional[int], default: None ) –

Optional source-faithful label index to record alongside label_id. Does not itself resolve a label.
label_name (Optional[str], default: None ) –

Optional label name to record alongside label_id. Does not itself resolve a label.
polygon (Optional[str], default: None ) –

Polygon data as a JSON string (for segmentation).
object_reference (Optional[str], default: None ) –

Optional object tracking reference.

Snapshot

This class represents a snapshot in EdgeFirst Studio.

Snapshots are frozen datasets in EdgeFirst Dataset Format (Zip/Arrow pairs) used for MCAP uploads with AGTG or dataset backup/migration.

created `property`

created: str

Returns the creation timestamp of the snapshot.

Returns:

str ( str ) –

The snapshot creation timestamp.

description `property`

description: str

Returns the description of the snapshot.

Returns:

str ( str ) –

The snapshot description.

id `property`

id: SnapshotID

Returns the unique identifier of the snapshot.

Returns:

SnapshotID ( SnapshotID ) –

The snapshot ID.

path `property`

path: str

Returns the storage path of the snapshot.

Returns:

str ( str ) –

The snapshot path.

status `property`

status: str

Returns the status of the snapshot (e.g., 'available', 'processing').

Returns:

str ( str ) –

The snapshot status.

uid `property`

uid: str

Returns the unique string identifier of the snapshot.

.. deprecated:: Use str(Snapshot.id) instead. This property will be removed in a future version.

Returns:

str ( str ) –

The snapshot UID.

delete

delete() -> None

Delete this snapshot.

Requires an embedded client reference (snapshots returned by the client methods automatically have one).

Raises:

TypeError –

If snapshot has no client reference. Use client.delete_snapshot(snapshot.id) instead.

Example

snapshot.delete()

download

download(
    output: str, progress: Optional[Progress] = None
) -> None

download(client: Client, output: str) -> None

download(
    output_or_client: Union[str, Client],
    output: Optional[str] = None,
    progress: Optional[Progress] = None,
) -> None

Download this snapshot to a local directory.

restore

restore(
    project_id: Union[ProjectID, str],
    topics: List[str],
    autolabel: List[str],
    autodepth: bool,
    dataset_name: Optional[str] = None,
    dataset_description: Optional[str] = None,
) -> SnapshotRestoreResult

Restore this snapshot into a new dataset.

Requires an embedded client reference (snapshots returned by the client methods automatically have one).

Parameters:

project_id (Union[ProjectID, str]) –

The project ID to restore into (ProjectID or string like "proj-xxx").
topics (List[str]) –

List of MCAP topics to include in the restored dataset.
autolabel (List[str]) –

List of autolabel pipeline names to run. Pass an empty list to skip autolabeling.
autodepth (bool) –

Whether to run the autodepth pipeline.
dataset_name (Optional[str], default: None ) –

Optional name for the created dataset.
dataset_description (Optional[str], default: None ) –

Optional description for the created dataset.

Returns:

SnapshotRestoreResult –

class:SnapshotRestoreResult with the new dataset and task IDs.

Raises:

TypeError –

If snapshot has no client reference. Use client.restore_snapshot(project_id, snapshot.id, ...) instead.

Example

result = snapshot.restore( ... project_id="proj-abc123", ... topics=["/camera/image"], ... autolabel=[], ... autodepth=False, ... dataset_name="Restored Dataset", ... )

SnapshotFromDatasetResult

Result of creating a snapshot from a dataset.

Contains the snapshot ID and task ID for monitoring the creation progress.

id `property`

id: SnapshotID

Returns the unique identifier of the created snapshot.

Returns:

SnapshotID ( SnapshotID ) –

The snapshot ID.

task_id `property`

task_id: TaskID | None

Returns the ID of the task processing the snapshot creation.

Returns:

TaskID | None –

TaskID | None: The task ID for tracking progress, or None if the operation completed synchronously.

SnapshotID

Unique identifier for a snapshot in EdgeFirst Studio.

Snapshots represent saved states of datasets or model checkpoints. Can be constructed from an integer, a prefixed hex string (e.g., "ss-abc123"), or another SnapshotID instance.

Examples:

>>> snapshot_id = SnapshotID("ss-abc123")
>>> snapshot_id = SnapshotID(0xABC123)
>>> snapshot_id = SnapshotID.from_str("ss-abc123")
>>> int(snapshot_id)
11256099
>>> str(snapshot_id)
'ss-abc123'

Note

Internally a SnapshotID is an unsigned 64-bit integer. This class handles translating between integer and string representations of snapshot IDs.

SnapshotRestoreResult

Result of a snapshot restore operation.

Contains information about the dataset created from restoring a snapshot, including the dataset ID, annotation set ID, and associated task ID for tracking the restore process.

annotation_set_id `property`

annotation_set_id: AnnotationSetID

Returns the ID of the annotation set in the restored dataset.

Returns:

AnnotationSetID ( AnnotationSetID ) –

The annotation set ID.

dataset_id `property`

dataset_id: DatasetID

Returns the ID of the dataset created from the restore.

Returns:

DatasetID ( DatasetID ) –

The dataset ID.

dataset_name `property`

dataset_name: str

Returns the name of the created dataset.

Returns:

str ( str ) –

The dataset name.

date `property`

date: str | None

Returns the timestamp when the restore was initiated.

The snapshots.restore response does not always include a date, so this may be None.

Returns:

str | None –

str | None: The restore timestamp, or None if not provided.

description `property`

description: str

Returns the description of the restore operation.

Returns:

str ( str ) –

The restore description.

id `property`

id: SnapshotID

Returns the unique identifier of the snapshot that was restored.

Returns:

SnapshotID ( SnapshotID ) –

The snapshot ID.

task_id `property`

task_id: TaskID | None

Returns the ID of the task processing the restore operation.

Returns:

TaskID | None –

TaskID | None: The task ID for tracking progress, or None.

Stage

Represents a stage in the task.

description `property`

description: Optional[str]

Returns the description of the stage, if any.

Returns:

Optional[str] –

Optional[str]: The stage description or None.

message `property`

message: Optional[str]

Returns the message associated with the stage, if any.

Returns:

Optional[str] –

Optional[str]: The stage message or None.

percentage `property`

percentage: int

Returns the completion percentage of the stage.

Returns:

int ( int ) –

The stage completion percentage as an integer, each step representing 1% of the total.

stage_id `property`

stage_id: str

Returns the ID of the stage.

Returns:

str ( str ) –

The stage ID.

status `property`

status: Optional[str]

Returns the status of the stage.

Returns:

str ( Optional[str] ) –

The stage status.

task_id `property`

task_id: TaskID

Returns the ID of the task associated with this stage.

Returns:

ID ( TaskID ) –

The task ID.

Tag

A legacy free-form tag on a dataset (tags.list_dataset).

Unrelated to dataset version tags — see VersionTag for the dataset-versioning tag feature.

dataset_id `property`

dataset_id: int

The dataset this tag belongs to.

id `property`

id: int

The tag's unique identifier (creation-ordered).

name `property`

name: str

The tag name.

Task

Represents an EdgeFirst Studio Cloud Task. A task could be a docker instance or an EC2 instance or similar.

created `property`

created: datetime

Returns the creation date of the Docker task.

Returns:

datetime ( datetime ) –

The Docker task creation date.

id `property`

id: TaskID

Returns the unique identifier of the Docker task.

Returns:

TaskID ( TaskID ) –

The Docker task ID.

instance `property`

instance: str

Returns the instance type for the task. The instance type depends on the manager, for cloud manager it is the AWS EC2 instance type.

Returns:

str ( str ) –

The task instance type.

manager `property`

manager: str

Returns the manager type for the task. The manager could be cloud, user, or kubernetes.

Returns:

str ( str ) –

The task manager type.

name `property`

name: str

Returns the name of the Docker task.

Returns:

str ( str ) –

The Docker task name.

status `property`

status: str

Returns the status of the Docker task.

Returns:

str ( str ) –

The Docker task status.

uid `property`

uid: str

The unique string identifier for the object.

.. deprecated:: Use str(Task.id) instead. This property will be removed in a future version.

workflow `property`

workflow: str

Returns the task workflow which could be trainer or validation workflows.

Returns:

str ( str ) –

The task workflow.

TaskDataList

List of data and chart artefacts attached to a task.

The data map encodes the folder layout: keys are folder names, values are filenames within that folder.

Note: validation sessions use a flat list[str] of relative paths (returned by :meth:ValidationSession.data_list), not this type.

data `property`

data: Dict[str, List[str]]

Folder -> filename map of artefacts.

Returns:

Dict[str, List[str]] –

Dict[str, List[str]]: Map of folder names to lists of filenames.

organization_uid `property`

organization_uid: str

Owning organization identifier (e.g. 'org-abc123').

Returns:

str ( str ) –

The organization UID.

server `property`

server: str

The server hostname for the underlying storage.

Returns:

str ( str ) –

The storage server hostname.

traces `property`

traces: List[str]

Trace files surfaced from the trace folder.

Returns:

List[str] –

List[str]: List of trace filenames.

TaskID

Unique identifier for a task in EdgeFirst Studio.

Can be constructed from an integer, a prefixed hex string (e.g., "task-abc123"), or another TaskID instance.

Examples:

>>> task_id = TaskID("task-abc123")
>>> task_id = TaskID(0xABC123)
>>> task_id = TaskID.from_str("task-abc123")
>>> int(task_id)
11256099
>>> str(task_id)
'task-abc123'

Note

Internally a TaskID is an unsigned 64-bit integer. This class handles translating between integer and string representations of task IDs.

TaskInfo

The TaskInfo class provides detailed information about a specific task such as its status and progress.

completed `property`

completed: datetime

Returns the completion date of the task, if any.

Returns:

datetime ( datetime ) –

The task completion date or None.

created `property`

created: datetime

Returns the creation date of the task.

Returns:

datetime ( datetime ) –

The task creation date.

description `property`

description: str

Returns the description of the task, if any.

Returns:

str –

Optional[str]: The task description or None.

id `property`

id: TaskID

Returns the unique identifier of the task.

Returns:

TaskID ( TaskID ) –

The task ID.

project_id `property`

project_id: ProjectID

Returns the ID of the project associated with the task.

Returns:

ProjectID ( ProjectID ) –

The project ID.

stages `property`

stages: Dict[str, Stage]

Returns the stages of the task.

Returns:

Dict[str, Stage] –

Dict[str, Stage]: A dictionary of stage names to Stage objects.

status `property`

status: str

Returns the status of the task.

Returns:

str ( str ) –

The task status.

uid `property`

uid: str

Returns the unique string identifier for the task.

.. deprecated:: Use str(TaskInfo.id) instead. This property will be removed in a future version.

Returns:

str ( str ) –

The task UID.

add_chart

add_chart(
    client: Client,
    group: str,
    name: str,
    data: Parameter,
    params: Optional[Parameter] = None,
) -> None

Add (or overwrite) a chart under (group, name) for this task.

Parameters:

client (Client) –

The authenticated EdgeFirst client.
group (str) –

Chart group name (non-empty).
name (str) –

Chart name within the group (non-empty).
data (Parameter) –

Chart body as a Parameter (arbitrary JSON).
params (Optional[Parameter], default: None ) –

Optional chart-rendering parameters.

Raises:

RuntimeError –

If the request fails or group/name are empty.

data_list

data_list(client: Client) -> TaskDataList

List data artefacts (non-chart files) attached to this task.

Parameters:

client (Client) –

The authenticated EdgeFirst client.

Returns:

TaskDataList ( TaskDataList ) –

Data artefacts keyed by folder name.

Raises:

RuntimeError –

If the request fails.

download_data

download_data(
    client: Client,
    file: str,
    output_path: Union[str, Path],
    folder: Optional[str] = None,
    progress: Optional[Callable[..., None]] = None,
) -> None

Download a data file from this task to a local path.

Parameters:

client (Client) –

The authenticated EdgeFirst client.
file (str) –

Filename to download.
output_path (Union[str, Path]) –

Local path to write the downloaded file.
folder (Optional[str], default: None ) –

Optional logical subdirectory under the task data root.
progress (Optional[Callable], default: None ) –
Optional progress callback. Supports two signatures:
- callback(current, total) — basic progress
- callback(current, total, status) — with status message

Raises:

RuntimeError –

If the download fails.

get_chart

get_chart(
    client: Client, group: str, name: str
) -> Parameter

Fetch the raw chart body for (group, name) on this task.

Parameters:

client (Client) –

The authenticated EdgeFirst client.
group (str) –

Chart group name (non-empty).
name (str) –

Chart name within the group (non-empty).

Returns:

Parameter ( Parameter ) –

The deserialized chart JSON.

Raises:

RuntimeError –

If the request fails or group/name are empty.

list_charts

list_charts(
    client: Client, group: Optional[str] = None
) -> TaskDataList

List charts attached to this task, optionally filtered to a group.

Parameters:

client (Client) –

The authenticated EdgeFirst client.
group (Optional[str], default: None ) –

Optional group name to filter charts.

Returns:

TaskDataList ( TaskDataList ) –

Charts keyed by group name.

Raises:

RuntimeError –

If the request fails.

set_stages

set_stages(
    client: Client, stages: List[Tuple[str, str]]
) -> None

Sets the stages of the task.

Parameters:

client (Client) –

The EdgeFirst client.
stages (List[Tuple[str, str]]) –

A list of tuples containing stage names and descriptions.

set_status

set_status(client: Client, status: str) -> None

Sets the status of the task.

Parameters:

client (Client) –

The EdgeFirst client.
status (str) –

The new status for the task.

update_stage

update_stage(
    client: Client,
    stage: str,
    status: str,
    message: str,
    percentage: int,
) -> None

Updates a specific stage of the task.

Parameters:

client (Client) –

The EdgeFirst client.
stage (str) –

The name of the stage to update.
status (str) –

The new status for the stage.
message (str) –

A message associated with the stage.
percentage (int) –

The completion percentage of the stage.

upload_data

upload_data(
    client: Client,
    path: Union[str, Path],
    folder: Optional[str] = None,
    progress: Optional[Callable[..., None]] = None,
) -> None

Upload a data file to this task.

Parameters:

client (Client) –

The authenticated EdgeFirst client.
path (Union[str, Path]) –

Local file path to upload.
folder (Optional[str], default: None ) –

Optional logical subdirectory under the task data root.
progress (Optional[Callable], default: None ) –
Optional progress callback. Supports two signatures:
- callback(current, total) — basic progress
- callback(current, total, status) — with status message
total equals the file size in bytes; current tracks bytes sent. status is always None for uploads.

Raises:

RuntimeError –

If the upload fails.

TrainerSchemaInfo

Catalog entry describing an available trainer type.

Returned by meth:Client.trainer_schemas. The schema_type value is what gets passed to meth:Client.trainer_schema and to meth:Client.start_training_session.

label `property`

label: str

Human-readable label shown in the Studio UI.

name `property`

name: str

Internal trainer name (e.g. "modelpack").

schema_type `property`

schema_type: str

Schema type identifier used for schema lookup and launch.

TrainingSession

A training session for a specific experiment, this represents the configuration and state of the training process.

dataset_params `property`

dataset_params: DatasetParams

Returns the dataset parameters used in the training session.

Returns:

DatasetParams ( DatasetParams ) –

The dataset parameters object.

description `property`

description: Optional[str]

Returns the description of the training session, if any.

Returns:

Optional[str] –

Optional[str]: The training session description or None.

experiment_id `property`

experiment_id: ExperimentID

Returns the ID of the experiment associated with this training session.

Returns:

ExperimentID ( ExperimentID ) –

The experiment ID.

id `property`

id: TrainingSessionID

Returns the unique identifier of the training session.

Returns:

TrainingSessionID ( TrainingSessionID ) –

The training session ID.

model `property`

model: str

Returns the model used in the training session.

Returns:

str ( str ) –

The model implementation name.

model_params `property`

model_params: Dict[str, Parameter]

Returns the model parameters used in the training session.

Returns:

Dict[str, Parameter] –

Dict[str, Parameter]: The model parameters.

name `property`

name: str

Returns the name of the training session.

Returns:

str ( str ) –

The training session name.

task `property`

task: Task

Returns the Docker task associated with the training session.

Returns:

Task ( Task ) –

The Docker task object.

uid `property`

uid: str

The unique string identifier for the object.

.. deprecated:: Use str(TrainingSession.id) instead. This property will be removed in a future version.

artifacts

artifacts(
    client: Optional[Client] = None,
) -> List[Artifact]

Returns a list of artifacts produced by the training session.

New API (v2.6.0+): Uses embedded client reference. Deprecated API: Pass client explicitly.

Parameters:

client (Optional[Client], default: None ) –

The EdgeFirst client. Deprecated - omit to use the embedded client reference.

Returns:

List[Artifact] –

List[Artifact]: A list of artifacts.

.. deprecated:: Passing client is deprecated and will be removed in v3.0.0. Use session.artifacts() instead.

download

download(
    filename_or_client: Union[str, Client],
    filename: Optional[str] = None,
) -> str

Downloads the specified file from the training session. This function requires the target file to only contain valid utf-8 as it is returned through a JSON response. To retrieve binary files use the client.download_artifact method instead.

New API (v2.6.0+): session.download(filename) Deprecated API: session.download(client, filename)

Parameters:

filename_or_client (Union[str, Client]) –

Either filename (new API) or Client (deprecated).
filename (Optional[str], default: None ) –

The filename when using deprecated API.

Returns:

str ( str ) –

The raw file data as a string.

.. deprecated:: Passing client is deprecated and will be removed in v3.0.0. Use session.download(filename) instead.

download_artifact

download_artifact(
    filename_or_client: Union[str, Client],
    filename: Optional[str] = None,
) -> bytes

Downloads the specified artifact file from the training session.

New API (v2.6.0+): session.download_artifact(filename) Deprecated API: session.download_artifact(client, filename)

Parameters:

filename_or_client (Union[str, Client]) –

Either filename (new API) or Client (deprecated).
filename (Optional[str], default: None ) –

The filename when using deprecated API.

Returns:

bytes ( bytes ) –

The raw file data as bytes.

.. deprecated:: Passing client is deprecated and will be removed in v3.0.0. Use session.download_artifact(filename) instead.

download_checkpoint

download_checkpoint(
    filename_or_client: Union[str, Client],
    filename: Optional[str] = None,
) -> bytes

Downloads the specified checkpoint file from the training session.

New API (v2.6.0+): session.download_checkpoint(filename) Deprecated API: session.download_checkpoint(client, filename)

Parameters:

filename_or_client (Union[str, Client]) –

Either filename (new API) or Client (deprecated).
filename (Optional[str], default: None ) –

The filename when using deprecated API.

Returns:

bytes ( bytes ) –

The raw file data as bytes.

.. deprecated:: Passing client is deprecated and will be removed in v3.0.0. Use session.download_checkpoint(filename) instead.

metrics

metrics(
    client: Optional[Client] = None,
) -> Dict[str, Parameter]

Returns the metrics associated with the training session.

New API (v2.6.0+): Uses embedded client reference. Deprecated API: Pass client explicitly.

Parameters:

client (Optional[Client], default: None ) –

The EdgeFirst client. Deprecated - omit to use the embedded client reference.

Returns:

Dict[str, Parameter] –

Dict[str, Parameter]: The training session metrics.

.. deprecated:: Passing client is deprecated and will be removed in v3.0.0. Use session.metrics() instead.

set_metrics

set_metrics(
    metrics_or_client: Union[Dict[str, Parameter], Client],
    metrics: Optional[Dict[str, Parameter]] = None,
) -> None

Sets the metrics for the training session.

New API (v2.6.0+): session.set_metrics(metrics) Deprecated API: session.set_metrics(client, metrics)

Parameters:

metrics_or_client (Union[Dict[str, Parameter], Client]) –

Either a metrics dict (new API) or Client (deprecated).
metrics (Optional[Dict[str, Parameter]], default: None ) –

The metrics dict when using deprecated API.

.. deprecated:: Passing client is deprecated and will be removed in v3.0.0. Use session.set_metrics(metrics) instead.

upload

upload(
    files_or_client: Union[
        List[Tuple[str, Union[str, Path]]], Client
    ],
    files: Optional[
        List[Tuple[str, Union[str, Path]]]
    ] = None,
) -> None

Uploads files to the training session. This can be used to upload model weights or other files that are needed for the training session.

The first element in the files tuple is the target name for the file while the second element is the local path to the file. The target name is the path where the file will be stored in the training session.

Artifacts must be uploaded to artifacts/*, checkpoints to checkpoints/*, while metrics should be uploaded to metrics/*.

New API (v2.6.0+): session.upload(files) Deprecated API: session.upload(client, files)

Parameters:

files_or_client (Union[List[Tuple[str, Union[str, Path]]], Client]) –

Either files list (new API) or Client (deprecated).
files (Optional[List[Tuple[str, Union[str, Path]]]], default: None ) –

The files list when using deprecated API.

.. deprecated:: Passing client is deprecated and will be removed in v3.0.0. Use session.upload(files) instead.

upload_artifact

upload_artifact(
    filename_or_client: Union[str, Client],
    filename_or_path: Optional[Union[str, Path]] = None,
    path: Optional[Union[str, Path]] = None,
) -> None

Uploads an artifact file to the training session.

New API (v2.6.0+): session.upload_artifact(filename, path) Deprecated API: session.upload_artifact(client, filename, path)

Parameters:

filename_or_client (Union[str, Client]) –

Either filename (new API) or Client (deprecated).
filename_or_path (Optional[Union[str, Path]], default: None ) –

Either path (new API) or filename (deprecated).
path (Optional[Union[str, Path]], default: None ) –

Local path to the artifact file (deprecated API only).

.. deprecated:: Passing client is deprecated and will be removed in v3.0.0. Use session.upload_artifact(filename, path) instead.

upload_checkpoint

upload_checkpoint(
    filename_or_client: Union[str, Client],
    filename_or_path: Optional[Union[str, Path]] = None,
    path: Optional[Union[str, Path]] = None,
) -> None

Uploads a checkpoint file to the training session.

New API (v2.6.0+): session.upload_checkpoint(filename, path) Deprecated API: session.upload_checkpoint(client, filename, path)

Parameters:

filename_or_client (Union[str, Client]) –

Either filename (new API) or Client (deprecated).
filename_or_path (Optional[Union[str, Path]], default: None ) –

Either path (new API) or filename (deprecated).
path (Optional[Union[str, Path]], default: None ) –

Local path to the checkpoint file (deprecated API only).

.. deprecated:: Passing client is deprecated and will be removed in v3.0.0. Use session.upload_checkpoint(filename, path) instead.

TrainingSessionID

Unique identifier for a training session within an experiment.

Training sessions represent individual training runs with specific hyperparameters and configurations. Can be constructed from an integer, a prefixed hex string (e.g., "t-abc123"), or another TrainingSessionID instance.

Examples:

>>> training_id = TrainingSessionID("t-abc123")
>>> training_id = TrainingSessionID(0xABC123)
>>> training_id = TrainingSessionID.from_str("t-abc123")
>>> int(training_id)
11256099
>>> str(training_id)
't-abc123'

Note

Internally a TrainingSessionID is an unsigned 64-bit integer. This class handles translating between integer and string representations of training session IDs.

UsageSummary

Billing usage summary for an organization.

credits `property`

credits: float

The organization's available credits.

funds `property`

funds: float

The organization's available funds.

total `property`

total: float

Total spendable balance (credits + funds).

ValidationSession

This class represents a validation session for a given model and dataset.

annotation_set_id `property`

annotation_set_id: AnnotationSetID

Returns the ID of the annotation set associated with this validation session.

Returns:

AnnotationSetID ( AnnotationSetID ) –

The annotation set ID.

dataset_id `property`

dataset_id: DatasetID

Returns the ID of the dataset associated with this validation session.

Returns:

DatasetID ( DatasetID ) –

The dataset ID.

description `property`

description: str

Returns the description of the validation session, if any.

Returns:

str ( str ) –

The validation session description or an empty string.

experiment_id `property`

experiment_id: ExperimentID

Returns the ID of the experiment associated with this validation session.

Returns:

ExperimentID ( ExperimentID ) –

The experiment ID.

id `property`

id: ValidationSessionID

Returns the unique identifier of the validation session.

Returns:

ValidationSessionID ( ValidationSessionID ) –

The validation session ID.

name `property`

name: str

Returns the name of the validation session.

Returns:

str ( str ) –

The validation session name.

params `property`

params: Dict[str, Parameter]

Returns the parameters associated with this validation session.

Returns:

Dict[str, Parameter] –

Dict[str, Parameter]: The validation session parameters.

task `property`

task: Task

Returns the Docker task associated with the validation session.

Returns:

Task ( Task ) –

The Docker task object.

training_session_id `property`

training_session_id: TrainingSessionID

Returns the ID of the training session associated with this validation session.

Returns:

TrainingSessionID ( TrainingSessionID ) –

The training session ID.

uid `property`

uid: str

Returns the unique string identifier of the validation session.

.. deprecated:: Use str(ValidationSession.id) instead. This property will be removed in a future version.

Returns:

str ( str ) –

The validation session UID.

artifacts

artifacts(
    client: Optional[Client] = None,
) -> List[Artifact]

Returns a list of artifacts produced by the validation session.

New API (v2.6.0+): Uses embedded client reference. Deprecated API: Pass client explicitly.

Note: Returns artifacts from the associated training session.

Parameters:

client (Optional[Client], default: None ) –

The EdgeFirst client. Deprecated - omit to use the embedded client reference.

Returns:

List[Artifact] –

List[Artifact]: A list of artifacts.

.. deprecated:: Passing client is deprecated and will be removed in v3.0.0. Use session.artifacts() instead.

data_list

data_list(client: Client) -> List[str]

List files attached to this validation session's data folder.

Parameters:

client (Client) –

The authenticated EdgeFirst client.

Returns:

List[str] –

List[str]: Flat list of relative file paths
List[str] –

(e.g. "folder/file.txt"), sorted lexicographically.

Raises:

RuntimeError –

If the request fails.

download_artifact

download_artifact(filename: str) -> bytes

Download an artifact file from the associated training session.

Parameters:

filename (str) –

Name of the artifact file to download (e.g., "labels.txt").

Returns:

bytes ( bytes ) –

The downloaded file content.

Raises:

TypeError –

If validation session has no client reference. Use client.download_artifact( validation_session.training_session_id, modelname) to download to disk (note: that variant writes to a file rather than returning bytes).

Example

data = validation_session.download_artifact("labels.txt")

download_checkpoint

download_checkpoint(filename: str) -> bytes

Download a checkpoint file from the associated training session.

Parameters:

filename (str) –

Name of the checkpoint file to download (e.g., "best.pt").

Returns:

bytes ( bytes ) –

The downloaded file content.

Raises:

TypeError –

If validation session has no client reference. Use client.download_checkpoint( validation_session.training_session_id, checkpoint) to download to disk (note: that variant writes to a file rather than returning bytes).

Example

data = validation_session.download_checkpoint("best.pt")

download_data

download_data(
    client: Client,
    filename: str,
    output_path: Union[str, Path],
    progress: Optional[Callable[..., None]] = None,
) -> None

Download a file from this validation session's data folder.

Parameters:

client (Client) –

The authenticated EdgeFirst client.
filename (str) –

Name of the file to download.
output_path (Union[str, Path]) –

Local path to write the downloaded file.
progress (Optional[Callable], default: None ) –
Optional progress callback. Supports two signatures:
- callback(current, total) — basic progress
- callback(current, total, status) — with status message

Raises:

RuntimeError –

If the download fails.

metrics

metrics(
    client: Optional[Client] = None,
) -> Dict[str, Parameter]

Returns the metrics associated with the validation session.

New API (v2.6.0+): Uses embedded client reference. Deprecated API: Pass client explicitly.

Parameters:

client (Optional[Client], default: None ) –

The EdgeFirst client. Deprecated - omit to use the embedded client reference.

Returns:

Dict[str, Parameter] –

Dict[str, Parameter]: The validation session metrics.

.. deprecated:: Passing client is deprecated and will be removed in v3.0.0. Use session.metrics() instead.

set_metrics

set_metrics(
    metrics_or_client: Union[Dict[str, Parameter], Client],
    metrics: Optional[Dict[str, Parameter]] = None,
) -> None

Sets the metrics for the validation session.

New API (v2.6.0+): session.set_metrics(metrics) Deprecated API: session.set_metrics(client, metrics)

Parameters:

metrics_or_client (Union[Dict[str, Parameter], Client]) –

Either a metrics dict (new API) or Client (deprecated).
metrics (Optional[Dict[str, Parameter]], default: None ) –

The metrics dict when using deprecated API.

.. deprecated:: Passing client is deprecated and will be removed in v3.0.0. Use session.set_metrics(metrics) instead.

upload_data

upload_data(
    client: Client,
    files: List[Tuple[str, Union[str, Path]]],
    folder: Optional[str] = None,
    progress: Optional[Callable[..., None]] = None,
) -> None

Upload files to this validation session's data folder.

Parameters:

client (Client) –

The authenticated EdgeFirst client.
files (List[Tuple[str, Union[str, Path]]]) –

List of (filename, path) tuples to upload. The path may be either a str or a pathlib.Path; PyO3 accepts any os.PathLike.
folder (Optional[str], default: None ) –

Optional logical subdirectory under the session data root.
progress (Optional[Callable], default: None ) –
Optional progress callback. Supports two signatures:
- callback(current, total) — basic progress
- callback(current, total, status) — with status message
total equals the sum of all file sizes in bytes; current tracks aggregate bytes sent across all files using a shared atomic counter. status is always None for uploads.

Raises:

RuntimeError –

If the upload fails.

ValidationSessionID

Unique identifier for a validation session within an experiment.

Validation sessions represent model validation runs that evaluate trained models against test datasets. Can be constructed from an integer, a prefixed hex string (e.g., "v-deadbeef"), or another ValidationSessionID instance.

Examples:

>>> validation_id = ValidationSessionID("v-deadbeef")
>>> validation_id = ValidationSessionID(0xDEADBEEF)
>>> validation_id = ValidationSessionID.from_str("v-deadbeef")
>>> int(validation_id)
3735928559
>>> str(validation_id)
'v-deadbeef'

Note

Internally a ValidationSessionID is an unsigned 64-bit integer. This class handles translating between integer and string representations of validation session IDs.

ValidatorSchema

A validator parameter schema, as returned by meth:Client.validator_schemas.

name `property`

name: str

Internal validator name.

schema `property`

schema: List[SchemaField]

The parameter field descriptors.

schema_type `property`

schema_type: str

Schema type identifier (matched against a model's trainer type).

VersionCurrentResponse

Response from the version current endpoint with serial, tags, and summary.

current_serial `property`

current_serial: int

The current changelog serial number.

dataset_id `property`

dataset_id: DatasetID

The dataset ID.

latest_tag `property`

latest_tag: Optional[VersionTag]

The most recent version tag, if any.

summary `property`

summary: Optional[DatasetSummary]

The dataset summary, if available.

tags `property`

tags: List[VersionTag]

All version tags for the dataset.

VersionTag

A version tag marking a specific point in a dataset's changelog history.

Version tags are immutable snapshots that record the dataset's state (image count, annotation counts, label count, etc.) at the time of creation. They can be used to query historical data or restore the dataset to a previous state.

annotation_counts `property`

annotation_counts: Dict[str, int]

Annotation counts by type (e.g., {"box": 150000}).

annotation_set_count `property`

annotation_set_count: int

Number of annotation sets at tag time.

created_at `property`

created_at: str

ISO 8601 timestamp of when this tag was created.

created_by `property`

created_by: str

The username that created this tag.

dataset_id `property`

dataset_id: DatasetID

The dataset this tag belongs to.

description `property`

description: str

The description of the version tag.

id `property`

id: int

The unique identifier for this version tag.

image_count `property`

image_count: int

Number of images at tag time.

is_current `property`

is_current: bool

Whether this tag is the dataset's current tag (i.e. matches Dataset.tag_id).

label_count `property`

label_count: int

Number of labels at tag time.

name `property`

name: str

The name of the version tag (e.g., "v1.0").

sensor_counts `property`

sensor_counts: Dict[str, int]

Sensor data counts by type (e.g., {"lidar": 25000}).

serial `property`

serial: int

The changelog serial number this tag references.

snapshot_id `property`

snapshot_id: Optional[int]

Optional snapshot export ID.

arrow_to_coco `builtin`

arrow_to_coco(
    arrow_path: Union[str, Path],
    output_path: Union[str, Path],
    include_masks: bool = True,
    groups: List[str] = Ellipsis,
    progress: Optional[Progress] = None,
) -> int

Convert EdgeFirst Arrow format to COCO dataset.

Arguments

arrow_path - Path to EdgeFirst Arrow file
output_path - Output COCO JSON file path
include_masks - Include segmentation masks (default: True)
groups - Filter by group names (empty list = all)
progress - Optional callback function(current, total) for progress

Returns

Number of annotations converted

coco_to_arrow `builtin`

coco_to_arrow(
    coco_path: Union[str, Path],
    output_path: Union[str, Path],
    include_masks: bool = True,
    group: Optional[str] = None,
    progress: Optional[Progress] = None,
    images_dir: Optional[Union[str, Path]] = None,
    link_images: bool = False,
) -> int

Convert COCO dataset to EdgeFirst Arrow format.

Arguments

coco_path - Path to COCO annotation JSON/ZIP or a standard extracted directory; directory inputs combine inferred train/val groups
output_path - Output Arrow IPC or Parquet file path (selected by extension)
include_masks - Include segmentation masks (default: True)
group - Optional group name for all samples (e.g., "train")
progress - Optional callback function(current, total) for progress
images_dir - Optional path to stage the referenced images from, producing a complete offline dataset next to output_path
link_images - Symlink staged images instead of copying (default: False)

Returns

Number of EdgeFirst rows written (including unannotated image placeholders)

collect_labels_from_samples `builtin`

collect_labels_from_samples(
    samples: List[Sample],
) -> Tuple[List[str], List[Optional[int]]]

Collect parallel label name/index arrays from samples, for use with Client.add_labels(dataset_id, names, indices).

Annotations without a label_index contribute None at the matching position. Raises an error if the same label name maps to conflicting indices across the samples.

Parameters:

samples (List[Sample]) –

Samples whose annotations should be scanned for labels.

Returns:

Tuple[List[str], List[Optional[int]]] –

Tuple[List[str], List[Optional[int]]]: Parallel label names and their (possibly absent) source indices.

Example

names, indices = collect_labels_from_samples(samples) client.add_labels(dataset_id, names, indices)

is_polars_enabled `builtin`

is_polars_enabled() -> bool

Check if the Polars feature is enabled in this build.

The Polars feature enables DataFrame support for annotations and other data structures. It is enabled at compile time with the 'polars' feature flag.

Returns:

bool –

True if Polars support is compiled in, False otherwise.

Examples:

>>> import edgefirst_client as ec
>>> if ec.is_polars_enabled():
...     df = client.samples_dataframe(dataset_id)
... else:
...     annotations = client.annotations(annotation_set_id)

version `builtin`

version() -> str

Get the version of the edgefirst_client library.

Returns:

str –

The version string (e.g., "0.3.0").

Examples:

>>> import edgefirst_client as ec
>>> print(ec.version())
0.3.0

Python API

AnnotationSetUID module-attribute

AppUID module-attribute

DatasetUID module-attribute

ExperimentUID module-attribute

ImageUID module-attribute

OrganizationUID module-attribute

ParameterDict module-attribute

ParameterValue module-attribute

Progress module-attribute

ProjectUID module-attribute

SampleUID module-attribute

SequenceUID module-attribute

SnapshotUID module-attribute

TaskUID module-attribute

TrainingSessionUID module-attribute

ValidationSessionUID module-attribute

__all__ module-attribute

__doc__ module-attribute

Annotation

box2d property

box2d_score property

box3d property

box3d_score property

category_frequency property

frame_number property

group property

iscrowd property

label property

label_index property

mask property

mask_score property

name property

object_id property

polygon property

polygon_score property

sample_id property

sequence_name property

__init__

set_box2d

set_box2d_score

set_box3d

set_box3d_score

set_category_frequency

set_frame_number

set_iscrowd

set_label

set_label_index

set_mask

set_mask_score

set_name

set_object_id

set_polygon

set_polygon_score

set_sample_id

set_sequence_name

AnnotationSet

created property

dataset_id property

description property

id property

name property

uid property

annotations

delete

AnnotationSetID

AnnotationType

AppId

Artifact

model_type property

name property

BackgroundTaskID

Box2d

cx property

cy property

height property

left property

top property

width property

__init__

AnnotationSetUID `module-attribute`

AppUID `module-attribute`

DatasetUID `module-attribute`

ExperimentUID `module-attribute`

ImageUID `module-attribute`

OrganizationUID `module-attribute`

ParameterDict `module-attribute`

ParameterValue `module-attribute`

Progress `module-attribute`

ProjectUID `module-attribute`

SampleUID `module-attribute`

SequenceUID `module-attribute`

SnapshotUID `module-attribute`

TaskUID `module-attribute`

TrainingSessionUID `module-attribute`

ValidationSessionUID `module-attribute`

all `module-attribute`

doc `module-attribute`

box2d `property`

box2d_score `property`

box3d `property`

box3d_score `property`

category_frequency `property`

frame_number `property`

group `property`

iscrowd `property`

label `property`

label_index `property`

mask `property`

mask_score `property`

name `property`

object_id `property`

polygon `property`

polygon_score `property`

sample_id `property`

sequence_name `property`

init

created `property`

dataset_id `property`

description `property`

id `property`

name `property`

uid `property`

model_type `property`

name `property`

cx `property`

cy `property`

height `property`

left `property`

top `property`

width `property`

init

cx `property`

cy `property`

cz `property`

front `property`

height `property`

left `property`

length `property`

top `property`

width `property`

init

change_data `property`

created_at `property`

dataset_id `property`

entity_id `property`

entity_type `property`

id `property`

message `property`

operation `property`

organization_id `property`

s3_version_ids `property`

serial `property`

username `property`

continue_token `property`

count `property`

entries `property`

from_serial `property`

to_serial `property`

server `property`