feat(linking): implement possible match short-term

[alhayward]

Description

• Implement Possible Match using short-term approach: Apply a user-configurable range to the Belongingness Ratio threshold.
• To support Possible Match, update Link API response as follows:

Example: belongingness_ratio=[0.75, 0.9]

No Match

{
    "patient_reference_id": "5a12bf00-16f8-4c03-b980-81d3f5ff6db6",
    "person_reference_id": "b104942e-6327-4643-801a-5fb22cb621c4", # New Person ID
    "results": []
}

Possible Match

{
    "patient_reference_id": "c5fcfc39-a915-4b65-afc7-b681c892652e",
    "person_reference_id": None,
    "results": [
        {
            "person_reference_id": "bf27f9f2-2882-4e6f-9db9-6a916679cff7",
            "belongingness_ratio": 0.8
        }
    ]
}

Match include_multiple_matches=false

{
    "patient_reference_id": "2eb14d86-217f-45c3-a528-d038e7eadce7",
    "person_reference_id": "6abb63cb-6c31-4142-bdbf-8b2956dab1c1",
    "results": [
        {
            "person_reference_id": "6abb63cb-6c31-4142-bdbf-8b2956dab1c1",
            "belongingness_ratio": 0.98
        },
    ]
}

Match include_multiple_matches=true

{
    "patient_reference_id": "2eb14d86-217f-45c3-a528-d038e7eadce7",
    "person_reference_id": "6abb63cb-6c31-4142-bdbf-8b2956dab1c1", # Person ID with highest Belongingness Ratio
    "results": [
        {
            "person_reference_id": "6abb63cb-6c31-4142-bdbf-8b2956dab1c1",
            "belongingness_ratio": 0.98
        },
        {
            "person_reference_id": "8acf6104-d633-4516-8c7f-2c6e88a8ceae",
            "belongingness_ratio": 0.8
        },
    ]
}

Related Issues

#91

Additional Notes

• Rename cluster_ratio -> belongingness_ratio for clarity
• Move belongingness_ratio definition from AlgorithmPass to Algorithm level (this was the DIBBs team's original intent)
• Add user-configurable Algorithm.include_multiple_matches boolean parameter to return multiple matches
  • Given belongingness_ratio=[X, Y], if Algorithm.include_multiple_matches=true, return all resultswherebelongingness_ratio >= X]. Assign person_reference_id of Person with highest Belongingness Ratio.
• Add test coverage for
  • Possible Match result (Basic, Enhanced Algorithm)
  • New Link API response (LinkResponse, LinkFhirResponse)
  • Include multiple matches or not (Algorithm.include_multiple_matches)
• Add new test patient bundle assets for above coverage

<--------------------- REMOVE THE LINES BELOW BEFORE MERGING --------------------->

Checklist

Please review and complete the following checklist before submitting your pull request:

• I have ensured that the pull request is of a manageable size, allowing it to be reviewed within a single session.
• I have reviewed my changes to ensure they are clear, concise, and well-documented.
• I have updated the documentation, if applicable.
• I have added or updated test cases to cover my changes, if applicable.
• I have minimized the number of reviewers to include only those essential for the review.

Checklist for Reviewers

Please review and complete the following checklist during the review process:

• The code follows best practices and conventions.
• The changes implement the desired functionality or fix the reported issue.
• The tests cover the new changes and pass successfully.
• Any potential edge cases or error scenarios have been considered.

[codecov]

Codecov Report

Attention: Patch coverage is 96.10390% with 3 lines in your changes missing coverage. Please review.

Project coverage is 95.56%. Comparing base (379cd47) to head (68c93ec).
Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
src/recordlinker/routes/link_router.py	81.81%	2 Missing ⚠️
src/recordlinker/schemas/link.py	95.45%	1 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #111   +/-   ##
=======================================
  Coverage   95.56%   95.56%           
=======================================
  Files          31       31           
  Lines        1375     1421   +46     
=======================================
+ Hits         1314     1358   +44     
- Misses         61       63    +2     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

---

🚨 Try these New Features:

• Flaky Tests Detection - Detect and resolve failed and flaky tests

[ericbuckley]

This looks great @alhayward thanks for all your work on updating the unit tests!