tools.hpp

Go to the documentation of this file.

// SPDX-License-Identifier: AGPL-3.0-only
// Copyright (c) 2026 ForestHub. All rights reserved.
// For commercial licensing, visit https://github.com/ForestHubAI/fh-sdk
 
#ifndef FORESTHUB_CORE_TOOLS_HPP
#define FORESTHUB_CORE_TOOLS_HPP

 
#include <cstdint>
#include <functional>
#include <memory>
#include <string>
#include <utility>
 
#include "foresthub/core/input.hpp"
#include "foresthub/util/json.hpp"
#include "foresthub/util/schema.hpp"
 
namespace foresthub {
namespace core {
 
using json = nlohmann::json;
 
// 1. Interfaces

enum class ToolType : uint8_t {
    kFunction,   
    kWebSearch,  
    kHandoff     
};

class Tool {
public:
    virtual ~Tool() = default;

    virtual std::string ToolName() const = 0;

    virtual ToolType GetToolType() const = 0;

    virtual void ToJson(json& j) const = 0;

    virtual bool IsExternal() const { return false; }
};

class InternalToolCall {
public:
    virtual ~InternalToolCall() = default;

    virtual std::string ToolName() const = 0;
};
 
// 2. Data Structures

class ToolCallRequest : public InputItem {
public:
    std::string call_id;    
    std::string name;       
    std::string arguments;  

    InputItemType GetItemType() const override { return InputItemType::kToolCall; }

    std::string ToString() const override { return "Function tool call: " + name + " with arguments " + arguments; }

    void ToJson(json& j) const override {
        j = json{{"callId", call_id}, {"name", name}};
        json args_json = json::parse(arguments, nullptr, false);
        if (!args_json.is_discarded()) {
            j["arguments"] = args_json;
        } else {
            j["arguments"] = arguments;
        }
    }
};

class ToolResult : public InputItem {
public:
    std::string call_id;  
    std::string name;     
    json output;          

    InputItemType GetItemType() const override { return InputItemType::kToolResult; }

    std::string ToString() const override {
        if (output.is_string()) {
            return "Function " + name + " returned: " + output.get<std::string>();
        }
        return "Function " + name + " returned: " + output.dump();
    }

    void ToJson(json& j) const override {
        j = json{{"callId", call_id}, {"name", name}};
        j["output"] = output;
    }
};
 
// 3. External Tools

class ExternalTool : public Tool {
public:
    virtual std::string ToolDescription() const = 0;

    virtual const json& ToolParameters() const = 0;

    bool IsExternal() const override { return true; }
};

class ExternalToolBase : public ExternalTool {
public:
    std::string name;         
    std::string description;  
    json parameters;          

    std::string ToolName() const override { return name; }
    std::string ToolDescription() const override { return description; }
    const json& ToolParameters() const override { return parameters; }

    void ToJson(json& j) const override {
        j = json{{"type", "external"}, {"name", name}, {"description", description}, {"parameters", parameters}};
    }
};

class FunctionTool : public ExternalToolBase {
public:
    std::function<json(const std::string&)>
        tool_call;  
    ToolType GetToolType() const override { return ToolType::kFunction; }
};
 
// 4. Factory Function

template <typename T, typename R>
std::shared_ptr<FunctionTool> NewFunctionTool(std::string name, std::string description, const json& schema,
                                              const std::function<R(T)>& handler) {
    auto tool = std::make_shared<FunctionTool>();
 
    tool->name = std::move(name);
    tool->description = std::move(description);
    tool->parameters = util::NormalizeSchema(schema);
 
    tool->tool_call = [handler, tool_name = tool->name](const std::string& raw_args) -> json {
        json j_args = json::parse(raw_args, nullptr, false);
        if (j_args.is_discarded()) {
            return json(std::string("Error: Tool arguments for " + tool_name + " were not valid JSON."));
        }
 
        T args = j_args.get<T>();
 
        R result = handler(args);
        return result;
    };
 
    return tool;
}
 
// 5. Internal Tools

class WebSearch : public Tool {
public:
    std::string ToolName() const override { return "web_search"; }
    ToolType GetToolType() const override { return ToolType::kWebSearch; }

    void ToJson(json& j) const override { j = json{{"type", "web_search"}}; }
};

class WebSearchToolCall : public InternalToolCall {
public:
    std::string query;  
    std::string ToolName() const override { return "web_search"; }
};
 
}  // namespace core
}  // namespace foresthub
 
#endif  // FORESTHUB_CORE_TOOLS_HPP