Knowledge Graph Builder

Knowledge Graph Builder

Overview

This skill provides a reusable framework for constructing domain-specific knowledge graphs by combining two complementary data pipelines:

• Phase 1 — Structured Ingestion: Import concepts and relations from curated databases, ontologies, and brain atlases (e.g., NeuroNames, MeSH, DisGeNET, Cognitive Atlas, Nilearn atlases).
• Phase 2 — Literature Claim Extraction: Use LLMs to extract structured scientific claims from PubMed paper abstracts, then resolve entities and ingest into the graph.
• Phase 3 — Hypothesis Engine: Traverse the graph to find novel connections, contradictions, and unexplored gaps — turning raw claims into testable research hypotheses.

The output is a directed knowledge graph (NetworkX DiGraph + JSON serialization) where nodes represent domain concepts and claims, and edges represent typed relationships with confidence scores and provenance.

Primary implementation: neurooracle/ in the NeuroClaw project.

Architecture

                    ┌─────────────────────┐
                    │  Knowledge Graph     │
                    │  (NetworkX DiGraph)  │
                    └──────┬──────────────┘
                           │
         ┌─────────────────┼─────────────────┐
         │                 │                 │
┌────────▼────────┐ ┌─────▼──────────┐ ┌────▼─────────────┐
│  Phase 1:       │ │  Phase 2:      │ │  Phase 3:        │
│  Structured     │ │  Literature    │ │  Hypothesis      │
│  Data Ingestion │ │  Claim Extract │ │  Engine          │
└────────┬────────┘ └──────┬─────────┘ └────┬─────────────┘
         │                 │                 │
┌────────▼────────┐ ┌──────▼─────────┐ ┌────▼─────────────┐
│ - NeuroNames    │ │ - PubMed search│ │ - Path finding   │
│ - MeSH          │ │ - LLM extract  │ │ - Bridge discover│
│ - DisGeNET      │ │ - Entity resol │ │ - Contradictions │
│ - Cognitive Atl │ │ - Claim ingest │ │ - Gap detection  │
│ - Nilearn atlas │ │                │ │ - Ranking        │
└─────────────────┘ └────────────────┘ └──────────────────┘

Key Design Decisions (Lessons Learned)

1. Schema Design: Three-Tier Nodes

The graph uses three types of nodes, all stored in the same DiGraph:

Why this matters: Claims are stored as nodes (not just edges) so they can carry full metadata (evidence, p-value, sample size, conditions, population). Simplified edges are also generated for fast traversal.

2. Entity Resolution: 5-Level Matching

When ingesting claims, entity names must be resolved to existing concept IDs. Use a cascading strategy:

1. Exact match on preferred_name
2. Case-insensitive match
3. Alias match (check synonyms)
4. Substring match (entity contained in name or vice versa, prefer shortest name)
5. Create new concept if no match found

Why not just use embeddings? For small-to-medium graphs (<100K concepts), string matching is fast and predictable. SapBERT/FAISS alignment is recommended when UMLS is available and the graph exceeds 100K concepts.

3. LLM Extraction: Keep Prompts Short

LLMs (especially via proxy endpoints) return empty responses when prompts + expected output exceed the token window. Hard-won rules:

• Truncate abstracts to 2000 chars before sending to LLM
• Keep extraction prompts concise — list field names and allowed values, not verbose descriptions
• Use max_tokens=8192 — 4096 is too small for papers with many claims
• Fix [[ double brackets — a common LLM error when outputting JSON arrays
• Temperature=0.1 for extraction consistency

4. Contextualized Triplets (MDKG-style)

Beyond simple (subject, predicate, object), extract:

• Conditions: list of conditions under which the claim holds (e.g., ["female only", "age > 65"])
• Population: study demographics (mean_age, gender distribution, sample size, cohort name)

This enables more nuanced graph queries and downstream hypothesis generation.

5. Checkpoint/Resume for Batch Jobs

Large-scale extraction (10 diseases x 27 years x 20 papers = 5400 papers) takes 10-60 hours. Always implement:

• Save checkpoint after each batch (disease+year)
• Track completed_diseases and completed_years
• Save graph periodically (every 5 years or after each disease)
• CSV export of paper metadata for audit trail

Quick Reference

Agent Reference Rule

When the agent needs knowledge graph implementation code, it should first consult the curated snippets in skills/knowledge-graph-builder/scripts/ instead of writing from scratch.

Reference snippets available:

• scripts/entity_resolution.py → EntityResolver class with 5-level matching
• scripts/graph_query.py → CLI tool for graph queries (stats, search, neighbors, paths, domain)
• scripts/hypothesis_cli_reference.py → Hypothesis engine usage patterns (executable code in neurooracle/hypothesis_cli.py)
• scripts/extraction_prompt_template.txt → LLM extraction prompt template
• scripts/new_data_source_template.py → Template for adding new data sources

Installation

# Core dependencies
pip install networkx requests openai

# Optional: for atlas generation
pip install nilearn nibabel

# Optional: for Biopython Entrez (PubMed)
pip install biopython

# Use the neuroclaw conda environment
conda activate neuroclaw

Phase 1: Structured Data Ingestion

Supported Data Sources

Adding a New Data Source

Create a new file in neurooracle/ingestion/ following this pattern:

"""Ingest data from [SOURCE] into the knowledge graph."""

from ..schema import ConceptNode, Edge, DomainTag
from ..graph_manager import KnowledgeGraph

def ingest_source(kg: KnowledgeGraph, data_path: str) -> dict:
    """Parse source data and add to graph.

    Returns summary dict with counts.
    """
    concepts_added = 0
    edges_added = 0

    # 1. Parse raw data
    records = parse_data(data_path)

    # 2. Create ConceptNodes
    for record in records:
        node = ConceptNode(
            id=record["id"],
            preferred_name=record["name"],
            domain_tags=[DomainTag.DISEASE.value],
            source_vocab="my_source",
            aliases=record.get("synonyms", []),
        )
        kg.add_concept(node)
        concepts_added += 1

    # 3. Create Edges (if hierarchical)
    for record in records:
        if record.get("parent_id"):
            edge = Edge(
                source_id=record["id"],
                target_id=record["parent_id"],
                relation_type="is_a",
                source="my_source",
            )
            kg.add_edge(edge)
            edges_added += 1

    return {"concepts_added": concepts_added, "edges_added": edges_added}

Atlas Generation (Nilearn)

Use scripts/generate_atlas.py as a template for generating brain region hierarchies from Nilearn built-in atlases. Key points:

• Start with a manual hierarchy of core brain regions (~100-200)
• Augment with atlas labels (Talairach, Harvard-Oxford, AAL, Dosenbach, Pauli, Seitzman)
• Handle SSL issues by patching requests.Session.verify before Nilearn calls
• Output: TSV with columns: NN_ID, Name, Latin_Name, Synonyms, Parent_ID, Brodmann_area

Phase 2: Literature Claim Extraction

Pipeline: PubMed Search → LLM Extraction → Entity Resolution → Ingestion

PubMed query → PMIDs → XML parse → (abstract, PaperRef)
                                         │
                                    LLM extraction
                                         │
                                  [Claim objects]
                                         │
                                  Entity resolution
                                         │
                              Graph ingestion (nodes + edges)

PubMed Search Strategy

For each disease+year combination, search with neuroimaging focus:

({disease}[Title/Abstract])
AND ("brain imaging"[Title/Abstract] OR "neuroimaging"[Title/Abstract]
     OR "MRI"[Title/Abstract] OR "fMRI"[Title/Abstract] OR "PET"[Title/Abstract])
AND {year}:{year}[pdat]

Rate limit: 0.4s between NCBI API calls (3 req/sec without API key).

LLM Extraction Prompt Design

See scripts/extraction_prompt_template.txt for the recommended prompt structure. Key fields to extract:

Entity Resolution During Ingestion

When a claim references "hippocampus" and the graph already has NN:11 (preferred_name="Hippocampus"), the entity resolver matches them. If no match is found, a new concept node is created with prefix CLM_CONCEPT:.

This means the graph grows organically: atlas data provides the backbone, and claim extraction fills in relationships and discovers new entities.

Claim Node vs. Simplified Edge

Each claim generates three graph elements:

1. Claim node (CLM:abc123): full metadata (evidence, conditions, population, raw text)
2. Simplified edge (subject → object): for fast multi-hop traversal
3. About edges (claim → subject, claim → object): for provenance queries

Output Files

Complementary / Related Skills

• academic-research-hub → paper search (arXiv, PubMed, Semantic Scholar)
• research-idea → consumes knowledge graph for hypothesis generation
• method-design → uses graph structure for method comparison

Reference

• MDKG paper: Gao et al., "Large language model powered knowledge graph construction for mental health exploration." Nature Communications (2025). PMID: 40804250
• NeuroNames: Brain region hierarchy
• MeSH: Medical Subject Headings (NLM)
• DisGeNET: Gene-disease association database
• Cognitive Atlas: Cognitive paradigm ontology
• Nilearn: Python brain atlas library

Phase 3: Hypothesis Engine

The hypothesis engine batch-generates hypotheses across the entire graph, persists them to JSON, and ranks by novelty, evidence, testability, and confidence. See neurooracle/hypothesis_engine.py for the implementation.

Workflow

batch_generate() → save_hypotheses() → rank_hypotheses() → (Phase 5: convert to analysis tasks)

Capabilities

Scoring (4 Dimensions)

Each hypothesis is scored on four dimensions:

Composite ranking: confidence^0.25 * evidence^0.25 * novelty^0.25 * testability^0.25

Default Domain Pairs

The batch generator explores these cross-domain pairs:

• neuroanatomy ↔ disease
• neuroanatomy ↔ cognitive_function
• disease ↔ gene
• disease ↔ drug
• disease ↔ biomarker
• gene ↔ disease
• drug ↔ disease
• cognitive_function ↔ disease
• neurotransmitter ↔ disease

Future Work

• SapBERT entity alignment with UMLS (cosine similarity > 0.9)
• LLM-based hypothesis summarization — use LLM to generate natural language hypothesis descriptions
• Result feedback loop: validated hypotheses write back to graph
• Temporal analysis: implemented as find_trending() — tracks strengthening/weakening evidence trends across publication years

Created At: 2026-05-04 20:28 HKT Last Updated At: 2026-05-06 14:46 HKT Author: chengwang96