harness.h

Go to the documentation of this file.

 
#pragma once
 
#include <neograph/api.h>
#include <neograph/graph/cancel.h>
#include <neograph/json.h>
#include <neograph/mcp/harness_program_translator.h>
#include <neograph/program/catalog.h>
#include <neograph/program/compiler.h>
#include <neograph/program/runtime.h>
#include <neograph/program/store.h>
#include <neograph/graph/store.h>
#include <neograph/types.h>
#include <neograph/tool_set.h>
 
#include <atomic>
#include <chrono>
#include <cstddef>
#include <functional>
#include <cstdint>
#include <limits>
#include <memory>
#include <map>
#include <optional>
#include <string>
#include <utility>
#include <vector>
 
namespace sp { class NativeArchive; }
 
namespace neograph {
class Provider;
namespace program {
class ProgramRuntime;
}
}
 
namespace neograph::mcp {
 
class MCPServer;
 
enum class HarnessWorkerResponseKind {
    VALUE,
    EMPTY,
    PARSE_ERROR,
    TOOL_ERROR,
    TIMEOUT,
    CANCELLED,
    AWAITING_TOOL_RESULTS,
    INPUT_REQUIRED,
};
 
struct HarnessWorkerCall {
    json task;
    json worker;
    json tool_catalog;
    json policy;
    std::size_t attempt = 1;
    std::string repair_feedback;
    std::optional<json> resume_value;
    std::string run_id;
    std::shared_ptr<UsageAccumulator> usage;
    std::uint64_t                     model_token_budget = 0;
    std::shared_ptr<std::atomic_bool> budget_exhausted;
};
 
struct NEOGRAPH_HARNESS_API HarnessWorkerResponse {
    HarnessWorkerResponseKind kind = HarnessWorkerResponseKind::VALUE;
    json value;
    std::string message;
    bool provider_effect_uncertain = false;
 
    static HarnessWorkerResponse success(json value);
    static HarnessWorkerResponse empty(std::string message = {});
    static HarnessWorkerResponse parse_error(std::string message);
    static HarnessWorkerResponse tool_error(std::string message);
    static HarnessWorkerResponse timeout(std::string message = {});
    static HarnessWorkerResponse cancelled(std::string message = {});
    static HarnessWorkerResponse awaiting_tool_results(json pending);
    static HarnessWorkerResponse input_required(json pending);
};
 
using HarnessWorkerExecutor = std::function<HarnessWorkerResponse(
    const HarnessWorkerCall&, const std::shared_ptr<graph::CancelToken>&)>;
 
using HarnessCapabilityExecutor = std::function<json(const json& tool_definition,
                                                     const json& arguments,
                                                     const std::shared_ptr<graph::CancelToken>&)>;
 
struct HarnessProviderExecutorConfig {
    std::shared_ptr<Provider> provider;
    std::string model;
    HarnessCapabilityExecutor capability_executor;
    std::size_t max_tool_rounds = 8;
    std::shared_ptr<sp::NativeArchive> native_archive;
};
 
NEOGRAPH_HARNESS_API HarnessWorkerExecutor
make_provider_harness_executor(HarnessProviderExecutorConfig config);
 
class NEOGRAPH_HARNESS_API HarnessJournal {
public:
    virtual ~HarnessJournal() = default;
 
    virtual void append_event(const json& event) = 0;
    virtual std::vector<json> list_events(const std::string& run_id,
                                          std::size_t        after_sequence = 0,
                                          std::size_t        limit = 1000) = 0;
};
 
class NEOGRAPH_HARNESS_API HarnessRecordStore {
public:
    virtual ~HarnessRecordStore() = default;
 
    virtual void save_artifact(const std::string& artifact_id, const json& record)      = 0;
    virtual std::optional<json> load_artifact(const std::string& artifact_id)           = 0;
    virtual void                save_run(const std::string& run_id, const json& record) = 0;
    virtual std::optional<json> load_run(const std::string& run_id)                     = 0;
};
 
struct HarnessRetentionPolicy {
    std::size_t              max_artifacts = std::numeric_limits<std::size_t>::max();
    std::size_t              max_runs      = std::numeric_limits<std::size_t>::max();
    std::vector<std::string> protected_artifact_ids;
    std::vector<std::string> protected_run_ids;
    std::string namespace_prefix;
};
 
struct HarnessRetentionResult {
    std::vector<std::string> artifact_ids;
    std::vector<std::string> run_ids;
};
 
class NEOGRAPH_HARNESS_API HarnessRetentionStore {
public:
    virtual ~HarnessRetentionStore()                                                      = default;
    virtual HarnessRetentionResult cleanup_retained(const HarnessRetentionPolicy& policy) = 0;
};
 
class NEOGRAPH_HARNESS_API FileHarnessRecordStore final : public HarnessRecordStore {
public:
    explicit FileHarnessRecordStore(std::string root_directory);
    ~FileHarnessRecordStore() override;
 
    void                save_artifact(const std::string& artifact_id, const json& record) override;
    std::optional<json> load_artifact(const std::string& artifact_id) override;
    void                save_run(const std::string& run_id, const json& record) override;
    std::optional<json> load_run(const std::string& run_id) override;
 
private:
    struct Impl;
    std::unique_ptr<Impl> impl_;
};
 
struct HarnessServiceResources;
 
struct HarnessProgramHostConfig {
    HarnessWorkerExecutor                    worker_executor;
    HarnessCapabilityExecutor                capability_executor;
    HarnessProgramSnapshotConfig             snapshots;
    std::shared_ptr<graph::CheckpointStore>  checkpoints;
    std::shared_ptr<graph::Store>            state_store;
    std::shared_ptr<program::EngineGenerationCache> engines;
    std::string                              compiler_build_id;
    std::string                              provider_binding_identity;
    json                                     provider_host_configuration = json::object();
    std::map<std::string, std::string>       tool_binding_identities;
    std::size_t                              scheduler_threads = 1;
};
 
NEOGRAPH_HARNESS_API HarnessServiceResources
make_harness_program_service_resources(HarnessProgramHostConfig config);
 
using HarnessProgramCatalogFactory = std::function<std::shared_ptr<program::ProgramCatalog>(
    std::shared_ptr<program::ProgramStore>,
    const HarnessCapabilityBindingRequest&)>;
 
using HarnessProgramRuntimeFactory = std::function<std::shared_ptr<program::ProgramRuntime>(
    std::shared_ptr<program::ProgramCatalog>,
    std::shared_ptr<program::ProgramTransitionStore>)>;
using HarnessRecordedBindingFactory = std::function<program::RecordedBindingSet(
    const program::ProgramVersion&,
    const HarnessCapabilityBindingRequest&,
    const std::vector<program::ProgramEvent>&)>;
 
struct HarnessServiceResources {
    HarnessProgramSnapshots                   snapshots;
    std::shared_ptr<program::ProgramCompiler> compiler;
    HarnessProgramCatalogFactory              make_program_catalog;
    HarnessProgramRuntimeFactory              make_program_runtime;
    HarnessRecordedBindingFactory             make_recorded_binding;
    std::string                               owner_scope;
    std::string                               artifact_binding_identity;
};
 
struct HarnessServiceConfig {
    std::shared_ptr<HarnessRecordStore> record_store;
    HarnessTranslationDefaults          translation_defaults;
    std::size_t                         max_artifacts = 128;
    std::size_t                         max_runs = 128;
    std::chrono::milliseconds           poll_interval{1000};
    std::chrono::milliseconds           run_ttl{std::chrono::hours(24)};
    bool                                enable_experimental_tasks = false;
};
 
class NEOGRAPH_HARNESS_API HarnessService {
public:
    HarnessService(HarnessServiceConfig             config,
                   std::shared_ptr<HarnessJournal>  journal,
                   HarnessServiceResources          resources);
    ~HarnessService();
 
    HarnessService(const HarnessService&) = delete;
    HarnessService& operator=(const HarnessService&) = delete;
 
    void register_tools(MCPServer& server);
 
    json schema() const;
 
    json compile(const json& request);
 
    json start(const json& arguments);
 
    json resume(const json& arguments);
 
    json get(const std::string& run_id, const std::string& view = "status") const;
 
    json get(const std::string& run_id,
             const std::string& view,
             std::size_t        after_sequence,
             std::size_t        limit) const;
 
    json read(const std::string& uri) const;
 
    bool cancel(const std::string& run_id);
 
private:
    struct Impl;
    std::shared_ptr<Impl> impl_;
};
 
} // namespace neograph::mcp