Graph SDK Builder Contract

The builder is deliberately thin: every method assembles the same GraphDefinition dataclasses the canvas emits and the JSON stores, and run() hands them to the same GraphExecutor the Play button drives — the SDK adds no execution machinery. Its hard promise is identity: a graph built in code, drawn on the canvas, or loaded from JSON is indistinguishable to the engine, and to_code() closes the loop by regenerating a builder script from any of them. This page specifies the assembly rules; engine semantics stay with their owners — graph-executor, loop-control-system, batch-eval. Feature-level tour: capability page #10.

1. What it does

Three object kinds do all the work. Graph owns a private GraphDefinition and mutates it; g.add(…) returns a NodeHandle (a node id plus port accessors); handle.out("port") / handle.in_("port") return PortRefs, and g.connect(src, dst) turns a PortRef pair into an EdgeDef. Nothing is deferred or symbolic — after every call the underlying dataclasses are complete, so g.to_dict() at any moment is valid canvas JSON, and Graph.from_definition(gd) re-wraps any existing graph for further editing.

The smallest build

g = Graph(name="demo")
a = g.add("demo_seven", id="a", x=7)     # kwargs → NodeDef.config
o = g.graph_out("r")                     # boundary node; port name = output key
g.connect(a.out("y"), o.in_("value"))    # PortRef pair → EdgeDef
print(g.run()["r"])                      # check → executor → RunResult

2. Assembly rules

Each builder call maps to one dataclass mutation — the full table (graph_sdk.py · Graph):

3. loop() — what the sugar actually sets

The loop helper exists because the raw iterIn/iterOut flags are a known foot-gun; it writes them so you don't. g.loop(init=…, carry=…) (graph_sdk.py · Graph.loop) adds the paired iterIn/iterOut nodes and returns a Loop handle whose methods wire both sides at once:

• init ports are seed-only: fed once at run start, persisted unchanged across every step — the helper sets the persist flag that, when forgotten by hand, starves the port from iteration 1 onward.
• carry ports are written back each step by iterOut and re-entered on the next: seeded on step 0, then the carry supersedes — the init side deliberately does not persist, so a stale seed can never shadow a fresh carry.
• loop.seed(name, ref) wires the run-start value, loop.feed(name, ref) wires both the init and carry entry sides to a consumer, loop.carry(name, ref) wires the per-step write-back, loop.stop(ref) wires the termination signal.

Step semantics — what fires when, budget, termination — are the engine's, specified in loop-control-system; this page only owes you what the builder writes into the definition.

4. Two-level checking

Every run() / eval() is checked by default; the checks differ in depth, and both fail before anything executes.

5. Typed authoring — stubs are frozen catalog output

agentcanvas.nodes is the workspace catalog, compiled to importable symbols. generate_node_stubs() runs the same spawn-free scan as catalog() / describe() / nodesets() and emits one NodeProxy subclass per node type into agentcanvas/nodes/. g.add() accepts either form — the registered string key, or any class carrying a node_type attribute (graph_sdk.py · Graph.add); passing a NodeProxy subclass additionally returns a typed handle whose out/in_ autocomplete the port names. The two forms produce identical NodeDefs. Being generated files, the stubs are a snapshot: they go stale when workspace nodesets change ports, until regenerated — staleness shows up as the resolution check disagreeing with the stub's port list.

6. on_event — where the events come from

The executor already dispatched every lifecycle moment to shell hooks; on_event surfaces the same moments as Python objects. GraphExecutor.__init__ takes an on_event callback; graph_executor.py · _emit builds a plain event dict, awaits the callback if it returns an awaitable, and swallows callback exceptions with a warning — an observer can never kill a run. Emission points: graph_start after the GraphStart hook, node_start in _fire_node once inputs are resolved, terminal node_finish/node_error with duration_ms, and graph_complete/graph_error at run end. The SDK wraps the user callback so it receives a typed RunEvent (graph_sdk.py · RunEvent._from_dict — unknown keys filtered, so executor-side additions never break callers). Two contract points: the callback runs inside the executor's event loop (keep it cheap), and inputs/outputs on node events are the live engine dicts, not copies — read, don't mutate.

7. to_code — the round trip

graph_to_code(gd) / Graph.to_code() (graph_sdk_codegen.py) compiles any GraphDefinition — canvas-authored, JSON-loaded, or code-built — into a standalone script that rebuilds the same topology through this builder API. The round trip is semantically exact: node types + configs, the wire multiset, containers, grants, and hooks survive; cosmetic properties (canvas layout positions) do not. Verified against the reference MapGPT-MP3D graph.

8. Where it deviates from the mental model

9. Key files