Three Graph Router

Three-Graph Router

Overview

Real agentic systems integrate trusted structured data (CSVs, databases) with untrusted extracted data (documents, reviews). Merging them into one graph is the failure: unverified information pollutes trusted data, provenance is lost, extraction errors cascade, and validating agent reasoning becomes impossible.

The Three-Graph Architecture solves this by separating knowledge on origin, certainty, and semantic role:

• Domain graph — trusted, curated, entity-resolved. The canonical product list, the definitive org hierarchy. High certainty, stable IDs, protected from contamination.
• Lexical graph — original unstructured text in structured form. Document and Chunk nodes, immutable, complete provenance (every chunk links back to its source). This is the "retrieval" in RAG.
• Subject graph — entities/facts an LLM extracted from the lexical graph, kept SEPARATE from domain until entity resolution establishes confident links. Extraction artifacts with explicit uncertainty (confidence, model version, timestamp).

The router refuses the boundary violations that quietly destroy the architecture: raw text without provenance is refused from the lexical graph, extractions without a confidence score are refused from the subject graph, and an extraction is never written straight into the domain graph. The critical operation is entity resolution: a subject entity links to a domain entity via CORRESPONDS_TO only when similarity clears a confidence threshold (default 0.85; 0.95 high-stakes, 0.75 exploratory). The worked example: a review mentions "the Stockholm chair", the system extracts a Subject_Product, finds Product(PROD_12345, "Stockholm Chair") in the domain graph, and links them if similar enough — enabling the cross-graph query domain -> CORRESPONDS_TO -> subject -> EXTRACTED_FROM -> lexical with full provenance.

When to Use

• Ingesting mixed structured + unstructured sources into one agent knowledge base
• Designing the trusted-vs-extracted separation for a graph RAG system
• Preventing LLM extraction errors from contaminating a system of record
• Implementing the CORRESPONDS_TO linkage between extracted and canonical entities

Phrases: "three-graph", "domain/lexical/subject graph", "CORRESPONDS_TO", "entity resolution linkage", "keep extractions separate", "provenance", "trusted vs extracted knowledge".

When NOT to Use

• Single trusted source. If all data is curated and entity-resolved, it all lives in the domain graph; the separation buys nothing.
• The matching algorithm itself. This skill GATES the link with a threshold; the actual embedding/Jaro-Winkler matcher is a swappable seam, not this skill's job.
• Graph storage/query engine selection. Use graph-model-selector for the model class; this routes records, it does not pick Neo4j-vs-RDF.
• Append-only logs with no notion of "trusted". No domain/subject split applies.

Process

Rationalizations

Red Flags

• Many extractions routed with requires_resolution=False. Bug — every subject entity needs resolution before it can be trusted as domain.
• link_subject_to_domain linking almost everything. Threshold too low; you are conflating distinct entities. Raise it and re-audit.
• link_subject_to_domain linking almost nothing. Threshold too high OR the similarity stub is wrong for the domain — swap in the real matcher at the seam.
• Domain graph node count growing on every ingestion run. Extractions are leaking into domain. Verify route is the only write path to domain and that it rejects extraction origins.
• Lexical chunks with no source-document edge. Provenance broken; agent citations become unverifiable.

Non-Negotiable Verification

1. Run the benchmark battery. python cli.py benchmark must report 10/10:
   • each origin routes to the correct graph
   • provenance-less raw_text, confidence-less extraction, and extraction-marked-resolved all RAISE (boundary enforcement)
   • linkage respects the threshold and picks the best candidate
   • cross-graph path is correct
2. Run the scenario. python cli.py scenario stockholm-chair routes all three record types and shows the CORRESPONDS_TO link forming.
3. Verify CLI help. python cli.py --help exits 0 and prints this SKILL.md description (so any harness can discover the skill from --help).

Security Posture

• Prompt injection. Records are untrusted by design - subject-graph extractions come from adversarial documents. The router never executes payload content; its refusal rules ARE the defense that keeps injected extractions out of the trusted domain graph. The attack to resist is threshold-lowering or marking extractions entity_resolved to bypass the gate.
• Data exfiltration. No network calls, no file writes. Record payloads and provenance metadata stay in-process; routing decisions go to stdout and the caller owns downstream piping.
• Privilege escalation. A CORRESPONDS_TO link is the escalation surface: it promotes extracted data toward trusted status. The gate links only above the confidence threshold, and no code path writes an extraction directly to domain - keep those invariants when swapping in a real matcher at the seam.

Source Attribution

Distilled from Agentic GraphRAG (O'Reilly, by Anthony Alcaraz and Sam Julien) Ch3 — Knowledge Representation, section "The Three-Graph Architecture for Agent Knowledge" (domain / lexical / subject graphs, Figure 3-2) and "Entity Resolution and Linking Across Graphs" (the CORRESPONDS_TO three-stage linking pipeline and the 0.95 / 0.85 / 0.75 Jaro-Winkler thresholds). The Stockholm-chair worked example is the chapter's own illustration of subject-to-domain resolution.