patchr 0.1.0__py3-none-any.whl

picux/domains/hunt/engine.py

@@ -0,0 +1,307 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any
+
+from .models import HuntCriteria, HuntOffer
+
+
+class HuntDomain:
+    """Deterministic discovery and ranking for HUNT telemetry."""
+
+    def discover(self, payload: dict[str, Any]) -> dict[str, Any]:
+        criteria = HuntCriteria.fromObj(payload.get("criteria") if isinstance(payload.get("criteria"), dict) else payload)
+        offers = [
+            HuntOffer.fromObj(item)
+            for item in payload.get("offers", payload.get("telemetry", []))
+            if isinstance(item, dict)
+        ]
+        candidates = [self.scoreOffer(offer, criteria) for offer in offers]
+        candidates.sort(key=lambda item: (item["eligible"], item["score"], -item["netUsd"]), reverse=True)
+        selected = next((item for item in candidates if item["eligible"]), None)
+        sourceResponse = self.sourceResponse(payload, offers, candidates, selected)
+        handoff = self.handoff(payload)
+        aggregate = self.sourceAggregate(payload, offers, candidates, selected, sourceResponse, handoff)
+        stream = self.streamEvents(aggregate)
+        return {
+            "ok": bool(selected),
+            "criteria": criteria.toMap(),
+            "selected": selected or {},
+            "candidates": candidates,
+            "sourceResponse": sourceResponse,
+            "sourceAggregate": aggregate,
+            "aggregate": aggregate,
+            "stream": stream,
+            "handoff": handoff,
+            "response": {
+                "status": "selected" if selected else sourceResponse["status"],
+                "message": self.responseMessage(sourceResponse, selected),
+                "nextAction": "returnSelectedOption" if selected else "requestBetterSourceTelemetry",
+                "delivery": aggregate["delivery"],
+            },
+            "trace": self.trace(candidates),
+        }
+
+    def scoreOffer(self, offer: HuntOffer | dict[str, Any], criteria: HuntCriteria | dict[str, Any]) -> dict[str, Any]:
+        item = offer if isinstance(offer, HuntOffer) else HuntOffer.fromObj(offer)
+        crit = criteria if isinstance(criteria, HuntCriteria) else HuntCriteria.fromObj(criteria)
+        reasons = self.reasons(item, crit)
+        latencyPenalty = min(20.0, item.latencyMs / 50.0) if item.latencyMs > 0 else 0.0
+        feePenalty = min(30.0, item.feesUsd)
+        stockBoost = min(10.0, max(0, item.stock) / 10.0)
+        score = round(max(0.0, item.discountPct + stockBoost - latencyPenalty - feePenalty), 3)
+        return {
+            **item.toMap(),
+            "eligible": not reasons,
+            "reasons": reasons,
+            "score": score,
+            "povRules": self.povRules(item, crit, reasons),
+        }
+
+    def reasons(self, offer: HuntOffer, criteria: HuntCriteria) -> list[str]:
+        reasons: list[str] = []
+        if criteria.itemId and offer.itemId != criteria.itemId:
+            reasons.append("itemMismatch")
+        if offer.discountPct < criteria.minDiscountPct:
+            reasons.append("discountBelowThreshold")
+        if criteria.maxNetUsd > 0 and offer.netUsd > criteria.maxNetUsd:
+            reasons.append("overBudget")
+        if offer.stock < criteria.minStock:
+            reasons.append("stockLimit")
+        if criteria.region and offer.region != criteria.region:
+            reasons.append("regionMismatch")
+        if criteria.maxLatencyMs > 0 and offer.latencyMs > criteria.maxLatencyMs:
+            reasons.append("latencyExceeded")
+        if offer.feesUsd > 0:
+            reasons.append("feeLeak")
+        return reasons
+
+    @staticmethod
+    def povRules(offer: HuntOffer, criteria: HuntCriteria, reasons: list[str]) -> list[str]:
+        rules = []
+        if offer.stock >= criteria.minStock:
+            rules.append("inventoryVerified")
+        if criteria.minDiscountPct > 0 and offer.discountPct >= criteria.minDiscountPct:
+            rules.append(f"priceArbitrage{int(criteria.minDiscountPct)}")
+        if criteria.region and offer.region == criteria.region:
+            rules.append("regionMatched")
+        if offer.feesUsd <= 0:
+            rules.append("hiddenFeeClear")
+        if not reasons:
+            rules.append("huntEligible")
+        return rules
+
+    @staticmethod
+    def trace(candidates: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        events = []
+        for idx, candidate in enumerate(candidates, start=1):
+            events.append(
+                {
+                    "step": idx,
+                    "phase": "hunt",
+                    "name": "candidateRanked" if candidate["eligible"] else "candidatePruned",
+                    "status": "selected" if idx == 1 and candidate["eligible"] else "observed",
+                    "sourceId": candidate["sourceId"],
+                    "score": candidate["score"],
+                    "reasons": candidate["reasons"],
+                }
+            )
+        return events
+
+    @staticmethod
+    def sourceResponse(payload: dict[str, Any], offers: list[HuntOffer], candidates: list[dict[str, Any]], selected: dict[str, Any] | None) -> dict[str, Any]:
+        sourceTelemetry = payload.get("sourceTelemetry", {}) if isinstance(payload.get("sourceTelemetry"), dict) else {}
+        attempts = sourceTelemetry.get("attempts", []) if isinstance(sourceTelemetry.get("attempts"), list) else []
+        targetSources = [str(item) for item in sourceTelemetry.get("targetSources", []) if str(item)]
+        attemptedSources = [str(item.get("source", "")) for item in attempts if isinstance(item, dict) and item.get("source")]
+        failedSources = [str(item.get("source", "")) for item in attempts if isinstance(item, dict) and item.get("source") and not item.get("ok")]
+        successfulSources = [str(item.get("source", "")) for item in attempts if isinstance(item, dict) and item.get("source") and item.get("ok")]
+        listingSources = [str(item.get("source", "")) for item in attempts if isinstance(item, dict) and item.get("source") and int(item.get("listingCount", 0) or 0) > 0]
+        resultSources = [str(offer.meta.get("source", offer.sourceId) or offer.sourceId) for offer in offers]
+        listingCount = sum(int(item.get("listingCount", 0) or 0) for item in attempts if isinstance(item, dict))
+        filteredListingCount = sum(int(item.get("filteredListingCount", 0) or 0) for item in attempts if isinstance(item, dict))
+        marketplaceSet = sourceTelemetry.get("marketplaceSet", {}) if isinstance(sourceTelemetry.get("marketplaceSet"), dict) else {}
+        budget = sourceTelemetry.get("budget", {}) if isinstance(sourceTelemetry.get("budget"), dict) else {}
+        fx = sourceTelemetry.get("fx", {}) if isinstance(sourceTelemetry.get("fx"), dict) else {}
+        if selected:
+            status = "selected"
+        elif offers or candidates:
+            status = "noEligibleCandidate"
+        elif sourceTelemetry.get("networkAttempted"):
+            status = "searchedNoSourceBoundOffer"
+        else:
+            status = "needsSourceTelemetry"
+        return {
+            "status": status,
+            "adapter": sourceTelemetry.get("adapter", ""),
+            "rendered": sourceTelemetry.get("rendered", {}),
+            "marketplaceSet": marketplaceSet,
+            "budget": budget,
+            "fx": fx,
+            "targetSources": targetSources,
+            "attemptedSources": list(dict.fromkeys(attemptedSources)),
+            "successfulSources": list(dict.fromkeys(successfulSources)),
+            "failedSources": list(dict.fromkeys(failedSources)),
+            "listingSources": list(dict.fromkeys(listingSources)),
+            "resultSources": list(dict.fromkeys(resultSources)),
+            "networkAttempted": bool(sourceTelemetry.get("networkAttempted")),
+            "offerCount": int(sourceTelemetry.get("offerCount", len(offers)) or 0),
+            "listingCount": listingCount,
+            "filteredListingCount": filteredListingCount,
+            "candidateCount": len(candidates),
+            "selectedSourceId": str(selected.get("sourceId", "") if selected else ""),
+        }
+
+    @staticmethod
+    def responseMessage(sourceResponse: dict[str, Any], selected: dict[str, Any] | None) -> str:
+        if selected:
+            return f"HUNT selected {selected.get('sourceId', '')} from source-bound telemetry."
+        targets = ", ".join(sourceResponse.get("targetSources", [])[:6])
+        if sourceResponse.get("networkAttempted"):
+            return f"HUNT searched {targets} and returned no eligible source-bound offer."
+        return f"HUNT prepared source targets {targets}; live source telemetry is required before ranking."
+
+    @staticmethod
+    def handoff(payload: dict[str, Any]) -> dict[str, str]:
+        raw = payload.get("handoff", payload.get("handsoff", {}))
+        raw = raw if isinstance(raw, dict) else {}
+        explicitSource = raw.get("source") or payload.get("handoffSource") or payload.get("handsoffSource")
+        source = str(explicitSource or payload.get("clientId", "orchestrator") or "orchestrator")
+        explicitTarget = raw.get("target") or payload.get("handoffTarget") or payload.get("handsoffTarget")
+        target = str(explicitTarget or (source if explicitSource else "orchestrator") or "orchestrator")
+        if target in {"source", "handoffSource", "handsoffSource"}:
+            target = source
+        return {
+            "source": source,
+            "target": target,
+            "channel": str(raw.get("channel", payload.get("handoffChannel", payload.get("channel", "api"))) or "api"),
+            "mode": str(raw.get("mode", payload.get("handoffMode", "return")) or "return"),
+        }
+
+    @staticmethod
+    def sourceAggregate(
+        payload: dict[str, Any],
+        offers: list[HuntOffer],
+        candidates: list[dict[str, Any]],
+        selected: dict[str, Any] | None,
+        sourceResponse: dict[str, Any],
+        handoff: dict[str, str],
+    ) -> dict[str, Any]:
+        sourceTelemetry = payload.get("sourceTelemetry", {}) if isinstance(payload.get("sourceTelemetry"), dict) else {}
+        attempts = sourceTelemetry.get("attempts", []) if isinstance(sourceTelemetry.get("attempts"), list) else []
+        observations = sourceTelemetry.get("observations", []) if isinstance(sourceTelemetry.get("observations"), list) else []
+        sources = HuntDomain.aggregateSources(sourceResponse, attempts, offers)
+        deliveryMode = handoff.get("mode", "return")
+        aggregate = {
+            "kind": "huntSourceAggregate",
+            "aggregateId": "",
+            "status": sourceResponse.get("status", ""),
+            "handoff": handoff,
+            "delivery": {
+                "mode": deliveryMode,
+                "target": handoff.get("target", "orchestrator"),
+                "channel": handoff.get("channel", "api"),
+                "status": "streamReady" if deliveryMode == "stream" else "returned",
+            },
+            "marketplaceSet": sourceResponse.get("marketplaceSet", {}),
+            "budget": sourceResponse.get("budget", {}),
+            "fx": sourceResponse.get("fx", {}),
+            "adapter": sourceResponse.get("adapter", ""),
+            "rendered": sourceResponse.get("rendered", {}),
+            "sources": sources,
+            "observations": observations[:24],
+            "offers": [offer.toMap() for offer in offers[:24]],
+            "candidates": candidates[:24],
+            "result": {
+                "selected": selected or {},
+                "selectedSourceId": sourceResponse.get("selectedSourceId", ""),
+                "candidateCount": len(candidates),
+                "offerCount": sourceResponse.get("offerCount", 0),
+                "nextAction": "returnSelectedOption" if selected else "requestBetterSourceTelemetry",
+            },
+        }
+        aggregate["aggregateId"] = "huntAgg_" + hashlib.sha256(json.dumps(aggregate, sort_keys=True, default=str).encode("utf-8")).hexdigest()[:24]
+        return aggregate
+
+    @staticmethod
+    def aggregateSources(sourceResponse: dict[str, Any], attempts: list[Any], offers: list[HuntOffer]) -> list[dict[str, Any]]:
+        records: dict[str, dict[str, Any]] = {}
+        for source in sourceResponse.get("targetSources", []):
+            sourceId = str(source)
+            if sourceId:
+                records[sourceId] = {"source": sourceId, "status": "targeted", "ok": False, "attempted": False}
+        for attempt in attempts:
+            if not isinstance(attempt, dict):
+                continue
+            sourceId = str(attempt.get("source", "") or "")
+            if not sourceId:
+                continue
+            records[sourceId] = {
+                "source": sourceId,
+                "status": "read" if attempt.get("ok") else "failed",
+                "ok": bool(attempt.get("ok")),
+                "attempted": True,
+                "url": attempt.get("url", ""),
+                "statusCode": attempt.get("statusCode", 0),
+                "title": attempt.get("title", ""),
+                "matched": bool(attempt.get("matched")),
+                "listingCount": attempt.get("listingCount", 0),
+                "search": attempt.get("search", {}) if isinstance(attempt.get("search"), dict) else {},
+                "error": attempt.get("error", ""),
+            }
+        for offer in offers:
+            sourceId = str(offer.meta.get("source", offer.sourceId) or offer.sourceId)
+            if sourceId and sourceId not in records:
+                records[sourceId] = {"source": sourceId, "status": "candidateOnly", "ok": True, "attempted": False}
+            if sourceId:
+                records[sourceId]["offerCount"] = int(records[sourceId].get("offerCount", 0) or 0) + 1
+                records[sourceId]["ok"] = True
+        return list(records.values())
+
+    @staticmethod
+    def streamEvents(aggregate: dict[str, Any]) -> list[dict[str, Any]]:
+        events = [
+            {
+                "seq": 1,
+                "phase": "hunt",
+                "name": "sourceAggregate.started",
+                "status": "started",
+                "target": aggregate["delivery"]["target"],
+                "data": {"aggregateId": aggregate["aggregateId"], "sourceCount": len(aggregate.get("sources", []))},
+            }
+        ]
+        for source in aggregate.get("sources", []):
+            name = "source.read" if source.get("ok") else ("source.failed" if source.get("attempted") else "source.targeted")
+            events.append(
+                {
+                    "seq": len(events) + 1,
+                    "phase": "hunt",
+                    "name": name,
+                    "status": source.get("status", ""),
+                    "target": aggregate["delivery"]["target"],
+                    "data": source,
+                }
+            )
+        for candidate in aggregate.get("candidates", []):
+            events.append(
+                {
+                    "seq": len(events) + 1,
+                    "phase": "hunt",
+                    "name": "candidate.selected" if candidate.get("eligible") else "candidate.pruned",
+                    "status": "selected" if candidate.get("eligible") and candidate.get("sourceId") == aggregate["result"].get("selectedSourceId") else "observed",
+                    "target": aggregate["delivery"]["target"],
+                    "data": {"sourceId": candidate.get("sourceId", ""), "score": candidate.get("score", 0), "reasons": candidate.get("reasons", [])},
+                }
+            )
+        events.append(
+            {
+                "seq": len(events) + 1,
+                "phase": "hunt",
+                "name": "sourceAggregate.delivered",
+                "status": aggregate["delivery"]["status"],
+                "target": aggregate["delivery"]["target"],
+                "data": {"aggregateId": aggregate["aggregateId"], "result": aggregate["result"], "delivery": aggregate["delivery"]},
+            }
+        )
+        return events

picux/domains/hunt/models.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class HuntOffer:
+    sourceId: str
+    itemId: str
+    listUsd: float
+    offerUsd: float
+    feesUsd: float = 0.0
+    stock: int = 0
+    region: str = ""
+    latencyMs: int = 0
+    meta: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def fromObj(cls, value: dict[str, Any]) -> "HuntOffer":
+        return cls(
+            sourceId=str(value.get("sourceId", value.get("vendorId", "")) or ""),
+            itemId=str(value.get("itemId", value.get("sku", "")) or ""),
+            listUsd=float(value.get("listUsd", value.get("listPriceUsd", 0.0)) or 0.0),
+            offerUsd=float(value.get("offerUsd", value.get("priceUsd", 0.0)) or 0.0),
+            feesUsd=float(value.get("feesUsd", value.get("hiddenFeeUsd", 0.0)) or 0.0),
+            stock=int(value.get("stock", value.get("qty", 0)) or 0),
+            region=str(value.get("region", "") or ""),
+            latencyMs=int(value.get("latencyMs", 0) or 0),
+            meta=value.get("meta", {}) if isinstance(value.get("meta", {}), dict) else {},
+        )
+
+    @property
+    def netUsd(self) -> float:
+        return round(max(0.0, self.offerUsd + self.feesUsd), 2)
+
+    @property
+    def discountPct(self) -> float:
+        if self.listUsd <= 0:
+            return 0.0
+        return round(((self.listUsd - self.offerUsd) / self.listUsd) * 100, 2)
+
+    def toMap(self) -> dict[str, Any]:
+        return {
+            "sourceId": self.sourceId,
+            "itemId": self.itemId,
+            "listUsd": round(self.listUsd, 2),
+            "offerUsd": round(self.offerUsd, 2),
+            "feesUsd": round(self.feesUsd, 2),
+            "netUsd": self.netUsd,
+            "discountPct": self.discountPct,
+            "stock": self.stock,
+            "region": self.region,
+            "latencyMs": self.latencyMs,
+            "meta": self.meta,
+        }
+
+
+@dataclass(frozen=True)
+class HuntCriteria:
+    itemId: str = ""
+    minDiscountPct: float = 0.0
+    maxNetUsd: float = 0.0
+    minStock: int = 1
+    region: str = ""
+    maxLatencyMs: int = 0
+
+    @classmethod
+    def fromObj(cls, value: dict[str, Any] | None) -> "HuntCriteria":
+        value = value or {}
+        return cls(
+            itemId=str(value.get("itemId", value.get("sku", "")) or ""),
+            minDiscountPct=float(value.get("minDiscountPct", 0.0) or 0.0),
+            maxNetUsd=float(value.get("maxNetUsd", 0.0) or 0.0),
+            minStock=int(value.get("minStock", 1) or 1),
+            region=str(value.get("region", "") or ""),
+            maxLatencyMs=int(value.get("maxLatencyMs", 0) or 0),
+        )
+
+    def toMap(self) -> dict[str, Any]:
+        return {
+            "itemId": self.itemId,
+            "minDiscountPct": round(self.minDiscountPct, 2),
+            "maxNetUsd": round(self.maxNetUsd, 2),
+            "minStock": self.minStock,
+            "region": self.region,
+            "maxLatencyMs": self.maxLatencyMs,
+        }

picux/domains/pay/__init__.py

@@ -0,0 +1,16 @@
+"""PAY domain primitives."""
+
+from .adapters import PayRailAdapter, PayRailAdapterContext
+from .engine import PayDomain
+from .models import Money, ProofOfValue, SettlementAdapter, SettlementAdapterSpec, SettlementRequest
+
+__all__ = [
+    "Money",
+    "PayDomain",
+    "PayRailAdapter",
+    "PayRailAdapterContext",
+    "ProofOfValue",
+    "SettlementAdapter",
+    "SettlementAdapterSpec",
+    "SettlementRequest",
+]