Metadata-Version: 2.4
Name: biodrug-intelligence
Version: 1.2.1
Summary: A local pharmacogenomics evidence research workbench
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Provides-Extra: ml
Requires-Dist: scikit-learn>=1.4; extra == "ml"
Requires-Dist: joblib>=1.3; extra == "ml"
Provides-Extra: dl
Requires-Dist: scikit-learn>=1.4; extra == "dl"
Requires-Dist: joblib>=1.3; extra == "dl"
Requires-Dist: numpy>=1.26; extra == "dl"
Requires-Dist: torch>=2.2; extra == "dl"

# BioDrug Intelligence 1.2.1

BioDrug Intelligence is a local-first pharmacogenomics evidence-retrieval and research workbench. It loads a user-supplied JSON or VCF profile, searches local evidence records for a medication, reports explicitly annotated gene-name overlap, and exports a text and JSON report. It is not a trained drug-response prediction model and does not make clinical recommendations.

## Install from source

Python 3.10 or newer is required. The desktop interface uses Tkinter, which is commonly included with Python installers; some Linux distributions package it separately.

### Windows CMD

```bat
py -m venv .venv
.venv\Scripts\activate
py -m pip install --upgrade pip
py -m pip install -e .
biodrug
```

Run the command-line interface instead:

```bat
biodrug-cli
```

### macOS Terminal

```bash
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install --upgrade pip
python3 -m pip install -e .
biodrug
```

Run the command-line interface instead:

```bash
biodrug-cli
```

When running directly from the source folder without installing the package, use `python run_gui.py` or `python3 run_gui.py`; use `python run.py` or `python3 run.py` for the command-line interface.

## Tests and package build

```bash
python -m unittest discover -s tests -v
python -m compileall -q biodrug
python -m pip install --upgrade build twine
python -m build
python -m twine check dist/*
```

The distribution version is `1.2.1`. A published PyPI version cannot be replaced in place, so this corrected release uses a new version number.

## Experimental machine-learning and deep-learning research core

Version 1.1.0 includes optional evidence-text classification pipelines. Install the ML baseline with `python -m pip install -e ".[ml]"` or the PyTorch neural baseline with `python -m pip install -e ".[dl]"`. Training requires a reviewed CSV with `text,label` columns and preferably a source-aware `group` column. Use `biodrug-train reviewed_evidence.csv --engine ml --output models` or `biodrug-train reviewed_evidence.csv --engine dl --output models`. The pipeline reports held-out metrics and refuses basic group leakage. These classifiers learn labels assigned to evidence text; they do not predict whether a drug is safe or effective for a person. No trained model is included because no verified labeled dataset ships with the package. See `docs/RELEASE_1.1.0.md` and `docs/ML_AUDIT_1.1.0.md`.

## Evidence quality audit

Version 1.2.0 adds `biodrug-audit-evidence`, a structural audit for local evidence JSON. It checks required provenance fields, URL format, structured gene/drug presence, possible duplicate keys, and records explicitly marked as demonstrations. Run `biodrug-audit-evidence biodrug/resources/evidence.json --output reports/evidence_audit.json`. This is a metadata/structure audit only: it does not verify that sources are authentic, recommendations are current, the scientific interpretation is correct, or the data license permits reuse. Demonstration records are deliberately flagged and must not be treated as curated clinical evidence.

The ML and deep-learning training scripts now use group-separated holdout splitting and require every label to appear in both splits. This reduces one common leakage risk; it does not guarantee independent external validation or clinical performance. If there are too few independent groups per class, training stops rather than presenting a misleading score.

## Included workflows

- Desktop GUI using Python's Tkinter standard-library interface.
- JSON profile loading and basic VCF field parsing.
- Local profile snapshots and local text/JSON reports.
- Local evidence retrieval from a bundled demonstration JSON file and an optional SQLite evidence database.
- Exact normalized matching against structured drug fields; title matching is only a fallback when a record has no structured drug value.
- Explicit comparison of gene names already present in the supplied profile with gene names found in matching evidence records.
- Streaming import of an official ClinVar variant-summary text file into a separate SQLite catalog, with a configurable row limit and duplicate-resistant imports.
- Local variant catalog search.

## Data and interpretation boundaries

The bundled evidence file contains only three demonstration records. These records are for software testing and interface demonstration; they are not a curated or complete clinical knowledge base. The application does not automatically download authoritative data or silently train a model.

The ClinVar importer can import up to 1,000,000 rows per run by default. The archive does not include a million-row ClinVar database. Download the official `variant_summary.txt.gz` file from https://www.ncbi.nlm.nih.gov/clinvar/docs/downloads/ and import it through Dataset Manager. A ClinVar catalog is not a labeled medication-response dataset and does not train or validate a drug-response model.

VCF parsing reads basic columns and sample genotype text when present. It does not establish genome build, normalize variants, annotate variants to genes, infer star alleles or metabolizer phenotype, or interpret clinical significance for an individual. A gene-name overlap is a retrieval clue only. Text similarity against a user-entered allergy is not an allergy checker; no text match does not mean there is no allergy risk.

## Privacy and safe use

This software is a research prototype, not a certified medical device or clinically validated decision-support system. It cannot establish whether a medicine is safe, effective, appropriate, or correctly dosed for a person. Do not start, stop, or change medication based on its output. Confirm decisions with a qualified clinician or pharmacist and current authoritative guidance.

Genetic and medication data are sensitive. Use only data you are authorized to process, prefer pseudonyms, protect local backups, and remove personal details before sharing profiles, reports, or screenshots. Source checkouts store reports and profile snapshots in the project folder. Installed usage stores user-created data under `~/.biodrug-intelligence`.

## What this project does not claim

- No trained machine-learning model for clinical drug-response prediction is included.
- No clinical accuracy percentage is claimed.
- No automatic dose, medication alternative, diagnosis, or treatment recommendation is generated.
- Successful software tests verify the tested code paths, not clinical validity or medical safety.
- The GUI's DNA illustration is decorative and does not represent a user's actual genome.


## Curating source exports and independent evaluation

Version 1.2.1 adds `biodrug-curate-evidence` to normalize a locally downloaded official-source JSON/JSONL/CSV export. It writes a normalized evidence file and a SHA-256 manifest. Demonstration records are excluded by default; records remain marked `needs_human_review` and `clinical_use: false`. This is not an automated proof of source authenticity, clinical correctness, guideline currency, or licensing.

Example:

```bash
python -m biodrug.curate official_export.json --output data/curated/evidence_curated.json
```

It also adds `biodrug-evaluate-independent` for a reference-vs-prediction CSV. Required columns: `record_id,endpoint,reference_label,model_prediction,group_id,source`. Example:

```bash
python -m biodrug.evaluation evaluation_predictions.csv --output reports/independent_evaluation.json
```

The evaluation tool reports data coverage and exact-match rate only. It does not establish clinical validity and must not be run on synthetic labels and presented as clinical performance. No clinical patient dataset or validated clinical predictor is bundled.
