patchr 0.1.0__py3-none-any.whl

picux/benchmarks/local.py

@@ -0,0 +1,286 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import time
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any
+
+from picux.api import PicuxApiService
+from picux.domains.pay import PayDomain
+
+
+@dataclass(frozen=True)
+class BenchmarkSample:
+    name: str
+    label: str
+    count: int
+    ok: bool
+    elapsedMs: float
+    avgMs: float
+    p50Ms: float
+    p95Ms: float
+    minMs: float
+    maxMs: float
+    opsPerSec: float
+    unit: str
+    errors: tuple[str, ...] = ()
+
+    def toMap(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "label": self.label,
+            "count": self.count,
+            "ok": self.ok,
+            "elapsedMs": self.elapsedMs,
+            "avgMs": self.avgMs,
+            "p50Ms": self.p50Ms,
+            "p95Ms": self.p95Ms,
+            "minMs": self.minMs,
+            "maxMs": self.maxMs,
+            "opsPerSec": self.opsPerSec,
+            "unit": self.unit,
+            "errors": list(self.errors),
+        }
+
+
+class LocalBenchmark:
+    """Reproducible local route benchmark for protocol evidence labels."""
+
+    def __init__(self, *, service: PicuxApiService | None = None, iterations: int = 100) -> None:
+        self.iterations = _iterations(iterations)
+        self.service = service or PicuxApiService(pay=PayDomain(verifier=self._verifier, clock=self._clock))
+
+    def run(self) -> dict[str, Any]:
+        generatedAt = self._clock().isoformat().replace("+00:00", "Z")
+        samples = [
+            self._loop("taskCreate", self._taskCreate, unit="routeCall"),
+            self._loop("policyEval", self._policyEval, unit="routeCall"),
+            self._loop("settlementPrepare", self._settlementPrepare, unit="routeCall"),
+            self._deliveryBatch(),
+        ]
+        sampleMaps = [sample.toMap() for sample in samples]
+        elapsedMs = round(sum(sample.elapsedMs for sample in samples), 3)
+        measuredCount = sum(sample.count for sample in samples)
+        report = {
+            "ok": all(sample.ok for sample in samples),
+            "kind": "localBenchmark",
+            "label": "measuredLocal",
+            "generatedAt": generatedAt,
+            "iterations": self.iterations,
+            "elapsedMs": elapsedMs,
+            "measuredCount": measuredCount,
+            "samples": sampleMaps,
+            "claims": self._claims(sampleMaps),
+            "notes": [
+                "Local process benchmark only; no network, provider, database, or payment rail latency is included.",
+                "Numbers are evidence for regression tracking, not production SLA claims.",
+            ],
+        }
+        report["reportId"] = self._reportId(report)
+        return report
+
+    def _loop(self, name: str, fn, *, unit: str) -> BenchmarkSample:
+        durations: list[int] = []
+        errors: list[str] = []
+        for idx in range(self.iterations):
+            start = time.perf_counter_ns()
+            ok, error = fn(idx)
+            durations.append(time.perf_counter_ns() - start)
+            if not ok:
+                errors.append(error or "failed")
+        return _sample(name, durations, unit=unit, errors=errors)
+
+    def _deliveryBatch(self) -> BenchmarkSample:
+        for idx in range(self.iterations):
+            self.service.handle(
+                "POST",
+                "/v1/event-deliveries",
+                {
+                    "eventId": f"bench_event_{idx}",
+                    "subId": "bench_sub",
+                    "clientId": "bench_client",
+                    "transport": "poll",
+                    "createdAt": 1_800_000_000 + idx,
+                },
+            )
+        start = time.perf_counter_ns()
+        _status, result = self.service.handle(
+            "POST",
+            "/v1/event-deliveries/claimBatch",
+            {"claimedBy": "bench_worker", "limit": self.iterations, "leaseSeconds": 60},
+        )
+        duration = time.perf_counter_ns() - start
+        count = int(result.get("count", 0) or 0)
+        errors = () if result.get("ok") and count == self.iterations else ("claimBatchMismatch",)
+        return _sample("eventDeliveryClaimBatch", [duration], unit=f"{count} deliveries", count=count, errors=list(errors))
+
+    def _taskCreate(self, idx: int) -> tuple[bool, str]:
+        status, result = self.service.handle(
+            "POST",
+            "/v1/tasks",
+            {
+                "taskId": f"bench_task_{idx}",
+                "userId": "bench",
+                "domain": "hunt",
+                "goal": "benchmark task route",
+            },
+        )
+        return status == 200 and result.get("ok") is True, str(result.get("error", ""))
+
+    def _policyEval(self, idx: int) -> tuple[bool, str]:
+        status, result = self.service.handle("POST", "/v1/security/policy/evaluate", self._policyPayload(idx))
+        return status == 200 and result.get("ok") is True, str(result.get("error", ""))
+
+    def _settlementPrepare(self, idx: int) -> tuple[bool, str]:
+        status, result = self.service.handle("POST", "/v1/pay/prepare", self._payPayload(idx))
+        return status == 200 and result.get("ok") is True, str(result.get("error", ""))
+
+    @staticmethod
+    def _policyPayload(idx: int) -> dict[str, Any]:
+        resource = f"escrow:bench_{idx}"
+        return {
+            "subjectId": "bench_agent",
+            "domain": "pay",
+            "action": "pay.settle",
+            "resource": resource,
+            "mandateId": "bench_payment",
+            "povRef": "bench_pov",
+            "session": {
+                "sessionId": "bench_session",
+                "status": "active",
+                "subjectId": "bench_agent",
+                "mandateId": "bench_payment",
+                "domains": ["pay"],
+                "actions": ["pay.settle"],
+                "expiresAt": "2099-01-01T00:00:00Z",
+            },
+            "grants": [
+                {
+                    "grantId": "bench_grant",
+                    "subjectId": "bench_agent",
+                    "domains": ["pay"],
+                    "actions": ["pay.settle"],
+                    "resources": [resource],
+                    "expiresAt": "2099-01-01T00:00:00Z",
+                }
+            ],
+        }
+
+    @staticmethod
+    def _payPayload(idx: int) -> dict[str, Any]:
+        return {
+            "paymentMandate": {
+                "mandateId": "bench_payment",
+                "kind": "payment",
+                "intentMandateId": "bench_intent",
+                "issuer": {"entityId": "bench_tenant", "publicKey": "benchPub"},
+                "payer": {"entityId": "bench_buyer", "accountRef": "vault:bench:payer"},
+                "payee": {"entityId": "bench_vendor", "accountRef": "vault:bench:payee"},
+                "amount": {"amount": 80, "currency": "USD"},
+                "rail": {"railId": "benchRail", "network": "local", "asset": "USD"},
+                "constraints": {"resolveRules": ["benchProof"]},
+                "validUntil": "2099-01-01T00:00:00Z",
+                "signature": "benchSig",
+            },
+            "request": {
+                "taskId": f"bench_task_{idx}",
+                "payeeId": "bench_vendor",
+                "amount": {"amount": 80, "currency": "USD"},
+                "pov": {"povId": "bench_pov", "rules": ["benchProof"]},
+            },
+            "adapter": {"adapterId": "benchAdapter", "rail": "benchRail"},
+        }
+
+    @staticmethod
+    def _claims(samples: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        byName = {str(sample.get("name", "")): sample for sample in samples}
+        settlement = byName.get("settlementPrepare", {})
+        taskCreate = byName.get("taskCreate", {})
+        return [
+            {
+                "claimId": "taskThroughput10k",
+                "label": "unverifiedTarget",
+                "target": "10000 tasks/sec",
+                "measuredLocal": taskCreate.get("opsPerSec", 0.0),
+                "note": "The brief target requires a dedicated production-like benchmark before public use.",
+            },
+            {
+                "claimId": "settlementSub500ms",
+                "label": "measuredLocal",
+                "target": "<500ms local settlement preparation",
+                "measuredP95Ms": settlement.get("p95Ms", 0.0),
+                "note": "This measures local PAY preparation only, not live payment execution.",
+            },
+            {
+                "claimId": "oversightReduction",
+                "label": "unverifiedTarget",
+                "target": "94% oversight reduction",
+                "note": "Requires case-study instrumentation outside this local benchmark.",
+            },
+        ]
+
+    @staticmethod
+    def _reportId(report: dict[str, Any]) -> str:
+        payload = {key: value for key, value in report.items() if key != "reportId"}
+        digest = hashlib.sha256(
+            json.dumps(payload, ensure_ascii=True, sort_keys=True, separators=(",", ":")).encode("utf-8")
+        ).hexdigest()[:24]
+        return f"bench_{digest}"
+
+    @staticmethod
+    def _clock() -> datetime:
+        return datetime(2026, 5, 9, 12, 0, tzinfo=timezone.utc)
+
+    @staticmethod
+    def _verifier(payload: dict[str, Any], signature: str, publicKey: str) -> bool:
+        return payload.get("mandateId") == "bench_payment" and signature == "benchSig" and publicKey == "benchPub"
+
+
+def _sample(
+    name: str,
+    durations: list[int],
+    *,
+    unit: str,
+    count: int | None = None,
+    errors: list[str] | None = None,
+) -> BenchmarkSample:
+    errors = errors or []
+    durations = durations or [0]
+    sampleCount = int(count if count is not None else len(durations))
+    elapsedNs = sum(durations)
+    elapsedMs = elapsedNs / 1_000_000
+    avgMs = (elapsedNs / max(1, sampleCount)) / 1_000_000
+    opsPerSec = (sampleCount / (elapsedNs / 1_000_000_000)) if elapsedNs > 0 else 0.0
+    return BenchmarkSample(
+        name=name,
+        label="measuredLocal",
+        count=sampleCount,
+        ok=not errors,
+        elapsedMs=round(elapsedMs, 3),
+        avgMs=round(avgMs, 3),
+        p50Ms=round(_percentile(durations, 0.50) / 1_000_000, 3),
+        p95Ms=round(_percentile(durations, 0.95) / 1_000_000, 3),
+        minMs=round(min(durations) / 1_000_000, 3),
+        maxMs=round(max(durations) / 1_000_000, 3),
+        opsPerSec=round(opsPerSec, 3),
+        unit=unit,
+        errors=tuple(dict.fromkeys(errors)),
+    )
+
+
+def _percentile(values: list[int], pct: float) -> int:
+    ordered = sorted(values)
+    if not ordered:
+        return 0
+    idx = min(len(ordered) - 1, max(0, int(round((len(ordered) - 1) * pct))))
+    return ordered[idx]
+
+
+def _iterations(value: int) -> int:
+    try:
+        parsed = int(value)
+    except (TypeError, ValueError):
+        return 100
+    return max(1, min(parsed, 1000))

picux/config.py

@@ -0,0 +1,140 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Mapping, Optional
+
+
+LEGACY_ENV_ALIASES: dict[str, tuple[str, ...]] = {
+    "PICUX_ENV": ("SWARM_ENV",),
+    "PICUX_PRODUCTION_MODE": ("SWARM_PRODUCTION_MODE",),
+    "PICUX_API_BASE_URL": ("SWARM_API_BASE_URL",),
+    "PICUX_API_TOKEN": ("SWARM_API_TOKEN",),
+    "PICUX_REDIS_URL": ("REDIS_URL",),
+    "PICUX_POSTGRES_DSN": ("SWARM_POSTGRES_DSN",),
+    "PICUX_MCP_BASE_URL": ("SWARM_MCP_BASE_URL",),
+    "PICUX_MCP_TOKEN": ("SWARM_MCP_TOKEN",),
+    "PICUX_A2A_BASE_URL": ("SWARM_A2A_BASE_URL",),
+    "PICUX_A2A_TOKEN": ("SWARM_A2A_TOKEN",),
+    "PICUX_BRIDGE_API_BASE": ("SWARM_BRIDGE_API_BASE",),
+    "PICUX_BRIDGE_API_TOKEN": ("SWARM_BRIDGE_API_TOKEN",),
+    "PICUX_POLICY_ENFORCEMENT": ("SWARM_POLICY_ENFORCEMENT",),
+    "PICUX_RESOLVE_OUTCOME_WEBHOOK_TOKEN": ("SWARM_RESOLVE_OUTCOME_WEBHOOK_TOKEN",),
+    "PICUX_BRIDGE_OUTCOME_WEBHOOK_TOKEN": ("SWARM_BRIDGE_OUTCOME_WEBHOOK_TOKEN",),
+    "PICUX_VAULT_KEY_B64": ("SWARM_VAULT_KEY_B64",),
+}
+
+
+@dataclass(frozen=True)
+class EnvValue:
+    name: str
+    value: str
+    source: str
+
+
+def resolve_env(
+    name: str,
+    default: str = "",
+    *,
+    env: Optional[Mapping[str, str]] = None,
+) -> EnvValue:
+    """Resolve a Picux env var with temporary legacy fallbacks."""
+
+    source_env = os.environ if env is None else env
+    if name in source_env and str(source_env[name]).strip() != "":
+        return EnvValue(name=name, value=str(source_env[name]), source=name)
+
+    for alias in LEGACY_ENV_ALIASES.get(name, ()):
+        if alias in source_env and str(source_env[alias]).strip() != "":
+            return EnvValue(name=name, value=str(source_env[alias]), source=alias)
+
+    return EnvValue(name=name, value=default, source="default")
+
+
+def env_bool(value: str, *, default: bool = False) -> bool:
+    if value is None or str(value).strip() == "":
+        return default
+    return str(value).strip().lower() in {"1", "true", "yes", "on", "prod", "production", "live"}
+
+
+@dataclass(frozen=True)
+class PicuxSettings:
+    env: str
+    prod: bool
+    apiUrl: str
+    apiToken: str
+    redisUrl: str
+    postgresDsn: str
+    mcpUrl: str
+    mcpToken: str
+    a2aUrl: str
+    a2aToken: str
+    bridgeUrl: str
+    bridgeToken: str
+    policyEnforcement: bool
+    resolveToken: str
+    bridgeOutcomeToken: str
+    vaultKey: str
+    sources: dict[str, str]
+
+    @classmethod
+    def fromEnv(cls, env: Optional[Mapping[str, str]] = None) -> "PicuxSettings":
+        resolved = {
+            name: resolve_env(name, default=default, env=env)
+            for name, default in {
+                "PICUX_ENV": "local",
+                "PICUX_PRODUCTION_MODE": "false",
+                "PICUX_API_BASE_URL": "http://127.0.0.1:8088",
+                "PICUX_API_TOKEN": "",
+                "PICUX_REDIS_URL": "redis://localhost:6379/0",
+                "PICUX_POSTGRES_DSN": "",
+                "PICUX_MCP_BASE_URL": "",
+                "PICUX_MCP_TOKEN": "",
+                "PICUX_A2A_BASE_URL": "",
+                "PICUX_A2A_TOKEN": "",
+                "PICUX_BRIDGE_API_BASE": "",
+                "PICUX_BRIDGE_API_TOKEN": "",
+                "PICUX_POLICY_ENFORCEMENT": "",
+                "PICUX_RESOLVE_OUTCOME_WEBHOOK_TOKEN": "",
+                "PICUX_BRIDGE_OUTCOME_WEBHOOK_TOKEN": "",
+                "PICUX_VAULT_KEY_B64": "",
+            }.items()
+        }
+
+        env_name = resolved["PICUX_ENV"].value.strip() or "local"
+        explicit_production = env_bool(resolved["PICUX_PRODUCTION_MODE"].value, default=False)
+        prod = explicit_production or env_name.strip().lower() in {"prod", "production", "live"}
+
+        return cls(
+            env=env_name,
+            prod=prod,
+            apiUrl=resolved["PICUX_API_BASE_URL"].value,
+            apiToken=resolved["PICUX_API_TOKEN"].value,
+            redisUrl=resolved["PICUX_REDIS_URL"].value,
+            postgresDsn=resolved["PICUX_POSTGRES_DSN"].value,
+            mcpUrl=resolved["PICUX_MCP_BASE_URL"].value,
+            mcpToken=resolved["PICUX_MCP_TOKEN"].value,
+            a2aUrl=resolved["PICUX_A2A_BASE_URL"].value,
+            a2aToken=resolved["PICUX_A2A_TOKEN"].value,
+            bridgeUrl=resolved["PICUX_BRIDGE_API_BASE"].value,
+            bridgeToken=resolved["PICUX_BRIDGE_API_TOKEN"].value,
+            policyEnforcement=env_bool(resolved["PICUX_POLICY_ENFORCEMENT"].value, default=prod),
+            resolveToken=resolved["PICUX_RESOLVE_OUTCOME_WEBHOOK_TOKEN"].value,
+            bridgeOutcomeToken=resolved["PICUX_BRIDGE_OUTCOME_WEBHOOK_TOKEN"].value,
+            vaultKey=resolved["PICUX_VAULT_KEY_B64"].value,
+            sources={name: item.source for name, item in resolved.items()},
+        )
+
+    def publicSummary(self) -> dict[str, object]:
+        return {
+            "env": self.env,
+            "prod": self.prod,
+            "api": bool(self.apiUrl),
+            "redis": bool(self.redisUrl),
+            "postgres": bool(self.postgresDsn),
+            "mcp": bool(self.mcpUrl),
+            "a2a": bool(self.a2aUrl),
+            "bridge": bool(self.bridgeUrl),
+            "policyEnforcement": self.policyEnforcement,
+            "vaultKey": bool(self.vaultKey),
+        }

picux/contracts/__init__.py

@@ -0,0 +1,22 @@
+"""Machine-readable Picux protocol contracts."""
+
+from .handshake import integrationHandshake
+from .integration import integrationManifest
+from .openapi import contractSummary, mcpTools, openapiSpec
+from .protocol_map import protocolMap, protocolMapDigest
+from .routes import ContractEndpoint, CONTRACT_ENDPOINTS
+from .schema_catalog import getSchema, schemaCatalog
+
+__all__ = [
+    "CONTRACT_ENDPOINTS",
+    "ContractEndpoint",
+    "contractSummary",
+    "getSchema",
+    "integrationHandshake",
+    "integrationManifest",
+    "mcpTools",
+    "openapiSpec",
+    "protocolMap",
+    "protocolMapDigest",
+    "schemaCatalog",
+]

picux/contracts/handshake.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+from typing import Any
+
+from picux.contracts.integration import integrationManifest
+from picux.contracts.protocol_map import protocolMapDigest
+
+
+REQUIRED_SURFACES = {
+    "agent": ("api", "a2a", "schemas"),
+    "app": ("api", "schemas"),
+    "service": ("api", "schemas"),
+}
+
+
+def integrationHandshake(payload: dict[str, Any] | None = None) -> dict[str, Any]:
+    """Validate an external caller's declared Picux integration compatibility."""
+
+    payload = payload or {}
+    manifest = integrationManifest()
+    kind = _kind(payload.get("kind", payload.get("type", "service")))
+    clientId = str(payload.get("clientId", payload.get("agentId", payload.get("appId", ""))) or "")
+    surfaces = _clean(payload.get("surfaces", []))
+    schemaIds = _clean(payload.get("schemaIds", payload.get("schemas", [])))
+    mcpTools = _clean(payload.get("mcpTools", payload.get("tools", [])))
+    domains = _clean(payload.get("domainIds", payload.get("domains", [])))
+
+    knownSurfaces = {item["id"] for item in manifest["surfaces"]}
+    knownSchemas = set(manifest["schemas"]["ids"])
+    knownTools = set(manifest["mcpTools"])
+    knownDomains = set(manifest.get("domains", {}).keys())
+    required = set(REQUIRED_SURFACES[kind])
+    acceptedSurfaces = [item for item in surfaces if item in knownSurfaces]
+    acceptedSchemas = [item for item in schemaIds if item in knownSchemas]
+    acceptedTools = [item for item in mcpTools if item in knownTools]
+    acceptedDomains = [item for item in domains if item in knownDomains]
+
+    missingSurfaces = sorted(required.difference(surfaces))
+    missingSchemas = [item for item in schemaIds if item not in knownSchemas]
+    missingTools = [item for item in mcpTools if item not in knownTools]
+    unknownDomains = [item for item in domains if item not in knownDomains]
+    unknownSurfaces = [item for item in surfaces if item not in knownSurfaces]
+    errors: list[str] = []
+    if not clientId:
+        errors.append("missing:clientId")
+    if unknownSurfaces:
+        errors.append("unknown:surfaces")
+    if missingSchemas:
+        errors.append("unknown:schemas")
+    if missingTools:
+        errors.append("unknown:mcpTools")
+    if unknownDomains:
+        errors.append("unknown:domains")
+    if missingSurfaces:
+        errors.append("missing:surfaces")
+
+    ready = not errors
+    domainCapabilities = {
+        domain: _domainCapability(manifest["domains"][domain])
+        for domain in acceptedDomains
+        if isinstance(manifest.get("domains", {}).get(domain), dict)
+    }
+    contracts = dict(manifest.get("contracts", {})) if isinstance(manifest.get("contracts"), dict) else {}
+    return {
+        "ok": ready,
+        "ready": ready,
+        "clientId": clientId,
+        "kind": kind,
+        "acceptedSurfaces": acceptedSurfaces,
+        "missingSurfaces": missingSurfaces,
+        "unknownSurfaces": unknownSurfaces,
+        "acceptedSchemas": acceptedSchemas,
+        "missingSchemas": missingSchemas,
+        "acceptedTools": acceptedTools,
+        "missingTools": missingTools,
+        "acceptedDomains": acceptedDomains,
+        "unknownDomains": unknownDomains,
+        "domainCapabilities": domainCapabilities,
+        "contracts": contracts,
+        "manifest": {"version": manifest["version"], "url": "/v1/manifest"},
+        "protocolMap": _protocolMapRef(contracts, str(manifest.get("version", "") or ""), protocolMapDigest()),
+        "errors": errors,
+    }
+
+
+def _kind(value: Any) -> str:
+    kind = str(value or "service").strip().lower()
+    return kind if kind in REQUIRED_SURFACES else "service"
+
+
+def _clean(value: Any) -> list[str]:
+    if isinstance(value, str):
+        value = [value]
+    if not isinstance(value, (list, tuple, set)):
+        return []
+    cleaned: list[str] = []
+    for item in value:
+        text = str(item or "").strip()
+        if text and text not in cleaned:
+            cleaned.append(text)
+    return cleaned
+
+
+def _domainCapability(value: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "routes": value.get("routes", []) if isinstance(value.get("routes"), list) else [],
+        "schemas": value.get("schemas", []) if isinstance(value.get("schemas"), list) else [],
+        "mcpTools": value.get("mcpTools", []) if isinstance(value.get("mcpTools"), list) else [],
+        "sdkHelpers": value.get("sdkHelpers", []) if isinstance(value.get("sdkHelpers"), list) else [],
+        "policy": value.get("policy", {}) if isinstance(value.get("policy"), dict) else {},
+        "guide": str(value.get("guide", "") or ""),
+    }
+
+
+def _protocolMapRef(contracts: dict[str, Any], version: str = "", digest: str = "") -> dict[str, str]:
+    return {
+        "url": str(contracts.get("protocolMap", "/v1/protocol-map") or "/v1/protocol-map"),
+        "version": version,
+        "digest": digest,
+        "schemaId": "protocolMap",
+        "mcpTool": "picux.protocolMap",
+    }