iicp-proxy 0.2.0__tar.gz

iicp_proxy-0.2.0/PKG-INFO

@@ -0,0 +1,23 @@
+Metadata-Version: 2.4
+Name: iicp-proxy
+Version: 0.2.0
+Summary: IICP Client Proxy — Client Plane
+License: Apache-2.0
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.115
+Requires-Dist: uvicorn[standard]>=0.32
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.9
+Requires-Dist: pydantic-settings>=2.6
+Requires-Dist: prometheus-client>=0.21
+Requires-Dist: cryptography>=42
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: respx>=0.21; extra == "dev"
+Requires-Dist: ruff>=0.8; extra == "dev"
+Requires-Dist: coverage[toml]>=7.6; extra == "dev"
+Requires-Dist: cbor2>=5.4; extra == "dev"
+Provides-Extra: cbor
+Requires-Dist: cbor2>=5.4; extra == "cbor"

iicp_proxy-0.2.0/README.md

@@ -0,0 +1,224 @@
+# IICP Client Proxy
+
+**Plane**: Client  
+**Language**: Python 3.11+ / FastAPI  
+**ADRs**: [ADR-001](../project/decisions/ADR-001-three-plane-architecture.md), [ADR-005](../project/decisions/ADR-005-adapter-proxy-python-fastapi.md), [ADR-008](../project/decisions/ADR-008-node-scoring-formula.md)
+
+Routes IICP task requests to discovered adapter nodes. Exposes three inbound LLM API surfaces on port 9483 so existing client tools work without modification:
+
+| Surface | Endpoints | Compatible tools |
+|---------|-----------|-----------------|
+| OpenAI-compat | `POST /v1/chat/completions` | OpenAI SDK, LangChain, LlamaIndex, liteLLM, Cursor |
+| Ollama-compat | `POST /api/chat`, `POST /api/generate`, `GET /api/tags`, `GET /api/version` | Open WebUI, Continue.dev, aider, Jan, Chatbox |
+| Anthropic-compat | `POST /v1/messages`, `GET /v1/models` | Anthropic SDK (`base_url` override) |
+
+All three surfaces translate to the same IICP `CALL` message and route through the same FallbackChain pipeline.
+
+The proxy **does not re-rank nodes** — it trusts the directory's score order and only filters out unavailable nodes (ADR-008 hard rule: score computed server-side only).
+
+---
+
+## Module layout
+
+```
+src/proxy/
+  main.py              — FastAPI app factory, startup; wires routing stack + mounts compat apps
+  config.py            — ProxyConfig (pydantic-settings)
+  clients/
+    directory.py       — DirectoryClient: GET /v1/discover, GET /v1/bootstrap
+    node.py            — NodeClient: POST /v1/task to a specific adapter node
+  routing/
+    selector.py        — NodeSelector: filter-only (available=true); preserves directory order
+    router.py          — TaskRouter: submit task to a single node via NodeClient
+    retry.py           — RetryManager: 3 attempts, 200ms base, ×2 backoff, ±20% jitter
+    circuit_breaker.py — CircuitBreaker: 5 failures → open, 30s half-open (per node)
+    fallback.py        — FallbackChain: best → second → local fallback → structured error
+    aggregator.py      — ResultAggregator: best-of-N / majority vote (Phase 2)
+  openai_compat/       — OpenAI API surface (POST /v1/chat/completions)
+    server.py          — create_compat_app(): base FastAPI app; other surfaces add routes to it
+    translator.py      — OpenAI body → IicpTask, IicpResponse → OpenAI response
+  ollama_compat/       — Ollama API surface (/api/chat, /api/generate, /api/tags, /api/version)
+    server.py          — add_ollama_routes(app): registers Ollama endpoints on the shared compat app
+    translator.py      — Ollama body → IicpTask, IicpResponse → Ollama response
+  anthropic_compat/    — Anthropic Messages API surface (/v1/messages, /v1/models)
+    server.py          — add_anthropic_routes(app): registers Anthropic endpoints on the shared compat app
+    translator.py      — Anthropic body → IicpTask, IicpResponse → Anthropic response
+  plugin/
+    iicp_provider.py   — IicpModelProvider: drop-in OpenAI-compatible provider for host assistants
+                         (OpenClaw, Moltbot etc.); injects directory + selector + fallback_chain
+  network/
+    peer_cache.py      — Local peer cache (Phase 2: persist discovered peers)
+  auth/
+    secrets.py         — Node token storage (OS keychain integration)
+  cip/
+    consumer.py        — CIPConsumerConfig + CIPCallFields (S.12 §4.1 wire-boundary validator:
+                         policy ∈ {best_of_n,majority_vote,map_reduce}, replicas ∈ [1,10])
+    aggregation.py     — CIPAggregationResult (S.12 §4.3): coordinator RESPONSE aggregation
+                         object; cross-field invariants: responded ≤ dispatched,
+                         selected_worker_id null when responded == 0
+    coordinator.py     — CIP coordinator: split task, collect results from workers
+    dispatch.py        — CIP dispatch helpers: worker selection + envelope construction
+    strategies.py      — Split/merge strategies (token-split, prompt-prefix, local-first precedence S.12 §2.2)
+  address_state.py     — AddressState: tracks observed source IP across directory interactions (ADR-011 DIR-ADDR-04)
+  metrics.py           — Shared Prometheus metric definitions (iicp_proxy_tasks_total etc.)
+  otel_tracer.py       — OTelTracer: W3C traceparent propagation, ADR-014 TRACE-04, no-op fallback
+```
+
+---
+
+## Configuration
+
+Environment variables (no TOML file for proxy — secrets should not live in files):
+
+| Env var | Default | Description |
+|---------|---------|-------------|
+| `IICP_PROXY_DIRECTORY_URL` | `"https://iicp.network/api"` | Directory service URL |
+| `IICP_NODE_TOKEN` | — | Bearer token for authenticating to adapter nodes |
+| `IICP_PROXY_PREFERRED_REGION` | — | Hint passed to directory `?region=` filter |
+| `IICP_PROXY_MAX_RETRIES` | `3` | Maximum task retry attempts |
+| `IICP_PROXY_DIRECTORY_TIMEOUT_MS` | `5000` | Directory request timeout (ms) |
+| `IICP_PROXY_HOST` | `"127.0.0.1"` | Listen address (loopback only by default) |
+| `IICP_PROXY_PORT` | `9483` | Listen port (reserved IICP proxy band; set `=11434` for Ollama drop-in) |
+
+---
+
+## Running
+
+```bash
+# Install
+pip install -e ".[dev]"
+
+# Run (listens on 127.0.0.1:9483 by default)
+iicp-proxy
+
+# Override the port — e.g. 11434 for literal Ollama drop-in
+IICP_PROXY_PORT=11434 iicp-proxy
+
+# Docker
+docker build -t iicp-proxy .
+docker run -p 127.0.0.1:9483:9483 --env-file .env iicp-proxy
+```
+
+---
+
+## Protocol surface usage
+
+**OpenAI-compat** (ChatGPT SDK, LangChain, liteLLM — point `base_url` at port 9483):
+```bash
+curl http://localhost:9483/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{"model":"iicp","messages":[{"role":"user","content":"Hello"}]}'
+```
+
+**Ollama-compat** (Open WebUI, Continue.dev, aider — set Ollama URL to `http://localhost:9483`):
+```bash
+curl http://localhost:9483/api/chat \
+  -H "Content-Type: application/json" \
+  -d '{"model":"iicp","messages":[{"role":"user","content":"Hello"}]}'
+```
+
+**Anthropic-compat** (Anthropic SDK — pass `base_url="http://localhost:9483"`):
+```bash
+curl http://localhost:9483/v1/messages \
+  -H "Content-Type: application/json" \
+  -H "x-api-key: any" \
+  -H "anthropic-version: 2023-06-01" \
+  -d '{"model":"claude-3-5-sonnet-20241022","max_tokens":100,"messages":[{"role":"user","content":"Hello"}]}'
+```
+
+All three translate to the same IICP `CALL` message with intent `urn:iicp:intent:llm:chat:v1`.
+
+---
+
+## Testing
+
+```bash
+pytest tests/ -v
+pytest tests/ --cov=proxy --cov-report=term-missing
+```
+
+---
+
+## Adding a new LLM API compat layer
+
+The proxy translates between client-side LLM API formats and the IICP task wire format.
+`openai_compat/` is the reference implementation; `ollama_compat/` and `anthropic_compat/`
+are working examples. To add support for a new API shape, follow this pattern:
+
+**1. Create `src/proxy/<name>_compat/`**
+
+```
+<name>_compat/
+  __init__.py    — empty
+  server.py      — add_<name>_routes(app): registers endpoints on the shared compat app
+  translator.py  — your_body → IicpTask, IicpResponse → your_response
+```
+
+`translator.py` must export:
+- `to_iicp_task(body: dict) -> tuple[UUID, str, dict]` — produces `(task_id, intent, payload)`
+- `to_<name>_response(iicp_response: dict, ...) -> dict` — converts IICP response to your format
+
+Use `ollama_compat/translator.py` as the template — it is ≤50 lines and handles the common
+patterns (flatten messages, forward options, map token counts).
+
+**2. Wire it in `main.py`**
+
+```python
+from proxy.<name>_compat.server import add_<name>_routes
+
+# In create_app(), after create_compat_app():
+compat = create_compat_app()
+add_ollama_routes(compat)
+add_anthropic_routes(compat)
+add_<name>_routes(compat)   # add your surface here
+app.mount("/", compat)
+```
+
+The routing stack (`selector`, `fallback_chain`, `aggregator`, `directory`) is attached
+to `app.state` during lifespan startup. In your handler:
+
+```python
+@app.post("/your-endpoint")
+async def your_handler(request: Request) -> JSONResponse:
+    fallback_chain = request.app.state.fallback_chain
+    directory      = request.app.state.directory
+    selector       = request.app.state.selector
+
+    body = await request.json()
+    task_id, intent, payload = your_translator.to_iicp_task(body)
+    nodes    = selector.select(await directory.discover(intent=intent))
+    response = await fallback_chain.execute(nodes, task_id, intent, payload, timeout_ms=30_000)
+    return JSONResponse(content=your_translator.to_your_response(response))
+```
+
+**3. No changes to routing, selector, or circuit breaker are needed.**
+
+The routing layer is format-agnostic. The only contract: produce a valid IICP
+`intent` URN and a `payload` dict; get back a response dict with a `result` key.
+
+---
+
+## CIP Wire Format Validation (CIP-V01..V06 — S.12)
+
+The `cip/` package enforces all normative wire constraints from S.12 before any
+dispatch occurs. Invalid values raise `ValidationError` at parse time → 422 IICP-E028.
+
+| Model | File | Validates |
+|-------|------|-----------|
+| `CIPCallFields` | `cip/consumer.py` | `cip.policy` ∈ `{best_of_n, majority_vote, map_reduce}` (V01); `cip.replicas` ∈ [1, 10] (V02) |
+| `CIPAggregationResult` | `cip/aggregation.py` | coordinator RESPONSE `cip_aggregation` object (V06): `replicas_responded` ≤ `replicas_dispatched`; `selected_worker_id` null when `replicas_responded == 0` |
+
+`CIPConsumerConfig` (also in `consumer.py`) is operator-level config loaded from
+`proxy.toml` — it silently clamps rather than rejecting. This is intentional: operator
+config is trusted; per-request wire input is not.
+
+---
+
+## Key invariants
+
+- Proxy binds to `127.0.0.1` only (loopback) — never exposed directly to internet.
+- TLS certificate validation is **not** bypassable; no `verify=False` anywhere.
+- Node score order from directory is preserved; only `available=false` nodes are filtered.
+- Circuit breaker state is per-node and in-memory; resets on proxy restart (accepted Phase 1 limitation).
+- No task payload content is logged (privacy invariant — mirrors adapter rule).
+- All retries use jittered backoff; `RetryManager` enforces maximum 3 attempts.

iicp_proxy-0.2.0/pyproject.toml

@@ -0,0 +1,59 @@
+[project]
+name = "iicp-proxy"
+version = "0.2.0"
+description = "IICP Client Proxy — Client Plane"
+license = {text = "Apache-2.0"}
+requires-python = ">=3.11"
+dependencies = [
+    "fastapi>=0.115",
+    "uvicorn[standard]>=0.32",
+    "httpx>=0.27",
+    "pydantic>=2.9",
+    "pydantic-settings>=2.6",
+    "prometheus-client>=0.21",
+    # P6-4.2b: Ed25519 verification for X-IICP-Replica-Sig on discover responses.
+    # Pure-Python alternatives exist but are 50x slower; cryptography is well-
+    # maintained and widely deployed.
+    "cryptography>=42",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.3",
+    "pytest-asyncio>=0.24",
+    "pytest-cov>=5.0",
+    "respx>=0.21",
+    "ruff>=0.8",
+    "coverage[toml]>=7.6",
+    "cbor2>=5.4",
+]
+cbor = [
+    "cbor2>=5.4",
+]
+
+[project.scripts]
+iicp-proxy = "proxy.main:run"
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+
+[tool.coverage.run]
+source = ["src/proxy"]
+omit = ["tests/*"]
+[tool.coverage.report]
+fail_under = 70

iicp_proxy-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

iicp_proxy-0.2.0/src/iicp_proxy.egg-info/PKG-INFO

@@ -0,0 +1,23 @@
+Metadata-Version: 2.4
+Name: iicp-proxy
+Version: 0.2.0
+Summary: IICP Client Proxy — Client Plane
+License: Apache-2.0
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.115
+Requires-Dist: uvicorn[standard]>=0.32
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.9
+Requires-Dist: pydantic-settings>=2.6
+Requires-Dist: prometheus-client>=0.21
+Requires-Dist: cryptography>=42
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: respx>=0.21; extra == "dev"
+Requires-Dist: ruff>=0.8; extra == "dev"
+Requires-Dist: coverage[toml]>=7.6; extra == "dev"
+Requires-Dist: cbor2>=5.4; extra == "dev"
+Provides-Extra: cbor
+Requires-Dist: cbor2>=5.4; extra == "cbor"

iicp_proxy-0.2.0/src/iicp_proxy.egg-info/SOURCES.txt

@@ -0,0 +1,85 @@
+README.md
+pyproject.toml
+src/iicp_proxy.egg-info/PKG-INFO
+src/iicp_proxy.egg-info/SOURCES.txt
+src/iicp_proxy.egg-info/dependency_links.txt
+src/iicp_proxy.egg-info/entry_points.txt
+src/iicp_proxy.egg-info/requires.txt
+src/iicp_proxy.egg-info/top_level.txt
+src/proxy/__init__.py
+src/proxy/address_state.py
+src/proxy/config.py
+src/proxy/main.py
+src/proxy/metrics.py
+src/proxy/otel_tracer.py
+src/proxy/anthropic_compat/__init__.py
+src/proxy/anthropic_compat/server.py
+src/proxy/anthropic_compat/translator.py
+src/proxy/auth/__init__.py
+src/proxy/auth/secrets.py
+src/proxy/cip/__init__.py
+src/proxy/cip/aggregation.py
+src/proxy/cip/consumer.py
+src/proxy/cip/coordinator.py
+src/proxy/cip/dispatch.py
+src/proxy/cip/gates.py
+src/proxy/cip/receipts.py
+src/proxy/cip/strategies.py
+src/proxy/clients/__init__.py
+src/proxy/clients/did_resolver.py
+src/proxy/clients/directory.py
+src/proxy/clients/node.py
+src/proxy/clients/replica_registry.py
+src/proxy/clients/replica_sig_verifier.py
+src/proxy/clients/trust_resolver.py
+src/proxy/network/__init__.py
+src/proxy/network/peer_cache.py
+src/proxy/ollama_compat/__init__.py
+src/proxy/ollama_compat/server.py
+src/proxy/ollama_compat/translator.py
+src/proxy/openai_compat/__init__.py
+src/proxy/openai_compat/server.py
+src/proxy/openai_compat/translator.py
+src/proxy/plugin/__init__.py
+src/proxy/plugin/iicp_provider.py
+src/proxy/routing/__init__.py
+src/proxy/routing/aggregator.py
+src/proxy/routing/circuit_breaker.py
+src/proxy/routing/fallback.py
+src/proxy/routing/retry.py
+src/proxy/routing/router.py
+src/proxy/routing/selector.py
+tests/test_address_learning.py
+tests/test_aggregator.py
+tests/test_anthropic_cip_dispatch.py
+tests/test_anthropic_compat.py
+tests/test_cip_aggregation.py
+tests/test_cip_call_validators.py
+tests/test_cip_consumer.py
+tests/test_cip_coordinator.py
+tests/test_cip_integration.py
+tests/test_circuit_breaker.py
+tests/test_compat_routes.py
+tests/test_coverage_gates.py
+tests/test_did_resolver.py
+tests/test_directory_client.py
+tests/test_directory_redirect_trust.py
+tests/test_directory_sig_verify.py
+tests/test_fallback.py
+tests/test_node_client.py
+tests/test_node_client_fallback.py
+tests/test_ollama_cip_dispatch.py
+tests/test_ollama_compat.py
+tests/test_openai_cip_dispatch.py
+tests/test_otel_proxy_spans.py
+tests/test_peer_cache.py
+tests/test_plugin.py
+tests/test_prometheus_metrics.py
+tests/test_proxy_config.py
+tests/test_replica_registry.py
+tests/test_replica_sig_verifier.py
+tests/test_retry.py
+tests/test_router.py
+tests/test_selector.py
+tests/test_translator.py
+tests/test_trust_resolver.py

iicp_proxy-0.2.0/src/iicp_proxy.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

iicp_proxy-0.2.0/src/iicp_proxy.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+iicp-proxy = proxy.main:run

iicp_proxy-0.2.0/src/iicp_proxy.egg-info/requires.txt

@@ -0,0 +1,19 @@
+fastapi>=0.115
+uvicorn[standard]>=0.32
+httpx>=0.27
+pydantic>=2.9
+pydantic-settings>=2.6
+prometheus-client>=0.21
+cryptography>=42
+
+[cbor]
+cbor2>=5.4
+
+[dev]
+pytest>=8.3
+pytest-asyncio>=0.24
+pytest-cov>=5.0
+respx>=0.21
+ruff>=0.8
+coverage[toml]>=7.6
+cbor2>=5.4

iicp_proxy-0.2.0/src/iicp_proxy.egg-info/top_level.txt

@@ -0,0 +1 @@
+proxy

iicp_proxy-0.2.0/src/proxy/__init__.py

@@ -0,0 +1,2 @@
+# SPDX-License-Identifier: Apache-2.0
+"""IICP client proxy — routes tasks to discovered adapter nodes."""

iicp_proxy-0.2.0/src/proxy/address_state.py

@@ -0,0 +1,29 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Runtime holder for the proxy's observed external IP (DIR-ADDR-02)."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class AddressState:
+    observed_source_ip: str | None = field(default=None)
+    endpoint: str | None = field(default=None)
+    node_id: str | None = field(default=None)
+
+    def update_from_ack(self, ack: dict) -> None:
+        self.observed_source_ip = ack.get("observed_source_ip")
+        self.node_id = ack.get("node_id")
+
+    def update_from_me(self, me: dict) -> None:
+        self.observed_source_ip = me.get("observed_source_ip")
+        self.node_id = me.get("node_id")
+        self.endpoint = me.get("endpoint")
+
+
+# Module-level singleton — set once at startup, read by status commands
+_state: AddressState = AddressState()
+
+
+def get_address_state() -> AddressState:
+    return _state

iicp_proxy-0.2.0/src/proxy/anthropic_compat/__init__.py

@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.0