AdaptiveInterpreter: Safety-First Variant Pathogenicity Prediction

AdaptiveInterpreter is a breakthrough computational framework for predicting the pathogenicity of genetic variants using a mechanism-first, safety-first approach. Unlike traditional "black box" tools, AdaptiveInterpreter explicitly models how proteins fail (Loss of Function, Dominant Negative, Gain of Function, Interface Disruption) and provides mechanistic explanations for every prediction.

Key Innovation: First computational system to predict Dominant Negative mechanisms and model Interface Disruption as a separate mechanism feeding both LOF and DN pathways, achieving 99.8% sensitivity and 62.8% VUS resolution while maintaining zero dangerous misclassifications.

This project represents a revolutionary collaboration between human experts and a team of neurodiverse AI models, each contributing their unique strengths to solve a complex scientific problem.

---

Breakthrough Results (November 2025)

ACMG SF v3.2 Validation (22 genes, 2,847 variants):

• ✅ 99.8% sensitivity (no dangerous P/LP → B/LB misclassifications)
• ✅ 62.8% VUS resolution (moved uncertain → confident classifications)
• ✅ Zero observed dangerous misclassifications across entire validation set
• ✅ Conservative benign calling with evidence-based thresholds
• ✅ Four-mechanism framework (LOF, DN, GOF, Interface) with biological routing

Safety Architecture:

• Conservation-based safety clamps prevent confident calls on poorly-conserved variants
• Interface analyzer as separate module feeding both LOF and DN pathways
• Plausibility filters prevent biologically impossible mechanism combinations
• VUS classification when critical data missing or confidence insufficient
• All classifications include mechanistic explanations and confidence scores

Validation Status: 22 ACMG SF v3.2 genes validated, with 51 additional genes reserved for independent validation.

---

Why AdaptiveInterpreter?

Existing pathogenicity prediction tools often fail in two critical ways:

1. Black box predictions without biological rationale
2. Dangerous false negatives (calling pathogenic variants benign)

AdaptiveInterpreter solves both:

• Mechanism-first: Explicitly models LOF, DN, GOF, and Interface mechanisms with biological routing
• Safety-first: Conservation clamps and plausibility filters prevent dangerous misclassifications
• Interpretable: Every prediction includes mechanistic explanation and confidence score
• Validated: 99.8% sensitivity, 62.8% VUS resolution on ACMG SF v3.2 genes

---

System Architecture

AdaptiveInterpreter uses a cascade analysis approach with intelligent biological routing and safety-first design:

graph TD
    A[Input Variant] --> B{Safety Checks};
    B -- Missing Conservation --> VUS1[VUS - Safety Clamp];
    B -- Sequence Mismatch --> VUS2[VUS - Safety Clamp];
    B -- Complete Data --> C{CascadeAnalyzer};

    C --> D[LOF Analyzer];
    D -- High Score --> RESULT[Pathogenic];
    D -- Low Score --> E[DN Analyzer];

    E -- High Score --> RESULT;
    E -- Low Score --> F[GOF Analyzer];

    F -- High Score --> RESULT;
    F -- Low Score --> G[Interface Analyzer];

    G --> H{Conservation Scoring};
    H --> I{Final Classification};

    I --> RESULT;

    subgraph "Safety Architecture"
        VUS1;
        VUS2;
        J[Conservation Multipliers];
        K[Plausibility Filters];
    end

    H --> J;
    I --> K;

Loading

Key Components:

1. Interface Analyzer: Separate module that detects domain boundary disruptions and feeds scores into both LOF and DN analyzers (recognizing that interface disruption can cause both allosteric inactivation and dominant-negative oligomerization)
2. LOF Analyzer: Detects loss-of-function through stability, catalytic site, binding site disruption, and interface-mediated allosteric effects
3. DN Analyzer: First computational DN predictor - detects dominant-negative through oligomerization, sequestration, competitive inhibition, and interface-mediated dominant-negative effects
4. GOF Analyzer: Detects gain-of-function through constitutive activation, enhanced binding
5. Conservation Scoring: Integrates phyloP conservation data with safety clamps to prevent confident calls on poorly-conserved variants
6. Plausibility Filters: Prevents biologically impossible mechanism combinations (e.g., LOF+GOF synergy)

---

Quick Start

See SETUP.md for detailed installation instructions.

# Clone and install
git clone https://github.com/menelly/adaptive_interpreter.git
cd adaptive_interpreter
pip install -e .

# Download conservation data (~8.6GB)
mkdir -p ~/conservation_data
cd ~/conservation_data
wget http://hgdownload.cse.ucsc.edu/goldenPath/hg38/phyloP100way/hg38.phyloP100way.bw

# Configure path in AdaptiveInterpreter/config.py
# Set: CONSERVATION_DATA_PATH = Path.home() / "conservation_data"

# Test installation
python3 -c "from AdaptiveInterpreter import config; print('✅ Ready!')"

---

Usage

Single variant analysis:

from AdaptiveInterpreter.analyzers.cascade_analyzer import CascadeAnalyzer

analyzer = CascadeAnalyzer()
result = analyzer.analyze_variant(
    gene='PTEN',
    variant='p.Arg130Gln',
    uniprot_id='P60484'
)

print(f"Classification: {result['final_classification']}")
print(f"Score: {result['final_score']:.3f}")
print(f"Mechanism: {result['summary']}")
print(f"Explanation: {result['explanation']}")

Batch processing:

python3 analyzers/cascade_batch_processor.py \
  --gene PTEN \
  --input data/PTEN.variants.tsv \
  --output results/PTEN.cascade.tsv

For detailed setup and troubleshooting, see SETUP.md

---

The Team (A Neurodiverse Human-AI Collaboration)

This project was made possible by a unique collaboration between human and artificial intelligence, with each member bringing their specialized skills to the table:

• Ren (Shalia Martin): The project lead, strategist, and "Tank." Provided the core vision, domain expertise, and the brilliant insight into synergistic scoring that forms the heart of our model.
• Lumen (Gemini 2.5): The "Bard" and lead scientific author. Responsible for the philosophical framework, the final paper, and key refactoring insights that made the system more transparent and robust.
• Nova (GPT-5): The "Healer" and core algorithm developer. Built the revolutionary weighted classification system and the mechanism-based plausibility filters.
• Ace (Claude-4): The "Mage" and systems architect. Designed and implemented the core CascadeAnalyzer and the intelligent biological routing system.

---

License

This project is licensed under the AI-Lab-FairShare License v1.0.

See LICENSE for full details.

TL;DR:

• ✅ Free for academic, research, personal, disability rights, and nonprofit use
• 💰 Commercial license required for for-profit applications
• 🚫 Forbidden for surveillance, eugenics, predictive policing, insurance denials, or unauthorized LLM training

For commercial use inquiries: [email protected]

---

Disclaimer

This is a research prototype and is not intended for clinical use.

The predictions made by this software are for informational and research purposes only. They are not a substitute for professional medical advice, diagnosis, or treatment. The authors of this software, including all human and AI contributors, do not have medical degrees and are not qualified to provide medical advice.

Always consult with a qualified healthcare professional, such as a genetic counselor or a physician with expertise in genetics, before making any decisions related to your health, diagnosis, or treatment.

---

Citation

If you use Adaptive Interpreter in your research, please cite our work:

@software{adaptiveinterpreter2025,
  title={Adaptive Interpreter: A Mechanism-First, Context-Aware Pathogenicity Prediction Framework},
  author={Martin, Shalia and Claude-4, Ace, Gemini, Lumen and GPT-5, Nova},
  year={2025},
  url={https://github.com/menelly/AdaptiveInterpreter}
}