patchr 0.1.0__py3-none-any.whl

picux/protocols/mcp/server.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from picux import __version__
+from picux.protocols.mcp.contract import PicuxMCPContract
+
+
+class PicuxMCPServer:
+    """JSON-RPC MCP endpoint backed by the Picux route registry."""
+
+    def __init__(self, *, service: Any | None = None) -> None:
+        self.contract = PicuxMCPContract(service=service)
+
+    def handle(self, request: dict[str, Any]) -> dict[str, Any]:
+        requestId = request.get("id")
+        method = str(request.get("method", "") or "")
+        params = request.get("params", {}) if isinstance(request.get("params"), dict) else {}
+        if request.get("jsonrpc") != "2.0":
+            return self._error(requestId, -32600, "invalidRequest", {"reason": "jsonrpc"})
+        try:
+            result = self._dispatch(method, params)
+        except MCPDispatchError as exc:
+            return self._error(requestId, exc.code, exc.message, exc.data)
+        return {"jsonrpc": "2.0", "id": requestId, "result": result}
+
+    def _dispatch(self, method: str, params: dict[str, Any]) -> dict[str, Any]:
+        if method == "initialize":
+            return {
+                "protocolVersion": "2024-11-05",
+                "capabilities": {"tools": {}},
+                "serverInfo": {"name": "picux", "version": __version__},
+            }
+        if method == "ping":
+            return {"ok": True}
+        if method == "notifications/initialized":
+            return {"ok": True}
+        if method == "tools/list":
+            return self.contract.listTools()
+        if method == "tools/call":
+            name = str(params.get("name", params.get("tool", "")) or "")
+            args = params.get("arguments", params.get("args", {}))
+            if not isinstance(args, dict):
+                args = {}
+            if not name:
+                raise MCPDispatchError(-32602, "invalidParams", {"missing": "name"})
+            return self._toolResult(self.contract.callTool(name, args))
+        if method.startswith("picux."):
+            return self.contract.callTool(method, params)
+        raise MCPDispatchError(-32601, "methodNotFound", {"method": method})
+
+    @staticmethod
+    def _toolResult(result: dict[str, Any]) -> dict[str, Any]:
+        isError = not bool(result.get("ok"))
+        return {
+            **result,
+            "isError": isError,
+            "structuredContent": result.get("payload", result),
+            "content": [{"type": "text", "text": json.dumps(result, ensure_ascii=True, sort_keys=True)}],
+        }
+
+    @staticmethod
+    def _error(requestId: Any, code: int, message: str, data: dict[str, Any] | None = None) -> dict[str, Any]:
+        error = {"code": code, "message": message}
+        if data:
+            error["data"] = data
+        return {"jsonrpc": "2.0", "id": requestId, "error": error}
+
+
+class MCPDispatchError(Exception):
+    def __init__(self, code: int, message: str, data: dict[str, Any] | None = None) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.data = data or {}

picux/sandbox/__init__.py

@@ -0,0 +1,6 @@
+"""Picux developer sandbox runtimes."""
+
+from .midnight_arbitrage import MidnightArbitrageSandbox
+from .models import SandboxResult, TraceEvent, VendorQuote
+
+__all__ = ["MidnightArbitrageSandbox", "SandboxResult", "TraceEvent", "VendorQuote"]

picux/sandbox/midnight_arbitrage.py

@@ -0,0 +1,215 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from datetime import datetime, timezone
+from typing import Any
+
+from picux.api import PicuxApiService
+from picux.domains.pay import PayDomain
+from picux.domains.pay.models import Money, ProofOfValue, SettlementRequest
+from picux.protocols.mcp import PicuxMCPContract
+from picux.sandbox.models import SandboxResult, TraceEvent, VendorQuote
+
+
+CHAOS_MODES = {"", "latency", "modelError", "unauthorizedSpend", "freeze"}
+
+
+class MidnightArbitrageSandbox:
+    """Deterministic local sandbox for the HUNT -> RESOLVE -> PAY loop."""
+
+    def __init__(
+        self,
+        *,
+        clock: Callable[[], datetime] | None = None,
+        mcp: PicuxMCPContract | None = None,
+        pay: PayDomain | None = None,
+    ) -> None:
+        self.clock = clock or (lambda: datetime(2026, 5, 9, 12, 0, tzinfo=timezone.utc))
+        self.mcp = mcp or PicuxMCPContract(service=PicuxApiService())
+        self.pay = pay or PayDomain(verifier=self._verifyMandate, clock=self.clock)
+
+    def run(self, *, chaos: str = "") -> dict[str, Any]:
+        if chaos not in CHAOS_MODES:
+            raise ValueError(f"unknownChaos:{chaos}")
+
+        trace: list[TraceEvent] = []
+        task = self._createTask(trace)
+        vendors = self._hunt(trace, chaos)
+        decisionTree = self._resolve(trace, vendors, chaos)
+        mandate = self.mandate()
+        self._event(trace, "pay", "mandateView", "ready", "Intent Mandate loaded", {"mandateId": mandate["mandateId"]})
+
+        if chaos == "modelError":
+            freeze = self.pay.freeze(mandateId=mandate["mandateId"], taskId=task["taskId"], reason="modelErrorRollback")
+            self._event(trace, "resolve", "rollback", "failedClosed", "Model error detected; settlement blocked", {"receiptId": freeze["receiptId"]})
+            return self._result(False, "failedClosed", chaos, task, trace, vendors, decisionTree, mandate, freezeReceipt=freeze)
+
+        if chaos == "freeze":
+            freeze = self.pay.freeze(mandateId=mandate["mandateId"], taskId=task["taskId"], reason="protocolFreeze")
+            self._event(trace, "pay", "killSwitch", "failedClosed", "Protocol freeze stopped settlement", {"receiptId": freeze["receiptId"]})
+            return self._result(False, "failedClosed", chaos, task, trace, vendors, decisionTree, mandate, freezeReceipt=freeze)
+
+        selected = decisionTree.get("selected", "")
+        if not selected:
+            freeze = self.pay.freeze(mandateId=mandate["mandateId"], taskId=task["taskId"], reason="noSafeVendor")
+            self._event(trace, "pay", "freeze", "failedClosed", "No safe vendor remained after pruning", {"receiptId": freeze["receiptId"]})
+            return self._result(False, "failedClosed", chaos, task, trace, vendors, decisionTree, mandate, freezeReceipt=freeze)
+
+        quote = next(vendor for vendor in vendors if vendor.vendorId == selected)
+        amount = 120.0 if chaos == "unauthorizedSpend" else quote.netUsd
+        request = SettlementRequest(
+            taskId=task["taskId"],
+            vendorId=quote.vendorId,
+            amount=Money(amount, "USD"),
+            pov=ProofOfValue(
+                povId=f"pov_{quote.vendorId}",
+                rules=("inventoryVerified", "priceArbitrage20", "regionMatched", "hiddenFeeClear"),
+                meta={"discountPct": quote.discountPct, "netUsd": quote.netUsd},
+            ),
+        )
+        settled = self.pay.settle(mandate, request)
+        receipt = settled["receipt"]
+        if settled["ok"]:
+            self._event(trace, "pay", "microEscrow", "settled", "Proof-of-value verified; escrow settled", {"receiptId": receipt["receiptId"]})
+            self._event(trace, "pay", "receiptView", "ready", "Settlement receipt available", {"receipt": receipt})
+            return self._result(True, "settled", chaos, task, trace, vendors, decisionTree, mandate, receipt=receipt)
+
+        freeze = self.pay.freeze(mandateId=mandate["mandateId"], taskId=task["taskId"], reason="unauthorizedSpend")
+        self._event(
+            trace,
+            "pay",
+            "unauthorizedSpend",
+            "failedClosed",
+            "PAY rejected unauthorized spend and froze the rail",
+            {"errors": settled["decision"]["errors"], "receiptId": freeze["receiptId"]},
+        )
+        return self._result(False, "failedClosed", chaos, task, trace, vendors, decisionTree, mandate, receipt=receipt, freezeReceipt=freeze)
+
+    def mandate(self) -> dict[str, Any]:
+        return {
+            "mandateId": "mandate_midnight_arbitrage",
+            "issuer": {"entityId": "tenant_sandbox", "publicKey": "sandboxPub"},
+            "validUntil": "2099-01-01T00:00:00Z",
+            "constraints": {
+                "maxSpend": {"amount": 100.0, "currency": "USD"},
+                "allowedVendors": ["vendorA"],
+                "resolveRules": ["inventoryVerified", "priceArbitrage20", "regionMatched", "hiddenFeeClear"],
+            },
+            "signature": "sandboxSig",
+        }
+
+    def _createTask(self, trace: list[TraceEvent]) -> dict[str, Any]:
+        tools = self.mcp.listTools()["tools"]
+        self._event(trace, "mcp", "toolDiscovery", "ready", "Picux MCP tools discovered", {"toolCount": len(tools)})
+        result = self.mcp.callTool(
+            "picux.createTask",
+            {
+                "userId": "sandbox",
+                "channel": "sandbox",
+                "domain": "hunt",
+                "goal": "Midnight Arbitrage: capture Resource-X discount before reset",
+            },
+        )
+        task = result["payload"]["task"]
+        self._event(trace, "hunt", "marketAnomaly", "started", "Market anomaly triggered", {"taskId": task["taskId"]})
+        return task
+
+    def _hunt(self, trace: list[TraceEvent], chaos: str) -> tuple[VendorQuote, ...]:
+        vendors = (
+            VendorQuote("vendorA", 100.0, 80.0, 0.0, 12, "SE", 42),
+            VendorQuote("vendorB", 100.0, 75.0, 30.0, 30, "SE", 51),
+            VendorQuote("vendorC", 100.0, 70.0, 0.0, 0, "NO", 38),
+        )
+        if chaos == "latency":
+            vendors = tuple(VendorQuote(v.vendorId, v.listUsd, v.offerUsd, v.hiddenFeeUsd, v.stock, v.region, v.latencyMs + (250 if v.vendorId == "vendorA" else 0)) for v in vendors)
+            self._event(trace, "bridge", "latencyInject", "rerouted", "Latency injected; protocol route stayed live", {"vendorId": "vendorA", "addedMs": 250})
+
+        for vendor in vendors:
+            self._event(
+                trace,
+                "hunt",
+                "telemetryTick",
+                "observed",
+                f"{vendor.vendorId} quote observed",
+                {"vendor": vendor.toMap()},
+            )
+        self._event(trace, "hunt", "dealFound", "ready", "20% Resource-X discount candidate found", {"vendorId": "vendorA"})
+        return vendors
+
+    def _resolve(self, trace: list[TraceEvent], vendors: tuple[VendorQuote, ...], chaos: str) -> dict[str, Any]:
+        paths: list[dict[str, Any]] = []
+        selected = ""
+        for vendor in vendors:
+            reasons: list[str] = []
+            if vendor.discountPct < 20:
+                reasons.append("discountBelowThreshold")
+            if vendor.hiddenFeeUsd > 0:
+                reasons.append("hiddenFee")
+            if vendor.stock <= 0:
+                reasons.append("stockLimit")
+            if vendor.region != "SE":
+                reasons.append("regionMismatch")
+            status = "pruned" if reasons else "selected"
+            if status == "selected":
+                selected = vendor.vendorId
+            paths.append({"vendorId": vendor.vendorId, "status": status, "reasons": reasons, "netUsd": vendor.netUsd})
+            self._event(
+                trace,
+                "resolve",
+                "pathPrune" if reasons else "pathSelect",
+                status,
+                f"{vendor.vendorId} {status}",
+                {"vendorId": vendor.vendorId, "reasons": reasons},
+            )
+
+        if chaos == "modelError":
+            paths.append({"vendorId": "vendorZ", "status": "pruned", "reasons": ["modelHallucination"], "netUsd": 0.0})
+            self._event(trace, "resolve", "modelGuard", "failedClosed", "Hallucinated vendor pruned", {"vendorId": "vendorZ"})
+            selected = ""
+
+        tree = {"root": "marketAnomaly", "selected": selected, "paths": paths}
+        self._event(trace, "resolve", "decisionTree", "ready", "Decision tree ready", tree)
+        return tree
+
+    def _result(
+        self,
+        ok: bool,
+        status: str,
+        chaos: str,
+        task: dict[str, Any],
+        trace: list[TraceEvent],
+        vendors: tuple[VendorQuote, ...],
+        decisionTree: dict[str, Any],
+        mandate: dict[str, Any],
+        *,
+        receipt: dict[str, Any] | None = None,
+        freezeReceipt: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        return SandboxResult(
+            ok=ok,
+            scenario="midnightArbitrage",
+            status=status,
+            chaos=chaos,
+            task=task,
+            trace=tuple(trace),
+            vendors=vendors,
+            decisionTree=decisionTree,
+            mandate=mandate,
+            receipt=receipt,
+            freezeReceipt=freezeReceipt,
+        ).toMap()
+
+    def _event(
+        self,
+        trace: list[TraceEvent],
+        phase: str,
+        name: str,
+        status: str,
+        msg: str,
+        data: dict[str, Any] | None = None,
+    ) -> None:
+        trace.append(TraceEvent(len(trace) + 1, phase, name, status, msg, len(trace) * 37, data or {}))
+
+    @staticmethod
+    def _verifyMandate(payload: dict[str, Any], signature: str, publicKey: str) -> bool:
+        return payload.get("mandateId") == "mandate_midnight_arbitrage" and signature == "sandboxSig" and publicKey == "sandboxPub"

picux/sandbox/models.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class VendorQuote:
+    vendorId: str
+    listUsd: float
+    offerUsd: float
+    hiddenFeeUsd: float
+    stock: int
+    region: str
+    latencyMs: int = 0
+
+    @property
+    def netUsd(self) -> float:
+        return round(max(0.0, float(self.offerUsd) + float(self.hiddenFeeUsd)), 2)
+
+    @property
+    def discountPct(self) -> float:
+        if self.listUsd <= 0:
+            return 0.0
+        return round(((self.listUsd - self.offerUsd) / self.listUsd) * 100, 2)
+
+    def toMap(self) -> dict[str, Any]:
+        return {
+            "vendorId": self.vendorId,
+            "listUsd": round(self.listUsd, 2),
+            "offerUsd": round(self.offerUsd, 2),
+            "hiddenFeeUsd": round(self.hiddenFeeUsd, 2),
+            "netUsd": self.netUsd,
+            "discountPct": self.discountPct,
+            "stock": self.stock,
+            "region": self.region,
+            "latencyMs": self.latencyMs,
+        }
+
+
+@dataclass(frozen=True)
+class TraceEvent:
+    step: int
+    phase: str
+    name: str
+    status: str
+    msg: str
+    atMs: int
+    data: dict[str, Any] = field(default_factory=dict)
+
+    def toMap(self) -> dict[str, Any]:
+        return {
+            "step": self.step,
+            "phase": self.phase,
+            "name": self.name,
+            "status": self.status,
+            "msg": self.msg,
+            "atMs": self.atMs,
+            "data": self.data,
+        }
+
+
+@dataclass(frozen=True)
+class SandboxResult:
+    ok: bool
+    scenario: str
+    status: str
+    chaos: str
+    task: dict[str, Any]
+    trace: tuple[TraceEvent, ...]
+    vendors: tuple[VendorQuote, ...]
+    decisionTree: dict[str, Any]
+    mandate: dict[str, Any]
+    receipt: dict[str, Any] | None = None
+    freezeReceipt: dict[str, Any] | None = None
+
+    def toMap(self) -> dict[str, Any]:
+        return {
+            "ok": self.ok,
+            "scenario": self.scenario,
+            "status": self.status,
+            "chaos": self.chaos,
+            "task": self.task,
+            "trace": [event.toMap() for event in self.trace],
+            "vendors": [vendor.toMap() for vendor in self.vendors],
+            "decisionTree": self.decisionTree,
+            "mandate": self.mandate,
+            "receipt": self.receipt,
+            "freezeReceipt": self.freezeReceipt,
+        }

picux/sdk/__init__.py

@@ -0,0 +1,13 @@
+"""Picux SDK."""
+
+from .client import HttpTransport, InProcessTransport, PicuxApiError, PicuxClient
+from .external import ExternalAppClient, ExternalPricing
+
+__all__ = [
+    "ExternalAppClient",
+    "ExternalPricing",
+    "HttpTransport",
+    "InProcessTransport",
+    "PicuxApiError",
+    "PicuxClient",
+]