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
CompletionPolicy
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 AnyCreateSessionIfNotExistsRequest
Bases: pydantic.BaseModel
Request body for POST /v1/sessions/create_if_not_exists.
Parameters
data AnyAttributes
CreateSessionIfNotExistsRequest.create_request
The session to create when none matches.
CreateSessionIfNotExistsRequest.match_roboql_query
RoboQL query over sessions. The first matching session is returned instead of creating one.
FileDeclaration
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):startis the first covered position;endis 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 AnyAttributes
FileDeclaration.anchor_ns
Optional wall-clock anchor for the data this declaration names: 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.
FileDeclaration.data_range
The slice of the file this declaration describes, or None for the whole file.
FileDeclaration.file_id
Identifier of the already-uploaded file this declaration describes.
FileDeclaration.model_config
model_config #Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
FileDeclaration.topics
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.
MAX_INGESTION_SUMMARIES
Most sessions one POST /v1/sessions/ingestion/summaries takes.
MAX_SESSIONS_PER_REQUEST
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.
PendingIngestionFile
Bases: pydantic.BaseModel
A file in a session that is ingestable and not ingested yet.
Parameters
data AnyAttributes
PendingIngestionFile.ingestion_status
How much of the file’s current version is ingested: not at all, or partly.
PendingIngestionFile.last_run
The latest time an ingestion rule’s trigger ran on the file. None when none has.
PendingIngestionFile.relative_path
Path of the file within its dataset, device, or org.
PendingIngestionFile.uploaded
When the file’s current version was uploaded.
Session
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().
Usage
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
roboto_client Optional[roboto.Session.add_file()
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.A File or a file ID.
data_range Optional[roboto.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.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.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
TypeErroranchor is not one of the Time types.
ValueErroranchor 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.
OverflowErroranchor is infinite, such as float("inf"); rejected client-side, before any request is made.
pydantic.ValidationErrorThe 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.
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.
Whatever else the platform refused this file with.
Usage
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,
)Session.add_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.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.ValidationErrorThe 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.
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.
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.
Usage
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])Session.attach_to_device()
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 strID of the Device to add as a subject of this Session.
Raises
The Device does not exist in this Session’s org, or the Session no longer exists.
Return type
Usage
session.attach_to_device("wingman")
list(session.list_devices())
# ['lead', 'wingman']Session.clear_custom_field()
Clear a single custom-field value on this session to None.
Parameters
name strReturn type
Session.clear_custom_fields()
Clear multiple custom-field values on this session to None.
Parameters
names collections.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
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.
A concurrent writer added files to the Session while the clear was being applied; retry the call.
The Session no longer exists.
The caller lacks permission to manage Sessions in the org that owns this Session.
Usage
The recomputed bounds return to the Session’s stored values:
session.min_timestamp_ns
# 1700000000250000000
session = session.clear_unix_offset()
session.min_timestamp_ns
# 250000000Session.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.
Usage
session.add_file("fl_0123456789abcdef")
session = session.complete()
session.status is SessionStatus.Complete
# TrueProperties
Session.completes_at
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.
Session.completion_policy
When Roboto marks this Session complete on its own, or None if it is marked complete only by complete().
Session.create()
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.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.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.Optional RobotoClient; defaults to the ambient one.
completion_policy Union[roboto.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
A device in device_ids does not exist in the caller’s org. No Session is created.
Usage
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"],
)Session.create_if_not_exists()
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 strRoboQL query over Sessions, e.g. name = 'flight-0042'.
name Optional[str]Name of the Session to create when none matches.
device_ids collections.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.Tags of a created Session.
custom_fields Optional[dict[str, Any]]Custom-field values of a created Session.
completion_policy Union[roboto.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.Optional RobotoClient; defaults to the ambient one.
Returns
The matching or created Session.
Raises
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.
Usage
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")Properties
Session.created
UTC timestamp when this Session was created.
Session.created_by
Identifier of the user or service which created this Session.
Session.custom_fields
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.
Session.delete()
Delete this Session. The files it included and the devices attached to it are not deleted.
Return type
Properties
Session.description
Optional description of this Session.
Session.detach_from_device()
Remove a Device from this Session’s subjects.
Parameters
device_id strID of the Device to remove as a subject of this Session.
Return type
Session.for_dataset()
Iterate Sessions whose composition includes any file in the given dataset.
Parameters
dataset_id strDataset whose sessions to list.
roboto_client Optional[roboto.Optional RobotoClient; defaults to the ambient one.
Yields
Sessions, one at a time, following pagination automatically.
Return type
Usage
from roboto.experimental.sessions import Session
for session in Session.for_dataset("ds_abc"):
print(session.session_id, session.name)Session.for_org()
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.Optional RobotoClient; defaults to the ambient one.
Yields
Sessions, one at a time, following pagination automatically.
Return type
Session.from_id()
Load a Session by ID.
Parameters
session_id strSession primary key.
roboto_client Optional[roboto.Optional RobotoClient; defaults to the ambient one.
Returns
The Session.
Raises
No session with this ID exists.
The caller lacks view access to the org that owns the session.
Usage
from roboto.experimental.sessions import Session
session = Session.from_id("se_abc123")
session.name
# 'flight-2026-04-23-001'Session.get_topic()
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 strExact name of the topic to retrieve (e.g. "/camera/image").
Returns
The matching Topic.
Raises
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).
The caller lacks permission to view Sessions in the org that owns this Session.
Usage
topic = session.get_topic("/camera/image")
for timestamp, record in topic.get_data():
print(timestamp, record)Properties
Session.ingestion_count
How many times this Session has been announced ingested.
Session.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.
Usage
status = session.ingestion_status()
status.state
# <SessionIngestionState.Processing: 'processing'>
[f.relative_path for f in status.pending_files]
# ['flight_002.mcap']Session.ingestion_summaries()
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.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.Optional RobotoClient; defaults to the ambient one.
Returns
One summary per Session found, in request order.
Usage
summaries = Session.ingestion_summaries(["se_abc123", "se_def456"])
[s.session_id for s in summaries if s.failed_file_count]
# ['se_def456']Session.list_devices()
Iterate the device IDs attached as subjects of this Session, paginated.
Return type
Session.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
Session.list_metrics()
Return all metrics published to this Session.
Returns
List of Metric instances for this Session.
Usage
metrics = session.list_metrics()
for m in metrics:
print(m.name, m.value)Session.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
Usage
for topic in session.list_topics():
for timestamp, record in topic.get_data():
print(topic.name, timestamp, record)Properties
Session.max_timestamp_ns
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.
Session.metadata
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.
Session.min_timestamp_ns
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.
Session.modified
UTC timestamp when this Session was last modified.
Session.modified_by
Identifier of the user or service which last modified this Session.
Session.publish_metrics()
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.Metric names and numeric values to record.
device_id Union[roboto.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
device_id was omitted and this Session has zero or more than one attached devices.
Usage
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)
# 2Attach to an explicit device, overriding inference:
session.publish_metrics(
[MetricEntry(name="cpu.usage_max", value=87.2)],
device_id="robot01",
)Session.put_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.
Usage
session.put_metadata({"weather": "clear", "pilot": "alice"})Session.put_tags()
Add tags to this Session.
Tags already present on the Session are not duplicated.
Parameters
Tags to add.
Returns
This Session, refreshed from the server response.
Usage
session.put_tags(["pre-flight-check", "training"])Properties
Session.record
Underlying data record for this Session.
Session.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.
Session.remove_file()
Remove a single file from this Session.
The singular form of remove_files().
Parameters
file Union[roboto.A File or a file ID.
Returns
The ID of the removed file.
Raises
This Session does not hold the file.
Session.remove_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.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.ValidationErrorThe 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.
Session.remove_metadata()
Remove metadata keys from this Session.
Parameters
metadata roboto.Metadata keys to remove. Dot notation addresses nested keys ("weather.condition").
Returns
This Session, refreshed from the server response.
Usage
session.remove_metadata(["pilot", "weather.condition"])Session.remove_tags()
Remove the given tags from this Session.
Parameters
Tags to remove. Tags not present on the Session are silently ignored.
Returns
This Session, refreshed from the server response.
Usage
session.remove_tags(["training"])Properties
Session.session_id
Globally unique identifier assigned to this Session on creation.
Session.set_custom_field()
Session.set_custom_fields()
Session.set_unix_offset()
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.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
TypeErroranchor is not one of the Time types.
ValueErroranchor 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.
OverflowErroranchor is infinite, such as float("inf"); rejected client-side, before any request is made.
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.
A concurrent writer added files to the Session while the anchor was being applied; retry the call.
The Session no longer exists.
The caller lacks permission to manage Sessions in the org that owns this Session.
Usage
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
# 1700000000250000000The 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
# 1700000000250000000Session.skip_waiting_for()
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.Files in this Session.
Returns
Where this Session stands in ingestion afterwards, and the requested files that are not in it.
Usage
response = session.skip_waiting_for(["fl_0123456789abcdef"])
response.ingestion.state
# <SessionIngestionState.Ingested: 'ingested'>
response.not_in_session
# []Properties
Session.status
Whether this Session is in progress or complete (see complete()).
Session.update()
Update mutable Session fields.
Fields left at the NotSet default are preserved; for nullable fields (description, name, completion_policy), pass None to clear.
Parameters
description Optional[Union[str, roboto.New description for the Session. Set to None to clear the description. Leave at the default to leave the description unchanged.
metadata_changeset Union[roboto.Tag and metadata changes to apply (put/remove tags and fields). See put_tags(), remove_tags(), put_metadata(), and remove_metadata() for shorthand helpers.
name Optional[Union[str, roboto.New name for the Session. Set to None to clear the name. Leave at the default to leave the name unchanged.
custom_fields_changeset Optional[roboto.Changes to apply to Ready custom-field values on this session. Field names not referenced by the changeset are left unchanged.
completion_policy Union[roboto.When Roboto marks the Session complete on its own. None removes the policy, so the Session is marked complete only by complete(). On a Session in progress that has files, a new policy counts its inactivity from now. A complete Session stays complete, and the policy applies after a file is added to it.
Returns
This Session, refreshed from the server response.
Usage
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))Session.wait_until_ingested()
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 floatMaximum seconds to wait.
poll_interval intSeconds between status checks.
Returns
This Session, refreshed from the server.
Raises
RuntimeErrorThis Session is in progress and will not complete on its own: it has no completion policy, or it has one but no files.
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.
Usage
session = session.complete().wait_until_ingested(timeout=2 * 60 * 60)SessionDeclaration
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 AnyAttributes
SessionDeclaration.anchor_ns
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.
SessionDeclaration.files
Files (and the topics they contribute to) composing this session. Each file appears exactly once, listing all of its topics.
SessionDeclaration.model_config
model_config #Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
SessionDeclaration.name
Name of the session (max 120 characters), unique within the device: retrying a batch converges on the existing session with this name instead of creating a duplicate.
SessionFile
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_nsa timeline source such asSchemaFieldSourcedeclares. 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, onmin_wall_clock_timestamp_nsandmax_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 AnyAttributes
SessionFile.max_file_timestamp_ns
Upper bound of the time window this entry states, in the file’s own timestamps.
SessionFile.min_file_timestamp_ns
Lower bound of the time window this entry states, in the file’s own timestamps.
SessionFileRecord
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):
- Set together or both
None; a window with only one bound is rejected on write. - When both are
None, the Session holds the file’s whole recorded time window. - 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]. - 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 theunix_epoch_offset_nsit added.
Data range contract (data_range):
Nonemeans the Session holds the whole file.(start, end):startis the first covered position;endis one past the last, with0 <= start < end. Values are in the file’s own units: stored-row positions (counted from 0), or nanoseconds of media time for video.- Used when one file is shared by several sessions; the range names the slice of the file that belongs to this session.
Parameters
data AnyAttributes
SessionFileRecord.created
When this file was added to the session.
SessionFileRecord.created_by
User ID or service account that added this file to the session.
SessionFileRecord.data_range
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.
SessionFileRecord.max_wall_clock_timestamp_ns
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.
SessionFileRecord.min_wall_clock_timestamp_ns
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.
SessionFileRecord.model_config
model_config #Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
SessionFileRecord.modified
When this file’s place in the session was last modified.
SessionFileRecord.modified_by
User ID or service account that last modified this file’s place in the session.
SessionFileRecord.unix_epoch_offset_ns
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.
SessionFileView
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 AnyAttributes
SessionFileView.data_range
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.
SessionFileView.ingestable
Whether the file is meant to be ingested: 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.
SessionFileView.ingestion_status
How much of the contributing file has been ingested.
SessionFileView.max_wall_clock_timestamp_ns
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.
SessionFileView.min_wall_clock_timestamp_ns
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.
SessionFileView.model_config
model_config #Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
SessionFileView.origination
Provenance of the file, e.g. an invocation id or upload source.
SessionFileView.unix_epoch_offset_ns
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.
SessionIngestionState
Bases: roboto.compat.StrEnum
Where a session’s ingestion stands.
Attributes
SessionIngestionState.InProgress
The session is in progress, so it is not announced ingested.
SessionIngestionState.Ingested
The session is complete and every ingestable file in it is ingested.
SessionIngestionState.Processing
The session is complete and at least one of its ingestable files is not ingested yet.
SessionIngestionStatus
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 AnyAttributes
SessionIngestionStatus.ingested_file_count
How many ingestable files are ingested.
SessionIngestionStatus.ingestion_count
How many times the session has been announced ingested.
SessionIngestionStatus.not_ingestable_file_count
How many files are not ingestable. The session never waits for them.
SessionIngestionStatus.pending_file_count
How many ingestable files are not ingested yet, leaving out skipped ones.
SessionIngestionStatus.pending_files
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.
SessionIngestionStatus.skipped_file_count
How many ingestable files not ingested the session was told to stop waiting for.
SessionIngestionStatus.skipped_files
Ingestable files not ingested that the session was told to stop waiting for. At most the first 100; skipped_file_count counts them all.
SessionIngestionStatus.state
Whether the session is in progress, waiting for files to be ingested, or ingested.
SessionIngestionSummariesRequest
Bases: pydantic.BaseModel
Request body for POST /v1/sessions/ingestion/summaries.
Parameters
data AnyAttributes
SessionIngestionSummariesRequest.session_ids
Sessions to summarize, at most MAX_INGESTION_SUMMARIES.
SessionIngestionSummariesResponse
Bases: pydantic.BaseModel
Response of POST /v1/sessions/ingestion/summaries.
Parameters
data AnyAttributes
SessionIngestionSummariesResponse.summaries
One per requested session in the caller’s org, in request order. Others are left out.
SessionIngestionSummary
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 AnyAttributes
SessionIngestionSummary.failed_file_count
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.
SessionIngestionSummary.ingested_file_count
How many ingestable files are ingested.
SessionIngestionSummary.not_ingestable_file_count
How many files are not ingestable. The session never waits for them.
SessionIngestionSummary.pending_file_count
How many ingestable files are not ingested yet, leaving out skipped ones.
SessionIngestionSummary.skipped_file_count
Ingestable files not ingested that the session no longer waits for.
SessionIngestionSummary.state
Whether the session is in progress, waiting for files to be ingested, or ingested.
SessionRecord
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 AnyAttributes
SessionRecord.completed_at
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.
SessionRecord.completed_by
User ID or service account that last marked the session complete. None if it never was.
SessionRecord.completes_at
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.
SessionRecord.completion_policy
When Roboto marks the session complete on its own. None: the session is marked complete only by request.
SessionRecord.custom_fields
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.
SessionRecord.ingested_at
When the session was last announced ingested. None until the first announcement.
SessionRecord.ingestion_count
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.
SessionRecord.max_timestamp_ns
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.
SessionRecord.metadata
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.
SessionRecord.min_timestamp_ns
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.
SessionRecord.model_config
model_config #Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
SessionRecord.modified_by
User ID or service account that last modified the Session.
SessionRecord.name
A short, human-readable name for the Session. If provided, must be 120 characters or less.
SessionRecord.status
Whether the session is in progress or complete. Adding a file to a complete session puts it back in progress.
SessionRecord.tags
User-supplied tags.
Sessions can be filtered by tag membership (e.g., tags CONTAINS '<tag>') but are not sortable by tag.
SessionStatus
Bases: roboto.compat.StrEnum
Whether a session is still receiving files.
Attributes
SkipWaitingRequest
Bases: pydantic.BaseModel
Request body for POST /v1/sessions/id/<session_id>/ingestion/skip.
Parameters
data AnyAttributes
SkipWaitingRequest.file_ids
Member files the session stops waiting for. Files not in the session are reported back, not skipped.
SkipWaitingResponse
Bases: pydantic.BaseModel
Response of POST /v1/sessions/id/<session_id>/ingestion/skip.
Parameters
data AnyAttributes
SkipWaitingResponse.ingestion
Where the session stands in ingestion after the skip.
SkipWaitingResponse.not_in_session
Requested file ids that are not in the session, so nothing was skipped for them.
SkippedIngestionFile
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 AnyAttributes
SkippedIngestionFile.relative_path
Path of the file within its dataset, device, or org.
SkippedIngestionFile.skipped_at
When the session was told to stop waiting for the file.
SkippedIngestionFile.skipped_by
User ID or service account that told the session to stop waiting for the file.