Patient Matching Library

What it is

An open-source Python library (Apache-2.0) that performs deterministic patient matching over FHIR R4 Patient resources. It has no HTTP layer of its own. Requires Python 3.12 or later.

It provides:

• The Table 2 rule set. Its README describes 39 rules: 29 Category 1 (flat) and 10 Category 2 (eight household-then-individual rules and two relationship-linkage rules), with exact and fuzzy comparison and handling for multiple births.
• Normalization. Text, names (including nicknames and suffix handling), phone (E.164), address (USPS standardization), identifiers, dates, and placeholder detection. See Normalization.
• A candidate cache with field-level indexing and fuzzy search, backed by in-process DuckDB or by MongoDB Atlas Search for deployments that share one cache across replicas.
• A FHIR client with OAuth2 for building the cache from a FHIR server.
• Confidence scoring based on the P(collision) values of the matched rule.

Install

pip install cms-hte-patient-matching

Optional extras: [fhir], [cache], [mongo], [scheduler], and [all]. See the README for what each installs.

Using it

The simplest entry point is PatientMatcherService, which chains normalization and matching against a cache:

from patient_matching.api import PatientMatcherService
from patient_matching.cache import DuckDBCache

cache = DuckDBCache()  # populate it first, for example with CacheManager
service = PatientMatcherService(cache=cache)
response = await service.match_patient(query_patient)

print(response.outcome)           # "match", "no_match", or "ambiguous"
print(response.confidence_score)  # 0.0 - 1.0
print(response.matched_patient_ids)

Populating the cache, and building a MatchingEngine directly instead, are shown in the README's Quick Start. All the matching and cache methods are async. The README's own PatientMatcherService example passes an engine argument that the constructor does not accept; the constructor takes cache, and optionally normalizer and config, as keyword arguments.

IAL2 tokens

The library does not verify or extract IAL2 tokens. Convert the token to a FHIR Patient first (see Service and IAL2 Reader), then pass the resulting Patient to the library.

How it relates to the specification

• Version. The README describes it as an implementation of the CMS Patient Matching Proposal v3.4.0.
• Rule 29 is not implemented. The specification v3.4.0 still lists rule 29 in Table 2. The library omits it ahead of proposal v3.4.1, which would remove it and is currently under review (issue #7). This is why the library's rule count is one lower than the specification's Category 1 count.
• Rule IDs. The library keeps the specification's Category 1 IDs. It prefixes Category 2 IDs with C2- (for example C2-13) because the specification's section III.C.8 prose uses the legacy numbers 13, 14, 15, 16, 34, 35, 37 and 38 for the household-then-individual rules, which would collide with Category 1 rules 13 to 16. See the Spec-to-Code Map.
• P(collision) values. The library computes each rule's figures from per-field u-values. Its README table lists a few values that differ from the specification's Table 2 (see the Spec-to-Code Map).

License and contributing

Apache-2.0. See Contribute for how to contribute and Report an Issue for where to send library bugs.