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#

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

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 (Any)

files: list[SessionFile]#: 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.

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

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

Bases: pydantic.BaseModel

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

Attaches a device as a subject of the session.

Parameters:: data (Any)

device_id: str#

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

class roboto.experimental.sessions.operations.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.operations.CreateSessionRequest(/, **data)#

Bases: SessionAttributes

Request body for POST /v1/sessions.

Creates a new session with zero, one, or many devices attached as subjects.

Parameters:: data (Any)

device_ids: list[str]#: Devices to attach to the Session as subjects; empty creates a Session with no devices.

name: str | None#: Optional short name for the Session (max 120 characters).

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

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 (Any)

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

sessions: list[SessionDeclaration]#: Sessions to create, between 1 and MAX_SESSIONS_PER_REQUEST per request.

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

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 (Any)

device_id: str#

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

class roboto.experimental.sessions.operations.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.operations.MAX_INGESTION_SUMMARIES = 100#: Most sessions one POST /v1/sessions/ingestion/summaries takes.

roboto.experimental.sessions.operations.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.operations.RemoveFilesRequest(/, **data)#

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 (Any)

file_ids: list[str]#: Files to remove, each named at most once.

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

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

Bases: pydantic.BaseModel

Descriptive attributes a caller can set on a session, whichever call creates it.

Parameters:: data (Any)

completion_policy: roboto.experimental.sessions.record.CompletionPolicy | roboto.sentinels.NotSetType | None#: 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.

custom_fields: dict[str, Any] | None = None#

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.

description: str | None = None#: Optional description of the Session.

metadata: dict[str, Any]#

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.

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

tags: list[str]#: Tags to associate with the Session.

class roboto.experimental.sessions.operations.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.operations.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.operations.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.operations.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.operations.SessionUpdate(/, **data)#

Bases: pydantic.BaseModel

Partial update for a session.

Fields left at NotSet are not modified.

Parameters:: data (Any)

completion_policy: roboto.experimental.sessions.record.CompletionPolicy | roboto.sentinels.NotSetType | None#

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.

custom_fields_changeset: roboto.updates.CustomFieldChangeset | None = None#

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.

description: str | roboto.sentinels.NotSetType | None#: New description for the Session. Set to None to clear the description.

metadata_changeset: roboto.updates.MetadataChangeset | roboto.sentinels.NotSetType#: Tag and metadata changes to merge into the Session (add, update, or remove fields and tags).

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

name: Annotated[str, pydantic.StringConstraints(max_length=120)] | roboto.sentinels.NotSetType | None#: New name for the Session (max 120 characters). Set to None to clear the name.

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

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 (Any)

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

unix_epoch_offset_ns: roboto.time._EpochNanosecondsFromTime#: 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.

class roboto.experimental.sessions.operations.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.