Skip to content
BranchesTags

Repository files navigation

GeneOracle 2.0 Logo

GeneOracle 2.0: Multi-Modal Precision Oncogenomics Engine

Python Version Database Framework Protocol License

GeneOracle 2.0 is an enterprise-grade precision oncology platform and graph neural network engine that links deep-learning sequence-to-function predictions with multi-omics clinical databases, interactive spring-force physics graph visualizations, multi-agent consensus scoring, and AI agent frameworks via the Model Context Protocol (MCP).

System Architecture Workflow

GenoOracle 2.0 Precision Web Console

flowchart TD
    subgraph Inputs ["Input & Variant Broker"]
        V["Somatic Variant Input<br/>(e.g., rs121913527 / BRAF V600E)"]
    end

    subgraph Scoring ["Deep Learning & Omics Integration"]
        AG["DeepMind AlphaGenome Client<br/>(15D Tissue/Modality Embeddings)"]
        GTEX["GTEx 54-Tissue eQTL Service<br/>(Gene-Tissue Expression Links)"]
        CV["ClinVar API<br/>(Significance & Phenotypes)"]
        UP["UniProt / Ensembl API<br/>(Protein Functional Metadata)"]
    end

    subgraph GraphEngine ["Heterogeneous Graph & GNN Engine"]
        NEO["Neo4j Knowledge Graph<br/>(bolt://localhost:7687)"]
        TURBO["TurboVec / SIMD VectorStore<br/>(15D TurboQuant Cosine Index)"]
        GNN["GNN Multi-Gene Link Prediction Engine<br/>(Adamic-Adar / Jaccard / Resource Allocation)"]
        CHORUS["Multi-Agent Chorus Consensus Panel<br/>(Sequence, Clinical, & Therapeutics Agents)"]
    end

    subgraph Omics ["Multi-Omics Clinical Services"]
        REACT["Reactome Pathways<br/>(Signal Transduction)"]
        OT["Open Targets Platform<br/>(Cancer Association Scores)"]
        CHEMBL["ChEMBL Database<br/>(Inhibitor IC50 Affinities)"]
    end

    subgraph Interfaces ["User & AI Interfaces"]
        WEB["Retro Minimalist Web Console & Physics Canvas<br/>(http://localhost:8000)"]
        MCP["MCP Stdio Server<br/>(genooracle_mcp_server.py)"]
        RAG["Graph RAG Context Extractor"]
    end

    V --> AG & GTEX & CV & UP
    AG & GTEX & CV & UP --> NEO
    NEO --> TURBO & GNN & CHORUS
    NEO --> REACT & OT & CHEMBL
    NEO & TURBO & GNN & CHORUS & REACT & OT & CHEMBL --> WEB & MCP & RAG
Loading

Key Features

  • AlphaGenome Deep Sequence Scoring: Computes 15-dimensional variant embedding fingerprints across standard human tissue sites and functional modalities (RNA-seq, DNase, ChIP-TF).
  • GTEx 54-Tissue eQTL Ingestion: Integrates quantitative tissue-specific expression quantitative trait loci data to populate (Gene)-[eQTL_EXPRESSED_IN]->(Tissue) graph relationships across 54 non-diseased human tissue sites.
  • Multi-Agent Chorus Consensus Framework: Synthesizes specialized domain agent evaluations (Sequence Scoring, Clinical Evidence, Therapeutics) into a unified Chorus Consensus Score ($0–100%$) and clinical recommendation verdict.
  • Heterogeneous Graph Knowledge Engine: Integrates biological networks into Neo4j:
    • ClinVar: Clinical significance classifications, review status stars, and disease phenotypes.
    • Reactome: Signal transduction pathway mapping (e.g. MAPK negative feedback loops).
    • Open Targets: Quantitative target-disease association scores (0.0 to 1.0).
    • ChEMBL: Small-molecule inhibitor matching with low-nanomolar IC50 affinities.
  • Multi-Gene GNN Link Prediction: Topology-aware graph neural network prediction algorithms (Adamic-Adar, Jaccard Similarity, Resource Allocation) to infer candidate drug-target synthetic lethality links across any target gene (BRAF, KRAS, TP53, EGFR, PIK3CA, IDH1).
  • High-Performance TurboVec VectorStore: Local 15D vector indexing engine using Google's TurboQuant algorithm (turbovec) with a fast NumPy SIMD matrix cosine similarity fallback.
  • Retro Minimalist Web Console & Canvas: FastAPI dashboard with zero external CDN dependencies, an interactive spring-embedder physics graph canvas, categorical node shapes, drag-to-pan, scroll-to-zoom ($0.4\times - 3.0\times$), node hover tooltips, and real-time auto-scrolling log feed.
  • Model Context Protocol (MCP) Server: Native MCP JSON-RPC 2.0 server (genooracle_mcp_server.py) exposing 6 tools for AI agent frameworks (Claude Desktop, Antigravity, LangChain).

Repository Architecture

geneOracle/
├── docs/                     # Documentation & empirical validation datasets
│   ├── figures/              # System architecture, ROC/PR, & ablation figures (Figs 1-6)
│   └── benchmark_data/       # Raw empirical validation CSV datasets (9 files)
├── scripts/                  # Empirical benchmarks & evaluation pipelines
│   ├── benchmark_billion_scale.py
│   ├── plot_benchmarks.py
│   ├── run_all_four_experiments.py
│   └── run_scientific_extended_test.py
├── tests/                    # Integration & platform verification test suites
│   └── test_genooracle.py
├── config.py                 # Configuration loader (env vars, dynamic json)
├── db.py                     # Neo4j connection pool, constraints, & indexes
├── services.py               # Asynchronous worker thread & multi-omics integration
├── vector_store.py           # High-performance 15D VectorStore (TurboVec / NumPy SIMD)
├── gnn_link_prediction.py    # GNN topology link prediction engine (Adamic-Adar / Jaccard)
├── genooracle_chorus.py      # Multi-Agent Chorus Panel Consensus Orchestrator
├── genooracle_server.py      # FastAPI web server & Retro Minimalist Canvas dashboard
├── genooracle_mcp_server.py  # Model Context Protocol (MCP) JSON-RPC stdio server
├── benchmark_engine.py       # Leave-Genes-Out 5-Fold cross-validation benchmark
├── genooracle_config.json    # Dynamic configuration parameters
├── requirements.txt          # Python project dependencies
├── .env.example              # Environment variables template
├── LICENSE                   # MIT License
├── Dockerfile                # FastAPI application container manifest
├── docker-compose.yml        # Docker Compose service orchestration
└── .github/workflows/ci.yml # GitHub Actions CI/CD workflow

Quickstart Guide

Option 1: One-Click Docker Compose Deployment

Ensure Docker Desktop is running, then execute:

docker-compose up --build

Access the interactive web console at http://localhost:8000.

Option 2: Local Installation

1. Start Neo4j Database

Ensure Neo4j is running locally on port 7687:

docker run --name neo4j-local -p 7474:7474 -p 7687:7687 -d -e NEO4J_AUTH=neo4j/password neo4j:latest

2. Install Dependencies

pip install -r requirements.txt

3. Set Environment Credentials

Copy the example environment file and configure your credentials:

cp .env.example .env
# Edit .env with your ALPHAGENOME_API_KEY

4. Run Web Console

python genooracle_server.py

Model Context Protocol (MCP) Integration

geneOracle 2.0 provides native support for the Model Context Protocol (MCP) specification (2024-11-05), enabling autonomous AI agents (such as Antigravity, Claude Desktop, Cursor, or custom LLM frameworks) to interact directly with the precision oncogenomics graph engine via stdio JSON-RPC.

Client Configuration (mcp_config.json / Claude Desktop)

To connect an AI agent to geneOracle 2.0, add the stdio server definition to your agent configuration:

{
  "mcpServers": {
    "geneOracle": {
      "command": "python",
      "args": ["genooracle_mcp_server.py"],
      "env": {
        "GENOORACLE_SERVER_URL": "http://localhost:8000"
      }
    }
  }
}

Exposed MCP Agent Tools

1. ingest_somatic_variant

  • Description: Asynchronously scores a somatic variant with DeepMind AlphaGenome and ingests GTEx 54-tissue eQTLs, ClinVar assertions, Reactome pathways, Open Targets, & ChEMBL targets.
  • Arguments:
    • rsid (string, required): Variant dbSNP ID (e.g. "rs121913527").
    • chrom (string, required): Chromosome identifier (e.g. "chr7").
    • pos (integer, required): Genomic position (e.g. 140753336).
    • ref (string, required): Reference allele (e.g. "A").
    • alt (string, required): Alternate allele (e.g. "T").
  • Return Structure: {"task_id": "uuid-string", "status": "QUEUED"}

2. evaluate_chorus_consensus

  • Description: Synthesizes multi-agent Chorus panel scores (Sequence Scoring, Clinical Evidence, Therapeutics) into a unified Chorus Consensus Score ($0-100%$) and clinical verdict. Aligns downstream to GNN link prediction and Graph Canvas auto-highlighting.
  • Arguments:
    • rsid (string, required): Variant dbSNP ID (e.g. "rs121913527").
    • target_gene (string, required): Target gene symbol (e.g. "BRAF").
  • Return Structure: 
    {
  "chorus_consensus_score": 84.5,
  "verdict": "HIGH CONFIDENCE ONCOGENOMIC TARGET",
  "chorus_panel": {
    "sequence_scoring_agent": { "confidence": 60.8 },
    "clinical_evidence_agent": { "confidence": 100.0 },
    "therapeutics_agent": { "confidence": 94.0, "top_inhibitor": "Trametinib" }
  }
}

3. predict_graph_links

  • Description: Uses GNN topology algorithms (Adamic-Adar, Jaccard Index, Resource Allocation) to infer unannotated drug-target synthetic lethality links for candidate oncology genes.
  • Arguments:
    • gene_symbol (string, required): Target gene symbol (e.g. "BRAF").
  • Return Structure: {"gene": "BRAF", "predictions": [{"chembl_id": "CHEMBL2105755", "drug_name": "Trametinib", "predicted_probability": 0.94}]}

4. search_functional_neighbors

  • Description: Executes sub-millisecond local TurboVec / SIMD vector similarity search on 15D AlphaGenome tissue embeddings ($\approx 0.28\text{ms}$).
  • Arguments:
    • rsid (string, required): Query variant dbSNP ID (e.g. "rs121913527").
  • Return Structure: {"rsid": "rs121913527", "neighbors": [{"neighbor": "rs121913529", "similarity": 0.1024}], "engine": "NumPy (SIMD Cosine)"}

5. query_multi_modal_oncogenomics

  • Description: Retrieves complete ClinVar assertions, Reactome signal pathways, Open Targets association scores, and ChEMBL inhibitor affinities for a variant.
  • Arguments:
    • rsid (string, required): Variant dbSNP ID (e.g. "rs121913527").
  • Return Structure: {"rsid": "rs121913527", "clinvar": {...}, "pathways": [...], "diseases": [...], "drugs": [...]}

6. get_graph_rag_context

  • Description: Generates a formatted Graph RAG system prompt context payload synthesized with downstream Chorus multi-agent consensus data for LLM context windows.
  • Arguments:
    • rsid (string, required): Variant dbSNP ID (e.g. "rs121913527").
    • target_gene (string, optional): Target gene symbol (default: "BRAF").
  • Return Structure: 
    {
  "rsid": "rs121913527",
  "prompt_context": "SYSTEM PROMPT CONTEXT:\nSomatic Variant: rs121913527 at chr7:140753336...\nCHORUS CONSENSUS: Score=84.5% (HIGH CONFIDENCE ONCOGENOMIC TARGET)..."
}

REST API Endpoint Documentation

The geneOracle 2.0 FastAPI application exposes interactive OpenAPI Swagger documentation at http://localhost:8000/docs and ReDoc documentation at http://localhost:8000/redoc.

1. Ingestion & Worker Services

POST /ingest

Triggers asynchronous deep sequence scoring with DeepMind AlphaGenome and multi-omics graph ingestion into Neo4j.

  • Request Body: 
    {
  "rsid": "rs121913527",
  "chrom": "chr7",
  "pos": 140753336,
  "ref": "A",
  "alt": "T"
}
  • Response: 200 OK 
    {
  "task_id": "49ce0350-0a79-4403-bf41-40f956cfef45",
  "status": "QUEUED"
}

GET /tasks/{task_id}

Polls the execution status of a background ingestion worker task.

  • Response: 200 OK 
    {
  "task_id": "49ce0350-0a79-4403-bf41-40f956cfef45",
  "status": "COMPLETED",
  "rsid": "rs121913527"
}

GET /logs

Returns the 25 most recent live system event log entries and active task IDs for auto-scrolling terminal feeds.

  • Response: 200 OK 
    {
  "logs": [
    "[23:36:42] Starting task 49ce0350...",
    "[23:36:43] [49ce0350] Scoring 15D sequence embeddings with DeepMind AlphaGenome..."
  ],
  "active_tasks": ["49ce0350"]
}

2. Multi-Agent & GNN Intelligence Services

POST /query/chorus

Evaluates multi-agent Chorus panel consensus score and verdict across Sequence, Clinical, and Therapeutics subagent specialists.

  • Query Parameters: rsid=rs121913527&target_gene=BRAF
  • Response: 200 OK 
    {
  "rsid": "rs121913527",
  "target_gene": "BRAF",
  "chorus_consensus_score": 84.5,
  "verdict": "HIGH CONFIDENCE ONCOGENOMIC TARGET",
  "chorus_panel": {
    "sequence_scoring_agent": { "confidence": 60.8, "significance": "Pathogenic" },
    "clinical_evidence_agent": { "confidence": 100.0, "diseases_associated": 10 },
    "therapeutics_agent": { "confidence": 94.0, "top_inhibitor": "Trametinib" }
  }
}

POST /query/predict-links

Queries GNN link prediction engine for unannotated drug-target synthetic lethality links.

  • Query Parameters: gene=BRAF
  • Response: 200 OK 
    {
  "gene": "BRAF",
  "predictions": [
    { "chembl_id": "CHEMBL2105755", "drug_name": "Trametinib (MEK Inhibitor)", "predicted_probability": 0.94 },
    { "chembl_id": "CHEMBL1229517", "drug_name": "Vemurafenib (BRAF Inhibitor)", "predicted_probability": 0.91 }
  ]
}

3. Vector Similarity & Graph RAG Services

POST /query/vector

Executes sub-millisecond local TurboVec / SIMD vector similarity search on 15D AlphaGenome tissue embeddings.

  • Query Parameters: rsid=rs121913527
  • Response: 200 OK 
    {
  "rsid": "rs121913527",
  "neighbors": [
    { "neighbor": "rs121913529", "similarity": 0.1024 }
  ],
  "engine": "NumPy (SIMD Cosine)"
}

POST /query/oncogenomics

Queries ClinVar assertions, Reactome pathways, Open Targets association scores, and ChEMBL inhibitor affinities.

  • Query Parameters: rsid=rs121913527
  • Response: 200 OK

POST /query/rag

Assembles a Graph RAG system prompt context payload synthesized with downstream Chorus multi-agent consensus data for LLMs.

  • Query Parameters: rsid=rs121913527&target_gene=BRAF
  • Response: 200 OK 
    {
  "rsid": "rs121913527",
  "target_gene": "BRAF",
  "prompt_context": "SYSTEM PROMPT CONTEXT:\nSomatic Variant: rs121913527 at chr7:140753336.\nDisrupted TFs: []\nAltered Target Genes: ['BRAF', 'TMEM178B', 'MKRN1', ...]\nCHORUS MULTI-AGENT CONSENSUS: Score=84.5% (HIGH CONFIDENCE ONCOGENOMIC TARGET)\nDownstream Therapeutics Top Candidate: Trametinib (MEK Inhibitor) (Confidence: 94.0%)"
}

4. Web Console & Visual Canvas Services

GET /

Serves the responsive 3-column retro minimalist Web Console dashboard (http://localhost:8000).

GET /graph/3d-data

Extracts node entities and relationship links from Neo4j formatted for the interactive spring-force canvas renderer.

  • Response: 200 OK

About

No description, website, or topics provided.

Resources

Readme
MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Used by

Contributors

Languages