Metadata-Version: 2.4
Name: bbbnuke
Version: 0.12.1
Summary: BBB-Nuke: Blood-brain barrier penetration screening pipeline
Author-email: Temi Sobodu <temisobodu@gmail.com>
License: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Chemistry
Requires-Python: >=3.9
Requires-Dist: huggingface-hub>=0.20
Requires-Dist: joblib>=1.2
Requires-Dist: numpy<2,>=1.24
Requires-Dist: openpyxl>=3.0
Requires-Dist: pandas>=2.0
Requires-Dist: pydantic>=2.0
Requires-Dist: rdkit
Requires-Dist: scikit-learn>=1.0
Requires-Dist: torch-geometric>=2.0
Requires-Dist: torch-scatter
Requires-Dist: torch-sparse
Requires-Dist: torch>=2.0
Provides-Extra: api
Requires-Dist: aiosqlite>=0.20; extra == 'api'
Requires-Dist: alembic>=1.13; extra == 'api'
Requires-Dist: arq>=0.26; extra == 'api'
Requires-Dist: asyncpg>=0.29; extra == 'api'
Requires-Dist: fastapi>=0.110; extra == 'api'
Requires-Dist: httpx>=0.25; extra == 'api'
Requires-Dist: redis>=5.0; extra == 'api'
Requires-Dist: sqlalchemy[asyncio]>=2.0; extra == 'api'
Requires-Dist: uvicorn[standard]>=0.25; extra == 'api'
Provides-Extra: api-test
Requires-Dist: aiosqlite>=0.20; extra == 'api-test'
Requires-Dist: arq>=0.26; extra == 'api-test'
Requires-Dist: fastapi>=0.110; extra == 'api-test'
Requires-Dist: httpx>=0.25; extra == 'api-test'
Requires-Dist: pytest-asyncio>=0.23; extra == 'api-test'
Requires-Dist: pytest>=7.0; extra == 'api-test'
Requires-Dist: redis>=5.0; extra == 'api-test'
Requires-Dist: sqlalchemy[asyncio]>=2.0; extra == 'api-test'
Requires-Dist: uvicorn[standard]>=0.25; extra == 'api-test'
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: mcp>=1.26; extra == 'mcp'
Provides-Extra: pdf
Requires-Dist: weasyprint>=68; extra == 'pdf'
Provides-Extra: tmap
Requires-Dist: faerun>=0.4; extra == 'tmap'
Requires-Dist: mhfp>=1.0; extra == 'tmap'
Requires-Dist: umap-learn>=0.5; extra == 'tmap'
Provides-Extra: viz
Requires-Dist: plotly>=5.0; extra == 'viz'
Description-Content-Type: text/markdown

# BBB-Nuke

<img width="960" height="540" alt="image" src="https://github.com/user-attachments/assets/42bfaee2-aa67-4675-9423-803386c1dc6c" />

**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](https://attentionlab.ai)

---

## 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

```bash
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

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

### Screen a batch

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

Input CSV format:

```csv
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

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

### Open the tutorial

```bash
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:**

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

**Claude Desktop** — add to `claude_desktop_config.json`:

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

### Local (unlimited, no quota)

```bash
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

```bash
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.

```bash
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

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

---

## Python API

```python
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:

```bash
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](https://attentionlab.ai)
