{
  "entity_id": "a1b2c3d4-...",
  "confidence": 0.94,
  "is_new": false,
  "canonical_data": {
    "email": "wsmith@acme.com",
    "first_name": "William",
    "last_name": "Smith",
    "phone": "+15550142"
  },
  "version": 7
}

{
  "entity_a_id": "a1b2c3d4-...",
  "entity_b_id": "e5f6g7h8-...",
  "confidence": 0.87,
  "evidence": {
    "email_match": { "score": 1.0, "values": ["wsmith@acme.com", "wsmith@acme.com"] },
    "name_match": { "score": 0.82, "values": ["William Smith", "Bill Smith"] },
    "phone_match": { "score": 1.0, "values": ["+15550142", "+15550142"] },
    "reasoning": "Same email and phone. Name differs but 'Bill' is a known nickname for 'William'."
  }
}

class IdentityMatcher:
    """
    Core matching logic for identity resolution.
    Compares two records field-by-field with type-aware scoring.
    """

    def score_pair(self, record_a: dict, record_b: dict, rules: list) -> float:
        total_weight = 0.0
        weighted_score = 0.0

        for rule in rules:
            field = rule["field"]
            val_a = record_a.get(field)
            val_b = record_b.get(field)

            if val_a is None or val_b is None:
                continue

            # Normalize before comparing
            val_a = self.normalize(val_a, rule.get("normalizer", "generic"))
            val_b = self.normalize(val_b, rule.get("normalizer", "generic"))

            # Compare using the specified method
            score = self.compare(val_a, val_b, rule.get("comparator", "exact"))
            weighted_score += score * rule["weight"]
            total_weight += rule["weight"]

        return weighted_score / total_weight if total_weight > 0 else 0.0

    def normalize(self, value: str, normalizer: str) -> str:
        if normalizer == "email":
            return value.lower().strip()
        elif normalizer == "phone":
            return re.sub(r"[^\d+]", "", value)  # Strip to digits
        elif normalizer == "name":
            return self.expand_nicknames(value.lower().strip())
        return value.lower().strip()

    def expand_nicknames(self, name: str) -> str:
        nicknames = {
            "bill": "william", "bob": "robert", "jim": "james",
            "mike": "michael", "dave": "david", "joe": "joseph",
            "tom": "thomas", "dick": "richard", "jack": "john",
        }
        return nicknames.get(name, name)

undefined

undefined