result.h

Go to the documentation of this file.

 
#pragma once
 
#include <neograph/api.h>
#include <neograph/json.h>
#include <neograph/program/pending.h>
#include <neograph/types.h>
#include <core/native_archive.h>
 
#include <cstdint>
#include <exception>
#include <memory>
#include <optional>
#include <string>
#include <string_view>
#include <vector>
 
namespace neograph::program {
 
namespace detail {
class RunControl;
}
 
enum class ProgramTerminalStatus : std::uint8_t {
    Completed,
    Interrupted,
    Cancelled,
    BudgetExhausted,
    TimedOut,
    Failed,
    AmbiguousEffect,
    CheckpointIncompatible,
};
 
NEOGRAPH_PROGRAM_API std::string_view to_string(ProgramTerminalStatus status) noexcept;
NEOGRAPH_PROGRAM_API ProgramTerminalStatus
program_terminal_status_from_string(std::string_view value);
 
struct RunBudget {
    std::uint64_t wall_time_ms           = 0;
    std::uint64_t model_tokens           = 0;
    std::uint64_t monetary_microunits    = 0;
    std::uint32_t max_concurrency        = 0;
    std::uint64_t max_program_operations = 0;
    std::uint64_t max_core_steps         = 0;
    std::uint64_t max_dynamic_compiles   = 0;
    std::uint32_t max_child_depth = 0;
    std::uint64_t max_total_children = 0;
    std::optional<std::uint64_t> max_node_retries;
 
    bool operator==(const RunBudget&) const = default;
};
 
struct ProgramUsage {
    std::uint64_t wall_time_ms        = 0;
    std::uint64_t model_tokens        = 0;
    std::uint64_t monetary_microunits = 0;
    std::uint64_t program_operations  = 0;
    std::uint64_t core_steps          = 0;
    std::uint32_t peak_concurrency    = 0;
    std::uint64_t node_retries        = 0;
 
    bool operator==(const ProgramUsage&) const = default;
};
 
enum class ProgramMonetaryEvidence : std::uint8_t {
    Reported,
    Estimated,
    Held,
};
 
NEOGRAPH_PROGRAM_API std::string_view to_string(ProgramMonetaryEvidence evidence) noexcept;
NEOGRAPH_PROGRAM_API ProgramMonetaryEvidence
program_monetary_evidence_from_string(std::string_view value);
 
struct ProgramMonetaryRecord {
    std::string             call_id;
    std::string             operation_id;
    std::string             node;
    std::string             origin;
    std::string             model;
    ProgramMonetaryEvidence evidence = ProgramMonetaryEvidence::Estimated;
    std::uint64_t           microunits = 0;
    std::uint64_t           reserved_microunits = 0;
    std::string             basis;
    std::string             catalog_version;
    std::string             catalog_digest;
    bool                    conservative = false;
    bool                    may_undercount = false;
    bool                    replayed = false;
    std::string             reason;
    json                    pricing = json::object();
    std::optional<std::string> served_by;
 
    bool operator==(const ProgramMonetaryRecord&) const = default;
};
 
struct CoreCheckpointIdentity {
    std::string   core_name;
    std::string   core_generation_id;
    std::string   core_thread_id;
    std::string   checkpoint_id;
    std::uint32_t checkpoint_schema_version;
 
    bool operator==(const CoreCheckpointIdentity&) const = default;
};
 
struct ProgramFailure {
    std::string   code;
    std::string   message;
    std::string   operation_id;
    std::string   core_node;
    std::uint32_t attempts = 0;
    json          witness;
    sp::runtime::Result provider_outcome;
    std::exception_ptr provider_cause;
 
    bool operator==(const ProgramFailure& other) const {
        return code == other.code && message == other.message &&
            operation_id == other.operation_id && core_node == other.core_node &&
            attempts == other.attempts && witness == other.witness;
    }
};
 
struct ProgramInterrupt {
    std::string core_node;
    json        value;
    std::optional<ProgramPendingInput>  pending_input;
    std::optional<ProgramPendingEffect> pending_effect;
 
};
 
struct ProgramResultData {
    ProgramTerminalStatus                 status = ProgramTerminalStatus::Failed;
    std::string                           run_id;
    std::string                           program_version_id;
    std::string                           bundle_id;
    std::string                           operation_id = "root";
    std::uint64_t                         attempt      = 0;
    json                                  output       = json::object();
    ProgramUsage                          usage;
    RunBudget                             remaining_budget;
    std::optional<CoreCheckpointIdentity> checkpoint;
    std::optional<ProgramInterrupt>       interrupt;
    std::optional<ProgramFailure>         failure;
    std::vector<std::string>              execution_trace;
    std::optional<UsageAccumulator::AuthoritySnapshot> provider_budget_authority;
    std::vector<ProgramMonetaryRecord> monetary_records;
};
 
class NEOGRAPH_PROGRAM_API ProgramResult {
public:
    ProgramResult();
    static ProgramResult create(ProgramResultData data);
    static ProgramResult parse(std::string_view stored_bytes);
    std::string          serialize_canonical() const;
    const std::string&   id() const noexcept;
    ProgramTerminalStatus                 status() const noexcept;
    const std::string&                    run_id() const noexcept;
    const std::string&                    program_version_id() const noexcept;
    const std::string&                    bundle_id() const noexcept;
    const std::string&                    operation_id() const noexcept;
    std::uint64_t                         attempt() const noexcept;
    json                                  output() const;
    ProgramUsage                          usage() const noexcept;
    RunBudget                             remaining_budget() const noexcept;
    std::optional<CoreCheckpointIdentity> checkpoint() const;
    std::optional<ProgramInterrupt>       interrupt() const;
    std::optional<ProgramFailure>         failure() const;
    std::vector<std::string>              execution_trace() const;
    const std::optional<UsageAccumulator::AuthoritySnapshot>& provider_budget_authority() const noexcept;
    const std::vector<ProgramMonetaryRecord>& monetary_records() const noexcept;
 
private:
    using ConstructionData = ProgramResultData;
 
    struct Impl;
    explicit ProgramResult(ConstructionData data, bool persistable = true);
    ProgramResult restore_provider_failure(
        std::string_view owner_scope, const std::shared_ptr<sp::NativeArchive>& archive) const;
    static ProgramResult create_for_runtime(
        ConstructionData data, std::string_view owner_scope,
        const std::shared_ptr<sp::NativeArchive>& archive);
    std::shared_ptr<const Impl> impl_;
 
    friend class detail::RunControl;
};
 
}  // namespace neograph::program