README.md

---
license: apache-2.0
library_name: sklearn
---
# Motor Insurance Claims Decision Model

## Model Description

This is a Logistic Regression model for motor insurance claims decision support. The model predicts whether a claim should be **approved**, sent for **review**, or **rejected** based on claim characteristics.

**Model Type:** Logistic Regression (Multinomial)  
**Version:** v1  
**Framework:** scikit-learn  
**Language:** Python 3.9+

## Intended Use

### Primary Use Case
This model is designed for **human-in-the-loop decision support** in motor insurance claims processing. It provides:
- A recommended decision (approve/review/reject)
- Confidence score for the recommendation
- Top 3 factors influencing the decision

### Intended Users
- Insurance claims adjusters
- Claims processing teams
- Risk assessment specialists

### Out-of-Scope Use
❌ **This model should NOT be used for:**
- Fully automated claims decisions without human review
- Legal or regulatory compliance decisions
- Claims outside motor insurance domain
- High-value claims above $50,000 without additional review
- Fraud detection (not trained for this purpose)

## Model Architecture

**Algorithm:** Logistic Regression with multinomial classification  
**Solver:** lbfgs  
**Class Balancing:** Enabled (class_weight='balanced')

### Input Features (10 total)
1. **Claim Amount** - Dollar amount claimed
2. **Vehicle Age** - Age of vehicle in years
3. **Accident Type** - Category (collision, theft, vandalism, weather_damage, fire)
4. **Police Report** - Whether police report exists (yes/no)
5. **Repair Estimate** - Estimated repair cost
6. **Prior Claims** - Number of previous claims
7. **Claim to Estimate Ratio** - Derived feature
8. **High Claim Flag** - Binary flag for claims > $15,000
9. **Old Vehicle Flag** - Binary flag for vehicles > 10 years
10. **Multiple Claims Flag** - Binary flag for > 2 prior claims

### Output Format
```json
{
  "decision": "approve|review|reject",
  "confidence": 0.0-1.0,
  "top_factors": ["factor_1", "factor_2", "factor_3"]
}
```

## Training Data

**Dataset:** insurance-motor-claims-decision-v1  
**Source:** Synthetic data generated with logical business rules  
**Size:** 800 records (640 training, 160 test)  
**Split:** 80/20 train-test, stratified by decision class

### Class Distribution (Training Set)
- **Review:** ~73% (most common)
- **Approve:** ~22%
- **Reject:** ~5%

## Performance Metrics

**Test Accuracy:** 86.4%

### Per-Class Performance
| Decision | Precision | Recall | F1-Score | Support |
|----------|-----------|--------|----------|---------|
| Approve  | 0.86      | 0.89   | 0.87     | 35      |
| Reject   | 0.44      | 1.00   | 0.62     | 8       |
| Review   | 0.95      | 0.71   | 0.81     | 117     |

**Macro Average:** Precision 0.75, Recall 0.87, F1 0.76  
**Weighted Average:** Precision 0.86, Recall 0.86, F1 0.78

## Explainability

This model uses Logistic Regression specifically for its explainability. Each prediction includes:

1. **Decision Coefficients:** Linear weights showing how each feature influences each decision type
2. **Top Factors:** The 3 most influential features for each specific prediction
3. **Confidence Score:** Probability of the predicted class

### Key Decision Factors

**APPROVE Decision - Influenced by:**
- Police Report presence (increases likelihood)
- Lower prior claims count
- Reasonable claim-to-estimate ratio

**REJECT Decision - Influenced by:**
- High claim flag (claims > $15,000)
- Multiple prior claims
- Large claim-to-estimate ratio discrepancy

**REVIEW Decision - Influenced by:**
- Moderate claim amounts
- Accident type (certain types trigger review)
- Old vehicle flag

## Limitations

### Known Limitations
1. **Synthetic Training Data:** Model trained on synthetic data, not real claims
2. **Class Imbalance:** Reject class has limited examples (5% of data)
3. **Feature Coverage:** Does not consider driver history, location, or policy details
4. **Temporal Factors:** No consideration of claim timing or seasonal patterns
5. **Fraud Detection:** Not designed to detect fraudulent claims
6. **Currency:** Assumes USD, no currency conversion
7. **Vehicle Types:** No distinction between vehicle types (sedan, truck, luxury, etc.)

### Performance Limitations
- **Reject Class:** Lower precision (0.44) due to limited training examples
- **Review Class:** Lower recall (0.71) - may miss some cases requiring review
- **Confidence Calibration:** Confidence scores may not be perfectly calibrated

## Known Failure Cases

### 1. Edge Case Claims
**Scenario:** Claims with unusual combinations (e.g., very old vehicle with very low claim amount)  
**Impact:** Model may provide low-confidence predictions  
**Mitigation:** Always review predictions with confidence < 0.6

### 2. High-Value Claims
**Scenario:** Claims exceeding $30,000  
**Impact:** Limited training data in this range may reduce accuracy  
**Mitigation:** Automatically route high-value claims for manual review

### 3. Missing Police Reports for Theft
**Scenario:** Theft claims without police reports  
**Impact:** Model may incorrectly approve when rejection is warranted  
**Mitigation:** Implement business rule override for theft + no police report

### 4. Multiple Prior Claims Edge Cases
**Scenario:** Customers with 5+ prior claims but legitimate current claim  
**Impact:** May be incorrectly flagged for rejection  
**Mitigation:** Human review required for customers with extensive claim history

### 5. Claim-to-Estimate Ratio Anomalies
**Scenario:** Claim amount significantly different from repair estimate  
**Impact:** May trigger incorrect review/reject decisions  
**Mitigation:** Investigate discrepancies before accepting model recommendation

## Ethical Considerations

### Bias Considerations
- Model does not consider demographic information (age, gender, location)
- Synthetic data may not reflect real-world claim distributions
- Class imbalance may lead to under-representation of reject cases

### Fairness
- Model should be monitored for disparate impact across customer segments
- Regular audits recommended to ensure fair treatment
- Human oversight required for all final decisions

### Privacy
- Model does not require or use personally identifiable information (PII)
- Input features are claim-specific, not customer-specific
- Logging mechanism should comply with data retention policies

## Usage Instructions

### Installation
```bash
pip install scikit-learn joblib numpy pandas
```

### Loading the Model
```python
from predict import ClaimsDecisionPredictor

predictor = ClaimsDecisionPredictor('model_artifacts')
```

### Making Predictions
```python
claim = {
    "claim_amount": 5000.0,
    "vehicle_age": 5,
    "accident_type": "collision",
    "police_report": "yes",
    "repair_estimate": 4800.0,
    "prior_claims": 1
}

result = predictor.predict(claim)
print(result)
# Output: {"decision": "approve", "confidence": 0.85, "top_factors": [...]}
```

### With Logging
```python
result = predictor.predict_with_logging(claim)
```

## Model Governance

### Version Control
- **Current Version:** v1
- **Release Date:** January 1, 2026
- **Model Hash:** Stored in metadata.json

### Monitoring Recommendations
1. Track prediction distribution (approve/review/reject ratios)
2. Monitor confidence score distributions
3. Collect human override data for model retraining
4. Review logs monthly for drift detection
5. Retrain quarterly with new data

### Update Triggers
- Accuracy drops below 80%
- Significant change in claim patterns
- New business rules introduced
- Regulatory requirement changes

## Disclaimer

⚠️ **IMPORTANT:** This model provides **decision support only**. All final decisions must be made by qualified human claims adjusters. The model is not a substitute for professional judgment, regulatory compliance, or legal requirements.

This model is provided "as-is" without warranties. Users are responsible for:
- Validating predictions before taking action
- Ensuring compliance with insurance regulations
- Maintaining human oversight of all decisions
- Monitoring for bias and fairness issues

## Contact & Support

**Model Maintainer:** BDR AI Organization  
**Dataset:** [insurance-motor-claims-decision-v1](https://huggingface.co/datasets/bdr-ai-org/insurance-motor-claims-decision-v1)  
**License:** MIT (for demonstration purposes)

## Citation

```bibtex
@misc{insurance_claims_model_v1,
  title={Motor Insurance Claims Decision Support Model},
  author={BDR AI Organization},
  year={2026},
  publisher={Hugging Face},
  version={v1}
}
```