types.h

Go to the documentation of this file.

 
#pragma once
 
#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>
 
// Windows SDK (pulled in transitively via asio on Win32) defines a
// bunch of ALL-CAPS macros — notably ERROR (wingdi.h) and DEBUG —
// that silently clobber enumerator names. `enum class Type { ERROR }`
// below becomes `enum class Type { 0 }` and every downstream parse
// collapses. Scrub the ones we actually use before declaring the
// enums. No-op outside of Windows.
#ifdef _WIN32
#  ifdef ERROR
#    undef ERROR
#  endif
#  ifdef DEBUG
#    undef DEBUG
#  endif
#  ifdef IN
#    undef IN
#  endif
#  ifdef OUT
#    undef OUT
#  endif
#endif
 
namespace neograph::graph {
 
// Forward declaration
class GraphState;
 
enum class ReducerType {
    OVERWRITE,  
    APPEND,     
    CUSTOM      
};
 
enum class ChannelRetentionPolicy : std::uint8_t {
    Unbounded,  
    Latest,     
    Bounded,    
};
 
enum class ChannelPersistencePolicy : std::uint8_t {
    Checkpoint, 
    Ephemeral,   
};
 
struct ChannelLifecyclePolicy {
    ChannelRetentionPolicy    retention = ChannelRetentionPolicy::Unbounded;
    std::uint64_t              retention_limit = 0;
    ChannelPersistencePolicy  persistence = ChannelPersistencePolicy::Checkpoint;
 
    bool operator==(const ChannelLifecyclePolicy&) const = default;
};
 
 
using ReducerFn = std::function<json(const json& current, const json& incoming)>;
 
struct Channel {
    std::string              name;  
    ReducerType              reducer_type = ReducerType::OVERWRITE; 
    ReducerFn                reducer; 
    ChannelLifecyclePolicy   lifecycle; 
    json                     value; 
    uint64_t                 version = 0;
};
 
struct ChannelWrite {
    enum class Mode {
        Reduce,
        Overwrite,
    };
 
    std::string channel;              
    json        value;                
    Mode        mode = Mode::Reduce;  
    std::shared_ptr<const std::vector<sp::Message>> native_messages;
};
 
inline ChannelWrite provider_messages_write(std::vector<sp::Message> messages,
    ChannelWrite::Mode mode = ChannelWrite::Mode::Reduce) {
    json projection = json::array();
    for (const auto& message : messages) {
        json item;
        to_json(item, project_message(message));
        projection.push_back(std::move(item));
    }
    return ChannelWrite{"messages", std::move(projection), mode,
        std::make_shared<const std::vector<sp::Message>>(std::move(messages))};
}
 
inline ChannelWrite provider_messages_write(const sp::runtime::Result& outcome,
    ChannelWrite::Mode mode = ChannelWrite::Mode::Reduce) {
    if (!outcome) throw std::invalid_argument("Provider returned no owned outcome");
    const auto& messages = outcome_messages(*outcome);
    json projection = json::array();
    for (const auto& message : messages) {
        json item;
        to_json(item, project_message(message));
        projection.push_back(std::move(item));
    }
    return ChannelWrite{"messages", std::move(projection), mode,
        std::shared_ptr<const std::vector<sp::Message>>(outcome, &messages)};
}
 
class NEOGRAPH_API NodeInterrupt : public std::runtime_error {
public:
    explicit NodeInterrupt(const std::string& reason)
        : std::runtime_error(reason), reason_(reason) {}
 
    NodeInterrupt(const std::string& reason, json value)
        : std::runtime_error(reason), reason_(reason),
          value_(std::move(value)) {}
 
    const std::string& reason() const { return reason_; }
 
    const json& value() const { return value_; }
 
    const std::string& node() const { return node_; }
 
    void set_node(std::string node) { node_ = std::move(node); }
 
private:
    std::string reason_;
    json        value_;
    std::string node_;
};
 
struct PendingInterrupt {
    std::string id;
    std::string node;  
    json value;
 
    bool operator==(const PendingInterrupt&) const = default;
};
 
class NEOGRAPH_API NodeExecutionError : public std::runtime_error {
public:
    NodeExecutionError(std::string node_name, int attempts,
                       std::exception_ptr cause)
        : std::runtime_error(make_message(node_name, attempts, cause)),
          node_name_(std::move(node_name)), attempts_(attempts),
          cause_(std::move(cause)) {}
 
    const std::string& node_name() const noexcept { return node_name_; }
    int attempts() const noexcept { return attempts_; }
    const std::exception_ptr& cause() const noexcept { return cause_; }
 
private:
    static std::string make_message(const std::string& node_name, int attempts,
                                    const std::exception_ptr& cause) {
        std::string detail = "unknown exception";
        try {
            if (cause) std::rethrow_exception(cause);
        } catch (const std::exception& e) {
            detail = e.what();
        } catch (...) {}
        return "Node '" + node_name + "' failed after "
            + std::to_string(attempts) + " attempt(s): " + detail;
    }
 
    std::string        node_name_;
    int                attempts_;
    std::exception_ptr cause_;
};
 
enum class 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,
};
 
enum class NodeFailureKind : std::uint8_t {
    Exhausted,        
    NonRetryable,
    EffectCommitted,  
    Deadline,
    Ceiling,
    VisitLimit,
};
 
struct FailureVerdict {
    NodeFailureClass failure_class = NodeFailureClass::Unknown;
    std::string code;
    std::string public_message;
    bool retryable = false;
    bool retryable_by_class = false;
    bool routable = false;
    std::exception_ptr signal;
};
 
class CancelToken;
 
NEOGRAPH_API FailureVerdict classify_failure(const std::exception_ptr& error,
                                             const CancelToken* run_token = nullptr) noexcept;
 
NEOGRAPH_API const char* node_failure_code(NodeFailureClass failure_class) noexcept;
NEOGRAPH_API bool node_failure_retryable(NodeFailureClass failure_class) noexcept;
NEOGRAPH_API bool node_failure_routable(NodeFailureClass failure_class) noexcept;
NEOGRAPH_API const char* to_string(NodeFailureKind kind) noexcept;
NEOGRAPH_API bool is_author_failure_code(std::string_view code) noexcept;
 
struct NodeFailureEffect {
    std::string   tool;
    std::uint64_t ordinal = 0;
    std::string   status;
    bool operator==(const NodeFailureEffect&) const = default;
};
 
struct NodeFailure {
    std::string node;
    std::string code;
    std::string public_message;
    NodeFailureClass failure_class = NodeFailureClass::Ordinary;
    NodeFailureKind kind = NodeFailureKind::NonRetryable;
    bool retryable = false;
    bool routable = false;
    int attempts = 0;
    std::vector<NodeFailureEffect> effects;
};
 
class NEOGRAPH_API NodeFailureError : public std::runtime_error {
public:
    explicit NodeFailureError(std::string code, std::string public_message = {},
                              std::optional<bool> retryable = std::nullopt)
        : NodeFailureError(what_of(code, public_message), code, public_message, retryable) {}
 
    const std::string& code() const noexcept { return code_; }
    const std::string& public_message() const noexcept { return public_message_; }
    std::optional<bool> retryable() const noexcept { return retryable_; }
 
protected:
    NodeFailureError(std::string what, std::string code, std::string public_message,
                     std::optional<bool> retryable)
        : std::runtime_error(std::move(what)), code_(std::move(code)),
          public_message_(std::move(public_message)), retryable_(retryable) {}
 
private:
    static std::string what_of(const std::string& code, const std::string& public_message) {
        if (!is_author_failure_code(code))
            throw std::invalid_argument(
                "NodeFailureError code must match [a-z][a-z0-9_]*(.[a-z0-9_]+)+ "
                "and must not use the reserved NG. prefix");
        return public_message.empty() ? code : code + ": " + public_message;
    }
 
    std::string         code_;
    std::string         public_message_;
    std::optional<bool> retryable_;
};
 
class NEOGRAPH_API RemoteControlFailure : public NodeFailureError {
public:
    RemoteControlFailure(const std::string& code, const std::string& public_message)
        : NodeFailureError(what_of(code, public_message), checked(code), public_message,
                           false) {}
 
private:
    static std::string checked(const std::string& code) {
        if (code != "NG.HookBlocked" && code != "NG.Interrupted")
            throw std::invalid_argument(
                "RemoteControlFailure code must be NG.HookBlocked or NG.Interrupted");
        return code;
    }
    static std::string what_of(const std::string& code, const std::string& public_message) {
        return public_message.empty() ? code : code + ": " + public_message;
    }
};
 
class NEOGRAPH_API NodeAttemptTimeout : public std::runtime_error {
public:
    NodeAttemptTimeout(std::string node, int attempt, std::chrono::milliseconds timeout,
                       bool stopped)
        : std::runtime_error(what_of(node, attempt, timeout, stopped)), node_(std::move(node)),
          attempt_(attempt), timeout_(timeout), stopped_(stopped) {}
 
    const std::string& node() const noexcept { return node_; }
    int attempt() const noexcept { return attempt_; }
    std::chrono::milliseconds timeout() const noexcept { return timeout_; }
    bool stopped() const noexcept { return stopped_; }
 
private:
    static std::string what_of(const std::string& node, int attempt,
                               std::chrono::milliseconds timeout, bool stopped) {
        auto text = "Node '" + node + "' attempt " + std::to_string(attempt + 1) +
                    " timed out after " + std::to_string(timeout.count()) + " ms";
        if (!stopped) text += " and did not stop by its stop deadline; its effects are uncertain";
        return text;
    }
 
    std::string               node_;
    int                       attempt_ = 0;
    std::chrono::milliseconds timeout_{0};
    bool                      stopped_ = true;
};
 
NEOGRAPH_API const NodeFailure* node_failure_of(const NodeExecutionError& error) noexcept;
NEOGRAPH_API std::optional<NodeFailure> node_failure_of(const std::exception_ptr& error);
 
using FailureTextRedactor = std::function<std::string(const NodeFailure& failure)>;
 
inline constexpr const char* kVisitLimitCode = "NG.VisitLimit";
inline constexpr const char* kAbortedCode = "NG.Aborted";
 
struct Send {
    std::string target_node;  
    json        input;        
    // Filled by GraphEngine when it collects a node's output. User-created
    // Sends leave this empty until they are returned from a node.
    std::string source_node;
};
 
struct Command {
    std::string                goto_node;  
    std::vector<ChannelWrite>  updates;    
};
 
struct RetryPolicy {
    int    max_retries      = 0;       
    int    initial_delay_ms = 100;     
    float  backoff_multiplier = 2.0f;  
    int    max_delay_ms     = 5000;    
    float  jitter_pct       = 0.0f;
};
 
enum class StreamMode : uint8_t {
    EVENTS   = 0x01,  
    TOKENS   = 0x02,  
    VALUES   = 0x04,  
    UPDATES  = 0x08,  
    DEBUG    = 0x10,  
    ALL      = 0xFF   
};
 
inline StreamMode operator|(StreamMode a, StreamMode b) {
    return static_cast<StreamMode>(static_cast<uint8_t>(a) | static_cast<uint8_t>(b));
}
inline StreamMode operator&(StreamMode a, StreamMode b) {
    return static_cast<StreamMode>(static_cast<uint8_t>(a) & static_cast<uint8_t>(b));
}
inline bool has_mode(StreamMode flags, StreamMode test) {
    return static_cast<uint8_t>(flags & test) != 0;
}
 
struct Edge {
    std::string from;  
    std::string to;    
};
 
struct ConditionalEdge {
    std::string from;                                
    std::string condition;                           
    std::map<std::string, std::string> routes;       
};
 
constexpr const char* DEFAULT_ROUTE = "default";
class GraphRegistry;
 
 
struct NodeContext {
    std::shared_ptr<Provider> provider;    
    ToolSet                   tools;
    std::string               model;       
    std::string               instructions; 
    json                      extra_config; 
    std::vector<ChatTool>    tool_definitions;
    std::string              provider_name;
    std::shared_ptr<const GraphRegistry> registry;
    ProviderControls provider_controls; 
};
 
struct GraphEvent {
    enum class Type {
        NODE_START,     
        NODE_END,       
        LLM_TOKEN,      
        CHANNEL_WRITE,  
        INTERRUPT,      
        ERROR           
    };
    Type        type;       
    std::string node_name;  
    json        data;       
};
 
struct NodeStartEvent {
    std::string        node_name;
    std::optional<int> retry_attempt;
    json               data;
};
 
struct NodeEndEvent {
    std::string                node_name;
    std::optional<std::string> command_goto;
    std::size_t                send_count = 0;
    json                       data;
};
 
struct LlmTokenEvent {
    std::string node_name;
    std::string token;
};
 
struct ChannelWriteEvent {
    std::string node_name;
    std::string channel;
    json        value;
};
 
struct StateSnapshotEvent {
    json state;
};
 
struct RoutingEvent {
    std::optional<std::string> command_goto;
    std::vector<std::string>   next_nodes;
    std::optional<int>         step;
    json                       data;
};
 
struct SendDispatchEvent {
    std::vector<Send> sends;
};
 
struct InterruptEvent {
    std::string                node_name;
    std::optional<std::string> phase;
    std::optional<std::string> checkpoint_id;
    json                       data;
};
 
struct ErrorEvent {
    std::string node_name;
    std::string message;
    json        data;
};
 
struct RawGraphEvent {
    GraphEvent event;
};
 
using TypedGraphEvent = std::variant<NodeStartEvent,
                                     NodeEndEvent,
                                     LlmTokenEvent,
                                     ChannelWriteEvent,
                                     StateSnapshotEvent,
                                     RoutingEvent,
                                     SendDispatchEvent,
                                     InterruptEvent,
                                     ErrorEvent,
                                     RawGraphEvent>;
 
NEOGRAPH_API TypedGraphEvent to_typed_event(const GraphEvent& event);
 
using GraphStreamCallback = std::function<void(const GraphEvent&)>;
 
using TypedGraphStreamCallback = std::function<void(const TypedGraphEvent&)>;
 
inline GraphStreamCallback adapt_typed_stream(TypedGraphStreamCallback callback) {
    if (!callback) return {};
    return [callback = std::move(callback)](const GraphEvent& event) {
        callback(to_typed_event(event));
    };
}
 
struct NodeResult {
    std::vector<ChannelWrite> writes;          
    std::optional<Command>    command;          
    std::vector<Send>         sends;           
 
    NodeResult() = default;
 
    NodeResult(std::vector<ChannelWrite> w) : writes(std::move(w)) {}
};
 
using ConditionFn = std::function<std::string(const GraphState&)>;
 
constexpr const char* START_NODE = "__start__";
constexpr const char* END_NODE   = "__end__";
 
} // namespace neograph::graph