patchr 0.1.0__py3-none-any.whl

picux/contracts/integration.py

@@ -0,0 +1,385 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from picux import __version__
+from picux.contracts.routes import CONTRACT_ENDPOINTS
+from picux.contracts.schema_catalog import SCHEMA_ENTRIES
+
+
+@dataclass(frozen=True)
+class IntegrationSurface:
+    id: str
+    kind: str
+    url: str
+    auth: str
+    contract: str = ""
+
+    def toMap(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "kind": self.kind,
+            "url": self.url,
+            "auth": self.auth,
+            "contract": self.contract,
+        }
+
+
+@dataclass(frozen=True)
+class EnvKey:
+    key: str
+    scope: str
+    requiredProd: bool
+    desc: str
+
+    def toMap(self) -> dict[str, Any]:
+        return {
+            "key": self.key,
+            "scope": self.scope,
+            "requiredProd": self.requiredProd,
+            "desc": self.desc,
+        }
+
+
+@dataclass(frozen=True)
+class DomainCapability:
+    id: str
+    desc: str
+    schemas: tuple[str, ...]
+    sdkHelpers: tuple[str, ...]
+    guide: str
+    policyActions: tuple[str, ...] = ()
+    policyResource: str = ""
+    policyRequired: bool = False
+    painPoints: tuple[str, ...] = ()
+    outcomes: tuple[str, ...] = ()
+    adoptionBlockers: tuple[str, ...] = ()
+    enhancements: tuple[str, ...] = ()
+    proofPack: str = ""
+    reviewProtocol: str = ""
+
+    def toMap(self, *, routes: list[dict[str, Any]], mcpTools: list[str]) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "desc": self.desc,
+            "routes": routes,
+            "schemas": list(self.schemas),
+            "mcpTools": mcpTools,
+            "sdkHelpers": list(self.sdkHelpers),
+            "guide": self.guide,
+            "policy": {
+                "required": self.policyRequired,
+                "actions": list(self.policyActions),
+                "resource": self.policyResource,
+            },
+            "painPoints": list(self.painPoints),
+            "outcomes": list(self.outcomes),
+            "adoptionBlockers": list(self.adoptionBlockers),
+            "enhancements": list(self.enhancements),
+            "proofPack": self.proofPack,
+            "reviewProtocol": self.reviewProtocol,
+        }
+
+
+SURFACES: tuple[IntegrationSurface, ...] = (
+    IntegrationSurface("api", "http", "/openapi.json", "api", "/v1/contract"),
+    IntegrationSurface("sdk", "python", "picux.sdk.PicuxClient", "api", "/v1/manifest"),
+    IntegrationSurface("mcp", "jsonRpc", "/mcp", "mcp", "/v1/contract"),
+    IntegrationSurface("a2a", "http", "/v1/a2a/envelopes", "a2a", "/v1/a2a/contract"),
+    IntegrationSurface("schemas", "jsonSchema", "/v1/schemas", "public", "/v1/schemas"),
+    IntegrationSurface("protocolMap", "jsonLd", "/v1/protocol-map", "public", "/v1/protocol-map"),
+    IntegrationSurface("workflows", "http", "/v1/workflows/templates", "api", "/v1/workflows/templates"),
+    IntegrationSurface("payAdapter", "contract", "/v1/pay/adapters/contract", "public", "/v1/pay/adapters/contract"),
+    IntegrationSurface("payRails", "http", "/v1/pay/rails", "api", "/v1/pay/rails"),
+    IntegrationSurface("payChallenges", "http", "/v1/pay/challenges", "api", "/v1/pay/challenges"),
+)
+
+
+DOMAIN_CAPABILITIES: tuple[DomainCapability, ...] = (
+    DomainCapability(
+        "hunt",
+        "Signal discovery, source attribution, monitoring, and launchable public signals.",
+        ("communitySignal", "communitySignalRecord", "proofPack", "proofCard", "workflowTemplate"),
+        ("PicuxClient.huntDiscover", "ExternalAppClient.publishSignal", "PicuxClient.createProofPack", "PicuxClient.runWorkflowTemplate"),
+        "docs/developers/domain-reference.md#hunt",
+        painPoints=(
+            "Fragmented discovery across markets, people, leads, opportunities, and evidence sources.",
+            "Continuous scam-pattern monitoring across public discussion channels and web signals.",
+            "Public-signal entity collisions and misinformation risk before launch.",
+        ),
+        outcomes=("Ranked discoveries with source attribution.", "Human-review queue for low-confidence claims."),
+        adoptionBlockers=("Opaque multi-agent discovery outputs.",),
+        enhancements=("Misinformation escalation protocol routes low-confidence claims to PROXY review.",),
+        proofPack="Completed HUNT monitoring runs can emit source snapshots and decision logs as a portable case file.",
+        reviewProtocol="Claims below the confidence threshold are routed to PROXY instead of surfaced as answers.",
+    ),
+    DomainCapability(
+        "resolve",
+        "Dispute, audit, chronology, evidence integrity, and deterministic decision support.",
+        ("proofValue", "evidenceArtifact", "vaultEvidence", "fraudSourceTaxonomy", "proofPack", "proofCard", "workflowTemplate"),
+        ("ExternalAppClient.requestResolve", "PicuxClient.resolveTask", "PicuxClient.resolveScamTriage", "PicuxClient.createProofPack", "PicuxClient.runWorkflowTemplate"),
+        "docs/developers/domain-reference.md#resolve",
+        painPoints=(
+            "Disputes, audits, and contested claims where chronology and evidence integrity matter.",
+            "Agent complaints or document inconsistencies that need defensible outcomes.",
+            "Trust-sensitive decisions where automation must remain auditable and human-readable.",
+        ),
+        outcomes=("Chronology-aware claim drafts and decisions.", "Portable proof pack for defending outcomes later."),
+        adoptionBlockers=("Multi-agent systems can feel opaque unless outputs are tightly audited.",),
+        enhancements=("Auto-Audit Vault stores source snapshots, decision logs, complaint evidence, source classes, and fraud indicators.",),
+        proofPack="RESOLVE outcomes should close with a shareable proof pack: from opaque workflow to portable case file.",
+        reviewProtocol="Low-confidence or regulated-life-decision claims can suspend into PROXY for human review.",
+    ),
+    DomainCapability(
+        "bridge",
+        "External connector registry, scoped credentials, preflight, MCP, and A2A handoffs.",
+        (
+            "bridgeConnector",
+            "bridgeConnectionSession",
+            "bridgePreflight",
+            "credentialScope",
+            "providerAction",
+            "providerCallback",
+            "portalSession",
+            "portalSessionPreflight",
+            "portalAction",
+            "portalActionTemplate",
+            "portalPlaybook",
+            "portalStep",
+            "portalProof",
+            "a2aEnvelope",
+            "a2aEnvelopeRecord",
+        ),
+        (
+            "PicuxClient.registerConnector",
+            "PicuxClient.createBridgeConnectionSession",
+            "PicuxClient.matchConnectors",
+            "PicuxClient.preflightConnector",
+            "PicuxClient.preflightConnectorPaid",
+            "PicuxClient.createBridgeAction",
+            "PicuxClient.runBridgeAction",
+            "PicuxClient.updateBridgeAction",
+            "PicuxClient.createPortalSession",
+            "PicuxClient.preflightPortalSession",
+            "PicuxClient.listPortalActionTemplates",
+            "PicuxClient.getPortalActionTemplate",
+            "PicuxClient.listPortalPlaybooks",
+            "PicuxClient.getPortalPlaybook",
+            "PicuxClient.instantiatePortalPlaybook",
+            "PicuxClient.runPortalAction",
+        ),
+        "docs/developers/bridge-connectors.md",
+        ("bridge.<action>",),
+        "payload.resource or connector scope resource",
+        True,
+    ),
+    DomainCapability(
+        "channels",
+        "Durable conversation state across email, chat, messaging apps, telephony, CRM callbacks, and adapter actions.",
+        ("channelThread", "channelTimeline", "touchpoint", "providerAction", "providerCallback", "providerCaseSync", "channelState"),
+        (
+            "PicuxClient.createChannelThread",
+            "PicuxClient.channelThreadTimeline",
+            "PicuxClient.recordTouchpoint",
+            "PicuxClient.ingestProviderCallback",
+            "PicuxClient.listTouchpoints",
+        ),
+        "docs/developers/channelGuide.md",
+        painPoints=(
+            "Conversation state fragmented across email, chat, calls, CRM records, and webhooks.",
+            "Provider callbacks need to resume the correct Picux conversation and case.",
+            "Developers need inspectable inbound/outbound traces for every channel touchpoint.",
+        ),
+        outcomes=("Provider callbacks reconcile into one channel thread.", "Touchpoints can be exported into case evidence bundles."),
+        adoptionBlockers=("Deep integrations become hard to trust when provider IDs are not source-bound.",),
+        enhancements=("Channel threads bind provider thread IDs, Picux conversation IDs, case IDs, and proof artifacts."),
+        proofPack="Touchpoints become evidence-ready source records for Resolve and Proxy case workspaces.",
+    ),
+    DomainCapability(
+        "cases",
+        "Formal dispute and audit workspaces with stakeholders, deadlines, timelines, evidence refs, collaboration, and portable bundle exports.",
+        ("caseWorkspace", "caseStakeholder", "caseDeadline", "caseAction", "caseEvent", "caseNote", "caseBundleDocument", "evidenceBundle", "proofPack", "touchpoint"),
+        (
+            "PicuxClient.createCase",
+            "PicuxClient.addCaseStakeholder",
+            "PicuxClient.addCaseDeadline",
+            "PicuxClient.reviewCaseDeadlines",
+            "PicuxClient.addCaseAction",
+            "PicuxClient.listCaseActions",
+            "PicuxClient.updateCaseAction",
+            "PicuxClient.addCaseNote",
+            "PicuxClient.listCaseNotes",
+            "PicuxClient.addCaseEvidence",
+            "PicuxClient.exportCaseBundle",
+        ),
+        "docs/developers/caseGuide.md",
+        painPoints=(
+            "Complex disputes scatter evidence across documents, calls, chats, and provider portals.",
+            "Deadlines and stakeholder accountability are easy to lose in automation-only logs.",
+            "Operators need a shareable record that can defend the outcome later.",
+        ),
+        outcomes=("Portable case file.", "Deadline-aware status timeline.", "Stakeholder collaboration record."),
+        adoptionBlockers=("Evidence-rich users need exportable proof, not just internal logs.",),
+        enhancements=("Every Resolve or Proxy workflow can attach to a case workspace and export an evidence bundle."),
+        proofPack="Case exports turn touchpoints, proof packs, deadlines, and decisions into a portable case file.",
+    ),
+    DomainCapability(
+        "pay",
+        "Payment-as-auth challenges, bounded sessions, mandates, escrow records, receipts, and adapter contracts.",
+        (
+            "payRail",
+            "paymentChallenge",
+            "paymentCredential",
+            "paymentSession",
+            "usageMandate",
+            "procurementMandate",
+            "paymentMandate",
+            "mandateRecord",
+            "escrowMission",
+            "disputeCase",
+            "reputationCard",
+            "settlementAdapter",
+            "settlementInstruction",
+            "escrowRecord",
+            "settlementReceipt",
+        ),
+        (
+            "PicuxClient.listPayRails",
+            "PicuxClient.listPayAdapters",
+            "PicuxClient.getPayAdapter",
+            "PicuxClient.invokePayAdapter",
+            "PicuxClient.initEscrowMission",
+            "PicuxClient.settleEscrowMission",
+            "PicuxClient.abortEscrowMission",
+            "PicuxClient.listReputationCards",
+            "PicuxClient.updateReputationCard",
+            "PicuxClient.createPaymentChallenge",
+            "PicuxClient.verifyPaymentChallenge",
+            "PicuxClient.createPaymentSession",
+            "PicuxClient.consumePaymentSession",
+            "PicuxClient.localPaymentCredential",
+            "PicuxClient.payFetch",
+            "PicuxClient.createMandate",
+            "PicuxClient.fundEscrow",
+            "PicuxClient.submitEscrowProof",
+            "PicuxClient.settleEscrow",
+            "PicuxClient.refundEscrow",
+            "PicuxClient.disputeEscrow",
+            "PicuxClient.prepareSettlement",
+            "PicuxClient.settle",
+        ),
+        "docs/developers/pay-guide.md",
+        ("pay.challenge", "pay.session", "pay.adapter", "pay.prepare", "pay.settle"),
+        "escrow:<escrowId> or mandate:<mandateId>",
+        True,
+        painPoints=(
+            "API-key and account setup friction for machine-to-machine resource use.",
+            "High-frequency microtransactions that are too small for human-centric billing.",
+            "Irreversible autonomous purchases that need proof-gated settlement and dispute paths.",
+        ),
+        outcomes=("Payment-authenticated resource access.", "Bounded spending sessions.", "Proof-backed receipts and escrow gates."),
+        adoptionBlockers=("Agent spending needs clear limits before developers and users trust it.",),
+        enhancements=("PAY v2 adds 402 challenges, usage mandates, MPP sessions, escrow missions, and reputation cards.",),
+        proofPack="PAY receipts and escrow outcomes link payment, mandate, proof artifact, and settlement status.",
+        reviewProtocol="Tier 3 spending and disputed settlements suspend into PROXY for explicit human arbitration.",
+    ),
+    DomainCapability(
+        "proxy",
+        "Human intervention for oversight, physical logistics, subjective judgment, proof, and Resolve resume.",
+        ("proxyMission", "proxyBrief", "proxyOutcome", "proxyProof", "proxyRoute", "channelMsg", "voiceCall", "caseOpsTimeline", "proofPack", "proofCard", "workflowTemplate"),
+        (
+            "ExternalAppClient.requestProxy",
+            "ExternalAppClient.submitProxy",
+            "PicuxClient.createProxyMission",
+            "PicuxClient.submitProxyOutcomeByRef",
+            "PicuxClient.createProofPack",
+            "PicuxClient.runWorkflowTemplate",
+        ),
+        "docs/developers/proxy-guide.md",
+        ("proxy.request", "proxy.submit"),
+        "explicit resource, proxy:<proxyId>, task:<taskId>, or proxy:missions",
+        True,
+        painPoints=(
+            "Human logistics coordination across multiple actors, documents, and status changes.",
+            "Escalations to consultants, legal review, or document verification.",
+            "Voice, chat, and physical proof collection before Resolve or PAY can continue.",
+        ),
+        outcomes=("Suspend/resume mission state.", "Verified human outcome proof.", "Shareable workflow proof pack."),
+        adoptionBlockers=("Trust-sensitive users may worry about automation making the wrong call.",),
+        enhancements=("Human review routes make low-confidence claims explicit instead of hidden in agent output.",),
+        proofPack="Every completed PROXY workflow can emit a shareable proof pack for operators and reviewers.",
+        reviewProtocol="PROXY is the default misinformationEscalation route for human review and mission-critical ambiguity.",
+    ),
+)
+
+
+ENV_KEYS: tuple[EnvKey, ...] = (
+    EnvKey("PICUX_API_BASE_URL", "api", True, "Base URL for HTTP API and SDK clients."),
+    EnvKey("PICUX_API_TOKEN", "api", True, "Bearer token for protected API routes."),
+    EnvKey("PICUX_MCP_BASE_URL", "mcp", True, "Base URL for MCP JSON-RPC clients."),
+    EnvKey("PICUX_MCP_TOKEN", "mcp", True, "Bearer token for MCP JSON-RPC calls."),
+    EnvKey("PICUX_A2A_BASE_URL", "a2a", True, "Base URL for A2A envelope transport."),
+    EnvKey("PICUX_A2A_TOKEN", "a2a", True, "Bearer token for A2A envelope transport."),
+    EnvKey("PICUX_POSTGRES_DSN", "storage", True, "Postgres DSN for durable protocol state."),
+    EnvKey("PICUX_REDIS_URL", "cache", True, "Redis URL for runtime coordination."),
+    EnvKey("PICUX_ENV", "runtime", False, "Runtime environment label."),
+    EnvKey("PICUX_PRODUCTION_MODE", "runtime", False, "Fail-closed production-mode switch."),
+)
+
+
+def integrationManifest() -> dict[str, Any]:
+    """Return the compact integration contract for external builders."""
+
+    tools = [endpoint.mcpTool for endpoint in CONTRACT_ENDPOINTS if endpoint.mcpTool]
+    routes = [endpoint.toMap() for endpoint in CONTRACT_ENDPOINTS]
+    schemaIds = [entry.schemaId for entry in SCHEMA_ENTRIES]
+    domains = _domainMap()
+    return {
+        "ok": True,
+        "name": "picux",
+        "version": __version__,
+        "kind": "agenticEconomyInfra",
+        "surfaces": [surface.toMap() for surface in SURFACES],
+        "auth": {
+            "api": {"type": "bearer", "env": "PICUX_API_TOKEN"},
+            "mcp": {"type": "bearer", "env": "PICUX_MCP_TOKEN", "fallback": "PICUX_API_TOKEN"},
+            "a2a": {"type": "bearer", "env": "PICUX_A2A_TOKEN", "fallback": "PICUX_API_TOKEN"},
+            "public": {"type": "none"},
+        },
+        "env": [item.toMap() for item in ENV_KEYS],
+        "sdk": {
+            "python": {
+                "client": "picux.sdk.PicuxClient",
+                "transport": "picux.sdk.HttpTransport",
+                "env": ["PICUX_API_BASE_URL", "PICUX_API_TOKEN"],
+            }
+        },
+        "contracts": {
+            "api": "/openapi.json",
+            "summary": "/v1/contract",
+            "manifest": "/v1/manifest",
+            "protocolMap": "/v1/protocol-map",
+            "mcp": "/mcp",
+            "a2a": "/v1/a2a/contract",
+            "schemas": "/v1/schemas",
+        },
+        "schemas": {
+            "catalog": "/v1/schemas",
+            "ids": schemaIds,
+        },
+        "domains": domains,
+        "mcpTools": tools,
+        "routes": routes,
+    }
+
+
+def _domainMap() -> dict[str, Any]:
+    out: dict[str, Any] = {}
+    for capability in DOMAIN_CAPABILITIES:
+        endpoints = [endpoint for endpoint in CONTRACT_ENDPOINTS if endpoint.tag == capability.id]
+        out[capability.id] = capability.toMap(
+            routes=[endpoint.toMap() for endpoint in endpoints],
+            mcpTools=[str(endpoint.mcpTool) for endpoint in endpoints if endpoint.mcpTool],
+        )
+    return out

picux/contracts/openapi.py

@@ -0,0 +1,187 @@
+from __future__ import annotations
+
+from typing import Any
+
+from picux import __version__
+from picux.contracts.routes import CONTRACT_ENDPOINTS, ContractEndpoint
+
+
+def openapiSpec() -> dict[str, Any]:
+    paths: dict[str, Any] = {}
+    for endpoint in CONTRACT_ENDPOINTS:
+        paths.setdefault(endpoint.path, {})[endpoint.method.lower()] = _operation(endpoint)
+    return {
+        "openapi": "3.1.0",
+        "info": {
+            "title": "Picux Protocol API",
+            "version": __version__,
+            "summary": "Agentic economy infrastructure contract for external apps, services, and agents.",
+        },
+        "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
+        "servers": [{"url": "http://127.0.0.1:8088", "description": "Local development"}],
+        "tags": _tags(),
+        "paths": paths,
+        "components": {
+            "schemas": {
+                "AnyObject": {"type": "object", "additionalProperties": True},
+                "Ok": {
+                    "type": "object",
+                    "required": ["ok"],
+                    "properties": {"ok": {"type": "boolean"}},
+                    "additionalProperties": True,
+                },
+                "Error": {
+                    "type": "object",
+                    "required": ["ok", "error"],
+                    "properties": {"ok": {"const": False}, "error": {"type": "string"}},
+                    "additionalProperties": True,
+                },
+            },
+            "securitySchemes": {
+                "bearerAuth": {
+                    "type": "http",
+                    "scheme": "bearer",
+                }
+            },
+        },
+        "security": [{"bearerAuth": []}],
+    }
+
+
+def contractSummary() -> dict[str, Any]:
+    return {
+        "ok": True,
+        "name": "picux",
+        "version": __version__,
+        "contracts": {
+            "api": "/openapi.json",
+            "manifest": "/v1/manifest",
+            "protocolMap": "/v1/protocol-map",
+            "mcp": "/v1/contract",
+        },
+        "endpoints": [endpoint.toMap() for endpoint in CONTRACT_ENDPOINTS],
+        "mcpTools": mcpTools(),
+    }
+
+
+def mcpTools() -> list[dict[str, Any]]:
+    tools = []
+    for endpoint in CONTRACT_ENDPOINTS:
+        if not endpoint.mcpTool:
+            continue
+        tools.append(
+            {
+                "name": endpoint.mcpTool,
+                "description": endpoint.desc,
+                "inputSchema": {
+                    "type": "object",
+                    "additionalProperties": True,
+                },
+            }
+        )
+    return tools
+
+
+def _operation(endpoint: ContractEndpoint) -> dict[str, Any]:
+    operation: dict[str, Any] = {
+        "operationId": endpoint.opId,
+        "summary": endpoint.desc,
+        "tags": [endpoint.tag],
+        "responses": {
+            "200": {
+                "description": "Picux response",
+                "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Ok"}}},
+            },
+            "404": {
+                "description": "Not found",
+                "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}},
+            },
+        },
+    }
+    params = _pathParams(endpoint.path)
+    if params:
+        operation["parameters"] = params
+    if endpoint.method == "POST":
+        operation["requestBody"] = {
+            "required": False,
+            "content": {
+                "application/json": {
+                    "schema": {"$ref": "#/components/schemas/AnyObject"},
+                }
+            },
+        }
+    return operation
+
+
+def _pathParams(path: str) -> list[dict[str, Any]]:
+    params: list[dict[str, Any]] = []
+    for name in (
+        "taskId",
+        "mandateId",
+        "receiptId",
+        "artifactId",
+        "povId",
+        "packId",
+        "agentId",
+        "connectorId",
+        "proxyId",
+        "escrowId",
+        "railId",
+        "challengeId",
+        "resourceId",
+        "adapterId",
+        "cardId",
+        "schemaId",
+        "msgId",
+        "signalId",
+        "eventId",
+        "subId",
+        "deliveryId",
+        "templateId",
+        "sessionId",
+        "threadId",
+        "touchpointId",
+        "actionId",
+        "caseId",
+        "portalSessionId",
+        "portalActionId",
+    ):
+        if "{" + name + "}" in path:
+            params.append(
+                {
+                    "name": name,
+                    "in": "path",
+                    "required": True,
+                    "schema": {"type": "string"},
+                }
+            )
+    return params
+
+
+def _tags() -> list[dict[str, str]]:
+    labels = {
+        "runtime": "Runtime health and configuration.",
+        "contract": "Machine-readable Picux contracts.",
+        "mcp": "MCP JSON-RPC transport for external agents.",
+        "a2a": "Agent-to-agent envelope contracts.",
+        "security": "Policy evaluation for mandate sessions and capability grants.",
+        "sandbox": "Deterministic benchmark traces for developer playgrounds.",
+        "orchestrator": "Live developer orchestration across Picux domains.",
+        "benchmarks": "Local benchmark evidence and claim labels.",
+        "agents": "Agent lifecycle and capability discovery.",
+        "tasks": "Task lifecycle.",
+        "cases": "Formal case workspaces, deadlines, stakeholders, timelines, and evidence bundle exports.",
+        "workflows": "Use-case-first workflow templates.",
+        "hunt": "Discovery and telemetry ranking.",
+        "resolve": "Resolve decisions and evidence.",
+        "bridge": "External connector registry, scope, and preflight contracts.",
+        "channels": "Persistent conversation state across provider touchpoints.",
+        "proxy": "Human-in-the-loop suspend and resume contracts.",
+        "mandates": "Mandate registration and verification.",
+        "pay": "PAY settlement and receipts.",
+        "audit": "Evidence, proof-of-value, and receipt verification.",
+        "signals": "Community signal ingestion and task launch.",
+        "events": "External integration event outbox, subscriptions, and delivery attempts.",
+    }
+    used = dict.fromkeys(endpoint.tag for endpoint in CONTRACT_ENDPOINTS)
+    return [{"name": tag, "description": labels.get(tag, "")} for tag in used]