# Match Rule Simulator (SimPy + NumPy)

## PURPOSE
This project simulates the identity-resolution stage of the Fan 360 demo. It models the
recommended rule — **exact match on billing address + fuzzy match on full name** — as a
rule applied to incoming records from a newly integrated source, and simulates how many
records auto-match, how many land in a borderline review queue, and how long the
end-to-end run takes when reviews are handled by an automated agent, a human reviewer, or
both.

## WHY THIS MATTERS
The transcript shows Genie proposing a match rule, explaining why, and offering to route
borderline cases to review. Before trusting a rule in production you need to know its
precision/recall trade-off and the review load it creates. A discrete-event simulation
answers "how many reviewers do we need and what match rate do we get?" without touching
real customer data.

## HOW TO BUILD
1. `pip install simpy numpy pandas`
2. Generate a synthetic source with NumPy: names, billing addresses, phone numbers.
3. Implement `exact_address_match()` and `fuzzy_name_similarity()` (e.g. difflib or a
   normalized token ratio).
4. Combine them into a rule that returns MATCH / NO_MATCH / BORDERLINE.
5. Use SimPy `Environment` + `Resource` for reviewers; each borderline record consumes
   one review slot. Sweep the borderline threshold to plot match rate vs review load.

Key snippet:
```python
def classify(rec_a, rec_b, threshold):
    if norm(rec_a["billing_address"]) == norm(rec_b["billing_address"]):
        sim = name_similarity(rec_a["full_name"], rec_b["full_name"])
        if sim >= threshold:
            return "MATCH"
        if sim >= threshold - 0.15:
            return "BORDERLINE"
    return "NO_MATCH"
```

## WHEN TO USE IN PRODUCTION
Use it to size review teams, tune fuzzy thresholds, and forecast unified-profile growth
(recall the demo's 4.2 million unified profiles) before running expensive jobs. Do **not**
use the simulator as the production matcher — real matching belongs in a governed
identity-resolution engine with audit trails.

## HOW IT HELPS STUDENTS
Students learn discrete-event simulation, NumPy-based synthetic data generation, and
fuzzy-matching metrics. They see how a single rule parameter drives both accuracy and
operational cost — a genuinely production-grade way of thinking.

## STARTER CODE
`starter/main.py` builds a synthetic dataset, implements the exact+fuzzy rule, and runs a
SimPy review-queue simulation over a threshold sweep, printing match counts per run.
