Abstract base class for all graph nodes. More...

#include <node.h>

Inheritance diagram for neograph::graph::GraphNode:

Public Member Functions
virtual std::string	get_name () const =0
	Get the node's unique name within the graph.

virtual asio::awaitable< NodeOutput >	run (NodeInput in)=0
	v0.4 unified dispatch entry — replaces the 8-virtual cross product over (sync/async) × (writes/full) × (stream/non-stream).

Detailed Description

Abstract base class for all graph nodes.

Nodes are the building blocks of the graph. Each node reads from the graph state and produces channel writes (and optionally Command or Send directives). Override execute() for basic nodes, or execute_full() to use Command/Send.

Thread safety

Node instances are owned by the GraphEngine and shared across all concurrent run() invocations on that engine — including runs with different thread_ids. Implementations MUST therefore be either stateless (the recommended default — derive everything from the GraphState argument) or fully self-synchronized. Storing per-run scratch data in a member variable will silently corrupt parallel runs.

Per-execution state belongs in the channels: read inputs from state.get(...) and emit outputs as ChannelWrites.

Definition at line 132 of file node.h.

Member Function Documentation

◆ get_name()

virtual std::string neograph::graph::GraphNode::get_name ( ) const

pure virtual

Get the node's unique name within the graph.

Returns: Node name string.

Implemented in neograph::a2a::A2ACallerNode, neograph::graph::LLMCallNode, neograph::graph::ToolDispatchNode, neograph::graph::IntentClassifierNode, and neograph::graph::SubgraphNode.

◆ run()

virtual asio::awaitable< NodeOutput > neograph::graph::GraphNode::run ( NodeInput in )

pure virtual

v0.4 unified dispatch entry — replaces the 8-virtual cross product over (sync/async) × (writes/full) × (stream/non-stream).

New nodes override THIS method. Read in.state for channel inputs, read in.ctx for per-run metadata (cancel token, deadline, current step, …), check in.stream_cb for an optional LLM_TOKEN sink, and return a NodeOutput (alias for NodeResult) populated with channel writes plus optional Command / Send directives.

Legacy nodes that override one of the 8 virtuals keep working unchanged: the default body of run() below forwards to execute_full_async / execute_full_stream_async, which preserves the existing default-fallback chain (and its ExecuteDefaultGuard recursion guard).

The engine (NodeExecutor::execute_node_with_retry_async) dispatches via this method as of PR 2. Sync-vs-async is no longer a user concern — return whatever your body needs to co_return (sync work: co_return execute(...); async work: co_return co_await provider->complete_async(...)).

class MyNode : public GraphNode {
    asio::awaitable<NodeOutput> run(const NodeInput& in) override {
        auto messages = in.state.get_messages();
        auto reply = co_await provider_->complete_async({...});
        NodeOutput out;
        out.writes.push_back({"messages", json::array({reply})});
        co_return out;
    }
    std::string get_name() const override { return "my_node"; }
};

See also: ROADMAP_v1.md "Execution plan" → PR 2; NodeInput and NodeOutput above.

Lifetime note: in is taken by value so the coroutine frame owns its own copy of the struct. The state / ctx references inside still point to objects on the engine's suspended-frame stack (which outlive the run by construction), but the struct itself is no longer a reference parameter. Coroutine-reference-parameter UAF (per feedback_async_bridge_required.md / the v0.2.0 RunConfig crash) does not apply.