Nexus Bio Engine

A production-grade, 10-agent autonomous system for rare disease drug repurposing. Synthesizes biomedical signals into mechanism-of-action rationales and FDA 505(b)(2)-aligned dossiers.

Status: 230+ tests passing. GitHub-ready milestone complete. Designed for NVIDIA, Allen Institute, Fred Hutch, and Talus Bio reviewers.

What It Does

1. Signal Ingestion (Seth): Mines PubMed and Open Targets for disease-target associations
2. Structural Validation (Chyna): AlphaFold confidence scoring and binding pocket prediction
3. Dynamic Refinement (Kingsley): Per-tool circuit breakers with trust-weighted evidence routing
4. Pathway Analysis (Erika): STRING DB network mapping and disease pathway identification
5. MOA Synthesis (Ellie): Claude-based mechanism-of-action narratives with ephemeral caching
6. Regulatory Scaffolding (Azia): FDA 505(b)(2)-compliant dossier compilation
7. Consensus Validation (Vasily): Internal coherence checking (≥0.65 confidence)
8. Export (Semien): JSON/Markdown/CSV output with filtering and pagination
9. Quality Audit (Marcus): Four-gate regulatory compliance validation (0.75 confidence floor)
10. Orchestration (Cody): Hierarchical routing and concurrent batch processing

Output: Ranked drug-target repurposing candidates with MOA rationales, confidence scores, and regulatory alignment notes.

Architecture

Core Patterns:

• Stateless phantom execution with Redis state batching
• Asynchronous non-blocking orchestration (asyncio.gather)
• Per-tool circuit breakers with EMA-based trust scoring
• Anthropic ephemeral prompt caching (90% input cost discount on Ellie)
• Hierarchical manager-worker coordination

Agent Hierarchy:

CodySperber (Manager 1: Strategy & Routing)
  ├── Seth (Signal Ingestion)
  ├── Chyna (Structural Validation)
  ├── Kingsley (Dynamic Tool-Calling)
  ├── Erika (Pathway Mapping)
  ├── Ellie (MOA Synthesis)
  ├── Azia (Dossier Compilation)
  └── Vasily (Consensus Checking)
      └── Semien (Export)
          └── MarcusFabritius (Manager 2: Regulatory Gate)

Key Features

• AlphaFold Integration: v1/v2/v3 versioning with pLDDT confidence tiering and binding pocket analysis
• Multi-Source Evidence: ClinVar, PubMed, Open Targets, STRING DB with fault-tolerant routing
• Regulatory Alignment: 505(b)(2) dossier scaffolding with four-gate compliance validation
• Cost Optimization: Ephemeral prompt caching, circuit breaker spend guards, Redis caching
• Confidence Transparency: Class-constant thresholds (Vasily: 0.65, Marcus: 0.75) for reviewer auditability
• Concurrent Batching: Process multiple diseases in parallel (default: 5 concurrent requests)

Quick Start

# Clone and install
git clone https://github.com/onepunchone/Nexus-Bio-Engine.git
cd Nexus-Bio-Engine
pip install -r requirements.txt

# Run example pipeline
python run_engine.py

# Run test suite
pytest tests/ -v

Example Output

[
  {
    "candidate_name": "IL6_Target_001",
    "disease_target": "neuro-inflammatory",
    "confidence_score": 0.78,
    "consensus_ready": true,
    "regulatory_ready": true,
    "sections": 3
  }
]

Design Principles

1. Systems Efficiency: Zero-memory leaks, high-throughput batching, non-blocking async
2. Scientific Rigor: Evidence-based thresholds, transparent confidence floors, auditability
3. Fault Tolerance: Per-tool circuit breakers, dynamic trust scoring, exponential backoff
4. Cost Control: Prompt caching, Redis backing, spend-velocity guards
5. Regulatory Awareness: 505(b)(2) scaffolding, four-gate compliance validation

Documentation

• ARCHITECTURE.md: System design, agent specifications, data flow
• run_engine.py: Example end-to-end pipeline execution
• tests/test_agents.py: 230+ test cases covering all agents and integration scenarios

Testing

# Run all tests (230+ cases)
pytest tests/ -v

# Run specific agent tests
pytest tests/test_agents.py::TestSeith -v
pytest tests/test_agents.py::TestMarcus -v

# Run with coverage
pytest tests/ --cov=nexus

Architecture Decisions

Structure-First Foundation

AlphaFold integration (Chyna) was prioritized over signal ingestion (Seth) because protein structure is the foundational validation layer for biological credibility.

Separation of Validation Concerns

• Vasily (0.65 confidence, 50+ char): Internal pipeline coherence only
• Marcus (0.75 confidence, 120+ char): Regulatory compliance only
• Semien (50+ char floor): Output formatting only

Marcus is the SOLE component authorized to set regulatory_ready.

Transparent Confidence Thresholds

All scoring constants are visible in code as class attributes, enabling reviewer auditability without hidden logic.

Per-Tool Trust Scoring

Kingsley implements exponential moving average (EMA) updates on each external tool call. Failing tools below threshold are skipped to enforce spend-velocity limits without cascading failures.

Deployment

Environment Setup

# .env (do NOT commit API keys)
NCBI_API_KEY=your_key_here
OPENTARGETS_API_KEY=your_key_here
REDIS_URL=redis://localhost:6379
ANTHROPIC_API_KEY=your_key_here

Production Considerations

• Redis required for state batching (TTL cache backing)
• API credential injection via environment variables (NO hardcoded keys)
• Exponential backoff on network failures
• Circuit breaker thresholds tunable per environment
• Logging to stdout with structured JSON

Limitations & Future Work

Current Implementation

• Outputs are hypothesis-based MOA narratives (generated via Claude)
• Confidence scores measure internal pipeline coherence, not biological ground truth
• Designed as explanation scaffold for downstream empirical validation

Roadmap: Phase V - Empirical Validation Layer

Replace Ellie's speculative synthesis with quantified evidence:

• Published binding affinity data (Ki, Kd, IC50)
• pLDDT structural confidence thresholds
• Statistical significance gates (p < 0.05)
• Smaller but scientifically defensible output (8-25 vs 30-60 candidates)

Citation & Attribution

This engine was designed as a portfolio project for the AI × Biology initiative, targeting reviewers at NVIDIA, Allen Institute, Fred Hutch, and Talus Bio.

GitHub: nexus-bio-engine

License

Currently unlicensed. MIT license pending approval.

Contact

For questions on architecture, agent design, or deployment, see ARCHITECTURE.md.