https://github.com/roble3/iicp-client-python
Python client SDK for IICP — route tasks across an AI agent mesh by intent
https://github.com/roble3/iicp-client-python
ai-agents asyncio iicp llm protocol python sdk
Last synced: 24 days ago
JSON representation
Python client SDK for IICP — route tasks across an AI agent mesh by intent
- Host: GitHub
- URL: https://github.com/roble3/iicp-client-python
- Owner: RobLe3
- License: other
- Created: 2026-05-15T15:14:59.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-05-27T09:08:39.000Z (26 days ago)
- Last Synced: 2026-05-27T10:21:04.025Z (25 days ago)
- Topics: ai-agents, asyncio, iicp, llm, protocol, python, sdk
- Language: Python
- Homepage: https://iicp.network
- Size: 145 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# iicp-client · Python SDK
[](https://github.com/RobLe3/iicp-client-python/actions/workflows/ci.yml)
[](LICENSE)
[](https://iicp.network/spec)
[](https://pypi.org/project/iicp-client/)
Official Python client library for the [IICP protocol](https://iicp.network) — route AI agent tasks by intent across a self-organising mesh of provider nodes. No central broker. No hardcoded endpoints.
```
urn:iicp:intent:llm:chat:v1 → discover → select → submit
```
---
## Install
```bash
pip install iicp-client
```
Requires **Python ≥ 3.11** and [`httpx`](https://www.python-httpx.org/).
---
## Quickstart
```python
import asyncio
from iicp_client import IicpClient, ChatMessage
async def main():
client = IicpClient()
# chat_async discovers, selects best node, and submits in one call
response = await client.chat_async(
messages=[ChatMessage(role="user", content="Hello from IICP!")],
)
print(response.choices[0].message.content)
asyncio.run(main())
```
Synchronous wrapper for scripts and notebooks:
```python
from iicp_client import IicpClient, ChatMessage
client = IicpClient()
response = client.chat([ChatMessage(role="user", content="Hello from IICP!")])
print(response.choices[0].message.content)
```
---
## Configuration
```python
from iicp_client import ClientConfig
config = ClientConfig(
directory_url = "https://iicp.network", # IICP directory
timeout_ms = 30_000, # max 120 000 (SDK-04)
region = "eu-central", # prefer nodes in region
)
```
| Field | Default | Description |
|-------|---------|-------------|
| `directory_url` | `"https://iicp.network"` | IICP directory endpoint |
| `timeout_ms` | `30000` | Request timeout — max 120 000 ms |
| `region` | `None` | Preferred node region |
| `max_retries` | `3` | Retry count for transient errors |
---
## Discover options
```python
from iicp_client import DiscoverOptions
node_list = await client.discover_async(
"urn:iicp:intent:llm:chat:v1",
DiscoverOptions(
region = "eu-central",
model = "phi3:mini",
min_reputation = 0.7,
limit = 5,
)
)
nodes = node_list.nodes # list of Node objects
```
---
## Error handling
```python
from iicp_client import IicpClient, IicpError, ChatMessage
client = IicpClient()
try:
response = client.chat([ChatMessage(role="user", content="hi")])
except IicpError as e:
print(f"[{e.code}] {e.message} (HTTP {e.http_status})")
```
Error codes match the [IICP error reference](https://iicp.network/docs/error-reference) — e.g. `task_timeout`, `capacity_exceeded`, `no_nodes_available`.
---
## SDK conformance
| Rule | Description | Status |
|------|-------------|--------|
| SDK-01 | discover → select → submit pipeline with node retry | ✓ |
| SDK-02 | `task_id` auto-generated (UUID v4) | ✓ |
| SDK-03 | Intent URN pattern validation | ✓ |
| SDK-04 | `timeout_ms` capped at 120 000 ms | ✓ |
| SDK-05 | Retry on 429 / 503 with exponential back-off | ✓ |
| SDK-06 | W3C `traceparent` propagation | ✓ |
Conformance tier: `iicp:sdk:v1` (spec S.14) · [Request a badge](https://iicp.network/conformance)
---
## Development
```bash
pip install -e ".[dev]" # install with dev deps
pytest tests/ -v # run 28 unit tests
ruff check src tests # lint
```
---
## Links
- [Protocol spec](https://iicp.network/spec) — full IICP specification
- [Node setup guide](https://iicp.network/docs/node-setup) — run your own node
- [Error reference](https://iicp.network/docs/error-reference) — all error codes
- [iicp-client-typescript](https://github.com/RobLe3/iicp-client-typescript) — TypeScript SDK
- [iicp-client-rust](https://github.com/RobLe3/iicp-client-rust) — Rust SDK
---
Apache 2.0 · [iicp.network](https://iicp.network)