patchr 0.1.0__py3-none-any.whl

picux/contracts/protocol_map.py

@@ -0,0 +1,152 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any
+
+from picux.contracts.integration import integrationManifest
+from picux.contracts.routes import CONTRACT_ENDPOINTS
+
+
+CORE_DOMAINS = ("hunt", "resolve", "bridge", "channels", "cases", "pay", "proxy")
+
+
+def protocolMap() -> dict[str, Any]:
+    """Return the JSON-LD protocol map for agent-readable discovery."""
+
+    payload = _protocolMapPayload()
+    payload["digest"] = protocolMapDigest(payload)
+    return payload
+
+
+def protocolMapDigest(payload: dict[str, Any] | None = None) -> str:
+    """Return a stable digest for protocol map cache validation."""
+
+    data = dict(payload or _protocolMapPayload())
+    data.pop("digest", None)
+    raw = json.dumps(data, ensure_ascii=True, sort_keys=True, separators=(",", ":"))
+    return "sha256:" + hashlib.sha256(raw.encode("utf-8")).hexdigest()
+
+
+def _protocolMapPayload() -> dict[str, Any]:
+    manifest = integrationManifest()
+    contracts = manifest.get("contracts", {}) if isinstance(manifest.get("contracts"), dict) else {}
+    return {
+        "@context": {
+            "picux": "https://schemas.picux.io/",
+            "name": "https://schema.org/name",
+            "description": "https://schema.org/description",
+            "version": "picux:version",
+            "source": "picux:source",
+            "digest": "picux:digest",
+            "domain": "picux:domain",
+            "surface": "picux:surface",
+            "route": "picux:route",
+            "schemaId": "picux:schemaId",
+            "mcpTool": "picux:mcpTool",
+            "sdkHelper": "picux:sdkHelper",
+            "guide": "picux:guide",
+            "policy": "picux:policy",
+            "required": "picux:required",
+            "actions": "picux:actions",
+            "resource": "picux:resource",
+            "painPoint": "picux:painPoint",
+            "outcome": "picux:outcome",
+            "adoptionBlocker": "picux:adoptionBlocker",
+            "enhancement": "picux:enhancement",
+            "proofPack": "picux:proofPack",
+            "reviewProtocol": "picux:reviewProtocol",
+        },
+        "@id": "https://schemas.picux.io/protocol",
+        "@type": "picux:Protocol",
+        "name": "Picux Protocol",
+        "description": "Agentic economy infrastructure for external apps, services, and agents.",
+        "version": str(manifest.get("version", "")),
+        "source": {"name": "manifest", "route": str(contracts.get("manifest", "/v1/manifest"))},
+        "surface": _surfaces(manifest),
+        "domain": [_domainEntry(manifest["domains"][name]) for name in CORE_DOMAINS] + _supportDomains(),
+    }
+
+
+def _surfaces(manifest: dict[str, Any]) -> list[dict[str, str]]:
+    contracts = manifest.get("contracts", {}) if isinstance(manifest.get("contracts"), dict) else {}
+    return [
+        {"name": "api", "route": str(contracts.get("api", "/openapi.json"))},
+        {"name": "status", "route": "/v1/status"},
+        {"name": "manifest", "route": str(contracts.get("manifest", "/v1/manifest"))},
+        {"name": "protocolMap", "route": str(contracts.get("protocolMap", "/v1/protocol-map"))},
+        {"name": "schemas", "route": str(contracts.get("schemas", "/v1/schemas"))},
+        {"name": "mcp", "route": str(contracts.get("mcp", "/mcp"))},
+        {"name": "a2a", "route": str(contracts.get("a2a", "/v1/a2a/contract"))},
+        {"name": "benchmarks", "route": "/v1/benchmarks/local"},
+    ]
+
+
+def _domainEntry(capability: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "name": str(capability["id"]),
+        "description": str(capability["desc"]),
+        "route": [dict(route) for route in capability.get("routes", []) if isinstance(route, dict)],
+        "schemaId": list(capability.get("schemas", [])),
+        "mcpTool": list(capability.get("mcpTools", [])),
+        "sdkHelper": list(capability.get("sdkHelpers", [])),
+        "guide": str(capability.get("guide", "")),
+        "policy": capability.get("policy", {"required": False, "actions": [], "resource": ""}),
+        "painPoint": list(capability.get("painPoints", [])),
+        "outcome": list(capability.get("outcomes", [])),
+        "adoptionBlocker": list(capability.get("adoptionBlockers", [])),
+        "enhancement": list(capability.get("enhancements", [])),
+        "proofPack": str(capability.get("proofPack", "")),
+        "reviewProtocol": str(capability.get("reviewProtocol", "")),
+    }
+
+
+def _supportDomains() -> list[dict[str, Any]]:
+    return [
+        {
+            "name": "workflows",
+            "description": "Use-case-first flagship templates for Hunt, Resolve, and Proxy.",
+            "route": _routeMapsForTags(("workflows",)),
+            "schemaId": ["workflowTemplate", "proofCard", "proofPack"],
+            "mcpTool": ["picux.listWorkflowTemplates", "picux.getWorkflowTemplate", "picux.runWorkflowTemplate"],
+            "sdkHelper": ["PicuxClient.listWorkflowTemplates", "PicuxClient.getWorkflowTemplate", "PicuxClient.runWorkflowTemplate"],
+            "guide": "docs/developers/workflows.md",
+        },
+        {
+            "name": "security",
+            "description": "Mandate-session decisions, capability grants, and redacted secret-reference checks.",
+            "route": _routeMapsForPaths(("/v1/status", "/v1/security/policy/evaluate", "/v1/security/secrets/check")),
+            "schemaId": ["apiStatus", "capabilityGrant", "mandateSession", "policyDecision", "secretCheck"],
+            "mcpTool": ["picux.apiStatus", "picux.evaluatePolicy", "picux.checkSecrets"],
+            "sdkHelper": ["PicuxClient.apiStatus", "PicuxClient.evaluatePolicy", "PicuxClient.checkSecrets"],
+            "guide": "docs/developers/security.md",
+        },
+        {
+            "name": "sandbox",
+            "description": "Developer test client for the Picux Orchestrator plus deterministic benchmark traces.",
+            "route": _routeMapsForTags(("sandbox", "orchestrator")),
+            "schemaId": ["sandboxRun"],
+            "mcpTool": ["picux.runSandbox", "picux.runOrchestrator"],
+            "sdkHelper": ["PicuxClient.runSandbox", "PicuxClient.runOrchestrator", "PicuxClient.streamOrchestrator"],
+            "guide": "docs/developers/getting-started.md",
+        },
+        {
+            "name": "benchmarks",
+            "description": "Local measured evidence and public-claim labels.",
+            "route": _routeMapsForTags(("benchmarks",)),
+            "schemaId": ["benchmarkReport"],
+            "mcpTool": ["picux.runBenchmark"],
+            "sdkHelper": ["PicuxClient.runBenchmark"],
+            "guide": "docs/developers/benchmarks.md",
+        },
+    ]
+
+
+def _routeMapsForPaths(paths: tuple[str, ...]) -> list[dict[str, Any]]:
+    wanted = set(paths)
+    return [endpoint.toMap() for endpoint in CONTRACT_ENDPOINTS if endpoint.path in wanted]
+
+
+def _routeMapsForTags(tags: tuple[str, ...]) -> list[dict[str, Any]]:
+    wanted = set(tags)
+    return [endpoint.toMap() for endpoint in CONTRACT_ENDPOINTS if endpoint.tag in wanted]