> ## Documentation Index
> Fetch the complete documentation index at: https://iii.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK

> API reference for the iii SDK for Python.

{/* AI: any skill-check (vale/AI) text fixes belong in the source doc-comments under sdk/packages/python/iii/src (prose) or docs/next/scripts/ (structure/formatting), then regenerate. Never edit this file directly. */}

## Installation

```bash theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
pip install iii-sdk
```

## Initialization

### register\_worker

Register the worker with a iii instance, returns a connected worker client.

Blocks until the WebSocket connection is established and ready.

**Signature**

```python theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
register_worker(address: str, options: InitOptions | None = None) -> III
```

<Tabs>
  <Tab title="Parameters">
    <ParamField body="address" type="str" required>
      WebSocket URL of the III engine (e.g. `ws://localhost:49134`).
    </ParamField>

    <ParamField body="options" type="InitOptions | None">
      Optional configuration for worker name, timeouts, reconnection, and OTel.

      <Expandable title="`InitOptions` fields">
        <ParamField body="enable_metrics_reporting" type="bool">
          Enable worker metrics via OpenTelemetry. Default `True`.
        </ParamField>

        <ParamField body="headers" type="dict[str, str] | None" />

        <ParamField body="invocation_timeout_ms" type="int">
          Default timeout for `worker.trigger()` invocations in milliseconds. Default `30000`.
        </ParamField>

        <ParamField body="otel" type="OtelConfig | dict[str, Any] | None">
          OpenTelemetry configuration. Enabled by default. Set `\{'enabled': False\}` or env `OTEL_ENABLED=false` to disable.
        </ParamField>

        <ParamField body="reconnection_config" type="ReconnectionConfig | None">
          WebSocket reconnection behavior.
        </ParamField>

        <ParamField body="telemetry" type="TelemetryOptions | None">
          Internal worker metadata reported to the engine.
        </ParamField>

        <ParamField body="worker_description" type="str | None">
          One-line, human/LLM-readable summary of what this worker does. Surfaces in `engine::workers::list` / `engine::workers::info`.
        </ParamField>

        <ParamField body="worker_name" type="str | None">
          Display name for this worker. Defaults to `hostname:pid`.
        </ParamField>
      </Expandable>
    </ParamField>
  </Tab>

  <Tab title="Example">
    ```python theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
    from iii import register_worker, InitOptions
    worker = register_worker('ws://localhost:49134', InitOptions(worker_name='my-worker'))
    ```
  </Tab>
</Tabs>

## Methods

### register\_trigger

Bind a trigger configuration to a registered function.

**Signature**

```python theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
register_trigger(trigger: RegisterTriggerInput | dict[str, Any]) -> Trigger
```

<Tabs>
  <Tab title="Parameters">
    <ParamField body="trigger" type="RegisterTriggerInput | dict[str, Any]" required>
      A `RegisterTriggerInput` or dict with `type`, `function_id`, and optional `config`.

      <Expandable title="`RegisterTriggerInput` fields" defaultOpen>
        <ParamField body="config" type="Any">
          Trigger-type-specific configuration, matching the shape the trigger type expects.
        </ParamField>

        <ParamField body="function_id" type="str" required>
          ID of the function this trigger invokes when it fires.
        </ParamField>

        <ParamField body="metadata" type="Any | None">
          Arbitrary user-specifiable metadata supplied to the triggered handler function on every invocation.
        </ParamField>

        <ParamField body="type" type="str" required>
          Identifier of the registered trigger type this trigger uses (e.g. `storage::object-created`, `http`).
        </ParamField>
      </Expandable>
    </ParamField>
  </Tab>

  <Tab title="Example">
    ```python theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
    trigger = worker.register_trigger({
      'type': 'http',
      'function_id': 'greet',
      'config': {'api_path': '/greet', 'http_method': 'GET'}
    })
    trigger = worker.register_trigger(RegisterTriggerInput(
        type="http", function_id="greet",
        config={'api_path': '/greet', 'http_method': 'GET'}
    ))
    trigger.unregister()
    ```
  </Tab>
</Tabs>

***

### register\_function

Register a function with the engine.

Pass a handler for local execution, or an `HttpInvocationConfig`
for HTTP-invoked functions (Lambda, Cloudflare Workers, etc.).

Handlers can be synchronous or asynchronous.  Sync handlers are
automatically wrapped with `run_in_executor` so they do not
block the event loop.  Each handler receives a `data` argument
containing the trigger payload, and may optionally accept a second
`metadata` argument carrying per-invocation metadata (e.g.
`def handler(data, metadata=None)` or `def handler(data, *,
metadata=None)`).  Metadata is only forwarded to handlers that
declare a parameter literally named `metadata`, so existing
handlers, including ones with unrelated extra parameters,
`*args`, or `**kwargs`, keep working unchanged.

`request_format` and `response_format` are auto-extracted
from the handler's type hints when omitted or passed as `None`
(the default).  To opt out of auto-extraction, pass an explicit
schema (`RegisterFunctionFormat` or `dict`).  This behavior
is Python-specific; the Node SDK relies on explicit schemas because
TypeScript types are erased at runtime.

**Signature**

```python theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
register_function(function_id: str, handler_or_invocation: RemoteFunctionHandler | HttpInvocationConfig, *, description: str | None = None, metadata: dict[str, Any] | None = None, request_format: RegisterFunctionFormat | dict[str, Any] | None = None, response_format: RegisterFunctionFormat | dict[str, Any] | None = None) -> FunctionRef
```

<Tabs>
  <Tab title="Parameters">
    <ParamField body="function_id" type="str" required>
      Unique string identifier for the function.
    </ParamField>

    <ParamField body="handler_or_invocation" type="RemoteFunctionHandler | HttpInvocationConfig" required>
      A callable handler or `HttpInvocationConfig`.  Callable handlers receive `data` (the trigger payload) as the first argument and may optionally accept `metadata` (per-invocation metadata) as a second argument; they may return a value.
    </ParamField>

    <ParamField body="description" type="str | None">
      Human-readable description of what the function does.
    </ParamField>

    <ParamField body="metadata" type="dict[str, Any] | None">
      Arbitrary metadata attached to the function.
    </ParamField>

    <ParamField body="request_format" type="RegisterFunctionFormat | dict[str, Any] | None">
      Schema describing expected input.  When `None` (default), auto-extracted from the handler's first-parameter type hint.  Pass an explicit schema to override; there is no way to register with no schema when the handler is typed.

      <Expandable title="`RegisterFunctionFormat` fields">
        <ParamField body="body" type="list[RegisterFunctionFormat] | None">
          Nested fields for object types.
        </ParamField>

        <ParamField body="description" type="str | None">
          Human-readable description of the parameter.
        </ParamField>

        <ParamField body="items" type="RegisterFunctionFormat | None">
          Item schema for array types.
        </ParamField>

        <ParamField body="name" type="str" required>
          Parameter name.
        </ParamField>

        <ParamField body="required" type="bool">
          Whether the parameter is required.
        </ParamField>

        <ParamField body="type" type="str" required>
          Type string (`string`, `number`, `boolean`, `object`, `array`, `null`, `map`).
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="response_format" type="RegisterFunctionFormat | dict[str, Any] | None">
      Schema describing expected output.  Same auto-extraction semantics as `request_format`.
    </ParamField>
  </Tab>

  <Tab title="Example">
    ```python theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
    def greet(data):
        return {'message': f"Hello, {data['name']}!"}
    fn = worker.register_function("greet", greet, description="Greets a user")
    fn.unregister()
    from pydantic import BaseModel
    class GreetInput(BaseModel):
        name: str
    class GreetOutput(BaseModel):
        message: str
    async def greet(data: GreetInput) -> GreetOutput:
        return GreetOutput(message=f"Hello, {data.name}!")
    fn = worker.register_function("greet", greet, description="Greets a user")
    ```
  </Tab>
</Tabs>

***

### trigger

Invoke a remote function.

The routing behavior and return type depend on the `action` field:

* No action: synchronous, waits for the function to return.
* `TriggerAction.Enqueue(...)`: async via named queue, returns a dict
  with `messageReceiptId`.
* `TriggerAction.Void()`: fire-and-forget, returns `None`.

**Signature**

```python theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
trigger(request: dict[str, Any] | TriggerRequest) -> Any
```

<Tabs>
  <Tab title="Parameters">
    <ParamField body="request" type="dict[str, Any] | TriggerRequest" required>
      A `TriggerRequest` or dict with `function_id`, `payload`, and optional `action` / `timeout_ms`.

      <Expandable title="`TriggerRequest` fields" defaultOpen>
        <ParamField body="action" type="TriggerActionEnqueue | TriggerActionVoid | None">
          Sets how the trigger is routed. Omit for a synchronous request/response. Specify for a specific routing scheme (e.g. `TriggerAction.Enqueue(...)`, `TriggerAction.Void()`).
        </ParamField>

        <ParamField body="function_id" type="str" required>
          ID of the function to invoke.
        </ParamField>

        <ParamField body="metadata" type="Any | None">
          Arbitrary user-specifiable metadata supplied to the triggered handler function on every invocation.
        </ParamField>

        <ParamField body="payload" type="Any">
          Input data passed to the function.
        </ParamField>

        <ParamField body="timeout_ms" type="int | None">
          Override the default invocation timeout, in milliseconds.
        </ParamField>
      </Expandable>
    </ParamField>
  </Tab>

  <Tab title="Example">
    ```python theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
    result = worker.trigger({'function_id': 'greet', 'payload': {'name': 'World'}})
    worker.trigger({'function_id': 'notify', 'payload': {}, 'action': TriggerAction.Void()})
    ```
  </Tab>
</Tabs>

***

### register\_trigger\_type

Register a custom trigger type with the engine.

Returns a :class:`TriggerTypeRef` handle with `register_trigger`
and `register_function` methods.

**Signature**

```python theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
register_trigger_type(trigger_type: RegisterTriggerTypeInput | dict[str, Any], handler: TriggerHandler[Any]) -> TriggerTypeRef[Any, Any]
```

<Tabs>
  <Tab title="Parameters">
    <ParamField body="trigger_type" type="RegisterTriggerTypeInput | dict[str, Any]" required>
      A `RegisterTriggerTypeInput` or dict with `id`, `description`, and optional `trigger_request_format` / `call_request_format` (Pydantic class or dict).

      <Expandable title="`RegisterTriggerTypeInput` fields">
        <ParamField body="call_request_format" type="Any | None">
          JSON Schema describing the payload sent to functions.
        </ParamField>

        <ParamField body="description" type="str" required>
          Human-readable description of what this trigger type does.
        </ParamField>

        <ParamField body="id" type="str" required>
          Unique identifier for the trigger type (e.g. `state`, `durable:subscriber`).
        </ParamField>

        <ParamField body="trigger_request_format" type="Any | None">
          JSON Schema describing the expected trigger config.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="handler" type="TriggerHandler[Any]" required>
      A `TriggerHandler` instance.

      <Expandable title="`TriggerHandler` fields">
        <ParamField body="register_trigger" type="async (config: TriggerConfig[TConfig]) -> None" required>
          Register a trigger with the given configuration.
        </ParamField>

        <ParamField body="unregister_trigger" type="async (config: TriggerConfig[TConfig]) -> None" required>
          Unregister a trigger with the given configuration.
        </ParamField>
      </Expandable>
    </ParamField>
  </Tab>

  <Tab title="Example">
    ```python theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
    webhook = worker.register_trigger_type(
        RegisterTriggerTypeInput(
            id="webhook",
            description="Webhook trigger",
            trigger_request_format=WebhookConfig,
            call_request_format=WebhookCallRequest,
        ),
        WebhookHandler(),
    )
    webhook.register_function("handler", handle_webhook)
    webhook.register_trigger("handler", WebhookConfig(url="/hook"))
    ```
  </Tab>
</Tabs>

***

### unregister\_trigger\_type

Unregister a previously registered trigger type.

**Signature**

```python theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
unregister_trigger_type(trigger_type: RegisterTriggerTypeInput | dict[str, Any]) -> None
```

<Tabs>
  <Tab title="Parameters">
    <ParamField body="trigger_type" type="RegisterTriggerTypeInput | dict[str, Any]" required>
      A `RegisterTriggerTypeInput` or dict with `id` and optional `description`.

      <Expandable title="`RegisterTriggerTypeInput` fields">
        <ParamField body="call_request_format" type="Any | None">
          JSON Schema describing the payload sent to functions.
        </ParamField>

        <ParamField body="description" type="str" required>
          Human-readable description of what this trigger type does.
        </ParamField>

        <ParamField body="id" type="str" required>
          Unique identifier for the trigger type (e.g. `state`, `durable:subscriber`).
        </ParamField>

        <ParamField body="trigger_request_format" type="Any | None">
          JSON Schema describing the expected trigger config.
        </ParamField>
      </Expandable>
    </ParamField>
  </Tab>

  <Tab title="Example">
    ```python theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
    worker.unregister_trigger_type({"id": "webhook", "description": "Webhook trigger"})
    worker.unregister_trigger_type(RegisterTriggerTypeInput(id="webhook", description="Webhook trigger"))
    ```
  </Tab>
</Tabs>

***

### connect\_async

Connect to the III Engine via WebSocket.

Initializes OpenTelemetry (if configured), attaches the event loop,
and establishes the WebSocket connection. This is called automatically
during construction; use it only if you need to reconnect manually
from an async context.

**Signature**

```python theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
async () -> None
```

***

### get\_connection\_state

Return the current WebSocket connection state.

**Signature**

```python theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
get_connection_state() -> IIIConnectionState
```

#### Example

```python theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
worker = register_worker("ws://localhost:49134")
if worker.get_connection_state() != "connected":
    print("engine not reachable yet")
```

***

### shutdown

Gracefully shut down the client, releasing all resources.

Cancels any pending reconnection attempts, rejects all in-flight
invocations with an error, closes the WebSocket connection, and
stops the background event-loop thread.  After this call the
instance must not be reused.

**Signature**

```python theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
shutdown() -> None
```

#### Example

```python theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
worker = register_worker('ws://localhost:49134')
# ... do work ...
worker.shutdown()
```

***

### shutdown\_async

Gracefully shut down the client, releasing all resources.

Cancels any pending reconnection attempts, rejects all in-flight
invocations with an error, closes the WebSocket connection, and
stops the background event-loop thread.  After this call the
instance must not be reused.

**Signature**

```python theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
async () -> None
```

#### Example

```python theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
worker = register_worker('ws://localhost:49134')
# ... do work ...
await worker.shutdown_async()
```

***

### trigger\_async

Invoke a remote function.

The routing behavior and return type depend on the `action` field:

* No action: synchronous, waits for the function to return.
* `TriggerAction.Enqueue(...)`: async via named queue, returns a dict
  with `messageReceiptId`.
* `TriggerAction.Void()`: fire-and-forget, returns `None`.

**Signature**

```python theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
async (request: dict[str, Any] | TriggerRequest) -> Any
```

<Tabs>
  <Tab title="Parameters">
    <ParamField body="request" type="dict[str, Any] | TriggerRequest" required>
      A `TriggerRequest` or dict with `function_id`, `payload`, and optional `action` / `timeout_ms`.

      <Expandable title="`TriggerRequest` fields">
        <ParamField body="action" type="TriggerActionEnqueue | TriggerActionVoid | None">
          Sets how the trigger is routed. Omit for a synchronous request/response. Specify for a specific routing scheme (e.g. `TriggerAction.Enqueue(...)`, `TriggerAction.Void()`).
        </ParamField>

        <ParamField body="function_id" type="str" required>
          ID of the function to invoke.
        </ParamField>

        <ParamField body="metadata" type="Any | None">
          Arbitrary user-specifiable metadata supplied to the triggered handler function on every invocation.
        </ParamField>

        <ParamField body="payload" type="Any">
          Input data passed to the function.
        </ParamField>

        <ParamField body="timeout_ms" type="int | None">
          Override the default invocation timeout, in milliseconds.
        </ParamField>
      </Expandable>
    </ParamField>
  </Tab>

  <Tab title="Example">
    ```python theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
    result = await worker.trigger_async({'function_id': 'greet', 'payload': {'name': 'World'}})
    await worker.trigger_async({'function_id': 'notify', 'payload': {}, 'action': TriggerAction.Void()})
    ```
  </Tab>
</Tabs>

## Types

### iii

[`EnqueueResult`](#enqueueresult) · [`InitOptions`](#initoptions) · [`MiddlewareFunctionInput`](#middlewarefunctioninput) · [`StreamRequest`](#streamrequest) · [`StreamResponse`](#streamresponse) · [`TelemetryOptions`](#telemetryoptions) · [`TriggerAction`](#triggeraction) · [`TriggerActionEnqueue`](#triggeractionenqueue)

#### EnqueueResult

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

| Name               | Type  | Required | Description                                 |
| ------------------ | ----- | -------- | ------------------------------------------- |
| `messageReceiptId` | `str` | Yes      | Unique receipt ID for the enqueued message. |

***

#### InitOptions

Configuration options passed to `register_worker`.

| 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 `worker.trigger()` invocations 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`](#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`](#triggeractionenqueue) \| [`TriggerActionVoid`](#triggeractionvoid) \| None | No       | Routing action, if any.                                      |
| `context`     | `dict[str, Any]`                                                                                     | Yes      | Auth context returned by the auth function for this session. |
| `function_id` | `str`                                                                                                | Yes      | ID of the function being invoked.                            |
| `payload`     | `dict[str, Any]`                                                                                     | Yes      | Payload sent by the caller.                                  |

***

#### StreamRequest

Incoming streaming request received by a function registered with a stream trigger.

| 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`](#channelreader) | Yes      | -           |

***

#### StreamResponse

Streaming response built on top of a ChannelWriter.

| Name      | Type                                      | Required | Description |
| --------- | ----------------------------------------- | -------- | ----------- |
| `close`   | `() -> None`                              | Yes      | -           |
| `headers` | `async (headers: dict[str, str]) -> None` | Yes      | -           |
| `status`  | `async (status_code: int) -> None`        | Yes      | -           |
| `stream`  | `WritableStream`                          | Yes      | -           |
| `writer`  | [`ChannelWriter`](#channelwriter)         | Yes      | -           |

***

#### TelemetryOptions

Worker metadata reported to the engine (language, framework, project).

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

***

#### TriggerAction

Factory for creating trigger actions used with `trigger()`.

| Name      | Type                                                                | Required | Description                                                      |
| --------- | ------------------------------------------------------------------- | -------- | ---------------------------------------------------------------- |
| `Enqueue` | (\*, queue: str) -> [`TriggerActionEnqueue`](#triggeractionenqueue) | Yes      | Route the invocation through a named queue for async processing. |
| `Void`    | () -> [`TriggerActionVoid`](#triggeractionvoid)                     | Yes      | Fire-and-forget routing. No response is returned.                |

***

#### TriggerActionEnqueue

Routes the invocation through a named queue for async processing.

Requires a queue worker in the project. Run `iii worker add queue`.
Without it the trigger rejects with `enqueue_error` (no queue provider).

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

### iii.channel

[`Channel`](#channel) · [`ChannelReader`](#channelreader) · [`ChannelWriter`](#channelwriter) · [`StreamChannelRef`](#streamchannelref)

#### Channel

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

| Name         | Type                                    | Required | Description |
| ------------ | --------------------------------------- | -------- | ----------- |
| `reader`     | [`ChannelReader`](#channelreader)       | Yes      | -           |
| `reader_ref` | [`StreamChannelRef`](#streamchannelref) | Yes      | -           |
| `writer`     | [`ChannelWriter`](#channelwriter)       | Yes      | -           |
| `writer_ref` | [`StreamChannelRef`](#streamchannelref) | Yes      | -           |

***

#### ChannelReader

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

| Name          | Type                                       | Required | Description                                        |
| ------------- | ------------------------------------------ | -------- | -------------------------------------------------- |
| `close_async` | `async () -> None`                         | Yes      | -                                                  |
| `on_message`  | `(callback: Callable[[str], Any]) -> None` | Yes      | -                                                  |
| `read_all`    | `async () -> bytes`                        | Yes      | Read the entire stream into a single bytes object. |
| `stream`      | `Any`                                      | No       | -                                                  |

***

#### ChannelWriter

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

| Name                 | Type                          | Required | Description                                                           |
| -------------------- | ----------------------------- | -------- | --------------------------------------------------------------------- |
| `close`              | `() -> None`                  | Yes      | Fire-and-forget close.                                                |
| `close_async`        | `async () -> None`            | Yes      | -                                                                     |
| `send_message`       | `(msg: str) -> None`          | Yes      | Fire-and-forget text message. Queues a coroutine on the running loop. |
| `send_message_async` | `async (msg: str) -> None`    | Yes      | -                                                                     |
| `stream`             | `Any`                         | No       | -                                                                     |
| `write`              | `async (data: bytes) -> None` | Yes      | -                                                                     |

***

#### StreamChannelRef

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

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

### iii.engine

[`EngineFunctions`](#enginefunctions) · [`EngineTriggers`](#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)

#### 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.protocol

[`MessageType`](#messagetype) · [`RegisterFunctionFormat`](#registerfunctionformat) · [`RegisterFunctionInput`](#registerfunctioninput) · [`RegisterFunctionMessage`](#registerfunctionmessage) · [`RegisterTriggerInput`](#registertriggerinput) · [`RegisterTriggerMessage`](#registertriggermessage) · [`RegisterTriggerTypeInput`](#registertriggertypeinput) · [`RegisterTriggerTypeMessage`](#registertriggertypemessage) · [`TriggerRequest`](#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`](#registerfunctionformat)] \| None | No       | Nested fields for object types.                                                |
| `description` | `str \| None`                                                      | No       | Human-readable description of the parameter.                                   |
| `items`       | [`RegisterFunctionFormat`](#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`                                                                          | Yes      | Unique function identifier.                             |
| `invocation`      | `HttpInvocationConfig \| None`                                                 | No       | HTTP invocation config for externally hosted functions. |
| `metadata`        | `Any \| None`                                                                  | No       | Arbitrary metadata attached to the function.            |
| `request_format`  | [`RegisterFunctionFormat`](#registerfunctionformat) \| dict\[str, Any] \| None | No       | Schema describing expected input.                       |
| `response_format` | [`RegisterFunctionFormat`](#registerfunctionformat) \| dict\[str, Any] \| None | No       | Schema describing expected output.                      |

***

#### RegisterFunctionMessage

| Name              | Type                                                                           | Required | Description |
| ----------------- | ------------------------------------------------------------------------------ | -------- | ----------- |
| `description`     | `str \| None`                                                                  | No       | -           |
| `id`              | `str`                                                                          | Yes      | -           |
| `invocation`      | `HttpInvocationConfig \| None`                                                 | No       | -           |
| `message_type`    | [`MessageType`](#messagetype)                                                  | No       | -           |
| `metadata`        | `Any \| None`                                                                  | No       | -           |
| `request_format`  | [`RegisterFunctionFormat`](#registerfunctionformat) \| dict\[str, Any] \| None | No       | -           |
| `response_format` | [`RegisterFunctionFormat`](#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, matching the shape the trigger type expects.                     |
| `function_id` | `str`         | Yes      | ID of the function this trigger invokes when it fires.                                                |
| `metadata`    | `Any \| None` | No       | Arbitrary user-specifiable metadata supplied to the triggered handler function on every invocation.   |
| `type`        | `str`         | Yes      | Identifier of the registered trigger type this trigger uses (e.g. `storage::object-created`, `http`). |

***

#### RegisterTriggerMessage

| Name           | Type                          | Required | Description |
| -------------- | ----------------------------- | -------- | ----------- |
| `config`       | `Any`                         | Yes      | -           |
| `function_id`  | `str`                         | Yes      | -           |
| `id`           | `str`                         | Yes      | -           |
| `message_type` | [`MessageType`](#messagetype) | No       | -           |
| `metadata`     | `Any \| None`                 | No       | -           |
| `trigger_type` | `str`                         | Yes      | -           |

***

#### 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`         | Yes      | Human-readable description of what this trigger type does.                   |
| `id`                     | `str`         | Yes      | Unique identifier for the trigger type (e.g. `state`, `durable:subscriber`). |
| `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`](#messagetype) | No       | -           |
| `trigger_request_format` | `Any \| None`                 | No       | -           |

***

#### TriggerRequest

Request object for `trigger()`.

| Name          | Type                                                                                                 | Required | Description                                                                                                                                                                 |
| ------------- | ---------------------------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `action`      | [`TriggerActionEnqueue`](#triggeractionenqueue) \| [`TriggerActionVoid`](#triggeractionvoid) \| None | No       | Sets how the trigger is routed. Omit for a synchronous request/response. Specify for a specific routing scheme (e.g. `TriggerAction.Enqueue(...)`, `TriggerAction.Void()`). |
| `function_id` | `str`                                                                                                | Yes      | ID of the function to invoke.                                                                                                                                               |
| `metadata`    | `Any \| None`                                                                                        | No       | Arbitrary user-specifiable metadata supplied to the triggered handler function on every invocation.                                                                         |
| `payload`     | `Any`                                                                                                | No       | Input data passed to the function.                                                                                                                                          |
| `timeout_ms`  | `int \| None`                                                                                        | No       | Override the default invocation timeout, in milliseconds.                                                                                                                   |

### iii.runtime

[`FunctionRef`](#functionref) · [`TriggerTypeRef`](#triggertyperef)

#### FunctionRef

Reference to a registered function, allowing programmatic unregistration.

| Name         | Type                 | Required | Description                            |
| ------------ | -------------------- | -------- | -------------------------------------- |
| `id`         | `str`                | Yes      | The unique function identifier.        |
| `unregister` | `Callable[[], None]` | Yes      | Removes this function from the engine. |

***

#### 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`

| Name                | Type                                                                                                                          | Required | Description                                                      |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------- |
| `register_function` | `(function_id: str, handler: Callable[[R], Any] \| Callable[[R], Awaitable[Any]], *, description: str \| None = None) -> Any` | Yes      | Register a function whose input matches the call-request format. |
| `register_trigger`  | (function\_id: str, config: C, metadata: dict\[str, Any] \| None = None) -> [`Trigger`](#trigger)                             | Yes      | Register a trigger with validated config.                        |

### iii.state

[`IState`](#istate) · [`StateDeleteInput`](#statedeleteinput) · [`StateDeleteResult`](#statedeleteresult) · [`StateEventData`](#stateeventdata) · [`StateEventType`](#stateeventtype) · [`StateGetInput`](#stategetinput) · [`StateListInput`](#statelistinput) · [`StateSetInput`](#statesetinput) · [`StateSetResult`](#statesetresult) · [`StateUpdateInput`](#stateupdateinput) · [`StateUpdateResult`](#stateupdateresult)

#### IState

Abstract interface for state management operations.

| Name     | Type                                                                                                                | Required | Description                                      |
| -------- | ------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------ |
| `delete` | async (input: [`StateDeleteInput`](#statedeleteinput)) -> [`StateDeleteResult`](#statedeleteresult)                 | Yes      | Delete a state value.                            |
| `get`    | async (input: [`StateGetInput`](#stategetinput)) -> TData \| None                                                   | Yes      | Retrieve a value by scope and key.               |
| `list`   | async (input: [`StateListInput`](#statelistinput)) -> list\[TData]                                                  | Yes      | List all values in a scope.                      |
| `set`    | async (input: [`StateSetInput`](#statesetinput)) -> [`StateSetResult`](#statesetresult)\[TData] \| None             | Yes      | Set (create or overwrite) a state value.         |
| `update` | async (input: [`StateUpdateInput`](#stateupdateinput)) -> [`StateUpdateResult`](#stateupdateresult)\[TData] \| None | Yes      | Apply atomic update operations to a state value. |

***

#### StateDeleteInput

Input for deleting a state value.

| Name    | Type  | Required | Description              |
| ------- | ----- | -------- | ------------------------ |
| `key`   | `str` | Yes      | Key within the scope.    |
| `scope` | `str` | Yes      | State scope (namespace). |

***

#### StateDeleteResult

Result of a state delete operation.

| Name        | Type          | Required | Description                     |
| ----------- | ------------- | -------- | ------------------------------- |
| `old_value` | `Any \| None` | No       | Previous value (if it existed). |

***

#### StateEventData

Payload for state change events.

| Name         | Type                                | Required | Description                                |
| ------------ | ----------------------------------- | -------- | ------------------------------------------ |
| `event_type` | [`StateEventType`](#stateeventtype) | Yes      | Type of state change.                      |
| `key`        | `str`                               | Yes      | Key within the scope.                      |
| `new_value`  | `TData \| None`                     | No       | New value (for create/update events).      |
| `old_value`  | `TData \| None`                     | No       | Previous value (for update/delete events). |
| `scope`      | `str`                               | Yes      | State scope (namespace).                   |
| `type`       | `str`                               | No       | Event category (always `state`).           |

***

#### 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      | Key within the scope.    |
| `scope` | `str` | Yes      | State scope (namespace). |

***

#### StateListInput

Input for listing all values in a state scope.

| Name    | Type  | Required | Description              |
| ------- | ----- | -------- | ------------------------ |
| `scope` | `str` | Yes      | State scope (namespace). |

***

#### StateSetInput

Input for setting a state value.

| Name    | Type  | Required | Description              |
| ------- | ----- | -------- | ------------------------ |
| `key`   | `str` | Yes      | Key within the scope.    |
| `scope` | `str` | Yes      | State scope (namespace). |
| `value` | `Any` | Yes      | Value to store.          |

***

#### StateSetResult

Result of a state set operation.

| Name        | Type            | Required | Description                     |
| ----------- | --------------- | -------- | ------------------------------- |
| `new_value` | `TData`         | Yes      | New value that was stored.      |
| `old_value` | `TData \| None` | No       | Previous value (if it existed). |

***

#### StateUpdateInput

Input for atomically updating a state value.

| Name    | Type             | Required | Description                                            |
| ------- | ---------------- | -------- | ------------------------------------------------------ |
| `key`   | `str`            | Yes      | Key within the scope.                                  |
| `ops`   | `list[UpdateOp]` | Yes      | Ordered list of update operations to apply atomically. |
| `scope` | `str`            | Yes      | State scope (namespace).                               |

***

#### StateUpdateResult

Result of a state update operation.

| Name        | Type            | Required | Description                     |
| ----------- | --------------- | -------- | ------------------------------- |
| `new_value` | `TData`         | Yes      | New value after the update.     |
| `old_value` | `TData \| None` | No       | Previous value (if it existed). |

### iii.stream

[`IStream`](#istream) · [`StreamDeleteInput`](#streamdeleteinput) · [`StreamDeleteResult`](#streamdeleteresult) · [`StreamGetInput`](#streamgetinput) · [`StreamListGroupsInput`](#streamlistgroupsinput) · [`StreamListInput`](#streamlistinput) · [`StreamSetInput`](#streamsetinput) · [`StreamSetResult`](#streamsetresult) · [`StreamUpdateInput`](#streamupdateinput) · [`StreamUpdateResult`](#streamupdateresult)

#### IStream

Abstract interface for stream operations.

| Name          | Type                                                                                                                    | Required | Description                                      |
| ------------- | ----------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------ |
| `delete`      | async (input: [`StreamDeleteInput`](#streamdeleteinput)) -> [`StreamDeleteResult`](#streamdeleteresult)                 | Yes      | Delete an item from the stream.                  |
| `get`         | async (input: [`StreamGetInput`](#streamgetinput)) -> TData \| None                                                     | Yes      | Get an item from the stream.                     |
| `list`        | async (input: [`StreamListInput`](#streamlistinput)) -> list\[TData]                                                    | Yes      | Get all items in a group.                        |
| `list_groups` | async (input: [`StreamListGroupsInput`](#streamlistgroupsinput)) -> List\[str]                                          | Yes      | List all groups in the stream.                   |
| `set`         | async (input: [`StreamSetInput`](#streamsetinput)) -> [`StreamSetResult`](#streamsetresult)\[TData] \| None             | Yes      | Set an item in the stream.                       |
| `update`      | async (input: [`StreamUpdateInput`](#streamupdateinput)) -> [`StreamUpdateResult`](#streamupdateresult)\[TData] \| None | Yes      | Apply atomic update operations to a stream item. |

***

#### StreamDeleteInput

Input for stream delete operation.

| Name          | Type  | Required | Description         |
| ------------- | ----- | -------- | ------------------- |
| `group_id`    | `str` | Yes      | Group identifier.   |
| `item_id`     | `str` | Yes      | Item identifier.    |
| `stream_name` | `str` | Yes      | Name of the stream. |

***

#### StreamDeleteResult

Result of stream delete operation.

| Name        | Type          | Required | Description                     |
| ----------- | ------------- | -------- | ------------------------------- |
| `old_value` | `Any \| None` | No       | Previous value (if it existed). |

***

#### StreamGetInput

Input for stream get operation.

| Name          | Type  | Required | Description         |
| ------------- | ----- | -------- | ------------------- |
| `group_id`    | `str` | Yes      | Group identifier.   |
| `item_id`     | `str` | Yes      | Item identifier.    |
| `stream_name` | `str` | Yes      | Name of the stream. |

***

#### StreamListGroupsInput

Input for stream list groups operation.

| Name          | Type  | Required | Description         |
| ------------- | ----- | -------- | ------------------- |
| `stream_name` | `str` | Yes      | Name of the stream. |

***

#### StreamListInput

Input for stream list operation.

| Name          | Type  | Required | Description         |
| ------------- | ----- | -------- | ------------------- |
| `group_id`    | `str` | Yes      | Group identifier.   |
| `stream_name` | `str` | Yes      | Name of the stream. |

***

#### StreamSetInput

Input for stream set operation.

| Name          | Type  | Required | Description         |
| ------------- | ----- | -------- | ------------------- |
| `data`        | `Any` | Yes      | Data to store.      |
| `group_id`    | `str` | Yes      | Group identifier.   |
| `item_id`     | `str` | Yes      | Item identifier.    |
| `stream_name` | `str` | Yes      | Name of the stream. |

***

#### StreamSetResult

Result of stream set operation.

| Name        | Type            | Required | Description                     |
| ----------- | --------------- | -------- | ------------------------------- |
| `new_value` | `TData`         | Yes      | New value that was stored.      |
| `old_value` | `TData \| None` | No       | Previous value (if it existed). |

***

#### StreamUpdateInput

Input for stream update operation.

| Name          | Type               | Required | Description                                            |
| ------------- | ------------------ | -------- | ------------------------------------------------------ |
| `group_id`    | `str`              | Yes      | Group identifier.                                      |
| `item_id`     | `str`              | Yes      | Item identifier.                                       |
| `ops`         | `list['UpdateOp']` | Yes      | Ordered list of update operations to apply atomically. |
| `stream_name` | `str`              | Yes      | Name of the stream.                                    |

***

#### StreamUpdateResult

Result of stream update operation.

| Name        | Type                  | Required | Description                                                                                                                                                                                                                                                                                                                                                                               |
| ----------- | --------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `errors`    | `list[UpdateOpError]` | No       | Per-op errors. Emitted by `merge` and `append` for validation rejections (path depth/size, value depth, or a `__proto__` / `constructor` / `prototype` segment or top-level key) and by `append` for the `append.type_mismatch` and `append.target_not_object` surfaces. Successfully applied ops are still reflected in `new_value`. The field is omitted from the JSON wire when empty. |
| `new_value` | `TData`               | Yes      | New value after the update.                                                                                                                                                                                                                                                                                                                                                               |
| `old_value` | `TData \| None`       | No       | Previous value (if it existed).                                                                                                                                                                                                                                                                                                                                                           |

### iii.trigger

[`Trigger`](#trigger) · [`TriggerActionVoid`](#triggeractionvoid) · [`TriggerConfig`](#triggerconfig) · [`TriggerHandler`](#triggerhandler)

#### Trigger

Represents a registered trigger.

| Name         | Type         | Required | Description              |
| ------------ | ------------ | -------- | ------------------------ |
| `unregister` | `() -> None` | Yes      | Unregister this trigger. |

***

#### TriggerActionVoid

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

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

***

#### TriggerConfig

Configuration passed to a trigger handler when a trigger instance is
registered or unregistered.

| Name          | Type                     | Required | Description                                                                                         |
| ------------- | ------------------------ | -------- | --------------------------------------------------------------------------------------------------- |
| `config`      | `Any`                    | Yes      | Trigger-specific configuration.                                                                     |
| `function_id` | `str`                    | Yes      | Function to invoke when the trigger fires.                                                          |
| `id`          | `str`                    | Yes      | Trigger instance ID.                                                                                |
| `metadata`    | `dict[str, Any] \| None` | No       | Arbitrary user-specifiable metadata supplied to the triggered handler function on every invocation. |

***

#### TriggerHandler

Abstract base class for trigger handlers.

| Name                 | Type                                                                | Required | Description                                        |
| -------------------- | ------------------------------------------------------------------- | -------- | -------------------------------------------------- |
| `register_trigger`   | async (config: [`TriggerConfig`](#triggerconfig)\[TConfig]) -> None | Yes      | Register a trigger with the given configuration.   |
| `unregister_trigger` | async (config: [`TriggerConfig`](#triggerconfig)\[TConfig]) -> None | Yes      | Unregister a trigger with the given configuration. |