Model Configuration

Audience: IT, Fraud Operations Last updated: March 2026 Version: 4.2

FraudShield AI Engine is configured through a set of YAML and INI files deployed alongside the application. Configuration controls channel mapping, Base Transaction Activity (BTA) definitions, enrichment provider integration, and multi-tenant setup. This page describes each configuration file, its key parameters, and how changes are applied.

Change management required All configuration changes must be reviewed and approved through your institution's change management process before being applied to production. Configuration errors can affect real-time scoring and fraud detection coverage. Always test changes in a staging environment first.

Configuration file structure

File	Format	Purpose	Reload required
`fs-core.yaml`	YAML	Core engine settings: API server, database connections, profile store, enrichment provider order.	Yes — restart engine
`bta-mapping.yaml`	YAML	Maps incoming `transaction_type` + `channel` combinations to Base Transaction Activities (BTAs).	Yes — restart engine
`enrichment-providers.yaml`	YAML	Enrichment provider credentials, endpoint URLs, timeout settings, and call order.	Yes — restart engine
`ri-config.ini`	INI	RI activation flags, score scale assignments, weight overrides, and population scope settings.	Hot-reload supported (up to 60 s lag)
`threshold-config.yaml`	YAML	Risk score thresholds and decision mapping per BTA and channel. Loaded by Decisioning Engine.	Hot-reload supported (up to 60 s lag)
`tenant-overrides.ini`	INI	Per-tenant parameter overrides for multi-tenant deployments. Values here take precedence over `ri-config.ini`.	Hot-reload supported

Core engine settings — `fs-core.yaml`

fs-core.yaml — key parameters

# FraudShield AI Engine — Core Configuration
# Version: 4.2 | Environment: production

server:
  host: "0.0.0.0"
  port: 8443
  tls_cert: "/etc/fraudshield/certs/server.crt"
  tls_key: "/etc/fraudshield/certs/server.key"
  request_timeout_ms: 3000

profile_store:
  type: "redis_cluster"
  nodes:
    - "redis-node-1:6379"
    - "redis-node-2:6379"
    - "redis-node-3:6379"
  profile_ttl_days: 90
  max_connections: 200

model_registry:
  path: "/var/fraudshield/models/"
  auto_load_on_startup: true
  champion_model_file: "champion.json"

audit_log:
  enabled: true
  destination: "kafka"
  kafka_topic: "fraudshield-audit"
  include_ri_details: true
  include_enrichment_data: false  # PII — disable unless required
  

Parameter	Default	Description
`server.request_timeout_ms`	`3000`	Maximum time (ms) allowed for the full scoring pipeline to complete. If exceeded, a TIMEOUT decision is returned and the transaction is approved by default (fail-open). Reduce only if your core system SLA is tighter.
`profile_store.profile_ttl_days`	`90`	How long profile data is retained. Shorter retention reduces storage cost but degrades 90-day rolling RI accuracy.
`audit_log.include_enrichment_data`	`false`	When `true`, enrichment responses (including IP address and device fingerprint) are written to the audit log. Enable only if required for regulatory purposes, as enrichment data may be classified as PII.

Base Transaction Activity mapping — `bta-mapping.yaml`

The BTA mapping file determines which detection model runs for each transaction. Every transaction_type + channel combination maps to exactly one BTA. The BTA then determines the active detection model and which RI categories are evaluated.

bta-mapping.yaml — example entries

bta_mappings:

  - transaction_type: "WIRE"
    channel: "WEB"
    bta_id: "WEB_WIRE_TRANSFER"
    detection_model: "MDL_WIRE_ATO"
    ri_categories: ["velocity", "amount_anomaly", "beneficiary", "device_channel", "network_ip", "behavioral"]

  - transaction_type: "ACH_CREDIT"
    channel: "BATCH"
    bta_id: "ACH_CREDIT_BATCH"
    detection_model: "MDL_ACH_FRAUD"
    ri_categories: ["velocity", "amount_anomaly", "beneficiary", "account_lifecycle"]

  - transaction_type: "RTP"
    channel: "MOBILE"
    bta_id: "MOB_RTP_SEND"
    detection_model: "MDL_RTP_MULE"
    ri_categories: ["velocity", "amount_anomaly", "beneficiary", "behavioral", "network_graph"]
  

Unmapped transaction types If a transaction arrives with a transaction_type or channel combination that has no BTA mapping, the engine uses the GENERIC_DEFAULT BTA and the fallback model. This generates a warning in the application log. Review unmapped combinations in the BTA Gap Report (Administration > Diagnostics).

Enrichment provider configuration — `enrichment-providers.yaml`

enrichment-providers.yaml — example

enrichment_providers:

  - name: "ip_intelligence"
    provider: "ipqualityscore"
    enabled: true
    endpoint: "https://ipqualityscore.com/api/json/ip"
    api_key_env_var: "IPQS_API_KEY"   # Never hard-code credentials
    timeout_ms: 400
    on_timeout: "skip"           # skip | fail-open | fail-closed

  - name: "device_fingerprint"
    provider: "threatmetrix"
    enabled: true
    org_id_env_var: "TMX_ORG_ID"
    timeout_ms: 300
    on_timeout: "skip"

  - name: "sanctions_screening"
    provider: "firco"
    enabled: true
    endpoint: "https://sanctions-api.internal/v2/screen"
    timeout_ms: 800
    on_timeout: "fail-closed"   # Block on timeout — regulatory requirement
  

Never store credentials in configuration files Use environment variables or a secrets manager (HashiCorp Vault, AWS Secrets Manager) for all provider API keys and credentials. The *_env_var parameter tells the engine which environment variable to read at startup.

Multi-tenant configuration

FraudShield AI supports multi-tenant deployments where multiple business units or subsidiary institutions share a single engine instance. Shared configuration applies to all tenants; tenant-specific overrides in tenant-overrides.ini take precedence.

Configuration precedence (highest to lowest)

tenant-overrides.ini — tenant-specific overrides
ri-config.ini — institution-wide RI settings
Built-in model defaults — factory settings

tenant-overrides.ini — example (Tenant: RETAIL_BANK_WEST)

[tenant:RETAIL_BANK_WEST]

# Override HIGH threshold — this tenant has lower risk appetite
threshold_high = 500
threshold_critical = 700

# Disable EAM uplift for accounts acquired via branch (staff-verified)
eam_uplift_channel_branch = false

# Activate insider fraud model for this tenant only
detection_model_override = MDL_INTERNAL_EMP
detection_model_btalist = BRANCH_WIRE_TRANSFER,BRANCH_ACH
  

Shared vs. tenant-specific parameters Parameters that affect all tenants (database connections, model registry path) must be set in fs-core.yaml. Only scoring behavior parameters (thresholds, RI weights, model selection) should appear in tenant overrides.