Skip to content

How-to guides

Task-oriented recipes. Each one assumes you've completed Getting Started — pick the task you need and follow the steps.

Building detectors

  • :material-rule:{ .lg .middle } Add a new detection rule

    Declare an aggregation_window / list_match / custom_sql rule with full audit evidence from day one. ~10 min.

  • Wire a python_ref scorer

    Escape-hatch logic type for ML scorers, multi-source heuristics, graph traversal. Comes with SR 11-7 / E-23 / SS1/23 model evidence baked in. ~30 min.

  • Discover candidate typologies from a run

    The offline aml discover-typologies CLI clusters a run's unexplained anomalies (no rule caught them) into candidate_typologies.yaml proposals (status: pending_promotion). Deterministic, human-gated, never auto-promoted. ~5 min. Detailed.

  • Detect mule rings from the identity graph

    The offline aml detect-mule-rings CLI runs deterministic union-find + density community detection over the resolved_entity_link graph into a governed mule_rings.json. Surfaced on Network Explorer. Advisory — an investigator confirms, never auto-escalated. ~5 min. Detailed.

  • Wire point-in-time reference data (M4)

    Declare a reference contract effective_dated + add an enrich block to an aggregation_window rule so each transaction joins the reference row in force at its booked_at — not the latest row. Closes the Pillar-3 SCD-2 gap. ~15 min. Detailed.

Migrating + operating

  • Migrate from SAS / Actimize / Mantas

    The aml inventory + aml import-legacy wizard parses a legacy rule dump and produces a starter rules: block. Already a how-to.

  • Promote a rule across environments

    dev → test → uat → prod with sign-off events on the audit ledger. The Program.environment + Rule.environments machinery. ~5 min. Detailed.

  • Stand up a GENIUS Act PPSI program

    Walk the richer NPRM-grounded genius_ppsi_stablecoin spec end to end — 31 CFR Part 502 OFAC sanctions program, ISO 20022 fields, SAR + proposed PPSI CTR, filing-latency SLA, six stablecoin typologies. ~10 min. Detailed.

Audit + evidence

  • Verify the audit hash chain

    Prove a decisions.jsonl hasn't been tampered with. CLI: aml verify-decisions. ~30 sec for a single run, ~5 min to wire into CI. Detailed.

  • Export per-case / per-batch evidence packs

    Hand a regulator a single-case ZIP, not the whole run. aml export-case and aml export-batch. ~30 sec per export. Detailed.

  • Use the Case Copilot for a case

    Governed, in-page GenAI DRAFTS on the Case Investigation page (#499) — summarize / typology / draft STR-SAR narrative / counterparty network / risk. Human-reviewed, never auto-dispositions, audited as ai_case_copilot_action. Backend via AML_AI_BACKEND. ~2 min. Detailed.

  • Walk the lineage chain for a case

    Paste a case_id and trace it back to source rows. CLI: aml lineage. Dashboard: Lineage Explorer page. ~30 sec per case. Detailed.

  • Run a 5-year transaction-monitoring lookback

    The copy-paste runbook companion to the 5-year lookback architectural overview. 60-month replay against the community_bank_lookback example + a deterministic synthetic generator. ~30–60 min wall time on a laptop. Detailed.

  • Run a FinCEN Whistleblower internal-channel audit

    The offline aml whistleblower-audit CLI (#531) rolls SAR-backlog exposure, escalation coverage (documented reviewer + rationale), triage time, board-documented decisions, and ledger integrity out of a run's audit ledger into a frozen whistleblower_audit_report.json (+ --markdown board table + --format nprm-gap). Advisory readiness lens against FR 2026-06271. ~5 min. Detailed.

Monitoring + DQ

  • Configure SLA monitoring

    Program.sla block + sla_report.json per-run artifact. ~5 min. Detailed.

  • Triage defects from defect_log.jsonl

    Round 28's 11-category classifier + data/rule/mapping decision tree. ~2 min per defect. Detailed.

  • Enable the alert prioritization scorer

    Advisory, deterministic, explainable priority_score (0–1) per alert via program.prioritization. Stamps priority_explanation, emits a manifest-pinned priority_report.json, ranks the Triage Queue. Never changes a disposition. ~10 min. Detailed.

  • Configure risk segmentation + governed suppression

    Advisory de-prioritization of low-score alerts on low-risk customers via program.risk_segmentation. Never auto-closes; emits suppression_report.json. Requires program.prioritization. ~10 min. Detailed.

  • Run a champion-challenger validation

    Compare two prioritization weight sets on a labelled alert set with aml run --labels --challenger-weights. Emits a frozen, manifest-pinned priority_outcome.json (precision@k / recall / winner) for the model-risk committee. SR 26-2; temporal-leakage guard enforced. ~5 min. Detailed.

  • Monitor model risk + per-rule drift

    Governed model-risk monitoring via program.model_risk_monitoring. Emits a frozen, manifest-pinned model_risk_report.json (model inventory + per-rule count drift vs prior run + validation cadence). Advisory only; SR 11-7 / OSFI E-23. ~10 min. Detailed.

  • Produce an AMLA RTS effectiveness pack

    The offline aml amla-effectiveness-report CLI rolls one run into the alert→case→STR funnel + per-rule precision + AMLA citation coverage (CDD AMLR Art. 28(1), ongoing monitoring AMLR Art. 26, targeted-financial-sanctions screening AMLR Art. 20(1)(d)) for EU-supervised obliged entities. Deterministic, manifest-pinned; STR acceptance honestly reported as not-tracked. ~5 min. Detailed.

Deploying

How-to guide template

Every page in this section follows the same shape:

# How to <verb> <noun>

> When you need this: <1-sentence trigger>
> Prereqs: <bullet list>
> Time: ~N min

## Steps
1. ...
2. ...

## Verify it worked
<one paragraph + a check>

## Common problems
| Symptom | Cause | Fix |

## Next steps
<links to related how-tos>

If a placeholder doesn't have content yet, it follows this template with the steps marked TODO. Want one filled in? File an issue or PR — the structure is intentional, so contributions can drop straight into the template.