Skip to main content

ADR-0185: Navin Fraud & Anomaly Investigation Agent, detection and investigation product layer on top of the Control Plane

  • Status: accepted on 2026-11-04; the open choices were settled by the user on 2026-11-04 (see "User decisions")
  • Date: 2026-11-04
  • Scope: new project navin-fraud-investigation/ (FastAPI backend, workers, screens in the shared sector-agent frontend (ADR-0180), Navin integration), additive Control Plane domain fraud (services/control-plane/src/eai/domains/fraud, migrations V230 to V239), additive OpenFGA types, OPA package eai.fraud, Enterprise portal activation flow, service template prepared but not published
  • Related documents: ADR-0101 (licence policy), ADR-0103 (vLLM and LiteLLM), ADR-0108 (Opik), ADR-0111 (storage without MinIO), ADR-0113 (Redis as a cache only), ADR-0114 (PostgreSQL source of truth), ADR-0116 (chained audit), ADR-0166 (ClamAV and YARA-X scanning), ADR-0174 (Mem0 and Cognee memory), ADR-0175 (RAG Agent model), audit navin-fraud-investigation/docs/en/NAVIN_INTEGRATION_AUDIT.md

Context​

The client asks for a fraud and anomaly detection and investigation agent for three sectors (banking, insurance, retail): ingestion of authorized business events, versioned rules, statistical and Machine Learning models, explainable scores, correlation, alerts, relationship graph, analysis of supporting documents, investigation cases, evidence and chain of custody, human review, controlled actions, investigation copilot, reports and indicators.

The 2026-11-04 audit shows that the platform already provides the governance (identity, tenants, RLS, OpenFGA, OPA, quotas, chained audit, DLP and Presidio), the agent runtime (runs, subagents, tools, approvals, SSE), document ingestion (Docling, Qdrant, ClamAV, YARA-X), Cognee memory, seals and legal holds (/v1/evidence/*), object storage with declared locking, the Connector Hub and the rag_agent lifecycle model. Missing: the product layer, the business connectors (core banking, claims, e-commerce, POS, OMS, payment: absent) and any detection engine.

Decision​

1. Product layer, same model as ADR-0175​

WhoDoes what
Navin Managerinstalls and runs the runtime (API, workers, web), TLS, health, backups, upgrades, rollback
Control Planetenants, projects, roles, language models, knowledge bases, memory, file scanning, storage, seals, quotas, audit, policies, traces; domain fraud for instances and their lifecycle
FAI backendingestion, detection, scoring, alerts, graph, cases, evidence, decisions, actions, copilot, reports, KPIs; it reaches the Control Plane only through the Python SDK enterprise_ai

The backend never talks directly to Qdrant, Cognee, LiteLLM, Docling, ClamAV or YARA-X. It owns its PostgreSQL schema fraud (Alembic, like the rag schema) and its Redis namespace. Development ports: backend 8474, frontend 3474.

2. One common engine, three packs​

One engine (ingestion, rules, features, models, scoring, correlation, alerts, graph, cases) and three versioned, schema validated sector packs (banking, insurance, retail): rules, features, models, scoring policies, alert and case types, workflows, actions, KPIs and reports. An instance activates a pack and customizes it without code.

3. Detection independent of the LLM​

  • Detection is done by deterministic rules and statistical or ML models. An LLM is never a scoring engine, never changes a production rule, threshold or policy, and only assists the investigation (summary, search, drafting), always through the /v1/gateway/* gateway in front of LiteLLM.
  • Rules are written in a structured language validated by schema (contracts/v1/fraud-rule.schema.json) and run by a deterministic interpreter: never eval, never code supplied by a user.
  • Each result records the versions of the features, rules, models and scoring policy.
  • A score is never a decision: "confirmed fraud" is reserved for a case validated by an authorized human according to the procedure.

4. ML stack​

  • scikit-learn 1.9.1 (BSD-3-Clause) for robust scores, Isolation Forest and classifiers, XGBoost through the xgboost-cpu 3.4.1 package (Apache-2.0; the xgboost package is rejected because it pulls nvidia-nccl-cu13 under an NVIDIA licence), SHAP 0.54.1 (MIT) for explanations, NumPy 2.5.4, pandas 3.1.0, SciPy 1.18.1 (BSD). Licences read on PyPI on 2026-11-04; tqdm (a SHAP dependency, MPL-2.0 and MIT) is already covered by catalog/licence-exceptions.yaml.
  • No LLaMA-Factory: no language model fine-tuning in this product.
  • Versioned datasets with a temporal split, no leakage between training and validation, no automatic retraining on closed alerts, uninvestigated cases never counted as legitimate.

5. Model artifacts​

The /v1/models registry describes language models and the Navin Trusted Hub distributes services: neither describes a tabular classifier. Artifacts are written to the Control Plane object storage (/v1/storage/profiles, SeaweedFS or the client storage, never MinIO), with a SHA-256 digest and an Ed25519 signature whose key lives in OpenBao. The version registry (state, approval, shadow, canary, rollback, retirement) lives in the fraud schema. An artifact whose digest or signature does not verify is never loaded.

6. Durable flows and data​

  • No new broker: durable jobs in PostgreSQL (FOR UPDATE SKIP LOCKED, signed identity, retry, backoff, dead letter, replay) as in the RAG Agent, catalogue NATS JetStream for near real time fan-out when installed (eai/integrations/nats.py).
  • PostgreSQL is the source of truth of the product, business systems stay the source of truth of their data: the FAI keeps references and computed characteristics rather than sensitive copies; tokenized payment references only, never a CVV, a PIN or forbidden authentication data.
  • Forced RLS on every tenant table, date partitioning of events and scores, outbox, retention and legal holds.
  • Redis isolated per tenant for ephemeral data only (rule cache, feature windows, rate limiting, idempotency, locks, deduplication), never as definitive storage.

7. Investigation graph​

The business graph is authoritative in PostgreSQL (nodes, relations, provenance, visibility, status observed, imported, inferred, AI proposed, verified). Algorithms (neighbours, bounded paths, communities, motifs, temporal filtering) run in the backend with NetworkX (BSD-3-Clause), without a new graph database. Cognee only brings semantic enrichment, through the Control Plane; Qdrant only serves document similarity. No relation across tenants, and an indirect relation is never presented as evidence.

8. Evidence and chain of custody​

The Compliance & Audit Agent evidence vault does not exist in the repository yet (parallel development). The FAI defines a single vault interface: original never modified, digest, seal and legal hold through /v1/evidence/*, an FAI chained custody register modelled on eai/domains/soc/evidence.py, separate annotations, WORM only when the storage profile declares and verifies it. After the merge, the interface is rewired to the C&A vault without rewriting data already sealed. A hash alone is never presented as complete evidential preservation.

9. Human decisions and actions​

  • No automatic restrictive measure (account block, payment freeze, claim refusal, refund suspension) outside a framework pre-approved by the client; every sensitive action goes through OPA before any effect, through an authorized approver distinct from the investigator, then through the authorized API of the business system, and its result is verified.
  • Investigations about employees follow the client HR procedures and confidentiality: access restricted by OpenFGA, decision by the designated HR roles.

10. Security and observability​

  • Fail-closed controls: OpenFGA, OPA (eai.fraud), file scanning, quotas. Untrusted content (documents, tool results, memory) is handled as data, with injection detection.
  • OpenTelemetry from ingestion to the human decision, Opik traces for agent runs only (not for deterministic scoring), Prometheus metrics without a client identifier in labels, logs to Alloy and OpenSearch.
  • Grafana, Loki and Tempo are under AGPL-3.0 and refused by ADR-0101: Prometheus, Alertmanager, Alloy, OpenSearch, Jaeger, Opik and ClickHouse replace them.
  • The Navin SOC distinguishes cybersecurity incidents from fraud alerts.

11. Reports​

PDF with ReportLab 5.1.0 (BSD-3-Clause), DOCX with python-docx 1.2.0 (MIT), XLSX with openpyxl 3.1.5 (MIT), CSV and JSON with the standard library; the Control Plane has no rendering service (audit, section 6). Reports separate observations, inferences and validated human conclusions; a final report is never modified, it is amended.

12. Truth of capabilities​

No connector is declared operational without a real test or a representative test environment. No detected fraud rate is published without reliable ground truth. Limits are written in navin-fraud-investigation/docs/KNOWN_LIMITATIONS.md.

User decisions​

On 2026-11-04, the user settled the open choices:

  1. ML stack: scikit-learn, XGBoost and SHAP from the start (option "c", preferred to the recommended scikit-learn only option). XGBoost ships as xgboost-cpu to stay under Apache-2.0.
  2. Model artifacts: Control Plane object storage, SHA-256 digest, Ed25519 signature with its key in OpenBao, version registry in the fraud schema.
  3. Evidence: Control Plane seals and legal holds and the FAI chain of custody, convergence with the C&A vault after the merge.
  4. Guidia: outside this repository, no impact on the FAI for now; the point stays open.

Points for the client to validate​

  1. Replacement of Grafana, Loki and Tempo (AGPL-3.0) by the authorized catalogue components, as for ADR-0175.
  2. List of pre-approved restrictive actions per sector (default: none).
  3. HR procedure applicable to investigations about employees and the roles that apply it.
  4. Location of the Guidia ecosystem.

Rejected alternatives​

  • An LLM as scoring engine or production rule writer: non deterministic, not auditable.
  • A rule language made of user supplied Python or SQL expressions: arbitrary code execution.
  • A dedicated graph database (Neo4j, GPL or commercial) or Cognee as the business graph: second source of truth.
  • A new broker (Kafka, RabbitMQ): the existing broker and durable queue are enough.
  • The xgboost package: nvidia-nccl-cu13 dependency under a proprietary licence.
  • Extending the /v1/models registry or the Hub for tabular models: change of shared contracts.
  • Waiting for the C&A vault: would block the evidence, cases, human review and packs batches.
  • LLaMA-Factory: no language model fine-tuning is needed.

Delivery plan​

Fifteen batches tracked on the project board ("FAI" tasks): audit and architecture; backend foundations; ingestion and connectors; rules; features, models and scoring; correlation and alerts; graph and documents; cases, evidence and decisions; RAG and memory; subagents and copilot; packs; governance, reports and KPIs; screens; observability and security; lifecycle, end to end scenarios and production readiness.