/kg-builder

name: kg-builder
description: 'Designs and builds knowledge graphs from documents — ontology modeling with domain/range constraints, entity/relation/event extraction, entity resolution, provenance and supersession, and GraphRAG serving. Use when asked to "build a knowledge graph", "design an ontology", "extract entities and relations", "deduplicate entities", "entity resolution", "add GraphRAG", or "graph memory for an agent". NOT for multi-agent task graphs or agent orchestration, use task-decomposer.'
metadata:
  version: 1.0.0
  category: data
  tags: [knowledge-graph, ontology, entity-resolution, graphrag, provenance]
  difficulty: advanced
  phase: build

KG Builder

A knowledge graph is a product with a schema, not a pile of triples. Quality comes from pipeline order: model the domain **before** extracting, validate **during** extraction, fuse **before** storing, and attach provenance to every fact from the first write.

This skill covers the full build — value test, ontology, extraction, quality gate, entity resolution, serving, and maintenance — plus the boundary question that decides whether the result is trustworthy: which stages are deterministic code and which are LLM judgment.

**Scope note.** This is about knowledge graphs — what an agent *remembers*. It is not about task graphs, agent orchestration, or multi-agent topology.

Reference Files

| File | Contents | Load When | |---|---|---| | `references/ontology-design.md` | Competency questions, entity/relation types, domain/range, storage choice | Phase 1 | | `references/extraction.md` | Source routing, NER/RE/EE prompt patterns, validation, failure modes | Phase 2 | | `references/fusion.md` | Blocking, matching layers, merge policy, threshold bands | Phase 3 | | `references/serving.md` | GraphRAG retrieval, path queries, community summaries, query layer | Phase 4 | | `references/provenance-and-supersession.md` | Claim model, append-only updates, contradiction handling, audit trail | Phase 1 and Phase 4 |

The deterministic / LLM boundary

Decide this before writing code. Code owns control flow, identity, validation, and merges. The model gets contained judgments behind a typed interface, each with a measured baseline.

| Stage | Deterministic (code) | LLM judgment (measure it) | |---|---|---| | Source routing | format detection, structured mapping | — | | Entity extraction | span capture, type validation, dictionary matching | "what entities are in this text" | | Relation extraction | domain/range enforcement, endpoint checks | "which relation does this sentence assert" | | Quality gate | sampling, scoring, thresholds | — | | Blocking | key generation, candidate pairing | — | | Matching | string/attribute/structure scoring | ambiguous middle band only | | Merge | canonical selection, edge union, lineage | — (never let a model own a merge) | | Serving | traversal, subgraph selection, serialization | the agent's own reasoning |

**Measure every LLM surface against a prompt-only baseline before trusting it.** This is not theoretical caution. In a pre-registered real-model evaluation of an LLM-adjudicated dedup and contradiction loop, the loop trailed a plain prompt-only baseline by 0.28–0.33 on detection and safety across every provider cell tested. Adjudication that is not measured is decoration.

Workflow

Phase 1 — Design (do not skip)

1. **Value test.** A graph pays off when queries are multi-hop ("who worked with X on projects using Y"), when entities recur across documents, or when the relationships *are* the data. If every query is a single-hop lookup or an aggregation, use a table and stop here. Write the kill criterion down before continuing. 2. **Competency questions.** Write the 10–20 questions the graph must answer. These are the ontology's spec and its test suite. Anything you cannot path through the finished schema is a missing type or relation. 3. **Ontology.** 5–15 entity types, 10–30 relation types, each relation with explicit domain and range. Precise verb names (`ACQUIRED`, `DEPENDS_ON`) — never `RELATED_TO`. Keep it in `ontology.yaml` as the single source of truth; every extraction prompt embeds it verbatim. 4. **Storage and identity.** Choose property graph (default), RDF/OWL (interop, description-logic reasoning), or typed edges in SQLite (<50K nodes). Decide *now* how time and provenance attach to every fact — retrofitting provenance after fusion is effectively impossible.

Validate the schema before extracting anything:

uv run scripts/validate_ontology.py ontology.yaml

Phase 2 — Extract

5. **Route by source type.** Structured sources (databases, CSVs, APIs) map column → type in deterministic code with no model involved. Semi-structured sources (HTML tables, infoboxes) get per-layout parsers. Only unstructured text enters the LLM pipeline. Running NLP over already-structured data is the classic waste. 6. **Entities.** Dictionaries and exact rules first for closed vocabularies — free, deterministic, perfect precision. LLM extraction for open text, with the ontology in the prompt. Always capture surface form, canonical guess, type, source pointer, and confidence. 7. **Relations.** Extract only between entities that already passed step 6; never let relation extraction invent endpoints. Constrain output to the ontology's relation list and **validate domain/range