Knowledge Graph Builder

Knowledge Graph Builder

Build structured knowledge graphs for enhanced AI system performance through relational knowledge.

Core Principle

Knowledge graphs make implicit relationships explicit, enabling AI systems to reason about connections, verify facts, and avoid hallucinations.

When to Use Knowledge Graphs

Use Knowledge Graphs When:

• ✅ Complex entity relationships are central to your domain
• ✅ Need to verify AI-generated facts against structured knowledge
• ✅ Semantic search and relationship traversal required
• ✅ Data has rich interconnections (people, organizations, products)
• ✅ Need to answer "how are X and Y related?" queries
• ✅ Building recommendation systems based on relationships
• ✅ Fraud detection or pattern recognition across connected data

Don't Use Knowledge Graphs When:

• ❌ Simple tabular data (use relational DB)
• ❌ Purely document-based search (use RAG with vector DB)
• ❌ No significant relationships between entities
• ❌ Team lacks graph modeling expertise
• ❌ Read-heavy workload with no traversal (use traditional DB)

---

6-Phase Knowledge Graph Implementation

Phase 1: Ontology Design

Goal: Define entities, relationships, and properties for your domain

Entity Types (Nodes):

• Person, Organization, Location, Product, Concept, Event, Document

Relationship Types (Edges):

• Hierarchical: IS_A, PART_OF, REPORTS_TO
• Associative: WORKS_FOR, LOCATED_IN, AUTHORED_BY, RELATED_TO
• Temporal: CREATED_ON, OCCURRED_BEFORE, OCCURRED_AFTER

Properties (Attributes):

• Node properties: id, name, type, created_at, metadata
• Edge properties: type, confidence, source, timestamp

Example Ontology:

# RDF/Turtle format
@prefix : <http://example.org/ontology#> .

:Person a owl:Class ;
    rdfs:label "Person" .

:Organization a owl:Class ;
    rdfs:label "Organization" .

:worksFor a owl:ObjectProperty ;
    rdfs:domain :Person ;
    rdfs:range :Organization ;
    rdfs:label "works for" .

Validation:

• [ ] Entities cover all domain concepts
• [ ] Relationships capture key connections
• [ ] Ontology reviewed with domain experts
• [ ] Classification hierarchy defined (is-a relationships)

---

Phase 2: Graph Database Selection

Decision Matrix:

Neo4j (Recommended for most):

• Pros: Mature, Cypher query language, graph algorithms, excellent visualization
• Cons: Licensing costs for enterprise, scaling complexity
• Use when: Complex queries, graph algorithms, team can learn Cypher

Amazon Neptune:

• Pros: Managed service, supports Gremlin and SPARQL, AWS integration
• Cons: Vendor lock-in, more expensive than self-hosted
• Use when: AWS infrastructure, need managed service, compliance requirements

ArangoDB:

• Pros: Multi-model (graph + document + key-value), JavaScript queries
• Cons: Smaller community, fewer graph-specific features
• Use when: Need document DB + graph in one system

TigerGraph:

• Pros: Best performance for deep traversals, parallel processing
• Cons: Complex setup, higher learning curve
• Use when: Massive graphs (billions of edges), real-time analytics

Technology Stack:

graph_database: 'Neo4j Community' # or Enterprise for production
vector_integration: 'Pinecone' # For hybrid search
embeddings: 'text-embedding-3-large' # OpenAI
etl: 'Apache Airflow' # For data pipelines

Neo4j Schema Setup:

// Create constraints for uniqueness
CREATE CONSTRAINT person_id IF NOT EXISTS
FOR (p:Person) REQUIRE p.id IS UNIQUE;

CREATE CONSTRAINT org_name IF NOT EXISTS
FOR (o:Organization) REQUIRE o.name IS UNIQUE;

// Create indexes for performance
CREATE INDEX entity_search IF NOT EXISTS
FOR (e:Entity) ON (e.name, e.type);

CREATE INDEX relationship_type IF NOT EXISTS
FOR ()-[r:RELATED_TO]-() ON (r.type, r.confidence);

---

Phase 3: Entity Extraction & Relationship Building

Goal: Extract entities and relationships from data sources

Data Sources:

• Structured: Databases, APIs, CSV files
• Unstructured: Documents, web content, text files
• Semi-structured: JSON, XML, knowledge bases

Entity Extraction Pipeline:

class EntityExtractionPipeline:
    def __init__(self):
        self.ner_model = load_ner_model()  # spaCy, Hugging Face
        self.entity_linker = EntityLinker()
        self.deduplicator = EntityDeduplicator()

    def process_text(self, text: str) -> List[Entity]:
        # 1. Extract named entities
        entities = self.ner_model.extract(text)

        # 2. Link to existing entities (entity resolution)
        linked_entities = self.entity_linker.link(entities)

        # 3. Deduplicate and resolve conflicts
        resolved_entities = self.deduplicator.resolve(linked_entities)

        return resolved_entities

Relationship Extraction:

class RelationshipExtractor:
    def extract_relationships(self, entities: List[Entity],
                            text: str) -> List[Relationship]:
        relationships = []

        # Use dependency parsing or LLM for extraction
        doc = self.nlp(text)
        for sent in doc.sents:
            rels = self.extract_from_sentence(sent, entities)
            relationships.extend(rels)

        # Validate against ontology
        valid_relationships = self.validate_relationships(relationships)
        return valid_relationships

LLM-Based Extraction (for complex relationships):

def extract_with_llm(text: str) -> List[Relationship]:
    prompt = f"""
    Extract entities and relationships from this text:
    {text}

    Format: (Entity1, Relationship, Entity2, Confidence)
    Only extract factual relationships.
    """

    response = llm.generate(prompt)
    relationships = parse_llm_response(response)
    return relationships

Validation:

• [ ] Entity extraction accuracy >85%
• [ ] Entity deduplication working
• [ ] Relationships validated against ontology
• [ ] Confidence scores assigned

---

Phase 4: Hybrid Knowledge-Vector Architecture

Goal: Combine structured graph with semantic vector search

Architecture:

class HybridKnowledgeSystem:
    def __init__(self):
        self.graph_db = Neo4jConnection()
        self.vector_db = PineconeClient()
        self.embedding_model = OpenAIEmbeddings()

    def store_entity(self, entity: Entity):
        # Store structured data in graph
        self.graph_db.create_node(entity)

        # Store embeddings in vector database
        embedding = self.embedding_model.embed(entity.description)
        self.vector_db.upsert(
            id=entity.id,
            values=embedding,
            metadata=entity.metadata
        )

    def hybrid_search(self, query: str, top_k: int = 10) -> SearchResults:
        # 1. Vector similarity search
        query_embedding = self.embedding_model.embed(query)
        vector_results = self.vector_db.query(
            vector=query_embedding,
            top_k=100
        )

        # 2. Graph traversal from vector results
        entity_ids = [r.id for r in vector_results.matches]
        graph_results = self.graph_db.get_subgraph(entity_ids, max_hops=2)

        # 3. Merge and rank results
        merged = self.merge_results(vector_results, graph_results)
        return merged[:top_k]

Benefits of Hybrid Approach:

• Vector search: Semantic similarity, flexible queries
• Graph traversal: Relationship-based reasoning, context expansion
• Combined: Best of both worlds

---

Phase 5: Query Patterns & API Design

Common Query Patterns:

1. Find Entity:

MATCH (e:Entity {id: $entity_id})
RETURN e

2. Find Relationships:

MATCH (source:Entity {id: $entity_id})-[r]-(target)
RETURN source, r, target
LIMIT 20

3. Path Between Entities:

MATCH path = shortestPath(
  (source:Person {id: $source_id})-[*..5]-(target:Person {id: $target_id})
)
RETURN path

4. Multi-Hop Traversal:

MATCH (p:Person {name: $name})-[:WORKS_FOR]->(o:Organization)-[:LOCATED_IN]->(l:Location)
RETURN p.name, o.name, l.city

5. Recommendation Query:

// Find people similar to this person based on shared organizations
MATCH (p1:Person {id: $person_id})-[:WORKS_FOR]->(o:Organization)<-[:WORKS_FOR]-(p2:Person)
WHERE p1 <> p2
RETURN p2, COUNT(o) AS shared_orgs
ORDER BY shared_orgs DESC
LIMIT 10

Knowledge Graph API:

class KnowledgeGraphAPI:
    def __init__(self, graph_db):
        self.graph = graph_db

    def find_entity(self, entity_name: str) -> Entity:
        """Find entity by name with fuzzy matching"""
        query = """
        MATCH (e:Entity)
        WHERE e.name CONTAINS $name
        RETURN e
        ORDER BY apoc.text.levenshtein(e.name, $name)
        LIMIT 1
        """
        return self.graph.run(query, name=entity_name).single()

    def find_relationships(self, entity_id: str,
                         relationship_type: str = None,
                         max_hops: int = 2) -> List[Relationship]:
        """Find relationships within specified hops"""
        query = f"""
        MATCH (source:Entity {{id: $entity_id}})
        MATCH path = (source)-[r*1..{max_hops}]-(target)
        RETURN path, relationships(path) AS rels
        LIMIT 100
        """
        return self.graph.run(query, entity_id=entity_id).data()

    def get_subgraph(self, entity_ids: List[str],
                    max_hops: int = 2) -> Subgraph:
        """Get connected subgraph for multiple entities"""
        query = f"""
        MATCH (e:Entity)
        WHERE e.id IN $entity_ids
        CALL apoc.path.subgraphAll(e, {{maxLevel: {max_hops}}})
        YIELD nodes, relationships
        RETURN nodes, relationships
        """
        return self.graph.run(query, entity_ids=entity_ids).data()

---

Phase 6: AI Integration & Hallucination Prevention

Goal: Use knowledge graph to ground LLM responses and detect hallucinations

Knowledge Graph RAG:

class KnowledgeGraphRAG:
    def __init__(self, kg_api, llm_client):
        self.kg = kg_api
        self.llm = llm_client

    def retrieve_context(self, query: str) -> str:
        # Extract entities from query
        entities = self.extract_entities_from_query(query)

        # Retrieve relevant subgraph
        subgraph = self.kg.get_subgraph(
            [e.id for e in entities],
            max_hops=2
        )

        # Format subgraph for LLM
        context = self.format_subgraph_for_llm(subgraph)
        return context

    def generate_with_grounding(self, query: str) -> GroundedResponse:
        context = self.retrieve_context(query)

        prompt = f"""
        Context from knowledge graph:
        {context}

        User query: {query}

        Answer based only on the provided context. Include source entities.
        """

        response = self.llm.generate(prompt)

        return GroundedResponse(
            response=response,
            sources=self.extract_sources(context),
            confidence=self.calculate_confidence(response, context)
        )

Hallucination Detection:

class HallucinationDetector:
    def __init__(self, knowledge_graph):
        self.kg = knowledge_graph

    def verify_claim(self, claim: str) -> VerificationResult:
        # Parse claim into (subject, predicate, object)
        parsed_claim = self.parse_claim(claim)

        # Query knowledge graph for evidence
        evidence = self.kg.find_evidence(
            parsed_claim.subject,
            parsed_claim.predicate,
            parsed_claim.object
        )

        if evidence:
            return VerificationResult(
                is_supported=True,
                evidence=evidence,
                confidence=evidence.confidence
            )

        # Check for contradictory evidence
        contradiction = self.kg.find_contradiction(parsed_claim)

        return VerificationResult(
            is_supported=False,
            is_contradicted=bool(contradiction),
            contradiction=contradiction
        )

---

Key Principles

1. Start with Ontology

Define your schema before ingesting data. Changing ontology later is expensive.

2. Entity Resolution is Critical

Deduplicate entities aggressively. "Apple Inc", "Apple", "Apple Computer" → same entity.

3. Confidence Scores on Everything

Every relationship should have a confidence score (0.0-1.0) and source.

4. Incremental Building

Don't try to model entire domain at once. Start with core entities and expand.

5. Hybrid Architecture Wins

Combine graph traversal (structured) with vector search (semantic) for best results.

---

Common Use Cases

1. Question Answering:

• Extract entities from question
• Traverse graph to find answer
• Return path as explanation

2. Recommendation:

• Find similar entities via shared relationships
• Rank by relationship strength
• Return top-K recommendations

3. Fraud Detection:

• Model transactions as graph
• Find suspicious patterns (cycles, anomalies)
• Flag for review

4. Knowledge Discovery:

• Identify implicit relationships
• Suggest missing connections
• Validate with domain experts

5. Semantic Search:

• Hybrid vector + graph search
• Expand context via relationships
• Return rich connected results

---

Technology Recommendations

For MVPs (<10K entities):

• Neo4j Community Edition (free)
• SQLite for metadata
• OpenAI embeddings
• FastAPI for API layer

For Production (10K-1M entities):

• Neo4j Enterprise or ArangoDB
• Pinecone for vector search
• Airflow for ETL
• GraphQL API

For Enterprise (1M+ entities):

• Neo4j Enterprise or TigerGraph
• Distributed vector DB (Pinecone, Weaviate)
• Kafka for streaming
• Kubernetes deployment

---

Validation Checklist

• [ ] Ontology designed and validated with domain experts
• [ ] Graph database selected and set up
• [ ] Entity extraction pipeline tested (>85% accuracy)
• [ ] Relationship extraction validated
• [ ] Hybrid search (graph + vector) implemented
• [ ] Query API created and documented
• [ ] AI integration tested (RAG or hallucination detection)
• [ ] Performance benchmarks met (query <100ms for common patterns)
• [ ] Data quality monitoring in place
• [ ] Backup and recovery tested

---

Related Resources

Related Skills:

• rag-implementer - For hybrid KG+RAG systems
• multi-agent-architect - For knowledge-graph-powered agents
• api-designer - For KG API design

Related Patterns:

• META/DECISION-FRAMEWORK.md - Graph DB selection
• STANDARDS/architecture-patterns/knowledge-graph-pattern.md - KG architectures (when created)

Related Playbooks:

• PLAYBOOKS/deploy-neo4j.md - Neo4j deployment (when created)
• PLAYBOOKS/build-kg-rag-system.md - KG-RAG integration (when created)

Knowledge Graph Builder - Quick Start

Version: 1.0.0 Category: AI-Native Development Difficulty: Advanced

What This Skill Does

Guides design and implementation of knowledge graphs for modeling complex entity relationships, semantic search, and AI hallucination prevention through structured knowledge.

When to Use

Use this skill when you need to:

• Model complex relationships between entities
• Build semantic search with relationship traversal
• Verify AI-generated facts against structured knowledge
• Create recommendation systems based on connections
• Detect fraud or patterns in connected data
• Ground LLM responses in verifiable knowledge

Quick Start

Fastest path to a working knowledge graph:

1. Design ontology (Phase 1)

• Define entity types (Person, Organization, Location, etc.)
• Define relationship types (WORKS_FOR, LOCATED_IN, etc.)
• Add properties (id, name, confidence, timestamp)
• Validate with domain experts

2. Choose graph database (Phase 2)

• MVP: Neo4j Community (free, mature, excellent)
• Production: Neo4j Enterprise or ArangoDB
• AWS: Amazon Neptune (managed)
• Performance: TigerGraph (billions of edges)

3. Extract entities and relationships (Phase 3)

• Use NER models (spaCy, Hugging Face) for entities
• Use dependency parsing or LLM for relationships
• Implement entity resolution (deduplication)
• Assign confidence scores

4. Build hybrid architecture (Phase 4)

• Graph DB (Neo4j) for structured relationships
• Vector DB (Pinecone) for semantic search
• Combine for best of both worlds

5. Create query API (Phase 5)

• Find entity, find relationships, shortest path
• Multi-hop traversal, recommendations
• Natural language query interface

6. Integrate with AI (Phase 6)

• Knowledge Graph RAG (ground LLM responses)
• Hallucination detection (verify claims)
• Self-correction loops

Time to working graph: 1-2 weeks for MVP, 4-8 weeks for production

File Structure

knowledge-graph-builder/
├── SKILL.md           # Main skill instructions (start here)
└── README.md          # This file

Prerequisites

Knowledge:

• Graph theory basics (nodes, edges, paths)
• Understanding of ontologies and semantic relationships
• Database query fundamentals

Tools:

• Graph database (Neo4j recommended)
• NER model (spaCy or Hugging Face)
• Vector database (Pinecone, Weaviate) for hybrid
• LLM API (Anthropic Claude or OpenAI) for extraction

Related Skills:

• rag-implementer for hybrid KG+RAG systems
• multi-agent-architect for knowledge-powered agents

Success Criteria

You've successfully used this skill when:

• ✅ Ontology designed and validated with domain experts
• ✅ Graph database set up with schema constraints
• ✅ Entity extraction pipeline working (>85% accuracy)
• ✅ Relationship extraction validated against ontology
• ✅ Hybrid search (graph + vector) implemented
• ✅ Query API created with common patterns
• ✅ AI integration tested (KG-RAG or hallucination detection)
• ✅ Query performance meets targets (<100ms for common queries)
• ✅ Data quality monitoring in place
• ✅ Backup and recovery procedures tested

Common Workflows

Workflow 1: Build Knowledge Graph from Documents

1. Use knowledge-graph-builder ontology design (Phase 1) 2. Extract entities and relationships with LLM (Phase 3) 3. Store in Neo4j with confidence scores 4. Build query API for access 5. Integrate with rag-implementer for KG-RAG

Workflow 2: Semantic Search with Relationships

1. Design ontology for domain 2. Set up hybrid architecture (Neo4j + Pinecone) 3. Extract and store entities with embeddings 4. Implement hybrid search (vector similarity + graph traversal) 5. Return results with relationship context

Workflow 3: AI Hallucination Prevention

1. Build knowledge graph from verified sources 2. Implement KG-RAG system 3. Add hallucination detection layer 4. Verify LLM claims against graph 5. Return only verified or flag uncertain claims

Key Concepts

Ontology Design:

• Entities: Nodes representing real-world concepts
• Relationships: Edges connecting entities
• Properties: Attributes on nodes and edges
• Confidence: Score (0.0-1.0) on relationships

Graph Database Options:

• Neo4j: Most popular, Cypher query language, graph algorithms
• Amazon Neptune: Managed AWS service, Gremlin/SPARQL
• ArangoDB: Multi-model (graph + document + KV)
• TigerGraph: High-performance, massive scale

Hybrid Architecture:

• Graph DB: Structured relationships, traversal, reasoning
• Vector DB: Semantic similarity, flexible search
• Combined: Structured + semantic = best results

Query Patterns:

• Find entity: Simple lookup by ID or name
• Find relationships: 1-hop connections from entity
• Shortest path: Connect two entities via relationships
• Multi-hop: Traverse N hops for context expansion
• Recommendations: Find similar via shared relationships

AI Integration:

• KG-RAG: Retrieve from graph, generate with LLM
• Hallucination detection: Verify claims against graph
• Self-correction: Iteratively fix inaccurate responses

Troubleshooting

Skill not activating?

• Try explicitly requesting: "Use the knowledge-graph-builder skill to..."
• Mention keywords: "knowledge graph", "ontology", "relationships", "Neo4j"

Should I use a knowledge graph or just RAG?

• RAG: Document search, semantic similarity, no complex relationships
• Knowledge Graph: Entity relationships central, need traversal, verification
• Hybrid KG+RAG: Best of both (recommended for complex domains)

Choosing between Neo4j, Neptune, ArangoDB?

• Neo4j: Most mature, best for learning, excellent community
• Neptune: AWS infrastructure, managed service, compliance
• ArangoDB: Need document DB + graph in one system
• Start with Neo4j Community (free) for MVP

Entity extraction accuracy too low?

• Use larger NER models (Hugging Face transformers)
• Fine-tune on domain-specific data
• Use LLM (Claude, GPT-4) for complex extraction
• Implement human-in-the-loop validation
• Track confidence scores, review low-confidence entities

Too many duplicate entities?

• Implement robust entity resolution
• Use fuzzy matching (Levenshtein distance)
• Normalize entity names (lowercase, strip whitespace)
• Create canonical entity IDs
• Merge duplicates with highest-confidence properties

Graph queries too slow?

• Add indexes on frequently queried properties
• Limit traversal depth (max_hops parameter)
• Use pagination for large result sets
• Cache common queries
• Optimize Cypher queries (use EXPLAIN and PROFILE)
• Consider read replicas for high traffic

How to handle conflicting information?

• Assign confidence scores to all relationships
• Track data sources for provenance
• Implement conflict resolution rules
• Keep multiple versions with timestamps
• Flag conflicts for human review

Hybrid search not working well?

• Tune vector search top_k (try 50-200)
• Adjust graph traversal depth (1-3 hops typically)
• Weight vector vs graph results differently
• Filter by entity types before graph traversal
• Experiment with different embedding models

Version History

• 1.0.0 (2025-10-21): Initial release, adapted from Knowledge Graph Engineering Framework

License

Part of ai-dev-standards repository.