knowledge-graph-builder

Knowledge Graph Builder

Overview

Knowledge graphs represent structured relationships between entities, enabling powerful reasoning, contextual retrieval, and explainable AI. Building production knowledge graphs requires ontology design, entity extraction, graph database selection, query optimization, and integration with LLM systems via GraphRAG patterns.

Knowledge Graph Architecture

+------------------+     +-------------------+     +------------------+
| Data Sources     | --> | Extraction        | --> | Graph Database   |
| - Documents      |     | - NER             |     | (Person)-[:WORKS_AT]->(Company)
| - APIs           |     | - Relation extract|     | (Paper)-[:CITES]->(Paper)
| - Databases      |     | - Entity linking  |     | (Product)-[:HAS]->(Feature)
+------------------+     +-------------------+     +------------------+
                                                          |
+------------------+     +-------------------+     +------v-----------+
| Applications     | <-- | Query & Reasoning | <-- | Indexing &       |
| - GraphRAG       |     | - Cypher / SPARQL |     | Enrichment       |
| - Recommendations|     | - Path finding    |     | - Embeddings     |
| - Analytics      |     | - Subgraph match  |     | - Community det. |
+------------------+     +-------------------+     +------------------+

Graph Database Selection

Selection guide:
  AWS native? -> Amazon Neptune
  Need RDF/SPARQL? -> Neptune or Apache Jena
  Graph + document hybrid? -> ArangoDB (multi-model)
  SQL-like preferred? -> Neo4j (Cypher is most approachable)
  GraphQL preferred? -> Dgraph
  Enterprise trillions of edges? -> TigerGraph
  Default -> Neo4j (largest community, vector search, mature)

Ontology Design

Design Process

1. Start with competency questions
   "Who authored papers about topic X?"
   "What products share features?"

2. Identify entity types (nouns in questions)

3. Define relationship types (verbs connecting nouns)
   Always directional: (Subject)-[:VERB]->(Object)

4. Add properties (attributes of nodes and edges)
   Include temporal properties (created_at, valid_from)

5. Define constraints (uniqueness, required props, cardinality)

Schema in Neo4j

CREATE CONSTRAINT person_id IF NOT EXISTS
FOR (p:Person) REQUIRE p.id IS UNIQUE;

CREATE CONSTRAINT company_id IF NOT EXISTS
FOR (c:Company) REQUIRE c.id IS UNIQUE;

CREATE FULLTEXT INDEX entity_search IF NOT EXISTS
FOR (n:Person|Company|Paper) ON EACH [n.name, n.title, n.description];

CREATE VECTOR INDEX entity_embeddings IF NOT EXISTS
FOR (n:Entity) ON (n.embedding)
OPTIONS {indexConfig: {
  `vector.dimensions`: 1536,
  `vector.similarity_function`: 'cosine'
}};

Common Ontology Patterns

Temporal:     (Person)-[:WORKS_AT {from: date, to: date}]->(Company)
Hierarchical: (Category)-[:SUBCATEGORY_OF]->(Category)
Provenance:   (Fact)-[:EXTRACTED_FROM {confidence: 0.95}]->(Document)
Events:       (Person)-[:PARTICIPATED_IN]->(Event)-[:OCCURRED_AT]->(Location)
Multi-hop:    (Drug)-[:TREATS]->(Disease)-[:HAS_SYMPTOM]->(Symptom)

Entity and Relation Extraction

LLM-Based Extraction

from openai import OpenAI
import json

class KnowledgeExtractor:
    def __init__(self, model: str = "gpt-4o-mini"):
        self.client = OpenAI()
        self.model = model

    def extract(self, text: str, schema: dict = None) -> dict:
        schema_inst = ""
        if schema:
            schema_inst = (f"\nEntity types: {schema.get('entity_types', [])}\n"
                          f"Relation types: {schema.get('relation_types', [])}\n")

        response = self.client.chat.completions.create(
            model=self.model,
            messages=[
                {"role": "system", "content": "Extract precise entities and relationships. "
                 "Only extract what is explicitly stated or strongly implied."},
                {"role": "user", "content": f"Extract entities and relationships:{schema_inst}\n"
                 f"Return JSON: {{\"entities\": [{{\"id\", \"type\", \"name\", \"properties\"}}], "
                 f"\"relationships\": [{{\"source\", \"target\", \"type\", \"properties\"}}]}}\n\n"
                 f"Text: {text}"},
            ],
            response_format={"type": "json_object"}, temperature=0,
        )
        return json.loads(response.choices[0].message.content)

    def extract_batch(self, documents: list[str], schema: dict = None) -> dict:
        all_entities = {}
        all_rels = []
        for doc in documents:
            result = self.extract(doc, schema)
            for e in result.get("entities", []):
                key = (e["type"], e["name"].lower())
                if key not in all_entities:
                    all_entities[key] = e
                else:
                    all_entities[key]["properties"].update(e.get("properties", {}))
            all_rels.extend(result.get("relationships", []))
        return {"entities": list(all_entities.values()), "relationships": all_rels}

Extraction Method Comparison

GraphRAG

GraphRAG vs. Vector RAG

Implementation

from neo4j import GraphDatabase

class GraphRAGPipeline:
    def __init__(self, neo4j_uri: str, neo4j_auth: tuple, llm_model: str = "gpt-4o"):
        self.driver = GraphDatabase.driver(neo4j_uri, auth=neo4j_auth)
        self.client = OpenAI()
        self.llm_model = llm_model

    def query(self, question: str) -> dict:
        entities = self._extract_query_entities(question)
        subgraph = self._retrieve_subgraph(entities)
        answer = self._generate_answer(question, subgraph)
        return {"answer": answer, "entities_found": entities,
                "subgraph_nodes": len(subgraph["nodes"])}

    def _extract_query_entities(self, question: str) -> list[str]:
        resp = self.client.chat.completions.create(
            model="gpt-4o-mini",
            messages=[{"role": "user", "content":
                f"Extract entity names. JSON: {{\"entities\": [...]}}\nQuestion: {question}"}],
            response_format={"type": "json_object"}, temperature=0,
        )
        return json.loads(resp.choices[0].message.content).get("entities", [])

    def _retrieve_subgraph(self, entities: list[str], hops: int = 2) -> dict:
        nodes, edges = [], []
        with self.driver.session() as session:
            for entity in entities:
                result = session.run("""
                    CALL db.index.fulltext.queryNodes('entity_search', $name)
                    YIELD node, score WHERE score > 0.5
                    WITH node LIMIT 5
                    CALL apoc.path.subgraphAll(node, {maxLevel: $hops, limit: 50})
                    YIELD nodes, relationships
                    RETURN nodes, relationships
                """, name=entity, hops=hops)
                for record in result:
                    nodes.extend([{"labels": list(n.labels), "props": dict(n)} for n in record["nodes"]])
                    edges.extend([{"type": r.type} for r in record["relationships"]])
        return {"nodes": nodes, "edges": edges}

    def _generate_answer(self, question: str, subgraph: dict) -> str:
        context = "\n".join(
            f"[{'/'.join(n['labels'])}] {n['props']}" for n in subgraph["nodes"][:30]
        )
        resp = self.client.chat.completions.create(
            model=self.llm_model,
            messages=[
                {"role": "system", "content": "Answer using the knowledge graph context. Cite entities."},
                {"role": "user", "content": f"Context:\n{context}\n\nQuestion: {question}"},
            ], temperature=0,
        )
        return resp.choices[0].message.content

Knowledge Graph Embeddings

Query Optimization

-- Bound traversal depth (never use unbounded [*])
MATCH (a:Person {name: "Alice"})-[*1..3]->(b:Company)
RETURN b.name;

-- Use full-text index instead of CONTAINS
CALL db.index.fulltext.queryNodes('entity_search', 'Alice') YIELD node;

-- Profile to find bottlenecks
PROFILE MATCH (a:Person)-[:WORKS_AT]->(c:Company)-[:LOCATED_IN]->(city:City)
WHERE city.name = "San Francisco"
RETURN a.name, c.name;

-- Use parameters (enables query plan caching)
MATCH (p:Person {name: $name}) RETURN p;

Checklist

• Define competency questions the graph must answer
• Design ontology with entity types, relationships, and constraints
• Select graph database based on deployment, scale, and team expertise
• Build entity extraction pipeline (SpaCy for speed, LLM for quality)
• Implement relation extraction with confidence scoring
• Set up entity linking and deduplication across documents
• Create graph indexes (full-text, vector, composite)
• Implement GraphRAG pipeline for LLM-powered Q&A
• Optimize queries with bounded traversals and index usage
• Plan incremental update strategy for evolving knowledge bases
• Monitor graph quality (completeness, consistency, freshness)

When to Use

Use this skill when:

• Designing or implementing knowledge graph builder solutions
• Reviewing or improving existing knowledge graph builder approaches
• Making architectural or implementation decisions about knowledge graph builder
• Learning knowledge graph builder patterns and best practices
• Troubleshooting knowledge graph builder-related issues

Do NOT use this skill when:

• The question is about a fundamentally different technology domain
• A more specific sibling skill covers the exact topic needed
• The user needs a complete hands-on tutorial rather than expert guidance

Output Format

# Knowledge Graph Builder Analysis

## Context Assessment
[Situation summary and constraints]

## Recommended Approach
[Primary recommendation with rationale]

## Implementation Steps
1. [Step with specific details]
2. [Step with specific details]
3. [Step with specific details]

## Trade-offs and Considerations
- [Key trade-off 1]
- [Key trade-off 2]

## Next Steps
- [Immediate action item]
- [Follow-up action item]

Example

Input: "Help me implement knowledge graph builder for a medium-scale production application"

Output: A structured analysis covering current state assessment, recommended knowledge graph builder approach with specific patterns, implementation roadmap with milestones, and risk mitigation strategies tailored to the application scale and constraints.

Edge Cases

• Legacy system integration: When knowledge graph builder must coexist with legacy approaches, provide a gradual migration path rather than a complete rewrite
• Scale mismatch: When the solution complexity exceeds the project scale, recommend a simpler approach and note when to revisit
• Team skill gaps: When the team lacks experience with the recommended approach, include learning resources and simpler alternatives
• Conflicting requirements: When constraints conflict (e.g., performance vs. maintainability), explicitly state the trade-off and recommend based on stated priorities