bbbnuke 0.12.1

BBB-Nuke: Blood-brain barrier penetration screening pipeline

BBB-Nuke

Nuke the Barrier. Reach the Brain.

BBB-Nuke is a blood-brain barrier penetration screening pipeline for small molecules. It chains six stages — standardization, physicochemical properties, pKa prediction, CNS-MPO scoring (with cLogD), live efflux transporter screening, and a gradient-boosted classifier — to produce a final P_BBB probability (0–1).

v0.9.4 · By Attention Labs

---

Features

• Gradient-boosted classifier trained on 7,807 compounds (5×10-fold CV: F1 = 0.903)
• Live efflux screening against 9 transporter proteins (MDR1, ABCG2, MRP1–5, MATE1, OAT3) via GNN inference
• CNS-MPO scoring with 6 desirability components including cLogD via Henderson-Hasselbalch
• Efflux veto — compounds with high efflux binding (>0.7) are flagged
• Interactive heatmap — Plotly-based screening overview with hover tooltips
• Compound report cards — per-compound HTML with molecule SVG, radar chart, efflux bars, and properties table
• MCP server — score molecules directly from Claude, Codex, or any MCP-compatible AI assistant
• REST API — FastAPI with batch scoring, job queue, and rate limiting
• Built-in tutorial — run bbnuke tutorial to open the interactive guide

---

Quick Start

Install

pip install bbnuke            # Core CLI + pipeline
pip install "bbnuke[viz]"     # Add heatmap + report card visualizations
pip install "bbnuke[mcp]"     # Add MCP server
pip install "bbnuke[api]"     # Add REST API

Score a single compound

bbnuke score-single --smiles "CC(=O)Oc1ccccc1C(=O)O" --name aspirin

Screen a batch

bbnuke run --input compounds.csv --output results.json

Input CSV format:

compound_id,smiles
serotonin,C1=CC2=C(C=C1O)C(=CN2)CCN
dopamine,NCCc1ccc(O)c(O)c1
caffeine,Cn1c(=O)c2c(ncn2C)n(C)c1=O

Generate visualizations

bbnuke heatmap --input results.json          # Interactive screening heatmap
bbnuke report --input results.json           # Compound report cards

Open the tutorial

bbnuke tutorial

---

Pipeline

SMILES
  │
  ▼
[1] Standardize ─── canonicalize, strip salts, neutralize (RDKit)
  │
  ▼
[2] Properties ──── MW, LogP, TPSA, HBD, HBA, rotatable bonds,
  │                  rings, aromatic rings, heavy atoms, Fsp3
  ▼
[3] pKa ─────────── acid/base pKa prediction (MolGpKa if available)
  │
  ▼
[4] CNS-MPO ─────── 6-component desirability score (0–6):
  │                  MW + LogP + TPSA + HBD + pKa + cLogD
  │                  Compounds scoring < 3.0 are filtered
  ▼
[5] Efflux ──────── GNN inference against 9 efflux transporters
  │                  CPU fine for small batches; GPU for >1000 compounds
  ▼
[6] Classifier ──── Gradient-boosted model (10 RDKit descriptors)
  │                  + efflux veto (binding > 0.7 → P_BBB ≈ 0)
  ▼
P_BBB (0–1)

---

CLI Commands

Command	Description
bbnuke score-single	Score one molecule
bbnuke run	Batch screen from CSV (JSON or CSV output)
bbnuke screen	End-to-end with external pKa + affinity tools
bbnuke heatmap	Generate interactive screening heatmap
bbnuke report	Generate compound report cards (HTML)
bbnuke tutorial	Open the interactive CLI tutorial

---

MCP Server (Claude / Codex)

BBB-Nuke runs as an MCP server, allowing AI assistants to score molecules directly.

Remote (hosted)

Live at https://mcp.attentionlab.ai/mcp — no setup required.

Claude Code:

claude mcp add bbnuke --transport streamable-http https://mcp.attentionlab.ai/mcp

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "bbnuke": {
      "type": "streamable-http",
      "url": "https://mcp.attentionlab.ai/mcp"
    }
  }
}

Local (unlimited, no quota)

pip install "bbnuke[mcp]"
bbnuke-mcp                           # stdio mode
bbnuke-mcp --http --port 8080        # HTTP mode

MCP Tools

Tool	Description
score_compound	Full pipeline scoring with live efflux screening
score_with_affinity	Score with pre-computed affinity data (599 compounds, 65 proteins)
explain_score	Human-readable breakdown of every pipeline stage
get_pipeline_info	Version, hyperparameters, and capabilities

---

REST API

pip install "bbnuke[api]"
uvicorn bbnuke.api.app:app --host 0.0.0.0 --port 8000

Method	Path	Description
POST	/v1/score	Score a single compound
GET	/v1/proteins	List all 65 BBB target proteins
POST	/v1/batch	Submit batch job
GET	/v1/batch/{id}	Poll batch progress
GET	/v1/batch/{id}/results	Download results (JSON or CSV)
GET	/v1/health	Liveness probe
GET	/v1/version	Pipeline version + hyperparameters

---

Visualizations

Heatmap

Bird's-eye view of all compounds across all dimensions. Green→purple color scale, P_BBB inverted so green = high penetration. Hover for raw values.

bbnuke heatmap --input results.json
bbnuke heatmap --input results.csv

Report Cards

Per-compound HTML with:

• 2D molecule structure (RDKit SVG)
• P_BBB badge (green/amber/red)
• CNS-MPO radar chart (6 axes)
• Efflux transporter bar chart (9 proteins, veto line at 0.7)
• Properties table
• Sort by P_BBB or CNS-MPO, search by name or SMILES
• Dark/light theme toggle

bbnuke report --input results.json
bbnuke report --input results.json --compound-id caffeine

---

Python API

from bbnuke.core.schemas import CompoundInput
from bbnuke.pipeline.runner import run_single, run_batch

# Single compound
result = run_single(CompoundInput(compound_id="caffeine", smiles="Cn1c(=O)c2c(ncn2C)n(C)c1=O"))
print(f"P_BBB: {result.heuristic.p_bbb:.4f}")
print(f"CNS-MPO: {result.cns_mpo.score}, cLogD: {result.cns_mpo.clogd}")

# Batch
compounds = [
    CompoundInput(compound_id="serotonin", smiles="C1=CC2=C(C=C1O)C(=CN2)CCN"),
    CompoundInput(compound_id="dopamine", smiles="NCCc1ccc(O)c(O)c1"),
]
results = run_batch(compounds, run_efflux=True)

---

Understanding P_BBB

P_BBB	Interpretation
> 0.8	High likelihood of BBB penetration
0.4 – 0.8	Moderate — may cross under favorable conditions
< 0.4	Low likelihood
≈ 0 (vetoed)	Efflux transporter binding exceeded veto threshold

---

Configuration

Environment Variable	Default	Description
BBNUKE_PSICHIC_DEVICE	cpu	Compute device (cpu or cuda)
BBNUKE_PSICHIC_BATCH_SIZE	16	Batch size for efflux screening

GPU recommended for >1000 compounds:

export BBNUKE_PSICHIC_DEVICE=cuda
bbnuke run --input large_library.csv --output results.json

---

Requirements

• Python >= 3.9
• PyTorch >= 2.0
• RDKit
• numpy < 2

---

License

Proprietary — Attention Labs