CI deploy 0c6476e

amanpay/agentic_orchestration/agents.py

@@ -0,0 +1,89 @@
+"""Bounded PR C2 agents — Context, Risk, Auth-Rec, Rail, Explanation.
+
+Each agent is a reasoning-only actor (PR B registry `can_execute_payment=False`). It produces a
+STRUCTURED, validated output and never carries authority. Tool-using agents (Context, Risk, Rail)
+reach data/models only through the PR B `ToolGateway` with a PoP-checked `CapabilityGrant`.
+
+Authority reminders (enforced by the orchestrator + PDP):
+  * Risk Agent output is ADVISORY (recommend_step_up may only add caution).
+  * Auth-Rec Agent may recommend only a method meeting/exceeding the PDP minimum.
+  * Rail Agent ranks only eligible/available rails.
+  * Explanation Agent renders reason codes; it cannot change decisions.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Dict, List, Optional
+
+from amanpay.agentic_orchestration import schemas
+from amanpay.agentic_orchestration.tools import (
+    TOOL_FEATURES, TOOL_RAIL_OPTIONS, TOOL_RISK_MODEL, ToolClient,
+)
+from amanpay.agentic_risk.reason_codes import render, validate as validate_codes
+
+# Assurance ordering is CONTEXT-SENSITIVE (see AGENT_ARCHITECTURE); this rank is used only to
+# reject a recommendation that is *below* the PDP minimum, never to assert a universal hierarchy.
+_ASSURANCE_RANK = {"trusted_session": 0, "webauthn": 2, "oob": 2, "webauthn+oob": 3,
+                   "manual_review": 4}
+
+
+class ContextAgent:
+    spiffe = "spiffe://amanpay/agent/context"
+
+    def run(self, client: ToolClient, cap, txn_id: str, *, now: float, intent_hash: str) -> Dict:
+        out = client.call(cap, TOOL_FEATURES, {"txn_id": txn_id}, now=now, intent_hash=intent_hash)
+        return schemas.validate_context(out)
+
+
+class RiskAgent:
+    spiffe = "spiffe://amanpay/agent/risk"
+
+    def run(self, client: ToolClient, cap, txn_id: str, *, now: float, intent_hash: str) -> Dict:
+        out = client.call(cap, TOOL_RISK_MODEL, {"txn_id": txn_id}, now=now, intent_hash=intent_hash)
+        return schemas.validate_risk(out)          # advisory only
+
+
+class AuthRecommendationAgent:
+    spiffe = "spiffe://amanpay/agent/auth"
+
+    def run(self, *, pdp_required: List[str], risk_band: str,
+            supported: List[str]) -> Dict:
+        """Recommend a method that MEETS/EXCEEDS the PDP minimum. Never weakens it."""
+        min_rank = max((_ASSURANCE_RANK.get(m, 0) for m in pdp_required), default=0)
+        # prefer the least-intrusive supported method that still meets the minimum
+        eligible = [m for m in supported
+                    if _ASSURANCE_RANK.get(m, 0) >= min_rank]
+        # elevated/high risk -> lean to a stronger eligible method
+        if risk_band in ("elevated", "high") and "webauthn+oob" in supported:
+            rec = "webauthn+oob"
+        elif eligible:
+            rec = sorted(eligible, key=lambda m: _ASSURANCE_RANK.get(m, 0))[0]
+        else:
+            rec = "manual_review"
+        meets = _ASSURANCE_RANK.get(rec, 0) >= min_rank
+        return schemas.validate_auth({"recommended_method": rec, "meets_pdp_minimum": bool(meets)})
+
+
+class RailRecommendationAgent:
+    spiffe = "spiffe://amanpay/agent/rail"
+
+    def run(self, client: ToolClient, cap, *, country: str, currency: str, now: float,
+            intent_hash: str, user_pref: str = "") -> Dict:
+        opts = client.call(cap, TOOL_RAIL_OPTIONS, {"country": country, "currency": currency},
+                           now=now, intent_hash=intent_hash)
+        rails = list(opts.get("rails", []))
+        # order signals: user preference first, otherwise stable configured order (eligibility
+        # already applied by the tool). Never adds a rail not returned by the tool.
+        ranked = sorted(rails, key=lambda r: (0 if r == user_pref else 1))
+        return schemas.validate_rail({"ranked": ranked, "eligible_only": True})
+
+
+class ExplanationAgent:
+    spiffe = "spiffe://amanpay/agent/explain"
+
+    def run(self, *, reason_codes: List[str], locale: str = "en") -> Dict:
+        codes = validate_codes(reason_codes)        # allowlist only; no invented codes
+        messages = [render(c, locale) for c in codes]
+        return schemas.validate_explanation({"locale": locale, "messages": messages,
+                                             "reason_codes": codes})

amanpay/agentic_orchestration/api.py

@@ -0,0 +1,85 @@
+"""Internal /ai/v1 API surface for PR C2 (labelled demo).
+
+Per the checkpoint API-exposure classification, the per-agent endpoints (context/risk/auth/rails/
+explain) are internal-only and are NOT exposed as public HTTP routes. This module exposes only:
+  * GET  /ai/v1/models/status   — safe aggregate status (no scores/thresholds).
+  * POST /ai/v1/demo/payee      — register a demo payee (returns ref, never the raw IBAN).
+  * POST /ai/v1/demo/orchestrate — run the secured agent workflow (mock provider, shadow model).
+
+The demo endpoint is gated: it runs only when AMANPAY_ENABLE_AI_DEMO is truthy (default on for the
+trusted HF demo; disable in real production). It exposes no keys/capabilities/approval secrets/raw
+IBANs and cannot mint execution capabilities or move real money.
+"""
+
+from __future__ import annotations
+
+import os
+import time
+
+from fastapi import APIRouter, Body, HTTPException
+
+from amanpay.agentic_orchestration.orchestrator import DEMO_LABEL, SecureAgentOrchestrator
+from amanpay.agentic_risk.features import UserHistory
+from amanpay.agentic_risk.reason_codes import REASON_CODES_VERSION
+from amanpay.agentic_risk.features import FEATURE_SCHEMA_VERSION
+
+router = APIRouter(prefix="/ai/v1", tags=["agentic-risk"])
+
+_orch = SecureAgentOrchestrator()
+
+
+def _demo_enabled() -> bool:
+    v = os.getenv("AMANPAY_ENABLE_AI_DEMO", "1").strip().lower()
+    return v not in ("", "0", "false", "no")
+
+
+@router.get("/models/status")
+def models_status() -> dict:
+    """Safe status — versions + shadow flag, NO scores or thresholds."""
+    return {"behavioural_model": _orch.shadow.model.name if _orch.shadow.model else "none",
+            "model_version": _orch.shadow.model.version if _orch.shadow.model else "none",
+            "feature_version": FEATURE_SCHEMA_VERSION,
+            "reason_codes_version": REASON_CODES_VERSION,
+            "shadow_only": True, "affects_payment": False, "label": DEMO_LABEL}
+
+
+@router.post("/demo/payee")
+def demo_payee(body: dict = Body(...)) -> dict:
+    try:
+        p = _orch.base.payees.register(body["iban"], country=body.get("country", "SA"))
+    except (KeyError, ValueError) as exc:
+        raise HTTPException(status_code=422, detail=str(exc))
+    return {"payee_ref": p.payee_ref, "display": p.display, "label": DEMO_LABEL}
+
+
+@router.post("/demo/orchestrate")
+def demo_orchestrate(body: dict = Body(...)) -> dict:
+    if not _demo_enabled():
+        raise HTTPException(status_code=403, detail="AI demo disabled")
+    try:
+        hist = UserHistory(
+            payments=int(body.get("history_payments", 20)),
+            payees=set(body.get("known_payees", [])),
+            merchants=set(body.get("known_merchants", ["m1"])),
+            amount_mean=float(body.get("amount_mean", 5000)),
+            amount_std=float(body.get("amount_std", 1500)),
+            hour_hist={int(body.get("usual_hour", 12)): 10},
+            recent_24h=int(body.get("recent_24h", 1)),
+            device_trust_days=float(body.get("device_trust_days", 200)),
+            rail_pref=body.get("rail_pref", "sarie"))
+        r = _orch.run(user_id=body.get("user_id", "demo"), payee_ref=body["payee_ref"],
+                      amount_minor=int(body["amount_minor"]), hist=hist,
+                      consent=bool(body.get("consent", True)),
+                      approve=bool(body.get("approve", False)),
+                      country=body.get("country", "SA"), currency=body.get("currency", "SAR"),
+                      merchant=body.get("merchant", "m1"),
+                      now=float(body.get("now", time.time())), locale=body.get("locale", "en"))
+    except (KeyError, ValueError) as exc:
+        raise HTTPException(status_code=422, detail=str(exc))
+    # Return only safe fields (no keys/capabilities/approval secrets/raw IBAN).
+    return {"decision": r.decision, "reason_codes": r.reason_codes,
+            "required_auth": r.required_auth, "agent_state": r.agent_state,
+            "risk": r.risk, "auth_recommendation": r.auth_recommendation,
+            "rails": r.rails, "explanation": r.explanation,
+            "payment": r.payment, "audit": r.audit, "fallback": r.fallback,
+            "labels": r.labels}

amanpay/agentic_orchestration/orchestrator.py

@@ -0,0 +1,239 @@
+"""PR C2 — Secure Agent Orchestration.
+
+Runs the bounded agents through PR B security (identities, signed AgentMessages, PoP-checked
+capabilities, ToolGateway, ReplayStore, AuditChain, budgets) and feeds their outputs to the
+deterministic PR B PDP, which stays authoritative. The C1 behavioural-risk model runs in SHADOW —
+its output is an advisory input (`recommend_step_up`) that can only ADD caution.
+
+Guarantees (tested): Risk Agent cannot call Payment Core; agent "allow" cannot override a PDP deny;
+agent cannot lower a PDP step-up; malformed/absent agent output falls back to deterministic policy;
+only Payment Core initiates.
+"""
+
+from __future__ import annotations
+
+import secrets
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional
+
+from amanpay.agent_security import envelopes as E
+from amanpay.agent_security.budgets import AgentBudget, BudgetExceeded
+from amanpay.agent_security.gateway import MessageRejected, ToolError, validate_message
+from amanpay.agent_security.orchestrator import AgentPaymentOrchestrator, ENV
+from amanpay.agentic_orchestration import schemas
+from amanpay.agentic_orchestration.agents import (
+    AuthRecommendationAgent, ContextAgent, ExplanationAgent, RailRecommendationAgent, RiskAgent,
+)
+from amanpay.agentic_orchestration.tools import (
+    TOOL_FEATURES, TOOL_RAIL_OPTIONS, TOOL_RISK_MODEL, ToolClient, register_tools,
+)
+from amanpay.agentic_risk.calibration import PlattCalibrator
+from amanpay.agentic_risk.evaluation import temporal_user_split
+from amanpay.agentic_risk.features import FeatureProvider, Transaction, UserHistory
+from amanpay.agentic_risk.models import LogisticRegression
+from amanpay.agentic_risk.shadow import ShadowRiskService
+from amanpay.agentic_risk.synthetic import SyntheticConfig, generate
+
+DEMO_LABEL = ("DEMO ONLY — local identity issuer, mock agents, mock provider, shadow-only "
+              "behavioural model (no payment authority), no real-money authority.")
+
+
+def _default_shadow() -> ShadowRiskService:
+    """Fit the C1 logistic model on deterministic synthetic data for the demo (shadow-only)."""
+    import numpy as np
+    ex = generate(SyntheticConfig(n_users=40, seed=1234))
+    fp = FeatureProvider()
+    X = np.array([fp.derive(e.hist, e.txn)["vector"] for e in ex])
+    y = np.array([e.label for e in ex])
+    uid = np.array([e.user_id for e in ex]); t = np.array([e.t for e in ex])
+    tr, _ = temporal_user_split(uid, t, test_frac=0.3)
+    m = LogisticRegression().fit(X[tr], y[tr])
+    cal = PlattCalibrator().fit(m.predict_proba(X[tr]), y[tr])
+    return ShadowRiskService(m, cal)
+
+
+@dataclass
+class OrchestrationResult:
+    decision: str
+    reason_codes: List[str]
+    required_auth: List[str]
+    agent_state: str
+    context: Optional[Dict] = None
+    risk: Optional[Dict] = None
+    auth_recommendation: Optional[Dict] = None
+    rails: Optional[Dict] = None
+    explanation: Optional[Dict] = None
+    payment: Optional[Dict] = None
+    audit: Optional[Dict] = None
+    fallback: Optional[str] = None
+    labels: Dict[str, str] = field(default_factory=lambda: {"note": DEMO_LABEL})
+
+
+class SecureAgentOrchestrator:
+    """Composes the PR B payment orchestrator + C1 shadow model + the C2 agent layer."""
+
+    def __init__(self, shadow: Optional[ShadowRiskService] = None) -> None:
+        self.base = AgentPaymentOrchestrator()            # PR B: keyring/issuer/pdp/replay/audit/core
+        self.shadow = shadow or _default_shadow()
+        self.gw = __import__("amanpay.agent_security.gateway", fromlist=["ToolGateway"]).ToolGateway(
+            self.base.kr, self.base.replay, env=ENV)
+        self._txns: Dict[str, Dict] = {}                  # txn_id -> {hist, txn, consent}
+        register_tools(self.gw, features_handler=self._features, risk_handler=self._risk,
+                       rail_handler=self._rails)
+        # short-lived agent identities (PR B LocalDemoIssuer)
+        self.ids = {a: self.base.issuer.issue(a, now=0.0, ttl=1_000_000.0)
+                    for a in ("spiffe://amanpay/agent/context", "spiffe://amanpay/agent/risk",
+                              "spiffe://amanpay/agent/rail")}
+        self.context_agent = ContextAgent(); self.risk_agent = RiskAgent()
+        self.auth_agent = AuthRecommendationAgent(); self.rail_agent = RailRecommendationAgent()
+        self.explain_agent = ExplanationAgent()
+
+    # -- tool handlers (resolve behavioural data by txn_id from the trusted store) ------ #
+    def _features(self, args: Dict, ctx: Dict) -> Dict:
+        rec = self._txns[args["txn_id"]]
+        f = FeatureProvider().derive(rec["hist"], rec["txn"])
+        return {"channel": rec.get("channel", "app"), "recent_count": int(rec["hist"].recent_24h),
+                "cold_start": bool(f["cold_start"]), "missing": list(f["missing"]),
+                "feature_version": f["schema_version"]}
+
+    def _risk(self, args: Dict, ctx: Dict) -> Dict:
+        rec = self._txns[args["txn_id"]]
+        a = self.shadow.assess(rec["hist"], rec["txn"], consent=rec["consent"])
+        return {"band": a.band,
+                "recommend_step_up": a.band in ("elevated", "high", "uncertain")
+                                     or a.confidence == "uncertain",
+                "reason_codes": a.reason_codes, "confidence": a.confidence,
+                "model_version": a.model_version, "feature_version": a.feature_version,
+                "shadow": bool(a.shadow)}
+
+    def _rails(self, args: Dict, ctx: Dict) -> Dict:
+        rails = self.base.provider.rails_by_country.get(args["country"].upper(), [])
+        return {"rails": list(rails), "eligible_only": True}
+
+    def _cap(self, subject_spiffe: str, cnf_kid: str, audience: str, intent, *, now: float):
+        return E.make_capability(
+            self.base.kr, kid=self.base.pdp_k.kid, issuer="spiffe://amanpay/pdp", key_version=1,
+            env=ENV, subject_agent=subject_spiffe, cnf=cnf_kid, audience=audience,
+            operation=audience, resource=intent.intent_id, intent_id=intent.intent_id,
+            intent_hash=intent.intent_hash, now=now)
+
+    def _msg(self, sender: str, recipient: str, mtype: str, payload: Dict, intent, flow: str,
+             *, now: float) -> None:
+        """Send + validate one signed AgentMessage (proves the PR B envelope path)."""
+        kid = self.ids[sender].kid if sender in self.ids else self.base.pdp_k.kid
+        m = E.make_message(self.base.kr, kid=kid, sender=sender, recipient=recipient,
+                           audience=recipient, intent_id=intent.intent_id,
+                           intent_hash=intent.intent_hash, message_type=mtype, payload=payload,
+                           flow_id=flow, env=ENV, now=now)
+        validate_message(self.base.kr, self.base.replay, m, now=now, env=ENV,
+                         expected_intent_hash=intent.intent_hash, expected_flow_id=flow)
+
+    # -- the secured workflow ----------------------------------------------------------- #
+    def run(self, *, user_id: str, payee_ref: str, amount_minor: int, hist: UserHistory,
+            consent: bool = True, approve: bool = False, country: str = "SA",
+            currency: str = "SAR", merchant: str = "m1", now: float = 1000.0,
+            locale: str = "en") -> OrchestrationResult:
+        payee = self.base.payees.get(payee_ref)
+        if payee is None:
+            raise ValueError("unknown payee_ref")
+        flow = "flow_" + secrets.token_hex(6)
+        txn_id = "txn_" + secrets.token_hex(6)
+        txn = Transaction(amount_minor=amount_minor, hour=int(now // 3600) % 24,
+                          payee_ref=payee_ref, merchant=merchant, country=country,
+                          currency=currency, rail="sarie", country_currency_ok=True)
+        self._txns[txn_id] = {"hist": hist, "txn": txn, "consent": consent, "channel": "app"}
+
+        intent = E.make_intent(
+            self.base.kr, kid=self.base.fe_k.kid, issuer="spiffe://amanpay/frontend", key_version=1,
+            env=ENV, user_id=user_id, operation="payment.create", amount_minor=amount_minor,
+            currency=currency, payee_ref=payee.payee_ref, payee_display=payee.display,
+            payee_binding_hash=payee.binding_hash, merchant=merchant, country=country,
+            reference="invoice", now=now)
+        self.base.audit.append(actor_identity="spiffe://amanpay/frontend", action="intent.created",
+                               result="ok", intent_id=intent.intent_id,
+                               intent_hash=intent.intent_hash, now=now)
+
+        budget = AgentBudget(started_at=now)
+        fallback = None
+        context = risk = None
+        # ----- Context + Risk agents (advisory), with fail-closed fallback -----
+        try:
+            cctx = ToolClient(self.gw, self.base.kr, self.context_agent.spiffe,
+                              self.ids[self.context_agent.spiffe].kid, budget)
+            ccap = self._cap(self.context_agent.spiffe, cctx.kid, TOOL_FEATURES, intent, now=now)
+            context = self.context_agent.run(cctx, ccap, txn_id, now=now,
+                                             intent_hash=intent.intent_hash)
+            self._msg(self.context_agent.spiffe, self.risk_agent.spiffe, schemas.CONTEXT_RESULT,
+                      context, intent, flow, now=now)
+
+            rctx = ToolClient(self.gw, self.base.kr, self.risk_agent.spiffe,
+                              self.ids[self.risk_agent.spiffe].kid, budget)
+            rcap = self._cap(self.risk_agent.spiffe, rctx.kid, TOOL_RISK_MODEL, intent, now=now)
+            risk = self.risk_agent.run(rctx, rcap, txn_id, now=now, intent_hash=intent.intent_hash)
+            self._msg(self.risk_agent.spiffe, "spiffe://amanpay/pdp", schemas.RISK_RESULT,
+                      risk, intent, flow, now=now)
+        except (BudgetExceeded, ToolError, MessageRejected, schemas.SchemaError) as exc:
+            fallback = f"agent-failure->deterministic ({type(exc).__name__})"
+            self.base.audit.append(actor_identity="spiffe://amanpay/agent/risk",
+                                   action="conflicting.action", result="fallback",
+                                   intent_id=intent.intent_id, reason_codes=[], now=now)
+            risk = None
+
+        # ----- Deterministic PDP (authoritative); risk is ADVISORY (add-caution only) -----
+        agent_rec = {"recommend_step_up": bool(risk["recommend_step_up"])} if risk else None
+        ctx_for_pdp = {"biometric_ok": True, "confidence": 0.95,
+                       "modalities": ["face", "fp", "voice"],
+                       "recent_count": int(hist.recent_24h)}
+        d1 = self.base.pdp.evaluate(intent, None, context=ctx_for_pdp, now=now + 1,
+                                    idempotency_key=txn_id, agent_recommendation=agent_rec)
+
+        # ----- Auth recommendation (advisory; PDP already chose the minimum) -----
+        auth_rec = self.auth_agent.run(pdp_required=d1.required_auth,
+                                       risk_band=(risk["band"] if risk else "model_unavailable"),
+                                       supported=["trusted_session", "webauthn", "oob",
+                                                  "webauthn+oob"])
+        # ----- Rail ranking (only configured/available) -----
+        try:
+            rcl = ToolClient(self.gw, self.base.kr, self.rail_agent.spiffe,
+                             self.ids[self.rail_agent.spiffe].kid, budget)
+            rlcap = self._cap(self.rail_agent.spiffe, rcl.kid, TOOL_RAIL_OPTIONS, intent, now=now)
+            rails = self.rail_agent.run(rcl, rlcap, country=country, currency=currency, now=now,
+                                        intent_hash=intent.intent_hash, user_pref=hist.rail_pref)
+        except (ToolError, schemas.SchemaError):
+            rails = {"ranked": [], "eligible_only": True}
+
+        reason_codes = list(risk["reason_codes"]) if risk else ["MODEL_UNAVAILABLE"]
+        explanation = self.explain_agent.run(reason_codes=reason_codes, locale=locale)
+
+        result = OrchestrationResult(
+            decision=d1.decision, reason_codes=d1.reason_codes, required_auth=d1.required_auth,
+            agent_state="policy_evaluated", context=context, risk=risk,
+            auth_recommendation=auth_rec, rails=rails, explanation=explanation,
+            audit=self.base.audit.summary(), fallback=fallback)
+
+        if d1.decision != "step_up" or not approve:
+            return result
+
+        # ----- User approval -> PDP validates -> single-use ExecutionCapability -> Payment Core -----
+        ap = self.base.approve(intent, now=now + 2)
+        d2 = self.base.pdp.evaluate(intent, ap, context=ctx_for_pdp, now=now + 3,
+                                    idempotency_key=txn_id, agent_recommendation=agent_rec)
+        if d2.decision != "allow":
+            result.decision = d2.decision; result.reason_codes = d2.reason_codes
+            return result
+        ec = d2.execution_capability
+        E.verify_execution_capability(self.base.kr, ec, now=now + 3, env=ENV)
+        if not self.base.replay.consume("exec-cap", ec.execution_id, now=now + 3):
+            result.decision = "deny"; return result
+        payment = self.base.core.create_payment(
+            user_id=user_id, amount_minor=amount_minor, country=country, currency=currency,
+            merchant_id=merchant, payee_iban=payee.iban,
+            consent={"granted": True, "purpose": "agent-orchestrated payment (demo)"},
+            idempotency_key=txn_id, now=now + 3)
+        self.base.audit.append(actor_identity="spiffe://amanpay/payment-core",
+                               action="payment.initiated", result="ok",
+                               intent_id=intent.intent_id, now=now + 3)
+        result.decision = "allow"; result.reason_codes = d2.reason_codes
+        result.agent_state = "initiated"; result.payment = payment.view()
+        result.audit = self.base.audit.summary()
+        return result

amanpay/agentic_orchestration/schemas.py

@@ -0,0 +1,83 @@
+"""Structured, validated agent-output schemas (PR C2).
+
+Every model/agent result is treated as UNTRUSTED input until validated: it must match a strict
+schema, carry versions + allowlisted reason codes, and must NOT carry executable instructions or
+free-form text that could reach authorization logic. Malformed output is rejected (fail-closed).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List
+
+from amanpay.agentic_risk.reason_codes import validate as validate_codes
+
+# Message types (must be a subset of PR B gateway MESSAGE_TYPES).
+CONTEXT_RESULT = "context.result"
+RISK_RESULT = "risk.result"
+AUTH_RESULT = "auth.result"
+RAIL_RESULT = "rail.result"
+EXPLAIN_RESULT = "explain.result"
+
+# Keys that must never appear in an agent payload (no executable/authorization instructions).
+_FORBIDDEN_KEYS = {"command", "run", "exec", "sql", "url", "capability", "execution_capability",
+                   "approve", "authorize", "decision", "override", "signature", "private_key",
+                   "secret", "token"}
+
+
+class SchemaError(ValueError):
+    pass
+
+
+def _check_forbidden(payload: Dict[str, Any]) -> None:
+    bad = [k for k in payload if k.lower() in _FORBIDDEN_KEYS]
+    if bad:
+        raise SchemaError(f"agent payload contains forbidden key(s): {bad}")
+
+
+def _require(payload: Dict[str, Any], fields: Dict[str, type]) -> None:
+    for k, t in fields.items():
+        if k not in payload:
+            raise SchemaError(f"missing field {k!r}")
+        if not isinstance(payload[k], t):
+            raise SchemaError(f"field {k!r} wrong type (want {t.__name__})")
+
+
+def validate_context(payload: Dict[str, Any]) -> Dict[str, Any]:
+    _check_forbidden(payload)
+    _require(payload, {"channel": str, "recent_count": int, "cold_start": bool,
+                       "missing": list, "feature_version": str})
+    return payload
+
+
+def validate_risk(payload: Dict[str, Any]) -> Dict[str, Any]:
+    """Risk Agent output — advisory ONLY. It may set recommend_step_up (add caution) but carries
+    no decision/authority. Reason codes must be allowlisted."""
+    _check_forbidden(payload)
+    _require(payload, {"band": str, "recommend_step_up": bool, "reason_codes": list,
+                       "confidence": str, "model_version": str, "feature_version": str,
+                       "shadow": bool})
+    if payload["band"] not in ("low", "uncertain", "elevated", "high", "model_unavailable"):
+        raise SchemaError(f"invalid band: {payload['band']}")
+    validate_codes(payload["reason_codes"])            # allowlist enforcement
+    if payload.get("shadow") is not True:
+        raise SchemaError("risk output must be shadow=True in this phase")
+    return payload
+
+
+def validate_auth(payload: Dict[str, Any]) -> Dict[str, Any]:
+    _check_forbidden(payload)
+    _require(payload, {"recommended_method": str, "meets_pdp_minimum": bool})
+    return payload
+
+
+def validate_rail(payload: Dict[str, Any]) -> Dict[str, Any]:
+    _check_forbidden(payload)
+    _require(payload, {"ranked": list, "eligible_only": bool})
+    return payload
+
+
+def validate_explanation(payload: Dict[str, Any]) -> Dict[str, Any]:
+    _check_forbidden(payload)
+    _require(payload, {"locale": str, "messages": list, "reason_codes": list})
+    validate_codes(payload["reason_codes"])
+    return payload

amanpay/agentic_orchestration/tools.py

@@ -0,0 +1,74 @@
+"""Tool handlers + ToolClient for PR C2 agents.
+
+Tools are registered in the PR B `ToolGateway` (static allowlist, typed schemas, PoP-checked
+capability, budgets, secret scrubbing). Agents reach data/models ONLY through these tools — never
+the Payment Core, shell, DB, or arbitrary URLs.
+
+Only a `txn_id` crosses the (signed) tool args; the handler resolves the actual behavioural data
+from the orchestrator's trusted in-process store, so raw features never travel through signed
+request bodies or agent messages.
+"""
+
+from __future__ import annotations
+
+from typing import Callable, Dict
+
+from amanpay.agent_security import envelopes as E
+from amanpay.agent_security.budgets import AgentBudget
+from amanpay.agent_security.gateway import ToolGateway, ToolSpec
+
+# Tool names (also the capability audiences).
+TOOL_FEATURES = "tool:read_derived_features"
+TOOL_RISK_MODEL = "tool:invoke_risk_model"
+TOOL_RAIL_OPTIONS = "tool:rail_options"
+
+Handler = Callable[[Dict, Dict], Dict]
+
+
+def register_tools(gw: ToolGateway, *, features_handler: Handler, risk_handler: Handler,
+                   rail_handler: Handler) -> None:
+    """Register the C2 tools with orchestrator-provided handlers (closures over its txn store)."""
+    gw.register_tool(ToolSpec(
+        name=TOOL_FEATURES,
+        allowed_agents=frozenset({"spiffe://amanpay/agent/context"}),
+        input_schema={"txn_id": str},
+        output_schema={"channel": str, "recent_count": int, "cold_start": bool,
+                       "missing": list, "feature_version": str},
+        handler=features_handler))
+
+    gw.register_tool(ToolSpec(
+        name=TOOL_RISK_MODEL,
+        allowed_agents=frozenset({"spiffe://amanpay/agent/risk"}),
+        input_schema={"txn_id": str},
+        output_schema={"band": str, "recommend_step_up": bool, "reason_codes": list,
+                       "confidence": str, "model_version": str, "feature_version": str,
+                       "shadow": bool},
+        handler=risk_handler))
+
+    gw.register_tool(ToolSpec(
+        name=TOOL_RAIL_OPTIONS,
+        allowed_agents=frozenset({"spiffe://amanpay/agent/rail"}),
+        input_schema={"country": str, "currency": str},
+        output_schema={"rails": list, "eligible_only": bool},
+        handler=rail_handler))
+
+
+class ToolClient:
+    """Wraps a single agent's capability + key so it can call the gateway with a fresh PoP."""
+
+    def __init__(self, gw: ToolGateway, keyring, agent_spiffe: str, subject_kid: str,
+                 budget: AgentBudget, env: str = "demo") -> None:
+        self.gw = gw
+        self.keyring = keyring
+        self.agent = agent_spiffe
+        self.kid = subject_kid
+        self.budget = budget
+        self.env = env
+
+    def call(self, capability: E.CapabilityGrant, tool_name: str, args: Dict, *,
+             now: float, intent_hash: str | None = None) -> Dict:
+        proof = E.make_use_proof(self.keyring, self.kid, capability, operation=tool_name,
+                                 audience=tool_name, request=args, now=now)
+        return self.gw.call(agent_spiffe=self.agent, tool_name=tool_name, args=args,
+                            capability=capability, use_proof=proof, subject_kid=self.kid,
+                            budget=self.budget, now=now, intent_hash=intent_hash)

api/main.py

@@ -117,6 +117,10 @@ app.include_router(notifications_router)   # torch-free /notify/* endpoints
 from api.agent_security_routes import router as agent_security_router  # noqa: E402
 app.include_router(agent_security_router)
 
+# Agentic risk orchestration (/ai/v1 — shadow-only behavioural model, labelled demo).
+from amanpay.agentic_orchestration.api import router as ai_router  # noqa: E402
+app.include_router(ai_router)
+
 
 _ROOT = os.path.dirname(os.path.dirname(__file__))
 _FRONTEND = os.path.join(_ROOT, "frontend", "index.html")           # legacy (rollback)

build_info.json

@@ -1 +1 @@
-{"commit":"8832af5","build_time":"2026-07-13T04:36:02Z","frontend":"1.0.0"}
+{"commit":"0c6476e","build_time":"2026-07-13T04:57:19Z","frontend":"1.0.0"}