roboto.domain.triggers

Bases: pydantic.BaseModel

How to run an action: which action, its parameters, overrides, and input selectors.

The part of an invoke-action target that says nothing about when it runs, shared by InvokeActionTarget and anything else that stores an action invocation to run later, such as an ingestion rule. String leaves of parameter_values and invocation_input may contain {{...}} placeholders resolved against the event namespace at dispatch time.

ActionInvocationSpec.referenced_placeholders()

Bases: pydantic.BaseModel

One leaf of the trigger’s condition, with the actual value it saw.

Evaluates a trigger condition tree against an event namespace.

Reuses the query Condition comparators unchanged; only the value source differs. Each leaf routes to the namespace root its field targets and matches against that root’s record, so roots hydrate lazily on first reference. A root whose record is missing evaluates to a non-match, so NOT_EXISTS and IS_NULL never match against an entity that was deleted before evaluation.

ConditionMatcher.matches()

Bases: pydantic.BaseModel

Request payload to create a trigger.

The server assigns identity and audit fields, and runs TriggerValidator over the cross-field rules (exposed roots, once_per legality, target placeholders) before persisting.

Triggered work runs as the organization’s actions service user; a trigger cannot run its targets as anyone else.

One target of one trigger at one dedup token: the unit a dispatch claims.

At most one dispatch ever occupies a slot. It is the dispatch table’s primary key and the vocabulary every dispatch port speaks.

Bases: pydantic.BaseModel

The state of one target’s dispatch slot at the dry run’s idempotency token.

Resolves dotted variable paths against a platform event.

The one namespace with three consumers: condition evaluation (whole records via record()), target template substitution (single paths via resolve(), satisfying the VariableResolver protocol), and idempotency projections. Entity-backed roots hydrate through the NamespaceSource at most once each and are cached for the namespace’s lifetime — including None results. The envelope, changed, tag and schedule roots are served from the event itself and never touch the source; trigger is served from the bound trigger (see bound_to()) and is otherwise absent.

envelope carries the event’s own fields plus the payload under envelope.data. The payload is fixed when the event is published, while an entity root reads that entity as it stands at evaluation time: on a file.uploaded event, envelope.data.file_version is the version that fired the trigger and file.version is the version the file is on when the condition runs. That payload field is optional on file.uploaded, file.ingested and file.metadata_updated, and resolves to None on events published before the payload carried it.

Payload values are rendered as JSON, so a timestamp under envelope.data is an ISO-8601 string while envelope.time and schedule.scheduled_for are datetime objects. Conditions compare the two forms alike; a template substitutes each in its own spelling (2026-08-27T09:00:00Z against 2026-08-27 09:00:00+00:00).

EventNamespace.bound_to()

EventNamespace.get()

EventNamespace.record()

EventNamespace.resolve()

Bases: _SourceBase

Fire when any of the subscribed platform events occurs.

Carries once_per because it only means something here: it names what the event is about that the trigger fires at most once for, and a schedule has no such subject.

EventSubscription.fires_for()

Bases: ActionInvocationSpec, _TargetSpecBase

Stored configuration for invoking an action when a trigger fires.

Spec only — dispatch behavior lives server-side. The ActionInvocationSpec fields say how to run the action; this class adds the target’s identity and its file patterns. String leaves of required_inputs and additional_inputs may contain {{...}} placeholders, as the spec’s may.

An event that names a dataset invokes the action against that dataset, with inputs matched from its files by the file patterns. An event that names no dataset has no files to match: the invocation has no data source and selects its inputs with invocation_input.

InvokeActionTarget.from_invocation()

InvokeActionTarget.invocation()

InvokeActionTarget.referenced_placeholders()

Maximum trigger name length.

Bases: pydantic.BaseModel

The owner of a trigger whose definition is managed by something other than the org’s members.

No managed trigger can be deleted, or have its definition changed, through the triggers API. Org members may enable or disable a system-managed trigger. A trigger owned by an ingestion rule may not be enabled, disabled, edited or deleted directly: change the rule instead, e.g. turn its auto-ingest off. An org has at most one trigger per owner.

Bases: roboto.compat.StrEnum

What kind of thing in Roboto manages a trigger.

Bases: Protocol

Lazily hydrates entity-backed namespace roots for an event.

NamespaceSource.record_for_root()

Bases: pydantic.BaseModel

One event type, dereferenced: the envelope, every root it exposes, and the template paths that resolve against them.

Bases: pydantic.BaseModel

Wire shape of GET /v1/triggers/events/samples: one sample per platform event type.

A NamespaceSource that hydrates every root from the sample scenario.

Serves each root the way a real firing does — including action as the invocation’s provenance and upload as the bare transaction id — so a sample carries exactly the roots a trigger would see.

SampleNamespaceSource.record_for_root()

Bases: _SourceBase

Fire on a cron schedule, in UTC.

Each scheduled minute fires the trigger once (once_per='occurrence' over the schedule tick). A missed minute is skipped rather than replayed later, so a delayed schedule never floods targets with backdated firings. Cron expressions are evaluated in UTC; a schedule cannot name a time zone.

Schedule.fires_for()

Bases: _TargetSpecBase

Stored configuration for posting a Slack message when a trigger fires.

Spec only — dispatch behavior lives server-side. The channel must be on the org’s Slack outbound allowlist at dispatch time.

SendSlackMessageTarget.referenced_placeholders()

Bases: _TargetSpecBase

Stored configuration for starting an agent thread when a trigger fires.

Spec only — dispatch behavior lives server-side. Each value in values is a template resolved against the event namespace, then handed to the agent’s own variable resolution as a plain value.

StartAgentTarget.referenced_placeholders()

Legal trigger names: word characters and hyphens.

Bases: pydantic.BaseModel

One target’s prefilter decision.

A trigger: a firing source (event subscriptions or a schedule), an optional condition, and targets.

Triggers created through the older causes/for_each API (roboto.domain.actions.Trigger) are listed and loaded here too, projected onto this shape and marked engine == "v1"; they accept a narrower set of edits (see update()).

Usage

Start an agent whenever a dataset gains a ready tag:

from roboto.domain.platform_events import OncePer, PlatformEventType
from roboto.domain.triggers import StartAgentTarget, Trigger
trigger = Trigger.create(
    name="analyze-ready-datasets",
    targets=[StartAgentTarget(target_id="analyze", agent_id="ag_abc123")],
    events=[PlatformEventType.DatasetTagAdded],
    once_per=OncePer.Occurrence,
)

Post to Slack every Monday at 09:00 UTC:

from roboto.domain.triggers import SendSlackMessageTarget
weekly = Trigger.create(
    name="weekly-status",
    targets=[SendSlackMessageTarget(target_id="post", channel_id="C0123", text="Weekly check-in")],
    schedule="0 9 * * 1",
)

Trigger.create()

Trigger.delete()

Trigger.disable()

Trigger.dispatches()

Trigger.dry_run()

trace = trigger.dry_run(dataset_id="ds_abc123")
print(trace.verdict)

Trigger.enable()

Trigger.from_id()

Trigger.from_name()

Trigger.list()

Trigger.platform_event_samples()

samples = Trigger.platform_event_samples()
samples[PlatformEventType.FileUploaded].paths[:3]
# ['envelope.id', 'envelope.type', 'envelope.time']

Trigger.set_enabled()

Trigger.to_dict()

Trigger.update()

Bases: pydantic.BaseModel

Wire-transmissible representation of one trigger dispatch.

A dispatch is one attempt to run one target of one trigger for one matched platform event, deduped at the trigger’s OncePer. The triple (trigger_id, idempotency_token, target_id) is the DispatchSlot; at most one dispatch ever occupies a slot, which is what makes redelivered events safe.

Bases: roboto.compat.StrEnum

Lifecycle state of one dispatch: one attempt to run one target for one matched event.

Bases: pydantic.BaseModel

One gate’s result in a dry-run trace.

condition_leaves is populated only on the condition gate, targets only on target_prefilter, and idempotency_token/dispatches only on already_fired.

Bases: roboto.compat.StrEnum

The gates the evaluator runs, in evaluation order.

Bases: roboto.compat.StrEnum

Outcome of one gate in a dry run.

Bases: pydantic.BaseModel

Request payload for a trigger dry run.

Provide event (a fully-formed platform event to evaluate) or a single reference (dataset_id, file_id, invocation_id, event_id, or scheduled_for), from which the server synthesizes an event. With an entity reference, event_type optionally picks which of the trigger’s subscribed event types to synthesize; the default is the trigger’s first subscribed event type compatible with the reference. A schedule-fired trigger needs no reference: the server synthesizes its next scheduled minute.

Bases: pydantic.BaseModel

The structured trace a trigger dry run produces.

Gates appear in evaluation order. The first failed gate is why the trigger would not fire; every gate after it is not_evaluated.

Bases: pydantic.BaseModel

Wire-transmissible representation of a trigger.

A firing source (a platform event subscription or a schedule), an optional condition over the firing’s namespace, and the targets to dispatch on a match. Cross-field rules — exposed roots, once_per legality, template placeholders — are enforced when the trigger is saved, by TriggerValidator.

Triggered work runs as the organization’s actions service user; a trigger cannot run its targets as anyone else.

A trigger’s firing source, discriminated on type.

Bases: roboto.compat.StrEnum

Discriminator for TriggerSource.

A trigger target spec, discriminated on type.

Bases: roboto.compat.StrEnum

The kind of thing a trigger does when it fires.

Save-time validation for triggers.

Enforces the cross-field rules that need the event catalog: a condition may only reference namespace roots exposed by every event the source fires for, once_per must be legal for every subscribed event, an action target’s file patterns need a dataset to match against and are themselves required when the firing event’s own file is the action’s input, and every target template placeholder must resolve to a shared exposed root (or a reserved envelope./trigger. context). A schedule fires for exactly one occurrence type, so the same rules apply to it with that occurrence’s roots.

Run before persistence so a trigger that could never fire — or could never resolve its templates — fails loudly with an actionable message instead of silently misbehaving at evaluation time.

TriggerValidator.validate()

TriggerValidator.validate_record()

Bases: pydantic.BaseModel

Request payload to update a trigger.

Only fields explicitly provided are changed; the NotSetType sentinel distinguishes “field omitted” from “field set to None”. The updated record must still satisfy every TriggerValidator rule.

Yield every RoboQL query in invocation_input, in document order.

Return invocation_input with transform applied to every RoboQL query it holds.

Build the sample for one event type.

The event, changed and tag roots are built by the same EventNamespace that serves them when a trigger fires; the entity roots are exactly the ones catalog exposes for the type.

A sample for every event type in catalog, in catalog order.

The schedule-fired trigger the schedule.fired sample is evaluated for, so the sample’s schedule root carries the cron a template may name.

The trigger the sample is evaluated for; what {{trigger.*}} sees.

Return query with each placeholder replaced by resolve’s value for it, escaped in place.

Each placeholder is substituted exactly once, and a value is escaped for the literal that encloses it, so a value that itself looks like a template or carries a quote stays data.

The kinds of target a trigger can have, as the web UI’s target picker reads them.

target_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. Each entry’s body is empty: a target carries no save-time constraint of its own, so the picker offers every type for every event.

Every dotted path a template may reference under prefix, in document order.

Walks nested mappings only. A list is a leaf, because path resolution descends through mappings and stops at anything else: dataset.tags is addressable, dataset.tags.0 is not.