patchr 0.1.0__py3-none-any.whl

picux/domains/resolve/engine.py

@@ -0,0 +1,546 @@
+from __future__ import annotations
+
+import json
+import re
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+
+DEFAULT_RULES: tuple[dict[str, str], ...] = (
+    {
+        "id": "junkFee",
+        "pattern": r"(junk fee|processing fee|regulatory recovery|administrative fee|hidden fee)",
+        "feeName": "Undisclosed Fee",
+        "clause": "Consumer pricing transparency obligations",
+    },
+    {
+        "id": "shippingLeak",
+        "pattern": r"(shipping surcharge|residential surcharge|fuel adjustment)",
+        "feeName": "Shipping Surcharge",
+        "clause": "Carrier billing disclosure obligations",
+    },
+    {
+        "id": "refundGap",
+        "pattern": r"(refund due|credit due|overcharge|duplicate charge)",
+        "feeName": "Recoverable Overcharge",
+        "clause": "Provider refund and account-credit obligations",
+    },
+    {
+        "id": "damagedGoods",
+        "pattern": r"(broken in transit|damaged in transit|damaged tv|cracked panel|arrived broken|defective item|damaged goods)",
+        "feeName": "Damaged Goods Claim",
+        "clause": "Consumer purchase and transport-damage obligations",
+    },
+)
+
+
+@dataclass(frozen=True)
+class ResolveDomain:
+    rules: tuple[dict[str, str], ...] = field(default_factory=lambda: DEFAULT_RULES)
+    policyVer: str = "picux-resolve-2026-05-09"
+
+    def redact(self, text: str) -> str:
+        masked = re.sub(r"\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b", "[email]", str(text or ""), flags=re.IGNORECASE)
+        masked = re.sub(r"\+?\b(?:\d[\s().-]?){8,15}\d\b", "[phone]", masked)
+        masked = re.sub(r"\b\d{3}-\d{2}-\d{4}\b", "***-**-****", masked)
+        masked = re.sub(r"\b(?:\d[ -]*?){13,19}\b", "**** **** **** ****", masked)
+        masked = re.sub(r"\b\d{9,12}\b", "**********", masked)
+        return masked
+
+    def auditText(self, text: str, *, provider: str = "") -> dict[str, Any]:
+        lowered = self.redact(text).lower()
+        findings: list[dict[str, Any]] = []
+        for rule in self.rules:
+            pattern = str(rule.get("pattern", ""))
+            if not pattern or not re.search(pattern, lowered):
+                continue
+            refund = self._nearestAmount(lowered, pattern)
+            findings.append(
+                {
+                    "ruleId": str(rule.get("id", "")),
+                    "feeName": str(rule.get("feeName", "Unknown Fee")),
+                    "clause": str(rule.get("clause", "Consumer pricing protections")),
+                    "refundAmount": refund,
+                    "reason": f"pattern:{pattern}",
+                }
+            )
+
+        refundAmount = round(sum(max(0.0, float(item.get("refundAmount", 0.0))) for item in findings), 2)
+        top = findings[0] if findings else {}
+        return {
+            "provider": provider,
+            "violation": bool(findings),
+            "findings": findings,
+            "refundAmount": refundAmount,
+            "clause": str(top.get("clause", "")),
+            "feeName": str(top.get("feeName", "")),
+            "policyVer": self.policyVer,
+            "ruleCount": len(self.rules),
+            "auditedAt": int(time.time()),
+        }
+
+    def detectOutcome(self, *, providerText: str = "", payload: dict[str, Any] | None = None) -> dict[str, Any]:
+        payload = payload or {}
+        payloadText = ""
+        if payload:
+            try:
+                payloadText = json.dumps(payload, ensure_ascii=True, sort_keys=True).lower()
+            except Exception:
+                payloadText = str(payload).lower()
+        text = f"{str(providerText or '').lower()} {payloadText}".strip()
+        if not text:
+            return {"status": "pending", "reason": "missingProviderText", "type": "", "amount": 0.0}
+
+        positive = (
+            "refund issued",
+            "refund processed",
+            "credit issued",
+            "credit applied",
+            "credit posted",
+            "adjustment posted",
+            "charge reversed",
+            "fee removed",
+            "we have credited",
+            "replacement approved",
+            "exchange approved",
+            "replacement case approved",
+            "rma approved",
+            '"status":"credited"',
+            '"status":"refunded"',
+            '"decision":"approved"',
+        )
+        negative = (
+            "refund denied",
+            "credit denied",
+            "request denied",
+            "request rejected",
+            "not eligible",
+            "unable to provide a refund",
+            "no refund",
+            '"status":"denied"',
+            '"decision":"denied"',
+        )
+        pending = (
+            "under review",
+            "in progress",
+            "pending",
+            "awaiting review",
+            "processing request",
+            "we are investigating",
+        )
+
+        amount = self._firstAmount(text)
+        if any(marker in text for marker in negative):
+            return {"status": "confirmedFailure", "reason": "providerDenied", "type": "denied", "amount": amount}
+        if any(marker in text for marker in positive):
+            kind = "credit" if "credit" in text else "refund"
+            return {"status": "confirmedSuccess", "reason": "providerConfirmed", "type": kind, "amount": amount}
+        if any(marker in text for marker in pending):
+            return {"status": "pending", "reason": "providerPending", "type": "", "amount": amount}
+        return {"status": "pending", "reason": "outcomeUnclear", "type": "", "amount": amount}
+
+    def buildNotice(self, *, accountId: str, provider: str, userName: str, audit: dict[str, Any]) -> dict[str, str]:
+        refund = float(audit.get("refundAmount", 0.0) or 0.0)
+        feeName = str(audit.get("feeName", "Undisclosed Fee") or "Undisclosed Fee")
+        clause = str(audit.get("clause", "Consumer pricing protections") or "Consumer pricing protections")
+        subject = f"Formal Billing Dispute - Account {accountId}"
+        body = (
+            f"To the {provider} Billing Department,\n\n"
+            f"Picux Resolve identified a '{feeName}' charge of ${refund:.2f}. "
+            f"This appears to violate {clause}.\n\n"
+            "Required action: issue the applicable credit and confirm the fee has been removed from future invoices.\n\n"
+            f"Regards,\nPicux Resolve on behalf of {userName}"
+        )
+        return {"subject": subject, "body": body}
+
+    def contactPlan(self, *, request: dict[str, Any] | None = None, target: dict[str, Any] | None = None) -> dict[str, Any]:
+        request = request or {}
+        target = target or {}
+        entityType = str(target.get("type", target.get("entityType", "merchant")) or "merchant")
+        channels = target.get("channels", []) if isinstance(target.get("channels"), list) else []
+        if not channels:
+            channels = self._defaultChannels(entityType)
+        preferred = str(request.get("preferredChannel", target.get("preferredChannel", "")) or "")
+        primary = self._primaryChannel(channels, preferred)
+        phone = next((item for item in channels if isinstance(item, dict) and str(item.get("type", "")) == "phone"), {})
+        requiresProxy = bool(target.get("voiceRequired") or request.get("requiresVoice") or phone.get("requiresProxy"))
+        return {
+            "target": {
+                "entityId": str(target.get("entityId", request.get("provider", "")) or ""),
+                "name": str(target.get("name", request.get("provider", "")) or ""),
+                "type": entityType,
+            },
+            "channels": channels,
+            "primary": primary,
+            "requiresProxy": requiresProxy,
+            "proxyChannel": phone if requiresProxy else {},
+        }
+
+    def draftClaim(
+        self,
+        *,
+        request: dict[str, Any] | None = None,
+        audit: dict[str, Any] | None = None,
+        target: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        request = request or {}
+        audit = audit or {}
+        target = target or {}
+        plan = self.contactPlan(request=request, target=target)
+        targetName = plan["target"]["name"] or "target entity"
+        issue = str(request.get("issueType", audit.get("feeName", "consumer claim")) or "consumer claim")
+        location = str(request.get("location", "") or "")
+        evidence = self._attachmentRefs(request.get("attachments", []))
+        subject = f"Claim for {issue} with {targetName}".strip()
+        evidenceLine = ", ".join(item["label"] for item in evidence) or "attached evidence"
+        body = (
+            f"Hello {targetName},\n\n"
+            f"Picux Resolve is submitting a claim for {issue}. "
+            f"The request references {location or 'the relevant service location'} and includes {evidenceLine}. "
+            "Please confirm the remedy path, case reference, and next action.\n\n"
+            "Requested remedy: repair, replacement, refund, or formal case opening according to the applicable policy.\n\n"
+            "Regards,\nPicux Resolve"
+        )
+        chatText = f"Picux Resolve claim: {issue}. Evidence: {evidenceLine}. Please provide case reference and remedy path."
+        phoneScript = (
+            f"Call {targetName}. Explain that Picux Resolve is following up on {issue}. "
+            "Ask for the case reference, remedy path, expected timeline, and whether more evidence is required."
+        )
+        return {
+            "kind": "resolveClaimDraft",
+            "target": plan["target"],
+            "channelPlan": plan,
+            "evidence": evidence,
+            "drafts": {
+                "email": {
+                    "to": str(plan["primary"].get("address", plan["primary"].get("to", "")) or ""),
+                    "subject": subject,
+                    "body": body,
+                },
+                "letter": {"subject": subject, "body": body},
+                "chat": {"channel": str(plan["primary"].get("type", "chat") or "chat"), "text": chatText},
+                "phone": {
+                    "requiresProxy": bool(plan["requiresProxy"]),
+                    "connectorId": str(plan["proxyChannel"].get("connectorId", "") or ""),
+                    "phoneRef": str(plan["proxyChannel"].get("phoneRef", plan["proxyChannel"].get("phone", "")) or ""),
+                    "script": phoneScript,
+                },
+            },
+        }
+
+    def triageClaim(self, payload: dict[str, Any]) -> dict[str, Any]:
+        text = self.redact(str(payload.get("claim", payload.get("text", payload.get("query", ""))) or ""))
+        docs = payload.get("documents", payload.get("attachments", []))
+        docs = docs if isinstance(docs, list) else []
+        agentClaims = payload.get("agentClaims", [])
+        agentClaims = agentClaims if isinstance(agentClaims, list) else []
+        profile = self._profile(payload, text)
+        evidenceMap = self._evidenceMap(docs)
+        contradictions = self._contradictions(text, docs, agentClaims)
+        sourceClasses = self._sourceClasses(text, docs)
+        typedEvidence = self._typedEvidence(text, docs, sourceClasses)
+        fraudIndicators = self._fraudIndicators(text, docs, agentClaims, sourceClasses)
+        missing = self._missingEvidence(text, docs, profile=profile, sourceClasses=sourceClasses, typedEvidence=typedEvidence)
+        risk = self._riskClass(text, contradictions, missing, agentClaims, profile=profile, fraudIndicators=fraudIndicators)
+        confidence = self._triageConfidence(evidenceMap, contradictions, missing)
+        openQuestions = [f"missing:{item}" for item in missing]
+        if contradictions:
+            openQuestions.append("contradictionsRequireReview")
+        if fraudIndicators:
+            openQuestions.append("fraudIndicatorsRequireReview")
+        escalation = {
+            "recommended": risk["severity"] in {"high", "critical"} or bool(openQuestions),
+            "routeDomain": "proxy" if risk["severity"] in {"high", "critical"} or bool(openQuestions) else "",
+            "reason": "humanReviewerNeeded" if risk["severity"] in {"high", "critical"} else ("missingEvidence" if openQuestions else ""),
+        }
+        return {
+            "kind": "resolveScamTriage",
+            "workflow": str(payload.get("workflow", "resolveForMobility") or "resolveForMobility"),
+            "profile": profile,
+            "claim": text,
+            "risk": risk,
+            "evidenceMap": evidenceMap,
+            "typedEvidence": typedEvidence,
+            "sourceClasses": sourceClasses,
+            "fraudIndicators": fraudIndicators,
+            "verificationStatus": self._verificationStatus(evidenceMap, sourceClasses, fraudIndicators, missing),
+            "caseOpsTimeline": self._caseOpsTimeline(profile, risk, sourceClasses, fraudIndicators, missing),
+            "contradictions": contradictions,
+            "missingEvidence": missing,
+            "openQuestions": openQuestions,
+            "confidence": confidence,
+            "recommendedRestraint": "escalateBeforeActing" if escalation["recommended"] else "safeToProceedWithCitations",
+            "nextAction": self._nextAction(risk, missing, contradictions, fraudIndicators),
+            "escalation": escalation,
+        }
+
+    @staticmethod
+    def _nearestAmount(text: str, pattern: str) -> float:
+        match = re.search(pattern, text)
+        if not match:
+            return 0.0
+        start = max(0, match.start() - 80)
+        end = min(len(text), match.end() + 80)
+        return ResolveDomain._firstAmount(text[start:end])
+
+    @staticmethod
+    def _firstAmount(text: str) -> float:
+        matches = re.findall(r"\$\s*([0-9]+(?:\.[0-9]{1,2})?)", str(text or ""))
+        if not matches:
+            return 0.0
+        try:
+            return float(matches[0])
+        except Exception:
+            return 0.0
+
+    @staticmethod
+    def _defaultChannels(entityType: str) -> list[dict[str, Any]]:
+        if entityType == "bank":
+            return [{"type": "secureMessage"}, {"type": "phone", "requiresProxy": True}, {"type": "letter"}]
+        if entityType == "serviceOps":
+            return [{"type": "ticket"}, {"type": "chat"}, {"type": "phone", "requiresProxy": True}]
+        return [{"type": "email"}, {"type": "chat"}, {"type": "phone", "requiresProxy": True}]
+
+    @staticmethod
+    def _primaryChannel(channels: list[Any], preferred: str) -> dict[str, Any]:
+        typed = [item for item in channels if isinstance(item, dict)]
+        if preferred:
+            match = next((item for item in typed if str(item.get("type", "")) == preferred), None)
+            if match:
+                return match
+        return next((item for item in typed if str(item.get("type", "")) != "phone"), typed[0] if typed else {})
+
+    @staticmethod
+    def _attachmentRefs(value: Any) -> list[dict[str, str]]:
+        if not isinstance(value, list):
+            return []
+        refs: list[dict[str, str]] = []
+        for item in value:
+            if not isinstance(item, dict):
+                continue
+            name = str(item.get("name", item.get("uri", item.get("kind", "attachment"))) or "attachment")
+            kind = str(item.get("kind", "attachment") or "attachment")
+            digest = str(item.get("sha256", item.get("hash", "")) or "")
+            refs.append(
+                {
+                    "kind": kind,
+                    "name": name,
+                    "sha256": digest,
+                    "mime": str(item.get("mime", "") or ""),
+                    "size": str(item.get("size", "") or ""),
+                    "label": f"{kind}:{name}",
+                }
+            )
+        return refs
+
+    @staticmethod
+    def _evidenceMap(docs: list[Any]) -> list[dict[str, Any]]:
+        out = []
+        for index, item in enumerate(docs, start=1):
+            doc = item if isinstance(item, dict) else {"label": str(item)}
+            digest = str(doc.get("sha256", doc.get("hash", "")) or "")
+            out.append(
+                {
+                    "ref": str(doc.get("artifactId", doc.get("name", f"doc_{index}")) or f"doc_{index}"),
+                    "kind": str(doc.get("kind", doc.get("type", "document")) or "document"),
+                    "sourceBound": bool(digest or doc.get("source")),
+                    "hash": digest,
+                    "prevHash": str(doc.get("prevHash", "") or ""),
+                    "label": str(doc.get("label", doc.get("name", "")) or ""),
+                }
+            )
+        return out
+
+    @staticmethod
+    def _profile(payload: dict[str, Any], text: str) -> str:
+        explicit = str(payload.get("profile", payload.get("useCase", "")) or "")
+        if explicit:
+            return explicit
+        lowered = text.lower()
+        if any(token in lowered for token in ("migration", "visa", "residence permit", "work permit", "admission letter", "offer letter", "recruiter", "school claim")):
+            return "migrationTrust"
+        return str(payload.get("workflow", "resolveForMobility") or "resolveForMobility")
+
+    @staticmethod
+    def _sourceClasses(text: str, docs: list[Any]) -> list[dict[str, str]]:
+        classes: list[dict[str, str]] = []
+        for index, item in enumerate(docs, start=1):
+            doc = item if isinstance(item, dict) else {"label": str(item)}
+            ref = str(doc.get("artifactId", doc.get("name", f"doc_{index}")) or f"doc_{index}")
+            source = str(doc.get("source", doc.get("uri", "")) or "").lower()
+            kind = str(doc.get("kind", doc.get("type", "")) or "").lower()
+            label = "userUpload"
+            if any(token in source for token in (".gov", "gov/", "migrationsverket", "udi.no", "immigration")) or "official" in kind:
+                label = "officialPortal"
+            elif any(token in f"{kind} {source}" for token in ("school", "university", "admission")):
+                label = "school"
+            elif "recruiter" in f"{kind} {source}":
+                label = "recruiter"
+            elif any(token in f"{kind} {source}" for token in ("agent", "consultant", "licensed")):
+                label = "licensedAgent"
+            elif any(token in source for token in ("reddit", "forum", "facebook", "whatsapp")):
+                label = "publicForum"
+            elif source and not source.startswith("upload://"):
+                label = "externalSource"
+            classes.append({"ref": ref, "sourceClass": label, "verificationStatus": "sourceBound" if label == "officialPortal" else "unverified"})
+        if not classes and any(token in text.lower() for token in ("migration", "visa", "recruiter", "school", "offer letter")):
+            classes.append({"ref": "claimText", "sourceClass": "userStatement", "verificationStatus": "unverified"})
+        return classes
+
+    @staticmethod
+    def _typedEvidence(text: str, docs: list[Any], sourceClasses: list[dict[str, str]]) -> list[dict[str, str]]:
+        typed: list[dict[str, str]] = []
+        for index, item in enumerate(docs, start=1):
+            doc = item if isinstance(item, dict) else {"label": str(item)}
+            ref = str(doc.get("artifactId", doc.get("name", f"doc_{index}")) or f"doc_{index}")
+            value = f"{doc.get('kind', '')} {doc.get('type', '')} {doc.get('name', '')} {doc.get('source', '')}".lower()
+            evidenceType = "sourceSnapshot"
+            if "offer" in value:
+                evidenceType = "offerLetter"
+            elif "recruiter" in value:
+                evidenceType = "recruiterClaim"
+            elif any(token in value for token in ("school", "university", "admission")):
+                evidenceType = "schoolClaim"
+            elif "visa" in value or "permit" in value:
+                evidenceType = "visaStep"
+            elif any(token in value for token in ("payment", "invoice", "bank", "fee")):
+                evidenceType = "paymentInstruction"
+            elif any(token in value for token in ("identity", "passport", "id")):
+                evidenceType = "identityDocument"
+            elif any(token in value for token in ("message", "email", "chat", "thread")):
+                evidenceType = "messageThread"
+            sourceClass = next((item.get("sourceClass", "") for item in sourceClasses if item.get("ref") == ref), "")
+            typed.append({"ref": ref, "evidenceType": evidenceType, "sourceClass": sourceClass, "verificationStatus": "sourceBound" if doc.get("sha256") or doc.get("hash") or doc.get("source") else "unverified"})
+        if not typed and any(token in text.lower() for token in ("migration", "visa", "recruiter", "school", "offer letter")):
+            typed.append({"ref": "claimText", "evidenceType": "sourceSnapshot", "sourceClass": "userStatement", "verificationStatus": "unverified"})
+        return typed
+
+    @staticmethod
+    def _fraudIndicators(text: str, docs: list[Any], agentClaims: list[Any], sourceClasses: list[dict[str, str]]) -> list[dict[str, str]]:
+        indicators: list[dict[str, str]] = []
+        lowered = text.lower()
+        checks = (
+            ("guaranteedVisa", "critical", ("guaranteed visa", "guaranteed approval", "100% visa")),
+            ("urgencyPressure", "high", ("urgent payment", "pay today", "limited slot", "act now")),
+            ("informalPaymentRail", "high", ("western union", "crypto", "bitcoin", "gift card", "bank transfer only")),
+            ("identityMismatch", "high", ("mismatch", "different name", "name does not match")),
+            ("forgedDocument", "critical", ("forged", "fake document", "fake offer", "fake admission")),
+            ("unofficialChannel", "medium", ("whatsapp only", "gmail.com", "telegram only")),
+        )
+        for indicator, severity, tokens in checks:
+            if any(token in lowered for token in tokens):
+                indicators.append({"indicator": indicator, "severity": severity, "reason": "claimText", "evidenceRef": "claimText"})
+        if sourceClasses and not any(item.get("sourceClass") == "officialPortal" for item in sourceClasses):
+            indicators.append({"indicator": "officialSourceMissing", "severity": "medium", "reason": "noOfficialPortalSource", "evidenceRef": sourceClasses[0].get("ref", "claimText")})
+        for claim in agentClaims:
+            if isinstance(claim, dict) and str(claim.get("status", "")).lower() in {"unverified", "contested"}:
+                indicators.append({"indicator": "contestedAgentClaim", "severity": "high", "reason": str(claim.get("claim", "contested agent claim") or ""), "evidenceRef": "agentClaims"})
+        return indicators
+
+    @staticmethod
+    def _contradictions(text: str, docs: list[Any], agentClaims: list[Any]) -> list[dict[str, str]]:
+        contradictions: list[dict[str, str]] = []
+        lowered = text.lower()
+        if "fake offer" in lowered or "too good to be true" in lowered:
+            contradictions.append({"kind": "offerCredibility", "detail": "claim alleges fake or unrealistic offer"})
+        if "different name" in lowered or "mismatch" in lowered:
+            contradictions.append({"kind": "identityMismatch", "detail": "claim alleges document or actor mismatch"})
+        for claim in agentClaims:
+            if isinstance(claim, dict) and str(claim.get("status", "")).lower() in {"unverified", "contested"}:
+                contradictions.append({"kind": "agentClaim", "detail": str(claim.get("claim", "contested agent claim") or "")})
+        hashes = [str(item.get("sha256", item.get("hash", "")) or "") for item in docs if isinstance(item, dict)]
+        if hashes and len([item for item in hashes if item]) != len(set(item for item in hashes if item)):
+            contradictions.append({"kind": "duplicateDocumentHash", "detail": "document chain contains repeated hashes"})
+        return contradictions
+
+    @staticmethod
+    def _missingEvidence(text: str, docs: list[Any], *, profile: str = "", sourceClasses: list[dict[str, str]] | None = None, typedEvidence: list[dict[str, str]] | None = None) -> list[str]:
+        lowered = text.lower()
+        missing: list[str] = []
+        if "offer" in lowered and not any(isinstance(item, dict) and str(item.get("kind", "")) == "offer" for item in docs):
+            missing.append("offerSnapshot")
+        if not docs:
+            missing.append("sourceDocuments")
+        if not any(isinstance(item, dict) and str(item.get("sha256", item.get("hash", "")) or "") for item in docs):
+            missing.append("documentHashes")
+        if profile == "migrationTrust":
+            sourceClasses = sourceClasses or []
+            typedEvidence = typedEvidence or []
+            if not any(item.get("sourceClass") == "officialPortal" for item in sourceClasses):
+                missing.append("officialSourceSnapshot")
+            if any(item.get("evidenceType") == "offerLetter" for item in typedEvidence) and not any(item.get("sourceClass") in {"officialPortal", "school"} for item in sourceClasses):
+                missing.append("issuingInstitutionVerification")
+        return list(dict.fromkeys(missing))
+
+    @staticmethod
+    def _riskClass(text: str, contradictions: list[dict[str, str]], missing: list[str], agentClaims: list[Any], *, profile: str = "", fraudIndicators: list[dict[str, str]] | None = None) -> dict[str, str]:
+        lowered = text.lower()
+        fraudIndicators = fraudIndicators or []
+        if profile == "migrationTrust":
+            if any(item.get("severity") == "critical" for item in fraudIndicators) or any(token in lowered for token in ("scam", "fake offer", "fraud", "forged")):
+                return {"label": "migrationTrustFraudRisk", "severity": "critical"}
+            if fraudIndicators or contradictions:
+                return {"label": "migrationTrustReview", "severity": "high"}
+            if missing:
+                return {"label": "migrationTrustNeedsEvidence", "severity": "medium"}
+            return {"label": "migrationTrustSourceBound", "severity": "low"}
+        if any(token in lowered for token in ("scam", "fake offer", "fraud", "forged")):
+            return {"label": "scamTriage", "severity": "critical"}
+        if contradictions:
+            return {"label": "contestedFacts", "severity": "high"}
+        if any(token in lowered for token in ("damaged", "broken", "defective", "in-transit", "in transit", "transit")):
+            if any(token in lowered for token in ("followup", "follow up", "follow-up", "did not follow", "no response", "customer representative", "customer represent")):
+                return {"label": "damagedGoodsEscalation", "severity": "high"}
+            return {"label": "damagedGoodsClaim", "severity": "medium"}
+        if missing or agentClaims:
+            return {"label": "needsEvidence", "severity": "medium"}
+        return {"label": "routineDispute", "severity": "low"}
+
+    @staticmethod
+    def _triageConfidence(evidenceMap: list[dict[str, Any]], contradictions: list[dict[str, str]], missing: list[str]) -> float:
+        confidence = 0.45
+        if evidenceMap:
+            confidence += 0.20
+        if any(item.get("sourceBound") for item in evidenceMap):
+            confidence += 0.20
+        if contradictions:
+            confidence -= 0.05
+        if missing:
+            confidence -= min(0.20, 0.05 * len(missing))
+        return round(max(0.0, min(1.0, confidence)), 3)
+
+    @staticmethod
+    def _verificationStatus(evidenceMap: list[dict[str, Any]], sourceClasses: list[dict[str, str]], fraudIndicators: list[dict[str, str]], missing: list[str]) -> str:
+        if fraudIndicators and any(item.get("severity") in {"high", "critical"} for item in fraudIndicators):
+            return "needsHumanReview"
+        if missing:
+            return "needsSourceVerification"
+        if evidenceMap and any(item.get("sourceClass") == "officialPortal" for item in sourceClasses):
+            return "sourceBound"
+        return "unverified"
+
+    @staticmethod
+    def _caseOpsTimeline(profile: str, risk: dict[str, str], sourceClasses: list[dict[str, str]], fraudIndicators: list[dict[str, str]], missing: list[str]) -> list[dict[str, str]]:
+        if profile != "migrationTrust":
+            return []
+        timeline = [
+            {"stepId": "case_intake", "status": "completed", "owner": "resolve", "label": "Claim captured"},
+            {"stepId": "source_classification", "status": "completed" if sourceClasses else "needsInput", "owner": "hunt", "label": "Source classes assigned"},
+            {"stepId": "fraud_screen", "status": "completed" if fraudIndicators else "noFinding", "owner": "resolve", "label": "Fraud indicators screened"},
+        ]
+        if missing:
+            timeline.append({"stepId": "request_missing_evidence", "status": "needsInput", "owner": "proxy", "label": "Request missing evidence"})
+        if risk.get("severity") in {"high", "critical"} or fraudIndicators:
+            timeline.append({"stepId": "human_review", "status": "awaitingProxy", "owner": "proxy", "label": "Route to human reviewer"})
+        return timeline
+
+    @staticmethod
+    def _nextAction(risk: dict[str, str], missing: list[str], contradictions: list[dict[str, str]], fraudIndicators: list[dict[str, str]] | None = None) -> str:
+        if fraudIndicators or risk.get("severity") in {"high", "critical"}:
+            return "escalateToHumanReviewer"
+        if missing:
+            return "requestMissingEvidence"
+        if contradictions or risk.get("severity") in {"high", "critical"}:
+            return "escalateToHumanReviewer"
+        return "prepareClaimOrAuditSummary"

picux/orchestrator/__init__.py

@@ -0,0 +1,3 @@
+from .engine import PicuxMultiAgentOrchestrator
+
+__all__ = ["PicuxMultiAgentOrchestrator"]