patchr 0.1.0__py3-none-any.whl

picux/contracts/schema_catalog.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+@dataclass(frozen=True)
+class SchemaEntry:
+    schemaId: str
+    path: str
+    domain: str
+
+    def toMap(self) -> dict[str, Any]:
+        schema = _readSchema(self.path)
+        return {
+            "schemaId": self.schemaId,
+            "path": self.path,
+            "domain": self.domain,
+            "title": str(schema.get("title", self.schemaId) or self.schemaId),
+            "schemaUrl": str(schema.get("$id", "") or ""),
+        }
+
+
+SCHEMA_ENTRIES: tuple[SchemaEntry, ...] = (
+    SchemaEntry("agentCard", "schemas/agents/agent-card.schema.json", "agents"),
+    SchemaEntry("apiStatus", "schemas/runtime/api-status.schema.json", "runtime"),
+    SchemaEntry("benchmarkReport", "schemas/benchmarks/local-benchmark-report.schema.json", "benchmarks"),
+    SchemaEntry("caseAction", "schemas/cases/case-action.schema.json", "cases"),
+    SchemaEntry("caseDeadline", "schemas/cases/case-deadline.schema.json", "cases"),
+    SchemaEntry("caseBundleDocument", "schemas/cases/case-bundle-document.schema.json", "cases"),
+    SchemaEntry("caseEvent", "schemas/cases/case-event.schema.json", "cases"),
+    SchemaEntry("caseNote", "schemas/cases/case-note.schema.json", "cases"),
+    SchemaEntry("caseStakeholder", "schemas/cases/case-stakeholder.schema.json", "cases"),
+    SchemaEntry("caseWorkspace", "schemas/cases/case-workspace.schema.json", "cases"),
+    SchemaEntry("bridgeConnector", "schemas/connectors/bridge-connector.schema.json", "connectors"),
+    SchemaEntry("bridgeConnectionSession", "schemas/connectors/bridge-connection-session.schema.json", "connectors"),
+    SchemaEntry("bridgePreflight", "schemas/connectors/bridge-preflight.schema.json", "connectors"),
+    SchemaEntry("channelState", "schemas/channels/channel-state.schema.json", "channels"),
+    SchemaEntry("channelTimeline", "schemas/channels/channel-timeline.schema.json", "channels"),
+    SchemaEntry("channelThread", "schemas/channels/channel-thread.schema.json", "channels"),
+    SchemaEntry("providerAction", "schemas/channels/provider-action.schema.json", "channels"),
+    SchemaEntry("providerCaseSync", "schemas/channels/provider-case-sync.schema.json", "channels"),
+    SchemaEntry("providerCallback", "schemas/channels/provider-callback.schema.json", "channels"),
+    SchemaEntry("touchpoint", "schemas/channels/touchpoint.schema.json", "channels"),
+    SchemaEntry("capabilityGrant", "schemas/security/capability-grant.schema.json", "security"),
+    SchemaEntry("credentialScope", "schemas/connectors/credential-scope.schema.json", "connectors"),
+    SchemaEntry("evidenceBundle", "schemas/cases/evidence-bundle.schema.json", "cases"),
+    SchemaEntry("integrationHandshake", "schemas/contracts/integration-handshake.schema.json", "contract"),
+    SchemaEntry("integrationManifest", "schemas/contracts/integration-manifest.schema.json", "contract"),
+    SchemaEntry("protocolMap", "schemas/contracts/protocol-map.schema.json", "contract"),
+    SchemaEntry("evidenceArtifact", "schemas/audit/evidence-artifact.schema.json", "audit"),
+    SchemaEntry("fraudSourceTaxonomy", "schemas/audit/fraud-source-taxonomy.schema.json", "audit"),
+    SchemaEntry("proofValue", "schemas/audit/proof-of-value.schema.json", "audit"),
+    SchemaEntry("proofCard", "schemas/audit/proof-card.schema.json", "audit"),
+    SchemaEntry("proofPack", "schemas/audit/proof-pack.schema.json", "audit"),
+    SchemaEntry("vaultEvidence", "schemas/audit/vault-evidence.schema.json", "audit"),
+    SchemaEntry("workflowTemplate", "schemas/workflows/workflow-template.schema.json", "workflows"),
+    SchemaEntry("caseOpsTimeline", "schemas/proxy/case-ops-timeline.schema.json", "proxy"),
+    SchemaEntry("proxyMission", "schemas/proxy/proxy-mission.schema.json", "proxy"),
+    SchemaEntry("proxyBrief", "schemas/proxy/proxy-brief.schema.json", "proxy"),
+    SchemaEntry("proxyOutcome", "schemas/proxy/proxy-outcome.schema.json", "proxy"),
+    SchemaEntry("proxyProof", "schemas/proxy/proxy-proof.schema.json", "proxy"),
+    SchemaEntry("proxyRoute", "schemas/proxy/proxy-route.schema.json", "proxy"),
+    SchemaEntry("channelMsg", "schemas/proxy/channel-msg.schema.json", "proxy"),
+    SchemaEntry("voiceCall", "schemas/proxy/voice-call.schema.json", "proxy"),
+    SchemaEntry("communitySignal", "schemas/events/community-signal.schema.json", "signals"),
+    SchemaEntry("communitySignalRecord", "schemas/events/community-signal-record.schema.json", "signals"),
+    SchemaEntry("integrationEvent", "schemas/events/integration-event.schema.json", "events"),
+    SchemaEntry("eventSubscription", "schemas/events/event-subscription.schema.json", "events"),
+    SchemaEntry("eventDelivery", "schemas/events/event-delivery.schema.json", "events"),
+    SchemaEntry("mandateRecord", "schemas/mandates/mandate-record.schema.json", "mandates"),
+    SchemaEntry("paymentMandate", "schemas/mandates/payment.schema.json", "mandates"),
+    SchemaEntry("procurementMandate", "schemas/mandates/procurement.schema.json", "mandates"),
+    SchemaEntry("payRail", "schemas/pay/pay-rail.schema.json", "pay"),
+    SchemaEntry("paymentChallenge", "schemas/pay/payment-challenge.schema.json", "pay"),
+    SchemaEntry("paymentCredential", "schemas/pay/payment-credential.schema.json", "pay"),
+    SchemaEntry("paymentSession", "schemas/pay/payment-session.schema.json", "pay"),
+    SchemaEntry("portalAction", "schemas/portals/portal-action.schema.json", "portals"),
+    SchemaEntry("portalActionTemplate", "schemas/portals/portal-action-template.schema.json", "portals"),
+    SchemaEntry("portalProof", "schemas/portals/portal-proof.schema.json", "portals"),
+    SchemaEntry("portalPlaybook", "schemas/portals/portal-playbook.schema.json", "portals"),
+    SchemaEntry("portalSession", "schemas/portals/portal-session.schema.json", "portals"),
+    SchemaEntry("portalSessionPreflight", "schemas/portals/portal-session-preflight.schema.json", "portals"),
+    SchemaEntry("portalStep", "schemas/portals/portal-step.schema.json", "portals"),
+    SchemaEntry("usageMandate", "schemas/pay/usage-mandate.schema.json", "pay"),
+    SchemaEntry("escrowMission", "schemas/pay/escrow-mission.schema.json", "pay"),
+    SchemaEntry("disputeCase", "schemas/pay/dispute-case.schema.json", "pay"),
+    SchemaEntry("reputationCard", "schemas/pay/reputation-card.schema.json", "pay"),
+    SchemaEntry("escrowRecord", "schemas/pay/escrow-record.schema.json", "pay"),
+    SchemaEntry("settlementAdapter", "schemas/pay/settlement-adapter.schema.json", "pay"),
+    SchemaEntry("settlementInstruction", "schemas/pay/settlement-instruction.schema.json", "pay"),
+    SchemaEntry("a2aEnvelope", "schemas/protocols/a2a-envelope.schema.json", "a2a"),
+    SchemaEntry("a2aEnvelopeRecord", "schemas/protocols/a2a-envelope-record.schema.json", "a2a"),
+    SchemaEntry("settlementReceipt", "schemas/receipts/settlement-receipt.schema.json", "receipts"),
+    SchemaEntry("mandateSession", "schemas/security/mandate-session.schema.json", "security"),
+    SchemaEntry("policyDecision", "schemas/security/policy-decision.schema.json", "security"),
+    SchemaEntry("secretCheck", "schemas/security/secret-check.schema.json", "security"),
+    SchemaEntry("sandboxRun", "schemas/sandbox/midnight-arbitrage-run.schema.json", "sandbox"),
+    SchemaEntry("protocolTask", "schemas/tasks/protocol-task.schema.json", "tasks"),
+)
+
+
+def schemaCatalog() -> dict[str, Any]:
+    entries = [entry.toMap() for entry in SCHEMA_ENTRIES]
+    return {"ok": True, "schemas": entries, "count": len(entries)}
+
+
+def getSchema(schemaId: str) -> dict[str, Any]:
+    requested = str(schemaId or "")
+    entry = next((item for item in SCHEMA_ENTRIES if item.schemaId == requested), None)
+    if entry is None:
+        return {"ok": False, "error": "schemaNotFound", "schemaId": requested}
+    return {"ok": True, "schemaId": entry.schemaId, "schema": _readSchema(entry.path), "meta": entry.toMap()}
+
+
+def _readSchema(path: str) -> dict[str, Any]:
+    raw = (_repoRoot() / path).read_text(encoding="utf-8")
+    value = json.loads(raw)
+    return value if isinstance(value, dict) else {}
+
+
+def _repoRoot() -> Path:
+    return Path(__file__).resolve().parents[3]

picux/core/__init__.py

@@ -0,0 +1,17 @@
+"""Core Picux runtime primitives."""
+
+from .models import Domain, ProtocolTask, ProtocolTaskStatus, ProtocolUser
+from .router import PicuxIntentRouter, RouteDecision
+from .runtime import PicuxRuntime
+from .state_machine import PicuxStateMachine
+
+__all__ = [
+    "PicuxIntentRouter",
+    "PicuxRuntime",
+    "PicuxStateMachine",
+    "Domain",
+    "ProtocolTask",
+    "ProtocolTaskStatus",
+    "ProtocolUser",
+    "RouteDecision",
+]

picux/core/models.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Optional
+
+
+class Domain(str, Enum):
+    HUNT = "hunt"
+    RESOLVE = "resolve"
+    BRIDGE = "bridge"
+    PAY = "pay"
+    PROXY = "proxy"
+    SIGNALS = "signals"
+    AUDIT = "audit"
+    UNKNOWN = "unknown"
+
+
+class ProtocolTaskStatus(str, Enum):
+    PENDING = "pending"
+    PROCESSING = "processing"
+    AWAITING_PROXY = "awaitingProxy"
+    NEEDS_APPROVAL = "needs_approval"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELED = "canceled"
+    FROZEN = "frozen"
+
+
+def _to_int(raw: Any, default: int = 0) -> int:
+    try:
+        return int(raw)
+    except Exception:
+        return default
+
+
+def _to_bool(raw: Any) -> bool:
+    return str(raw).strip().lower() in {"1", "true", "yes", "on"}
+
+
+def _json_loads(raw: Any, default: Any) -> Any:
+    if raw in ("", None):
+        return default
+    try:
+        return json.loads(str(raw))
+    except Exception:
+        return default
+
+
+@dataclass
+class ProtocolUser:
+    userId: str
+    channel: str = "api"
+    trust: int = 1
+    refs: dict[str, str] = field(default_factory=dict)
+    prefs: dict[str, Any] = field(default_factory=dict)
+    meta: dict[str, Any] = field(default_factory=dict)
+    createdAt: int = field(default_factory=lambda: int(time.time()))
+    updatedAt: int = field(default_factory=lambda: int(time.time()))
+
+    def toMap(self) -> dict[str, str]:
+        return {
+            "userId": self.userId,
+            "channel": self.channel,
+            "trust": str(self.trust),
+            "refs": json.dumps(self.refs, ensure_ascii=True, sort_keys=True),
+            "prefs": json.dumps(self.prefs, ensure_ascii=True, sort_keys=True),
+            "meta": json.dumps(self.meta, ensure_ascii=True, sort_keys=True),
+            "createdAt": str(self.createdAt),
+            "updatedAt": str(self.updatedAt),
+        }
+
+    @classmethod
+    def fromMap(cls, data: dict[str, Any]) -> "ProtocolUser":
+        return cls(
+            userId=str(data.get("userId", "")),
+            channel=str(data.get("channel", "api") or "api"),
+            trust=_to_int(data.get("trust", 1), 1),
+            refs=_json_loads(data.get("refs"), {}),
+            prefs=_json_loads(data.get("prefs"), {}),
+            meta=_json_loads(data.get("meta"), {}),
+            createdAt=_to_int(data.get("createdAt", 0), 0),
+            updatedAt=_to_int(data.get("updatedAt", 0), 0),
+        )
+
+
+@dataclass
+class ProtocolTask:
+    taskId: str
+    userId: str
+    domain: Domain
+    status: ProtocolTaskStatus
+    channel: str = "api"
+    inData: dict[str, Any] = field(default_factory=dict)
+    outData: dict[str, Any] = field(default_factory=dict)
+    needsApproval: bool = False
+    mandateId: str = ""
+    extRef: str = ""
+    errorMsg: str = ""
+    meta: dict[str, Any] = field(default_factory=dict)
+    createdAt: int = field(default_factory=lambda: int(time.time()))
+    updatedAt: int = field(default_factory=lambda: int(time.time()))
+    approvalBy: Optional[int] = None
+
+    def toMap(self) -> dict[str, str]:
+        return {
+            "taskId": self.taskId,
+            "userId": self.userId,
+            "domain": self.domain.value,
+            "status": self.status.value,
+            "channel": self.channel,
+            "inData": json.dumps(self.inData, ensure_ascii=True, sort_keys=True),
+            "outData": json.dumps(self.outData, ensure_ascii=True, sort_keys=True),
+            "needsApproval": "1" if self.needsApproval else "0",
+            "mandateId": self.mandateId,
+            "extRef": self.extRef,
+            "errorMsg": self.errorMsg,
+            "meta": json.dumps(self.meta, ensure_ascii=True, sort_keys=True),
+            "createdAt": str(self.createdAt),
+            "updatedAt": str(self.updatedAt),
+            "approvalBy": "" if self.approvalBy is None else str(self.approvalBy),
+        }
+
+    @classmethod
+    def fromMap(cls, data: dict[str, Any]) -> "ProtocolTask":
+        domain = str(data.get("domain", Domain.UNKNOWN.value))
+        status = str(data.get("status", ProtocolTaskStatus.PENDING.value))
+        return cls(
+            taskId=str(data.get("taskId", "")),
+            userId=str(data.get("userId", "")),
+            domain=Domain(domain) if domain in Domain._value2member_map_ else Domain.UNKNOWN,
+            status=ProtocolTaskStatus(status)
+            if status in ProtocolTaskStatus._value2member_map_
+            else ProtocolTaskStatus.PENDING,
+            channel=str(data.get("channel", "api") or "api"),
+            inData=_json_loads(data.get("inData"), {}),
+            outData=_json_loads(data.get("outData"), {}),
+            needsApproval=_to_bool(data.get("needsApproval", "0")),
+            mandateId=str(data.get("mandateId", "")),
+            extRef=str(data.get("extRef", "")),
+            errorMsg=str(data.get("errorMsg", "")),
+            meta=_json_loads(data.get("meta"), {}),
+            createdAt=_to_int(data.get("createdAt", 0), 0),
+            updatedAt=_to_int(data.get("updatedAt", 0), 0),
+            approvalBy=_to_int(data.get("approvalBy", ""), 0) or None,
+        )

picux/core/router.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from picux.core.models import Domain
+
+
+@dataclass(frozen=True)
+class RouteDecision:
+    domain: Domain
+    reason: str
+
+
+class PicuxIntentRouter:
+    """Deterministic scaffold router for Picux protocol domains."""
+
+    resolve_keywords = {
+        "invoice",
+        "bill",
+        "fee",
+        "refund",
+        "dispute",
+        "claim",
+        "complaint",
+        "damaged",
+        "broken",
+        "defective",
+        "in-transit",
+        "in transit",
+        "transit",
+        "followup",
+        "follow up",
+        "customer representative",
+        "overcharge",
+        "sla",
+        "cancel subscription",
+        "processing fee",
+        "regulatory recovery",
+        "evidence",
+        "verification",
+    }
+    bridge_keywords = {
+        "api",
+        "webhook",
+        "erp",
+        "connector",
+        "integration",
+        "slack",
+        "whatsapp",
+        "email",
+        "mcp",
+        "a2a",
+    }
+    proxy_keywords = {
+        "pick up",
+        "pickup",
+        "physically",
+        "physical",
+        "drop off",
+        "courier",
+        "runner",
+        "deliver",
+        "errand",
+        "human",
+        "human review",
+        "oversight",
+        "field",
+        "call",
+        "phone",
+        "subjective",
+    }
+    pay_keywords = {
+        "mandate",
+        "escrow",
+        "settle",
+        "settlement",
+        "payment",
+        "pay",
+        "receipt",
+        "proof of value",
+    }
+    signal_keywords = {
+        "reddit",
+        "community",
+        "public signal",
+        "signals",
+        "harness",
+        "swarm core",
+    }
+    hunt_keywords = {
+        "zillow",
+        "redfin",
+        "ebay",
+        "amazon",
+        "listing",
+        "price drop",
+        "deal",
+        "hunt",
+        "under $",
+        "arbitrage",
+        "vendor",
+    }
+
+    def classify(self, query: str) -> RouteDecision:
+        text = (query or "").strip().lower()
+        if not text:
+            return RouteDecision(Domain.UNKNOWN, "empty_query")
+        if _matchesAny(text, self.pay_keywords):
+            return RouteDecision(Domain.PAY, "pay_keyword_match")
+        if _matchesAny(text, self.resolve_keywords):
+            return RouteDecision(Domain.RESOLVE, "resolve_keyword_match")
+        if _matchesAny(text, self.proxy_keywords):
+            return RouteDecision(Domain.PROXY, "proxy_keyword_match")
+        if _matchesAny(text, self.bridge_keywords):
+            return RouteDecision(Domain.BRIDGE, "bridge_keyword_match")
+        if _matchesAny(text, self.signal_keywords):
+            return RouteDecision(Domain.SIGNALS, "signal_keyword_match")
+        if _matchesAny(text, self.hunt_keywords):
+            return RouteDecision(Domain.HUNT, "hunt_keyword_match")
+        return RouteDecision(Domain.HUNT, "default_to_hunt")
+
+
+def _matchesAny(text: str, keywords: set[str]) -> bool:
+    for token in keywords:
+        if re.fullmatch(r"[a-z0-9]+", token):
+            if re.search(rf"\b{re.escape(token)}\b", text):
+                return True
+        elif token in text:
+            return True
+    return False

picux/core/runtime.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+from picux import __version__
+from picux.config import PicuxSettings
+from picux.security import assertProductionReady, validateProductionReady
+
+
+@dataclass(frozen=True)
+class PicuxRuntime:
+    service: str = "picux"
+    settings: Optional[PicuxSettings] = None
+
+    def settingsObj(self) -> PicuxSettings:
+        return self.settings or PicuxSettings.fromEnv()
+
+    def health(self) -> dict[str, object]:
+        settings = self.settingsObj()
+        readiness = validateProductionReady(settings)
+        return {
+            "ok": True,
+            "svc": self.service,
+            "ver": __version__,
+            "phase": "scaffold",
+            "env": settings.env,
+            "prod": settings.prod,
+            "ready": readiness.ok,
+        }
+
+    def summary(self) -> dict[str, object]:
+        settings = self.settingsObj()
+        return {
+            **self.health(),
+            "settings": settings.publicSummary(),
+            "configSources": settings.sources,
+            "productionReadiness": validateProductionReady(settings).toMap(),
+        }
+
+    def assertBootable(self) -> None:
+        assertProductionReady(self.settingsObj())

picux/core/state_machine.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from typing import Any
+
+from picux.core.models import Domain
+from picux.core.router import PicuxIntentRouter
+
+
+class PicuxStateMachine:
+    """Minimal domain state machine for Phase 2 extraction."""
+
+    def __init__(self, router: PicuxIntentRouter | None = None) -> None:
+        self.router = router or PicuxIntentRouter()
+
+    def route(self, query: str) -> dict[str, Any]:
+        decision = self.router.classify(query)
+        return {
+            "query": query,
+            "domain": decision.domain.value,
+            "routeReason": decision.reason,
+            "phase": self._phase_forDomain(decision.domain),
+        }
+
+    @staticmethod
+    def _phase_forDomain(domain: Domain) -> str:
+        if domain == Domain.HUNT:
+            return "discovery"
+        if domain == Domain.RESOLVE:
+            return "orchestration"
+        if domain == Domain.BRIDGE:
+            return "connectivity"
+        if domain == Domain.PAY:
+            return "settlement"
+        if domain == Domain.SIGNALS:
+            return "signal_intake"
+        if domain == Domain.AUDIT:
+            return "audit"
+        return "unknown"

picux/domains/__init__.py

@@ -0,0 +1,2 @@
+"""Picux protocol domains."""
+