docs/MODEL_CONTRACT.md

Model Contract Documentation

Overview

The FraudSimulator-AI system implements a strict model contract to ensure consistency, reliability, and auditability across all fraud detection decisions.

Model Identity

Model Name: fraud-risk-agent
Version: 1.0.0
Type: Decision Intelligence Agent
Domain: Insurance Fraud Detection
Decision Output: investigate | allow

Input Contract

Required Fields

{
  "claim_id": "string (required)",
  "amount": "float (required)",
  "type": "string (required)",
  "claimant_id": "string (required)",
  "days_since_policy_start": "integer (required)"
}

Optional Fields

{
  "average_claim_amount": "float (default: 5000)",
  "claimant_history": {
    "claim_count": "integer (default: 0)",
    "avg_amount": "float (default: 5000)",
    "total_paid": "float (default: 0)"
  },
  "document_consistency_score": "float 0.0-1.0 (default: 1.0)",
  "linked_suspicious_entities": "integer (default: 0)"
}

Input Validation Rules

• amount must be > 0
• days_since_policy_start must be ≥ 0
• document_consistency_score must be between 0.0 and 1.0
• linked_suspicious_entities must be ≥ 0
• claim_id must be unique
• type must be one of: ["auto", "property", "health", "life", "other"]

Output Contract (STRICT)

Mandatory Fields

The model MUST return exactly these fields:

{
  "fraud_score": "float (0.0-1.0, 3 decimal places)",
  "risk_band": "string (low | medium | high)",
  "top_indicators": "array of strings",
  "recommended_action": "string (investigate | allow)",
  "confidence": "float (0.0-1.0, 3 decimal places)",
  "explainability": {
    "signals": "array of objects",
    "weights": "object (indicator -> weight mapping)"
  }
}

Field Specifications

fraud_score

• Type: Float
• Range: 0.0 to 1.0
• Precision: 3 decimal places
• Description: Overall fraud risk score

risk_band

• Type: String (enum)
• Values: "low" | "medium" | "high"
• Mapping:
  • "high": fraud_score ≥ 0.7
  • "medium": 0.4 ≤ fraud_score < 0.7
  • "low": fraud_score < 0.4

top_indicators

• Type: Array of strings
• Max Length: 5
• Description: Top fraud indicators ranked by contribution
• Possible Values:
  • "amount_deviation"
  • "high_frequency"
  • "early_claim"
  • "document_mismatch"
  • "entity_linkage"

recommended_action

• Type: String (enum)
• Values: "investigate" | "allow"
• Logic:
  • "investigate" if fraud_score ≥ 0.65
  • "allow" if fraud_score < 0.65

confidence

• Type: Float
• Range: 0.0 to 1.0
• Precision: 3 decimal places
• Description: Confidence in the decision

explainability

• Type: Object
• Required Fields:
  • signals: Array of signal objects
  • weights: Object mapping indicators to weights

Signal Object Structure:

{
  "indicator": "string (indicator name)",
  "value": "float (0.0-1.0, 3 decimal places)",
  "description": "string (human-readable explanation)"
}

Weights Object Structure:

{
  "amount_deviation": 0.25,
  "high_frequency": 0.20,
  "early_claim": 0.15,
  "document_mismatch": 0.25,
  "entity_linkage": 0.15
}

Output Example

{
  "fraud_score": 0.742,
  "risk_band": "high",
  "top_indicators": [
    "early_claim",
    "amount_deviation",
    "entity_linkage",
    "document_mismatch"
  ],
  "recommended_action": "investigate",
  "confidence": 0.856,
  "explainability": {
    "signals": [
      {
        "indicator": "early_claim",
        "value": 1.000,
        "description": "Claim filed shortly after policy inception"
      },
      {
        "indicator": "amount_deviation",
        "value": 0.667,
        "description": "Claim amount significantly differs from average"
      }
    ],
    "weights": {
      "amount_deviation": 0.25,
      "high_frequency": 0.20,
      "early_claim": 0.15,
      "document_mismatch": 0.25,
      "entity_linkage": 0.15
    }
  }
}

Model Behavior Guarantees

Determinism

• Same input MUST produce same output (given same model version)
• No randomness in decision logic
• Reproducible for audit purposes

Performance

• Latency: < 100ms per prediction (p95)
• Throughput: > 1000 predictions/second
• Availability: 99.9% uptime

Accuracy

• Precision: ≥ 75% (validated on test set)
• Recall: ≥ 80% (validated on test set)
• F1 Score: ≥ 0.77

Explainability

• 100% of decisions include explainability payload
• All signals have human-readable descriptions
• Weights sum to 1.0

Error Handling

Input Validation Errors

{
  "error": "INVALID_INPUT",
  "message": "Detailed error description",
  "field": "Field name that failed validation",
  "value": "Invalid value provided"
}

Model Errors

{
  "error": "MODEL_ERROR",
  "message": "Internal model error",
  "model_version": "1.0.0",
  "timestamp": "ISO 8601 timestamp"
}

Versioning

Version Format

MAJOR.MINOR.PATCH

• MAJOR: Breaking changes to input/output contract
• MINOR: New features, backward compatible
• PATCH: Bug fixes, no contract changes

Version History

1.0.0 (2026-01-01)

• Initial release
• Core fraud detection logic
• Five fraud indicators
• Binary decision output (investigate | allow)

Deprecation Policy

• Major versions supported for 12 months after new major release
• Minor versions supported for 6 months after new minor release
• Deprecation warnings provided 3 months in advance

Testing & Validation

Unit Tests

• Input validation
• Indicator calculation
• Score calculation
• Decision logic
• Explainability generation

Integration Tests

• End-to-end prediction flow
• Error handling
• Performance benchmarks

Validation Dataset

• 10,000 labeled claims
• Balanced fraud/legitimate split
• Diverse claim types and amounts
• Regular updates with new fraud patterns

Compliance

This model contract complies with:

• BDR-Agent-Factory: Registered in capability registry
• IFRS 17: Actuarial soundness
• AML Standards: Fraud pattern detection
• Explainability Requirements: Full XAI support
• Audit Standards: Complete traceability

Support

For model contract questions:

• Documentation: See DECISION_LOGIC.md and GOVERNANCE.md
• Technical Support: data-science@bdr-ai.com
• Contract Changes: Submit RFC to architecture team