Project Summary
Fraud Agent Orchestrator is a multi-agent fraud triage reference implementation with explicit pipeline stages (intake → features → risk → policy → report), deterministic scoring with optional Ollama narrative, OPA policy-as-code, Temporal workflows with supervisor HITL, hash-chained audit plus HMAC-signed evidence, FastAPI with RBAC scaffolding, and a React operator console.
Technical deep dive
Overview
Fraud Orchestrator is a real-time fraud detection and decision orchestration architecture for payment risk teams that need speed, explainability, and regulatory defensibility in one production workflow. The system composes specialist agents for intake, feature engineering, model scoring, policy enforcement, and report generation so high-volume alert streams can be adjudicated consistently under strict governance controls.
The design is intentionally policy-first. Machine learning scores rank risk and guide triage, but policy determines permitted actions. That boundary is critical in enterprise fraud operations where legal constraints, sanctions obligations, and customer impact thresholds must remain stable as model behavior evolves. This project demonstrates how to combine adaptive model intelligence with deterministic controls, immutable event trails, and human-in-the-loop override paths.
Pipeline mermaid
Agent stage table
| Stage | Role |
|---|---|
| IntakeAgent | Validates alert schema, source authenticity, and deduplication keys; normalizes payloads into a stable orchestration contract. |
| FeatureAgent | Builds deterministic risk features such as velocity windows, entity graph overlap, geospatial mismatch, and channel behavior drift. |
| RiskScoringAgent | Executes calibrated fraud models, emits probability plus severity band, and returns transparent reason codes for analyst review. |
| PolicyAgent | Applies jurisdictional and institution-specific controls including sanctions intersections, exposure caps, and mandatory escalation rules. |
| ReportAgent | Produces regulator-ready narrative, evidence timeline, and verification metadata for case systems, governance review, and examiner requests. |
Policy-above-models
Policy-above-models is the core safety principle in this architecture. Risk scores are informative but not sovereign. The PolicyAgent remains the final authority for approve, hold, escalate, or block outcomes. This prevents model drift, threshold miscalibration, or data-quality incidents from silently bypassing business and compliance guardrails.
Operationally, this separation lets data science teams improve model recall and precision without destabilizing control behavior. Governance teams can version policy independently, run impact simulations, and certify changes through formal review. The result is a resilient fraud decisioning stack that preserves customer trust and examination readiness even as scoring logic iterates rapidly.
Temporal HITL flow
- Start a durable Temporal workflow with idempotency key, request digest, and pinned model and policy versions.
- Run IntakeAgent and FeatureAgent as bounded activities with retries, timeouts, and immutable checkpoint snapshots.
- Execute RiskScoringAgent and branch to analyst queue on low confidence, high projected loss, or policy-mandated review.
- Capture analyst approve, reject, or escalate actions with signed rationale, actor scope, and replay-safe transition metadata.
- Apply PolicyAgent for terminal controls, then run ReportAgent to produce evidence package and verification output.
- Commit final hash-chain anchor and publish workflow completion to case management, SIEM, and model monitoring streams.
Governance/security table
| Domain | Control |
|---|---|
| Audit provenance | Hash-linked event chain records every machine and human transition from alert ingest through final disposition. |
| Evidence integrity | Signed evidence manifests support non-repudiation, forensic replay, and regulator-facing validation workflows. |
| Access governance | Role-scoped permissions isolate analyst, supervisor, auditor, and platform-admin actions with explicit approval boundaries. |
| Operational resilience | Temporal retries, dead-letter handling, and compensating actions contain partial dependency failures without losing lineage. |
| Data security | Field-level encryption, tokenized identifiers, and retention controls minimize sensitive data footprint across systems. |
| Model governance | Versioned policy and model lineage enable deterministic replay, controlled promotion, and incident-era rollback. |
API table
| API | Purpose |
|---|---|
| POST /api/v1/cases | Registers a fraud case, stores provenance metadata, and starts durable orchestration. |
| POST /api/v1/triage | Runs low-latency risk and policy evaluation for payment authorization and account protection flows. |
| POST /api/v1/hitl/{caseId} | Persists analyst decision with signed rationale and applies auditable workflow state transition. |
| GET /api/v1/cases/{caseId} | Returns full execution timeline with agent outputs, policy checkpoints, and active disposition. |
| GET /api/v1/evidence/{caseId} | Exports verification package containing hash proofs, signatures, and machine-readable audit metadata. |
Roadmap
- Add champion-challenger scoring with segment-level calibration monitoring and policy-gated rollout controls.
- Integrate end-to-end OpenTelemetry spans from ingress through Temporal workflow, report generation, and evidence export.
- Move verification signatures to HSM or KMS-backed key management with automated rotation attestation.
- Ship policy simulation sandbox for pre-release impact analysis on historical fraud corpora and rare-edge scenarios.
- Expand regulator-ready templates for card fraud, ACH fraud, account takeover, mule activity, and APP fraud narratives.
- Close the learning loop by feeding adjudication outcomes into threshold optimization and retraining governance pipelines.
Key Features & Capabilities
- Typed multi-agent pipeline: IntakeAgent, FeatureAgent, RiskScoringAgent, PolicyAgent, ReportAgent
- OPA/Rego policy layer merged with Python rules in execute_triage service
- Temporal durable execution with retries, visibility, and supervisor HITL signals
- SHA-256 hash chain audit trail with HMAC-SHA256 evidence envelope signing
- PII minimization: raw user_id replaced with user_id_sha256 after intake in audit payloads
- FastAPI with rate limits, JWT/RBAC, idempotency keys, and Vite React operator UI
Tech Stack & Components
Getting Started
1.Editable Python install
Install the package in development mode with dev extras.
python -m venv .venv
.\.venv\Scripts\activate
pip install -e ".[dev]"2.CLI batch triage (no DB)
Run triage against sample transaction JSON.
python -m fraud_agent_orchestrator.cli run --input data\sample_transactions.json --pretty3.API + operator UI
Open http://localhost:5173 — Vite proxies /api to port 8000.
fraud-api
cd web && npm install && npm run devFrequently asked questions
- What is Fraud Agent Orchestrator?
- A multi-agent fraud triage reference with explicit pipeline stages (intake → features → risk → policy → report), OPA/Rego policy-as-code merged with Python rules, Temporal durable workflows with supervisor HITL, hash-chained audit trails, HMAC-signed evidence, and a React operator console.
- How does policy override ML scoring in Fraud Agent Orchestrator?
- PolicyAgent applies hard rules and thresholds that can force review or escalation regardless of soft risk scores. OPA/Rego policies merge with Python rules in execute_triage—sample data includes restricted geography cases where policy overrides model-friendly heuristics.
- What audit integrity guarantees does the orchestrator provide?
- Each pipeline stage appends to a SHA-256 hash chain over canonical step payloads. AuditTrail.verify() drives the audit_verified flag in API responses. Evidence packs use HMAC-SHA256 envelopes; raw user_id is replaced with user_id_sha256 after intake in audit payloads for PII minimization.
- Does Fraud Agent Orchestrator require Temporal?
- Temporal enables durable case workflows, retries, visibility, and supervisor HITL signals when TEMPORAL_ENABLED=true. When Temporal is unreachable, the API falls back to in-process synchronous triage so local demos and CLI batch mode remain runnable without a cluster.
- What authentication does the Fraud Agent Orchestrator API use?
- JWT plus role checks (analyst, admin, supervisor, auditor) when AUTH_DISABLED=false. Development defaults use AUTH_DISABLED=true with a dev actor. SlowAPI rate limits hot routes; production requires real IdP integration, rotated EVIDENCE_HMAC_SECRET, and TLS.