roboto.experimental.sessions.operations
Request bodies for the session endpoints, and what a caller declares about sessions in them.
What the platform reports back is in roboto.experimental.sessions.record, and the types describing a file’s contents, independent of any session, live in roboto.experimental.ingest.
Module Contents
AddFilesRequest
Bases: pydantic.BaseModel
Request body for POST /v1/sessions/id/<session_id>/files.
Adds one or more files to the session, each with whatever topic data it carries, and reports what became of each entry. The platform decides every refusal before writing anything, so an entry it refuses leaves the others added, and a failure it did not anticipate adds none of them.
Parameters
data AnyAttributes
AddFilesRequest.files
Files to include, each appearing exactly once and listing all of its topics. The entries and the topics on them count together toward MAX_FILES_AND_TOPICS_PER_REQUEST.
AddFilesRequest.model_config
model_config #Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
AttachToDeviceRequest
Bases: pydantic.BaseModel
Request body for POST /v1/sessions/id/<session_id>/devices.
Attaches a device as a subject of the session.
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.
CreateSessionRequest
Bases: SessionAttributes
Request body for POST /v1/sessions.
Creates a new session with zero, one, or many devices attached as subjects.
Parameters
data AnyCreateSessionsRequest
Bases: pydantic.BaseModel
Request body for POST /v1/devices/id/<device_id>/sessions.
Creates up to MAX_SESSIONS_PER_REQUEST sessions on one device, each with its files, topics, and schemas, in a single call; the platform additionally rejects batches declaring more than MAX_FILES_AND_TOPICS_PER_REQUEST files and topics combined, counted across all sessions.
A malformed batch is rejected whole, before anything is written. Past that point the platform decides every declaration’s refusal before writing anything, writes the others together, and answers with one element per declaration, in the order they were declared; see create_sessions() for what a declaration writes, what a refused one leaves behind, and what a resend of the same batch does.
Parameters
data AnyAttributes
CreateSessionsRequest.model_config
model_config #Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
CreateSessionsRequest.sessions
Sessions to create, between 1 and MAX_SESSIONS_PER_REQUEST per request.
DetachFromDeviceRequest
Bases: pydantic.BaseModel
Request body for DELETE /v1/sessions/id/<session_id>/devices.
Detaches a device from the session; the session itself is not deleted.
Parameters
data AnyFileDeclaration
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.
RemoveFilesRequest
Bases: pydantic.BaseModel
Request body for DELETE /v1/sessions/id/<session_id>/files.
Removes the listed files from the session and reports what became of each: a file the session does not hold is reported as its own entry rather than failing the call, and a failure the platform did not anticipate removes none of them.
Parameters
data AnySessionAttributes
Bases: pydantic.BaseModel
Descriptive attributes a caller can set on a session, whichever call creates it.
Parameters
data AnyAttributes
SessionAttributes.completion_policy
completion_policy roboto.When Roboto marks the session complete on its own. Omit it to use the org’s default completion policy, if the org has one. None: the session is marked complete only by request, whatever the org’s default.
SessionAttributes.custom_fields
Initial values for Ready custom fields on this session.
Each key must be the name of a CustomField that is Ready for the caller’s org and the Session entity type; each value must satisfy the field’s declared type. Names that are undefined or not Ready, and values that don’t match the field’s type, are rejected with a structured error.
SessionAttributes.metadata
Key-value metadata to associate with the Session.
Sessions cannot be filtered or sorted by metadata keys; for queryable structured attributes, define a custom field on the Session entity type.
SessionAttributes.model_config
model_config #Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
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.
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.
SessionUpdate
Bases: pydantic.BaseModel
Partial update for a session.
Fields left at NotSet are not modified.
Parameters
data AnyAttributes
SessionUpdate.completion_policy
completion_policy roboto.New completion policy for the Session. None removes it, so the Session is marked complete only by request.
On a Session in progress that has files, setting a policy restarts its inactivity: Roboto marks the Session complete inactivity_minutes from now, unless a file is added first. A complete Session stays complete; the policy applies after a file is added to it, which puts it back in progress.
SessionUpdate.custom_fields_changeset
Changes to apply to Ready custom-field values on this session.
Each referenced field name must be a Ready custom field for this session’s org and the Session entity type; each set_fields value must satisfy the field’s declared type. Names that are undefined or not Ready are rejected with a structured error. Field names not mentioned by the changeset are left unchanged.
SessionUpdate.description
New description for the Session. Set to None to clear the description.
SessionUpdate.metadata_changeset
Tag and metadata changes to merge into the Session (add, update, or remove fields and tags).
SessionUpdate.model_config
model_config #Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
SessionUpdate.name
name Annotated[str, pydantic.New name for the Session (max 120 characters). Set to None to clear the name.
SetUnixOffsetRequest
Bases: pydantic.BaseModel
Request body for POST /v1/sessions/id/<session_id>/unix-offset.
Anchors the session’s data to wall-clock time. See set_unix_offset() for the write’s reach and its interaction with anchors already on the data.
Parameters
data AnyAttributes
SetUnixOffsetRequest.model_config
model_config #Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
SetUnixOffsetRequest.unix_epoch_offset_ns
Wall-clock instant of stored time 0, in nanoseconds since the Unix epoch. Must fall after the Unix epoch, and must 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.
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.