The Graph Engine¶
Graphinate decouples graph traversal and event generation (GraphEngine) from graph storage and representation (GraphObserver implementations such as NetworkxBuilder).
Architecture Overview¶
When a GraphModel is executed, GraphEngine:
- Compiles an immutable, validated copy of the
GraphModel. - Notifies all subscribed observers via
on_start(name). - Traverses root and hierarchical
@model.nodegenerators, resolvingParentIddependencies and lineage tuples, and emitsNodeEvent(and hierarchicalEdgeEvent) instances. - Evaluates
@model.edgegenerators and emitsEdgeEventinstances. - Notifies all subscribed observers via
on_finish().
flowchart LR
M["GraphModel"] -->|compile| E["GraphEngine"]
E -->|NodeEvent / EdgeEvent| O1["NetworkxBuilder"]
E -->|NodeEvent / EdgeEvent| O2["Custom GraphObserver"]
Subscribing Custom Observers¶
You can implement the GraphObserver protocol to stream graph generation events to logs, progress bars, databases, or message queues without waiting for an in-memory graph to finish building:
Event Contracts¶
NodeEvent: Immutable dataclass carryingnode_id,type,label,value,magnitude,lineage,multiplicity, andcreated.EdgeEvent: Immutable dataclass carryingsource_id,target_id,type,label,value,weight,is_hierarchy, andcreated.
Asynchronous Execution (async def)¶
@model.node and @model.edge support asynchronous generator functions (async def ... yield) as well as coroutine functions (async def ... return [...]). You can mix synchronous and asynchronous generators freely within the same GraphModel and execute them with await engine.arun(...) or await builder.abuild(...) (or await graphinate.abuild(BuilderCls, model)):
Performance & Benchmarks
In pure in-memory scenarios, synchronous builds achieve the lowest overhead by avoiding coroutine frame
allocation. In I/O-bound pipelines (fetching from microservices, APIs, or databases), asynchronous builds with
abuild() enable concurrent execution via asyncio.gather(), achieving multi-fold speedups.
See Performance Optimization for benchmarks.