fhiratwill.terminology_binder

Nearest-neighbor terminology binding for FHIR at Will. A free-text phrase is embedded with SapBERT and matched by cosine similarity against one or more dictionaries. ICD-10-CM is loaded by default. Codes always come from a catalog row; the model never invents a code.

Alpha software. Binding logic in this package is expected to change.

Install

pip install "fhiratwill.terminology_binder[nn]"

The [nn] extra installs sentence-transformers and torch for the default SapBERT encoder. The base install is enough if you inject your own encoder.

Bind a phrase or a Bundle

from fhiratwill.terminology_binder import Dictionary, TerminologyIndex, bind_bundle

index = TerminologyIndex.load()  # ICD-10-CM by default
result = index.bind("type 2 diabetes")
print(result.coding)
# {'system': 'http://hl7.org/fhir/sid/icd-10-cm', 'code': 'E11.9', 'display': '...'}

bound = await bind_bundle(bundle, index=index)

confidence is not the cosine. It uses the sample standard deviation of the k neighbor scores so a tight pack cannot look sure: min(1, s1 * std / 0.10).

Add your own dictionaries

A dictionary is JSON: either a concept list (pass name and system) or an object that already includes them.

{
  "name": "loinc",
  "system": "http://loinc.org",
  "concepts": [
    {"code": "8867-4", "display": "Heart rate", "aliases": ["pulse"], "leaf": true}
  ]
}

loinc = Dictionary.from_path("loinc.json")
index = TerminologyIndex.load()
index.add_dictionary(loinc)

index = TerminologyIndex.load(loinc)  # ICD-10-CM + LOINC
index = TerminologyIndex.load(loinc, include_default=False)  # LOINC only

First ICD-10-CM embed is cached under %LOCALAPPDATA%/fhiratwill/terminology_binder (or $XDG_CACHE_HOME/fhiratwill/terminology_binder). Override with FHIRATWILL_BINDER_CACHE. Later runs only encode the query.

Development

From the fhirbridge repository root:

python -m pip install -e ".[dev]"
python -m pip install -e "./packages/terminology-binder[nn]"
pytest packages/terminology-binder/tests
python -m build packages/terminology-binder
twine check packages/terminology-binder/dist/*

Tests inject a fake encoder and do not download SapBERT.

License

Apache License 2.0.