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

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

### Optional Fields

```json
{
  "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:

```json
{
  "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**:
```json
{
  "indicator": "string (indicator name)",
  "value": "float (0.0-1.0, 3 decimal places)",
  "description": "string (human-readable explanation)"
}
```

**Weights Object Structure**:
```json
{
  "amount_deviation": 0.25,
  "high_frequency": 0.20,
  "early_claim": 0.15,
  "document_mismatch": 0.25,
  "entity_linkage": 0.15
}
```

### Output Example

```json
{
  "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

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

### Model Errors

```json
{
  "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