Graph Engineering

Design the graph. Bound the retries. Validate the structure.

Graph Engineering is a Python toolkit and discipline for multi-step AI/agent systems as explicit graphs: nodes are steps, edges are transition conditions, state and checkpoints are first-class.

Standalone technology — not an extension of another product line.

Architecture

Full write-up: docs/architecture.md
Editable diagram (draw.io / diagrams.net): docs/diagrams/graph-engineering/architecture-overview.drawio

flowchart LR
  subgraph Authoring
    Eng[Engineer]
    Pat[Pattern catalog]
    Sk[Sketch / checklist]
  end

  subgraph Definition
    JSON[Graph JSON]
    Sch[(graph.schema.json)]
  end

  subgraph Core["Core library Python"]
    Parse[parse + SCHEMA]
    Val[validate V1-V9]
    Mmd[to_mermaid]
    Walk[walk skeleton]
  end

  subgraph Interfaces
    CLI[CLI]
    API[Python API]
  end

  Eng --> Pat --> JSON
  Eng --> Sk --> JSON
  JSON --> Parse --> Val
  Sch -.-> Parse
  Val --> Mmd
  Val --> Walk
  Val --> CLI
  Val --> API

Loading

Layer	Status
Docs / patterns / architecture diagram	Shipped
Define · SCHEMA · V1–V9 · Mermaid	Shipped
init from pattern	Shipped
walk structural runtime skeleton	Shipped (not agent execute)
Agent execute / resume / tools	Later

Stack

Piece	Choice
Language	Python 3.10+
Definition	Portable JSON (schemas/graph.schema.json)
Validate	SCHEMA + structural rules V1–V9
Visualize	Mermaid
Init	Scaffold from published pattern
Walk	Edge-following skeleton + intentional-cycle budget

Zero runtime dependencies for the core library.

Install (dev)

python -m pip install -e ".[dev]"

Quick start

# Architecture + patterns
python -m graph_engineering patterns

# Scaffold from a published pattern
python -m graph_engineering init research-verify-retry -o my-flow.json
python -m graph_engineering check my-flow.json

# Structural walk (branch with --via when needed)
python -m graph_engineering walk examples/research-verify-retry.json --via pass
python -m graph_engineering walk examples/classify-branch-synthesize.json --via type_code --via approved

# Validate / Mermaid
python -m graph_engineering validate path/to/graph.json
python -m graph_engineering visualize path/to/graph.json

python -m pytest
python scripts/check_structure.py

Library:

from graph_engineering import load_and_validate, to_mermaid, walk_graph, init_from_pattern

init_from_pattern("research-verify-retry", "my-flow.json")
result = load_and_validate("my-flow.json")
assert result.ok
print(to_mermaid(result.graph))
run = walk_graph(result.graph)  # or fixed_conditions_chooser([...])
assert run.ok

Repository map

src/graph_engineering/     Python package
docs/
  architecture.md          Architecture (Mermaid + links)
  diagrams/.../*.drawio    draw.io architecture (diagram-kit style)
  vocabulary.md, ...
schemas/graph.schema.json
examples/                  Pattern example graphs
fixtures/                  Unit-test graphs
patterns/                  Catalog + registry.json
templates/                 Sketch + migration notes
tests/
pyproject.toml

Patterns

id	Example
research-verify-retry	examples/research-verify-retry.json
classify-branch-synthesize	examples/classify-branch-synthesize.json

See patterns/README.md.

Docs

1. Architecture · draw.io
2. Vocabulary
3. Design checklist
4. Pattern picker
5. Graph definition
6. Validation rules

Non-goals (v0.3)

• Full agent execution (LLM tools, resume-from-checkpoint engine)
• Mandatory multi-agent framework
• No-code builders

walk only follows edges / budgets on a validated definition — it does not call models or tools.

License

MIT — see LICENSE.