iicp-proxy 0.2.0__py3-none-any.whl

iicp_proxy-0.2.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,48 @@
+proxy/__init__.py,sha256=Lfc1HttJAEcwR58vOPACs_2F8IdzgM7lFYWlQrxr9Iw,108
+proxy/address_state.py,sha256=tcfUTjH_-D4wvPqqqjcPvWbyscHPNdeNvcCVUeimjv0,899
+proxy/config.py,sha256=vsgiVDE1q1DIALPPClxYcMQvkC_D7QhHIR920yIhK3Y,6778
+proxy/main.py,sha256=mx2yrlaQxwnFbxpobR1CuiCRcIqqBlA97GJf_6eMXOI,8241
+proxy/metrics.py,sha256=91Lz24D49QezlaLDXck9bVctWaW4clFutLIvlUwiwuM,880
+proxy/otel_tracer.py,sha256=25FrfYhstH79-776xrY9VHK7_20mmJ021GAQzxYV1HU,7382
+proxy/anthropic_compat/__init__.py,sha256=bG7Ffen4LvQtgnYPFEpFccsWs81t4zqqeqn9ZeirH6E,38
+proxy/anthropic_compat/server.py,sha256=2CKDt4aSIF0jBrL2Q_5aaVcutOpNi7NCsxvXn1g0h18,8449
+proxy/anthropic_compat/translator.py,sha256=52IzAKwWRKZBPWxbRVBvZWCrurtIpi-FKHrp2HLfnac,3972
+proxy/auth/__init__.py,sha256=lCBXDz1ncyBS7uKJTTW-5YWK_gFHyuzsTTxSh7GO6gA,106
+proxy/auth/secrets.py,sha256=4g3rwPfQQKKYYLPiCvo_Qqc-T6Oi9GydUPNtBX6mL10,486
+proxy/cip/__init__.py,sha256=bG7Ffen4LvQtgnYPFEpFccsWs81t4zqqeqn9ZeirH6E,38
+proxy/cip/aggregation.py,sha256=C_zGV5VDWzDlwvliqg_akM-exNJ-i2FJByiBiTNR4d8,3576
+proxy/cip/consumer.py,sha256=xcIe_nlghZe8myMNU3NoWrfNOVou3Lpzl1gPrwLvce4,4236
+proxy/cip/coordinator.py,sha256=bj9Ex4rJ-onTjTkKyXLgQGgV9l4Clji0N_HU1Qia7Xc,4179
+proxy/cip/dispatch.py,sha256=HWF9z3T3zMpYfYdrAEcALY4SD4yg-H4sXxCvD9cK9Lg,6336
+proxy/cip/gates.py,sha256=75IxMgb1HOHU6wklGJquE7XqfhWhEBusz_ljXZCGINg,10070
+proxy/cip/receipts.py,sha256=gnwcC01m2DudiHshurEzM67Tn_8u5MCOFK1_0YlkbdY,5966
+proxy/cip/strategies.py,sha256=RvTi22m9_JdbPlcGombDufeIfkkhNhQUQ_0eHPiuOPc,3643
+proxy/clients/__init__.py,sha256=hb3Dqx75vIw7B16DC2hf7rwqsc4i0pG0-d7ON8pdEYE,151
+proxy/clients/did_resolver.py,sha256=AoeqKIgCl8-zYTuPKzZ7bWuk-ZR4gIkq456N8BIHQxs,3597
+proxy/clients/directory.py,sha256=32v5HlsjrdAhYmVneuidVU14Hi-StzgaixSNo1djeN4,16945
+proxy/clients/node.py,sha256=0Y7kB12v85xKCgpetQniJJM1Yd57EV-8tmiZsX_l9_w,5298
+proxy/clients/replica_registry.py,sha256=URVOmAn9f4oLdD8JY8yrFMQ0AQoQfGM7MM8tE6PZ9WQ,5600
+proxy/clients/replica_sig_verifier.py,sha256=avdWuH9Wp-5xVLjPXU-vfBbWO8uPmMlePHsmsH7J9h4,3392
+proxy/clients/trust_resolver.py,sha256=v3z6i0BmGT6nqazRk0ELzr2iRIhq8jQ-IDbIwNInWHk,4807
+proxy/network/__init__.py,sha256=TgsLhskDDpruFwpCNzFEHt3PnbxgdsD1aOwZCgW85Rs,110
+proxy/network/peer_cache.py,sha256=MdQ2QNq6UfN3K8s2I1mZSab0a616XQer3BIoTe9QQq4,4438
+proxy/ollama_compat/__init__.py,sha256=bG7Ffen4LvQtgnYPFEpFccsWs81t4zqqeqn9ZeirH6E,38
+proxy/ollama_compat/server.py,sha256=7KOwrTltNdGm8VRg2D5uVe-iT7YRvz36tAC0OEizBC8,7925
+proxy/ollama_compat/translator.py,sha256=BvskBs4ZTTs24TMav3KT2R_79He44UcSXYFaAN1PYZ4,3739
+proxy/openai_compat/__init__.py,sha256=3nn-coQF54jT-NiFHAgy0VIMW6qoUfQddg_T208dUWQ,204
+proxy/openai_compat/server.py,sha256=1Q0ug2miREFDmIW96o_JGtu91v8yhntJYRAy0rFPzaA,4933
+proxy/openai_compat/translator.py,sha256=08dNgt2DNJKrKcFAFqYQ2bnjYdtNBs7psBfUMP6TYFE,1270
+proxy/plugin/__init__.py,sha256=0BdZIoC_IrIwWlCthQ66Euyk_RzRPBQrj4Taj-pamaU,125
+proxy/plugin/iicp_provider.py,sha256=JJdxHbxMOOepIhcjK0JC27Hbe50F6ssLveANeEXYJQM,2430
+proxy/routing/__init__.py,sha256=C1aWxm8QzsgILSPN_V_oDQZLMhfsKhAV0PGSF1XZd6w,374
+proxy/routing/aggregator.py,sha256=_lERRNMOPpQRM9eDhQTXlKzv81M3oOtzhkhTbSdAiR4,4485
+proxy/routing/circuit_breaker.py,sha256=T-RUuwmTLmlcvOhwvh6FKvspVAfqD4cKpXWEGbe5IRc,3806
+proxy/routing/fallback.py,sha256=0sOXYv2F3B-O8S_YX3afOULcLyy5YDvZgKcimf3bqlE,10991
+proxy/routing/retry.py,sha256=hZmjppiVjROWBxY_b0OIu8dgrzqz51IcmVxreP-tyVI,3884
+proxy/routing/router.py,sha256=LEcgbyA3FiMwi23z5zSKbqg_n8feGmtcXpJlFUY7974,3856
+proxy/routing/selector.py,sha256=kuQTcL5hGBX64t6bOwU_9O1bNTqH2p72C5lfJK_XIJg,8014
+iicp_proxy-0.2.0.dist-info/METADATA,sha256=5gsf1_FUPJIfrnZV9jmfHzRIgmaR6Mbk99FglbtDScg,779
+iicp_proxy-0.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+iicp_proxy-0.2.0.dist-info/entry_points.txt,sha256=aIKEwg0qIZantd3tMk-DTNEvysEQqJ2vRrBw0H8YY7w,46
+iicp_proxy-0.2.0.dist-info/top_level.txt,sha256=z6RYBTHwGoNGkSVH3TvrDF_N3yovKtb4mncOphsetf8,6
+iicp_proxy-0.2.0.dist-info/RECORD,,

iicp_proxy-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

iicp_proxy-0.2.0.dist-info/entry_points.txt

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

iicp_proxy-0.2.0.dist-info/top_level.txt

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

proxy/__init__.py

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

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

proxy/anthropic_compat/__init__.py

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

proxy/anthropic_compat/server.py

@@ -0,0 +1,207 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Anthropic Messages API routes added to the proxy's FastAPI application.
+
+WHY /v1/messages alongside /v1/chat/completions: Anthropic clients call POST /v1/messages.
+OpenAI clients call POST /v1/chat/completions. Both paths exist under /v1/ with distinct
+route names — no collision. The proxy registers both and routes IICP tasks identically
+through the same fallback_chain.
+
+WHY /v1/models is a static list: Anthropic SDKs call GET /v1/models on startup to verify
+the base URL is valid. IICP proxy returns a minimal static entry so SDK initialization
+succeeds. Actual model selection is intent-based on the mesh, not name-based.
+
+WHY fake SSE streaming via six typed events: Anthropic SDK stream=True requires
+text/event-stream with message_start, content_block_start, content_block_delta,
+content_block_stop, message_delta, and message_stop events. IICP task execution is
+synchronous (single request-response cycle), so we emit the full response as a single
+content_block_delta event. SDK streaming iterators receive the complete text in the
+first delta and immediately see message_stop, satisfying the protocol without token-level
+granularity. True streaming requires adapter-side SSE (Phase 4 stretch goal, #280).
+
+Spec: spec/iicp-core.md §3. ADR: ADR-001, ADR-005. Issues: #279, #280.
+"""
+from __future__ import annotations
+
+import json
+import logging
+from collections.abc import Iterator
+from typing import Any
+
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse, Response, StreamingResponse
+
+from proxy.anthropic_compat.translator import to_anthropic_response, to_iicp_task
+from proxy.cip.dispatch import (
+    CIPInsufficientCredits,
+    compute_cip_envelope,
+    resolve_consumer_balance,
+)
+from proxy.otel_tracer import proxy_route_span
+
+logger = logging.getLogger(__name__)
+
+def _sse_events(
+    iicp_response: dict[str, Any],
+    task_id: str,
+    model: str,
+) -> Iterator[bytes]:
+    """Yield Anthropic SSE events for a complete IICP response.
+
+    Emits the six required event types (message_start, content_block_start,
+    content_block_delta, content_block_stop, message_delta, message_stop) with
+    the full response text in a single content_block_delta. Anthropic SDK
+    streaming iterators collect all deltas and reassemble them — receiving the
+    full text in one delta is equivalent to receiving it word-by-word.
+    """
+    result = iicp_response.get("result") or {}
+    choices: list[dict[str, Any]] = result.get("choices") or [{}]
+    message = (choices[0].get("message") or {}) if choices else {}
+    usage: dict[str, Any] = result.get("usage") or {}
+    text = message.get("content", "")
+    input_tokens = usage.get("prompt_tokens", 0)
+    output_tokens = usage.get("completion_tokens", 0)
+
+    def _event(name: str, data: dict[str, Any]) -> bytes:
+        return f"event: {name}\ndata: {json.dumps(data, ensure_ascii=False)}\n\n".encode()
+
+    yield _event("message_start", {
+        "type": "message_start",
+        "message": {
+            "id": f"msg_{task_id or 'iicp'}",
+            "type": "message",
+            "role": "assistant",
+            "content": [],
+            "model": model,
+            "stop_reason": None,
+            "stop_sequence": None,
+            "usage": {"input_tokens": input_tokens, "output_tokens": 0},
+        },
+    })
+    yield _event("content_block_start", {
+        "type": "content_block_start",
+        "index": 0,
+        "content_block": {"type": "text", "text": ""},
+    })
+    yield _event("content_block_delta", {
+        "type": "content_block_delta",
+        "index": 0,
+        "delta": {"type": "text_delta", "text": text},
+    })
+    yield _event("content_block_stop", {"type": "content_block_stop", "index": 0})
+    yield _event("message_delta", {
+        "type": "message_delta",
+        "delta": {"stop_reason": "end_turn", "stop_sequence": None},
+        "usage": {"output_tokens": output_tokens},
+    })
+    yield _event("message_stop", {"type": "message_stop"})
+
+
+# Static model list — Anthropic SDK calls GET /v1/models to validate base_url
+_MODELS_RESPONSE = {
+    "data": [
+        {
+            "id": "iicp",
+            "object": "model",
+            "created": 1700000000,
+            "owned_by": "iicp",
+        }
+    ],
+    "object": "list",
+}
+
+
+async def _execute_iicp(request: Request, body: dict[str, Any]) -> tuple[dict[str, Any], str]:
+    """Run an IICP task through the proxy routing stack. Returns (response, str_task_id)."""
+    fallback_chain = request.app.state.fallback_chain
+    directory = request.app.state.directory
+    selector = request.app.state.selector
+    peer_cache = getattr(request.app.state, "peer_cache", None)
+    cip_config = getattr(request.app.state, "cip_config", None)
+    session_tracker = getattr(request.app.state, "cip_budget_tracker", None)
+    node_token = getattr(request.app.state, "node_token", None)
+
+    task_id, intent, payload = to_iicp_task(body)
+    timeout_ms = int(body.get("timeout_ms", 30000))
+
+    raw: list[dict[str, Any]] = []
+    with proxy_route_span(str(task_id), intent):
+        if peer_cache is not None:
+            raw = await peer_cache.get_nodes(intent) or []
+        if not raw:
+            try:
+                raw = await directory.discover(intent=intent)
+                if peer_cache is not None:
+                    await peer_cache.fetch_and_cache(intent)
+            except Exception as exc:
+                logger.warning("Directory discover failed: %s", exc)
+
+        nodes = selector.select(raw)
+        consumer_balance = await resolve_consumer_balance(directory, node_token, cip_config)
+        cip_envelope = compute_cip_envelope(
+            nodes, body, cip_config, str(task_id),
+            session_tracker=session_tracker, consumer_balance=consumer_balance,
+        )
+        cip_block = body.get("cip") if isinstance(body.get("cip"), dict) else {}
+        response: dict[str, Any] = await fallback_chain.execute(
+            nodes, task_id, intent, payload, timeout_ms,
+            cip_envelope=cip_envelope,
+            cip_policy=cip_block.get("policy", "best_of_n"),
+            cip_replicas=int(cip_block.get("replicas", 1)),
+            cip_quorum=cip_block.get("quorum"),
+        )
+
+    return response, str(task_id)
+
+
+def add_anthropic_routes(app: FastAPI) -> None:
+    """Register Anthropic Messages API-compatible routes on an existing FastAPI app."""
+
+    @app.get("/v1/models", include_in_schema=False)
+    async def list_models() -> JSONResponse:
+        """Static model list — satisfies Anthropic SDK base_url validation."""
+        return JSONResponse(_MODELS_RESPONSE)
+
+    @app.post("/v1/messages", include_in_schema=False)
+    async def messages(request: Request) -> Response:
+        """Anthropic /v1/messages — translates to IICP CALL and returns Messages API shape.
+
+        stream=True: returns text/event-stream with six typed SSE events.
+        stream=False (Anthropic SDK default): returns application/json.
+        Errors always return application/json regardless of stream value.
+        """
+        body: dict[str, Any] = await request.json()
+        stream: bool = body.get("stream", False)  # Anthropic SDK default is False
+        try:
+            response, task_id = await _execute_iicp(request, body)
+        except CIPInsufficientCredits as exc:
+            return JSONResponse(
+                status_code=402,
+                content={
+                    "type": "error",
+                    "error": {
+                        "type": "api_error",
+                        "message": exc.error_code + ": Insufficient S-Credit balance for remote dispatch",
+                    },
+                },
+            )
+
+        if response.get("status") == "error":
+            err = response.get("error", {})
+            return JSONResponse(
+                status_code=502,
+                content={
+                    "type": "error",
+                    "error": {
+                        "type": "api_error",
+                        "message": err.get("code", "proxy_error") + ": Upstream error",
+                    },
+                },
+            )
+
+        model = body.get("model", "iicp")
+        if stream:
+            return StreamingResponse(
+                _sse_events(response, task_id, model),
+                media_type="text/event-stream",
+            )
+        return JSONResponse(content=to_anthropic_response(response, model, task_id))

proxy/anthropic_compat/translator.py

@@ -0,0 +1,101 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Translate between Anthropic Messages API and IICP task formats.
+
+WHY Anthropic-compat: The Anthropic Python/TypeScript SDKs (client.messages.create)
+are used by a growing segment of AI developers post-Claude-4. Adding a single
+base_url override routes those apps through the IICP mesh without further code changes.
+
+WHY system is extracted separately: Anthropic places the system prompt as a top-level
+string, not inside the messages list. IICP task format uses OpenAI-style messages.
+We convert the Anthropic system prompt to a {"role": "system", "content": "..."} entry
+at the front of the messages list so adapter nodes receive a standard message array.
+
+WHY content blocks are flattened to a string: Anthropic supports typed content blocks
+([{"type": "text", "text": "..."}]) instead of a plain string. IICP task messages use
+plain string content. Non-text block types (tool_use, tool_result, image) are omitted
+with a placeholder — the proxy is a text completion gateway, not a multimodal router.
+
+WHY max_tokens is required (but treated as optional here): Anthropic requires max_tokens;
+IICP does not mandate it. We forward it as-is — adapter nodes apply their own token cap
+if max_tokens is absent. Rejecting requests without max_tokens would break the Anthropic
+SDK default path unnecessarily.
+
+Spec: spec/iicp-core.md §3 (CALL/RESPONSE). ADR: ADR-001, ADR-005. Issue: #279.
+"""
+from __future__ import annotations
+
+from typing import Any
+from uuid import UUID, uuid4
+
+
+def _flatten_content(content: Any) -> str:
+    """Flatten Anthropic typed content blocks or plain strings to a plain string."""
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        parts = []
+        for block in content:
+            if isinstance(block, dict) and block.get("type") == "text":
+                parts.append(block.get("text", ""))
+        return " ".join(parts)
+    return ""
+
+
+def to_iicp_task(body: dict[str, Any]) -> tuple[UUID, str, dict[str, Any]]:
+    """Return (task_id, intent, payload) from an Anthropic /v1/messages body.
+
+    Handles system prompt extraction, content block flattening, and max_tokens forwarding.
+    """
+    task_id = uuid4()
+    intent = "urn:iicp:intent:llm:chat:v1"
+
+    messages: list[dict[str, Any]] = []
+
+    # Anthropic top-level system prompt → prepend as system message
+    system = body.get("system")
+    if system:
+        messages.append({"role": "system", "content": _flatten_content(system)})
+
+    for msg in body.get("messages") or []:
+        if not isinstance(msg, dict):
+            continue
+        role = msg.get("role", "user")
+        content = _flatten_content(msg.get("content", ""))
+        messages.append({"role": role, "content": content})
+
+    payload: dict[str, Any] = {
+        "messages": messages,
+        "model": body.get("model"),
+        "max_tokens": body.get("max_tokens"),
+        "temperature": body.get("temperature"),
+        "stream": body.get("stream", False),
+    }
+    return task_id, intent, payload
+
+
+def to_anthropic_response(
+    iicp_response: dict[str, Any],
+    model: str = "iicp",
+    task_id: str = "",
+) -> dict[str, Any]:
+    """Translate an IICP task response to Anthropic Messages API response format."""
+    result = iicp_response.get("result") or {}
+    choices: list[dict[str, Any]] = result.get("choices") or [{}]
+    message = (choices[0].get("message") or {}) if choices else {}
+    usage: dict[str, Any] = result.get("usage") or {}
+
+    return {
+        "id": f"msg_{task_id or 'iicp'}",
+        "type": "message",
+        "role": "assistant",
+        "model": model,
+        "content": [
+            {"type": "text", "text": message.get("content", "")},
+        ],
+        "stop_reason": "end_turn",
+        "stop_sequence": None,
+        "usage": {
+            "input_tokens": usage.get("prompt_tokens", 0),
+            "output_tokens": usage.get("completion_tokens", 0),
+        },
+    }

proxy/auth/__init__.py

@@ -0,0 +1,4 @@
+# SPDX-License-Identifier: Apache-2.0
+from .secrets import load_node_token
+
+__all__ = ["load_node_token"]

proxy/auth/secrets.py

@@ -0,0 +1,18 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Load the node token from the environment (or OS keychain as fallback)."""
+from __future__ import annotations
+
+import os
+
+
+class MissingNodeTokenError(RuntimeError):
+    pass
+
+
+def load_node_token(env_var: str = "IICP_NODE_TOKEN") -> str:
+    token = os.environ.get(env_var, "").strip()
+    if not token:
+        raise MissingNodeTokenError(
+            f"Node token not found. Set the {env_var} environment variable."
+        )
+    return token

proxy/cip/__init__.py

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

proxy/cip/aggregation.py

@@ -0,0 +1,77 @@
+# SPDX-License-Identifier: Apache-2.0
+"""CIP-V06: CIPAggregationResult — coordinator RESPONSE aggregation object (S.12 §4.3).
+
+When a proxy acts as CIP coordinator, every RESPONSE that involved dispatching at
+least one worker MUST include a `cip_aggregation` object in the trace (§4.3 MUST).
+This model is the canonical Python representation of that object.
+
+Spec normative requirements (S.12 §4.3):
+  - policy, replicas_dispatched, replicas_responded, selected_worker_id are MUST fields
+  - aggregation_latency_ms is SHOULD
+  - cip_vote_count and cip_quorum_threshold are MUST for majority_vote policy
+  - selected_worker_id MUST be null when replicas_responded == 0
+  - replicas_responded MUST NOT exceed replicas_dispatched
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+_VALID_CIP_POLICIES = frozenset({"best_of_n", "majority_vote", "map_reduce"})
+
+
+class CIPAggregationResult(BaseModel):
+    """CIP-V06: §4.3 cip_aggregation object included in coordinator RESPONSE trace."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    policy: str = Field(description="CIP policy used — best_of_n | majority_vote | map_reduce")
+    replicas_dispatched: int = Field(ge=0, description="Number of workers dispatched")
+    replicas_responded: int = Field(ge=0, description="Number of workers that responded")
+    selected_worker_id: str | None = Field(
+        default=None, description="Worker whose result was used; null when none responded"
+    )
+    aggregation_latency_ms: int | None = Field(
+        default=None, ge=0, description="Elapsed ms from last response to aggregation complete"
+    )
+    cip_vote_count: int | None = Field(
+        default=None, ge=0, description="Agreeing majority count (majority_vote only)"
+    )
+    cip_quorum_threshold: int | None = Field(
+        default=None, ge=1, description="Quorum required (majority_vote only)"
+    )
+
+    @model_validator(mode="before")
+    @classmethod
+    def validate_cross_fields(cls, values: Any) -> Any:
+        """CIP-V06: enforce cross-field invariants from S.12 §4.3."""
+        if isinstance(values, dict):
+            dispatched = values.get("replicas_dispatched", 0)
+            responded = values.get("replicas_responded", 0)
+            worker_id = values.get("selected_worker_id")
+            policy = values.get("policy", "")
+            vote_count = values.get("cip_vote_count")
+            quorum_threshold = values.get("cip_quorum_threshold")
+
+            if responded > dispatched:
+                raise ValueError(
+                    f"replicas_responded ({responded}) must not exceed "
+                    f"replicas_dispatched ({dispatched})"
+                )
+            if responded == 0 and worker_id is not None:
+                raise ValueError(
+                    "selected_worker_id must be null when replicas_responded == 0 (S.12 §4.3)"
+                )
+            # S.12 §4.3: cip_vote_count and cip_quorum_threshold MUST be non-null
+            # for majority_vote policy — null values indicate incomplete aggregation
+            if policy == "majority_vote":
+                if vote_count is None:
+                    raise ValueError(
+                        "cip_vote_count must be non-null for majority_vote policy (S.12 §4.3)"
+                    )
+                if quorum_threshold is None:
+                    raise ValueError(
+                        "cip_quorum_threshold must be non-null for majority_vote policy (S.12 §4.3)"
+                    )
+        return values

proxy/cip/consumer.py

@@ -0,0 +1,109 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Phase 5A CIP Consumer Mode — safe-default stub.
+
+The consumer allows the proxy to use remote IICP nodes as inference fallback
+when no local model is available. Off by default; requires explicit operator
+configuration per CIP-S1 (S.12) and ADR-012.
+
+Safety boundary: consumer mode only receives responses — it never exposes
+system prompt, local tools, or private memory to remote nodes.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+_VALID_CIP_POLICIES = frozenset({"best_of_n", "majority_vote", "map_reduce"})
+
+
+@dataclass
+class CIPConsumerConfig:
+    """Configuration for CIP Phase 5A Consumer Mode.
+
+    All fields default to the safest possible state (off / local-only).
+    Operators must explicitly opt in by setting ``enabled=True`` in
+    ``proxy.toml`` under ``[cooperative_inference]``.
+    """
+
+    enabled: bool = False
+    policy: str = "local_only"
+    replicas: int = 1
+    fallback_to_local: bool = True
+    coordinator_timeout_ms: int = 30_000
+
+    def __post_init__(self) -> None:
+        # Clamp replicas to [1, 10] — safety boundary on fan-out
+        self.replicas = max(1, min(10, self.replicas))
+        # Clamp timeout to [1, 60_000] ms
+        self.coordinator_timeout_ms = max(1, min(60_000, self.coordinator_timeout_ms))
+
+    def is_remote_allowed(self) -> bool:
+        """Return True only when consumer mode is on and policy permits remote."""
+        return self.enabled and self.policy != "local_only"
+
+
+class CIPCallFields(BaseModel):
+    """CIP-V01/CIP-V02: wire-boundary validation for the `cip` object in a CIP CALL.
+
+    A Coordinator MUST validate these fields before dispatching (S.12 §4.1).
+    Invalid values → 422 IICP-E028 at parse time, except majority_vote even
+    replicas which → IICP-E025 (S.12 §3.2).
+    """
+
+    model_config = ConfigDict(extra="ignore")
+
+    policy: str = Field(description="CIP aggregation policy — best_of_n | majority_vote | map_reduce")
+    replicas: int = Field(ge=1, le=10, description="Number of worker nodes to fan out to [1, 10]")
+    quorum: int | None = None
+
+    @field_validator("policy", mode="before")
+    @classmethod
+    def validate_policy(cls, v: Any) -> str:
+        """CIP-V01: cip.policy must be one of the three normative values (S.12 §4.1)."""
+        if v not in _VALID_CIP_POLICIES:
+            raise ValueError(
+                f"cip.policy must be one of {sorted(_VALID_CIP_POLICIES)}, got: {v!r}"
+            )
+        return str(v)
+
+    @model_validator(mode="after")
+    def validate_majority_vote_replicas(self) -> CIPCallFields:
+        """CIP-V02a + CIP-V07: cross-field validation after field-level checks pass.
+
+        CIP-V02a: majority_vote requires odd replicas ≥ 3 → IICP-E025 (S.12 §3.2).
+        CIP-V07:  quorum MUST be null OR a positive integer ≤ replicas → IICP-E028 (S.12 §4.1).
+
+        Uses mode="after" so both policy and replicas are already validated and typed.
+        Fires at model construction — callers do not need to invoke this explicitly.
+        """
+        if self.policy == "majority_vote":
+            if self.replicas < 3 or self.replicas % 2 == 0:
+                raise ValueError(
+                    f"IICP-E025: majority_vote requires odd replicas ≥ 3, "
+                    f"got: {self.replicas} (S.12 §3.2)"
+                )
+        if self.quorum is not None:
+            if self.quorum < 1:
+                raise ValueError(
+                    f"IICP-E028: cip.quorum must be a positive integer, got: {self.quorum} (S.12 §4.1)"
+                )
+            if self.quorum > self.replicas:
+                raise ValueError(
+                    f"IICP-E028: cip.quorum ({self.quorum}) must not exceed "
+                    f"cip.replicas ({self.replicas}) (S.12 §4.1)"
+                )
+        return self
+
+
+_consumer_config = CIPConsumerConfig()
+
+
+def get_consumer_config() -> CIPConsumerConfig:
+    return _consumer_config
+
+
+def configure_consumer(**kwargs: object) -> None:
+    global _consumer_config
+    _consumer_config = CIPConsumerConfig(**kwargs)  # type: ignore[arg-type]