roboto.domain.sessions.session#

Module Contents#

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

An operational time window of a Device.

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

The Session’s aggregate bounds — min_timestamp_ns and max_timestamp_ns, in Unix-epoch nanoseconds — are recomputed by Roboto across all file contributions on every add or remove, and the returned instance reflects 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.

  • create_session() is a shortcut for the common single-device case.

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

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

Examples

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

>>> from roboto.domain.sessions import Session
>>> session = Session.create(name="flight-2026-04-23-001", device_ids=["dv_abc"])
>>> session = session.add_file("fl_0123456789abcdef")
>>> for topic in session.list_topics():
...     print(topic.name)
Parameters:
add_file(file, range_min_timestamp_ns=None, range_max_timestamp_ns=None)#

Include a single file in this Session as a contribution.

Thin convenience over add_files() for the common one-file case.

Parameters:

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

  • range_min_timestamp_ns (Optional[int]) – Optional lower bound (Unix-epoch nanoseconds) of this file’s contribution to the Session. Must be paired with range_max_timestamp_ns; leaving both None contributes the whole file’s time window.

  • range_max_timestamp_ns (Optional[int]) – Optional upper bound paired with range_min_timestamp_ns.

Returns:

This Session, refreshed from the server response.

Return type:

Session

Examples

Include a whole file:

>>> session.add_file("fl_0123456789abcdef")

Include only a sub-window of a file:

>>> session.add_file(
...     "fl_0123456789abcdef",
...     range_min_timestamp_ns=1_700_000_000_000_000_000,
...     range_max_timestamp_ns=1_700_000_060_000_000_000,
... )
add_files(files)#

Include the given files in this Session as contributions.

Each file may carry optional range_min_timestamp_ns / range_max_timestamp_ns bounds (Unix-epoch nanoseconds) narrowing its contribution to a sub-window of the file’s data. The service recomputes the Session’s aggregate bounds across all contributions, and the Session instance reflects the new min_timestamp_ns / max_timestamp_ns on return.

Parameters:

files (collections.abc.Sequence[roboto.domain.sessions.operations.SessionFile]) – Files to contribute to the Session.

Returns:

This Session, refreshed from the server response.

Return type:

Session

Examples

>>> from roboto.domain.sessions import SessionFile
>>> session.add_files(
...     [
...         SessionFile(file_id="fl_aaa"),
...         SessionFile(
...             file_id="fl_bbb",
...             range_min_timestamp_ns=1_700_000_000_000_000_000,
...             range_max_timestamp_ns=1_700_000_060_000_000_000,
...         ),
...     ]
... )
attach_to_device(device_id)#

Attach a Device to this Session as a subject.

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

Parameters:

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

Return type:

None

Examples

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

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

Parameters:

name (str)

Return type:

Session

clear_custom_fields(names)#

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

Parameters:

names (collections.abc.Sequence[str])

Return type:

Session

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

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

Prefer create_session() for the common single-device case. To add devices to an existing Session later, see attach_to_device().

Parameters:

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

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

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

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

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

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

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

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

Returns:

The created Session.

Return type:

Session

Examples

>>> from roboto.domain.sessions import Session
>>> session = Session.create(
...     name="flight-2026-04-23-001",
...     device_ids=["dv_a", "dv_b"],
...     description="formation flight #4",
...     metadata={"pilot": "alice"},
...     tags=["pre-flight-check"],
... )
property created: datetime.datetime | None#

UTC timestamp when this Session was created.

Return type:

Optional[datetime.datetime]

property created_by: str#

Identifier of the user or service which created this Session.

Return type:

str

property custom_fields: dict[str, Any]#

Custom-field values defined on Sessions in this org.

Every Ready CustomField defined for (org_id, Session) 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.

Return type:

dict[str, Any]

delete()#

Delete this Session. Its file contributions and device attachments are removed alongside it.

Return type:

None

property description: str | None#

Optional description of this Session.

Return type:

Optional[str]

detach_from_device(device_id)#

Remove a Device from this Session’s subjects.

Parameters:

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

Return type:

None

classmethod for_dataset(dataset_id, owner_org_id=None, roboto_client=None)#

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

Parameters:

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

  • owner_org_id (Optional[str]) – Org that owns the dataset. Required when the caller belongs to multiple orgs.

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

Yields:

Sessions, one at a time, following pagination automatically.

Return type:

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

Examples

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

Iterate all Sessions visible to the caller’s org.

Parameters:

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

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

Yields:

Sessions, one at a time, following pagination automatically.

Return type:

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

classmethod from_id(session_id, owner_org_id=None, roboto_client=None)#

Load a Session by ID.

Parameters:

  • session_id (str) – Session primary key.

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

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

Returns:

The Session.

Return type:

Session

list_devices()#

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

Return type:

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

list_files()#

Iterate this Session’s file contributions, following pagination automatically.

Yields:

SessionFile entries, each carrying its optional range_min_timestamp_ns / range_max_timestamp_ns sub-window bounds.

Return type:

collections.abc.Generator[roboto.domain.sessions.operations.SessionFile, None, None]

list_metrics()#

Return all metrics published to this Session.

Returns:

List of Metric instances for this Session.

Return type:

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

Examples

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

Iterate topic identities reachable from this Session, following pagination.

Results are range-filtered: a topic identity is yielded only when the Session’s time window overlaps at least one of the topic’s timeline extents (TimelineExtentRecord). Results are deduplicated across files and partitions, ordered by name with topic_id as a deterministic tiebreaker.

Yields:

roboto.domain.topics.TopicIdentityRecord entries.

Return type:

collections.abc.Generator[roboto.domain.topics.record.TopicIdentityRecord, None, None]

Examples

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

Upper aggregate bound across this Session’s recording data contributions, in Unix-epoch nanoseconds.

None when the Session has no contributions.

Return type:

Optional[int]

property metadata: dict[str, Any]#

User-supplied metadata attached to this Session.

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

Return type:

dict[str, Any]

property min_timestamp_ns: int | None#

Lower aggregate bound across this Session’s recording data contributions, in Unix-epoch nanoseconds.

None when the Session has no contributions.

Return type:

Optional[int]

property modified: datetime.datetime | None#

UTC timestamp when this Session was last modified.

Return type:

Optional[datetime.datetime]

property modified_by: str#

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

Return type:

str

property name: str | None#

Optional short name of this Session.

Return type:

Optional[str]

property org_id: str#

Identifier of the organization that owns this Session.

Return type:

str

publish_metrics(metrics, device_id=NotSet)#

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

Convenience wrapper around publish() that supplies this Session’s session_id and org_id. Each (metric, session) pair is upserted: republishing under the same name replaces the previous value.

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

Parameters:

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

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

Returns:

A BulkPublishMetricsResult with succeeded and failed lists.

Raises:

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

Return type:

roboto.domain.metrics.metric.BulkPublishMetricsResult

Examples

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

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

Attach to an explicit device, overriding inference:

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

Add or update metadata fields on this Session.

Parameters:

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

Returns:

This Session, refreshed from the server response.

Return type:

Session

Examples

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

Add tags to this Session.

Tags already present on the Session are not duplicated.

Parameters:

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

Returns:

This Session, refreshed from the server response.

Return type:

Session

Examples

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

Underlying data record for this Session.

Return type:

roboto.domain.sessions.record.SessionRecord

remove_file(file)#

Remove a single file’s contributions from this Session.

Thin convenience over remove_files() for the common one-file case.

Parameters:

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

Returns:

This Session, refreshed from the server response.

Return type:

Session

remove_files(file_ids)#

Remove the given files’ contributions from this Session.

The service recomputes the Session’s aggregate bounds across the remaining contributions, and the Session instance reflects the new min_timestamp_ns / max_timestamp_ns on return.

Parameters:

file_ids (collections.abc.Sequence[str]) – File IDs whose contributions should be removed.

Returns:

This Session, refreshed from the server response.

Return type:

Session

remove_metadata(metadata)#

Remove metadata keys from this Session.

Parameters:

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

Returns:

This Session, refreshed from the server response.

Return type:

Session

Examples

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

Remove the given tags from this Session.

Parameters:

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

Returns:

This Session, refreshed from the server response.

Return type:

Session

Examples

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

Globally unique identifier assigned to this Session on creation.

Return type:

str

set_custom_field(name, value)#

Set a single custom-field value on this session.

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

Parameters:

  • name (str)

  • value (Any)

Return type:

Session

set_custom_fields(fields)#

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

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

Parameters:

fields (dict[str, Any])

Return type:

Session

property tags: list[str]#

User-supplied tags on this Session.

Return type:

list[str]

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

Update mutable Session fields.

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

Parameters:
Return type:

Session

:param See put_tags(): :param remove_tags(): :param put_metadata(): :param : :param and remove_metadata() for shorthand helpers.: :param name: New name for the Session. Set to None to clear the name.

Leave at the default to leave the name unchanged.

Parameters:
Returns:

This Session, refreshed from the server response.

Return type:

Session

Examples

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