roboto.experimental.sessions#

Compose sessions: the operational time windows of a device, and the files that belong to them.

A session can be created empty and composed file by file, or declared whole, with its files and the topic data they carry, in one call. The types describing a file’s contents live in roboto.experimental.ingest.

Submodules#

Package Contents#

class roboto.experimental.sessions.CompletionPolicy(/, **data)#

Bases: pydantic.BaseModel

When Roboto marks a session complete on its own.

A session’s completion policy is set when the session is created and can be changed with an update. Roboto marks the session complete once inactivity_minutes have passed since a file was last added to it, or since the policy was changed, whichever is later. A session that no file has been added to yet is not completed this way. Adding a file to a session Roboto completed puts it back in progress, and Roboto marks it complete again after the same inactivity.

Parameters:

data (Any)

inactivity_minutes: int#

Minutes without a new file after which Roboto marks the session complete.

model_config#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class roboto.experimental.sessions.CreateSessionIfNotExistsRequest(/, **data)#

Bases: pydantic.BaseModel

Request body for POST /v1/sessions/create_if_not_exists.

Parameters:

data (Any)

create_request: CreateSessionRequest#

The session to create when none matches.

match_roboql_query: str#

RoboQL query over sessions. The first matching session is returned instead of creating one.

class roboto.experimental.sessions.FileDeclaration(/, **data)#

Bases: pydantic.BaseModel

One already-uploaded file and the topic data it carries.

Everything here is true of the file and its recording whether or not any session ever names it, which is why declare_topics() can state the same facts without naming a session. SessionFile adds the one fact only a session can state: the window of the file’s data that session holds.

A file may contribute to any number of topics (a LeRobot parquet file typically carries several as columns of the same rows); declare them all on the one declaration for that file.

Data range (data_range):

  • Use when one file is shared by several sessions and its own timestamps cannot tell the shared parts apart (for example, a LeRobot v3 data file, whose episodes each restart their timestamp column at 0). When they can tell them apart, name the slice by time instead, with the time window on SessionFile.

  • (start, end): start is the first covered position; end is one past the last. Values are in the file’s own units: stored-row positions (counted from 0), or nanoseconds of media time for video.

  • Leaving it unset covers the whole file.

  • Each topic’s data in a file is stored as one or more partitions, and a topic declared over a range is registered as a partition over that range. Reading it returns only the positions in that range: a topic declared over (8, 20) of a 20-row file reads back 12 rows, not the file’s 20.

  • Inside a session the range also decides which of the file’s partitions the session admits; see SessionFile.

Parameters:

data (Any)

anchor_ns: roboto.time._EpochNanosecondsFromTime | None#

the real-world time, in nanoseconds since the Unix epoch, at which that data’s time 0 occurred. It covers exactly what the declaration names, the slice named by data_range or the whole file when none is named, so a file holding several slices can give each of them the instant it happened. Must fall after the Unix epoch, and be small enough to fit in the signed 64-bit integer the platform stores it in. Also accepts any roboto.time.Time at runtime, converted as roboto.time.to_epoch_nanoseconds() converts it: an int is nanoseconds, a float, Decimal, or numeric string is seconds, and a datetime or ISO 8601 string is that instant. The field is typed int, so convert with that function first to satisfy a type checker. When omitted on a declaration inside a SessionDeclaration, the declaration takes that session’s anchor_ns if one is set: None means “inherit”, not “no anchor”, so a declaration cannot opt out of a session-level anchor. With no anchor from either level, the data this declaration names keeps the anchor it already carries from an earlier declaration, and keeps an offset of 0 when it carries none: its timestamps read exactly as declared. Nothing is inherited across slices: a slice with no anchor of its own never takes on a neighbor’s instant, however the file’s other slices are anchored.

Type:

Optional wall-clock anchor for the data this declaration names

data_range: roboto.domain.topics.record.DataRange | None = None#

The slice of the file this declaration describes, or None for the whole file.

file_id: str#

Identifier of the already-uploaded file this declaration describes.

model_config#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

topics: list[roboto.experimental.ingest.TopicDeclaration]#

Topics this file contributes data to, each over the part of the file that carries it. Every topic sits inside the slice this declaration names: one declaring no data_range of its own covers all of it, and one declaring a range must sit within it. A topic and the slice it names identify one partition of the file, so each is declared at most once here. A topic’s data is read from the files the topic lists in representations, and from this file only when the topic lists it there.

roboto.experimental.sessions.MAX_INGESTION_SUMMARIES = 100#

Most sessions one POST /v1/sessions/ingestion/summaries takes.

roboto.experimental.sessions.MAX_SESSIONS_PER_REQUEST = 100#

Cap on the number of sessions one request may declare on a device; split a larger batch across several calls.

CreateSessionsRequest applies the cap when the request body is constructed, and the platform applies it again on arrival, so a body built by hand cannot exceed it either.

class roboto.experimental.sessions.PendingIngestionFile(/, **data)#

Bases: pydantic.BaseModel

A file in a session that is ingestable and not ingested yet.

Parameters:

data (Any)

file_id: str#

ID of the file.

ingestion_status: roboto.domain.files.IngestionStatus#

not at all, or partly.

Type:

How much of the file’s current version is ingested

last_run: roboto.experimental.ingestion_runs.IngestionRun | None = None#

The latest time an ingestion rule’s trigger ran on the file. None when none has.

relative_path: str#

Path of the file within its dataset, device, or org.

uploaded: datetime.datetime | None = None#

When the file’s current version was uploaded.

class roboto.experimental.sessions.Session(record, roboto_client=None)#

An operational time window of a Device.

A Session is a drone flight, a vehicle drive, a robot arm test run: some contiguous activity in the real world. It groups the recordings, logs, and other data produced during that window. Because a Session is bounded by the activity rather than by the recordings, it can span many files or cover just a slice of one. Each file it includes can be narrowed to a sub-window of that file.

The Session’s aggregate bounds, min_timestamp_ns and max_timestamp_ns in Unix-epoch nanoseconds, span every file the Session includes. Roboto recomputes them whenever the Session’s files or the anchors of their data change, and each method of this class that makes such a change returns with the updated bounds.

A Session can reference one or many devices: a single drone for a solo mission, or all of the drones in a formation flight. Use attach_to_device() and detach_from_device() to change which devices it references.

How to create a Session:

  • Session.create() accepts zero, one, or many devices, and does not require a name.

  • create_session() creates one named Session on a device, optionally declaring its files and topics in the same call.

  • create_sessions() creates many such Sessions on a device in one call.

  • create_session() creates a Session for an existing Dataset, inferring the devices involved and pre-populating files from the Dataset.

Once created, include files with add_file() or add_files().

Examples

Create a Session for a drone flight, include a recording, and list its topics:

>>> from roboto.experimental.sessions import Session
>>> session = Session.create(name="flight-2026-04-23-001", device_ids=["robot-abc"])
>>> session.add_file("fl_0123456789abcdef")
>>> for topic in session.list_topics():
...     print(topic.name)
Parameters:
add_file(file, data_range=None, min_file_timestamp_ns=None, max_file_timestamp_ns=None, anchor=None, topics=None)#

Include a single file in this Session, with whatever topic data it carries.

The singular form of add_files(), taking the fields of one SessionFile as separate arguments. That class documents what each field means; add_files() documents what the platform does with them.

Parameters:

  • file (Union[roboto.domain.files.File, str]) – A File or a file ID.

  • data_range (Optional[roboto.domain.topics.record.DataRange]) – Slice of the file this Session holds, or None for the whole file.

  • min_file_timestamp_ns (Optional[int]) – Optional lower bound of the part of the file to include, in the file’s own timestamps. Must be paired with max_file_timestamp_ns.

  • max_file_timestamp_ns (Optional[int]) – Optional upper bound paired with min_file_timestamp_ns.

  • anchor (Optional[roboto.time.Time]) – Optional wall-clock instant at which time 0 of the data added here occurred: an int of nanoseconds since the Unix epoch, or any other Time, read as to_epoch_nanoseconds() reads it (a datetime or ISO 8601 string is that instant; a float, Decimal, or numeric string is seconds since the epoch). Must fall after the Unix epoch.

  • topics (Optional[collections.abc.Sequence[roboto.experimental.ingest.TopicDeclaration]]) – Topics this file contributes data to, over the part of the file that carries them. Each lists the files a read of its data opens in representations.

Returns:

The file’s place in this Session, as list_files() reports it.

Raises:

  • TypeError – anchor is not one of the Time types.

  • ValueError – anchor is a boolean, a string that is neither seconds nor ISO 8601, or a negative number (an int, float, Decimal, or numeric string); rejected client-side, before any request is made.

  • OverflowError – anchor is infinite, such as float("inf"); rejected client-side, before any request is made.

  • pydantic.ValidationError – The arguments break a rule SessionFile enforces, such as an anchor at or before the Unix epoch or a time window with only one of its two bounds, or the representations listed in topics name one file in two storage formats; rejected client-side, before any request is made. The rules for one topic’s own representations are enforced earlier, when the caller builds its TopicDeclaration.

  • RobotoInvalidRequestException – With the anchor covering it added, the file’s data or the window stated here would fall before the Unix epoch or past the largest storable Unix-epoch nanosecond value, or the anchor would move a window another Session declared over the same data there. Anchor the data at the instant it was recorded.

  • RobotoDomainException – Whatever else the platform refused this file with.

Return type:

roboto.experimental.sessions.record.SessionFileView

Examples

Include a whole file:

>>> session.add_file("fl_0123456789abcdef")

Include only a sub-window of a file:

>>> session.add_file(
...     "fl_0123456789abcdef",
...     min_file_timestamp_ns=0,
...     max_file_timestamp_ns=60_000_000_000,
... )
add_files(files)#

Include the given files in this Session, with whatever topic data they carry.

Each entry states one file’s place in this Session, in the same terms a SessionDeclaration states the files of a Session declared whole, so a Session composed file by file can say everything a declared one says.

The platform decides every refusal before adding anything, so an entry it refuses leaves the others added, while a failure it did not anticipate, such as a timeout, adds none of them. Resending converges on the same composition rather than duplicating it. The platform then recomputes this Session’s aggregate bounds across every file it includes, and this instance reflects the new min_timestamp_ns / max_timestamp_ns on return.

Parameters:

files (collections.abc.Sequence[roboto.experimental.sessions.operations.SessionFile]) – Files to include in the Session, each appearing exactly once and listing all of its topics; SessionFile documents what one entry states, including how the window it names survives re-anchoring the file. An empty sequence returns an empty response without contacting the platform.

Returns:

One element per entry, in request order, holding either the file’s place in this Session or why the platform refused it.

Raises:

  • pydantic.ValidationError – The sequence names a file more than once, declares more than MAX_FILES_AND_TOPICS_PER_REQUEST files and topics between them, or lists representations naming one file in two storage formats; rejected client-side, before any request is made.

  • RobotoNotFoundException – A file an entry names, or a file one of its topics’ representations names, does not exist in this Session’s org or has a status other than Available. Nothing is added.

  • RobotoUnauthorizedException – The caller lacks permission to manage Sessions in the org that owns this Session, cannot edit a file an entry declares topics on, a file it anchors, or a file a listed representation names, or lacks topic edit access in that org while an entry states is_default_for_reads on a timeline source. Nothing is added.

Return type:

roboto.http.BatchResponse[roboto.experimental.sessions.record.SessionFileView]

Examples

>>> from roboto.experimental.sessions import SessionFile
>>> added = session.add_files(
...     [
...         SessionFile(file_id="fl_aaa"),
...         SessionFile(
...             file_id="fl_bbb",
...             min_file_timestamp_ns=0,
...             max_file_timestamp_ns=60_000_000_000,
...         ),
...     ]
... )
>>> print([view.file_id for view in added.succeeded])
attach_to_device(device_id)#

Attach a Device to this Session as a subject.

A Session may have many device attachments. For example, a formation flight where multiple drones operate within a single activity window.

Parameters:

device_id (str) – ID of the Device to add as a subject of this Session.

Raises:

RobotoNotFoundException – The Device does not exist in this Session’s org, or the Session no longer exists.

Return type:

None

Examples

>>> session.attach_to_device("wingman")
>>> list(session.list_devices())
['lead', 'wingman']
clear_custom_field(name)#

Clear a single custom-field value on this session to None.

Parameters:

name (str)

Return type:

Session

clear_custom_fields(names)#

Clear multiple custom-field values on this session to None.

Parameters:

names (collections.abc.Sequence[str])

Return type:

Session

clear_unix_offset()#

Return this Session’s data to an offset of 0.

Removes the wall-clock anchor from all of this Session’s topic data, so the Session’s bounds return to their stored values, read as nanoseconds since the Unix epoch with nothing added.

Clearing reaches this Session’s data and no more, exactly the data set_unix_offset() writes.

Any anchoring state can be cleared, and repeating the call changes nothing: clearing a Session that carries no anchor, or has no topic data at all, is a successful no-op, and a Session made of slices anchored at several different instants is still cleared, each slice moving back by its own offset.

Returns:

This Session, refreshed with recomputed aggregate bounds.

Raises:

  • RobotoInvalidRequestException – Returning the data to an offset of 0 would start it, or a time range declared over it, before the Unix epoch. Data starts there when its own timestamps are negative; a range starts there when it begins earlier than its data’s anchor.

  • RobotoConflictException – A concurrent writer added files to the Session while the clear was being applied; retry the call.

  • RobotoNotFoundException – The Session no longer exists.

  • RobotoUnauthorizedException – The caller lacks permission to manage Sessions in the org that owns this Session.

Return type:

Session

Examples

The recomputed bounds return to the Session’s stored values:

>>> session.min_timestamp_ns
1700000000250000000
>>> session = session.clear_unix_offset()
>>> session.min_timestamp_ns
250000000
complete()#

Mark this Session complete: declare that all of its files have been added.

Once it is complete, the platform announces the session.ingested platform event, which triggers can subscribe to, as soon as every ingestable file in the Session is ingested. A file is ingestable when its path matched one of the org’s ingestion rules when its current version was created, or it has since been partly or fully ingested. Files that are not ingestable never delay the announcement.

Adding a file to a complete Session puts it back in progress; mark it complete again once the new files are added. If its ingestable files change while it stays complete (a new version, a file removed or deleted), it is announced again once they are all ingested. Marking a complete Session complete changes nothing.

Returns:

This Session, refreshed from the server response.

Return type:

Session

Examples

>>> session.add_file("fl_0123456789abcdef")
>>> session = session.complete()
>>> session.status is SessionStatus.Complete
True
property completes_at: datetime.datetime | None#

When Roboto will mark this Session complete unless another file is added first, per its completion_policy.

None while the Session is complete, has no completion policy, or has no files.

Return type:

Optional[datetime.datetime]

property completion_policy: roboto.experimental.sessions.record.CompletionPolicy | None#

When Roboto marks this Session complete on its own, or None if it is marked complete only by complete().

Return type:

Optional[roboto.experimental.sessions.record.CompletionPolicy]

classmethod create(name=None, device_ids=(), description=None, metadata=None, tags=None, custom_fields=None, caller_org_id=None, roboto_client=None, completion_policy=NotSet)#

Create a new Session, optionally associating it with one or more devices.

Every call creates a new Session. For the common single-device case, prefer create_session(), which identifies the Session by name so a resend converges on the Session it already created. To add devices to an existing Session later, see attach_to_device().

Parameters:

  • name (Optional[str]) – Optional short name for the Session (max 120 characters).

  • device_ids (collections.abc.Sequence[str]) – Devices to associate with the Session at creation. Empty (the default) creates a Session with no associated devices.

  • description (Optional[str]) – Optional description of the Session.

  • metadata (Optional[dict[str, Any]]) – Optional initial metadata. Sessions are not filterable or sortable by metadata keys; for queryable structured attributes, define a custom field on the Session entity type.

  • tags (Optional[collections.abc.Sequence[str]]) – Optional initial tags. Sessions can be filtered by tag membership but are not sortable by tag.

  • custom_fields (Optional[dict[str, Any]]) – Optional initial values for Ready custom fields defined on Sessions in the caller’s org. Keys must match Ready field names; values must satisfy each field’s declared type.

  • caller_org_id (Optional[str]) – Caller’s org scope. Required when the caller belongs to multiple orgs.

  • roboto_client (Optional[roboto.http.RobotoClient]) – Optional RobotoClient; defaults to the ambient one.

  • completion_policy (Union[roboto.experimental.sessions.record.CompletionPolicy, None, roboto.sentinels.NotSetType]) – When Roboto marks the Session complete on its own. Left unset, the Session gets the org’s default completion policy, if an org admin has set one, and completion_policy on the returned Session shows the policy applied. None means the Session is marked complete only by complete(), whatever the org’s default. Change it later with update().

Returns:

The created Session.

Raises:

RobotoNotFoundException – A device in device_ids does not exist in the caller’s org. No Session is created.

Return type:

Session

Examples

>>> from roboto.experimental.sessions import Session
>>> session = Session.create(
...     name="flight-2026-04-23-001",
...     device_ids=["robot-a", "robot-b"],
...     description="formation flight #4",
...     metadata={"pilot": "alice"},
...     tags=["pre-flight-check"],
... )
classmethod create_if_not_exists(match_roboql_query, name=None, device_ids=(), description=None, metadata=None, tags=None, custom_fields=None, completion_policy=NotSet, caller_org_id=None, roboto_client=None)#

Return the first Session matching a RoboQL query, creating one when none matches.

Concurrent calls with the same query create one Session between them, so a process handling one file at a time (such as an S3 event handler) can use it to put each file into the Session it belongs to.

The Session created must match match_roboql_query. If name, tags and the other arguments describe a Session the query does not match, every later call creates another one.

When several Sessions match, which one is returned is not defined unless the query ends with a SORT BY clause, e.g. name = 'flight-0042' SORT BY session_id.

A matching Session is returned as it is: the arguments below apply only to a Session this call creates, so completion_policy and the rest are ignored on a match. Use update() to change a matched Session. The Session returned may be complete; adding a file to it puts it back in progress. To match only Sessions in progress, add AND status = 'in_progress' to the query.

Parameters:

  • match_roboql_query (str) – RoboQL query over Sessions, e.g. name = 'flight-0042'.

  • name (Optional[str]) – Name of the Session to create when none matches.

  • device_ids (collections.abc.Sequence[str]) – Devices to associate with a created Session.

  • description (Optional[str]) – Description of a created Session.

  • metadata (Optional[dict[str, Any]]) – Metadata of a created Session.

  • tags (Optional[collections.abc.Sequence[str]]) – Tags of a created Session.

  • custom_fields (Optional[dict[str, Any]]) – Custom-field values of a created Session.

  • completion_policy (Union[roboto.experimental.sessions.record.CompletionPolicy, None, roboto.sentinels.NotSetType]) – Completion policy of a created Session; see create().

  • caller_org_id (Optional[str]) – Caller’s org scope. Required when the caller belongs to multiple orgs.

  • roboto_client (Optional[roboto.http.RobotoClient]) – Optional RobotoClient; defaults to the ambient one.

Returns:

The matching or created Session.

Raises:

RobotoServiceUnavailableException – Other calls with the same query kept this one waiting for more than 10 seconds, after the SDK’s own retries. Calling again is safe.

Return type:

Session

Examples

>>> from roboto.experimental.sessions import CompletionPolicy, Session
>>> session = Session.create_if_not_exists(
...     "name = 'flight-0042'",
...     name="flight-0042",
...     completion_policy=CompletionPolicy(inactivity_minutes=15),
... )
>>> session.add_file("fl_0123456789abcdef")
property created: datetime.datetime | None#

UTC timestamp when this Session was created.

Return type:

Optional[datetime.datetime]

property created_by: str#

Identifier of the user or service which created this Session.

Return type:

str

property custom_fields: dict[str, Any]#

Custom-field values defined on Sessions in this org.

Every Ready CustomField for the org appears as a key. Values that have not been set on this session surface as None rather than being absent. Empty when no custom fields are defined for the org.

A Timestamp value is returned as an ISO 8601 string.

Return type:

dict[str, Any]

delete()#

Delete this Session. The files it included and the devices attached to it are not deleted.

Return type:

None

property description: str | None#

Optional description of this Session.

Return type:

Optional[str]

detach_from_device(device_id)#

Remove a Device from this Session’s subjects.

Parameters:

device_id (str) – ID of the Device to remove as a subject of this Session.

Return type:

None

classmethod for_dataset(dataset_id, roboto_client=None)#

Iterate Sessions whose composition includes any file in the given dataset.

Parameters:

  • dataset_id (str) – Dataset whose sessions to list.

  • roboto_client (Optional[roboto.http.RobotoClient]) – Optional RobotoClient; defaults to the ambient one.

Yields:

Sessions, one at a time, following pagination automatically.

Return type:

collections.abc.Generator[Session, None, None]

Examples

>>> from roboto.experimental.sessions import Session
>>> for session in Session.for_dataset("ds_abc"):
...     print(session.session_id, session.name)
classmethod for_org(org_id=None, roboto_client=None)#

Iterate all Sessions visible to the caller’s org.

Parameters:

  • org_id (Optional[str]) – Caller’s org scope. Required when the caller belongs to multiple orgs.

  • roboto_client (Optional[roboto.http.RobotoClient]) – Optional RobotoClient; defaults to the ambient one.

Yields:

Sessions, one at a time, following pagination automatically.

Return type:

collections.abc.Generator[Session, None, None]

classmethod from_id(session_id, roboto_client=None)#

Load a Session by ID.

Parameters:

  • session_id (str) – Session primary key.

  • roboto_client (Optional[roboto.http.RobotoClient]) – Optional RobotoClient; defaults to the ambient one.

Returns:

The Session.

Raises:
Return type:

Session

Examples

>>> from roboto.experimental.sessions import Session
>>> session = Session.from_id("se_abc123")
>>> session.name
'flight-2026-04-23-001'
get_topic(topic_name)#

Return the named Topic, scoped to this Session.

The returned Topic is scoped to this Session’s associated files and defaults its read window to this Session’s aggregate bounds, so get_data* reads just this Session’s data without an explicit window.

Parameters:

topic_name (str) – Exact name of the topic to retrieve (e.g. "/camera/image").

Returns:

The matching Topic.

Raises:

  • RobotoNotFoundException – No topic with topic_name is reachable from this Session (the topic is absent from the org, or this Session holds none of its data).

  • RobotoUnauthorizedException – The caller lacks permission to view Sessions in the org that owns this Session.

Return type:

roboto.experimental.topics.Topic

Examples

>>> topic = session.get_topic("/camera/image")
>>> for timestamp, record in topic.get_data():
...     print(timestamp, record)
property ingestion_count: int#

How many times this Session has been announced ingested.

Return type:

int

ingestion_status()#

Return where this Session stands in ingestion, with the files it is still waiting on.

Returns:

The current status. It does not refresh this Session instance.

Return type:

roboto.experimental.sessions.record.SessionIngestionStatus

Examples

>>> status = session.ingestion_status()
>>> status.state
<SessionIngestionState.Processing: 'processing'>
>>> [f.relative_path for f in status.pending_files]
['flight_002.mcap']
classmethod ingestion_summaries(session_ids, org_id=None, roboto_client=None)#

Where each of many Sessions stands in ingestion, in counts, a hundred Sessions per request.

Cheaper than ingestion_status() on each Session for finding which of many are stuck: a summary has no file lists, only counts, including how many waiting files failed to ingest.

Parameters:

  • session_ids (collections.abc.Sequence[str]) – Sessions in the caller’s org. Others are left out of the result.

  • org_id (Optional[str]) – Caller’s org scope. Required when the caller belongs to multiple orgs.

  • roboto_client (Optional[roboto.http.RobotoClient]) – Optional RobotoClient; defaults to the ambient one.

Returns:

One summary per Session found, in request order.

Return type:

list[roboto.experimental.sessions.record.SessionIngestionSummary]

Examples

>>> summaries = Session.ingestion_summaries(["se_abc123", "se_def456"])
>>> [s.session_id for s in summaries if s.failed_file_count]
['se_def456']
list_devices()#

Iterate the device IDs attached as subjects of this Session, paginated.

Return type:

collections.abc.Generator[str, None, None]

list_files()#

Iterate the files this Session includes, following pagination automatically.

Yields:

SessionFileView entries, each carrying the part of the file this Session holds (the optional data_range slice and min_wall_clock_timestamp_ns / max_wall_clock_timestamp_ns window), the unix_epoch_offset_ns the platform added to reach that window, and display fields of the file itself (name, dataset, tags, size, …).

Return type:

collections.abc.Generator[roboto.experimental.sessions.record.SessionFileView, None, None]

list_metrics()#

Return all metrics published to this Session.

Returns:

List of Metric instances for this Session.

Return type:

list[roboto.domain.metrics.metric.Metric]

Examples

>>> metrics = session.list_metrics()
>>> for m in metrics:
...     print(m.name, m.value)
list_topics()#

Iterate the topics reachable from this Session, following pagination.

A topic is yielded only when this Session holds some of its data: a time span of the topic (TimelineExtentRecord) on one of the Session’s files, inside the slice the Session holds of that file and overlapping the time window it holds. Each topic is yielded once however many files and partitions carry it, ordered by name with topic_id as a deterministic tiebreaker.

A yielded Topic is scoped to this Session’s files and defaults its read window to this Session’s aggregate bounds, so get_data() (and the other get_data* methods) read just this Session’s data without an explicit window.

Yields:

Topic instances.

Return type:

collections.abc.Generator[roboto.experimental.topics.Topic, None, None]

Examples

>>> for topic in session.list_topics():
...     for timestamp, record in topic.get_data():
...         print(topic.name, timestamp, record)
property max_timestamp_ns: int | None#

Latest time covered by this Session, in Unix-epoch nanoseconds.

None while the Session includes no files, or only files added without a time window whose topic data has no time span registered yet.

Return type:

Optional[int]

property metadata: dict[str, Any]#

User-supplied metadata attached to this Session.

Sessions are not filterable or sortable by metadata keys. For queryable structured attributes on a Session, define a custom field on the Session entity type.

Return type:

dict[str, Any]

property min_timestamp_ns: int | None#

Earliest time covered by this Session, in Unix-epoch nanoseconds.

None while the Session includes no files, or only files added without a time window whose topic data has no time span registered yet.

Return type:

Optional[int]

property modified: datetime.datetime | None#

UTC timestamp when this Session was last modified.

Return type:

Optional[datetime.datetime]

property modified_by: str#

Identifier of the user or service which last modified this Session.

Return type:

str

property name: str | None#

Optional short name of this Session.

Return type:

Optional[str]

property org_id: str#

Identifier of the organization that owns this Session.

Return type:

str

publish_metrics(metrics, device_id=NotSet)#

Record metric values for this Session in a single network call.

Convenience wrapper around publish() that supplies this Session’s session_id and org_id. Republishing a metric under the same name replaces its previous value for this Session.

If a metric definition does not already exist for a given name it is created automatically.

Parameters:

  • metrics (list[roboto.domain.metrics.record.MetricEntry]) – Metric names and numeric values to record.

  • device_id (Union[roboto.sentinels.NotSetType, Optional[str]]) – Device to associate with each published value, or None to opt out. When omitted, the server infers a device from this Session’s attached devices: the call succeeds only if exactly one device is associated and is rejected when zero or more than one are.

Returns:

One element per metric entry, in request order, holding either the recorded Metric or why the platform refused it.

Raises:

RobotoInvalidRequestException – device_id was omitted and this Session has zero or more than one attached devices.

Return type:

roboto.http.BatchResponse[roboto.domain.metrics.metric.Metric]

Examples

Let the server infer the device from this Session’s single attached device:

>>> from roboto.domain.metrics import MetricEntry
>>> published = session.publish_metrics(
...     [
...         MetricEntry(name="cpu.usage_max", value=87.2),
...         MetricEntry(name="memory.peak_mb", value=2048.0),
...     ]
... )
>>> len(published.succeeded)
2

Attach to an explicit device, overriding inference:

>>> session.publish_metrics(
...     [MetricEntry(name="cpu.usage_max", value=87.2)],
...     device_id="robot01",
... )
put_metadata(metadata)#

Add or update metadata fields on this Session.

Parameters:

metadata (dict[str, Any]) – Field-to-value map. Existing fields are overwritten; fields not in this map are left unchanged.

Returns:

This Session, refreshed from the server response.

Return type:

Session

Examples

>>> session.put_metadata({"weather": "clear", "pilot": "alice"})
put_tags(tags)#

Add tags to this Session.

Tags already present on the Session are not duplicated.

Parameters:

tags (roboto.updates.StrSequence) – Tags to add.

Returns:

This Session, refreshed from the server response.

Return type:

Session

Examples

>>> session.put_tags(["pre-flight-check", "training"])
property record: roboto.experimental.sessions.record.SessionRecord#

Underlying data record for this Session.

Return type:

roboto.experimental.sessions.record.SessionRecord

refresh()#

Re-read this Session from the platform, replacing every property backed by its record.

Call it when something other than this instance changed the Session: the aggregate bounds min_timestamp_ns and max_timestamp_ns are recomputed whenever a Session’s composition or anchoring changes, including by another caller.

Returns:

This Session.

Return type:

Session

remove_file(file)#

Remove a single file from this Session.

The singular form of remove_files().

Parameters:

file (Union[roboto.domain.files.File, str]) – A File or a file ID.

Returns:

The ID of the removed file.

Raises:

RobotoNotFoundException – This Session does not hold the file.

Return type:

str

remove_files(files)#

Remove the given files from this Session.

A file this Session does not hold is reported as its own element rather than failing the call, while a failure the platform did not anticipate, such as a timeout, removes none of the files. The platform then recomputes this Session’s aggregate bounds across the files that remain, and this instance reflects the new min_timestamp_ns / max_timestamp_ns on return.

Parameters:

files (collections.abc.Sequence[Union[roboto.domain.files.File, str]]) – Files to remove, each a File or a file ID. An empty sequence returns an empty response without contacting the platform.

Returns:

One element per named file, in request order, holding either its ID or why the platform refused to remove it.

Raises:

pydantic.ValidationError – The sequence names a file more than once, or names more than MAX_FILES_AND_TOPICS_PER_REQUEST files; rejected client-side, before any request is made.

Return type:

roboto.http.BatchResponse[str]

remove_metadata(metadata)#

Remove metadata keys from this Session.

Parameters:

metadata (roboto.updates.StrSequence) – Metadata keys to remove. Dot notation addresses nested keys ("weather.condition").

Returns:

This Session, refreshed from the server response.

Return type:

Session

Examples

>>> session.remove_metadata(["pilot", "weather.condition"])
remove_tags(tags)#

Remove the given tags from this Session.

Parameters:

tags (roboto.updates.StrSequence) – Tags to remove. Tags not present on the Session are silently ignored.

Returns:

This Session, refreshed from the server response.

Return type:

Session

Examples

>>> session.remove_tags(["training"])
property session_id: str#

Globally unique identifier assigned to this Session on creation.

Return type:

str

set_custom_field(name, value)#

Set a single custom-field value on this session.

name must be the name of a Ready custom field for this session’s org and the Session entity type; value must satisfy the field’s declared type.

Parameters:

  • name (str)

  • value (Any)

Return type:

Session

set_custom_fields(fields)#

Set or overwrite multiple custom-field values on this session.

Each key must name a Ready custom field for this session’s org and the Session entity type; each value must satisfy the field’s declared type.

Parameters:

fields (dict[str, Any])

Return type:

Session

set_unix_offset(anchor)#

Anchor this Session’s data to wall-clock time.

anchor becomes the wall-clock instant of stored time 0 for all of this Session’s topic data, and the Session’s aggregate bounds are recomputed to reflect it.

This write reaches this Session’s data and no more. Where several Sessions share one file, each owning a slice of it, it anchors the slices this Session holds and leaves the file’s other slices at whatever instant they were given. Data another Session also holds is shared, not copied, so that Session reads the same anchor.

An anchor exists only when a caller supplies one, either as the data is added (the anchor argument of add_file(), or anchor_ns on a SessionFile) or through this method. Until then, the data carries an offset of 0 and its stored timestamps are read as nanoseconds since the Unix epoch. Applying an anchor overwrites whatever anchor the data carried before; applying the one it already carries changes nothing, so repeating the call succeeds. An anchor survives re-ingest: redeclaring a slice without supplying an anchor preserves the one it already had.

Parameters:

anchor (roboto.time.Time) – Wall-clock instant of stored time 0: an int of nanoseconds since the Unix epoch, or any other Time, read as to_epoch_nanoseconds() reads it (a datetime or ISO 8601 string is that instant; a float, Decimal, or numeric string is seconds since the epoch). Must fall after the Unix epoch: zero is not an anchor (use clear_unix_offset() to return the Session to an offset of 0), and earlier instants are rejected.

Returns:

This Session, refreshed with recomputed aggregate bounds.

Raises:

  • TypeError – anchor is not one of the Time types.

  • ValueError – anchor is a boolean, a string that is neither seconds nor ISO 8601, zero, before the Unix epoch, or too large for a signed 64-bit integer of nanoseconds; rejected client-side, before any request is made. A range refusal is raised as pydantic.ValidationError, a subclass of ValueError.

  • OverflowError – anchor is infinite, such as float("inf"); rejected client-side, before any request is made.

  • RobotoInvalidRequestException – Any of three cases: the Session has no topic data to anchor; the Session’s own data already carries several distinct anchors, and the server will not pick one of them to move everything from (anchor less than a whole Session at a time instead, either one topic with set_unix_offset() on a Topic from get_topic() or list_topics(), or one whole file with set_timeline_offset()); or the anchor would move the Session’s data, or a time range declared over it, before the Unix epoch or past the largest storable Unix-epoch nanosecond value; anchor the data at the instant it was recorded.

  • RobotoConflictException – A concurrent writer added files to the Session while the anchor was being applied; retry the call.

  • RobotoNotFoundException – The Session no longer exists.

  • RobotoUnauthorizedException – The caller lacks permission to manage Sessions in the org that owns this Session.

Return type:

Session

Examples

The recomputed bounds are the offset plus the Session’s stored values:

>>> session.min_timestamp_ns
250000000
>>> session = session.set_unix_offset(1_700_000_000_000_000_000)
>>> session.min_timestamp_ns
1700000000250000000

The same anchor given as a datetime:

>>> import datetime
>>> session = session.set_unix_offset(
...     datetime.datetime(2023, 11, 14, 22, 13, 20, tzinfo=datetime.timezone.utc)
... )
>>> session.min_timestamp_ns
1700000000250000000
skip_waiting_for(file_ids)#

Stop waiting for these files to be ingested, e.g. ones whose ingestion failed.

A complete Session is announced ingested once its other ingestable files are. The skip covers each file’s current upload: uploading it again makes the Session wait for it again, while editing its tags or metadata does not. Skipped files stay in the Session and are listed in SessionIngestionStatus.skipped_files.

Parameters:

file_ids (collections.abc.Sequence[str]) – Files in this Session.

Returns:

Where this Session stands in ingestion afterwards, and the requested files that are not in it.

Return type:

roboto.experimental.sessions.record.SkipWaitingResponse

Examples

>>> response = session.skip_waiting_for(["fl_0123456789abcdef"])
>>> response.ingestion.state
<SessionIngestionState.Ingested: 'ingested'>
>>> response.not_in_session
[]
property status: roboto.experimental.sessions.record.SessionStatus#

Whether this Session is in progress or complete (see complete()).

Return type:

roboto.experimental.sessions.record.SessionStatus

property tags: list[str]#

User-supplied tags on this Session.

Return type:

list[str]

update(description=NotSet, metadata_changeset=NotSet, name=NotSet, custom_fields_changeset=None, completion_policy=NotSet)#

Update mutable Session fields.

Fields left at the NotSet default are preserved; for nullable fields (description, name, completion_policy), pass None to clear.

Parameters:
Returns:

This Session, refreshed from the server response.

Return type:

Session

Examples

>>> session.update(description="formation flight #4", name="flight-2026-04-23-001")

Let Roboto mark a Session complete 30 minutes after its last file is added:

>>> from roboto.experimental.sessions import CompletionPolicy
>>> session.update(completion_policy=CompletionPolicy(inactivity_minutes=30))
wait_until_ingested(timeout=600, poll_interval=15)#

Block until every ingestable file in this Session is ingested and Roboto has announced it ingested.

The wait ends once Roboto records the announcement that fires session.ingested, which raises ingestion_count. A Session already announced ingested since it was last marked complete returns at once.

A Session in progress is waited for when it will complete on its own: it has a completion_policy and files, so completes_at is set. The wait then includes the policy’s inactivity. A Session in progress that will not complete on its own is refused, as only complete() would complete it.

The default timeout of 10 minutes may be too short for a Session of large recordings. Pass a longer one, e.g. timeout=2 * 60 * 60 for two hours.

Parameters:

  • timeout (float) – Maximum seconds to wait.

  • poll_interval (int) – Seconds between status checks.

Returns:

This Session, refreshed from the server.

Raises:

  • RuntimeError – This Session is in progress and will not complete on its own: it has no completion policy, or it has one but no files.

  • roboto.waiters.TimeoutError – timeout elapsed first. The message says where the Session stands and lists up to 10 of the files it is still waiting for. It is also a built-in TimeoutError.

Return type:

Session

Examples

>>> session = session.complete().wait_until_ingested(timeout=2 * 60 * 60)
class roboto.experimental.sessions.SessionDeclaration(/, **data)#

Bases: SessionAttributes

One session to create on a device, with the files composing it.

Handed, one per session, to create_sessions(). create_session() builds one from its arguments for the single-session case.

Parameters:

data (Any)

anchor_ns: roboto.time._EpochNanosecondsFromTime | None#

Optional wall-clock anchor applied to every entry in this session that does not carry its own FileDeclaration.anchor_ns; each such entry then anchors the data it declares, which is its slice of the file when it names one. Takes the same values as FileDeclaration.anchor_ns, which states the range and the forms it accepts, what an anchor covers, and what an entry’s data does when neither level states one.

files: list[SessionFile]#

Files (and the topics they contribute to) composing this session. Each file appears exactly once, listing all of its topics.

model_config#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str#

retrying a batch converges on the existing session with this name instead of creating a duplicate.

Type:

Name of the session (max 120 characters), unique within the device

class roboto.experimental.sessions.SessionFile(/, **data)#

Bases: FileDeclaration

One already-uploaded file that belongs to a session, and the topic data it carries.

Adds to FileDeclaration the window of the file’s data this session holds. Everything else the entry states is true of the file whichever session, if any, names it.

The same entry states a file’s place in a session however that session is composed: inside a SessionDeclaration that creates the session whole, or handed to add_files() afterwards. An entry with no topics attaches the file without registering topic data; topics can be declared for the same file later, through this entry again or through declare_topics().

A topic listed here takes its anchor from this entry’s anchor_ns, which anchors everything the entry declares. A FileTopicDeclaration carrying an anchor_ns of its own is rejected here; state that anchor on the entry instead.

Time window (min_file_timestamp_ns and max_file_timestamp_ns):

  • Values are nanoseconds as the file’s own data carries them, measured the same way as the min_file_timestamp_ns a timeline source such as SchemaFieldSource declares. A slice of a shared file whose timestamp column restarts at 0 states bounds from 0.

  • Set both or set neither; a window with only one bound is rejected. The window is the closed interval [min_file_timestamp_ns, max_file_timestamp_ns], both endpoints included.

  • The window this entry gives the session is the smallest one enclosing these bounds and the bounds of every timeline source its topics declare. State them when the file’s topics are not declared here, or when what belongs to the session runs past the declared topic data. Leave both unset for a window spanning whatever the entry’s topic data spans, or, on an entry declaring no topics, the file’s whole window.

  • The anchor covering this entry is added to the stored window, so re-anchoring the file moves the window along with the data it names. The bounds may be negative, but with the anchor added the window must lie between the Unix epoch and the largest storable Unix-epoch nanosecond value (2**63 - 1). The platform refuses an entry whose window would fall outside that span, an entry whose anchor would move a window another session declared over the same data outside it, and a later re-anchoring that would move this window outside it. The platform reports the window back in wall clock, on min_wall_clock_timestamp_ns and max_wall_clock_timestamp_ns.

  • Several sessions can share one file, each stating its own window. A session takes on the file’s data that overlaps its window, and its own time bounds span the windows of all the files it holds; a read scoped to the session covers those bounds unless it names a window of its own.

  • The window this entry gives the session also trims a read of this file. A read scoped to this session returns only the rows of the file inside that window, however wide a window the read itself names, so a session holding part of a shared file reads back that part and not the whole file.

Data range (data_range) inside a session:

  • The range decides which of the file’s partitions this session admits. It admits a partition only when every one of its positions sits inside it; a partition reaching past either end is left out whole, never trimmed.

  • A range that cuts through a partition the file has already registered is refused by the platform rather than accepted to admit nothing of that partition.

Parameters:

data (Any)

max_file_timestamp_ns: int | None#

Upper bound of the time window this entry states, in the file’s own timestamps.

min_file_timestamp_ns: int | None#

Lower bound of the time window this entry states, in the file’s own timestamps.

class roboto.experimental.sessions.SessionFileRecord(/, **data)#

Bases: pydantic.BaseModel

Wire-format row for one file a Session holds, and the part of the file it holds.

Time window contract (min_wall_clock_timestamp_ns and max_wall_clock_timestamp_ns):

  1. Set together or both None; a window with only one bound is rejected on write.

  2. When both are None, the Session holds the file’s whole recorded time window.

  3. When both are set, min_wall_clock_timestamp_ns <= max_wall_clock_timestamp_ns. Consumers iterating session data must keep only the file’s data inside the closed interval [min_wall_clock_timestamp_ns, max_wall_clock_timestamp_ns].

  4. Values are nanoseconds since the Unix epoch, measured the same way as the parent Session’s own bounds. A caller states this window in the file’s own timestamps, on SessionFile; the platform adds the anchor covering the data the window names and reports the sum here, alongside the unix_epoch_offset_ns it added.

Data range contract (data_range):

  1. None means the Session holds the whole file.

  2. (start, end): start is the first covered position; end is one past the last, with 0 <= start < end. Values are in the file’s own units: stored-row positions (counted from 0), or nanoseconds of media time for video.

  3. Used when one file is shared by several sessions; the range names the slice of the file that belongs to this session.

Parameters:

data (Any)

created: datetime.datetime | None = None#

When this file was added to the session.

created_by: str#

User ID or service account that added this file to the session.

data_range: tuple[int, int] | None = None#

The slice of the file the Session holds, as (start, end) in the file’s own units, or None when it holds the whole file. start is the first covered position; end is one past the last.

fs_node_id: str#

Identifier of the file.

max_wall_clock_timestamp_ns: int | None = None#

Upper bound (inclusive) of the part of the file the Session holds, in Unix-epoch nanoseconds. None means the Session holds the file up to the end of its recorded time window; paired with min_wall_clock_timestamp_ns.

min_wall_clock_timestamp_ns: int | None = None#

Lower bound (inclusive) of the part of the file the Session holds, in Unix-epoch nanoseconds. None means the Session holds the file from the beginning of its recorded time window; paired with max_wall_clock_timestamp_ns.

model_config#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

modified: datetime.datetime | None = None#

When this file’s place in the session was last modified.

modified_by: str#

User ID or service account that last modified this file’s place in the session.

session_id: str#

Identifier of the session holding this file.

unix_epoch_offset_ns: int | None = None#

Wall-clock instant of stored time 0 for the file’s data the Session holds, in nanoseconds since the Unix epoch: what the platform added to the file’s own timestamps to reach min_wall_clock_timestamp_ns and max_wall_clock_timestamp_ns, and what to subtract to read any other instant back in the file’s own timestamps. None when that data includes nothing registered, and when it sits at more than one instant, which leaves no single offset to report.

class roboto.experimental.sessions.SessionFileView(/, **data)#

Bases: pydantic.BaseModel

One row of the GET /v1/sessions/id/<session_id>/files response: a file’s place in a Session joined with display fields of the file itself.

These fields come from the session’s composition: file_id, the optional time window min_wall_clock_timestamp_ns / max_wall_clock_timestamp_ns in Unix-epoch nanoseconds, the optional data_range slice (the window and the slice both under the contracts documented on SessionFileRecord), and the unix_epoch_offset_ns the platform added to reach that window. Every other field is read from the file itself when the files are listed, and describes the file rather than its place in the session: created is when the file was created, not when it joined the session. None of those fields is part of a write.

Parameters:

data (Any)

created: datetime.datetime | None = None#

When the file was created.

data_range: tuple[int, int] | None = None#

The slice of the file the Session holds, as (start, end) in the file’s own units, or None when it holds the whole file. start is the first covered position; end is one past the last.

dataset_id: str | None = None#

ID of the dataset that contains the file.

file_id: str#

Stable, unique identifier of the file.

ingestable: bool | None = None#

its path matched one of its org’s ingestion rules when its current version was created, or it has since been partly or fully ingested.

Type:

Whether the file is meant to be ingested

ingestion_status: roboto.domain.files.IngestionStatus | None = None#

How much of the contributing file has been ingested.

max_wall_clock_timestamp_ns: int | None = None#

Upper bound (inclusive) of the part of the file the Session holds, in Unix-epoch nanoseconds. None means the Session holds the file up to the end of its recorded time window; paired with min_wall_clock_timestamp_ns.

min_wall_clock_timestamp_ns: int | None = None#

Lower bound (inclusive) of the part of the file the Session holds, in Unix-epoch nanoseconds. None means the Session holds the file from the beginning of its recorded time window; paired with max_wall_clock_timestamp_ns.

model_config#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

modified: datetime.datetime | None = None#

When the file was last modified.

name: str | None = None#

Name of the file (the final segment of relative_path).

origination: str | None = None#

Provenance of the file, e.g. an invocation id or upload source.

relative_path: str | None = None#

Path of the file within its dataset.

size: int | None = None#

Size of the file in bytes.

tags: list[str]#

Tags on the file.

unix_epoch_offset_ns: int | None = None#

Wall-clock instant of stored time 0 for the file’s data the Session holds, in nanoseconds since the Unix epoch: what the platform added to the file’s own timestamps to reach min_wall_clock_timestamp_ns and max_wall_clock_timestamp_ns, and what to subtract to read any other instant back in the file’s own timestamps. None when that data includes nothing registered, and when it sits at more than one instant, which leaves no single offset to report.

class roboto.experimental.sessions.SessionIngestionState#

Bases: roboto.compat.StrEnum

Where a session’s ingestion stands.

InProgress = 'in_progress'#

The session is in progress, so it is not announced ingested.

Ingested = 'ingested'#

The session is complete and every ingestable file in it is ingested.

Processing = 'processing'#

The session is complete and at least one of its ingestable files is not ingested yet.

class roboto.experimental.sessions.SessionIngestionStatus(/, **data)#

Bases: pydantic.BaseModel

Where a session stands in ingestion, with the files it is still waiting for.

Response of GET /v1/sessions/id/<session_id>/ingestion.

Parameters:

data (Any)

failed_file_count: int = 0#

Pending files whose latest ingestion run failed, or finished without ingesting the file. Counts only the files in pending_files, so at most 100.

ingested_file_count: int = 0#

How many ingestable files are ingested.

ingestion_count: int#

How many times the session has been announced ingested.

not_ingestable_file_count: int = 0#

How many files are not ingestable. The session never waits for them.

pending_file_count: int = 0#

How many ingestable files are not ingested yet, leaving out skipped ones.

pending_files: list[PendingIngestionFile]#

Ingestable files not ingested yet, which keep a complete session from being announced. Holds at most the first 100, ordered by path; pending_file_count counts them all.

session_id: str#

ID of the session.

skipped_file_count: int = 0#

How many ingestable files not ingested the session was told to stop waiting for.

skipped_files: list[SkippedIngestionFile]#

Ingestable files not ingested that the session was told to stop waiting for. At most the first 100; skipped_file_count counts them all.

state: SessionIngestionState#

Whether the session is in progress, waiting for files to be ingested, or ingested.

class roboto.experimental.sessions.SessionIngestionSummariesRequest(/, **data)#

Bases: pydantic.BaseModel

Request body for POST /v1/sessions/ingestion/summaries.

Parameters:

data (Any)

session_ids: list[str]#

Sessions to summarize, at most MAX_INGESTION_SUMMARIES.

class roboto.experimental.sessions.SessionIngestionSummariesResponse(/, **data)#

Bases: pydantic.BaseModel

Response of POST /v1/sessions/ingestion/summaries.

Parameters:

data (Any)

summaries: list[roboto.experimental.sessions.record.SessionIngestionSummary]#

One per requested session in the caller’s org, in request order. Others are left out.

class roboto.experimental.sessions.SessionIngestionSummary(/, **data)#

Bases: pydantic.BaseModel

Where one session’s ingestion stands, in counts: what a sessions list shows per row.

Response item of POST /v1/sessions/ingestion/summaries.

Parameters:

data (Any)

failed_file_count: int = 0#

Pending files whose latest ingestion run failed, or finished without ingesting the file. Counted among the first 100 pending files, as SessionIngestionStatus.pending_files lists them.

ingested_file_count: int = 0#

How many ingestable files are ingested.

not_ingestable_file_count: int = 0#

How many files are not ingestable. The session never waits for them.

pending_file_count: int = 0#

How many ingestable files are not ingested yet, leaving out skipped ones.

session_id: str#

ID of the session.

skipped_file_count: int = 0#

Ingestable files not ingested that the session no longer waits for.

state: SessionIngestionState#

Whether the session is in progress, waiting for files to be ingested, or ingested.

class roboto.experimental.sessions.SessionRecord(/, **data)#

Bases: pydantic.BaseModel

Wire-format row for a session: an operational time window of a Device such as a drone flight, a vehicle drive, or a robot run.

A Session unifies the recordings and auxiliary data produced during its window; it may span many files or cover only a slice of one.

min_timestamp_ns and max_timestamp_ns span every file the Session holds: each file supplies the time window stated for it or, without one, the time span of the data the Session takes from it. The platform recomputes them in the same write as any change to the Session’s files or to the anchors of their data, so the row never disagrees with its contents.

Parameters:

data (Any)

completed_at: datetime.datetime | None = None#

When the session was last marked complete. None if it never was. Adding a file to a complete session puts it back in progress and keeps this value, so check status to tell whether the session is complete now.

completed_by: str | None = None#

User ID or service account that last marked the session complete. None if it never was.

completes_at: datetime.datetime | None = None#

When Roboto will mark the session complete unless another file is added first. None while the session is complete, has no completion policy, or has no files.

completion_policy: CompletionPolicy | None = None#

the session is marked complete only by request.

Type:

When Roboto marks the session complete on its own. None

created: datetime.datetime | None = None#

When the session was created.

created_by: str#

User ID or service account that created the session.

custom_fields: dict[str, Any]#

Values for the custom fields defined on Sessions in this org.

Every Ready custom field defined for (org_id, Session) appears as a key; values that have not been set surface as None rather than being absent. Empty when no custom fields are defined for the org.

description: str | None = None#

Optional description of the Session.

ingested_at: datetime.datetime | None = None#

When the session was last announced ingested. None until the first announcement.

ingestion_count: int = 0#

How many times the session has been announced ingested. Each announcement fires a session.ingested event. A session is announced again when it is put back in progress and marked complete again, or when its ingestable files change while it is complete, once they are all ingested again. A file uploaded again, removed, or deleted changes them; editing a file’s tags, metadata, or description does not.

max_timestamp_ns: int | None = None#

Latest time covered by the Session, in Unix-epoch nanoseconds. None while none of its files supplies a time: the Session holds no files, or only files added without a time window whose topic data has no time span registered yet.

metadata: dict[str, Any]#

User-supplied metadata.

Sessions cannot be filtered or sorted by metadata keys; for queryable structured attributes, define a custom field on the Session entity type.

min_timestamp_ns: int | None = None#

Earliest time covered by the Session, in Unix-epoch nanoseconds. None while none of its files supplies a time: the Session holds no files, or only files added without a time window whose topic data has no time span registered yet.

model_config#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

modified: datetime.datetime | None = None#

When the Session was last modified.

modified_by: str#

User ID or service account that last modified the Session.

name: str | None#

A short, human-readable name for the Session. If provided, must be 120 characters or less.

org_id: str#

Organization that owns the Session.

session_id: str#

Stable, unique identifier for the Session.

status: SessionStatus#

Whether the session is in progress or complete. Adding a file to a complete session puts it back in progress.

tags: list[str]#

User-supplied tags.

Sessions can be filtered by tag membership (e.g., tags CONTAINS '<tag>') but are not sortable by tag.

class roboto.experimental.sessions.SessionStatus#

Bases: roboto.compat.StrEnum

Whether a session is still receiving files.

Complete = 'complete'#

All of the session’s files have been added. Roboto announces session.ingested once every ingestable file in it is ingested.

InProgress = 'in_progress'#

Files may still be added. Roboto does not announce the session ingested.

class roboto.experimental.sessions.SkipWaitingRequest(/, **data)#

Bases: pydantic.BaseModel

Request body for POST /v1/sessions/id/<session_id>/ingestion/skip.

Parameters:

data (Any)

file_ids: list[str]#

Member files the session stops waiting for. Files not in the session are reported back, not skipped.

class roboto.experimental.sessions.SkipWaitingResponse(/, **data)#

Bases: pydantic.BaseModel

Response of POST /v1/sessions/id/<session_id>/ingestion/skip.

Parameters:

data (Any)

ingestion: SessionIngestionStatus#

Where the session stands in ingestion after the skip.

not_in_session: list[str]#

Requested file ids that are not in the session, so nothing was skipped for them.

class roboto.experimental.sessions.SkippedIngestionFile(/, **data)#

Bases: pydantic.BaseModel

A file in a session that is ingestable and not ingested, which the session no longer waits for.

The skip covers the upload of the file that was current when it was made: editing the file’s tags, metadata, or description keeps it, and uploading the file again ends it.

Parameters:

data (Any)

file_id: str#

ID of the file.

relative_path: str#

Path of the file within its dataset, device, or org.

skipped_at: datetime.datetime | None = None#

When the session was told to stop waiting for the file.

skipped_by: str | None = None#

User ID or service account that told the session to stop waiting for the file.

On this page