Skip to content

Knowledge Graph Integration

Two Modes

00panel operates in two modes depending on whether the graphrag_api (Neptune KG) is available:

graph LR
    subgraph Quick["Quick Mode (local)"]
        R[Reactome TSVs] --> E1[Single-hop<br/>pathway co-membership]
        H[HPA flat files] --> E1
        C[Competitor TSVs] --> E1
    end

    subgraph Deep["Deep Mode (KG)"]
        N[Neptune Graph<br/>4M+ edges] --> E2[Multi-hop traversal<br/>2-3 hops]
        E2 --> Q[Natural language queries<br/>via graphrag_api]
    end

    E1 -->|"~50 candidates<br/>instant"| SCORE[Scoring Pipeline]
    E2 -->|"1000+ candidates<br/>5-30s"| SCORE

Quick Mode (current default)

Capability Source Limitation
Pathway expansion Reactome UniProt2Reactome TSVs Single-hop only — finds direct pathway co-members
Blood detectability HPA secretome download Binary yes/no, no concentration data
Competitor coverage bioingest bulk TSVs Static snapshot, no cross-referencing
Demand signals NIH, OpenAlex, CT.gov, GWAS Live APIs, protein-level only
Evidence Open Targets Genetics pQTL Per-protein, no multi-target reasoning

Good for: Quick prototyping, initial scoring, demos, offline use.

Deep Mode (KG-powered)

Capability Source Advantage over Quick
Multi-hop expansion Neptune STRING + Reactome + CORUM Discovers proteins 2-3 hops away through interaction/complex/pathway chains
Cross-source reasoning 40+ integrated sources "Proteins linked to cardiovascular disease AND in TNF interaction network AND druggable"
Evidence aggregation All Neptune edges with confidence scores Weighted multi-source evidence, not single-API lookups
Disease module extraction Community detection on Neptune subgraphs Finds disease-specific protein modules automatically
Competitive intelligence Graph queries across competitor + disease + pathway "Gaps that are also in high-demand disease areas"

Good for: Production panel proposals, competitive positioning, publication-grade rationale.

Why the KG is superior

Quick mode can answer: "What other proteins are in the same Reactome pathway as TNF?"

The KG can answer:

  • "Find proteins that interact with TNF targets AND are implicated in cardiovascular disease AND are blood-detectable AND not in any competitor panel"
  • "Which proteins have the most genetic evidence (pQTL + GWAS) linking them to Alzheimer's but are under-published (<50 papers/year)?"
  • "Given this 10-protein inflammation seed, what disease modules emerge from the interaction network within 2 hops?"

These are multi-constraint, multi-hop queries that require traversing edges across source types — exactly what a graph database does that flat files cannot.

graph TD
    TNF["TNF (seed)"] -->|interacts_with| TRADD
    TNF -->|interacts_with| TRAF2
    TRADD -->|activates| RIPK1
    RIPK1 -->|implicated_in| CVD["Cardiovascular Disease"]
    CVD -->|associated_protein| GDF15
    GDF15 -->|measured_by| OLINK["Olink YES"]
    RIPK1 -->|not_measured_by| OLINK2["Olink ✗"]
    RIPK1 -->|blood_detectable| YES["HPA: Yes"]

    style RIPK1 fill:#ff9,stroke:#333
    style GDF15 fill:#9f9,stroke:#333

In this example, RIPK1 is discovered as a candidate through: TNF → interacts → TRADD → activates → RIPK1 → implicated in CVD. Quick mode would miss this because RIPK1 isn't in the same Reactome pathway as TNF.

Integration Status

Component Status What's needed
panel/kg.py Implemented Mode selection, expand_deep, evidence_deep
panel/evidence.py Implemented Falls back to pQTL when KG offline
panel/evidence_pqtl.py Implemented Open Targets Genetics colocalisation
graphrag_api /query endpoint 🔲 Pending Deploy graphrag_api with Neptune access
graphrag_api /proteins/{id} 🔲 Pending Protein detail endpoint
graphrag_api /proteins/{id}/diseases 🔲 Pending Disease association endpoint
Neptune data (4M+ edges) 🔲 Pending Complete bioingest structured loader deployment

What happens when graphrag_api goes live

Once graphrag_api is running and Neptune is populated:

  1. TUI auto-detects: The mode selector will show ● Knowledge Graph: CONNECTED
  2. Deep mode unlocks: Users can select Deep for multi-hop expansion
  3. Evidence scores activate: evidence_score column goes from 0.5 placeholder to real pQTL + KG aggregation
  4. Enrich gets rich: Disease/pathway fields populate from graph traversal instead of showing "-"
  5. Expansion improves: Instead of ~50 candidates from Reactome, Deep mode can evaluate 1000+ from interaction network

No code changes required in 00panel — it's already wired to call the API. Just deploy graphrag_api.

API Contract

00panel expects these endpoints from graphrag_api:

GET  /health                          → 200 OK
POST /query                           → {results: [{gene_name, ...}]}
GET  /proteins/{uniprot_id}           → {gene_name, name, ...}
GET  /proteins/{uniprot_id}/diseases  → [{disease, score, sources}]
GET  /proteins/{uniprot_id}/pathways  → [{pathway_id, pathway_name}]

The /query endpoint accepts natural language and returns structured protein results — this is where the LLM agent in graphrag_api generates Cypher and traverses Neptune.