Metadata-Version: 2.4
Name: matchminer-ai
Version: 0.2.1
Summary: MatchMiner-AI package
Maintainer-email: Sabrina Camp <sabrinay_camp@dfci.harvard.edu>, Ken Kehl <Kenneth_Kehl@dfci.harvard.edu>
License-Expression: GPL-2.0-only
Project-URL: Homepage, https://github.com/dfci/matchminer-ai-inference
Project-URL: Repository, https://github.com/dfci/matchminer-ai-inference
Project-URL: Issues, https://github.com/dfci/matchminer-ai-inference/issues
Keywords: clinical-trials,oncology,trial-matching,natural-language-processing,large-language-models
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=2.4.4
Requires-Dist: pandas>=3.0.2
Requires-Dist: pyarrow>=24.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: sentence-transformers>=5.4.1
Requires-Dist: torch>=2.11.0
Requires-Dist: vllm>=0.20.2
Requires-Dist: huggingface_hub>=1.14.0
Requires-Dist: openai>=2.8.0
Requires-Dist: transformers>=5.8.0
Provides-Extra: dev
Requires-Dist: pre-commit>=3.7; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: ruff>=0.6.0; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: types-PyYAML; extra == "dev"
Provides-Extra: release
Requires-Dist: build>=1.2; extra == "release"
Requires-Dist: twine>=5.0; extra == "release"
Dynamic: license-file

# matchminer-ai

## Overview

`matchminer-ai` is a Python package for running the clinical trial matching inference workflow described in [Altreuter et al., MatchMiner-AI: An Open-Source Solution for Cancer Clinical Trial Matching](https://doi.org/10.48550/arXiv.2412.17228). The package provides modular functions for the core MatchMiner-AI workflow: summarizing trials and patient histories, generating embeddings of each, retrieving candidate matches, scoring match quality, and assessing exclusion criteria.

This package is currently pre-v1 and under active development. APIs, configuration options, and outputs may change.

## Compute requirements

The most compute-intensive step is summarizing patient notes with the default Gemma 4 language model. Full pipeline runs can use either a local high-memory GPU environment, such as an NVIDIA H100 80GB, or a compatible remote vLLM inference server configured with the Gemma 4 reasoning parser. See the [example notebook](examples/run_examples.ipynb) for details on these two options.

Other entry points, such as running from precomputed summaries, may require less compute.

## Installation

This package requires Python 3.13+.

```shell
pip install matchminer-ai
```

## Quickstart

See the example notebook for a full walkthrough using sample input data:
[example notebook](examples/run_examples.ipynb)

## Citation

If you use `matchminer-ai`, please cite:
>Altreuter J, Trukhanov P, Paul MA, Hassett MJ, Riaz IB, Afzal MU, Mohammed AA, Sammons S, Lindsay J, Mallaber E, Klein HR, Gungor G, Galvin M, Deletto M, Van Nostrand SC, Provencher J, Yu J, Tahir N, Wischhusen J, Kozyreva O, Ortiz T, Tuncer H, Masri JE, Malcolm A, Mazor T, Cerami E, Kehl KL. MatchMiner-AI: An Open-Source Solution for Cancer Clinical Trial Matching. *arXiv*. 2026. doi: [10.48550/arXiv.2412.17228](https://doi.org/10.48550/arXiv.2412.17228)

## Contributing

Clone the repository and install the package in editable mode. We recommend working in a virtual or conda environment.

```shell
git clone https://github.com/dfci/matchminer-ai-inference.git
cd matchminer-ai-inference
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
```

This repository uses pre-commit for local code quality checks. To enable the hooks:

```shell
pre-commit install
```

Run the test suite with:

```shell
# lightweight tests
pytest
# tests requiring GPU
pytest -m resource_heavy
```
