# Dual Graph Router

> |

- **Type:** Skill
- **Install:** `agentstack add skill-anthonyalcaraz-agentic-graph-rag-skills-dual-graph-router`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [AnthonyAlcaraz](https://agentstack.voostack.com/s/anthonyalcaraz)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [AnthonyAlcaraz](https://github.com/AnthonyAlcaraz)
- **Source:** https://github.com/AnthonyAlcaraz/agentic-graph-rag-skills/tree/main/skills/architecture/dual-graph-router
- **Website:** https://www.oreilly.com/library/view/agentic-graphrag/9798341623163/

## Install

```sh
agentstack add skill-anthonyalcaraz-agentic-graph-rag-skills-dual-graph-router
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Dual-Graph Router

## Overview

The dual-graph architecture is the central framework of the book. An agentic
system needs two complementary structures: a representation of what it KNOWS
(the vertical knowledge graph — entities, relationships, constraints) and a
representation of how it ACTS (the horizontal workflow graph — reasoning,
execution, decision, and validation nodes with explicit dependencies). "The
vertical graph is the map. The horizontal graph is the route."

This skill routes a request to the right structure before any work begins:

- **vertical** — a knowledge question answerable by one traversal. "Which
  services depend on payments-db and were deployed in the last 24 hours?" is a
  single `MATCH` over `DEPENDS_ON` edges with a temporal filter (Example 2-1),
  not a workflow.
- **horizontal** — a process the agent must carry out. "Classify the alert,
  plan remediation, decide whether to roll back" decomposes into focused nodes.
- **both** — the central case from "Where the Two Graphs Meet." "Diagnose
  why checkout is slow and correlate the evidence" is a horizontal workflow
  whose reasoning/retrieval nodes traverse the vertical graph for the dependency
  chain, then write the result back (a new `CAUSED_BY` edge). The architecture's
  value emerges at this intersection.
- **unroutable** — no signal for either graph; ask rather than guess (the
  chapter's ambiguous-situation discipline).

## When to Use

- An agent receives an on-call request and must decide: lookup or process?
- You are wiring the top of a harness and need a deterministic first-hop router
- Auditing a set of historical requests to see how the workload splits across
  the two graphs

Phrases that should invoke this skill: "route this request", "is this a lookup
or an action", "vertical or horizontal graph", "which graph handles this",
"where the two graphs meet".

## When NOT to Use

- **Building the workflow DAG.** Once a request routes to `horizontal`/`both`,
  decomposition into constrained nodes is `harness-node-splitter`; scheduling
  the nodes into parallel phases is `investigation-dag-planner` (Ch5).
- **Choosing a graph data model.** Property graph vs RDF vs hypergraph is
  `graph-model-selector` (Ch3), a different decision.
- **Fixed pipelines.** If the request always runs the same hardcoded steps,
  there is nothing to route.
- **Retrieving the actual facts.** This picks the STRUCTURE; it does not run the
  traversal or execute the workflow.

## Process

| Step | Input | Action | Output | Verification |
|------|-------|--------|--------|--------------|
| 1 | request string | `lib.route(request)` | `RouteDecision` (target, scores, matched signals, rationale, node_hint) | target in {vertical, horizontal, both, unroutable}; scores are non-negative ints |
| 2 | a `both` decision | `lib.explain_meeting_point(decision)` | dict of workflow_role / knowledge_role / forward_flow / backward_flow | non-empty only when target == `both`; empty otherwise |
| 3 | list of requests | `lib.route_batch(requests)` | list of `RouteDecision` | one decision per request; order preserved |
| 4 | routed target | (your harness) builds the vertical traversal, the horizontal DAG, or both | structure ready to execute | `both` builds a workflow whose retrieval node queries the vertical graph |

## Rationalizations

| Agent rationalization | Documented rebuttal |
|------------------------|--------------------|
| "Everything is a workflow — just always build a horizontal graph." | A single relationship/temporal lookup ("which services depend on payments-db") is one traversal. Wrapping it in a workflow adds nodes, latency, and failure surface for a question the vertical graph answers directly (Example 2-1). |
| "Everything is knowledge — just query the graph." | "A knowledge graph alone does not tell the agent how to use that knowledge." A diagnosis is a process: classify, retrieve, correlate, report. That is the horizontal graph's job. |
| "The `both` case is just horizontal — the KG query is only a detail." | The chapter names the intersection as where the architecture earns its keep. Collapsing `both` into `horizontal` loses the bidirectional contract: the workflow drives, the knowledge graph supplies AND receives (the `CAUSED_BY` write-back). Model it as `both`. |
| "If unsure, pick the more powerful option (horizontal)." | An unroutable request is ambiguous by construction. Guessing horizontal builds a workflow with no defined goal. The chapter's discipline is to resolve ambiguity by asking, not by defaulting. |
| "Keyword scoring is too crude for real routing." | Correct for production — swap `_score` for an LLM/intent classifier at the documented seam. The routing CONTRACT (vertical/horizontal/both/unroutable + rationale) is stable; the spike validates the contract, not the classifier. |

## Red Flags

- **Every request routes to `horizontal`.** The vertical-signal set is not
  matching real lookups — you are wrapping single traversals in workflows.
- **Every request routes to `both`.** The signal sets overlap too much, or the
  requests genuinely always mix — verify against a labeled sample before trusting.
- **`unroutable` on a clearly-actionable request.** The horizontal-signal set is
  too narrow for your domain vocabulary; extend it (or swap to a classifier).
- **A `both` decision with an empty meeting-point explanation.** The
  `explain_meeting_point` contract is broken; the bidirectional interaction is
  the whole point of `both`.
- **CLI `--help` exits non-zero.** SKILL.md / CLI mismatch; the multi-harness
  invariant is broken.

## Non-Negotiable Verification

1. **Run the benchmark battery.**
   ```
   python cli.py benchmark
   ```
   All labeled sample requests must route to their expected target, and the
   four invariant checks (mixed→both, both→meeting-point, non-both→no
   meeting-point, empty→unroutable) must pass.

2. **Inspect a `both` route visually.**
   ```
   python cli.py route "diagnose why checkout depends on payments-db and is slow"
   ```
   Confirm the target is BOTH and the printed meeting-point names both the
   forward (workflow→knowledge query) and backward (knowledge←workflow write)
   flows.

3. **JSON output round-trips.**
   ```
   python cli.py route "list services that use stripe-python" --json | python -c "import json,sys; json.load(sys.stdin)"
   ```
   No exception means the CLI is harness-portable.

4. **Batch the labeled sample.**
   ```
   python cli.py batch
   ```
   Confirm the `ok` column is all `ok` — every labeled request matches its route.

## Security Posture

- **Prompt injection.** The request string is untrusted input. This skill only
  tokenizes it against a fixed signal vocabulary and returns a routing label; it
  never executes the request, calls a tool, or interpolates the string into a
  shell/graph query. A malicious request can at most mis-route itself.
- **Data exfiltration.** No network calls, no file writes outside the bundled
  `sample-requests.json` (read-only). The `--json` output goes to stdout; the
  caller owns downstream piping.
- **Privilege escalation.** No shell invocation, no eval, no dynamic import.
  The route label carries no capability — the harness that consumes it is
  responsible for authorizing the actual traversal or workflow (see
  `capability-authorization-gate`, Ch3).

## Source Attribution

Distilled from *Agentic GraphRAG* (O'Reilly, by Anthony Alcaraz and Sam Julien),
Chapter 2 — Agentic Graph Architecture Foundations:

- "The Dual-Graph Architecture" — vertical knowledge graph vs horizontal
  workflow graph; "the vertical graph is the map, the horizontal graph is the
  route."
- "The Vertical Knowledge Graph" — nodes/edges/properties, `DEPENDS_ON`
  traversal, temporal `since` metadata (Example 2-1, Example 2-2).
- "The Horizontal Workflow Graph" — reasoning/execution/decision/validation
  nodes (Example 2-3).
- "Where the Two Graphs Meet" — the workflow drives, the knowledge graph
  supplies and receives; the value emerges at the intersection.

This is the Inversion-pattern router at the top of the dual-graph harness:
downstream skills (`harness-node-splitter`, `investigation-dag-planner`) build
the structures it routes to.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [AnthonyAlcaraz](https://github.com/AnthonyAlcaraz)
- **Source:** [AnthonyAlcaraz/agentic-graph-rag-skills](https://github.com/AnthonyAlcaraz/agentic-graph-rag-skills)
- **License:** MIT
- **Homepage:** https://www.oreilly.com/library/view/agentic-graphrag/9798341623163/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-anthonyalcaraz-agentic-graph-rag-skills-dual-graph-router
- Seller: https://agentstack.voostack.com/s/anthonyalcaraz
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.