# MediMate DDI

Exact-source drug interaction evidence lookup with explicit identity ambiguity and missing-evidence status. The supported public dataset is a transformed DDInter snapshot. An unlisted pair returns `unknown`; it is never interpreted as a no-interaction finding.

The optional trained source-grade models are research diagnostics. The linear baseline and ATC/structure tree model missed the registered performance bar. Source grades always take precedence. No clinical approval or broad Vietnamese interaction coverage is claimed.

## Install

Python 3.12 or newer:

```sh
python -m venv .venv
.venv/bin/python -m pip install -e '.[test]'
.venv/bin/python -m pytest
```

On Windows, use `.venv\Scripts\python.exe`. Dependencies are pinned in `pyproject.toml`.

## Download the source dataset

Download the [dataset release](https://huggingface.co/datasets/nthan2005/medimate-ddi-ddinter-positive-v1). Set `DATASET` to the downloaded directory containing `manifest.json`, `source_assertions.jsonl` and `drugs.jsonl`. The loader checks the artifact SHA-256 values before serving. One way to download the releases is:

```sh
python -m pip install huggingface_hub
python -c "from huggingface_hub import snapshot_download; snapshot_download('nthan2005/medimate-ddi-ddinter-positive-v1', repo_type='dataset', local_dir='ddi-data')"
python -c "from huggingface_hub import snapshot_download; snapshot_download('nthan2005/medimate-ddi-conditional-source-v1', local_dir='ddi-model')"
```

```sh
medimate-ddi-lookup --dataset ddi-data Naltrexone Abacavir imaginary-drug
```

The result contains all three unordered pairs. Naltrexone/Abacavir has a source-recorded Moderate assertion; the two pairs involving the imaginary name return `unknown`. Names shared by multiple source identifiers return ambiguous candidates, with pair lookup abstention. To inspect a research estimate for a recorded pair whose source grade is `Unknown`, run `medimate-ddi-lookup --dataset ddi-data --model ddi-model Abacavir Ketotifen`; the estimate does not create a new interaction assertion.

## Real MCP server

The MCP Python SDK provides the stdio transport:

```sh
medimate-ddi-mcp --dataset ddi-data
```

Configure an MCP client with that executable and arguments. It exposes `normalize_drug_set` and `lookup_ddi_set`; both accept `{"drugs": ["Naltrexone", "Abacavir"]}`. Tools have no writes. The prescription-set tool checks each unordered pair for lists of one to eight names. Tests initialize a real MCP client and call both discovery and evidence tools over stdio.

A separate REST adapter is available with `medimate-ddi-serve --dataset "$DATASET"`. Its HTTP routes are a convenience API, not an MCP transport.

## Architecture

```mermaid
flowchart LR
  Input[Names or source IDs] --> Identity[Exact identity candidates]
  Identity --> Pair[Every unordered pair]
  Pair --> Source[Hash-pinned source assertions]
  Source --> Output[Recorded assertion or unknown]
  Source --> Research[Optional conditional source-grade research]
```

The public path resolves DDInter names/IDs only. [Vietnamese source references](VIETNAM_SOURCES.md) document the private evidence inventory and its unresolved extraction issues. A private multi-source bridge can supply separately licensed RxNorm/product/formulation candidates, regulatory source candidates and observational TWOSIDES signals. That private snapshot is not distributed here. Product salts, formulations and competing brand compositions require separate provenance; this package does not infer them.

## Research reproducibility and limits

The source-native structure corpus was joined through exact DDInter identifiers and audited page names. Pair duplicates are collapsed; conflicts, unknown source grades and unsupported structures are excluded from conditional-grade supervision. Parent identities and drug IDs are disjoint across the original train/development/test partitions. Cross-partition pairs are excluded. This is not a scaffold-disjoint or source-independent clinical benchmark.

Original linear diagnostic: 1,633 held-out graded source pairs, macro-F1 0.3729 and Major recall 0.3872. ATC/structure tree diagnostic: development macro-F1 0.5673; one fresh 173-pair partial-cold test macro-F1 0.4457 and Major recall 11/32. The second test is small and permits a previously seen partner drug. Neither result meets the registered macro-F1 0.80 / Major recall 0.95 bar. The linear research weights are available at [nthan2005/medimate-ddi-conditional-source-v1](https://huggingface.co/nthan2005/medimate-ddi-conditional-source-v1); they cannot establish an interaction. Pass `--model MODEL_DIR` to `medimate-ddi-lookup` to inspect an estimated grade only for a source-recorded, ungraded pair with verified structures. Exact evidence lookup performance is a separate engineering property.

Users may reproduce source acquisition locally through `medimate-ddi --workspace WORKSPACE fetch`, construction with `build`, and a **new** linear diagnostic with `freeze` followed by `train`; obtain the eight CSVs separately from the official DDInter download page into `WORKSPACE/data/ddinter`. Raw source pages remain local. `freeze` writes `WORKSPACE/warehouse/mlops/ddi_conditional_20261003/protocol-v1.json` with the exact dataset and trainer hashes and refuses to overwrite an existing protocol. Run these commands in a fresh workspace, in that order. A modified script or dataset cannot silently claim the original score.

Historical generated negative pairs and the old containment benchmark are excluded. The historical benchmark's unconditional containment calculation is not valid evidence. No MIMIC, MIMIC-derived weights or excluded commercial database records are included.

## Rights

Code: MIT. DDInter-derived data: CC BY-NC-SA 4.0, with attribution to the DDInter team and the original database publication. Preserve attribution, noncommercial and share-alike obligations. See the official [DDInter terms](https://ddinter.scbdd.com/terms/) and `source_rights.json`.

RxNorm's NLM normalized names/codes are public domain, while proprietary source atoms have distinct restrictions. The mixed private snapshot is references-only here. TWOSIDES, DTQG, BYT and DAV are source references pending verified redistribution scope. Public access alone does not grant redistribution rights. Source coverage is incomplete and source-reported grades are not independently reviewed treatment recommendations.