Python SDK

Installation

pip install iii-sdk

Initialization

register_worker

Create an III client and connect to the engine. Blocks until the WebSocket connection is established and ready. Signature

register_worker(address: str, options: InitOptions | None = None)

Parameters

Name	Type	Required	Description
`address`	`str`	Yes	-
`options`	`InitOptions` \| None	No	-

Example

from iii import register_worker, InitOptions
worker = register_worker('ws://localhost:49134', InitOptions(worker_name='my-worker'))

Methods

register_trigger

Signature

register_trigger(trigger: RegisterTriggerInput | dict[str, Any])

Parameters

Name	Type	Required	Description
`trigger`	`RegisterTriggerInput` \| dict[str, Any]	Yes	-

register_function

Signature

register_function(function_id: str, handler_or_invocation: RemoteFunctionHandler | HttpInvocationConfig)

Parameters

Name	Type	Required	Description
`function_id`	`str`	Yes	-
`handler_or_invocation`	`RemoteFunctionHandler \| HttpInvocationConfig`	Yes	-

trigger

Signature

trigger(request: dict[str, Any] | TriggerRequest)

Parameters

Name	Type	Required	Description
`request`	dict[str, Any] \| `TriggerRequest`	Yes	-

register_trigger_type

Signature

register_trigger_type(trigger_type: RegisterTriggerTypeInput | dict[str, Any], handler: TriggerHandler[Any])

Parameters

Name	Type	Required	Description
`trigger_type`	`RegisterTriggerTypeInput` \| dict[str, Any]	Yes	-
`handler`	`TriggerHandler`[Any]	Yes	-

unregister_trigger_type

Signature

unregister_trigger_type(trigger_type: RegisterTriggerTypeInput | dict[str, Any])

Parameters

Name	Type	Required	Description
`trigger_type`	`RegisterTriggerTypeInput` \| dict[str, Any]	Yes	-

shutdown

Signature

shutdown()

Types

iii

EnqueueResult · InitOptions · MiddlewareFunctionInput · StreamRequest · StreamResponse · TelemetryOptions · TriggerAction · TriggerActionEnqueue

EnqueueResult

Result returned when a function is invoked with TriggerAction.Enqueue.

Name	Type	Required	Description
`messageReceiptId`	`str`	No	UUID assigned by the engine to the enqueued job.

InitOptions

Options for configuring the III SDK.

Name	Type	Required	Description
`enable_metrics_reporting`	`bool`	No	Enable worker metrics via OpenTelemetry. Default `True`.
`headers`	`dict[str, str] \| None`	No	-
`invocation_timeout_ms`	`int`	No	Default timeout for `trigger()` in milliseconds. Default `30000`.
`otel`	`OtelConfig \| dict[str, Any] \| None`	No	OpenTelemetry configuration. Enabled by default. Set `\{'enabled': False\}` or env `OTEL_ENABLED=false` to disable.
`reconnection_config`	`ReconnectionConfig \| None`	No	WebSocket reconnection behavior.
`telemetry`	`TelemetryOptions` \| None	No	Internal worker metadata reported to the engine.
`worker_description`	`str \| None`	No	One-line, human/LLM-readable summary of what this worker does. Surfaces in `engine::workers::list` / `engine::workers::info`.
`worker_name`	`str \| None`	No	Display name for this worker. Defaults to `hostname:pid`.

MiddlewareFunctionInput

Input passed to the RBAC middleware function on every function invocation through the RBAC port.

Name	Type	Required	Description
`action`	`TriggerActionEnqueue` \| `TriggerActionVoid` \| None	No	Routing action, if any.
`context`	`dict[str, Any]`	No	Auth context returned by the auth function for this session.
`function_id`	`str`	No	ID of the function being invoked.
`payload`	`dict[str, Any]`	No	Payload sent by the caller.

StreamRequest

Streaming request without the response writer.

Name	Type	Required	Description
`body`	`Any`	Yes	-
`headers`	`dict[str, str \| list[str]]`	Yes	-
`method`	`str`	Yes	-
`path_params`	`dict[str, str]`	Yes	-
`query_params`	`dict[str, str \| list[str]]`	Yes	-
`request_body`	`ChannelReader`	Yes	-

StreamResponse

Streaming response built on top of a ChannelWriter.

Name	Type	Required	Description
`stream`	`WritableStream`	Yes	-
`writer`	`ChannelWriter`	Yes	-

TelemetryOptions

Worker metadata reported to the engine.

Name	Type	Required	Description
`amplitude_api_key`	`str \| None`	No	Amplitude API key for product analytics.
`framework`	`str \| None`	No	Framework name (e.g. `motia`) if applicable.
`language`	`str \| None`	No	Programming language of the worker (e.g. `python`).
`project_name`	`str \| None`	No	Name of the project this worker belongs to.

TriggerAction

Factory for creating trigger actions used with trigger().

TriggerActionEnqueue

Routes the invocation through a named queue for async processing.

Name	Type	Required	Description
`queue`	`str`	Yes	Name of the target queue.
`type`	`Literal['enqueue']`	No	Always `'enqueue'`.

iii.channel

Channel · ChannelReader · ChannelWriter · StreamChannelRef

Channel

A streaming channel pair for worker-to-worker data transfer.

Name	Type	Required	Description
`reader`	`ChannelReader`	Yes	-
`reader_ref`	`StreamChannelRef`	Yes	-
`writer`	`ChannelWriter`	Yes	-
`writer_ref`	`StreamChannelRef`	Yes	-

ChannelReader

WebSocket-backed reader for streaming binary data and text messages.

Name	Type	Required	Description
`stream`	`Any`	No	-

ChannelWriter

WebSocket-backed writer for streaming binary data and text messages.

Name	Type	Required	Description
`stream`	`Any`	No	-

StreamChannelRef

Reference to a streaming channel for worker-to-worker data transfer.

Name	Type	Required	Description
`access_key`	`str`	No	Secret key for authenticating channel access.
`channel_id`	`str`	No	Unique channel identifier.
`direction`	`Literal['read', 'write']`	No	Channel direction (`read` or `write`).

iii.engine

EngineFunctions · EngineTriggers

EngineFunctions

Engine function ids for internal operations (parity with the Node SDK).

Name	Type	Required	Description
`INFO_FUNCTIONS`	`Final[str]`	No	-
`INFO_REGISTERED_TRIGGERS`	`Final[str]`	No	-
`INFO_TRIGGERS`	`Final[str]`	No	-
`INFO_WORKERS`	`Final[str]`	No	-
`LIST_FUNCTIONS`	`Final[str]`	No	-
`LIST_REGISTERED_TRIGGERS`	`Final[str]`	No	-
`LIST_TRIGGERS`	`Final[str]`	No	-
`LIST_WORKERS`	`Final[str]`	No	-
`REGISTER_WORKER`	`Final[str]`	No	-

EngineTriggers

Engine trigger ids (parity with the Node SDK).

Name	Type	Required	Description
`FUNCTIONS_AVAILABLE`	`Final[str]`	No	-
`LOG`	`Final[str]`	No	-

iii.errors

InvocationError

InvocationError

Raised when an invocation dispatched by the SDK fails. Inspect err.code to react to a specific category (e.g. 'FORBIDDEN' for RBAC denials, 'TIMEOUT' for timeouts). Catch this class to handle every rejection. except Exception continues to work because InvocationError inherits from Exception. Attributes are read-only after construction. stacktrace is the engine-side trace when the remote handler raised; it may include internal file paths and should not be surfaced to end users. str(err) intentionally never includes the stacktrace.

Name	Type	Required	Description
`code`	`Any`	No	-
`function_id`	`Any`	No	-
`invocation_id`	`Any`	No	-
`message`	`Any`	No	-
`stacktrace`	`Any`	No	-

iii.internal

InternalHttpRequest

InternalHttpRequest

HTTP request with embedded channel references for streaming.

Name	Type	Required	Description
`body`	`Any`	Yes	-
`headers`	`dict[str, str \| list[str]]`	Yes	-
`method`	`str`	Yes	-
`path_params`	`dict[str, str]`	Yes	-
`query_params`	`dict[str, str \| list[str]]`	Yes	-
`request_body`	`ChannelReader`	Yes	-
`response`	`ChannelWriter`	Yes	-

iii.protocol

MessageType · RegisterFunctionFormat · RegisterFunctionInput · RegisterFunctionMessage · RegisterTriggerInput · RegisterTriggerMessage · RegisterTriggerTypeInput · RegisterTriggerTypeMessage · TriggerRequest

MessageType

Message types for iii communication.

Name	Type	Required	Description
`INVOCATION_RESULT`	`Any`	No	-
`INVOKE_FUNCTION`	`Any`	No	-
`REGISTER_FUNCTION`	`Any`	No	-
`REGISTER_SERVICE`	`Any`	No	-
`REGISTER_TRIGGER`	`Any`	No	-
`REGISTER_TRIGGER_TYPE`	`Any`	No	-
`TRIGGER_REGISTRATION_RESULT`	`Any`	No	-
`UNREGISTER_FUNCTION`	`Any`	No	-
`UNREGISTER_TRIGGER`	`Any`	No	-
`UNREGISTER_TRIGGER_TYPE`	`Any`	No	-
`WORKER_REGISTERED`	`Any`	No	-

RegisterFunctionFormat

Format definition for function parameters.

Name	Type	Required	Description
`body`	list[`RegisterFunctionFormat`] \| None	No	Nested fields for object types.
`description`	`str \| None`	No	Human-readable description of the parameter.
`items`	`RegisterFunctionFormat` \| None	No	Item schema for array types.
`name`	`str`	Yes	Parameter name.
`required`	`bool`	No	Whether the parameter is required.
`type`	`str`	Yes	Type string (`string`, `number`, `boolean`, `object`, `array`, `null`, `map`).

RegisterFunctionInput

Input for registering a function, matches Node.js RegisterFunctionInput.

Name	Type	Required	Description
`description`	`str \| None`	No	Human-readable description.
`id`	`str`	No	Unique function identifier.
`invocation`	`HttpInvocationConfig \| None`	No	HTTP invocation config for externally hosted functions.
`metadata`	`dict[str, Any] \| None`	No	Arbitrary metadata attached to the function.
`request_format`	`RegisterFunctionFormat` \| dict[str, Any] \| None	No	Schema describing expected input.
`response_format`	`RegisterFunctionFormat` \| dict[str, Any] \| None	No	Schema describing expected output.

RegisterFunctionMessage

Name	Type	Required	Description
`description`	`str \| None`	No	-
`id`	`str`	No	-
`invocation`	`HttpInvocationConfig \| None`	No	-
`message_type`	`MessageType`	No	-
`metadata`	`dict[str, Any] \| None`	No	-
`model_config`	`Any`	No	-
`request_format`	`RegisterFunctionFormat` \| dict[str, Any] \| None	No	-
`response_format`	`RegisterFunctionFormat` \| dict[str, Any] \| None	No	-

RegisterTriggerInput

Input for registering a trigger (matches Node SDK’s RegisterTriggerInput).

Name	Type	Required	Description
`config`	`Any`	No	Trigger-type-specific configuration.
`function_id`	`str`	No	ID of the function this trigger invokes.
`metadata`	`dict[str, Any] \| None`	No	Arbitrary metadata attached to the trigger.
`type`	`str`	No	Trigger type identifier (e.g. `http`, `queue`, `cron`).

RegisterTriggerMessage

Name	Type	Required	Description
`config`	`Any`	Yes	-
`function_id`	`str`	No	-
`id`	`str`	Yes	-
`message_type`	`MessageType`	No	-
`metadata`	`dict[str, Any] \| None`	No	-
`model_config`	`Any`	No	-
`trigger_type`	`str`	No	-

RegisterTriggerTypeInput

Input for registering a trigger type.

Name	Type	Required	Description
`call_request_format`	`Any \| None`	No	JSON Schema describing the payload sent to functions.
`description`	`str`	No	Human-readable description of the trigger type.
`id`	`str`	No	Unique identifier for the trigger type.
`trigger_request_format`	`Any \| None`	No	JSON Schema describing the expected trigger config.

RegisterTriggerTypeMessage

Name	Type	Required	Description
`call_request_format`	`Any \| None`	No	-
`description`	`str`	Yes	-
`id`	`str`	Yes	-
`message_type`	`MessageType`	No	-
`model_config`	`Any`	No	-
`trigger_request_format`	`Any \| None`	No	-

TriggerRequest

Request object for trigger().

Name	Type	Required	Description
`action`	`TriggerActionEnqueue` \| `TriggerActionVoid` \| None	No	Routing action, `None` for sync, `TriggerAction.Enqueue(...)` for queue, `TriggerAction.Void()` for fire-and-forget.
`function_id`	`str`	No	ID of the function to invoke.
`payload`	`Any`	No	Data to pass to the function.
`timeout_ms`	`int \| None`	No	Override the default invocation timeout.

iii.runtime

FunctionRef · TriggerTypeRef

FunctionRef

Reference to a registered function, allowing programmatic unregistration.

Name	Type	Required	Description
`id`	`str`	Yes	-
`unregister`	`Callable[None]`	Yes	-

TriggerTypeRef

Typed handle returned by :meth:iii.III.register_trigger_type. Type parameters:

C: configuration type for :meth:register_trigger
R: call-request type for :meth:register_function

iii.state

IState · StateDeleteInput · StateDeleteResult · StateEventData · StateEventType · StateGetInput · StateListInput · StateSetInput · StateSetResult · StateUpdateInput · StateUpdateResult

IState

Abstract interface for state management operations.

StateDeleteInput

Input for deleting a state value.

Name	Type	Required	Description
`key`	`str`	Yes	-
`scope`	`str`	Yes	-

StateDeleteResult

Result of a state delete operation.

Name	Type	Required	Description
`old_value`	`Any \| None`	No	-

StateEventData

Payload for state change events.

Name	Type	Required	Description
`event_type`	`StateEventType`	Yes	-
`key`	`str`	Yes	-
`new_value`	`TData \| None`	No	-
`old_value`	`TData \| None`	No	-
`scope`	`str`	Yes	-
`type`	`str`	No	-

StateEventType

Types of state change events.

Name	Type	Required	Description
`CREATED`	`Any`	No	-
`DELETED`	`Any`	No	-
`UPDATED`	`Any`	No	-

StateGetInput

Input for retrieving a state value.

Name	Type	Required	Description
`key`	`str`	Yes	-
`scope`	`str`	Yes	-

StateListInput

Input for listing all values in a state scope.

Name	Type	Required	Description
`scope`	`str`	Yes	-

StateSetInput

Input for setting a state value.

Name	Type	Required	Description
`key`	`str`	Yes	-
`scope`	`str`	Yes	-
`value`	`Any`	Yes	-

StateSetResult

Result of a state set operation.

Name	Type	Required	Description
`new_value`	`TData`	Yes	-
`old_value`	`TData \| None`	No	-

StateUpdateInput

Input for atomically updating a state value.

Name	Type	Required	Description
`key`	`str`	Yes	-
`ops`	`list[UpdateOp]`	Yes	-
`scope`	`str`	Yes	-

StateUpdateResult

Result of a state update operation.

Name	Type	Required	Description
`new_value`	`TData`	Yes	-
`old_value`	`TData \| None`	No	-

iii.stream

IStream · StreamDeleteInput · StreamDeleteResult · StreamGetInput · StreamListGroupsInput · StreamListInput · StreamSetInput · StreamSetResult · StreamUpdateInput · StreamUpdateResult

IStream

Abstract interface for stream operations.

StreamDeleteInput

Input for stream delete operation.

Name	Type	Required	Description
`group_id`	`str`	Yes	-
`item_id`	`str`	Yes	-
`stream_name`	`str`	Yes	-

StreamDeleteResult

Result of stream delete operation.

Name	Type	Required	Description
`old_value`	`Any \| None`	No	-

StreamGetInput

Input for stream get operation.

Name	Type	Required	Description
`group_id`	`str`	Yes	-
`item_id`	`str`	Yes	-
`stream_name`	`str`	Yes	-

StreamListGroupsInput

Input for stream list groups operation.

Name	Type	Required	Description
`stream_name`	`str`	Yes	-

StreamListInput

Input for stream list operation.

Name	Type	Required	Description
`group_id`	`str`	Yes	-
`stream_name`	`str`	Yes	-

StreamSetInput

Input for stream set operation.

Name	Type	Required	Description
`data`	`Any`	Yes	-
`group_id`	`str`	Yes	-
`item_id`	`str`	Yes	-
`stream_name`	`str`	Yes	-

StreamSetResult

Result of stream set operation.

Name	Type	Required	Description
`new_value`	`TData`	Yes	-
`old_value`	`TData \| None`	No	-

StreamUpdateInput

Input for stream update operation.

Name	Type	Required	Description
`group_id`	`str`	Yes	-
`item_id`	`str`	Yes	-
`ops`	`list['UpdateOp']`	Yes	-
`stream_name`	`str`	Yes	-

StreamUpdateResult

Result of stream update operation.

Name	Type	Required	Description
`errors`	`list[UpdateOpError]`	No	-
`new_value`	`TData`	Yes	-
`old_value`	`TData \| None`	No	-

iii.trigger

Trigger · TriggerActionVoid · TriggerConfig · TriggerHandler

Trigger

Represents a registered trigger.

TriggerActionVoid

Fire-and-forget routing. No response is returned.

Name	Type	Required	Description
`type`	`Literal['void']`	No	Always `'void'`.

TriggerConfig

Configuration for a trigger.

Name	Type	Required	Description
`config`	`Any`	Yes	-
`function_id`	`str`	Yes	-
`id`	`str`	Yes	-
`metadata`	`dict[str, Any] \| None`	No	-
`model_config`	`Any`	No	-

TriggerHandler

Abstract base class for trigger handlers.

​Installation

​Initialization

​register_worker

​Parameters

​Example

​Methods

​register_trigger

​Parameters

​register_function

​Parameters

​trigger

​Parameters

​register_trigger_type

​Parameters

​unregister_trigger_type

​Parameters

​shutdown

​Types

​iii

​EnqueueResult

​InitOptions

​MiddlewareFunctionInput

​StreamRequest

​StreamResponse

​TelemetryOptions

​TriggerAction

​TriggerActionEnqueue

​iii.channel

​Channel

​ChannelReader

​ChannelWriter

​StreamChannelRef

​iii.engine

​EngineFunctions

​EngineTriggers

​iii.errors

​InvocationError

​iii.internal

​InternalHttpRequest

​iii.protocol

​MessageType

​RegisterFunctionFormat

​RegisterFunctionInput

​RegisterFunctionMessage

​RegisterTriggerInput

​RegisterTriggerMessage

​RegisterTriggerTypeInput

​RegisterTriggerTypeMessage

​TriggerRequest

​iii.runtime

​FunctionRef

​TriggerTypeRef

​iii.state

​IState

​StateDeleteInput

​StateDeleteResult

​StateEventData

​StateEventType

​StateGetInput

​StateListInput

​StateSetInput

​StateSetResult

​StateUpdateInput

​StateUpdateResult

​iii.stream

​IStream

​StreamDeleteInput

​StreamDeleteResult

​StreamGetInput

​StreamListGroupsInput

​StreamListInput

​StreamSetInput

​StreamSetResult

​StreamUpdateInput

​StreamUpdateResult

​iii.trigger

​Trigger

​TriggerActionVoid

​TriggerConfig

​TriggerHandler

Installation

Initialization

register_worker

Parameters

Example

Methods

register_trigger

Parameters

register_function

Parameters

trigger

Parameters

register_trigger_type

Parameters

unregister_trigger_type

Parameters

shutdown

Types

iii

EnqueueResult

InitOptions

MiddlewareFunctionInput

StreamRequest

StreamResponse

TelemetryOptions

TriggerAction

TriggerActionEnqueue

iii.channel

Channel

ChannelReader

ChannelWriter

StreamChannelRef

iii.engine

EngineFunctions

EngineTriggers

iii.errors

InvocationError

iii.internal

InternalHttpRequest

iii.protocol

MessageType

RegisterFunctionFormat

RegisterFunctionInput

RegisterFunctionMessage

RegisterTriggerInput

RegisterTriggerMessage

RegisterTriggerTypeInput

RegisterTriggerTypeMessage

TriggerRequest

iii.runtime

FunctionRef

TriggerTypeRef

iii.state

IState

StateDeleteInput

StateDeleteResult

StateEventData

StateEventType

StateGetInput

StateListInput

StateSetInput

StateSetResult

StateUpdateInput

StateUpdateResult

iii.stream

IStream

StreamDeleteInput

StreamDeleteResult

StreamGetInput

StreamListGroupsInput

StreamListInput

StreamSetInput

StreamSetResult

StreamUpdateInput

StreamUpdateResult

iii.trigger

Trigger

TriggerActionVoid

TriggerConfig

TriggerHandler