client.hpp

Go to the documentation of this file.

// Copyright 2026 Aniket Kulkarni
// SPDX-License-Identifier: Apache-2.0
 
 
#pragma once
 
#include "neuralplus/export.hpp"
#include "neuralplus/session.hpp"
#include "neuralplus/tool.hpp"
#include "neuralplus/tracing.hpp"
#include "neuralplus/transport.hpp"
#include "neuralplus/types.hpp"
 
#include <functional>
#include <memory>
#include <mutex>
#include <string>
#include <unordered_map>
 
namespace neuralplus {
 
struct ClientOptions {
    Tools tools;
 
    Tracers tracers;
 
    std::shared_ptr<HttpTransport> transport;
 
    std::size_t max_model_rounds{8};
 
    bool parallel_tool_calls{true};
 
    std::size_t max_parallel_tool_calls{4};
 
    std::size_t max_tool_calls_per_generation{64};
 
    bool stop_on_tool_error{false};
 
    bool capture_trace_payloads{false};
};
 
class NEURALPLUS_API AIClient {
public:
    virtual ~AIClient();
 
    [[nodiscard]] const ModelDescriptor& model() const noexcept;
 
    AIResponse generate(Session& session,
                        const Message& input,
                        const GenerateOptions& options = {});
 
    AIResponse generate(Session& session,
                        const std::string& input,
                        const GenerateOptions& options = {});
 
    AIResponse generate(const Message& input,
                        const GenerateOptions& options = {});
 
    AIResponse generate(const std::string& input,
                        const GenerateOptions& options = {});
 
protected:
    AIClient(ModelDescriptor model, const ClientOptions& options = {});
 
    virtual AIResponse generate_once(const AIRequest& request) = 0;
 
    void trace(const TraceEvent& event) const noexcept;
 
private:
    struct ToolExecution;
    struct RegisteredTool {
        std::shared_ptr<Tool> implementation;
        ToolSpec spec;
    };
 
    [[nodiscard]] std::vector<ToolExecution>
    execute_tools(Session& session,
                  const std::string& run_id,
                  const std::vector<ToolCall>& calls) const;
 
    [[nodiscard]] ToolExecution
    execute_tool(Session& session,
                 const std::string& run_id,
                 const ToolCall& call) const;
 
    void validate_input(const Message& input) const;
 
    AIClient(const AIClient&) = delete;
    AIClient& operator=(const AIClient&) = delete;
 
    ModelDescriptor model_;
    ClientOptions options_;
    std::unordered_map<std::string, RegisteredTool> tools_;
    std::vector<ToolSpec> tool_specs_;
};
 
class NEURALPLUS_API FunctionAIClient final : public AIClient {
public:
    using Function = std::function<AIResponse(const AIRequest&)>;
 
    FunctionAIClient(ModelDescriptor model,
                     Function function,
                     const ClientOptions& options = {});
    ~FunctionAIClient() override;
 
private:
    FunctionAIClient(const FunctionAIClient&) = delete;
    FunctionAIClient& operator=(const FunctionAIClient&) = delete;
 
    AIResponse generate_once(const AIRequest& request) override;
 
    std::mutex mutex_;
    Function function_;
};
 
}  // namespace neuralplus