iicp-client · Python SDK

Official Python client library for the IICP protocol — 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

pip install iicp-client

Requires Python ≥ 3.11 and httpx.

---

Quickstart

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:

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

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

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

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

---

Development

pip install -e ".[dev]"   # install with dev deps
pytest tests/ -v          # run 28 unit tests
ruff check src tests       # lint

---

Links

• Protocol spec — full IICP specification
• Node setup guide — run your own node
• Error reference — all error codes
• iicp-client-typescript — TypeScript SDK
• iicp-client-rust — Rust SDK

---

Apache 2.0 · iicp.network