patchr 0.1.0__py3-none-any.whl

picux/domains/pay/models.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Protocol
+
+
+@dataclass(frozen=True)
+class Money:
+    amount: float
+    currency: str = "USD"
+
+    @classmethod
+    def fromObj(cls, value: dict[str, Any]) -> "Money":
+        return cls(
+            amount=float(value.get("amount", 0.0) or 0.0),
+            currency=str(value.get("currency", "USD") or "USD").upper(),
+        )
+
+    def toMap(self) -> dict[str, Any]:
+        return {"amount": round(max(0.0, float(self.amount or 0.0)), 2), "currency": self.currency}
+
+
+@dataclass(frozen=True)
+class ProofOfValue:
+    povId: str
+    rules: tuple[str, ...] = ()
+    meta: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def fromObj(cls, value: dict[str, Any] | None) -> "ProofOfValue":
+        value = value or {}
+        return cls(
+            povId=str(value.get("povId", value.get("id", "")) or ""),
+            rules=tuple(str(item) for item in value.get("rules", []) if str(item).strip()),
+            meta=value.get("meta", {}) if isinstance(value.get("meta", {}), dict) else {},
+        )
+
+    def toMap(self) -> dict[str, Any]:
+        return {"povId": self.povId, "rules": list(self.rules), "meta": self.meta}
+
+
+@dataclass(frozen=True)
+class SettlementRequest:
+    taskId: str
+    vendorId: str
+    amount: Money
+    pov: ProofOfValue
+
+    @classmethod
+    def fromObj(cls, value: dict[str, Any]) -> "SettlementRequest":
+        return cls(
+            taskId=str(value.get("taskId", "") or ""),
+            vendorId=str(value.get("vendorId", value.get("payeeId", "")) or ""),
+            amount=Money.fromObj(value.get("amount", {}) if isinstance(value.get("amount"), dict) else {}),
+            pov=ProofOfValue.fromObj(value.get("pov") if isinstance(value.get("pov"), dict) else {}),
+        )
+
+
+@dataclass(frozen=True)
+class SettlementAdapterSpec:
+    adapterId: str
+    rail: str
+    mode: str = "prepare"
+    network: str = ""
+    requiredEnv: tuple[str, ...] = ()
+    meta: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def fromObj(cls, value: dict[str, Any] | None) -> "SettlementAdapterSpec":
+        value = value or {}
+        return cls(
+            adapterId=str(value.get("adapterId", value.get("id", "adapter.prepare")) or "adapter.prepare"),
+            rail=str(value.get("rail", value.get("railId", "offchain")) or "offchain"),
+            mode=str(value.get("mode", "prepare") or "prepare"),
+            network=str(value.get("network", "") or ""),
+            requiredEnv=tuple(str(item) for item in value.get("requiredEnv", []) if str(item).strip()),
+            meta=value.get("meta", {}) if isinstance(value.get("meta", {}), dict) else {},
+        )
+
+    def toMap(self) -> dict[str, Any]:
+        return {
+            "adapterId": self.adapterId,
+            "rail": self.rail,
+            "mode": self.mode,
+            "network": self.network,
+            "requiredEnv": list(self.requiredEnv),
+            "meta": self.meta,
+        }
+
+
+class SettlementAdapter(Protocol):
+    adapterId: str
+
+    def prepare(self, instruction: dict[str, Any]) -> dict[str, Any]:
+        ...

picux/domains/proxy/__init__.py

@@ -0,0 +1,5 @@
+"""PROXY domain primitives."""
+
+from .engine import ProxyDomain
+
+__all__ = ["ProxyDomain"]

picux/domains/proxy/engine.py

@@ -0,0 +1,466 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class ProxyDomain:
+    """Human-as-callable-node primitives for oversight, logistics, and proof."""
+
+    feeRate: float = 0.05
+    feeCap: float = 5.0
+
+    def brief(self, task: str = "", *, context: dict[str, Any] | None = None) -> dict[str, Any]:
+        context = context or {}
+        clean = str(task or context.get("task", context.get("goal", "")) or "").strip()
+        overview = self._overview(clean, context)
+        decisionFork = self._dict(context.get("decisionFork", context.get("fork", {})))
+        logistics = self._dict(context.get("logistics", context.get("logisticsBrief", {}))) or {
+            "pickup": overview["pickup"],
+            "delivery": overview["delivery"],
+            "deadline": overview["deadline"],
+            "contact": overview["contact"],
+        }
+        proofReq = self._cleanList(context.get("proofReq", context.get("proof", []))) or ["photo", "gps", "receiptRef"]
+        steps = self._cleanList(context.get("steps", [])) or [
+            "Review the context snapshot before acting.",
+            "Confirm identity, scope, and safety constraints.",
+            "Complete the requested human action or judgment.",
+            "Return proof with photo, GPS, receipt, tracking, transcript, or note.",
+            "Escalate before changing scope.",
+        ]
+        channelMsg = self.channelMsg(context)
+        voiceCall = self.voiceCall(context)
+        caseOpsTimeline = self._caseOpsTimeline(context, steps)
+        brief = {
+            "briefId": self._stableId("pbrief", {"task": clean, "context": context}),
+            "kind": "proxyBrief",
+            "missionType": self._missionType(context),
+            "state": "awaitingProxy",
+            "reason": str(context.get("reason", "humanIntervention") or "humanIntervention"),
+            "task": clean,
+            "missionState": self._dict(context.get("missionState", context.get("state", {}))),
+            "decisionFork": decisionFork,
+            "logistics": logistics,
+            "overview": overview,
+            "steps": steps,
+            "caseOpsTimeline": caseOpsTimeline,
+            "proofReq": proofReq,
+            "constraints": self._dict(context.get("constraints", {})),
+            "channelMsg": channelMsg,
+            "voiceCall": voiceCall,
+        }
+        brief["markdown"] = self._markdown(brief)
+        return brief
+
+    def route(self, payload: dict[str, Any] | None = None) -> dict[str, Any]:
+        payload = payload or {}
+        routeType = str(payload.get("routeType", "") or "")
+        if not routeType:
+            routeType = self._regulatedRouteType(payload)
+        assignedTo = str(payload.get("assignedTo", payload.get("reviewerId", "")) or "")
+        status = "assigned" if assignedTo else str(payload.get("status", "queued") or "queued")
+        return {
+            "routeId": str(payload.get("routeId", "") or self._stableId("proute", payload)),
+            "kind": "proxyRoute",
+            "status": status,
+            "routeType": routeType,
+            "queue": str(payload.get("queue", "proxyQueue") or "proxyQueue"),
+            "assignedTo": assignedTo,
+            "credentials": self._credentials(payload, routeType),
+            "sla": self._dict(payload.get("sla", {})),
+            "share": self._sharePolicy(routeType),
+            "fallback": self._fallback(routeType),
+        }
+
+    def channelMsg(self, payload: dict[str, Any] | None = None) -> dict[str, Any]:
+        payload = payload or {}
+        raw = payload.get("channelMsg", {}) if isinstance(payload.get("channelMsg"), dict) else {}
+        channel = str(raw.get("channel", payload.get("channel", "")) or "")
+        to = str(raw.get("to", payload.get("to", payload.get("userId", ""))) or "")
+        text = str(raw.get("text", payload.get("message", "")) or "")
+        return {
+            "msgId": str(raw.get("msgId", "") or self._stableId("pmsg", {"channel": channel, "to": to, "text": text})),
+            "kind": "channelMsg",
+            "channel": channel,
+            "to": to,
+            "text": text,
+            "status": str(raw.get("status", "pending") or "pending"),
+            "connectorId": str(raw.get("connectorId", payload.get("connectorId", "")) or ""),
+        }
+
+    def voiceCall(self, payload: dict[str, Any] | None = None) -> dict[str, Any]:
+        payload = payload or {}
+        raw = payload.get("voiceCall", {}) if isinstance(payload.get("voiceCall"), dict) else {}
+        phone = str(raw.get("phone", raw.get("phoneNumber", payload.get("phone", ""))) or "")
+        phoneRef = str(raw.get("phoneRef", raw.get("contactRef", payload.get("phoneRef", payload.get("contactRef", "")))) or "")
+        if not phone and not phoneRef:
+            return {}
+        call = {
+            "callId": str(raw.get("callId", "") or self._stableId("pcall", {"phone": phone, "phoneRef": phoneRef, "taskId": payload.get("taskId", "")})),
+            "kind": "voiceCall",
+            "status": str(raw.get("status", "pending") or "pending"),
+            "connectorId": str(raw.get("connectorId", payload.get("connectorId", "")) or ""),
+            "prompt": str(raw.get("prompt", payload.get("prompt", "")) or ""),
+            "transcript": raw.get("transcript", []) if isinstance(raw.get("transcript"), list) else [],
+        }
+        if phone:
+            call["phone"] = phone
+        if phoneRef:
+            call["phoneRef"] = phoneRef
+        return call
+
+    def pickNode(self, nodes: list[dict[str, Any]]) -> dict[str, Any] | None:
+        eligible = [
+            node
+            for node in nodes
+            if float(node.get("rating", 0.0) or 0.0) >= 4.9
+            and int(node.get("done", node.get("tasksDone", node.get("tasks_completed", 0))) or 0) >= 50
+        ]
+        if not eligible:
+            return None
+        eligible.sort(
+            key=lambda item: (
+                float(item.get("rating", 0.0) or 0.0),
+                int(item.get("done", item.get("tasksDone", item.get("tasks_completed", 0))) or 0),
+            ),
+            reverse=True,
+        )
+        return eligible[0]
+
+    def verifyProof(self, *, text: str = "", payload: dict[str, Any] | None = None) -> dict[str, Any]:
+        payload = payload or {}
+        lowered = str(text or "").strip().lower()
+        status = str(payload.get("status") or payload.get("outcome") or "").strip().lower()
+        if status in {"failed", "failure", "cancelled", "canceled", "aborted"}:
+            return self._proofResult("confirmedFailure", "providerFailure", payload=payload, text=text)
+        if any(token in lowered for token in ("failed", "not delivered", "cancelled", "canceled", "abort")):
+            return self._proofResult("confirmedFailure", "textFailure", payload=payload, text=text)
+
+        photos = self._photos(payload) + self._photoUrls(text)
+        gps = self._gps(payload) or self._gpsText(text)
+        receipt = self._ref(payload, ("receiptId", "receipt", "receiptRef", "orderId", "confirmationId")) or self._receiptText(text)
+        tracking = self._ref(payload, ("trackingId", "tracking", "trackingNumber", "shipmentId")) or self._trackingText(text)
+        transcript = payload.get("transcript", []) if isinstance(payload.get("transcript"), list) else []
+        note = str(payload.get("note", payload.get("summary", text)) or "").strip()
+        proofTypes = []
+        if photos:
+            proofTypes.append("photo")
+        if isinstance(gps, dict):
+            proofTypes.append("gps")
+        if receipt:
+            proofTypes.append("receiptRef")
+        if tracking:
+            proofTypes.append("trackingId")
+        if transcript:
+            proofTypes.append("transcript")
+        if note:
+            proofTypes.append("note")
+
+        hasPhoto = bool(photos)
+        hasGps = isinstance(gps, dict)
+        hasRef = bool(receipt or tracking)
+        if hasPhoto and hasGps:
+            outStatus = "confirmedSuccess"
+            reason = "photoGps"
+        elif hasPhoto and hasRef:
+            outStatus = "confirmedSuccess"
+            reason = "photoRef"
+        elif hasGps:
+            outStatus = "confirmedSuccess"
+            reason = "gps"
+        elif note and not payload.get("requiresPhysicalProof"):
+            outStatus = "confirmedSuccess"
+            reason = "humanNote"
+        else:
+            outStatus = "pending"
+            reason = "missingProof"
+
+        return {
+            "status": outStatus,
+            "reason": reason,
+            "proofTypes": list(dict.fromkeys(proofTypes)),
+            "proof": {
+                "photo": photos[0] if photos else "",
+                "photoCount": len(photos),
+                "gps": gps or {},
+                "receiptRef": receipt,
+                "trackingId": tracking,
+                "transcript": transcript,
+                "note": note,
+            },
+            "laborCost": self._cost(payload, text),
+            "settleReady": outStatus == "confirmedSuccess" and (hasGps or hasRef or bool(note and not payload.get("requiresPhysicalProof"))),
+        }
+
+    def outcome(self, *, text: str = "", payload: dict[str, Any] | None = None) -> dict[str, Any]:
+        payload = payload or {}
+        proof = self.verifyProof(text=text, payload=payload)
+        resumeState = "ready" if proof["status"] in {"confirmedSuccess", "confirmedFailure"} else "awaitingProxy"
+        return {
+            "outcomeId": str(payload.get("outcomeId", "") or self._stableId("pout", {"text": text, "payload": payload})),
+            "kind": "proxyOutcome",
+            "status": proof["status"],
+            "reason": proof["reason"],
+            "proofTypes": proof["proofTypes"],
+            "proof": proof["proof"],
+            "laborCost": proof["laborCost"],
+            "settleReady": proof["settleReady"],
+            "resume": {
+                "state": resumeState,
+                "source": "proxy",
+                "sourceOfTruth": proof["status"] == "confirmedSuccess",
+                "inject": {"proof": proof["proof"], "reason": proof["reason"]},
+            },
+            "settlementGate": {
+                "status": "ready" if proof["settleReady"] else "blocked",
+                "reason": "proxyProofVerified" if proof["settleReady"] else proof["reason"],
+            },
+        }
+
+    def mgmtFee(self, laborCost: float) -> float:
+        cost = max(0.0, float(laborCost or 0.0))
+        if cost <= 0:
+            return 0.0
+        fee = cost * max(0.0, self.feeRate)
+        if self.feeCap > 0:
+            fee = min(fee, self.feeCap)
+        return round(max(0.0, fee), 2)
+
+    def _proofResult(self, status: str, reason: str, *, payload: dict[str, Any], text: str) -> dict[str, Any]:
+        return {
+            "status": status,
+            "reason": reason,
+            "proofTypes": [],
+            "proof": {},
+            "laborCost": self._cost(payload, text),
+            "settleReady": False,
+        }
+
+    @staticmethod
+    def _overview(text: str, context: dict[str, Any]) -> dict[str, str]:
+        pickup = str(context.get("pickup", "") or "") or ProxyDomain._match(text, r"(?:pickup|pick up|collect|from)\s+(?:at\s+)?(?P<v>[^,.;]+)")
+        delivery = str(context.get("delivery", "") or "") or ProxyDomain._match(text, r"(?:deliver|drop\s*off|to)\s+(?:at\s+)?(?P<v>[^,.;]+)")
+        deadline = str(context.get("deadline", "") or "") or ProxyDomain._match(text, r"(?:by|before|no later than)\s+(?P<v>[0-2]?\d(?::[0-5]\d)?(?:\s?[ap]m)?)")
+        contact = str(context.get("contact", "") or "") or ProxyDomain._match(text, r"(?:contact|ask for)\s+(?P<v>[A-Za-z][A-Za-z\s'\-]{1,40})")
+        return {
+            "pickup": pickup or "unspecified",
+            "delivery": delivery or "unspecified",
+            "deadline": deadline or "ASAP",
+            "contact": contact or "humanProxy",
+            "item": str(context.get("item", "") or text or "Proxy action"),
+        }
+
+    @staticmethod
+    def _missionType(context: dict[str, Any]) -> str:
+        raw = str(context.get("missionType", context.get("kind", "logistics")) or "logistics")
+        return raw if raw in {"review", "logistics", "call", "message", "approval", "custom"} else "custom"
+
+    @staticmethod
+    def _caseOpsTimeline(context: dict[str, Any], steps: list[str]) -> list[dict[str, Any]]:
+        raw = context.get("caseOpsTimeline", [])
+        if isinstance(raw, list):
+            timeline = [item for item in raw if isinstance(item, dict)]
+            if timeline:
+                return timeline
+        owner = str(context.get("owner", "proxy") or "proxy")
+        if owner not in {"hunt", "resolve", "bridge", "proxy", "pay", "client"}:
+            owner = "proxy"
+        return [
+            {
+                "stepId": f"proxy_step_{idx}",
+                "status": "queued" if idx == 1 else "blocked",
+                "owner": owner,
+                "label": step,
+                "approvalRequired": idx == 2,
+            }
+            for idx, step in enumerate(steps, start=1)
+        ]
+
+    @staticmethod
+    def _match(text: str, pattern: str) -> str:
+        match = re.search(pattern, text or "", re.IGNORECASE)
+        if not match:
+            return ""
+        value = str(match.group("v")).strip()
+        return re.sub(r"^(?:from|to|at)\s+", "", value, flags=re.IGNORECASE).strip()
+
+    @staticmethod
+    def _markdown(brief: dict[str, Any]) -> str:
+        overview = brief.get("overview", {})
+        lines = [
+            f"PROXY: {brief.get('missionType', 'custom')}",
+            f"State: {brief.get('state', 'awaitingProxy')}",
+            f"Reason: {brief.get('reason', 'humanIntervention')}",
+            "",
+            f"- Pickup: {overview.get('pickup', '-')}",
+            f"- Delivery: {overview.get('delivery', '-')}",
+            f"- Deadline: {overview.get('deadline', '-')}",
+            f"- Contact: {overview.get('contact', '-')}",
+            f"- Item: {overview.get('item', '-')}",
+            "",
+            "STEPS",
+        ]
+        for idx, step in enumerate(brief.get("steps", []), start=1):
+            lines.append(f"{idx}. {step}")
+        return "\n".join(lines)
+
+    @staticmethod
+    def _photoUrls(text: str) -> list[str]:
+        return [url.strip() for url in re.findall(r"https?://[^\s)]+", str(text or "")) if url.strip()]
+
+    @staticmethod
+    def _photos(payload: dict[str, Any]) -> list[str]:
+        urls = []
+        for key in ("photo", "photoUrl", "proofPhoto", "proofUrl", "imageUrl"):
+            value = payload.get(key)
+            if isinstance(value, str) and value.strip():
+                urls.append(value.strip())
+        for key in ("photos", "images"):
+            values = payload.get(key)
+            if isinstance(values, list):
+                for value in values:
+                    if isinstance(value, str) and value.strip():
+                        urls.append(value.strip())
+                    elif isinstance(value, dict) and isinstance(value.get("url"), str):
+                        urls.append(value["url"].strip())
+        deduped = []
+        for url in urls:
+            if url and url not in deduped:
+                deduped.append(url)
+        return deduped
+
+    @staticmethod
+    def _gps(payload: dict[str, Any]) -> dict[str, float] | None:
+        lat = payload.get("lat")
+        lng = payload.get("lng", payload.get("lon"))
+        if lat is not None and lng is not None:
+            return ProxyDomain._coerceGps(lat, lng)
+        for key in ("gps", "geo", "location"):
+            value = payload.get(key)
+            if not isinstance(value, dict):
+                continue
+            found = ProxyDomain._coerceGps(value.get("lat", value.get("latitude")), value.get("lng", value.get("lon", value.get("longitude"))))
+            if found:
+                return found
+        return None
+
+    @staticmethod
+    def _gpsText(text: str) -> dict[str, float] | None:
+        match = re.search(r"(-?\d{1,2}\.\d+)\s*,\s*(-?\d{1,3}\.\d+)", str(text or ""))
+        if not match:
+            return None
+        return ProxyDomain._coerceGps(match.group(1), match.group(2))
+
+    @staticmethod
+    def _coerceGps(lat: Any, lng: Any) -> dict[str, float] | None:
+        try:
+            latF = float(lat)
+            lngF = float(lng)
+        except Exception:
+            return None
+        if -90 <= latF <= 90 and -180 <= lngF <= 180:
+            return {"lat": latF, "lng": lngF}
+        return None
+
+    @staticmethod
+    def _ref(payload: dict[str, Any], keys: tuple[str, ...]) -> str:
+        for key in keys:
+            value = payload.get(key)
+            if isinstance(value, str) and value.strip():
+                return value.strip()
+        return ""
+
+    @staticmethod
+    def _receiptText(text: str) -> str:
+        match = re.search(r"(?:receipt|order|confirmation)\s*(?:#|no\.?|number)?\s*([A-Z0-9\-]{4,32})", str(text or ""), re.IGNORECASE)
+        return str(match.group(1)).strip() if match else ""
+
+    @staticmethod
+    def _trackingText(text: str) -> str:
+        match = re.search(r"(?:tracking|tracker)\s*(?:#|id|number)?\s*([A-Z0-9\-]{6,40})", str(text or ""), re.IGNORECASE)
+        return str(match.group(1)).strip() if match else ""
+
+    @staticmethod
+    def _cost(payload: dict[str, Any], text: str) -> float:
+        for key in ("laborCost", "taskCost", "cost", "amount"):
+            try:
+                value = float(payload.get(key))
+                if value > 0:
+                    return value
+            except (TypeError, ValueError):
+                continue
+        match = re.search(r"(?:cost|taskCost|laborCost|amount)\s*[:=]\s*\$?\s*(\d+(?:\.\d+)?)|\$\s*(\d+(?:\.\d+)?)", str(text or ""), re.IGNORECASE)
+        if not match:
+            return 0.0
+        return float(match.group(1) or match.group(2) or 0.0)
+
+    @staticmethod
+    def _dict(value: Any) -> dict[str, Any]:
+        return value if isinstance(value, dict) else {}
+
+    @staticmethod
+    def _cleanList(value: Any) -> list[str]:
+        if not isinstance(value, list):
+            return []
+        out = []
+        for item in value:
+            clean = str(item or "").strip()
+            if clean and clean not in out:
+                out.append(clean)
+        return out
+
+    @staticmethod
+    def _regulated(payload: dict[str, Any]) -> bool:
+        return ProxyDomain._regulatedRouteType(payload) != "humanOperator"
+
+    @staticmethod
+    def _regulatedRouteType(payload: dict[str, Any]) -> str:
+        text = json.dumps(payload, ensure_ascii=True, sort_keys=True).lower()
+        if "legal aid" in text or "lawyer" in text or "attorney" in text:
+            return "legalAid"
+        if "accredited counselor" in text or "counselor" in text:
+            return "accreditedCounselor"
+        if "licensed consultant" in text or "licensed" in text:
+            return "licensedConsultant"
+        if any(token in text for token in ("legal", "regulated", "medical", "professional")):
+            return "qualifiedHuman"
+        return "humanOperator"
+
+    @staticmethod
+    def _sharePolicy(routeType: str) -> dict[str, Any]:
+        qualified = routeType in {"qualifiedHuman", "legalAid", "accreditedCounselor", "licensedConsultant"}
+        return {
+            "allowFullDocs": qualified,
+            "allowPaymentDetails": qualified,
+            "redactSensitive": True,
+        }
+
+    @staticmethod
+    def _fallback(routeType: str) -> dict[str, str]:
+        if routeType in {"qualifiedHuman", "legalAid", "accreditedCounselor", "licensedConsultant"}:
+            return {"trigger": "slaOverdue", "action": "reassignQualifiedHuman"}
+        return {"trigger": "unassigned", "action": "escalateProxyQueue"}
+
+    @staticmethod
+    def _credentials(payload: dict[str, Any], routeType: str) -> dict[str, Any]:
+        raw = payload.get("credentials", payload.get("credentialReq", {}))
+        raw = raw if isinstance(raw, dict) else {}
+        if routeType == "humanOperator":
+            return raw
+        return {
+            "required": True,
+            "routeType": routeType,
+            "jurisdiction": str(raw.get("jurisdiction", payload.get("jurisdiction", "")) or ""),
+            "licenseRef": str(raw.get("licenseRef", raw.get("accreditationRef", "")) or ""),
+            "verified": bool(raw.get("verified", False)),
+        }
+
+    @staticmethod
+    def _stableId(prefix: str, payload: dict[str, Any]) -> str:
+        digest = hashlib.sha256(json.dumps(payload, ensure_ascii=True, sort_keys=True).encode("utf-8")).hexdigest()
+        return f"{prefix}_{digest[:24]}"

picux/domains/resolve/__init__.py

@@ -0,0 +1,5 @@
+"""RESOLVE domain primitives."""
+
+from .engine import ResolveDomain
+
+__all__ = ["ResolveDomain"]