Metadata-Version: 2.4
Name: clinpgx-term-lookup
Version: 0.1.0
Summary: Fuzzy term lookup for ClinPGx/PharmGKB: drugs and variants, via the PharmGKB and RxNorm APIs
Author-email: Shlok Natarajan <shlok.natarajan@gmail.com>
License: MIT License
        
        Copyright (c) 2025 Shlok Natarajan
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/shloknatarajan/ClinPGxTermNorm
Project-URL: Repository, https://github.com/shloknatarajan/ClinPGxTermNorm
Project-URL: Issues, https://github.com/shloknatarajan/ClinPGxTermNorm/issues
Keywords: pharmgkb,clinpgx,pharmacogenomics,rxnorm,drug,variant,lookup
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.32
Requires-Dist: pydantic>=2.11.7
Requires-Dist: loguru>=0.7.3
Dynamic: license-file

# clinpgx-term-lookup

Fuzzy term lookup for [ClinPGx](https://www.clinpgx.org/) / [PharmGKB](https://www.pharmgkb.org/):
take a free-text drug or variant term and resolve it to its ClinPGx record.

It is **API-only** — no local data files to download. Lookups are served by the
public [PharmGKB](https://api.pharmgkb.org/) and
[RxNorm](https://rxnav.nlm.nih.gov/) APIs, so results stay current and the
package stays small. An internet connection is required at lookup time.

## Installation

```bash
pip install clinpgx-term-lookup
```

## Usage

### Drugs

```python
from clinpgx_term_lookup import DrugLookup

results = DrugLookup().search("warfarin")
for r in results:
    print(r.name, r.id, r.url, r.score, r.source)
```

The drug lookup:

1. Tries an exact PharmGKB chemical name match.
2. On a miss, fuzzy-matches the term with RxNorm's `approximateTerm` endpoint,
   resolves it to its ingredient (so brand names like `Tylenol` map to
   `acetaminophen`), and re-queries PharmGKB by that name.
3. On a miss, returns the RxNorm result itself as a fallback (with
   `source="rxnorm"`).

So misspellings (`warfarn`) and trade names (`tylenol`) both resolve to the
right PharmGKB chemical.

### Variants

```python
from clinpgx_term_lookup import VariantLookup

VariantLookup().search("rs1234")        # rsID  -> variant endpoint
VariantLookup().search("CYP2C19*2")     # star allele -> haplotype endpoint
```

Terms starting with `rs` are looked up as rsIDs; everything else is treated as
a star allele.

### Result objects

Both lookups return a list of Pydantic models with these fields:

| Field       | Description                                  |
| ----------- | -------------------------------------------- |
| `raw_input` | The original query string                    |
| `id`        | PharmGKB accession ID (or `RXN<rxcui>`)      |
| `name`      | The matched name                             |
| `url`       | Link to the ClinPGx (or RxNorm) record       |
| `score`     | 0–1 fuzzy similarity to the query            |
| `source`    | `"pharmgkb"` or `"rxnorm"`                    |

## Command line

```bash
clinpgx-term-lookup warfarin --type drug
clinpgx-term-lookup rs1234 --type variant
```

Output is JSON. Use `--top-k` and `--threshold` to tune results.

## License

MIT. Note that lookups query the PharmGKB and RxNorm APIs; their data is subject
to their respective terms of use.
