roboto.experimental.ingest

Roboto’s normalized type for the field, used for cross-format reads and visualization.

Native type of the field as recorded by the source format (e.g. "float32").

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

Name of the field. Defaults to the last element of path when only path is given; at least one of name and path must be declared.

The names from the schema root down to this field; a nested field’s path extends its parent’s path. Omitted, None, or empty defaults to [name]; when given, every element must be non-empty and the last element must equal name.

Unit of the field’s values (e.g. "rad"). A field typed Timestamp must carry a TimeUnit value (one of "s", "ms", "us", "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. 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, read as roboto.time.to_epoch_nanoseconds() reads it; convert with that function first to satisfy a type checker. When omitted, the data 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.

An anchor covers the whole slice named by data_range, not this topic alone, so every topic declared over that slice moves to it; two declarations sharing a slice may not name different anchors.

Discriminator identifying this entry as MCAP log time.

Discriminator identifying this entry as MCAP publish time.

Discriminator identifying this entry as MP4 presentation time.

Format of the data inside the container, such as "jpeg" for re-encoded images or "compressedVideo" for passed-through video frames, or None when unspecified. A read names it through content_format.

Field of the topic’s schema this representation covers, as the names from the schema root down to it. None, the same as leaving it out, makes this a representation of the whole topic; an empty list and an empty name are refused.

The path must equal the path of a field the topic’s schema declares. That field may have fields under it, and the representation then covers those too. A level of the schema that only the paths of deeper fields pass through, with no field declared at it, cannot be named.

A read takes each field from the representation covering the deepest field that contains it, so a representation of one field supplies that field whatever its transformations, and the representations of the whole topic supply the rest. A read asking for untransformed data (RepresentationSelector.raw()) leaves out every representation that states a transformation.

File a read opens to get the topic’s data: the file the topic is declared on, when its own bytes hold the data, or another file of the org, such as a per-topic MCAP converted out of a PX4 ULog. Its status must be Available, and the caller must be able to edit it. A read through the SDK or the web app downloads this file with the reader’s own download permission on it, and Roboto’s AI tools read it for anyone who can read the topic.

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

Container file_id holds the data in. Within one request, every representation naming a file must state the same format for it, whichever of the request’s topics, files or sessions lists it; a request stating two formats for one file is refused when it is built.

The transformations applied to the topic’s data to produce what file_id holds, in the order applied, as "<kind>:<param>" descriptors such as ["downsample:0.7", "encode:jpeg"]; TransformationKind lists the kinds. Empty for untransformed data. A read names them through transformations, and with no selector the platform prefers the representation with the fewest.

A representation can be read by row position when it is untransformed or every transformation is an encode. One with any other transformation, such as a downsample, cannot, and a read of a topic declared over a data_range never uses it: on such a topic, everything it covers must also be covered by representations that can.

Within one topic, every representation naming a file must state the same transformations for it: a read that takes two representations from one file and finds their transformations differ raises RobotoReadPlanExecutionException with kind inconsistent-scan-tasks-on-file.

Declared columns of the topic’s data. At least one is required, and every field’s path must be unique within the schema.

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

Informational label for the schema (often the topic name). Not part of schema identity.

Path of the field holding this source’s timestamps: the names from the schema root down to that field. The field must be declared on the topic’s schema and typed Timestamp.

Discriminator identifying this entry as timestamps read from a data column.

The part of the file this topic’s data occupies, as (start, end): start is the first covered position, and end is one past the last. Set this when one file packs a topic’s data into slices, such as a single episode inside a LeRobot v3 data file. Omit it when the data covers whatever encloses this declaration: the slice claimed by the SessionFile carrying it, or the whole file when the topics are declared on the file itself through declare_topics(). A range set inside a SessionFile must sit within that entry’s own data_range.

Values are in the file’s own units: stored-row positions (counted from 0), or nanoseconds of the file’s media time for video. Each file uses exactly one of the two, so the pair needs no unit marker; which one applies follows from the file’s format. A read applies the range to the file it opens, and it opens only files named by representations that can be read by row position, as RepresentationDeclaration.transformations describes: each of those files must hold the same rows at the same positions. Over a range, everything a topic’s representations cover must be covered by ones that can be read by row position; the platform refuses the declaration otherwise.

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

The files a read of this topic’s data opens, each with how it holds that data. List the file the topic is declared on here, naming its file_id, when its own bytes are readable; list other files when the data is read from them, such as the per-topic MCAPs converted out of a PX4 ULog. A topic may list several, and a read picks among them by RepresentationSelector.

A topic with no representations is still registered: its data counts toward the bounds of every session holding the file, and a read of it returns no rows, or is refused when the read’s RepresentationSelector sets a criterion. A video, or a proprietary log with no file converted out of it, is declared that way.

Redeclaring the topic over the same part of the file adds the representations listed to the ones it has. A listed representation takes the place of the stored one that covers what it covers (the whole topic, or the same field) under the same storage format, content format and transformations, and of every stored one that names the same file, whatever that one covers; every other stored representation stays. Redeclaring the topic with the new files a conversion wrote therefore replaces each stored representation with the listed one that differs from it only in its file_id; redeclaring it with a file uploaded again in another storage format replaces the stored representation that names that file; and resending the same declaration leaves the stored representations as they are. To remove a representation, or to replace a topic’s representations outright, use set_representations().

A representation of one field is stored against that field of the schema it was declared under. While one is stored, the platform refuses a declaration of the topic over the same part of the file with a changed topic_schema, unless the declaration lists a representation that takes the stored one’s place. To change the schema, list the representation of that field again in the same declaration, or remove it first with set_representations().

Refused when the model is built:

1. Two representations covering the same thing (both the whole topic, or the same field) under the same storage format, content format and transformations.
2. Two representations naming one file under different transformations.
3. A representation whose field_path names no field of topic_schema.
4. A PARQUET representation on a topic declaring any timeline source but SchemaFieldSource: the others take their timestamps from the message envelope, which a Parquet file does not have.

Timeline sources this file’s topic data carries, each with its own bounds. Data timestamped several ways (a message’s publish time and the time the recorder wrote it, say) declares one entry per source; data timestamped one way declares a list of one. Reads pick a source by name, and resolve to the one marked is_default_for_reads when they do not.

Topic this file (or slice of it) contributes data to. Topic names are unique within an org; files declaring the same name contribute to the same topic.

Structure of the topic’s data. Repeat the same schema on every file that uses it; the platform stores each distinct schema once, so repetition costs nothing extra.

The part of the file over which the topic’s representations are replaced, or None for data declared over the whole file. It must equal a range the topic is already declared over on the file: the topic’s TopicDeclaration.data_range, or, for a topic that stated none inside a SessionFile, that entry’s data_range.

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

The representations the topic ends up with; its representations not listed are removed, those of one field included. An empty list removes every representation: the topic stays registered and still counts toward the bounds of every session holding the file, but reads of it return no rows. Two representations may not cover the same thing (both the whole topic, or the same field) under the same storage format, content format and transformations, or name one file under different transformations; both are refused when the model is built. set_representations() states what the platform refuses.

Topic whose representations are replaced. It must already be declared on the file.