roboto.domain.actions
Actions domain module for the Roboto SDK.
This module provides the core domain entities and operations for working with Actions, Invocations, and Triggers in the Roboto platform. Actions are reusable functions that process, transform, or analyze data. Invocations represent executions of actions, and Triggers automatically invoke actions when specific events or conditions occur.
The main classes in this module are:
Action: A reusable function to process dataInvocation: An execution instance of an actionTriggerandScheduledTrigger: the legacy trigger model, deprecated. Triggers now live inroboto.domain.triggers; the classes here remain only so existing code keeps working, and read only the triggers the old model can express.
Usage
Basic action invocation:
from roboto.domain.actions import Action, InvocationSource
action = Action.from_name("my_action", owner_org_id="my-org")
invocation = action.invoke(invocation_source=InvocationSource.Manual, parameter_values={"param1": "value1"})
invocation.wait_for_terminal_status()Creating a trigger:
from roboto.domain.actions import Trigger, TriggerForEachPrimitive
trigger = Trigger.create(
name="auto_process",
action_name="my_action",
required_inputs=["**/*.bag"],
for_each=TriggerForEachPrimitive.Dataset,
)Submodules
- roboto.domain.actions.action
- roboto.domain.actions.action_config
- roboto.domain.actions.action_operations
- roboto.domain.actions.action_record
- roboto.domain.actions.invocation
- roboto.domain.actions.invocation_operations
- roboto.domain.actions.invocation_record
- roboto.domain.actions.scheduled_trigger
- roboto.domain.actions.scheduled_trigger_operations
- roboto.domain.actions.scheduled_trigger_record
- roboto.domain.actions.stats
- roboto.domain.actions.trigger
- roboto.domain.actions.trigger_operations
- roboto.domain.actions.trigger_record
- roboto.domain.actions.trigger_view
Package Contents
Accessibility
Bases: roboto.compat.StrEnum
Controls who can query for and invoke an action.
Accessibility levels determine the visibility and usability of actions within the Roboto platform. Actions can be private to an organization or published publicly in the Action Hub.
Future accessibility levels may include: “user” and/or “team”.
Action
A reusable function to process, transform or analyze data in Roboto.
Actions are containerized functions that can be invoked to process datasets, files, or other data sources within the Roboto platform. They encapsulate processing logic, dependencies, and compute requirements, making data processing workflows reproducible and scalable.
Actions can be created, updated, invoked, and managed through this class. They support parameterization, inheritance from other actions, and can be triggered automatically based on events or conditions.
An Action consists of:
- Container image and execution parameters
- Input/output specifications
- Compute requirements (CPU, memory, etc.)
- Parameters that can be customized at invocation time
- Metadata and tags for organization
Actions are owned by organizations and can have different accessibility levels (private to organization or public in the Action Hub).
Parameters
roboto_client Optional[roboto.Properties
Action.accessibility
The accessibility level of this action (Organization or ActionHub).
Action.compute_requirements
The compute requirements (CPU, memory) for running this action.
Action.container_parameters
The container parameters including image URI and execution settings.
Action.create()
Create a new action in the Roboto platform.
Creates a new action with the specified configuration. The action will be owned by the caller’s organization and can be invoked to process data.
Parameters
name strUnique name for the action within the organization.
compute_requirements Optional[roboto.CPU, memory, and other compute specifications.
container_parameters Optional[roboto.Container image URI, entrypoint, and environment variables.
description Optional[str]Detailed description of what the action does.
inherits Optional[roboto.Reference to another action to inherit configuration from.
metadata Optional[dict[str, Any]]Custom key-value metadata to associate with the action.
parameters Optional[list[roboto.List of parameters that can be provided at invocation time.
requires_downloaded_inputs Optional[bool]Whether input files should be downloaded before execution.
short_description Optional[str]Brief description (max 140 characters) for display purposes.
tags Optional[list[str]]List of tags for categorizing and searching actions.
timeout Optional[int]Maximum execution time in minutes before the action is terminated.
uri Optional[str]Container image URI if not inheriting from another action.
caller_org_id Optional[str]Organization ID to create the action in. Defaults to caller’s org.
roboto_client Optional[roboto.Roboto client instance. Uses default if not provided.
Returns
The newly created Action instance.
Raises
If short_description exceeds 140 characters or other validation errors occur.
If the request is malformed.
If the caller lacks permission to create actions.
Usage
Create a simple action:
action = Action.create(
name="hello_world", uri="ubuntu:latest", description="A simple hello world action"
)Create an action with parameters and compute requirements:
from roboto.domain.actions import ComputeRequirements, ActionParameter
action = Action.create(
name="data_processor",
uri="my-registry.com/processor:v1.0",
description="Processes sensor data with configurable parameters",
compute_requirements=ComputeRequirements(vCPU=4096, memory=8192),
parameters=[
ActionParameter(name="threshold", required=True, description="Processing threshold"),
ActionParameter(name="output_format", default="json", description="Output format"),
],
tags=["data-processing", "sensors"],
timeout=60,
)Create an action that inherits from another:
base_action = Action.from_name("base_processor", owner_org_id="roboto-public")
derived_action = Action.create(
name="custom_processor",
inherits=base_action.record.reference,
description="Custom processor based on base_processor",
metadata={"version": "2.0", "team": "data-science"},
)Action.delete()
Delete this action from the Roboto platform.
Permanently removes this action and all its versions. This operation cannot be undone.
Raises
If the action is not found.
If the caller lacks permission to delete the action.
Return type
Usage
Delete an action:
action = Action.from_name("old_action")
action.delete()Action.from_name()
Load an existing action by name.
Retrieves an action from the Roboto platform by its name and optionally a specific version digest. Action names are unique within an organization, so a name + org_id combination always provides a fully qualified reference to a specific action.
Parameters
name strName of the action to retrieve. Must be unique within the organization.
digest Optional[str]Specific version digest of the action. If not provided, returns the latest version.
owner_org_id Optional[str]Organization ID that owns the action. If not provided, searches in the caller’s organization.
roboto_client Optional[roboto.Roboto client instance. Uses default if not provided.
Returns
The Action instance.
Raises
If the action is not found.
If the caller lacks permission to access the action.
Usage
Load the latest version of an action:
action = Action.from_name("data_processor")Load a specific version of an action:
action = Action.from_name("data_processor", digest="abc123def456")Load an action from another organization:
action = Action.from_name("public_processor", owner_org_id="roboto-public")Properties
Action.inherits_from
Reference to another action this action inherits configuration from.
Action.invoke()
Invokes this action using any inputs and options provided.
Executes this action with the specified parameters and returns an Invocation object that can be used to track progress and retrieve results.
Parameters
invocation_source roboto.Manual, trigger, etc.
data_source_type Optional[roboto.If set, should equal Dataset for backward compatibility.
data_source_id Optional[str]If set, should be a dataset ID for backward compatibility.
input_data Optional[Union[list[str], roboto.Either a list of file name patterns, or an InvocationInput specification.
upload_destination Optional[roboto.Default upload destination (e.g. dataset) for files written to the invocation’s output directory.
compute_requirement_overrides Optional[roboto.Overrides for the action’s default compute requirements (e.g. vCPU)
container_parameter_overrides Optional[roboto.Overrides for the action’s default container parameters (e.g. entrypoint)
idempotency_id Optional[str]Unique ID to ensure an invocation is run exactly once.
invocation_source_id Optional[str]ID of the trigger or manual operator performing the invocation.
parameter_values Optional[dict[str, Any]]Action parameter values.
timeout Optional[int]Action timeout in minutes.
caller_org_id Optional[str]Org ID of the caller.
Returns
An Invocation object that can be used to track the invocation’s progress.
Raises
Invalid method parameters or combinations.
Incorrectly formed request.
The caller is not authorized to invoke this action.
Usage
Basic invocation with a dataset:
from roboto import Action, InvocationSource
action = Action.from_name("ros_ingestion", owner_org_id="roboto-public")
iv = action.invoke(
invocation_source=InvocationSource.Manual,
data_source_id="ds_12345",
data_source_type=InvocationDataSourceType.Dataset,
input_data=["**/*.bag"],
upload_destination=InvocationUploadDestination.dataset("ds_12345"),
)
iv.wait_for_terminal_status()Invocation with compute requirement overrides:
from roboto import Action, InvocationSource, ComputeRequirements
action = Action.from_name("image_processing", owner_org_id="roboto-public")
compute_reqs = ComputeRequirements(vCPU=4096, memory=8192)
iv = action.invoke(
invocation_source=InvocationSource.Manual,
compute_requirement_overrides=compute_reqs,
parameter_values={"threshold": 0.75},
)
status = iv.wait_for_terminal_status()
print(status)
# 'COMPLETED'Properties
Action.metadata
Custom metadata key-value pairs associated with this action.
Action.modified
The timestamp when this action was last modified.
Action.parameters
The list of parameters that can be provided when invoking this action.
Action.published
The timestamp when this action was published to the Action Hub, if applicable.
Action.query()
Query actions with optional filtering and pagination.
Searches for actions based on the provided query specification. Can search within an organization or across the public Action Hub.
Parameters
spec Optional[roboto.Query specification with filters, sorting, and pagination. If not provided, returns all accessible actions.
accessibility roboto.Whether to search organization actions or public Action Hub. Defaults to Organization.
owner_org_id Optional[str]Organization ID to search within. If not provided, searches in the caller’s organization.
roboto_client Optional[roboto.Roboto client instance. Uses default if not provided.
Yields
Action instances matching the query criteria.
Raises
ValueErrorIf the query specification contains unknown fields.
If the caller lacks permission to query actions.
Return type
Usage
Query all actions in your organization:
for action in Action.query():
print(f"Action: {action.name}")Query actions with specific tags:
from roboto.query import QuerySpecification
spec = QuerySpecification().where("tags").contains("ml")
for action in Action.query(spec):
print(f"ML Action: {action.name}")Query public actions in the Action Hub:
from roboto.domain.actions import Accessibility
spec = QuerySpecification().where("name").contains("ros")
for action in Action.query(spec, accessibility=Accessibility.ActionHub):
print(f"Public ROS Action: {action.name}")Query with pagination:
spec = QuerySpecification().limit(10).order_by("created", ascending=False)
recent_actions = list(Action.query(spec))
print(f"Found {len(recent_actions)} recent actions")Properties
Action.record
The underlying action record containing all action data.
Action.requires_downloaded_inputs
Whether input files should be downloaded before executing this action.
Action.set_accessibility()
Set the accessibility level of this action.
Changes whether this action is private to the organization or published to the public Action Hub.
Parameters
accessibility roboto.The new accessibility level (Organization or ActionHub).
Returns
This Action instance with updated accessibility.
Raises
If the caller lacks permission to modify the action.
Usage
Make an action public in the Action Hub:
from roboto.domain.actions import Accessibility
action = Action.from_name("my_action")
action.set_accessibility(Accessibility.ActionHub)Make an action private to the organization:
action.set_accessibility(Accessibility.Organization)Properties
Action.short_description
A brief description of the action (max 140 characters) for display purposes.
Action.tags
The list of tags associated with this action for categorization.
Action.timeout
The maximum execution time in minutes before the action is terminated.
Action.to_dict()
Convert this action to a dictionary representation.
Returns
Dictionary containing all action data in JSON-serializable format.
Usage
Get action as dictionary:
action = Action.from_name("my_action")
action_dict = action.to_dict()
print(action_dict["name"])
# 'my_action'Action.update()
Update this action with new configuration.
Updates the action with the provided changes. Only specified parameters will be modified; others remain unchanged. This creates a new version of the action.
Parameters
compute_requirements Optional[Union[roboto.New compute requirements (CPU, memory).
container_parameters Optional[Union[roboto.New container parameters (image, entrypoint, etc.).
description Optional[Union[str, roboto.New detailed description.
inherits Optional[Union[roboto.New action reference to inherit from.
metadata_changeset Union[roboto.Changes to apply to metadata (add, remove, update keys).
parameter_changeset Union[roboto.Changes to apply to parameters (add, remove, update).
short_description Optional[Union[str, roboto.New brief description (max 140 characters).
timeout Optional[Union[int, roboto.New maximum execution time in minutes.
uri Optional[Union[str, roboto.New container image URI.
requires_downloaded_inputs Union[bool, roboto.Whether to download input files before execution.
Returns
This Action instance with updated configuration.
Raises
If short_description exceeds 140 characters or other validation errors occur.
If the caller lacks permission to update the action.
Usage
Update action description and timeout:
action = Action.from_name("my_action")
action.update(description="Updated description of what this action does", timeout=45)Update compute requirements:
from roboto.domain.actions import ComputeRequirements
action.update(compute_requirements=ComputeRequirements(vCPU=4096, memory=8192))Add metadata using changeset:
from roboto.updates import MetadataChangeset
changeset = MetadataChangeset().set("version", "2.0").set("team", "ml")
action.update(metadata_changeset=changeset)Properties
ActionConfig
Bases: pydantic.BaseModel
User-facing model for Action configuration used when creating or updating Actions.
This model defines the structure of the “action.json” file accepted by roboto actions create --from-file and templated for new Roboto Actions created by roboto actions init.
ActionConfig intentionally differs from roboto.domain.actions.action_record.ActionRecord by providing a simplified interface that: - Omits platform-managed fields (e.g., created, modified, org_id, digest) - Omits post-creation fields (e.g., published, accessibility) - Focuses on user-configurable options relevant at creation time
Structure:
- Required:
name - Optional: Most configuration options (compute requirements, parameters, metadata, etc.)
Parameters
data AnyAttributes
ActionConfig.compute_requirements
ActionConfig.container_parameters
ActionConfig.description
ActionConfig.docker_config
Configuration with which to build a Docker image for the Action.
ActionConfig.enforce_invariants()
Parameters
values dictReturn type
ActionConfig.from_file()
Load ActionConfig from a JSON file.
Parameters
path pathlib.Path to the JSON file containing action configuration
Returns
Parsed ActionConfig instance
Raises
FileNotFoundErrorIf the file doesn’t exist
pydantic.ValidationErrorIf the JSON is invalid or doesn’t match the schema
Attributes
ActionConfig.image_uri
URI to a non-local Docker image. Must already be pushed a registry accessible by the Roboto Platform.
ActionConfig.inherits
ActionConfig.metadata
ActionConfig.model_config
model_config #Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
ActionConfig.name
ActionConfig.parameters
ActionConfig.requires_downloaded_inputs
ActionConfig.short_description
ActionConfig.tags
ActionConfig.timeout
ActionParameter
Bases: pydantic.BaseModel
A parameter that can be provided to an Action at invocation time.
Action parameters allow customization of action behavior without modifying the action itself. Parameters can be required or optional, have default values, and include descriptions for documentation.
Parameters are validated when an action is invoked, ensuring that required parameters are provided and that values conform to expected types.
Parameters
data AnyAttributes
ActionParameter.default
Default value applied for parameter if it is not required and no value is given at invocation.
Accepts any default value, but coerced to a string.
ActionParameter.description
Human-readable description of the parameter.
ActionParameter.model_config
model_config #Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
ActionParameter.required
Whether this parameter is required at invocation time.
ActionParameter.validate_default()
Parameters
v Optional[Any]Return type
ActionParameterChangeset
Bases: pydantic.BaseModel
A changeset used to modify Action parameters.
Parameters
data AnyActionParameterChangeset.Builder
ActionParameterChangeset.Builder.build()
Return type
ActionParameterChangeset.Builder.put_parameter()
Parameters
parameter ActionParameterReturn type
ActionParameterChangeset.Builder.remove_parameter()
Parameters
parameter_name strReturn type
ActionParameterChangeset.is_empty()
Return type
Attributes
ActionParameterChangeset.put_parameters
Parameters to add or update.
ActionParameterChangeset.remove_parameters
Names of parameters to remove.
ActionProvenance
ActionRecord
Bases: pydantic.BaseModel
A wire-transmissible representation of an action.
Attributes
ActionRecord.accessibility
ActionRecord.compute_digest()
Return type
Attributes
ActionRecord.compute_requirements
ActionRecord.container_parameters
ActionRecord.created
ActionRecord.created_by
ActionRecord.description
ActionRecord.digest
ActionRecord.inherits
ActionRecord.metadata
ActionRecord.modified
ActionRecord.modified_by
ActionRecord.name
ActionRecord.org_id
ActionRecord.parameters
ActionRecord.published
Properties
Attributes
ActionRecord.requires_downloaded_inputs
ActionRecord.serialize_metadata()
Parameters
metadata dict[str, Any]Return type
ActionReference
ActionStatsRecord
Bases: pydantic.BaseModel
Statistical summary of action invocations for a specific action within a time period.
This model represents aggregated invocation counts for a single action, broken down by completion status (completed, failed, queued).
Parameters
data AnyAttributes
ActionStatsRecord.action_name
Name of the action. Action names are unique within an organization.
ActionStatsRecord.completed_count
Number of invocations that completed successfully during the time period.
ActionStatsRecord.fail_count
Number of invocations that failed during the time period.
ActionStatsRecord.queued_count
Number of invocations that are currently queued or in progress during the time period.
CancelActiveInvocationsRequest
Bases: pydantic.BaseModel
Request payload to bulk cancel all active invocations within an organization.
This operation cancels multiple invocations in a single request, but only affects invocations that are in non-terminal states (Queued, Running, etc.). The operation is limited in the number of invocations it will attempt to cancel in a single call for performance reasons.
For large numbers of active invocations, continue calling this operation until the has_more returned in the response is False.
Parameters
data AnyAttributes
CancelActiveInvocationsRequest.created_before
Only cancel invocations created before this timestamp.
If not provided, cancels all active invocations regardless of age.
CancelActiveInvocationsResponse
Bases: pydantic.BaseModel
Response payload from bulk cancellation of active invocations.
Contains the results of a bulk cancellation operation, including counts of successful and failed cancellations, and whether there are more active invocations to cancel.
Parameters
data AnyAttributes
CancelActiveInvocationsResponse.failure_count
Number of invocations that failed to cancel.
CancelActiveInvocationsResponse.has_more
Whether there are more active invocations to cancel.
CancelActiveInvocationsResponse.success_count
Number of invocations successfully cancelled.
ComputeRequirements
Bases: pydantic.BaseModel
Compute requirements for an action invocation.
Parameters
data AnyAttributes
ComputeRequirements.memory
Container memory in MiB. Set to 1024 MiB by default.
The possible values depend on the CPU units chosen, with as little as 512 MiB and as much as 122,800 MiB (120 GiB).
ComputeRequirements.model_config
model_config #Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
ComputeRequirements.storage
Container storage in GiB. Set to 21 GiB by default.
The minimum allowed value is 21 GiB, and the maximum allowed value is 200 GiB (for premium-tier orgs).
ComputeRequirements.vCPU
Container CPU units. Set to 512 by default.
1024 CPU units equal 1 vCPU.
Possible values: 256, 512, 1024, 2048, 4096, 8192, 16384.
ComputeRequirements.validate_storage_limit()
ComputeRequirements.validate_vcpu_mem_combination()
Return type
ContainerParameters
Bases: pydantic.BaseModel
Container parameters for an action invocation.
Parameters
data AnyAttributes
ContainerParameters.command
ContainerParameters.entry_point
ContainerParameters.env_vars
ContainerParameters.model_config
model_config #Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
ContainerParameters.workdir
CreateActionRequest
Bases: pydantic.BaseModel
Request payload to create a new action.
Contains all the configuration needed to create a new action in the Roboto platform, including container settings, compute requirements, parameters, and metadata.
Parameters
data AnyAttributes
CreateActionRequest.compute_requirements
CPU, memory, and other compute specifications.
CreateActionRequest.container_parameters
Container image URI, entrypoint, and environment variables.
CreateActionRequest.description
Detailed description of what the action does.
CreateActionRequest.inherits
Reference to another action to inherit configuration from.
CreateActionRequest.metadata
Custom key-value metadata to associate with the action.
CreateActionRequest.parameters
List of parameters that can be provided at invocation time.
CreateActionRequest.requires_downloaded_inputs
Whether input files should be downloaded before execution.
CreateActionRequest.short_description
Brief description (max 140 characters) for display purposes.
CreateActionRequest.timeout
Maximum execution time in minutes before the action is terminated.
CreateActionRequest.uri
Container image URI if not inheriting from another action.
CreateInvocationRequest
Bases: pydantic.BaseModel
Request payload to create a new action invocation.
Contains all the configuration needed to invoke an action, including input data specifications, parameter values, and execution overrides.
Parameters
data AnyAttributes
CreateInvocationRequest.compute_requirement_overrides
compute_requirement_overrides roboto.Optional overrides for CPU, memory, and other compute specifications.
CreateInvocationRequest.container_parameter_overrides
container_parameter_overrides roboto.Optional overrides for container image, entrypoint, and environment variables.
CreateInvocationRequest.data_source_id
ID of the data source providing input data.
CreateInvocationRequest.data_source_type
Type of the data source (e.g., Dataset).
CreateInvocationRequest.idempotency_id
Optional unique ID to ensure the invocation runs exactly once.
CreateInvocationRequest.input_data
List of file patterns for input data selection.
CreateInvocationRequest.invocation_source
Source of the invocation (Manual, Trigger, etc.).
CreateInvocationRequest.invocation_source_id
Optional ID of the entity that initiated the invocation.
CreateInvocationRequest.parameter_values
Optional parameter values to pass to the action.
CreateInvocationRequest.rich_input_data
Optional rich input data specification that supersedes the simple input_data patterns.
CreateInvocationRequest.upload_destination
upload_destination roboto.Optional destination for output files.
CreateScheduledTriggerRequest
Bases: pydantic.BaseModel
Request payload to create a scheduled trigger.
See create() for details on the request attributes.
Parameters
data AnyAttributes
CreateScheduledTriggerRequest.action_name
CreateScheduledTriggerRequest.action_owner_id
CreateScheduledTriggerRequest.compute_requirement_overrides
compute_requirement_overrides roboto.CreateScheduledTriggerRequest.container_parameter_overrides
container_parameter_overrides roboto.CreateScheduledTriggerRequest.enabled
CreateScheduledTriggerRequest.invocation_input
CreateScheduledTriggerRequest.invocation_upload_destination
invocation_upload_destination roboto.CreateScheduledTriggerRequest.name
CreateScheduledTriggerRequest.parameter_values
CreateScheduledTriggerRequest.schedule
CreateScheduledTriggerRequest.timeout
CreateTriggerRequest
Bases: pydantic.BaseModel
Request payload to create a new trigger.
Contains all the configuration needed to create a trigger that automatically invokes actions when specific conditions are met.
Parameters
data AnyAttributes
CreateTriggerRequest.action_digest
Optional specific version digest of the action to invoke. If not provided, uses the latest version.
CreateTriggerRequest.action_name
Name of the action to invoke when the trigger fires.
CreateTriggerRequest.action_owner_id
Organization ID that owns the target action. If not provided, searches in the caller’s organization.
CreateTriggerRequest.additional_inputs
Optional additional file patterns to include in action invocations beyond the required inputs.
CreateTriggerRequest.causes
List of events that can cause this trigger to be evaluated. If not provided, uses default causes.
CreateTriggerRequest.compute_requirement_overrides
Optional compute requirement overrides for action invocations.
CreateTriggerRequest.condition
Optional condition that must be met for the trigger to fire.
Can filter based on metadata, file properties, etc.
CreateTriggerRequest.container_parameter_overrides
Optional container parameter overrides for action invocations.
CreateTriggerRequest.enabled
Whether the trigger should be active immediately after creation.
CreateTriggerRequest.for_each
Granularity of execution - Dataset or DatasetFile.
CreateTriggerRequest.name
Unique name for the trigger (alphanumeric, hyphens, underscores only, max 256 characters).
CreateTriggerRequest.parameter_values
Parameter values to pass to the action when invoked.
CreateTriggerRequest.required_inputs
List of file patterns that must be present for the trigger to fire. Uses glob patterns like ‘**/*.bag’.
CreateTriggerRequest.service_user_id
Optional service user ID for authentication.
CreateTriggerRequest.timeout
Optional timeout override for action invocations in minutes.
CreateTriggerRequest.validate_additional_inputs()
Parameters
value Optional[list[str]]Return type
CreateTriggerRequest.validate_required_inputs()
Parameters
value list[str]Return type
DataSelector
Bases: pydantic.BaseModel
Selector for inputs (e.g. files) to an action invocation.
Parameters
data AnyAttributes
DataSelector.dataset_id
Dataset ID, needed for backward compatibility purposes. Prefer RoboQL: dataset_id = <the ID in double quotes>
DataSelector.ensure_not_empty()
Return type
EvaluateTriggersRequest
Bases: pydantic.BaseModel
Request payload to manually evaluate specific triggers.
Used to force evaluation of triggers outside of their normal automatic evaluation cycle. This is typically used for testing or debugging trigger behavior.
Parameters
data AnyAttributes
EvaluateTriggersRequest.trigger_evaluation_ids
Collection of trigger evaluation IDs to process.
ExecutableProvenance
ExecutorContainer
Bases: enum.Enum
Type of container running as part of an action invocation
FileSelector
Bases: DataSelector
Selector for file inputs to an action invocation.
This selector type exists for backward compatibility purposes. We encourage you to use the query field to scope your input query to any dataset and/or file paths.
Parameters
data AnyFileSelector.ensure_not_empty()
Return type
Attributes
FileSelector.paths
File paths or patterns. Prefer RoboQL: path LIKE <path pattern in double quotes>
Invocation
An instance of an execution of an action, initiated manually by a user or automatically by a trigger.
An Invocation represents a single execution of an Action with specific inputs, parameters, and configuration. It tracks the execution lifecycle from creation through completion, including status updates, logs, and results.
Invocations are created by calling Action.invoke() or through the UI. They cannot be created directly through the constructor. Each invocation has a unique ID and maintains a complete audit trail of its execution.
Key features:
- Status tracking (Queued, Running, Completed, Failed, etc.)
- Input data specification and parameter values
- Compute requirement and container parameter overrides
- Log collection and output file management
- Progress monitoring and result retrieval
Parameters
roboto_client Optional[roboto.Properties
Invocation.action
Provenance information about the action that was invoked.
Invocation.cancel()
Cancel this invocation if it is not already in a terminal status.
Attempts to cancel the invocation. If the invocation has already completed, failed, or reached another terminal status, this method has no effect.
Raises
If the invocation is not found.
If the caller lacks permission to cancel the invocation.
Return type
Usage
Cancel a running invocation:
invocation = Invocation.from_id("iv_12345")
if not invocation.reached_terminal_status:
invocation.cancel()Properties
Invocation.compute_requirements
The compute requirements (CPU, memory) used for this invocation.
Invocation.container_parameters
The container parameters used for this invocation.
Invocation.created
The timestamp when this invocation was created.
Invocation.current_status
The current status of this invocation (e.g., Queued, Running, Completed).
Invocation.data_source
The data source that provided input data for this invocation.
Invocation.executable
Provenance information about the executable (container) that was run.
Invocation.from_id()
Load an existing invocation by its ID.
Retrieves an invocation from the Roboto platform using its unique identifier.
Parameters
invocation_id strThe unique ID of the invocation to retrieve.
roboto_client Optional[roboto.Roboto client instance. Uses default if not provided.
Returns
The Invocation instance.
Raises
If the invocation is not found.
If the caller lacks permission to access the invocation.
Usage
Load an invocation and check its status:
invocation = Invocation.from_id("iv_12345")
print(f"Status: {invocation.current_status}")
print(f"Created: {invocation.created}")Invocation.get_logs()
Retrieve runtime STDOUT/STDERR logs generated during this invocation’s execution.
Fetches log records from the invocation’s container execution, with support for pagination to handle large log volumes.
Parameters
page_token Optional[str]Optional token for pagination. If provided, starts retrieving logs from that point.
Yields
LogRecord instances containing log messages and metadata.
Raises
If the invocation is not found.
If the caller lacks permission to access logs.
Return type
Properties
Invocation.input_data
The input data specification for this invocation, if any.
Invocation.is_queued_for_scheduling()
An invocation is queued for scheduling if:
1. its most recent status is “Queued” 3. and is not “Deadly”
Return type
Invocation.query()
Query invocations with optional filtering and pagination.
Searches for invocations based on the provided query specification. Can filter by status, action name, creation time, and other attributes.
Parameters
spec Optional[roboto.Query specification with filters, sorting, and pagination. If not provided, returns all accessible invocations.
owner_org_id Optional[str]Organization ID to search within. If not provided, searches in the caller’s organization.
roboto_client Optional[roboto.Roboto client instance. Uses default if not provided.
Yields
Invocation instances matching the query criteria.
Raises
ValueErrorIf the query specification contains unknown fields.
If the query filters or sorts on a field the invocations API does not accept.
If the caller lacks permission to query invocations.
Return type
Usage
Query all invocations:
for invocation in Invocation.query():
print(f"Invocation: {invocation.id}")Query invocations whose data source is a given dataset:
from roboto.query import Comparator, Condition, QuerySpecification
spec = QuerySpecification(
condition=Condition(
field="data_source_id",
comparator=Comparator.Equals,
value="ds_abc123",
)
)
for invocation in Invocation.query(spec):
print(invocation.id)Query completed invocations:
from roboto.domain.actions import InvocationStatus
spec = QuerySpecification(
condition=Condition(
field="last_status",
comparator=Comparator.Equals,
value=InvocationStatus.Completed.value,
)
)
completed = list(Invocation.query(spec))Query the ten most recent invocations. Neither limit nor max_results caps an invocation query, so take the first ten from the generator:
import itertools
from roboto.query import SortDirection
spec = QuerySpecification(sort_by="created", sort_direction=SortDirection.Descending)
recent = list(itertools.islice(Invocation.query(spec), 10))Properties
Invocation.reached_terminal_status
True if this invocation has reached a terminal status (Completed, Failed, etc.).
Invocation.record
The underlying invocation record containing all invocation data.
Invocation.refresh()
Return type
Invocation.set_container_image_digest()
This is an admin-only operation to memorialize the digest of the container image that was pulled in the course of invoking the action.
Parameters
digest strReturn type
Invocation.set_logs_location()
This is an admin-only operation to memorialize the base location where invocation logs are saved.
Use the “get_logs” or “stream_logs” methods to access invocation logs.
Parameters
Return type
Properties
Invocation.source
Provenance information about the source that initiated this invocation.
Invocation.status_log
The complete history of status changes for this invocation.
Invocation.stream_logs()
Parameters
last_read Optional[str]Return type
Properties
Invocation.to_dict()
Return type
Invocation.update_status()
Parameters
detail Optional[str]Return type
Properties
Invocation.upload_destination
The destination where output files from this invocation will be uploaded.
Invocation.wait_for_terminal_status()
Wait for the invocation to reach a terminal status.
Throws a TimeoutError if the timeout is reached.
Parameters
timeout floatThe maximum amount of time, in seconds, to wait for the invocation to reach a terminal status.
poll_interval roboto.The amount of time, in seconds, to wait between polling iterations.
Return type
InvocationDataSource
Bases: pydantic.BaseModel
Abstracted data source that can be provided to an invocation.
Represents a source of input data for action invocations. The data source type determines how the ID should be interpreted (e.g., as a dataset ID).
Parameters
data AnyAttributes
InvocationDataSource.data_source_id
The ID of the data source. For Dataset type, this is a dataset ID.
InvocationDataSource.data_source_type
The type of data source (currently only Dataset).
InvocationDataSource.is_unspecified()
Check if this data source is unspecified.
Returns
True if this is an unspecified data source, False otherwise.
InvocationDataSource.unspecified()
Returns a special value indicating that no invocation source is specified.
Returns
An InvocationDataSource instance representing an unspecified data source.
InvocationDataSourceType
Bases: enum.Enum
Source of data for an action’s input binding.
Defines the type of data source that provides input data to an action invocation. Currently supports datasets, with potential for future expansion to other data source types.
Attributes
InvocationDataSourceType.Dataset
InvocationInput
Bases: pydantic.BaseModel
Input specification for an action invocation.
An invocation may require no inputs at all, or some combination of Roboto files, topics, events, etc. Those are specified using selectors, which tell the invocation how to locate inputs. Selector choices include RoboQL queries (for maximum flexibility), as well as unique IDs or friendly names.
Note: support for certain input types is a work in progress, and will be offered in future Roboto platform releases.
At least one data selector must be provided in order to construct a valid InvocationInput instance.
Parameters
data AnyInvocationInput.ensure_not_empty()
Return type
Properties
InvocationInput.file_query()
Specify file inputs using a RoboQL query.
Parameters
roboql_query strReturn type
Attributes
InvocationInput.from_dataset_file_paths()
Specify file input by dataset ID and dataset-relative file paths or globs.
Parameters
dataset_id strfile_paths list[str]Return type
InvocationInput.from_session_id()
Specify session input by session ID.
Parameters
session_id strReturn type
Properties
InvocationInput.safe_files
File selectors as a list. Empty if no such selectors are specified.
InvocationInput.safe_sessions
Session selectors as a list. Empty if no such selectors are specified.
InvocationInput.safe_topics
Topic selectors as a list. Empty if no such selectors are specified.
InvocationInput.session_query()
Specify session inputs using a RoboQL query.
Parameters
roboql_query strReturn type
Attributes
InvocationInput.sessions
Session selectors.
InvocationInput.topic_query()
Specify topic inputs using a RoboQL query.
Parameters
roboql_query strReturn type
Attributes
InvocationProvenance
Bases: pydantic.BaseModel
Provenance information for an invocation
Parameters
data AnyAttributes
InvocationProvenance.executable
The underlying executable (e.g., Docker image) that was run.
InvocationRecord
Bases: pydantic.BaseModel
A wire-transmissible representation of an invocation.
Parameters
data AnyAttributes
InvocationRecord.compute_requirements
InvocationRecord.container_parameters
InvocationRecord.created
InvocationRecord.data_source
InvocationRecord.duration
InvocationRecord.idempotency_id
InvocationRecord.input_data
InvocationRecord.invocation_id
InvocationRecord.last_heartbeat
InvocationRecord.last_status
InvocationRecord.org_id
InvocationRecord.parameter_values
InvocationRecord.provenance
InvocationRecord.rich_input_data
InvocationRecord.status
InvocationRecord.timeout
InvocationRecord.upload_destination
InvocationSource
InvocationStatus
Bases: int, enum.Enum
Invocation status enum
Attributes
InvocationStatus.Cancelled
InvocationStatus.Completed
InvocationStatus.Deadly
InvocationStatus.Downloading
InvocationStatus.Failed
InvocationStatus.Processing
InvocationStatus.Queued
InvocationStatus.Scheduled
InvocationStatus.Uploading
InvocationStatus.can_transition_to()
Parameters
other InvocationStatusReturn type
InvocationStatus.from_value()
Parameters
v Union[int, str]Return type
InvocationStatus.is_running()
Return type
InvocationStatus.is_terminal()
Return type
InvocationStatus.next()
Return type
InvocationStatusRecord
Bases: pydantic.BaseModel
A wire-transmissible representation of an invocation status.
Parameters
data AnyAttributes
InvocationStatusRecord.detail
InvocationStatusRecord.status
InvocationStatusRecord.timestamp
InvocationStatusRecord.to_presentable_dict()
Return type
InvocationUploadDestination
Bases: pydantic.BaseModel
Default destination to which invocation outputs - if any - should be uploaded.
Specifies where files generated during action execution should be stored. Actions can write files to their output directory, and this destination determines where those files are uploaded after execution completes.
Parameters
data AnyInvocationUploadDestination.dataset()
Create a dataset upload destination with the given ID.
Parameters
dataset_id strThe ID of the dataset where outputs should be uploaded.
Returns
An InvocationUploadDestination configured for the specified dataset.
Attributes
InvocationUploadDestination.destination_id
Optional identifier for the upload destination. In the case of a dataset, it would be the dataset ID.
InvocationUploadDestination.destination_type
Type of upload destination. By default, outputs are uploaded to a dataset.
Properties
InvocationUploadDestination.is_dataset
True if this is a dataset destination with a dataset ID, False otherwise.
Returns
True if this destination is configured for a dataset with a valid ID.
InvocationUploadDestination.is_unknown
True if the upload destination is not of a supported type, False otherwise.
InvocationUploadDestination.pre_validate_destination_type()
Parameters
value AnyReturn type
LogRecord
Bases: pydantic.BaseModel
A wire-transmissible representation of a log record.
Parameters
data AnyAttributes
LogRecord.log
LogRecord.partial_id
LogRecord.process
LogRecord.timestamp
LogsLocation
QueryTriggersRequest
Bases: pydantic.BaseModel
Request payload to query triggers with filters.
Used to search for triggers based on various criteria such as name, status, or other attributes.
Parameters
data AnyScheduledTrigger
A trigger that invokes actions on a recurring schedule, e.g. hourly or daily.
Schedules are currently specified using standard Cron expressions, with times in UTC. A handful of common schedules are provided by the TriggerSchedule class.
Once a scheduled time is reached, the action associated with this trigger will be invoked using the optionally provided input specification, and any other overrides such as compute requirements or parameter values.
Parameters
roboto_client Optional[roboto.Properties
ScheduledTrigger.action_reference
Reference to the action this trigger invokes.
ScheduledTrigger.compute_requirement_overrides
Optional compute requirement overrides.
ScheduledTrigger.container_parameter_overrides
Optional container parameter overrides.
ScheduledTrigger.create()
Create a new scheduled trigger.
If the trigger is enabled on creation, action invocations will commence on the provided schedule. Note that the total number of active triggers in an organization is subject to a tier-specific limit. Exceeding that limit will result in the trigger being disabled.
Parameters
name strUnique name for the scheduled trigger. Must not exceed 256 characters.
schedule Union[str, TriggerSchedule]Recurring schedule for the trigger, e.g. hourly.
action_name strName of the action to invoke on schedule.
action_owner_id Optional[str]Organization ID that owns the target action. If not provided, searches the caller’s organization.
compute_requirement_overrides Optional[roboto.Optional compute requirement overrides for action invocations.
container_parameter_overrides Optional[roboto.Optional container parameter overrides for action invocations.
enabled boolWhether the trigger should be active immediately after creation.
invocation_input Optional[roboto.Optional input specification to be used for all scheduled action invocations.
invocation_upload_destination Optional[roboto.Optional upload destination for invocation outputs. Currently supports datasets.
parameter_values Optional[dict[str, Any]]Optional parameter values to pass to the action when invoked.
timeout Optional[int]Optional timeout override for action invocations, in minutes.
caller_org_id Optional[str]Organization ID to create the trigger in. Defaults to caller’s org.
roboto_client Optional[roboto.Roboto client instance. If not provided, defaults to the caller’s Roboto configuration.
Returns
The newly created ScheduledTrigger instance.
Raises
ValueErrorIf request parameters have invalid values, e.g. a negative timeout.
If the request cannot be satisfied as provided.
If the caller lacks permission to create triggers, invoke the specified action or upload to the specified upload destination.
If a scheduled trigger with the provided name already exists in the target organization.
If the caller has exceeded their organization’s maximum action timeout limit (in minutes).
Usage
Create an hourly trigger to invoke an analytics action with no explicit inputs:
from roboto.domain.actions import ScheduledTrigger, TriggerSchedule
scheduled_trigger = ScheduledTrigger.create(
name="analytics_action_hourly_trigger",
action_name="analytics_action",
schedule=TriggerSchedule.hourly(),
)Create a daily trigger to invoke an action that processes CSV files created after a given date:
from roboto.domain.actions import ScheduledTrigger, TriggerSchedule, InvocationInput
scheduled_trigger = ScheduledTrigger.create(
name="csv_processor_daily_trigger",
action_name="csv_processor",
schedule=TriggerSchedule.daily(),
invocation_input=InvocationInput.file_query("created > '2025-04-05' AND path LIKE '%.csv'"),
)ScheduledTrigger.delete()
Delete this scheduled trigger.
Return type
ScheduledTrigger.disable()
Disable this scheduled trigger.
If the trigger is already disabled, the call has no effect.
Any currently running scheduled invocations will proceed to completion, but no new scheduled invocations will occur, unless and until the trigger is re-enabled.
Return type
ScheduledTrigger.enable()
Enable this scheduled trigger.
If the trigger is already enabled, the call has no effect.
The total number of active triggers within an organization is subject to a tier-specific limit. If this operation results in the limit being exceeded, this trigger will remain disabled.
Returns
True if the trigger is now enabled, False otherwise.
Properties
ScheduledTrigger.from_id()
Fetch a scheduled trigger by its unique ID.
Parameters
trigger_id strUnique trigger ID.
owner_org_id Optional[str]Organization ID which owns the trigger. Defaults to caller’s org.
roboto_client Optional[roboto.Roboto client instance. If not provided, defaults to the caller’s Roboto configuration.
Returns
The ScheduledTrigger with the provided unique ID.
Raises
If no scheduled trigger exists with the provided ID in the target organization.
If the caller is not a member of the trigger’s target organization.
ScheduledTrigger.from_name()
Fetch a scheduled trigger by its unique name within an organization.
Parameters
name strName of the scheduled trigger.
owner_org_id Optional[str]Organization ID which owns the trigger. Defaults to caller’s org.
roboto_client Optional[roboto.Roboto client instance. If not provided, defaults to the caller’s Roboto configuration.
Returns
The ScheduledTrigger with the provided unique name.
Raises
If no scheduled trigger exists with the provided name in the target organization.
If the caller is not a member of the trigger’s target organization.
ScheduledTrigger.get_action()
Get the target Action for this scheduled trigger.
Returns
The action this trigger invokes on a recurring schedule.
ScheduledTrigger.get_evaluations()
Get the evaluation history for this scheduled trigger.
Under normal circumstances, this trigger’s target action will simply be invoked on the configured schedule, for as long as the trigger is enabled. However, it’s possible that an error occurs when attempting to invoke the action. In either case, a trigger evaluation record is created to capture the details of what happened.
Returns
A generator that yields TriggerEvaluationRecord instances, ordered by descending evaluation start time.
ScheduledTrigger.get_invocations()
Get the scheduled invocations initiated by this trigger, if any.
Returns
A generator that yields Invocation instances for any scheduled invocations kicked off by this trigger. The invocations are ordered from most to least recently created.
Properties
ScheduledTrigger.invocation_input
Optional input specification for action invocations.
ScheduledTrigger.invocation_upload_destination
invocation_upload_destination roboto.Optional upload destination for action invocation outputs.
ScheduledTrigger.modified
Last modification time for this scheduled trigger.
ScheduledTrigger.modified_by
User who last modified this scheduled trigger.
ScheduledTrigger.name
This trigger’s name, unique among scheduled triggers in the org.
ScheduledTrigger.org_id
Organization ID which owns this scheduled trigger.
ScheduledTrigger.parameter_values
Optional action parameter values.
ScheduledTrigger.record
Wire-transmissible representation of this scheduled trigger.
ScheduledTrigger.timeout
Optional invocation timeout, in minutes.
ScheduledTrigger.update()
Update this scheduled trigger.
Changing the action associated with this trigger, or the default upload destination, are subject to authorization checks. Enabling the trigger or changing the target action’s timeout are subject to tier-specific organization limit checks.
Per Roboto convention, the sentinel value NotSet is the default for all arguments to this call, indicating that the corresponding trigger attribute should not be updated. The value None, on the other hand, indicates that the relevant trigger attribute should be set to None (i.e. cleared).
Parameters
action_name Union[str, roboto.Name of the target action to associate with this trigger.
action_owner_id Union[str, roboto.Organization ID that owns the target action.
compute_requirement_overrides Union[Optional[roboto.Optional compute requirement overrides for action invocations.
container_parameter_overrides Union[Optional[roboto.Optional container parameter overrides for action invocations.
enabled Union[bool, roboto.Whether the trigger should be active immediately after creation.
invocation_input Union[Optional[roboto.Optional input specification to be used for all scheduled action invocations.
invocation_upload_destination Union[Optional[roboto.Optional upload destination for invocation outputs.
parameter_values Union[Optional[dict[str, Any]], roboto.Optional parameter values to pass to the action when invoked.
schedule Union[str, TriggerSchedule, roboto.Recurring schedule for the trigger, e.g. hourly.
timeout Union[Optional[int], roboto.Optional timeout override for action invocations, in minutes.
Returns
This trigger with any updates applied.
Raises
ValueErrorIf request parameters have invalid values, e.g. a negative timeout.
If the request cannot be satisfied as provided.
If the caller lacks permission to invoke the specified action or upload to the specified upload destination.
If the caller has exceeded their organization’s maximum action timeout limit (in minutes).
ScheduledTriggerRecord
Bases: pydantic.BaseModel
Wire-transmissible representation of a scheduled trigger.
Contains all the configuration and metadata for a scheduled trigger, including the target action, invocation schedule, input specification and execution settings.
This is the underlying data structure used by the ScheduledTrigger domain class to store and transmit trigger information.
Parameters
data AnyAttributes
ScheduledTriggerRecord.action
Reference to the action this trigger invokes.
ScheduledTriggerRecord.compute_requirement_overrides
compute_requirement_overrides roboto.Optional compute requirement overrides.
ScheduledTriggerRecord.container_parameter_overrides
container_parameter_overrides roboto.Optional container parameter overrides.
ScheduledTriggerRecord.invocation_input
Optional invocation input for action invocations.
ScheduledTriggerRecord.invocation_upload_destination
invocation_upload_destination roboto.Optional upload destination for action invocation outputs.
ScheduledTriggerRecord.modified
Last modification time for the scheduled trigger.
ScheduledTriggerRecord.next_occurrence
Next scheduled invocation time, or None if the trigger is disabled.
This is computed and updated by the Roboto system.
ScheduledTriggerRecord.parameter_values
Optional action parameter values.
SetActionAccessibilityRequest
Bases: pydantic.BaseModel
Request payload to set action accessibility.
Used to change whether an action is private to the organization or published publicly in the Action Hub.
Parameters
data AnyAttributes
SetActionAccessibilityRequest.accessibility
The new accessibility level (Organization or ActionHub).
SetActionAccessibilityRequest.digest
Specific version of Action. If not specified, the latest version’s accessibility will be updated.
SetActionAccessibilityRequest.model_config
model_config #Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
SetContainerInfoRequest
Bases: pydantic.BaseModel
Request to set container information for an invocation.
Used internally by the Roboto platform to record container details after the action image has been pulled and inspected.
Parameters
data AnyAttributes
SetContainerInfoRequest.image_digest
The digest of the container image that was pulled.
SetLogsLocationRequest
Bases: pydantic.BaseModel
Request to set the location where invocation logs are stored.
Used internally by the Roboto platform to record where log files are saved for later retrieval.
Parameters
data AnySourceProvenance
Bases: pydantic.BaseModel
Provenance information for an invocation source
Parameters
data AnyAttributes
SourceProvenance.source_id
SourceProvenance.source_type
Trigger
A rule that automatically invokes an action when specific events or conditions occur.
Triggers enable automated data processing workflows by monitoring for specific events (like new datasets being created) and automatically invoking actions when conditions are met. They eliminate the need for manual intervention in routine data processing tasks.
Triggers can be configured to:
- Monitor for new datasets, files, or other data sources
- Apply conditional logic to determine when to execute
- Specify input data patterns and action parameters
- Override compute requirements and container parameters
- Execute actions for each matching item or in batch
A trigger consists of:
- Target action to invoke
- Input data requirements and patterns
- Execution conditions and causes
- Parameter values and overrides
- Scheduling and execution settings
Parameters
roboto_client Optional[roboto.Properties
Trigger.condition
Trigger.create()
Create a new trigger that automatically invokes an action when conditions are met.
Creates a trigger that monitors for specific events (like new datasets or files) and automatically invokes the specified action when the trigger conditions are satisfied. This enables automated data processing workflows.
Parameters
name strUnique name for the trigger within the organization.
action_name strName of the action to invoke when the trigger fires.
required_inputs list[str]List of file patterns that must be present for the trigger to fire. Uses glob patterns like “**/*.bag” or “data/*.csv”.
Granularity of execution - Dataset creates one invocation per dataset, DatasetFile creates one invocation per matching file.
enabled boolWhether the trigger should be active immediately after creation.
action_digest Optional[str]Specific version digest of the action to invoke. If not provided, uses the latest version.
action_owner_id Optional[str]Organization ID that owns the target action. If not provided, searches in the caller’s organization.
additional_inputs Optional[list[str]]Optional additional file patterns to include in invocations.
causes Optional[list[roboto.List of events that can cause this trigger to be evaluated. If not provided, uses default causes.
compute_requirement_overrides Optional[roboto.Optional compute requirement overrides for action invocations.
condition Optional[roboto.Optional condition that must be met for the trigger to fire. Can filter based on metadata, file properties, etc.
container_parameter_overrides Optional[roboto.Optional container parameter overrides for action invocations.
parameter_values Optional[dict[str, Any]]Parameter values to pass to the action when invoked.
service_user_id Optional[str]Optional service user ID for authentication.
timeout Optional[int]Optional timeout override for action invocations in minutes.
caller_org_id Optional[str]Organization ID to create the trigger in. Defaults to caller’s org.
roboto_client Optional[roboto.Roboto client instance. Uses default if not provided.
Returns
The newly created Trigger instance.
Raises
If the trigger configuration is invalid.
If the request is malformed.
If the caller lacks permission to create triggers.
Usage
Create a simple trigger for ROS bag files:
from roboto.domain.actions import Trigger, TriggerForEachPrimitive
trigger = Trigger.create(
name="auto_process_bags",
action_name="ros_ingestion",
required_inputs=["**/*.bag"],
for_each=TriggerForEachPrimitive.Dataset,
)Create a conditional trigger with parameters:
from roboto.query import Condition
condition = Condition("metadata.sensor_type").equals("lidar")
trigger = Trigger.create(
name="lidar_processing",
action_name="lidar_processor",
required_inputs=["**/*.pcd"],
for_each=TriggerForEachPrimitive.Dataset,
condition=condition,
parameter_values={"resolution": "high", "filter": "statistical"},
)Create a trigger with compute overrides:
from roboto.domain.actions import ComputeRequirements
trigger = Trigger.create(
name="heavy_processing",
action_name="ml_inference",
required_inputs=["**/*.jpg", "**/*.png"],
for_each=TriggerForEachPrimitive.DatasetFile,
compute_requirement_overrides=ComputeRequirements(vCPU=8192, memory=16384),
)Trigger.delete()
Trigger.disable()
Trigger.enable()
Properties
Trigger.for_each
Trigger.from_name()
Parameters
Return type
Trigger.get_action()
Return type
Trigger.get_evaluations()
Parameters
limit Optional[int]page_token Optional[str]Return type
Trigger.get_evaluations_for_dataset()
Get all trigger evaluations for a specific dataset.
Retrieves the history of trigger evaluations that were performed for a given dataset, including successful invocations and failed attempts.
Parameters
dataset_id strThe ID of the dataset to get evaluations for.
owner_org_id Optional[str]Organization ID that owns the dataset. If not provided, searches in the caller’s organization.
roboto_client Optional[roboto.Roboto client instance. Uses default if not provided.
Yields
TriggerEvaluationRecord instances for the dataset.
Raises
If the dataset is not found.
If the caller lacks permission to access evaluations.
Return type
Usage
Get all evaluations for a dataset:
for evaluation in Trigger.get_evaluations_for_dataset("ds_12345"):
print(f"Trigger: {evaluation.trigger_name}, Status: {evaluation.status}")Check if any triggers succeeded for a dataset:
from roboto.domain.actions import TriggerEvaluationStatus
evaluations = list(Trigger.get_evaluations_for_dataset("ds_12345"))
successful = [e for e in evaluations if e.status == TriggerEvaluationStatus.Succeeded]
print(f"Found {len(successful)} successful trigger evaluations")Trigger.get_invocations()
Return type
Trigger.invoke()
Parameters
idempotency_id Optional[str]input_data_override Optional[list[str]]upload_destination Optional[roboto.Return type
Trigger.latest_evaluation()
Return type
Trigger.query()
Parameters
spec Optional[roboto.owner_org_id Optional[str]roboto_client Optional[roboto.Return type
Properties
Trigger.record
Trigger.to_dict()
Return type
Properties
Trigger.update()
Parameters
action_name Union[str, roboto.action_owner_id Union[str, roboto.action_digest Optional[Union[str, roboto.additional_inputs Optional[Union[list[str], roboto.causes Union[list[roboto.compute_requirement_overrides Optional[Union[roboto.container_parameter_overrides Optional[Union[roboto.condition Optional[Union[roboto.enabled Union[bool, roboto.parameter_values Optional[Union[dict[str, Any], roboto.required_inputs Union[list[str], roboto.timeout Optional[Union[int, roboto.Return type
Trigger.wait_for_evaluations_to_complete()
Wait for all evaluations for this trigger to complete.
Throws a TimeoutError if the timeout is reached.
Parameters
timeout floatThe maximum amount of time, in seconds, to wait for the evaluations to complete.
poll_interval roboto.The amount of time, in seconds, to wait between polling iterations.
Return type
TriggerEvaluationCause
Bases: enum.Enum
The cause of a TriggerEvaluationRecord is the reason why the trigger was selected for evaluation.
Represents the specific event that caused a trigger to be evaluated for potential execution. Different causes may result in different trigger behavior or input data selection.
Attributes
TriggerEvaluationCause.DatasetMetadataUpdate
Trigger evaluation caused by changes to dataset metadata.
TriggerEvaluationCause.FileIngest
Trigger evaluation caused by files being ingested into a dataset.
TriggerEvaluationCause.FileMetadataUpdate
Trigger evaluation caused by file metadata or tag updates.
TriggerEvaluationCause.FileUpload
Trigger evaluation caused by new files being uploaded to a dataset.
TriggerEvaluationCause.RecurringSchedule
Trigger evaluation caused by a recurring schedule.
This cause is used internally by the Roboto system, to track the evaluation history of scheduled triggers. It should not be used when creating or updating triggers, and doing so will result in an error.
To create a trigger that invokes an action on a recurring schedule, use ScheduledTrigger.
TriggerEvaluationDataConstraint
Bases: pydantic.BaseModel
An optional filtering constraint applied to the data considered by a trigger evaluation.
Each trigger evaluation considers data of a particular data source ID and data source type. Typically (and to start, exclusively), this is a dataset ID (and type Dataset).
In the naive case before the introduction of this class, trigger evaluation for a dataset with 20k files would have to scan each file. This constraint allows us to filter the data to a subset during evaluation, e.g. only evaluate files from dataset ds_12345 with upload ID tx_123abc
Parameters
data AnyTriggerEvaluationOutcome
Bases: enum.Enum
The outcome of a TriggerEvaluationRecord is the result of the evaluation. A trigger can either invoke its associated action (one or many times) or be skipped. If skipped, a skip reason is provided.
TriggerEvaluationOutcomeReason
Bases: enum.Enum
Context for why a trigger evaluation has its TriggerEvaluationOutcome
Attributes
TriggerEvaluationOutcomeReason.AlreadyRun
This trigger has already run its associated action for this dataset and/or file.
TriggerEvaluationOutcomeReason.ConditionNotMet
The trigger’s condition is not met.
TriggerEvaluationOutcomeReason.NoMatchingFiles
In the case of a dataset trigger, there is no subset of files that, combined, match ALL of the trigger’s required inputs.
In the case of a file trigger, there are no files that match ANY of the trigger’s required inputs.
TriggerEvaluationOutcomeReason.TriggerDisabled
The trigger is disabled.
TriggerEvaluationRecord
Bases: pydantic.BaseModel
Record of a point-in-time evaluation of whether to invoke an action associated with a trigger for a data source.
Parameters
data AnyAttributes
TriggerEvaluationRecord.cause
TriggerEvaluationRecord.data_constraint
TriggerEvaluationRecord.data_source
TriggerEvaluationRecord.evaluation_end
TriggerEvaluationRecord.evaluation_start
TriggerEvaluationRecord.outcome
TriggerEvaluationRecord.outcome_reason
TriggerEvaluationRecord.status
TriggerEvaluationRecord.status_detail
TriggerEvaluationRecord.trigger_evaluation_id
TriggerEvaluationRecord.trigger_id
TriggerEvaluationStatus
Bases: enum.Enum
When a trigger is selected for evaluation, a trigger evaluation record is created with a status of Pending. The evaluation can either run to completion (regardless of its outcome), in which case the status is Evaluated, or hit an unexpected exception, in which case the status is Failed.
TriggerEvaluationsSummaryResponse
Bases: pydantic.BaseModel
Response containing summary information about trigger evaluations.
Provides high-level statistics about trigger evaluation status, useful for monitoring and debugging trigger performance.
Parameters
data AnyAttributes
TriggerForEachPrimitive
Bases: roboto.compat.StrEnum
Defines the granularity at which a trigger executes.
Determines whether the trigger creates one invocation per dataset or one invocation per file within datasets that match the trigger conditions.
TriggerOnEvent
Bases: pydantic.BaseModel
Properties specific to event-driven triggers.
Parameters
data AnyAttributes
TriggerOnEvent.additional_inputs
Optional additional file patterns to include.
TriggerOnEvent.causes
One or more events that cause the trigger to be evaluated.
TriggerOnEvent.condition
Optional condition that must be met for trigger to fire.
TriggerOnEvent.for_each
Granularity of trigger execution.
TriggerOnEvent.required_inputs
File patterns that must be present for trigger to fire.
TriggerOnSchedule
Bases: pydantic.BaseModel
Properties specific to scheduled triggers.
Parameters
data AnyAttributes
TriggerOnSchedule.invocation_input
Input specification for each scheduled invocation.
TriggerOnSchedule.next_occurrence
Next scheduled invocation time.
TriggerRecord
Bases: pydantic.BaseModel
A wire-transmissible representation of a trigger.
Contains all the configuration and metadata for a trigger, including the target action, input requirements, conditions, and execution settings.
This is the underlying data structure used by the Trigger domain class to store and transmit trigger information.
Parameters
data AnyAttributes
TriggerRecord.action
Reference to the action that should be invoked.
TriggerRecord.additional_inputs
Optional additional file patterns to include.
TriggerRecord.causes
List of events that can cause this trigger to be evaluated.
TriggerRecord.compute_requirement_overrides
compute_requirement_overrides roboto.Optional compute requirement overrides.
TriggerRecord.condition
Optional condition that must be met for trigger to fire.
TriggerRecord.container_parameter_overrides
container_parameter_overrides roboto.Optional container parameter overrides.
TriggerRecord.for_each
Granularity of trigger execution (Dataset or DatasetFile).
TriggerRecord.parameter_values
Parameter values to pass to the action.
TriggerRecord.required_inputs
File patterns that must be present for trigger to fire.
TriggerRecord.validate_additional_inputs()
Parameters
value Optional[list[str]]Return type
TriggerRecord.validate_required_inputs()
Parameters
value list[str]Return type
TriggerSchedule
Utility for defining trigger schedules.
Parameters
cron_string strTriggerSchedule.cron()
Create a trigger schedule based on a Cron expression.
Parameters
cron_string strA Cron expression like */30 * * * *.
Returns
A TriggerSchedule instance.
Raises
ValueErrorIf the provided string is not a valid Cron expression.
Properties
TriggerSchedule.daily()
Every day at midnight UTC.
Return type
TriggerSchedule.hourly()
Every hour on the hour.
Return type
TriggerSchedule.monthly()
Every 1st of the month at midnight UTC.
Return type
TriggerSchedule.weekly()
Every Sunday at midnight UTC.
Return type
TriggerType
Bases: roboto.compat.StrEnum
Types of triggers supported by the Roboto platform.
Attributes
TriggerType.EventDriven
A trigger that invokes its target action in response to an event.
See TriggerEvaluationCause for the currently supported causes for event-driven triggers to be evaluated.
TriggerType.Scheduled
A trigger that invokes its target action on a recurring schedule.
TriggerView
Bases: pydantic.BaseModel
Unified data model for all Roboto trigger types.
Parameters
data AnyAttributes
TriggerView.action
Reference to the trigger’s target action.
TriggerView.compute_requirement_overrides
compute_requirement_overrides roboto.Optional compute requirement overrides.
TriggerView.container_parameter_overrides
container_parameter_overrides roboto.Optional container parameter overrides.
TriggerView.invocation_upload_destination
invocation_upload_destination roboto.Optional default upload destination for action invocations.
TriggerView.on_event
Properties of triggers that fire on events (TriggerType.EventDriven).
TriggerView.on_schedule
Properties of triggers that fire on a recurring schedule (TriggerType.Scheduled).
TriggerView.parameter_values
Optional action parameter values.
TriggerView.to_event_trigger_record()
Convert this trigger view into a TriggerRecord if possible.
Returns
A TriggerRecord instance if self.trigger_type is TriggerType.EventDriven, otherwise None.
TriggerView.to_scheduled_trigger_record()
Convert this trigger view into a ScheduledTriggerRecord if possible.
Returns
A ScheduledTriggerRecord instance if self.trigger_type is TriggerType.Scheduled, otherwise None.
Attributes
UpdateActionRequest
Bases: pydantic.BaseModel
Request payload to update an action.
Contains the changes to apply to an existing action. Only specified fields will be updated; others remain unchanged. Uses NotSet sentinel values to distinguish between explicit None values and unspecified fields.
Parameters
data AnyAttributes
UpdateActionRequest.compute_requirements
compute_requirements roboto.New compute requirements (CPU, memory).
UpdateActionRequest.container_parameters
container_parameters roboto.New container parameters (image, entrypoint, etc.).
UpdateActionRequest.description
New detailed description.
UpdateActionRequest.inherits
New action reference to inherit from.
UpdateActionRequest.metadata_changeset
Changes to apply to metadata (add, remove, update keys).
UpdateActionRequest.model_config
model_config #Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
UpdateActionRequest.parameter_changeset
parameter_changeset roboto.Changes to apply to parameters (add, remove, update).
UpdateActionRequest.requires_downloaded_inputs
Whether to download input files before execution.
UpdateActionRequest.short_description
New brief description (max 140 characters).
UpdateActionRequest.timeout
New maximum execution time in minutes.
UpdateActionRequest.validate_uri()
UpdateInvocationStatus
Bases: pydantic.BaseModel
Request payload to update an invocation’s status.
Used to record status changes during invocation execution, such as transitioning from Queued to Running to Completed.
Parameters
data AnyAttributes
UpdateInvocationStatus.status
The new status for the invocation.
UpdateScheduledTriggerRequest
Bases: pydantic.BaseModel
Request payload to update a scheduled trigger.
See update() for details on the request attributes.
Parameters
data AnyAttributes
UpdateScheduledTriggerRequest.action_name
UpdateScheduledTriggerRequest.action_owner_id
UpdateScheduledTriggerRequest.compute_requirement_overrides
compute_requirement_overrides roboto.UpdateScheduledTriggerRequest.container_parameter_overrides
container_parameter_overrides roboto.UpdateScheduledTriggerRequest.enabled
UpdateScheduledTriggerRequest.invocation_input
invocation_input roboto.UpdateScheduledTriggerRequest.invocation_upload_destination
invocation_upload_destination roboto.UpdateScheduledTriggerRequest.model_config
model_config #Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
UpdateScheduledTriggerRequest.parameter_values
UpdateScheduledTriggerRequest.schedule
UpdateScheduledTriggerRequest.timeout
UpdateTriggerRequest
Bases: pydantic.BaseModel
Request payload to update an existing trigger.
Contains the changes to apply to a trigger. Only specified fields will be updated; others remain unchanged. Uses NotSet sentinel values to distinguish between explicit None values and unspecified fields.
Parameters
data AnyAttributes
UpdateTriggerRequest.action_digest
New specific version digest of the action.
UpdateTriggerRequest.action_name
New action name to invoke.
UpdateTriggerRequest.action_owner_id
New organization ID that owns the target action.
UpdateTriggerRequest.additional_inputs
New additional file patterns to include.
UpdateTriggerRequest.causes
causes list[roboto.New list of events that can cause trigger evaluation.
UpdateTriggerRequest.compute_requirement_overrides
compute_requirement_overrides roboto.New compute requirement overrides.
UpdateTriggerRequest.condition
New condition that must be met for trigger to fire.
UpdateTriggerRequest.container_parameter_overrides
container_parameter_overrides roboto.New container parameter overrides.
UpdateTriggerRequest.enabled
New enabled status for the trigger.
UpdateTriggerRequest.for_each
for_each roboto.New execution granularity (Dataset or DatasetFile).
UpdateTriggerRequest.model_config
model_config #Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
UpdateTriggerRequest.parameter_values
New parameter values to pass to the action.
UpdateTriggerRequest.required_inputs
New list of required file patterns.
UpdateTriggerRequest.timeout
New timeout override for action invocations.
UploadDestinationType
Bases: enum.Enum
Type of upload destination for invocation outputs.
Defines where files generated by action invocations should be uploaded. Currently supports datasets as the primary destination type.
Attributes
UploadDestinationType.Dataset
Outputs will be uploaded to a dataset. This is the default.
UploadDestinationType.Unknown
The output destination is unknown.
This destination type exists for compatibility between different versions of the Roboto SDK and the Roboto service backend. It should not be used directly in action invocation requests. If you encounter it in an SDK response, consider upgrading to the latest available SDK version.