Skip to content
dphyyPublic

About

🥇 1st Place - SCALE Hackathon | SAP-powered AML investigation assistant combining ML alert classification with evidence-grounded AI case reports to help financial crime analysts focus on higher-risk cases

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

19 Commits

Folders and files

Repository files navigation

RiskLens AML Investigation Hub

RiskLens is an anti-money-laundering (AML) investigation prototype built around SAP HANA Cloud, SAP-RPT, and SAP Generative AI Hub. It adds a second-pass classification filter to existing rule-generated alerts, then helps analysts investigate flagged cases with case evidence and AI-generated reports.

The goal is fewer alerts escalated into full investigation, not fewer alerts generated by the bank's existing AML controls. The classification phase reduces total cost when it avoids invoking the RAG/LLM assistant for low-risk cases; measured savings still require validation.

This README describes the current main implementation and the intended operating workflow. The repository was previously named TrustSphere, so code, configuration variables, schemas, and older documents retain that name. Audit automation and durable decision storage are planned, not completed features.

End-to-end workflow

  1. Existing controls generate candidate alerts. RiskLens reads existing RISK_ALERTS and related transaction/customer data from SAP HANA Cloud. Upstream AML rule execution is outside this application.
  2. SAP-RPT classifies candidate alerts using richer context. Inputs include transaction amount and purpose, customer/KYC risk, geography, beneficial ownership, sanctions/PEP/adverse-media flags, and historical behaviour summaries.
  3. The classifier assigns an escalation status. A numeric RPT score and threshold produce Fraud Flagged or Fraud Not Flagged, represented in the app as FLAGGED and NOT_FLAGGED. These are routing labels, not findings of criminal conduct.
  4. Fraud Not Flagged cases remain available. The intended policy is retention for audit and periodic sampling/review, for example every three months. Classification does not delete or automatically resolve an alert. The current app preserves a Not Flagged queue; scheduled sampling and durable audit logging still need implementation.
  5. Fraud Flagged cases enter the investigation workflow. An analyst opens a case and requests a report. SAP Gen AI Hub Orchestration combines structured facts with Document Grounding reference material to draft an explanation.
  6. The financial crime analyst decides. The analyst reviews evidence, completes the checklist, records a rationale, and chooses an outcome. AI output remains decision support.
flowchart TD
    Rules["Existing AML / rule systems"] --> Alerts["Candidate alerts in SAP HANA Cloud"]
    Context["Customer, KYC, ownership, geography and baselines"] --> ML
    Alerts --> ML["SAP-RPT second-pass classification"]
    ML --> Flagged["Fraud Flagged"]
    ML --> NotFlagged["Fraud Not Flagged"]
    NotFlagged --> Retain["Retain for audit"]
    Retain -.-> Review["Periodic sampling / review: planned"]
    Flagged --> Workspace["Analyst opens investigation workspace"]
    Workspace --> Orch["SAP Gen AI Hub Orchestration"]
    Facts["Structured case facts / risk indicators"] --> Orch
    Grounding["SAP Document Grounding: AML reference corpus"] --> Orch
    Orch --> Report["Draft case report"]
    Report --> Human["Financial crime analyst: final decision"]
    Review -.-> Human
Loading

What the dashboard provides

The Streamlit application in app/app.py has three main views:

  • Risk Overview: flagged/not-flagged counts, flagged transaction exposure, workload charts, and a five-case flagged worklist.
  • Investigation Queue: searchable, paginated alert lists with status filters and sorting by RPT score, amount, or number of risk indicators.
  • Investigation Workspace: transaction/company facts, RPT status and score, observed risk evidence, tailored investigation checks, draft report generation/download, and a RAG Trace panel.

The analyst outcome workflow offers Confirm Fraudulent, Mark False Positive, and Escalate for EDD (enhanced due diligence). Submission requires all case-specific checks to be completed and a rationale of at least 10 characters. The demo records an analyst label, Singapore timestamp, outcome, rationale, and checklist completion in Streamlit session state. These records are not yet written back to HANA, and the displayed follow-up actions do not execute downstream workflows.

Unavailable information, such as supporting documents or detailed transaction history, is presented as a data gap. If report generation fails, the loaded case evidence remains available.

SAP components

Component Role in this repository
SAP HANA Cloud Supplies alerts, transactions, companies, country risk, beneficial owners, and transaction baselines through SQL joins using hdbcli.
SAP-RPT on SAP AI Core Provides tabular classification through the deployed /predict endpoint. The runner defaults to sap-rpt-1.5-large.
SAP AI Core Provides deployment endpoints and OAuth client-credentials authentication; requests specify the AI-Resource-Group header.
SAP Generative AI Hub Orchestration Combines the report prompt, alert facts, grounding configuration, and an LLM through /completion. The current client defaults to gpt-4o.
SAP Document Grounding Stores/retrieves reference passages from the modular AML corpus for report generation and analyst inspection.
SAP AI Launchpad Supports deployment inspection and orchestration testing. The dashboard sends its orchestration configuration inline; analysts do not need to use Launchpad for each case.

The analyst interface is a Python/Streamlit app. The repository does not currently implement the separate autonomous AI-agent layer shown in the wider solution concept.

How the ML filter works

src/run_rpt_pass.py reuses the feature extraction and RPT client in code/ml_pipeline/.

  1. Join RISK_ALERTS, TRANSACTIONS, COMPANIES, COUNTRIES, TRANSACTION_BASELINES, and COMPANY_BENEFICIAL_OWNERS.
  2. Map resolved outcomes to FRAUD_LABEL: TRUE_POSITIVE or FALSE_POSITIVE. Unresolved alerts have no target label.
  3. Sort resolved alerts chronologically: the oldest 70% become labelled context examples; the newest 30% form the evaluation holdout. Unresolved alerts are scored separately.
  4. Send labelled context plus prediction rows to SAP-RPT. Prediction rows use FRAUD_LABEL: "[PREDICT]"; the default batch size is 128 prediction rows.
  5. Export labels and scores to report/rpt_predictions.csv, evaluation metrics to report/rpt_metrics.txt, and run/threshold configuration to models/rpt_config.json.
  6. src/score_alerts.py joins predictions by ALERT_ID, applies the escalation threshold, and caches the dashboard dataset in report/scored_alerts.csv.

This is in-context prediction, not local model training or fine-tuning. Historical examples are supplied with each request; this runner does not create a trained model-weight artifact. The exported confidence field is the model's score for the TRUE_POSITIVE class, not necessarily confidence in its highest-ranked label.

The flagging policy uses the lowest available score among scored, labelled true-positive cases. That threshold is selected to retain those observed cases; it does not guarantee zero false negatives on future alerts. Because the threshold uses known evaluation outcomes, it also needs validation on a separate, untouched dataset.

Saved demo results

These are checked-in artifacts, not a new evaluation or a live service health check:

Measure Saved value
Labelled context examples 2,412
Holdout alerts 1,034
Unresolved alerts scored 1,554
Total RPT predictions 2,588
Holdout ROC AUC 0.487
Escalation threshold 0.16
Flagged among RPT-scored alerts 2,569 / 2,588

The saved results show near-chance discrimination on the supplied synthetic data, and the conservative threshold flags almost every scored alert. They do not establish a false-positive reduction or cost-saving percentage. Realistic labels, threshold validation, and end-to-end measurements are needed before making those claims.

Missing scores are a known limitation: the current scoring code can assign NOT_FLAGGED to rows without an RPT prediction, including historical context rows. An unscored alert must not be interpreted as a model-confirmed low-risk case or counted as a successful filtering result. An explicit unscored/manual-review state is needed before operational use.

Isolation Forest, HANA PAL anomaly detection, and combined anomaly-uplift scoring are not part of the active dashboard classification path. Related files remain as older experiments.

Case evidence and RAG reports

The transparent rules in src/score_alerts.py identify sanctions exposure, high-risk geography, PEP links, adverse media, and unusual amounts. Their weighted RISK_SCORE supports evidence presentation and secondary sorting; it does not determine the RPT classification.

Case facts are organised into five business risk groups when relevant: deviation from averages, geographic anomalies, counterparty risk, inconsistent transactions, and customer risk rating. These observations explain the case context; they are not model feature attributions or proof of why RPT made its prediction.

The modular reference library is in report/grounding/, with source metadata in source_registry.json. src/upload_grounding.py uploads the documents and records the collection ID in report/grounding_collection_id.txt.

The orchestration prompt asks for:

  • SUMMARY
  • RISK FACTORS
  • EVIDENCE & TYPOLOGY MATCH
  • RECOMMENDED ACTION
  • SOURCES

The prompt restricts the assistant to supplied facts/reference context and asks it not to invent evidence, assign the risk score, or make final enforcement decisions. Analysts must verify the draft.

Two grounding limitations matter: the client can retry without grounding after a grounded HTTP failure, and the visible RAG Trace is a separate retrieval request rather than the exact orchestration execution trace. A generated report or visible passage list alone therefore does not prove that those passages supported the final generation.

Run locally

Use Python 3.10 or newer. From a fresh checkout of main:

git clone --branch main https://github.com/dphyy/RiskLens.git
cd RiskLens
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements-app.txt
python -m streamlit run app/app.py

Open the local URL printed by Streamlit, normally http://localhost:8501. On macOS, run_dashboard.command also prepares the environment and launches the dashboard. On Windows, activate the environment with .venv\Scripts\Activate.ps1 in PowerShell.

The saved report/scored_alerts.csv supports browsing without a live HANA connection when the expected flag columns are present. Rebuilding the cache requires HANA access; generating reports requires SAP AI Core credentials and an accessible deployment.

Private configuration

Use code/credentials.example.json as the schema for a private .secrets/team_05_credentials.json containing the database and ai_core objects. Alternatively, point TRUSTSPHERE_CREDENTIALS_FILE at a credential file. Never commit credentials.

src/config.py also supports exported environment variables when a credential file is absent:

Purpose Variables
HANA connection HANA_HOST, HANA_PORT, HANA_USER, HANA_PASSWORD, HANA_SCHEMA
AI Core connection AICORE_CLIENT_ID, AICORE_CLIENT_SECRET, AICORE_AUTH_URL, AICORE_API_URL, AICORE_RESOURCE_GROUP
Orchestration override AICORE_ORCHESTRATION_DEPLOYMENT_URL, or ai_core.orchestration_deployment_url in the credential file
RPT runner overrides RPT_DEPLOYMENT_URL, RPT_MODEL_NAME, RPT_BATCH_SIZE

Supply the auth base URL without /oauth/token and the AI Core API base URL without /v2 for compatibility with the current helpers. Deployment URLs should omit their final /predict or /completion operation suffix.

The dashboard's live evidence query currently uses TRUSTSPHERE_REFERENCE; the RPT runner uses the configured schema (default TEAM_05) with a reference-schema fallback. Ensure both datasets describe the same alerts and share ALERT_ID values. Changing HANA_SCHEMA alone does not redirect the dashboard query.

The checked-in deployment URLs and grounding collection ID are demo-environment references. Configure accessible resources for your own SAP tenant; their presence does not establish that the services are running.

Refresh predictions and evidence

With credentials and an accessible RPT deployment configured, run from the repository root:

python -m pip install "requests>=2.32,<3"
python src/run_rpt_pass.py
python src/score_alerts.py

The first command adds the RPT client's dependency to the dashboard environment. The scripts make live SAP requests and overwrite the saved prediction, metric, configuration, and scored-alert artifacts. Restart Streamlit after refreshing them.

To provision a new grounding collection or upload revised reference documents:

python src/upload_grounding.py

This creates a remote collection, uploads the corpus, and replaces the local collection-ID file. It is not required for cached queue browsing. Restart Streamlit to load the new ID.

Prototype boundaries and next steps

  • Audit and review: implement durable retention/logging, periodic sampling of Not Flagged cases, and review outcomes. A three-month review cycle is a proposed policy, not an existing scheduled job.
  • Decision persistence: connect analyst outcomes to HANA or a case-management backend with authenticated identities and an audit history. Session state is not a durable audit record.
  • ML validation: separate unscored alerts, validate historical features as of each alert's timestamp, and assess escalation thresholds on an independent dataset.
  • Grounding integrity: expose whether generation actually used grounding, capture the exact supporting passages, and maintain source freshness.
  • Feedback: use reviewed analyst outcomes to refresh RPT context and recalibrate thresholds under validation. Automatic quarterly retraining/context refresh is not implemented.

The architecture notes, presentation report, slides brief, and ML pipeline guide provide additional background, but contain older workflow descriptions. The historical anomaly test also references removed scoring APIs; do not treat the full test suite as validated for this workflow.

Repository map

Path Purpose
app/ Streamlit dashboard and styles
src/score_alerts.py HANA evidence, RPT flags, case facts, and dashboard cache
src/run_rpt_pass.py SAP-RPT prediction/export runner
src/orchestration_client.py Report prompt and SAP Orchestration client
src/grounding_search.py Reference retrieval for the RAG Trace panel
src/decision_workflow.py Analyst decision validation and session-record construction
code/ml_pipeline/ Shared feature extraction, RPT client, and experimental backends
report/grounding/ Modular AML reference corpus and source registry
report/ Cached predictions/evidence, metrics, prompts, and project notes
models/rpt_config.json Saved RPT run and threshold configuration
tests/ Analyst decision tests and legacy anomaly tests
archive/ Earlier models, scripts, and prototype artifacts

About

🥇 1st Place - SCALE Hackathon | SAP-powered AML investigation assistant combining ML alert classification with evidence-grounded AI case reports to help financial crime analysts focus on higher-risk cases

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages