roboto.domain.actions.invocation

Module Contents

Invocation

class roboto.domain.actions.invocation.Invocation(record, roboto_client=None)#

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

record roboto.domain.actions.invocation_record.InvocationRecord

roboto_client Optional[roboto.http.RobotoClient]

Properties

Invocation.action

action roboto.domain.actions.invocation_record.ActionProvenance #

Provenance information about the action that was invoked.

Return type: roboto.domain.actions.invocation_record.ActionProvenance

Invocation.cancel()

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

RobotoNotFoundException

If the invocation is not found.

RobotoUnauthorizedException

If the caller lacks permission to cancel the invocation.

Return type

None

Usage

Cancel a running invocation:

invocation = Invocation.from_id("iv_12345")
if not invocation.reached_terminal_status:
    invocation.cancel()

Properties

Invocation.compute_requirements

compute_requirements roboto.domain.actions.action_record.ComputeRequirements #

The compute requirements (CPU, memory) used for this invocation.

Return type: roboto.domain.actions.action_record.ComputeRequirements

Invocation.container_parameters

container_parameters roboto.domain.actions.action_record.ContainerParameters #

The container parameters used for this invocation.

Return type: roboto.domain.actions.action_record.ContainerParameters

Invocation.created

created datetime.datetime #

The timestamp when this invocation was created.

Return type: datetime.datetime

Invocation.current_status

current_status roboto.domain.actions.invocation_record.InvocationStatus #

The current status of this invocation (e.g., Queued, Running, Completed).

Return type: roboto.domain.actions.invocation_record.InvocationStatus

Invocation.data_source

data_source roboto.domain.actions.invocation_record.InvocationDataSource #

The data source that provided input data for this invocation.

Return type: roboto.domain.actions.invocation_record.InvocationDataSource

Invocation.executable

executable roboto.domain.actions.invocation_record.ExecutableProvenance #

Provenance information about the executable (container) that was run.

Return type: roboto.domain.actions.invocation_record.ExecutableProvenance

Invocation.from_id()

classmethod from_id(invocation_id, roboto_client=None)#

Load an existing invocation by its ID.

Retrieves an invocation from the Roboto platform using its unique identifier.

Parameters

invocation_id str

The unique ID of the invocation to retrieve.

roboto_client Optional[roboto.http.RobotoClient]

Roboto client instance. Uses default if not provided.

Returns

Invocation

The Invocation instance.

Raises

RobotoNotFoundException

If the invocation is not found.

RobotoUnauthorizedException

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()

get_logs(page_token=None)#

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

RobotoNotFoundException

If the invocation is not found.

RobotoUnauthorizedException

If the caller lacks permission to access logs.

Return type

collections.abc.Generator[roboto.domain.actions.invocation_record.LogRecord, None, None]

Properties

Invocation.id

id str #

The unique identifier for this invocation.

Return type: str

Invocation.input_data

input_data roboto.domain.actions.invocation_record.InvocationInput | None #

The input data specification for this invocation, if any.

Return type: Optional[roboto.domain.actions.invocation_record.InvocationInput]

Invocation.is_queued_for_scheduling()

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

bool

Properties

Invocation.org_id

org_id str #

The organization ID that owns this invocation.

Return type: str

Invocation.parameter_values

parameter_values dict[str, Any] #

The parameter values that were provided when this invocation was created.

Return type: dict[str, Any]

Invocation.query()

classmethod query(spec=None, owner_org_id=None, roboto_client=None)#

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.QuerySpecification]

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.http.RobotoClient]

Roboto client instance. Uses default if not provided.

Yields

Invocation instances matching the query criteria.

Raises

ValueError

If the query specification contains unknown fields.

RobotoIllegalArgumentException

If the query filters or sorts on a field the invocations API does not accept.

RobotoUnauthorizedException

If the caller lacks permission to query invocations.

Return type

collections.abc.Generator[Invocation, None, None]

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))