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

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:

biodrug-cli

macOS Terminal

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:

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

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:

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:

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.