Graph engine type definitions: channels, edges, nodes, events, and control flow. More...

#include <neograph/api.h>
#include <neograph/graph/configuration_failure.h>
#include <neograph/provider.h>
#include <neograph/tool.h>
#include <neograph/tool_set.h>
#include <neograph/types.h>
#include <chrono>
#include <cstddef>
#include <cstdint>
#include <exception>
#include <functional>
#include <map>
#include <memory>
#include <optional>
#include <stdexcept>
#include <string>
#include <string_view>
#include <variant>
#include <vector>

Include dependency graph for types.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	neograph::graph::Channel
	A state channel that holds a reducer, lifecycle policy, and version. More...

struct	neograph::graph::ChannelWrite
	Output of a node: a write to a named channel. More...

struct	neograph::graph::ChannelWriteEvent
	Typed channel update event. More...

struct	neograph::graph::Command
	Combined routing override + state update. More...

struct	neograph::graph::ConditionalEdge
	A conditional edge with runtime routing based on state. More...

struct	neograph::graph::Edge
	A static edge connecting two nodes. More...

struct	neograph::graph::ErrorEvent
	Typed execution error event. `data` preserves retry diagnostics. More...

struct	neograph::graph::FailureVerdict
	The node failure classifier's verdict on any failure (see classify_failure). More...

struct	neograph::graph::GraphEvent
	An event emitted during graph execution for streaming. More...

struct	neograph::graph::InterruptEvent
	Typed HITL interrupt event. `data` remains available for custom metadata. More...

struct	neograph::graph::LlmTokenEvent
	Typed LLM token event. More...

class	neograph::graph::NodeAttemptTimeout
	A node attempt ran past its `attempt_timeout_ms` (#364). More...

struct	neograph::graph::NodeContext
	Dependency injection context passed to nodes during construction. More...

struct	neograph::graph::NodeEndEvent
	Typed view of a node-end event. `data` preserves extension fields. More...

class	neograph::graph::NodeExecutionError
	A node failure annotated by the executor with dispatch context. More...

struct	neograph::graph::NodeFailure
	The classified outcome of a failed node. More...

struct	neograph::graph::NodeFailureEffect
	One mediated Tool effect of a node attempt, as seen by the run's ToolEffectBroker. More...

class	neograph::graph::NodeFailureError
	Fail a node with an author code. More...

class	neograph::graph::NodeInterrupt
	Exception thrown from inside a node to trigger a dynamic breakpoint. More...

struct	neograph::graph::NodeResult
	Extended result returned by node execution. More...

struct	neograph::graph::NodeStartEvent
	Typed view of a node-start event. `data` preserves extension fields. More...

struct	neograph::graph::PendingInterrupt
	One NodeInterrupt of a paused super-step (#388). More...

struct	neograph::graph::RawGraphEvent
	Escape hatch for malformed input or payload shapes added by future versions. More...

class	neograph::graph::RemoteControlFailure
	A run control signal a remote peer reported for one call. More...

struct	neograph::graph::RetryPolicy
	Retry policy for node execution with exponential backoff. More...

struct	neograph::graph::RoutingEvent
	Routing decision emitted for StreamMode::DEBUG. More...

struct	neograph::graph::Send
	Dynamic fan-out request (map-reduce pattern). More...

struct	neograph::graph::SendDispatchEvent
	Dynamic Send batch emitted for StreamMode::DEBUG. More...

struct	neograph::graph::StateSnapshotEvent
	Full serialized state emitted for StreamMode::VALUES. More...

Typedefs
using	neograph::graph::ConditionFn = std::function< std::string(const GraphState &)>
	Condition function signature for conditional edge routing.

using	neograph::graph::FailureTextRedactor = std::function< std::string(const NodeFailure &failure)>
	Decides the free text a failure record may carry (#364).

using	neograph::graph::GraphStreamCallback = std::function< void(const GraphEvent &)>
	Callback for receiving graph execution events.

using	neograph::graph::ReducerFn = std::function< json(const json &current, const json &incoming)>
	Custom reducer function signature.

using	neograph::graph::TypedGraphStreamCallback = std::function< void(const TypedGraphEvent &)>
	Callback for the additive typed event view.

Enumerations
enum class	neograph::graph::ChannelPersistencePolicy : std::uint8_t { Checkpoint , Ephemeral }
	Whether a channel value is part of serialized checkpoints. More...

enum class	neograph::graph::ChannelRetentionPolicy : std::uint8_t { Unbounded , Latest , Bounded }
	Retention policy applied after a channel reducer produces a value. More...

enum class	neograph::graph::NodeFailureClass : std::uint8_t { Ordinary = 0 , Timeout = 1 , ProviderFailed = 2 , EffectCommitted = 3 , LogicError = 4 , ConfigError = 5 , SafetyBlocked = 6 , BudgetExhausted = 7 , EffectUncertain = 8 , Unknown = 9 , Interrupted = 10 , HookBlocked = 11 , Cancelled = 12 }
	What a node failure means for retry and for failure routing. More...

enum class	neograph::graph::NodeFailureKind : std::uint8_t { Exhausted , NonRetryable , EffectCommitted , Deadline , Ceiling , VisitLimit }
	Why the executor stopped trying a failed node. More...

enum class	neograph::graph::ReducerType { OVERWRITE , APPEND , CUSTOM }
	Strategy for merging values when writing to a channel. More...

enum class	neograph::graph::StreamMode : uint8_t { EVENTS = 0x01 , TOKENS = 0x02 , VALUES = 0x04 , UPDATES = 0x08 , DEBUG = 0x10 , ALL = 0xFF }
	Bitfield flags for selecting which events to stream during execution. More...

Functions
GraphStreamCallback	neograph::graph::adapt_typed_stream (TypedGraphStreamCallback callback)
	Adapt a typed callback to the existing GraphStreamCallback surface.

NEOGRAPH_API FailureVerdict	neograph::graph::classify_failure (const std::exception_ptr &error, const CancelToken *run_token=nullptr) noexcept
	Classify any failure the way the node retry loop and every tool path do: the most severe class found anywhere in its cause chain, with its stable code.

bool	neograph::graph::has_mode (StreamMode flags, StreamMode test)
	Check if a specific stream mode flag is set.

NEOGRAPH_API bool	neograph::graph::is_author_failure_code (std::string_view code) noexcept
	True for an author code: `[a-z][a-z0-9_]*(\.`

NEOGRAPH_API const char *	neograph::graph::node_failure_code (NodeFailureClass failure_class) noexcept
	The stable code of a class: "NG.TaskFailed", "NG.LogicError", ...

NEOGRAPH_API const NodeFailure *	neograph::graph::node_failure_of (const NodeExecutionError &error) noexcept
	The record the executor attached to `error`, or null when the executor's retry loop did not throw `error`.

NEOGRAPH_API std::optional< NodeFailure >	neograph::graph::node_failure_of (const std::exception_ptr &error)
	Same for a captured exception: empty unless it is such a NodeExecutionError.

NEOGRAPH_API bool	neograph::graph::node_failure_retryable (NodeFailureClass failure_class) noexcept
	Whether a failure of this class may be retried at all.

NEOGRAPH_API bool	neograph::graph::node_failure_routable (NodeFailureClass failure_class) noexcept
	Whether a failure of this class may be routed to a failure handler.

StreamMode	neograph::graph::operator& (StreamMode a, StreamMode b)
	Bitwise AND for StreamMode flags.

StreamMode	neograph::graph::operator\| (StreamMode a, StreamMode b)
	Bitwise OR for StreamMode flags.

NEOGRAPH_API const char *	neograph::graph::to_string (NodeFailureKind kind) noexcept
	"exhausted", "non_retryable", "effect_committed", "deadline", "ceiling", "visit_limit".

NEOGRAPH_API TypedGraphEvent	neograph::graph::to_typed_event (const GraphEvent &event)
	Convert the stable GraphEvent wire shape to an owning typed event.

Variables
constexpr const char *	neograph::graph::DEFAULT_ROUTE = "default"
	Reserved route key selected when an open/unspecified condition returns no exact match.

constexpr const char *	neograph::graph::END_NODE = "__end__"
	Special node name representing the graph exit point.

constexpr const char *	neograph::graph::kAbortedCode = "NG.Aborted"
	NG.Aborted: the code of a failure exit that declares none.

constexpr const char *	neograph::graph::kVisitLimitCode = "NG.VisitLimit"
	NG.VisitLimit: the code of a node activated once more than its max_visits.

constexpr const char *	neograph::graph::START_NODE = "__start__"
	Special node name representing the graph entry point.

Detailed Description

Graph engine type definitions: channels, edges, nodes, events, and control flow.

Contains all the foundational types used by the graph execution engine, including reducers, channels, edges, Send/Command control flow, retry policies, stream modes, and graph events.

Definition in file types.h.

Typedef Documentation

◆ ConditionFn

using neograph::graph::ConditionFn = typedef std::function<std::string(const GraphState&)>

Condition function signature for conditional edge routing.

Parameters

state The current graph state to evaluate.

Returns: A string key that is matched against ConditionalEdge::routes.

Definition at line 919 of file types.h.

◆ FailureTextRedactor

using neograph::graph::FailureTextRedactor = typedef std::function<std::string(const NodeFailure& failure)>

Decides the free text a failure record may carry (#364).

A node whose retry policy sets error_text: true asks for free text in the failure record its failure route writes. The text comes only from typed safe sources (NodeFailure::public_message: NodeFailureError, a Python exception's public_message attribute), never from what(). The host's redactor receives the whole record and returns the text to keep; an empty string keeps none, and without a redactor no text is written. The engine then strips C0, bidirectional, zero-width and tag characters and truncates the result to 512 bytes on a UTF-8 boundary. It runs on the executor, once per handled failure, possibly from parallel branches at the same time, so it must be thread-safe; a redactor that throws keeps no text.

Definition at line 592 of file types.h.

◆ GraphStreamCallback

using neograph::graph::GraphStreamCallback = typedef std::function<void(const GraphEvent&)>

Callback for receiving graph execution events.

Parameters

event The graph event to process.

Definition at line 881 of file types.h.

◆ ReducerFn

using neograph::graph::ReducerFn = typedef std::function<json(const json& current, const json& incoming)>

Custom reducer function signature.

Parameters

current	The current value in the channel.
incoming	The new value being written.

Returns: The merged result.

Definition at line 103 of file types.h.

Enumeration Type Documentation

◆ ChannelPersistencePolicy

enum class neograph::graph::ChannelPersistencePolicy : std::uint8_t

strong

Whether a channel value is part of serialized checkpoints.

Enumerator
Checkpoint	Include value and version in checkpoints.
Ephemeral	Omit value; checkpoint resume rejects written ephemeral state.

Definition at line 83 of file types.h.

◆ ChannelRetentionPolicy

enum class neograph::graph::ChannelRetentionPolicy : std::uint8_t

strong

Retention policy applied after a channel reducer produces a value.

Retention is independent from combination: a channel may append values while retaining only a bounded suffix, or overwrite a scalar without any retention work.

Enumerator
Unbounded	Keep the reducer result unchanged.
Latest	Keep the newest array element (as a one-element array).
Bounded	Keep at most `retention_limit` newest array elements.

Definition at line 74 of file types.h.

◆ NodeFailureClass

enum class neograph::graph::NodeFailureClass : std::uint8_t

strong

What a node failure means for retry and for failure routing.

One classifier decides it for every node failure and every tool failure ("Node failure contract" in the reference). It walks the whole cause chain (NodeExecutionError causes, std::nested_exception, subgraph failures) and the most severe class found anywhere wins. The values are ordered by that severity. The four least severe classes (Ordinary, Timeout, ProviderFailed, EffectCommitted) are routable; only Ordinary and Timeout are retried.

Enumerator
Ordinary	NG.TaskFailed, NG.SubgraphFailed or an author code. Retried unless the author marked it non-retryable. Routable.
Timeout	NG.Timeout: the attempt ran past its `attempt_timeout_ms`, was cancelled, and stopped (NodeAttemptTimeout). Retried. Routable.
ProviderFailed	NG.ProviderFailed: a transient provider failure (transport, timeout, server, overloaded, rate limited). Not retried, because the provider runtime owns provider retries. Routable.
EffectCommitted	NG.EffectCommitted: the attempt committed a non-idempotent effect, so running the node again could repeat it. Never retried. Routable, so a failure route can compensate the effects listed in NodeFailure::effects.
LogicError	NG.LogicError: std::logic_error, which includes integrity checks.
ConfigError	NG.ConfigError: configuration or misuse, including provider request, authentication and permission failures.
SafetyBlocked	NG.SafetyBlocked: a provider safety block.
BudgetExhausted	NG.BudgetExhausted: budget or quota exhaustion.
EffectUncertain	NG.EffectUncertain: an effect whose outcome is not known (ProviderOutcomeError, an unconfirmed Tool effect).
Unknown	NG.UnknownFailure: std::bad_alloc, an exception outside the known families, or a non-standard exception.
Interrupted	Run control: NodeInterrupt. Stops the run as before.
HookBlocked	Run control: HookBoundaryBlocked. Stops the run as before.
Cancelled	Run control: cancellation. Stops the run as before.

Definition at line 308 of file types.h.

◆ NodeFailureKind

enum class neograph::graph::NodeFailureKind : std::uint8_t

strong

Why the executor stopped trying a failed node.

Enumerator
Exhausted	Retryable, but every allowed attempt failed.
NonRetryable	The failure's class, the author's hint or the node's `non_retryable` codes rule out a retry.
EffectCommitted	The final attempt committed a non-idempotent effect.
Deadline	The backoff before the next attempt would cross the run's deadline (RunContext::deadline, a Program's wall-time budget).
Ceiling	The run-level retry ceiling (Program RunBudget::max_node_retries) was reached before a retry.
VisitLimit	The node was activated once more than its `max_visits`; it did not run (code NG.VisitLimit, 0 attempts).

Definition at line 347 of file types.h.

◆ ReducerType

enum class neograph::graph::ReducerType

strong

Strategy for merging values when writing to a channel.

Enumerator
OVERWRITE	Replace the current value entirely.
APPEND	Append to the current value (arrays are concatenated).
CUSTOM	Use a custom reducer function.

Definition at line 61 of file types.h.

◆ StreamMode

enum class neograph::graph::StreamMode : uint8_t

strong

Bitfield flags for selecting which events to stream during execution.

Combine with bitwise OR to select multiple event types:

StreamMode mode = StreamMode::EVENTS | StreamMode::TOKENS;

Enumerator
EVENTS	NODE_START, NODE_END, INTERRUPT, ERROR events.
TOKENS	LLM_TOKEN events (streaming tokens).
VALUES	Full state snapshot after each super-step.
UPDATES	Channel write deltas per node.
DEBUG	Internal debug info (retry attempts, routing decisions).
ALL	All event types.

Definition at line 690 of file types.h.

Function Documentation

◆ classify_failure()

NEOGRAPH_API FailureVerdict neograph::graph::classify_failure	(	const std::exception_ptr &	error,
		const CancelToken *	run_token = `nullptr`
	)

noexcept

Classify any failure the way the node retry loop and every tool path do: the most severe class found anywhere in its cause chain, with its stable code.

A run control signal is NG.Cancelled, NG.HookBlocked or NG.Interrupted. run_token only decides whether an aborted asio operation is cancellation. Protocol hosts report the code on the wire (reference, "Protocol failure mapping").

References neograph::graph::classify_failure().

Referenced by neograph::graph::classify_failure().

◆ has_mode()

bool neograph::graph::has_mode	(	StreamMode	flags,
		StreamMode	test
	)

inline

Check if a specific stream mode flag is set.

Parameters

flags	The combined StreamMode bitfield.
test	The flag to test for.

Returns: True if the flag is set.

Definition at line 717 of file types.h.

References neograph::graph::has_mode().

Referenced by neograph::graph::has_mode().

◆ is_author_failure_code()

NEOGRAPH_API bool neograph::graph::is_author_failure_code ( std::string_view code )

noexcept

True for an author code: [a-z][a-z0-9_]*(\.

[a-z0-9_]+)+, at most 128 bytes. The NG. prefix is reserved and never matches.

◆ operator&()

StreamMode neograph::graph::operator&	(	StreamMode	a,
		StreamMode	b
	)

inline

Bitwise AND for StreamMode flags.

Parameters

a	Left operand.
b	Right operand.

Returns: Intersection of StreamMode flags.

Definition at line 710 of file types.h.

References neograph::graph::operator&().

Referenced by neograph::graph::operator&().

◆ operator|()

StreamMode neograph::graph::operator\|	(	StreamMode	a,
		StreamMode	b
	)

inline

Bitwise OR for StreamMode flags.

Parameters

a	Left operand.
b	Right operand.

Returns: Combined StreamMode flags.

Definition at line 703 of file types.h.

References neograph::graph::operator|().

Referenced by neograph::graph::operator|().

◆ to_typed_event()

NEOGRAPH_API TypedGraphEvent neograph::graph::to_typed_event ( const GraphEvent & event )

Convert the stable GraphEvent wire shape to an owning typed event.

Existing JSON and callback contracts remain canonical. Sentinel debug events (__state__, __routing__, and __send__) receive dedicated alternatives; malformed or unknown payloads are returned as RawGraphEvent instead of throwing from a streaming callback.

References neograph::graph::to_typed_event().

Referenced by neograph::graph::adapt_typed_stream(), and neograph::graph::to_typed_event().

Variable Documentation

◆ DEFAULT_ROUTE

constexpr const char* neograph::graph::DEFAULT_ROUTE = "default"

constexpr

Reserved route key selected when an open/unspecified condition returns no exact match.

Omitting it makes an unknown label a runtime error.

Definition at line 743 of file types.h.

Classes

Typedefs

Enumerations

Functions

Variables

Detailed Description

Typedef Documentation

◆ ConditionFn

◆ FailureTextRedactor

◆ GraphStreamCallback

◆ ReducerFn

Enumeration Type Documentation

◆ ChannelPersistencePolicy

◆ ChannelRetentionPolicy

◆ NodeFailureClass

◆ NodeFailureKind

◆ ReducerType

◆ StreamMode

Function Documentation

◆ classify_failure()

◆ has_mode()

◆ is_author_failure_code()

◆ operator&()

◆ operator|()

◆ to_typed_event()

Variable Documentation

◆ DEFAULT_ROUTE