iicp-client 0.2.0__py3-none-any.whl

iicp_client/__init__.py

@@ -0,0 +1,35 @@
+"""iicp-client — Official Python client SDK for the IICP protocol."""
+
+from iicp_client.client import IicpClient
+from iicp_client.errors import IicpError
+from iicp_client.node import IicpNode, NodeConfig
+from iicp_client.types import (
+    ChatMessage,
+    ChatOptions,
+    ChatResponse,
+    ClientConfig,
+    DiscoverOptions,
+    NodeList,
+    TaskAuth,
+    TaskConstraints,
+    TaskRequest,
+    TaskResponse,
+)
+
+__version__ = "0.2.0"
+__all__ = [
+    "IicpClient",
+    "IicpError",
+    "IicpNode",
+    "NodeConfig",
+    "ClientConfig",
+    "TaskAuth",
+    "TaskConstraints",
+    "TaskRequest",
+    "TaskResponse",
+    "ChatMessage",
+    "ChatOptions",
+    "ChatResponse",
+    "DiscoverOptions",
+    "NodeList",
+]

iicp_client/_http.py

@@ -0,0 +1,112 @@
+"""Internal HTTP helpers — TLS context, timeout normalization."""
+from __future__ import annotations
+
+import secrets
+import ssl
+import time
+from typing import Any
+
+import httpx
+
+from iicp_client.errors import IicpError, from_http
+
+
+def _traceparent() -> str:
+    """Generate a W3C traceparent header value (SDK-06).
+
+    Format: 00-<trace-id>-<parent-id>-01
+    trace-id  = 16 random bytes as 32 hex chars
+    parent-id =  8 random bytes as 16 hex chars
+    flags     = 01 (sampled)
+    """
+    return f"00-{secrets.token_hex(16)}-{secrets.token_hex(8)}-01"
+
+
+def _tls_context(verify: bool) -> ssl.SSLContext | bool:
+    if not verify:
+        # SDK-05: tls_verify=False only permitted in debug; prod builds must verify
+        return False
+    ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+    ctx.minimum_version = ssl.TLSVersion.TLSv1_3
+    ctx.load_default_certs()
+    return ctx
+
+
+async def get_json(
+    url: str,
+    *,
+    params: dict[str, Any] | None = None,
+    timeout_ms: int = 5_000,
+    component: str = "directory",
+    tls_verify: bool = True,
+    traceparent: str | None = None,
+) -> dict[str, Any]:
+    timeout = timeout_ms / 1000.0
+    headers = {"traceparent": traceparent or _traceparent()}
+    try:
+        async with httpx.AsyncClient(
+            timeout=timeout, verify=_tls_context(tls_verify)
+        ) as client:
+            resp = await client.get(url, params=params, headers=headers)
+    except httpx.TimeoutException:
+        raise IicpError(
+            code="IICP-E003",
+            message=f"Request to {url} timed out after {timeout_ms}ms",
+            component=component,
+            retryable=True,
+        ) from None
+    except httpx.RequestError as exc:
+        raise IicpError(
+            code="IICP-E004",
+            message=f"Network error reaching {url}: {exc}",
+            component=component,
+            retryable=True,
+        ) from exc
+    if not resp.is_success:
+        raise from_http(resp.status_code, _safe_json(resp), component)
+    return resp.json()
+
+
+async def post_json(
+    url: str,
+    body: dict[str, Any],
+    *,
+    timeout_ms: int = 30_000,
+    component: str = "adapter",
+    tls_verify: bool = True,
+    traceparent: str | None = None,
+) -> tuple[dict[str, Any], int]:
+    """Returns (response_body, elapsed_ms)."""
+    timeout = (timeout_ms / 1000.0) + 2.0
+    headers = {"traceparent": traceparent or _traceparent()}
+    t0 = time.monotonic()
+    try:
+        async with httpx.AsyncClient(
+            timeout=timeout, verify=_tls_context(tls_verify)
+        ) as client:
+            resp = await client.post(url, json=body, headers=headers)
+    except httpx.TimeoutException:
+        raise IicpError(
+            code="IICP-E003",
+            message=f"Request to {url} timed out after {timeout_ms}ms",
+            component=component,
+            retryable=True,
+        ) from None
+    except httpx.RequestError as exc:
+        raise IicpError(
+            code="IICP-E004",
+            message=f"Network error reaching {url}: {exc}",
+            component=component,
+            retryable=True,
+        ) from exc
+    elapsed = int((time.monotonic() - t0) * 1000)
+    if not resp.is_success:
+        raise from_http(resp.status_code, _safe_json(resp), component)
+    return resp.json(), elapsed
+
+
+def _safe_json(resp: httpx.Response) -> dict:
+    try:
+        return resp.json()
+    except Exception:
+        return {"message": resp.text[:200]}

iicp_client/client.py

@@ -0,0 +1,248 @@
+"""IicpClient — primary entrypoint for the IICP Python SDK (ADR-016 §1)."""
+from __future__ import annotations
+
+import asyncio
+import re
+import uuid
+from typing import Any
+
+from iicp_client._http import _traceparent, get_json, post_json
+from iicp_client.errors import IicpError
+from iicp_client.types import (
+    ChatChoice,
+    ChatMessage,
+    ChatOptions,
+    ChatResponse,
+    ChatUsage,
+    ClientConfig,
+    DiscoverOptions,
+    Node,
+    NodeList,
+    TaskAuth,
+    TaskConstraints,
+    TaskMetrics,
+    TaskRequest,
+    TaskResponse,
+)
+
+_INTENT_RE = re.compile(r"^urn:iicp:intent:[a-z0-9_:/-]+$")
+_MAX_TIMEOUT_MS = 120_000
+
+
+class IicpClient:
+    """Discover → select → submit client for the IICP protocol.
+
+    Implements ADR-016 §1 (SDK-01..SDK-06 conformance rules).
+    """
+
+    def __init__(self, config: ClientConfig | None = None) -> None:
+        self._cfg = config or ClientConfig()
+        if self._cfg.timeout_ms > _MAX_TIMEOUT_MS:
+            # SDK-04: reject oversized timeouts at construction time
+            raise ValueError(
+                f"timeout_ms must be ≤ {_MAX_TIMEOUT_MS}; got {self._cfg.timeout_ms}"
+            )
+
+    # ------------------------------------------------------------------
+    # Public async API
+    # ------------------------------------------------------------------
+
+    async def discover_async(
+        self,
+        intent: str,
+        options: DiscoverOptions | None = None,
+        *,
+        traceparent: str | None = None,
+    ) -> NodeList:
+        """Discover nodes capable of handling *intent*."""
+        opts = options or DiscoverOptions()
+        params: dict[str, Any] = {"limit": min(opts.limit, 50)}
+        params["intent"] = intent
+        if opts.region or self._cfg.region:
+            params["region"] = opts.region or self._cfg.region
+        if opts.qos:
+            params["qos"] = opts.qos
+        if opts.min_reputation is not None:
+            params["min_reputation"] = opts.min_reputation
+        if opts.model:
+            params["model"] = opts.model
+
+        import time
+        t0 = time.monotonic()
+        data = await get_json(
+            f"{self._cfg.directory_url}/v1/discover",
+            params=params,
+            timeout_ms=5_000,
+            component="directory",
+            tls_verify=self._cfg.tls_verify,
+            traceparent=traceparent,
+        )
+        elapsed = int((time.monotonic() - t0) * 1000)
+
+        raw_nodes = data.get("nodes", [])
+        nodes = [
+            Node(
+                node_id=n["node_id"],
+                endpoint=n["endpoint"],
+                score=float(n.get("score", 0.0)),
+                available=bool(n.get("available", True)),
+                region=n.get("region", ""),
+                latency_estimate_ms=n.get("latency_estimate_ms"),
+                reputation_score=n.get("reputation_score"),
+            )
+            for n in raw_nodes
+        ]
+        return NodeList(nodes=nodes, query_ms=elapsed)
+
+    async def submit_async(self, request: TaskRequest) -> TaskResponse:
+        """Discover → select best node → submit task.
+
+        Retries up to max_retries on transient errors (SDK-01).
+        A single W3C traceparent is generated per submit call and propagated
+        to both the discover request and the node POST (SDK-06).
+        """
+        self._validate_intent(request.intent)
+        tp = _traceparent()  # SDK-06: one trace per operation, shared across calls
+        node_list = await self.discover_async(
+            request.intent,
+            DiscoverOptions(
+                region=request.constraints.region or self._cfg.region,
+                qos=request.constraints.qos,
+            ),
+            traceparent=tp,
+        )
+        if not node_list.nodes:
+            raise IicpError(
+                code="IICP-E006",
+                message=f"No nodes available for intent {request.intent!r}",
+                component="directory",
+                retryable=True,
+            )
+
+        node = node_list.nodes[0]  # highest score first (directory sorts by score)
+        task_id = str(uuid.uuid4())
+        body: dict[str, Any] = {
+            "task_id": task_id,
+            "intent": request.intent,
+            "payload": request.payload,
+            "constraints": {
+                "timeout_ms": request.constraints.timeout_ms,
+                "qos": request.constraints.qos,
+            },
+        }
+        if request.auth.node_token:
+            body["auth"] = {"node_token": request.auth.node_token}
+
+        last_exc: IicpError | None = None
+        for attempt in range(self._cfg.max_retries):
+            try:
+                raw, elapsed = await post_json(
+                    f"{node.endpoint}/v1/task",
+                    body,
+                    timeout_ms=request.constraints.timeout_ms,
+                    component="adapter",
+                    tls_verify=self._cfg.tls_verify,
+                    traceparent=tp,
+                )
+                return TaskResponse(
+                    task_id=raw.get("task_id", task_id),
+                    status=raw.get("status", "success"),
+                    result=raw.get("result"),
+                    metrics=TaskMetrics(
+                        latency_ms=elapsed,
+                        tokens_used=raw.get("usage", {}).get("total_tokens"),
+                        node_id=node.node_id,
+                    ),
+                )
+            except IicpError as exc:
+                last_exc = exc
+                if not exc.retryable or attempt == self._cfg.max_retries - 1:
+                    raise
+                await asyncio.sleep(0.5 * (attempt + 1))
+
+        raise last_exc  # type: ignore[misc]
+
+    async def chat_async(
+        self,
+        messages: list[ChatMessage],
+        options: ChatOptions | None = None,
+    ) -> ChatResponse:
+        """OpenAI-compatible chat over urn:iicp:intent:llm:chat:v1 (SDK-02)."""
+        opts = options or ChatOptions()
+        payload: dict[str, Any] = {
+            "messages": [{"role": m.role, "content": m.content} for m in messages],
+        }
+        if opts.model:
+            payload["model"] = opts.model
+        if opts.max_tokens is not None:
+            payload["max_tokens"] = opts.max_tokens
+        if opts.temperature is not None:
+            payload["temperature"] = opts.temperature
+
+        response = await self.submit_async(
+            TaskRequest(
+                intent="urn:iicp:intent:llm:chat:v1",
+                payload=payload,
+                constraints=TaskConstraints(
+                    timeout_ms=opts.timeout_ms or self._cfg.timeout_ms,
+                    qos=opts.qos,
+                ),
+                auth=TaskAuth(node_token=opts.node_token),
+            )
+        )
+
+        result = response.result or {}
+        raw_choices = result.get("choices", [])
+        choices = [
+            ChatChoice(
+                message=ChatMessage(
+                    role=c.get("message", {}).get("role", "assistant"),
+                    content=c.get("message", {}).get("content", ""),
+                ),
+                finish_reason=c.get("finish_reason", "stop"),
+            )
+            for c in raw_choices
+        ]
+        raw_usage = result.get("usage", {})
+        return ChatResponse(
+            id=response.task_id,
+            choices=choices,
+            usage=ChatUsage(
+                prompt_tokens=raw_usage.get("prompt_tokens", 0),
+                completion_tokens=raw_usage.get("completion_tokens", 0),
+                total_tokens=raw_usage.get("total_tokens", 0),
+            ),
+            model=result.get("model", opts.model or ""),
+            iicp_node_id=response.metrics.node_id,
+        )
+
+    # ------------------------------------------------------------------
+    # Sync wrappers (runs asyncio.run internally)
+    # ------------------------------------------------------------------
+
+    def discover(self, intent: str, options: DiscoverOptions | None = None) -> NodeList:
+        return asyncio.run(self.discover_async(intent, options))
+
+    def submit(self, request: TaskRequest) -> TaskResponse:
+        return asyncio.run(self.submit_async(request))
+
+    def chat(
+        self,
+        messages: list[ChatMessage],
+        options: ChatOptions | None = None,
+    ) -> ChatResponse:
+        return asyncio.run(self.chat_async(messages, options))
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _validate_intent(self, intent: str) -> None:
+        # SDK-03: validate URN format before sending
+        if not _INTENT_RE.match(intent):
+            raise IicpError(
+                code="IICP-E001",
+                message=f"Invalid intent URN: {intent!r}. Must match urn:iicp:intent:*",
+                component="proxy",
+                retryable=False,
+            )

iicp_client/errors.py

@@ -0,0 +1,44 @@
+"""IICP structured error type (ADR-016 §3)."""
+from __future__ import annotations
+
+
+class IicpError(Exception):
+    """Typed error surface — never exposes raw HTTP details to callers."""
+
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        component: str,
+        retryable: bool = False,
+        http_status: int | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.component = component
+        self.retryable = retryable
+        self.http_status = http_status
+
+    def __repr__(self) -> str:
+        return (
+            f"IicpError(code={self.code!r}, component={self.component!r}, "
+            f"retryable={self.retryable}, http_status={self.http_status})"
+        )
+
+
+# Well-known error codes (Phase 1 range, IICP-E001..E010)
+_RETRYABLE_CODES = {"IICP-E003", "IICP-E004", "IICP-E005"}
+
+
+def from_http(status: int, body: dict, component: str) -> IicpError:
+    """Build a typed IicpError from an HTTP response body."""
+    code = body.get("code", f"IICP-E{status:03d}")
+    message = body.get("message", body.get("error", "Unexpected error"))
+    return IicpError(
+        code=code,
+        message=message,
+        component=component,
+        retryable=code in _RETRYABLE_CODES or status in (429, 503),
+        http_status=status,
+    )

iicp_client/node.py

@@ -0,0 +1,404 @@
+"""IICP provider node — registration, heartbeats, and task serving.
+
+Endpoints served by ``IicpNode.serve()``:
+
++---------+----------------+----------------------------------------------+
+| Method  | Path           | Description                                  |
++=========+================+==============================================+
+| POST    | /v1/task       | Handle an inference task (IICP-E021 gate,    |
+|         |                | IICP-E011 nonce replay, W3C traceparent)     |
++---------+----------------+----------------------------------------------+
+| GET     | /iicp/health   | Liveness / capacity (always 200)             |
++---------+----------------+----------------------------------------------+
+| GET     | /metrics       | Prometheus text (503 if client absent)       |
++---------+----------------+----------------------------------------------+
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import threading
+import time
+from collections.abc import Callable, Coroutine
+from dataclasses import dataclass, field
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from typing import Any
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_TIMEOUT = 5.0
+_HEARTBEAT_INTERVAL = 30
+_NONCE_TTL = 300
+_REGISTER_PATH = "/v1/register"
+_HEARTBEAT_PATH = "/api/v1/heartbeat"
+
+# Lazy Prometheus import — None until first call, False when unavailable.
+_prom_mod: Any = None
+# Singleton: avoids duplicate metric registration across IicpNode instances.
+_global_metrics: _Metrics | None = None
+
+
+def _get_prom() -> Any:
+    global _prom_mod
+    if _prom_mod is None:
+        try:
+            import prometheus_client as _p
+
+            _prom_mod = _p
+        except ImportError:
+            _prom_mod = False
+    return _prom_mod if _prom_mod is not False else None
+
+
+@dataclass
+class NodeConfig:
+    node_id: str
+    endpoint: str
+    intent: str
+    model: str | None = None
+    region: str | None = None
+    capabilities: list[str] = field(default_factory=list)
+    directory_url: str = "https://iicp.network/api"
+    timeout: float = _DEFAULT_TIMEOUT
+    max_concurrent: int = 4
+
+
+TaskHandler = Callable[[dict[str, Any]], Coroutine[Any, Any, dict[str, Any]]]
+
+
+class _Metrics:
+    """Prometheus metrics wrapper — no-ops when prometheus_client is absent."""
+
+    def __init__(self, prom: Any) -> None:
+        self._enabled = prom is not None
+        if not self._enabled:
+            return
+        self.tasks_total = prom.Counter(
+            "iicp_tasks_total",
+            "Total IICP tasks handled",
+            ["status", "intent", "qos"],
+        )
+        self.task_latency_ms = prom.Histogram(
+            "iicp_task_latency_ms",
+            "IICP task processing latency (ms)",
+            ["intent", "qos"],
+            buckets=[50, 100, 250, 500, 1_000, 2_500, 5_000, 10_000, 30_000],
+        )
+        self.tokens_used_total = prom.Counter(
+            "iicp_tokens_used_total",
+            "Total tokens consumed",
+            ["intent"],
+        )
+
+    def observe(
+        self,
+        status: str,
+        intent: str,
+        qos: str,
+        latency_ms: float,
+        tokens: int = 0,
+    ) -> None:
+        if not self._enabled:
+            return
+        self.tasks_total.labels(status=status, intent=intent, qos=qos).inc()
+        self.task_latency_ms.labels(intent=intent, qos=qos).observe(latency_ms)
+        if tokens:
+            self.tokens_used_total.labels(intent=intent).inc(tokens)
+
+
+def _get_metrics() -> _Metrics:
+    global _global_metrics
+    if _global_metrics is None:
+        _global_metrics = _Metrics(_get_prom())
+    return _global_metrics
+
+
+class IicpNode:
+    """IICP provider node — registration, heartbeats, and task serving.
+
+    Example::
+
+        async def my_handler(task: dict) -> dict:
+            prompt = task["payload"]["messages"][-1]["content"]
+            return {"result": {"content": f"Echo: {prompt}"}}
+
+        node = IicpNode(NodeConfig(
+            node_id="my-node-001",
+            endpoint="https://my-host.example.com",
+            intent="urn:iicp:intent:llm:chat:v1",
+            max_concurrent=4,
+        ))
+        token = await node.register()
+        await node.serve(my_handler, port=8020, node_token=token)
+    """
+
+    def __init__(self, config: NodeConfig) -> None:
+        self._cfg = config
+        self._http = httpx.AsyncClient(timeout=config.timeout)
+        self._sem = threading.Semaphore(config.max_concurrent)
+        self._active_jobs = 0
+        self._jobs_lock = threading.Lock()
+        self._nonces: dict[str, float] = {}
+        self._nonces_lock = threading.Lock()
+        self._metrics = _get_metrics()
+
+    # ── Directory operations ──────────────────────────────────────────────
+
+    async def register(self) -> str:
+        """Register this node with the directory and return the node_token."""
+        payload: dict[str, Any] = {
+            "node_id": self._cfg.node_id,
+            "endpoint": self._cfg.endpoint,
+            "intent": self._cfg.intent,
+        }
+        if self._cfg.model:
+            payload["model"] = self._cfg.model
+        if self._cfg.region:
+            payload["region"] = self._cfg.region
+        if self._cfg.capabilities:
+            payload["capabilities"] = self._cfg.capabilities
+
+        resp = await self._http.post(
+            f"{self._cfg.directory_url.rstrip('/')}{_REGISTER_PATH}",
+            json=payload,
+        )
+        resp.raise_for_status()
+        data = resp.json()
+        token = data.get("node_token") or data.get("token")
+        if not token:
+            raise RuntimeError(f"Directory did not return node_token: {data}")
+        logger.info("Registered node %s, token acquired", self._cfg.node_id)
+        return str(token)
+
+    async def heartbeat(self, node_token: str) -> None:
+        """Send a single heartbeat to the directory."""
+        resp = await self._http.post(
+            f"{self._cfg.directory_url.rstrip('/')}{_HEARTBEAT_PATH}",
+            json={
+                "node_id": self._cfg.node_id,
+                "node_token": node_token,
+                "status": "available",
+            },
+        )
+        resp.raise_for_status()
+
+    async def _heartbeat_loop(self, node_token: str) -> None:
+        while True:
+            await asyncio.sleep(_HEARTBEAT_INTERVAL)
+            try:
+                await self.heartbeat(node_token)
+                logger.debug("Heartbeat sent for %s", self._cfg.node_id)
+            except Exception as exc:
+                logger.warning("Heartbeat failed: %s", exc)
+
+    # ── Nonce replay protection ───────────────────────────────────────────
+
+    def _check_nonce(self, nonce: str | None) -> bool:
+        """Return True if nonce is fresh (first use within TTL window)."""
+        if not nonce:
+            return True
+        now = time.monotonic()
+        with self._nonces_lock:
+            expired = [k for k, v in self._nonces.items() if v < now]
+            for k in expired:
+                del self._nonces[k]
+            if nonce in self._nonces:
+                return False
+            self._nonces[nonce] = now + _NONCE_TTL
+        return True
+
+    # ── HTTP server ───────────────────────────────────────────────────────
+
+    async def serve(
+        self,
+        handler: TaskHandler,
+        host: str = "0.0.0.0",
+        port: int = 8020,
+        node_token: str | None = None,
+    ) -> None:
+        """Start the task server (blocks until interrupted).
+
+        Args:
+            handler:    ``async def handler(task: dict) -> dict``
+            host:       Bind address (default ``0.0.0.0``).
+            port:       Bind port (default 8020).
+            node_token: If provided, starts a background heartbeat loop.
+        """
+        loop = asyncio.get_event_loop()
+        node = self
+
+        class _Handler(BaseHTTPRequestHandler):
+            def log_message(self, fmt: str, *args: Any) -> None:  # noqa: N802
+                logger.debug(fmt, *args)
+
+            def do_GET(self) -> None:  # noqa: N802
+                if self.path == "/iicp/health":
+                    self._health()
+                elif self.path == "/metrics":
+                    self._prometheus()
+                else:
+                    self.send_error(404)
+
+            def do_POST(self) -> None:  # noqa: N802
+                if self.path == "/v1/task":
+                    self._task()
+                else:
+                    self.send_error(404)
+
+            # ── GET /iicp/health ──────────────────────────────────────────
+
+            def _health(self) -> None:
+                with node._jobs_lock:
+                    active = node._active_jobs
+                denom = node._cfg.max_concurrent or 1
+                body = json.dumps(
+                    {
+                        "status": "ok",
+                        "node_id": node._cfg.node_id,
+                        "region": node._cfg.region or "unknown",
+                        "load": round(active / denom, 3),
+                        "active_jobs": active,
+                        "max_concurrent": node._cfg.max_concurrent,
+                        "available": active < node._cfg.max_concurrent,
+                        "model": node._cfg.model or "",
+                        "intent": node._cfg.intent,
+                    }
+                ).encode()
+                self._json_response(200, body)
+
+            # ── GET /metrics ──────────────────────────────────────────────
+
+            def _prometheus(self) -> None:
+                prom = _get_prom()
+                if prom is None:
+                    body = b"prometheus_client not installed"
+                    self.send_response(503)
+                    self.send_header("Content-Type", "text/plain; charset=utf-8")
+                    self.send_header("Content-Length", str(len(body)))
+                    self.end_headers()
+                    self.wfile.write(body)
+                    return
+                body = prom.generate_latest()
+                self.send_response(200)
+                self.send_header("Content-Type", prom.CONTENT_TYPE_LATEST)
+                self.send_header("Content-Length", str(len(body)))
+                self.end_headers()
+                self.wfile.write(body)
+
+            # ── POST /v1/task ─────────────────────────────────────────────
+
+            def _task(self) -> None:
+                # Concurrency gate — IICP-E021
+                if not node._sem.acquire(blocking=False):
+                    err = json.dumps(
+                        {
+                            "error": {
+                                "code": "IICP-E021",
+                                "message": "capacity_exceeded",
+                                "qos_class": None,
+                                "retry_after_ms": 2000,
+                            }
+                        }
+                    ).encode()
+                    self.send_response(429)
+                    self.send_header("Content-Type", "application/json")
+                    self.send_header("Retry-After", "2")
+                    self.send_header("Content-Length", str(len(err)))
+                    self.end_headers()
+                    self.wfile.write(err)
+                    return
+
+                with node._jobs_lock:
+                    node._active_jobs += 1
+                t0 = time.monotonic()
+                try:
+                    length = int(self.headers.get("Content-Length", 0))
+                    body: dict[str, Any] = (
+                        json.loads(self.rfile.read(length)) if length else {}
+                    )
+
+                    # Nonce replay — IICP-E011
+                    if not node._check_nonce(body.get("nonce")):
+                        err = json.dumps(
+                            {"error": {"code": "IICP-E011", "message": "replay_detected"}}
+                        ).encode()
+                        self.send_response(409)
+                        self.send_header("Content-Type", "application/json")
+                        self.send_header("Content-Length", str(len(err)))
+                        self.end_headers()
+                        self.wfile.write(err)
+                        return
+
+                    # W3C traceparent propagation
+                    traceparent = self.headers.get("traceparent")
+                    if traceparent:
+                        body.setdefault("_trace", {})["traceparent"] = traceparent
+
+                    intent = body.get("intent") or node._cfg.intent
+                    constraints = body.get("constraints") or {}
+                    qos = (
+                        constraints.get("qos_class", "best_effort")
+                        if isinstance(constraints, dict)
+                        else "best_effort"
+                    )
+
+                    try:
+                        result = asyncio.run_coroutine_threadsafe(
+                            handler(body), loop
+                        ).result(timeout=60)
+                        latency_ms = (time.monotonic() - t0) * 1000
+                        usage = result.get("usage") or {}
+                        tokens = (
+                            usage.get("total_tokens", 0) if isinstance(usage, dict) else 0
+                        )
+                        node._metrics.observe("completed", intent, qos, latency_ms, tokens)
+                        resp_body = json.dumps(
+                            {
+                                "task_id": body.get("task_id", ""),
+                                "status": "completed",
+                                **result,
+                            }
+                        ).encode()
+                        self._json_response(200, resp_body)
+                    except Exception as exc:
+                        latency_ms = (time.monotonic() - t0) * 1000
+                        node._metrics.observe("error", intent, qos, latency_ms)
+                        logger.error("Handler error: %s", exc)
+                        self.send_error(500, str(exc))
+                finally:
+                    node._sem.release()
+                    with node._jobs_lock:
+                        node._active_jobs -= 1
+
+            # ── helpers ───────────────────────────────────────────────────
+
+            def _json_response(self, status: int, body: bytes) -> None:
+                self.send_response(status)
+                self.send_header("Content-Type", "application/json")
+                self.send_header("Content-Length", str(len(body)))
+                self.end_headers()
+                self.wfile.write(body)
+
+        server = ThreadingHTTPServer((host, port), _Handler)
+        logger.info("IICP node %s listening on %s:%d", self._cfg.node_id, host, port)
+
+        bg_tasks: list[asyncio.Task] = []
+        if node_token:
+            bg_tasks.append(asyncio.create_task(self._heartbeat_loop(node_token)))
+
+        try:
+            await loop.run_in_executor(None, server.serve_forever)
+        finally:
+            server.shutdown()
+            for t in bg_tasks:
+                t.cancel()
+            await self._http.aclose()
+
+    async def __aenter__(self) -> IicpNode:
+        return self
+
+    async def __aexit__(self, *_: Any) -> None:
+        await self._http.aclose()

iicp_client/types.py

@@ -0,0 +1,118 @@
+"""Public types for iicp-client (ADR-016 §1)."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from iicp_client.errors import IicpError
+
+
+@dataclass
+class ClientConfig:
+    directory_url: str = "https://iicp.network"
+    region: str | None = None
+    timeout_ms: int = 30_000
+    max_retries: int = 3
+    tls_verify: bool = True
+
+
+@dataclass
+class TaskConstraints:
+    timeout_ms: int = 30_000
+    qos: str = "interactive"
+    region: str | None = None
+
+
+@dataclass
+class TaskAuth:
+    node_token: str | None = None
+
+
+@dataclass
+class TaskRequest:
+    intent: str
+    payload: dict[str, Any]
+    constraints: TaskConstraints = field(default_factory=TaskConstraints)
+    auth: TaskAuth = field(default_factory=TaskAuth)
+
+
+@dataclass
+class TaskMetrics:
+    latency_ms: int
+    tokens_used: int | None
+    node_id: str
+
+
+@dataclass
+class TaskResponse:
+    task_id: str
+    status: str
+    result: dict[str, Any] | None
+    metrics: TaskMetrics
+    error: IicpError | None = None
+
+
+@dataclass
+class ChatMessage:
+    role: str
+    content: str
+
+
+@dataclass
+class ChatOptions:
+    model: str | None = None
+    max_tokens: int | None = None
+    temperature: float | None = None
+    timeout_ms: int | None = None
+    qos: str = "interactive"
+    node_token: str | None = None
+
+
+@dataclass
+class ChatChoice:
+    message: ChatMessage
+    finish_reason: str
+
+
+@dataclass
+class ChatUsage:
+    prompt_tokens: int
+    completion_tokens: int
+    total_tokens: int
+
+
+@dataclass
+class ChatResponse:
+    id: str
+    choices: list[ChatChoice]
+    usage: ChatUsage
+    model: str
+    iicp_node_id: str
+
+
+@dataclass
+class DiscoverOptions:
+    region: str | None = None
+    qos: str | None = None
+    min_reputation: float | None = None
+    model: str | None = None
+    limit: int = 10
+
+
+@dataclass
+class Node:
+    node_id: str
+    endpoint: str
+    score: float
+    available: bool
+    region: str
+    latency_estimate_ms: int | None = None
+    reputation_score: float | None = None
+
+
+@dataclass
+class NodeList:
+    nodes: list[Node]
+    query_ms: int
+

iicp_client-0.2.0.dist-info/METADATA

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: iicp-client
+Version: 0.2.0
+Summary: Official Python client SDK for the IICP protocol
+Project-URL: Homepage, https://iicp.network
+Project-URL: Repository, https://github.com/RobLe3/iicp-client-python
+Project-URL: Documentation, https://iicp.network/docs
+Project-URL: Bug Tracker, https://github.com/RobLe3/iicp-client-python/issues
+Author-email: IICP Contributors <claude@roblemumin.com>
+License: Apache-2.0
+License-File: LICENSE
+Keywords: ai-agents,iicp,llm,protocol,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: prometheus-client>=0.20; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Provides-Extra: metrics
+Requires-Dist: prometheus-client>=0.20; extra == 'metrics'
+Description-Content-Type: text/markdown
+
+# iicp-client · Python SDK
+
+[![CI](https://github.com/RobLe3/iicp-client-python/actions/workflows/ci.yml/badge.svg)](https://github.com/RobLe3/iicp-client-python/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
+[![Protocol](https://img.shields.io/badge/IICP-v1.5-indigo.svg)](https://iicp.network/spec)
+[![PyPI](https://img.shields.io/badge/PyPI-iicp--client-blue?logo=pypi&logoColor=white)](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)

iicp_client-0.2.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+iicp_client/__init__.py,sha256=vBqdMu0m6HiqD5NlFbCJ4NWx8IWRopPrDLZqBvJIQdM,716
+iicp_client/_http.py,sha256=X4Pve4RWHcZH3qAT3lBMSig4Uq4MBWdTgDJOxQ7yUCs,3427
+iicp_client/client.py,sha256=UFfLsxiFq203yue-wSnKkhxZsBiwbRJtC9HbFPxX3oY,8895
+iicp_client/errors.py,sha256=XKZSp5uxkamoGhPIxcZsqsgd1Iv2P6osh5VhFhgRrI8,1358
+iicp_client/node.py,sha256=tTCk-iDs3UfBIi2cU9HTRujpoDRcXmoTQ3VYeeH69xU,15918
+iicp_client/types.py,sha256=X48Te4zqLv67QwwGh-TW-BpNzuOjsy4-RC1hJ5mXFGM,2125
+iicp_client-0.2.0.dist-info/METADATA,sha256=wuNvz0WBD1u_qIbl92tXXA3ZPJs_p4mIMvfUWIlZojc,5507
+iicp_client-0.2.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+iicp_client-0.2.0.dist-info/licenses/LICENSE,sha256=Iv_IDx2imte4neNvnlDK54ml35T8KSW30XdWoB7bFsw,10016
+iicp_client-0.2.0.dist-info/RECORD,,

iicp_client-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

iicp_client-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,180 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship made available under
+      the License, as indicated by a copyright notice that is included in
+      or attached to the work (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other transformations
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and its Derivative Works thereof.
+
+      "Contribution" shall mean, as submitted to the Licensor for inclusion
+      in the Work by the copyright owner or by an individual or Legal Entity
+      authorized to submit on behalf of the copyright owner. For the purposes
+      of this definition, "submitted" means any form of electronic, verbal,
+      or written communication sent to the Licensor or its representatives,
+      including but not limited to communication on electronic mailing lists,
+      source code control systems, and issue tracking systems that are managed
+      by, or on behalf of, the Licensor for the purpose of discussing and
+      improving the Work, but excluding communication that is conspicuously
+      marked or otherwise designated in writing by the copyright owner as
+      "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any Legal Entity on behalf of
+      whom a Contribution has been received by the Licensor and incorporated
+      within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or in combination with the Work to which such
+      Contribution(s) was submitted. If You institute patent litigation
+      against any entity (including a cross-claim or counterclaim in a
+      lawsuit) alleging that the Work or a Contribution incorporated within
+      the Work constitutes direct or contributory patent infringement, then
+      any patent licenses granted to You under this License for that Work
+      shall terminate as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, You must include a readable copy of the
+          attribution notices contained within such NOTICE file, in
+          at least one of the following places: within a NOTICE text
+          file distributed as part of the Derivative Works; within
+          the Source form or documentation, if provided along with the
+          Derivative Works; or, within a display generated by the
+          Derivative Works, if and wherever such third-party notices
+          normally appear. The contents of the NOTICE file are for
+          informational purposes only and do not modify the License.
+          You may add Your own attribution notices within Derivative
+          Works that You distribute, alongside or as an addendum to
+          the NOTICE text from the Work, provided that such additional
+          attribution notices cannot be construed as modifying the License.
+
+      You may add Your own license statement for Your modifications and
+      may provide additional grant of rights to use, copy, modify, merge,
+      publish, distribute, sublicense, and/or sell copies of the Work,
+      and to permit persons to whom the Work is furnished to do so, subject
+      to Your separate additional terms and conditions.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any conditions of title,
+      non-infringement, merchantability, or fitness for a particular
+      purpose. You are solely responsible for determining the
+      appropriateness of using or reproducing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or exemplary damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or all other
+      commercial damages or losses), even if such Contributor has been
+      advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may offer only
+      conditions fully consistent with this License to any recipient of
+      the Work.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Rob Lemumin
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.