Metadata-Version: 2.4
Name: iii-sdk
Version: 0.11.0.dev3
Summary: III SDK for Python
Project-URL: Homepage, https://github.com/iii-hq/sdk
Project-URL: Repository, https://github.com/iii-hq/sdk
Author: III
License: Apache-2.0
Keywords: iii,sdk
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: pydantic>=2.0
Requires-Dist: websockets>=12.0
Provides-Extra: dev
Requires-Dist: aiohttp>=3.9; extra == 'dev'
Requires-Dist: anyio>=4.0; extra == 'dev'
Requires-Dist: griffe>=1.0; extra == 'dev'
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: opentelemetry-api>=1.25; extra == 'dev'
Requires-Dist: opentelemetry-sdk>=1.25; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=6.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.2; extra == 'dev'
Provides-Extra: otel
Requires-Dist: opentelemetry-api>=1.25; extra == 'otel'
Requires-Dist: opentelemetry-sdk>=1.25; extra == 'otel'
Description-Content-Type: text/markdown

# iii-sdk

Python SDK for the [iii engine](https://github.com/iii-hq/iii).

[![PyPI](https://img.shields.io/pypi/v/iii-sdk)](https://pypi.org/project/iii-sdk/)
[![Python](https://img.shields.io/pypi/pyversions/iii-sdk)](https://pypi.org/project/iii-sdk/)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](../../../LICENSE)

## Install

```bash
pip install iii-sdk
```

## Hello World

```python
from iii import register_worker

iii = register_worker("ws://localhost:49134")

def greet(data):
    return {"message": f"Hello, {data['name']}!"}

iii.register_function({"id": "greet"}, greet)

iii.register_trigger({
    "type": "http",
    "function_id": "greet",
    "config": {"api_path": "/greet", "http_method": "POST"},
})

iii.connect()

result = iii.trigger({"function_id": "greet", "payload": {"name": "world"}})
print(result)  # {"message": "Hello, world!"}
```

## API

| Operation                | Signature                                         | Description                                            |
| ------------------------ | ------------------------------------------------- | ------------------------------------------------------ |
| Initialize               | `register_worker(url, options?)`                  | Create an SDK instance and auto-connect                |
| Register function        | `iii.register_function({"id": id}, handler)`      | Register a function that can be invoked by name        |
| Register trigger         | `iii.register_trigger({"type": ..., "function_id": ..., "config": ...})` | Bind a trigger (HTTP, cron, queue, etc.) to a function |
| Invoke (await result)    | `iii.trigger({"function_id": id, "payload": data})` | Invoke a function and wait for the result           |
| Invoke (fire-and-forget) | `iii.trigger({"function_id": id, ..., "action": TriggerAction.Void()})` | Fire-and-forget |
| Shutdown                 | `iii.shutdown()`                                  | Disconnect and stop background thread                  |

`register_worker()` creates the SDK instance and auto-connects to the engine.

### Registering Functions

```python
def create_order(data):
    return {"status_code": 201, "body": {"id": "123", "item": data["body"]["item"]}}

iii.register_function({"id": "orders.create"}, create_order)
```

### Registering Triggers

```python
iii.register_trigger({
    "type": "http",
    "function_id": "orders.create",
    "config": {"api_path": "/orders", "http_method": "POST"},
})
```

### Invoking Functions

```python
result = iii.trigger({"function_id": "orders.create", "payload": {"body": {"item": "widget"}}})
```

## Modules

| Import          | What it provides                  |
| --------------- | --------------------------------- |
| `iii`           | Core SDK (`III`, types)           |
| `iii.stream`    | Stream client for real-time state |
| `iii.telemetry` | OpenTelemetry integration         |

## Development

### Install in development mode

```bash
pip install -e .
```

### Type checking

```bash
mypy src
```

### Linting

```bash
ruff check src
```

## Resources

- [Documentation](https://iii.dev/docs)
- [iii Engine](https://github.com/iii-hq/iii)
- [Examples](https://github.com/iii-hq/iii-examples)
