roboto.domain.topics.record

Bases: enum.Enum

Normalized data types used across different robotics frameworks.

Well-known and simplified data types that provide a common vocabulary for describing message path data types across different frameworks and technologies. These canonical types are primarily used for UI rendering decisions and cross-platform compatibility.

The canonical types abstract away framework-specific details while preserving the essential characteristics needed for data processing and visualization.

References

• ROS 1 field types: http://wiki.ros.org/msg
• ROS 2 field types: https://docs.ros.org/en/iron/Concepts/Basic/About-Interfaces.html#field-types
• uORB: https://docs.px4.io/main/en/middleware/uorb.html#adding-a-new-topic

Example mappings:

• float32 -> CanonicalDataType.Number
• uint8[] -> CanonicalDataType.Array
• sensor_msgs/Image -> CanonicalDataType.Image
• geometry_msgs/Pose -> CanonicalDataType.Object
• std_msgs/Header -> CanonicalDataType.Object
• string -> CanonicalDataType.String
• char -> CanonicalDataType.String
• bool -> CanonicalDataType.Boolean
• byte -> CanonicalDataType.Byte

A slice of one file’s contents, as (start, end) with start included and end excluded.

A position is expressed in whatever the file’s format uses to address its contents: stored-row positions counted from 0, or nanoseconds of media time for video. The pair alone does not say which of the two applies, so a reader takes that from the file’s format. The half-open form matches LeRobot’s dataset_from_index and dataset_to_index, so row ranges read from LeRobot episode metadata carry over unchanged.

A schema field’s path components, in order from the schema root to the leaf.

Bases: roboto.compat.StrEnum

Well-known metadata key names (with well-known semantics) that may be set in metadata.

These are most often set by Roboto’s first-party ingestion actions and used by Roboto clients.

Bases: pydantic.BaseModel

Record representing a message path within a topic.

Defines a specific field or signal within a topic’s data schema, including its data type, metadata, and statistical information. Message paths use dot notation to specify nested attributes within complex message structures.

Message paths are the fundamental units for accessing individual data elements within time-series robotics data, enabling fine-grained analysis and visualization of specific signals or measurements.

MessagePathRecord.parents()

field = "root.sub_obj_1.sub_obj_2.leaf_field"
record = MessagePathRecord(message_path=field)  # other fields omitted for brevity
print(record.parents())
# ['root.sub_obj_1.sub_obj_2', 'root.sub_obj_1', 'root']

MessagePathRecord.to_field_selection()

Bases: pydantic.BaseModel

Mapping between message paths and their data representation.

Associates a set of message paths with a specific representation that contains their data. This mapping is used to efficiently locate and access data for specific message paths within topic representations.

Bases: enum.Enum

Statistics computed by Roboto in our standard ingestion actions.

Which of these a given message path actually carries depends on the ingestion path that produced it, so treat every one as optional: read them with metadata.get(...) or through the corresponding MessagePath property, both of which yield None when the statistic was never written, and never assume a missing value means zero. Indexing metadata directly raises KeyError for a statistic that was never written.

Bases: pydantic.BaseModel

Record representing a data representation for topic content.

A representation is a pointer to processed topic data stored in a specific format and location. Representations enable efficient access to topic data by providing multiple storage formats optimized for different use cases.

Most message paths within a topic point to the same representation (e.g., an MCAP or Parquet file containing all topic data). However, some message paths may have multiple representations for analytics or preview formats.

Representations are versioned and associated with specific files or storage locations through the association field.

Bases: pydantic.BaseModel

Criteria for selecting among multiple representations of the same data.

When a message path has multiple representations (e.g., both raw sensor data and a processed JPEG encoding), this is a hard filter: only matching representations qualify, and message paths with no matching representation are dropped from selection results — callers must handle empty or partial output.

Legacy carve-out for ``content_format``: representations with no format set (i.e., predating the field) are treated as matching any content_format request. This keeps older data accessible. When both an explicit format match and a legacy representation are available for the same message path, the explicit match wins.

Instances are immutable (frozen=True) so they can be safely shared — including as default arguments to methods like Topic.get_data().

RepresentationSelector.matches()

RepresentationSelector.raw()

RepresentationSelector.select_representations()

Bases: enum.Enum

Supported storage formats for topic data representations.

Defines the available formats for storing and accessing topic data within the Roboto platform. Each format has different characteristics and use cases.

Bases: pydantic.BaseModel

A single field within a topic schema.

One entry per unique field path within a schema; field paths are deduplicated across topics that share the schema.

Bases: pydantic.BaseModel

Min/max timestamp bounds for one topic partition measured against one timeline source.

Written by ingest when a partition’s timestamps are summarized for a given source (e.g., a schema timestamp field, or message log/publish time).

Stored timestamps come through verbatim from the data source: they may be absolute nanoseconds since the Unix epoch, or partition-relative (e.g., monotonic from zero). unix_epoch_offset_ns is the calibration that projects stored values onto Unix-epoch wall-clock: session_time_ns = stored_time_ns + unix_epoch_offset_ns. A value of 0 means the stored timestamps are already absolute Unix-epoch ns, or that no calibration has been applied yet.

Discriminator for how a TimelineSourceRecord derives its timestamps.

"schema_field" points at a timestamp field inside the schema (field_id is set). "message_log_time" and "message_publish_time" point at the message envelope’s log or publish timestamp respectively (field_id is None).

Bases: pydantic.BaseModel

A registered timeline source for a schema.

A timeline source either points at a timestamp field inside the schema (source="schema_field", field_id set) or at the message envelope’s log or publish timestamp (source in {"message_log_time", "message_publish_time"}, field_id is None). Timeline sources are scoped to a schema, not a topic, so topics that share a schema share their timeline sources.

Bases: pydantic.BaseModel

A durable identity for a topic.

Within an organization, topic names are unique: data logged under the same topic name in different files shares a single identity record.

Bases: pydantic.BaseModel

One file’s data for a topic.

Pairs a topic identity with a file and carries the facts that vary from file to file: the schema the file’s messages follow (schema_id), the device that produced them, and the data_range locating them inside the file, for formats that pack several slices of data into one shared file. A partition references a file, not a specific version; reads always resolve to the current version.

Bases: pydantic.BaseModel

Record representing a topic in the Roboto platform.

A topic is a collection of timestamped data records that share a common name and association (typically a file). Topics represent logical data streams from robotics systems, such as sensor readings, robot state information, or other time-series data.

Data from the same file with the same topic name are considered part of the same topic. Data from different files or with different topic names belong to separate topics, even if they have similar schemas.

When source files are chunked by time or size but represent the same logical data collection, they will produce multiple topic records for the same “logical topic” (same name and schema) across those chunks.

Bases: pydantic.BaseModel

A content-addressed topic schema.

Within an organization, two schemas with identical fields share a single record (identified by a deterministic checksum of the fields). name is a mutable, informational label (last-writer-wins) and is not part of the schema’s identity.

Bases: pydantic.BaseModel

Earliest start and latest end, in epoch nanoseconds, across a set of topics.

The aggregate of the start_time and end_time of every topic in the set, computed server-side so a caller does not have to page the whole set to fold them.

Either field is None when no topic in the set carries that timestamp — because the set is empty, or because every topic in it left that bound unset.

Bases: roboto.compat.StrEnum

Canonical vocabulary of transformations that can be applied when producing a representation.

A transformation is serialized into RepresentationRecord.transformations as a "<kind>:<param>" string (e.g. "downsample:0.5", "encode:jpeg"). This enum is the source of truth for the set of supported kinds; the parameter tail remains free-form because different kinds carry different parameter shapes (floats, format tokens, etc.).

Producers should construct transformation strings via with_param() and consumers should destructure them via parse() to keep the vocabulary centralized.

Usage

TransformationKind.DOWNSAMPLE.with_param(0.5)
# 'downsample:0.5'
TransformationKind.parse("encode:jpeg")
# (<TransformationKind.ENCODE: 'encode'>, 'jpeg')

TransformationKind.parse()

TransformationKind.with_param()

Check that data_range is a pair of non-negative positions with start < end.

Both positions must fit in a signed 64-bit integer, which is how the platform stores them.