Graph Engineering

Graph Engineering

Graph engineering is the discipline of designing the structures agents work through, not the prompts. It has two halves:

1. Knowledge graphs: what agents remember. Nodes are entities and facts, edges are relationships with time and provenance. This file's 9-stage pipeline covers it, distilled from Southeast University's graduate KG course (https://github.com/npubird/KnowledgeGraphCourse, Prof. Peng Wang), translated to English and adapted for LLM-era agents.
2. Task graphs: how agents work. Nodes are jobs, edges are execution dependencies: parallel fan-out, separate verifier contexts, the stop rule, the human gate. Read references/task-graphs.md when the request is about orchestrating agents rather than building memory.

Core mental model: a knowledge graph is a product with a schema, not a pile of triples. Quality comes from the pipeline order, model the domain BEFORE extracting, fuse BEFORE storing, evaluate at every stage.

Teaching Mode

When the user wants to LEARN graph engineering (rather than build something), teach it, do not just execute. Rules:

1. Anchor every stage in the user's own domain: ask for one real project or dataset, then use it as the running example through all stages.
2. Generate visual artifacts as you teach. Concepts in this discipline are shapes; show them. For each major concept, produce a small diagram the user can keep, mermaid diagrams (flowchart for the pipeline and task graphs, graph LR for example ontologies and subgraphs) or a single self-contained HTML page when interactivity helps. At minimum: the 9-stage pipeline, a 3-type ontology drawn from the user's domain, one extracted subgraph (5-10 nodes) from a real sample, and the diamond pattern with the user's own jobs as nodes.
3. Teach in the pipeline's order, one stage per exchange, each ending with a small exercise ("write 3 competency questions for your project") before moving on.
4. Close by assembling what was built during the lesson into a starter ontology.yaml and a drawn task graph for the user's first real build.

The 9-Stage Pipeline

Run stages in order. For small projects stages 4-6 collapse into one extraction pass, but never skip stages 3 (ontology) or 8 (fusion), they are where real-world graphs fail.

1. Scope & value test: Confirm a graph beats a simpler structure. A graph pays off when queries are multi-hop ("who worked with X on projects using Y"), when entities recur across documents, or when relationships ARE the data. If lookups are single-hop, use a table and stop.

2. Knowledge representation choice: Pick how facts are encoded: property graph (Neo4j-style, pragmatic default), RDF triples (interop/standards), or plain typed edges in JSON/SQLite (small scale). Decide now how time and provenance attach to every fact.

3. Ontology modeling: Define entity types, relation types (with domain/range), and attributes BEFORE extraction. Start minimal: 5-15 entity types, 10-30 relation types. Two rules from the course: every relation gets a precise verb name (ACQUIRED, not RELATED_TO), and if two types are always queried together, merge them. Details and worked examples: references/modeling.md

4. Entity extraction (NER): Extract typed entities from sources. Method ladder: exact rules/dictionaries for closed vocabularies → LLM extraction with the ontology in the prompt for open text. Always extract with span + source pointer for provenance.

5. Relation extraction: Extract typed edges between recognized entities. Constrain the LLM to the ontology's relation list with domain/range checks; reject edges whose endpoints have incompatible types. This one validation step removes most hallucinated structure.

6. Event extraction: For dynamic domains (news, logs, transactions), extract events as first-class nodes (trigger + typed arguments + time), not just static edges. Extraction methods, prompt patterns, and failure modes for stages 4-6: references/extraction.md

7. Quality gate: Before fusion, sample and score: entity precision (are extracted entities real and correctly typed?), relation precision (does the source sentence actually assert the edge?). Fix the prompt/rules, not the output, then re-run. Target ≥90% precision on a 50-item sample before proceeding, recall improves with more passes; bad precision poisons the graph permanently.

8. Knowledge fusion: Merge duplicates within and across sources: same real-world entity, different surface forms ("SEU" = "Southeast University" = "东南大学"). Blocking + matching + merge policy. Skipping this is the #1 cause of useless graphs. Matching strategies: references/fusion-and-llm.md

9. Serve to LLMs (KG × LLM): Make the graph useful to agents: GraphRAG retrieval (subgraph → context), graph-as-memory (agent writes facts back through stages 4-8), and LLM-as-reasoner over paths. Patterns and pitfalls: references/fusion-and-llm.md

Working Rules

• Schema first, always. Extraction without an ontology produces a "graph" that is really a word cloud with arrows. If the user resists schema design, build the minimal 5-type ontology from 3 sample documents and show it for approval.
• Provenance on every fact. Each node/edge stores source, extracted_at, and confidence. Non-negotiable, fusion (stage 8) and trust both depend on it.
• Incremental over big-bang. Process a 10-document pilot through all 9 stages before scaling. The pilot exposes ontology gaps at 1% of the cost.
• LLM extraction is stage machinery, not the pipeline. The LLM slots into stages 4-6; the surrounding schema, validation, and fusion are what make the output a knowledge graph.

Reference Files

• references/curriculum.md: Full translated curriculum of the source course with per-lecture summaries and links to the original Chinese slide decks. Read when the user wants theory depth, the academic grounding, or the original materials.
• references/modeling.md: Knowledge representation & ontology engineering (course lectures 2-3). Read during stages 2-3.
• references/extraction.md: Entity, relation, and event extraction from rules to LLM prompting (lectures 4-7). Read during stages 4-7.
• references/fusion-and-llm.md: Knowledge fusion and KG × LLM integration (lectures 8-9). Read during stages 8-9.

Credits

Distilled and translated from 东南大学《知识图谱》研究生课程 (Southeast University graduate course on Knowledge Graphs), Prof. Peng Wang, https://github.com/npubird/KnowledgeGraphCourse. All original lecture PDFs are in Chinese; this skill is an independent English distillation adapted for AI-agent workflows.