Drug Intelligence

Research-grade biomedical AI scaffolding for drug interaction reasoning.

This repository is the public-safe foundation for an end-to-end drug intelligence platform. The project focuses on the engineering and research layers required to turn heterogeneous pharmacology data into reliable AI systems: molecular featurization, graph representations, knowledge graph design, graph neural network benchmarks, evidence retrieval, and safety-aware evaluation.

Status

This public repository has completed the public-safe foundation, chemistry contracts, legacy baseline audit, public-fixture GNN benchmark plumbing, and the first Neo4j-compatible biomedical knowledge graph export layer.

Included now:

• repository structure for a clean Python package
• publication boundary and licensing documentation
• safety statement for research-only use
• CI, tests, issue templates, and roadmap
• sample-data directories without restricted data
• stdlib data schemas for drug, interaction, reference, and molecular feature records
• optional RDKit feature extraction module
• framework-neutral molecular graph conversion
• legacy GNN baseline audit and model card
• config-driven CPU GNN benchmark with five encoder families
• random, drug-disjoint, and scaffold-group split APIs
• synthetic benchmark metrics/report artifacts
• provenance-aware KG schema and validator
• deterministic public-fixture KG exports to JSON and Neo4j Cypher
• sample graph queries for interaction, evidence, and provenance inspection

Not included:

• raw DrugBank data
• scraped DrugBank-derived dumps
• credentials or browser/session material
• large pickle/model/checkpoint artifacts
• vendored DeepChem source
• legacy IDE/project files

Why This Exists

The private legacy workspace contains prototype work across:

• drug data collection and normalization
• RDKit molecular descriptor and graph feature extraction
• Neo4j-style knowledge graph construction
• Torch Geometric graph neural network experiments
• historical DDI mechanism and severity benchmarks

The public project will turn that work into a reproducible portfolio-grade research platform without publishing restricted data or unsafe credentials.

Public-Safe Corpus Policy

This repo publishes code, schemas, documentation, synthetic or license-safe fixtures, and experiment reports. It does not publish restricted third-party datasets.

For full-scale experiments, users must bring their own properly licensed data. See:

• Publication Boundary
• Licensing Notes
• Safety Statement
• Public Fixture Data Card
• Legacy GNN Model Card
• Biomedical Knowledge Graph

Planned Architecture

data ingestion
  -> entity normalization
  -> RDKit molecular featurization
  -> graph and KG construction
  -> graph ML benchmarks
  -> evidence retrieval
  -> safety-aware evaluation

Roadmap

Milestone progress is tracked in docs/roadmap.md:

1. Public-safe foundation
2. Chemistry feature extraction and legacy baseline audit
3. Reproducible GNN benchmark infrastructure
4. Biomedical knowledge graph layer
5. Evidence-grounded retrieval assistant
6. Multimodal interaction modeling
7. Continuous public experiment publishing

Research Safety

This project is not medical software, not clinical decision support, and not a source of medical advice. Any generated or predicted interaction information must be treated as research output requiring expert review and source verification.

Development

Create an isolated environment:

python -m venv .venv
. .venv/bin/activate
python -m pip install -e ".[dev]"

Run local checks:

python -m compileall src tests
python -m pytest -q
python -m ruff check .

Install optional chemistry dependencies when working on RDKit-backed features:

python -m pip install -e ".[dev,chem]"

Install GNN dependencies:

python -m pip install -e ".[dev,chem,gnn]"

Run the public synthetic smoke benchmark:

python scripts/train_gnn_baseline.py \
  --config configs/sample-gin.toml \
  --output-dir artifacts/sample-benchmark

See docs/gnn-benchmark.md for supported encoders, split strategies, output contracts, and limitations.

Export the public fixture knowledge graph:

python scripts/export_kg_sample.py --output-dir reports/sample-kg

The export emits deterministic JSON and Neo4j Cypher artifacts. See docs/knowledge-graph.md for the schema, validation rules, and sample Cypher queries.

Repository Layout

docs/                  public boundary, licensing, safety, roadmap
examples/              legal-safe fixtures only
src/drug_intelligence/ Python package
tests/                 CPU-safe tests
scripts/               future reproducible workflows
notebooks/             future reviewed notebooks
reports/               public fixture benchmark and KG export artifacts

License

Code in this repository is licensed under Apache-2.0. Dataset licenses are separate and must be respected independently. See docs/licensing.md.