Skip to content

Fraud output contract

Canonical partner publication

This file is the canonical partner copy. Service-repo mirrors must sync from here (see internal Engineering → Contract sources).

This page describes what the fraud report step accepts from the scoring services, how it turns a prediction into a dashboard report, and the payload it delivers to the banking application.

Two open issues affect this contract

  1. The risk tiers are incompatible. The ML scoring service and the report step use different tier labels and score boundaries. Some ML predictions are rejected and produce no dashboard report. See Risk tiers: producer and consumer disagree. This is a product defect awaiting an owner decision; this page does not choose the fix.
  2. The decision policy is provisional. The automated decision (approve | pend | block) and escalations come from fraud-decision-v1. That policy is provisional and has no production or compliance sign-off. The language model never makes the decision; Python policy code does.

Documentation status

Last verified: 26 Sep 2026. Contract behaviour follows the status vocabulary. Confirm the revision in your environment with MasteryHive.

Pipeline

transaction event → baseline checks → lastCheckReport
  → ML scoring (/call-and-predict)  or  rule scoring (/rule_based_engine)
  → report message → report step (/report)
  → validate → normalise score and category → derive evidence → apply policy
  → narrative (aiSummary only) → POST {backend}/transaction/create-report
Report field Produced by
fraudScore, riskCategory Deterministic normalisation (code)
indicatorRecords, aiChecks, reasonCodes Deterministic evidence derivation (code)
decision, escalations Policy fraud-decision-v1 (code, provisional)
fraudIndicators, aiRecommendation Views derived from the structured decision, kept for dashboard compatibility
aiSummary Language model, or a deterministic fallback if the model call fails
provenance Contract, policy and narrative versions plus a hash of the prediction

The contract version is fraud-output-v3, the policy version fraud-decision-v1, and the narrative version gemini-summary-v1. All three are carried in provenance.

Which engine produced the prediction

The report step identifies the engine from the envelope's check_type (ml_check or rule_based_check) plus the prediction's keys:

  • ML is identified by probability_score.
  • Rule is identified by flagged and score together.
  • predicted_level appears in both, so it does not identify the engine.
Condition Result
ML keys and rule keys in the same prediction Rejected: AMBIGUOUS_PREDICTION_CONTRACT
check_type says one engine, keys say the other Rejected: CHECK_TYPE_MISMATCH
No recognised check_type (missing, empty or any other value) and no identifiable shape Rejected: AMBIGUOUS_PREDICTION_CONTRACT

A rejected prediction produces no report. The report step answers the delivery with HTTP 400, and the message is retried and eventually dead-lettered.

Input validation

TransactionEvent

Validated on the checks service for baseline checks.

Field Type Required Notes
id string yes Transaction UUID
time string yes HH:MM:SS
date string yes YYYY-MM-DD
amount float yes
currency string yes For example NGN
description string or null no
type string or null no For example bill payment
device string or null no
device_type string or null no For example Online
balance float or null no Account balance after the transaction

channel is not a TransactionEvent field.

lastCheckReport

The minimum structure for ML scoring, validated as LastCheckReportInput.

Field Required Notes
id yes Report id
customerProfileId yes
temporalChecks.prediction no (defaults to {}) Flat dictionary of boolean anomaly flags
transactionChecks.prediction no
locationChecks.prediction no
*LastProcessedDate no Date strings
createdAt no

ML prediction: what the scoring service emits

Field Type Description
probability_score float, 0 to 1 1.0 when a critical feature fires (a blacklist or watchlist match). Otherwise the sum of the highest triggered weight in each tier group, divided by the maximum possible, capped at 0.9
predicted_level string Critical Risk (score >= 1.0), High Risk (> 0.70), Mid Risk (> 0.30), Low Risk otherwise
interpretation object Human-oriented explanation per check. Not used for evidence or policy
observations object Per-check {status, description} flags

ML prediction: what the report step accepts

Field Rule
probability_score Float between 0 and 1
predicted_level One of Low Risk, Mid Risk, High Risk. Critical Risk is not accepted
Agreement predicted_level must equal the report step's own band for the score: High Risk if > 0.66, Mid Risk if > 0.33, otherwise Low Risk. A mismatch is rejected with ML_SCORE_TIER_CONFLICT; the report step does not recompute or correct the label

ML → dashboard normalisation (accepted predictions only)

fraudScore   = round(probability_score × 100)    # Python round(): halves go to the even number
riskCategory = high    if probability_score > 0.66
             = medium  if probability_score > 0.33
             = low     otherwise

Risk tiers: producer and consumer disagree

The two sides above do not agree. For the scoring service's own output, the report step behaves as follows:

Scoring service output Report step result
Critical Risk, score 1.0 Rejected (label not accepted)
Score in (0.66, 0.70], labelled Mid Risk Rejected (ML_SCORE_TIER_CONFLICT: the report step requires High Risk)
Score in (0.30, 0.33], labelled Mid Risk Rejected (ML_SCORE_TIER_CONFLICT: the report step requires Low Risk)
Score in (0.70, 0.90], High Risk Accepted
Score in (0.33, 0.66], Mid Risk Accepted
Score <= 0.30, Low Risk Accepted

What this means for integrators:

  • A 200 from ML scoring does not mean a report will follow. Critical (blacklist or watchlist) outcomes and the two boundary bands currently produce no dashboard report.
  • Reconcile scoring responses against received reports by transactionId, and treat a scored transaction with no report after your agreed interval as an incident.
  • This site does not choose between the possible fixes (align the report step to the scoring service, align the scoring service to the report step, or translate at the boundary). The owners have not yet decided.

The rule engine labels its own predicted_level with > 0.70 / > 0.30. The report step does not validate that label (see below), so rule predictions are not rejected, but the level in the rule response and the category on the dashboard report can differ.

Rule prediction output

Field Type Description
flagged bool Whether any rule matched
score float, 0 to 1 Rule severity score
passed_conditions list Condition trees whose predicate did not match
failed_conditions list Condition trees whose predicate matched
predicted_level Low Risk, Mid Risk or High Risk Advisory label from the rule engine. Ignored for engine identity and for riskCategory

Rule → dashboard normalisation

fraudScore   = round(score × 100)
riskCategory = low     if flagged is false
             = high    if flagged and score >= 0.66
             = medium  if flagged and score <  0.66

The high band is inclusive (>= 0.66) on the rule path and exclusive (> 0.66) on the ML path. A flagged rule score of 0.659 rounds to fraudScore 66 with riskCategory medium.

Unflagged rule results map to riskCategory = low with reason RULE_NOT_FLAGGED. Do not compare a rule fraudScore with an ML fraudScore as if they measured the same thing.

Evidence and labels

  • indicatorRecords use stable codes (for example BLACKLISTED_LOCATION_TRANSACTION), and fraudIndicators is the list of their labels.
  • severity is set only when the code carries a known signal: codes starting BLACKLISTED, SANCTIONS, KNOWN_FRAUD, SAR_ or UNUSUAL are high; codes starting HIGH or LARGE are medium. Unknown codes, including rule-condition UUIDs, omit severity rather than defaulting to low.
  • aiChecks has one item per observation or rule condition. Its status is triggered (the observation is true, or the rule predicate matched) or not_triggered. The producers' passed/failed wording is kept only in rawAnalysisResponse.
  • Rule labels describe the rule in business language (for example Transaction amount exceeds 5,000,000), and details separate the observed value from the threshold. Currency symbols are not invented when the envelope has no currency. A missing observed value is reported as actual value was unavailable, never as a silent pass.

Decision policy (fraud-decision-v1, provisional)

The primary decision is exactly one of approve, pend or block. Escalations (investigator_review, sar_review) are separate.

riskCategory Primary decision Escalation
low approve none
medium pend none
high block investigator_review if any indicator triggered

Named overrides (to be confirmed by compliance):

Signal Effect
BLACKLISTED_* At least pend
SANCTIONS_* / KNOWN_FRAUD_* At least block
SAR_* / SAR_TRIGGER Adds sar_review

A blacklist match can never produce approve, and adding an indicator can never lower the primary decision. Escalation labels are labels on the report; they are not regulatory filings.

Dashboard payload (AIReportResponse)

Delivered to POST {backend}/transaction/create-report with Authorization: ApiKey <jwt> and x-tenant-id (see Auth and tenancy).

Field Type Source
transactionId UUID Report message envelope
aiSummary string Language model or deterministic fallback
fraudScore int, 0 to 100 Normalisation
riskCategory low, medium or high Normalisation (from the score, never from the model)
fraudIndicators list of strings Labels derived from indicatorRecords
indicatorRecords list of FraudIndicator Stable code, label and source; severity only when authoritative
aiRecommendation list of strings [decision] followed by the escalations
decision approve, pend or block Policy
escalations list of investigator_review / sar_review Policy
reasonCodes list of strings Policy and evidence codes
aiChecks list of FraudCheckResult status is triggered or not_triggered
provenance object Contract and policy versions, prediction hash, source score
rawAnalysisResponse object The full report message
timestamp string Server time

Errors the report step can raise

Code Meaning
AMBIGUOUS_PREDICTION_CONTRACT Both engine shapes present, or neither identifiable
CHECK_TYPE_MISMATCH Declared check_type contradicts the prediction's keys
UNKNOWN_CHECK_TYPE Defined but not currently raised: an unrecognised check_type is treated as undeclared, and the engine is identified from the keys
ML_SCORE_TIER_CONFLICT ML predicted_level disagrees with the report step's band for the score
Validation error (no code) A required field is missing, or a value is outside the allowed set (for example Critical Risk)

All of them stop the report. The message is answered with HTTP 400 and no dashboard report is delivered.