roboto.domain.platform_events
Platform events: what happened to an entity on the platform, as a record.
Distinct from roboto.domain.events, whose Event is a time-anchored annotation on robotics data. A platform event is emitted by the platform when a file is uploaded, a dataset is created, an invocation finishes, and so on. Triggers subscribe to them; outgoing integrations receive them as CloudEvents. The catalog describes each type: its payload model, the namespace roots it exposes, and the once_per values it supports.
Submodules
Package Contents
CLOUDEVENTS_SPECVERSION
The CloudEvents spec version PlatformEvent.to_cloudevent() produces.
CLOUDEVENTS_TYPE_PREFIX
Reverse-DNS prefix CloudEvents recommends on type. It appears only in what PlatformEvent.to_cloudevent() returns; subscriptions, conditions, and templates name an event by its bare PlatformEventType value (file.uploaded).
DATASET_ROOT
Namespace root naming a dataset. An event exposing it is about a dataset or about something within one, so a consumer may reach that dataset’s files from the event.
DEFAULT_PLATFORM_EVENT_CATALOG
The catalog of every PlatformEventType, used wherever a caller does not supply its own (envelope payload binding, trigger validation, evaluation).
DatasetCreatedPayload
DatasetMetadataUpdatedPayload
Bases: pydantic.BaseModel
Payload for PlatformEventType.DatasetMetadataUpdated.
Parameters
data AnyAttributes
DatasetMetadataUpdatedPayload.changeset
The applied metadata/tag delta, served to conditions as the changed and tag roots.
DatasetMetadataUpdatedPayload.model_config
model_config #Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
DatasetTagAddedPayload
Bases: pydantic.BaseModel
Payload for PlatformEventType.DatasetTagAdded.
Parameters
data AnyAttributes
DatasetTagAddedPayload.model_config
model_config #Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
DatasetTagAddedPayload.tags_added
Tags added by the mutation, served to conditions as the tag root.
ENVELOPE_ROOT
Namespace root served from the platform event’s own envelope: its id, source, subject, type, time, and org, plus the payload as published under data. Reserved: no event type may expose it as an entity root.
EventCreatedPayload
Bases: pydantic.BaseModel
Payload for PlatformEventType.EventCreated.
Parameters
data AnyAttributes
EventCreatedPayload.model_config
model_config #Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
FileIngestedPayload
Bases: pydantic.BaseModel
Payload for PlatformEventType.FileIngested.
Parameters
data AnyAttributes
FileIngestedPayload.file_version
The file’s version when the event was published; a newer version may exist by the time a trigger evaluates. Versions number revisions of the file record, which a metadata or tag edit advances just as an overwrite of the file’s contents does. None on events published before the payload carried this field.
FileIngestedPayload.model_config
model_config #Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
FileIngestedPayload.transaction_id
Upload transaction the file arrived in, when known.
FileMetadataUpdatedPayload
Bases: pydantic.BaseModel
Payload for PlatformEventType.FileMetadataUpdated.
Parameters
data AnyAttributes
FileMetadataUpdatedPayload.changeset
The applied metadata/tag delta, served to conditions as the changed and tag roots.
FileMetadataUpdatedPayload.file_version
The file’s version when the event was published; a newer version may exist by the time a trigger evaluates. Versions number revisions of the file record, which a metadata or tag edit advances just as an overwrite of the file’s contents does. None on events published before the payload carried this field.
FileMetadataUpdatedPayload.model_config
model_config #Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
FileUploadedPayload
Bases: pydantic.BaseModel
Payload for PlatformEventType.FileUploaded.
Parameters
data AnyAttributes
FileUploadedPayload.file_version
The file’s version when the event was published; a newer version may exist by the time a trigger evaluates. Versions number revisions of the file record, which a metadata or tag edit advances just as an overwrite of the file’s contents does. None on events published before the payload carried this field.
FileUploadedPayload.model_config
model_config #Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
FileUploadedPayload.transaction_id
Upload transaction the file arrived in, when the upload used one.
InvocationCompletedPayload
Bases: pydantic.BaseModel
Payload for PlatformEventType.InvocationCompleted.
Parameters
data AnyAttributes
InvocationCompletedPayload.action_name
Name of the invoked action. Unique within action_owner_id’s org.
InvocationCompletedPayload.model_config
model_config #Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
InvocationCompletedPayload.status
Terminal status the invocation reached.
InvocationFailedPayload
Bases: pydantic.BaseModel
Payload for PlatformEventType.InvocationFailed.
Parameters
data AnyAttributes
InvocationFailedPayload.action_name
Name of the invoked action. Unique within action_owner_id’s org.
InvocationFailedPayload.model_config
model_config #Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
InvocationFailedPayload.status
Terminal status the invocation reached (Failed or Deadly).
OncePer
Bases: roboto.compat.StrEnum
A grain an event offers for deduplication: the occurrence itself, or an entity the event names.
This is an event’s vocabulary, not a trigger’s. Each PlatformEventType declares the grains it supports, and how an occurrence projects onto each, in its PlatformEventDescriptor; that projection is what turns one occurrence into one idempotency token. A trigger only chooses among the grains its events offer, and its choice must be legal for every event type it subscribes to.
Attributes
OncePer.Event
Fire once per event, the annotation marking a span of time on your data.
OncePer.Occurrence
Fire on every occurrence; nothing collapses. Supported by every event type.
OncePerProjection
Projects a PlatformEvent onto the token string that identifies what the trigger fires once per (e.g. the dataset id for once_per=dataset).
A projection reads the event payload and nothing else: one event in, one string out, with no lookup against platform state. A once_per value can only name what the event itself already identifies, so there is no “once per file in the dataset this event is about”. once_per only collapses repeats; it never fans one event out into several runs, and a trigger dispatches each of its targets at most once per event.
PlatformEvent
Bases: pydantic.BaseModel
One occurrence of something that happened on the platform, as a trigger receives it.
id, source, type, time and subject are the CloudEvents 1.0 context attributes; to_cloudevent() renders the occurrence in that spec’s structured-JSON form. The envelope stays thin: data carries entity ids and facts fixed at time, such as a metadata delta or a terminal status, and never mutable entity state — conditions and target templates read an entity’s current state at evaluation time through an EventNamespace.
Parameters
data AnyAttributes
PlatformEvent.data
The per-type payload. Its model must be the one registered for type in the default catalog; a mismatch is rejected at validation time.
PlatformEvent.id
Producer-vended event id, unique within source; deterministic where possible (e.g. evt:{invocation_id}:completed).
PlatformEvent.model_config
model_config #Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
PlatformEvent.schema_version
Version of the envelope + payload schema. Bumped only for breaking changes.
PlatformEvent.source
The org and the deployment the event happened in, as built by platform_event_source().
Properties
PlatformEvent.subject
The entity the event is about, as a roboto:// URI (roboto://file/fl_1a2b).
Computed from data by the event type’s catalog descriptor rather than stored, so it cannot disagree with the payload, and serialized like a declared field.
PlatformEvent.subject_uri
subject as a parsed RobotoUri.
Attributes
PlatformEvent.to_cloudevent()
Return this event as CloudEvents 1.0 structured JSON (application/cloudevents+json).
Nothing serializes it yet: the command bus carries the model itself. It exists so an outbound webhook body needs no redesign.
Context attributes sit at the top level under their spec names, with type carrying CLOUDEVENTS_TYPE_PREFIX and datacontenttype fixed at application/json. org_id and schema_version arrive as the extension attributes orgid and schemaversion, because extension names must be lowercase alphanumerics. The returned dict is JSON-serializable as-is.
Return type
Attributes
PlatformEvent.type
Which kind of event this is. Dictates the concrete model of data.
PlatformEventCatalog
Descriptors for platform event types, looked up by type.
Everything that varies by event type — payload model, exposed roots, default root, dedup projections — hangs off the PlatformEventDescriptor objects registered here. DEFAULT_PLATFORM_EVENT_CATALOG registers every member of PlatformEventType; a caller may build a catalog over a subset.
Parameters
descriptors collections.PlatformEventCatalog.descriptor()
Return the descriptor for event_type.
Parameters
Raises
ValueErrorNo descriptor is registered for event_type.
Return type
PlatformEventCatalog.exposed_roots()
Return the namespace roots event_type exposes.
Parameters
Raises
ValueErrorNo descriptor is registered for event_type.
Return type
PlatformEventCatalog.namespace_roots()
Return the union of every registered event type’s exposed roots.
Return type
PlatformEventCatalog.subscribable_types()
Return the event types a trigger may subscribe to.
Return type
PlatformEventDescriptor
Everything the trigger system knows about one platform event type.
Immutable. Carries the payload model the envelope validates against, the namespace roots the event exposes to conditions and target templates, the default root unqualified condition fields bind to, the entity the event is about, and the OncePer values the event supports (as projections from an event to its dedup token value).
Every once_per value is declared as an OncePerProjection, a pure function of the event payload, so a descriptor can only offer what the payload itself names. No descriptor can resolve one event into several subjects, which is what holds dispatch at one per target per event.
Attributes
PlatformEventDescriptor.default_root
Root that unqualified condition fields bind to. Always one of exposed_roots.
PlatformEventDescriptor.event_type
The event type this descriptor describes.
PlatformEventDescriptor.exposed_roots
Namespace roots (dataset, file, changed, …) this event exposes.
PlatformEventDescriptor.idempotency_token()
Return the dedup token for event at once_per.
Two events that project onto the same token dispatch the same target of the same trigger at most once.
Parameters
The event to project. Must be of this descriptor’s type.
What the trigger fires once per.
Raises
ValueErrorevent is of a different type, or once_per is not supported by this event type.
Return type
Attributes
PlatformEventDescriptor.once_per_projections
once_per_projections collections.Supported once_per values, each mapped to the projection that yields its token. Key presence defines legality; every event supports OncePer.Occurrence.
PlatformEventDescriptor.payload_model
Model of PlatformEvent.data for this event type.
PlatformEventDescriptor.subject()
Return the roboto:// URI of the entity event is about.
Parameters
Raises
ValueErrorevent is not of this descriptor’s event type.
Return type
Attributes
PlatformEventDescriptor.subject_type
The kind of entity this event is about — its CloudEvents subject. The payload carries that entity’s id under {subject_type}_id, and may say more about it, such as the version a file was at. The rest is context around the entity: the upload transaction a file arrived in, or the applied changeset.
PlatformEventDescriptor.subscribable
Whether a trigger may name this type in an EventSubscription. False for occurrences delivered to a single trigger rather than broadcast to subscribers — the schedule tick — which still carry a descriptor so their tokens and namespaces are built the same way.
Properties
PlatformEventDescriptor.supported_once_per
The OncePer values this event type supports.
PlatformEventDescriptor.supports_once_per()
Return whether once_per is legal for this event type.
Parameters
Return type
PlatformEventPayload
Union of every per-type payload model. Which member is legal for a given PlatformEvent is dictated by its type.
PlatformEventType
Bases: roboto.compat.StrEnum
A thing that happens on the platform that triggers can subscribe to.
Every member has a PlatformEventDescriptor in the default PlatformEventCatalog describing its payload model, the namespace roots it exposes to conditions and templates, and the OncePer values it supports.
Attributes
PlatformEventType.DatasetMetadataUpdated
A dataset’s metadata or tags changed.
PlatformEventType.DatasetTagAdded
One or more tags were added to a dataset.
PlatformEventType.EventCreated
An event, the annotation marking a span of time on your data, was created.
PlatformEventType.FileIngested
A file finished ingestion (post-processing) and its topics are available.
PlatformEventType.FileMetadataUpdated
A file’s metadata or tags changed.
PlatformEventType.FileUploaded
A file finished uploading to a dataset.
PlatformEventType.InvocationCompleted
An action invocation reached a successful terminal status.
PlatformEventType.InvocationFailed
An action invocation reached a failed terminal status (Failed or Deadly).
PlatformEventType.ScheduleFired
A trigger’s own schedule reached one of its minutes. Not subscribable: a trigger fires on a schedule by declaring a Schedule source, and the scheduler delivers this occurrence to that trigger alone.
PlatformEventType.SessionIngested
Every ingestable file in a complete session is ingested. Fires again, as a new occurrence, each time the session’s ingestable files change and are all ingested again.
PlatformEventType.UploadCompleted
An upload transaction to a dataset completed (all of its files uploaded).
Properties
PlatformEventType.cloudevents_type
This type as a CloudEvents type attribute: ai.roboto.file.uploaded.
PlatformEventType.from_cloudevents_type()
Return the event type a CloudEvents type attribute names; the inverse of cloudevents_type.
Parameters
value strA prefixed type, such as ai.roboto.file.uploaded.
Raises
ValueErrorvalue lacks the prefix or names no platform event type.
Return type
RESERVED_ROOTS
Roots the evaluation namespace serves itself. A descriptor claiming one would be silently shadowed by the envelope or the trigger, so construction rejects it.
SAMPLE_ACTION_DIGEST
SAMPLE_ACTION_NAME
SAMPLE_API_DOMAIN
SAMPLE_CHANGESET
SAMPLE_DATASET_ID
SAMPLE_EVENT_ID
SAMPLE_FILE_ID
SAMPLE_FILE_VERSION
SAMPLE_INVOCATION_ID
SAMPLE_ORG_ID
SAMPLE_SESSION_ID
SAMPLE_TAGS_ADDED
SAMPLE_TIME
The instant every sample event and record is dated from, so samples are stable across calls.
SAMPLE_TRANSACTION_ID
SAMPLE_TRIGGER_ID
SAMPLE_USER
ScheduleFiredPayload
Bases: pydantic.BaseModel
Payload for PlatformEventType.ScheduleFired.
Parameters
data AnyAttributes
ScheduleFiredPayload.model_config
model_config #Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
ScheduleFiredPayload.scheduled_for
The scheduled minute (UTC) this occurrence stands for.
SessionIngestedPayload
Bases: pydantic.BaseModel
Payload for PlatformEventType.SessionIngested.
Parameters
data AnyAttributes
SessionIngestedPayload.ingestion_number
Which announcement this is for the session, starting at 1.
SessionIngestedPayload.model_config
model_config #Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
SessionIngestedPayload.session_id
The session whose ingestable files are all ingested.
TRIGGER_ROOT
Namespace root describing the trigger being evaluated. Reserved for the consumer; no event type may expose it as an entity root.
UploadCompletedPayload
Bases: pydantic.BaseModel
Payload for PlatformEventType.UploadCompleted.
Parameters
data AnyAttributes
UploadCompletedPayload.model_config
model_config #Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
event_catalog_manifest()
The catalog as the web UI’s TypeScript mirror reads it: per event type, its roots, default root, supported grains, subject type, and whether a trigger may subscribe.
event_catalog.json in this package is this function’s output, written by scripts/gen_trigger_manifests.py and drift-checked by a test on each side.
Parameters
catalog PlatformEventCatalogReturn type
platform_event_source()
Return the CloudEvents source for one org’s events on one deployment.
The value is the org’s own API resource, https://{api_domain}/v1/orgs/{org_id}. No two deployments produce the same source, so it pairs with PlatformEvent.id to identify a single occurrence.
Parameters
api_domain Optional[str]Public API host of the emitting deployment, such as api.roboto.ai. Without one, the result is the relative reference /v1/orgs/{org_id}.
org_id strOrganization whose events carry this source.
Return type
sample_platform_event()
A valid, fully populated event of event_type from the sample scenario.
Parameters