Metadata-Version: 2.4
Name: fhiratwill.terminology_binder
Version: 0.2.0
Summary: Nearest-neighbor terminology binding for FHIR at Will.
Project-URL: Homepage, https://github.com/Safwanmahmoud/fhirbridge
Project-URL: Documentation, https://github.com/Safwanmahmoud/fhirbridge#readme
Project-URL: Source, https://github.com/Safwanmahmoud/fhirbridge
Project-URL: Issues, https://github.com/Safwanmahmoud/fhirbridge/issues
Author: fhiratwill contributors
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: fhir,healthcare,hl7,interoperability,terminology
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Healthcare Industry
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: fhiratwill<1,>=0.3.0
Requires-Dist: numpy<3,>=1.26
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == 'dev'
Requires-Dist: mypy<2,>=1.11; extra == 'dev'
Requires-Dist: pytest-asyncio<2,>=0.24; extra == 'dev'
Requires-Dist: pytest<9,>=8.3; extra == 'dev'
Requires-Dist: ruff<1,>=0.8; extra == 'dev'
Requires-Dist: twine<7,>=5.1; extra == 'dev'
Provides-Extra: nn
Requires-Dist: sentence-transformers<6,>=3; extra == 'nn'
Requires-Dist: torch<3,>=2.2; extra == 'nn'
Description-Content-Type: text/markdown

# fhiratwill.terminology_binder

Nearest-neighbor terminology binding for [FHIR at Will](https://github.com/Safwanmahmoud/fhirbridge).
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

```bash
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

```python
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.

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

```python
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:

```bash
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.
