types.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 <nlohmann/json.hpp>
 
#include <cstddef>
#include <cstdint>
#include <optional>
#include <stdexcept>
#include <string>
#include <utility>
#include <vector>
 
namespace neuralplus {
 
using JsonValue = nlohmann::json;
 
// Object defaults below intentionally use `= JsonValue::object()`.
// With nlohmann/json, `JsonValue{JsonValue::object()}` is a one-element array,
// not an empty object: []-style initializer-list construction wins.
 
enum class Provider {
    openai,
    anthropic,
    gemini,
    openai_compatible,
    custom,
};
 
enum class Role {
    system,
    user,
    assistant,
    tool,
};
 
enum class FinishReason {
    stop,
    tool_calls,
    length,
    content_filter,
    refusal,
    error,
    unknown,
};
 
enum class ContentType {
    text,
    image,
    audio,
    file,
    extension,
};
 
enum class ContentSource {
    value,
    url,
    bytes,
    provider_data,
};
 
class NEURALPLUS_API Content final {
public:
    [[nodiscard]] static Content text(std::string value);
 
    [[nodiscard]] static Content image_url(std::string url,
                                           std::string media_type = {},
                                           JsonValue options = JsonValue::object());
 
    [[nodiscard]] static Content image_bytes(std::vector<std::uint8_t> bytes,
                                             std::string media_type,
                                             JsonValue options = JsonValue::object());
 
    [[nodiscard]] static Content audio_url(std::string url,
                                           std::string media_type = {},
                                           JsonValue options = JsonValue::object());
 
    [[nodiscard]] static Content audio_bytes(std::vector<std::uint8_t> bytes,
                                             std::string media_type,
                                             JsonValue options = JsonValue::object());
 
    [[nodiscard]] static Content file_url(std::string url,
                                          std::string media_type = {},
                                          std::string filename = {},
                                          JsonValue options = JsonValue::object());
 
    [[nodiscard]] static Content file_bytes(std::vector<std::uint8_t> bytes,
                                            std::string media_type,
                                            std::string filename = {},
                                            JsonValue options = JsonValue::object());
 
    [[nodiscard]] static Content extension(std::string provider,
                                           JsonValue provider_data);
 
    [[nodiscard]] ContentType type() const noexcept;
 
    [[nodiscard]] ContentSource source() const noexcept;
 
    [[nodiscard]] const std::string& value() const noexcept;
 
    [[nodiscard]] const std::string& url() const noexcept;
 
    [[nodiscard]] const std::vector<std::uint8_t>& bytes() const noexcept;
 
    [[nodiscard]] const std::string& media_type() const noexcept;
 
    [[nodiscard]] const std::string& filename() const noexcept;
 
    [[nodiscard]] const std::string& provider() const noexcept;
 
    [[nodiscard]] const JsonValue& options() const noexcept;
 
    [[nodiscard]] const JsonValue& provider_data() const noexcept;
 
private:
    Content(ContentType type, ContentSource source);
 
    ContentType type_;
    ContentSource source_;
    std::string value_;
    std::string url_;
    std::vector<std::uint8_t> bytes_;
    std::string media_type_;
    std::string filename_;
    std::string provider_;
    JsonValue options_ = JsonValue::object();
    JsonValue provider_data_ = JsonValue::object();
};
 
struct ToolCall {
    std::string id;
 
    std::string name;
 
    JsonValue arguments = JsonValue::object();
 
    std::string raw_arguments{"{}"};
 
    bool arguments_valid{true};
 
    JsonValue provider_metadata = JsonValue::object();
};
 
struct ToolSpec {
    std::string name;
 
    std::string description;
 
    JsonValue input_schema =
        JsonValue{{"type", "object"}, {"properties", JsonValue::object()}};
 
    JsonValue provider_options = JsonValue::object();
};
 
class NEURALPLUS_API Message final {
public:
    using Contents = std::vector<Content>;
 
    [[nodiscard]] static Message system(std::string text);
 
    [[nodiscard]] static Message user(std::string text);
 
    [[nodiscard]] static Message user(Contents contents);
 
    [[nodiscard]] static Message assistant(std::string text,
                                           std::vector<ToolCall> tool_calls = {});
 
    [[nodiscard]] static Message assistant(Contents contents,
                                           std::vector<ToolCall> tool_calls = {});
 
    [[nodiscard]] static Message tool(std::string call_id,
                                      std::string tool_name,
                                      Contents contents,
                                      bool is_error = false);
 
    [[nodiscard]] static Message tool_json(std::string call_id,
                                           std::string tool_name,
                                           JsonValue value,
                                           bool is_error = false);
 
    [[nodiscard]] Role role() const noexcept;
 
    [[nodiscard]] const Contents& contents() const noexcept;
 
    [[nodiscard]] const std::vector<ToolCall>& tool_calls() const noexcept;
 
    [[nodiscard]] const std::string& tool_call_id() const noexcept;
 
    [[nodiscard]] const std::string& tool_name() const noexcept;
 
    [[nodiscard]] bool is_tool_error() const noexcept;
 
    [[nodiscard]] std::string text() const;
 
    [[nodiscard]] const JsonValue& provider_metadata() const noexcept;
 
    Message& set_provider_metadata(JsonValue metadata);
 
private:
    explicit Message(Role role);
 
    Role role_;
    Contents contents_;
    std::vector<ToolCall> tool_calls_;
    std::string tool_call_id_;
    std::string tool_name_;
    bool tool_error_{false};
    JsonValue provider_metadata_ = JsonValue::object();
};
 
struct ModelCapabilities {
    bool text_input{true};
 
    bool text_output{true};
 
    bool image_input{false};
 
    bool image_output{false};
 
    bool audio_input{false};
 
    bool audio_output{false};
 
    bool file_input{false};
 
    bool file_output{false};
 
    bool tools{false};
 
    bool parallel_tool_calls{false};
};
 
struct ModelDescriptor {
    Provider provider{Provider::custom};
 
    std::string id;
 
    std::string display_name;
 
    ModelCapabilities capabilities;
 
    std::size_t context_window{0};
 
    std::optional<std::size_t> max_output_tokens;
 
    JsonValue provider_options = JsonValue::object();
};
 
struct GenerateOptions {
    std::optional<double> temperature;
 
    std::optional<std::size_t> max_output_tokens;
 
    JsonValue provider_options = JsonValue::object();
};
 
struct TokenUsage {
    std::optional<std::size_t> input_tokens;
 
    std::optional<std::size_t> output_tokens;
 
    std::optional<std::size_t> total_tokens;
 
    std::optional<std::size_t> cached_input_tokens;
 
    std::optional<std::size_t> cache_creation_input_tokens;
 
    std::optional<std::size_t> reasoning_tokens;
};
 
struct AIRequest {
    std::string session_id;
 
    std::string run_id;
 
    std::optional<std::string> system_message;
 
    std::vector<Message> messages;
 
    std::vector<ToolSpec> tools;
 
    GenerateOptions options;
};
 
struct NEURALPLUS_API AIResponse {
    explicit AIResponse(Message message);
 
    Message message;
 
    FinishReason finish_reason{FinishReason::unknown};
 
    TokenUsage usage;
 
    std::string provider_request_id;
 
    std::string provider_model;
 
    std::size_t model_rounds{1};
 
    std::size_t tool_calls{0};
 
    bool requires_continuation{false};
 
    JsonValue provider_metadata = JsonValue::object();
};
 
class NEURALPLUS_API Error : public std::runtime_error {
public:
    using std::runtime_error::runtime_error;
};
 
class NEURALPLUS_API ConfigurationError final : public Error {
public:
    using Error::Error;
};
 
class NEURALPLUS_API SessionInUseError final : public Error {
public:
    using Error::Error;
};
 
class NEURALPLUS_API MaxRoundsError final : public Error {
public:
    using Error::Error;
};
 
class NEURALPLUS_API TransportError final : public Error {
public:
    using Error::Error;
};
 
class NEURALPLUS_API ProviderError final : public Error {
public:
    ProviderError(std::string message,
                  Provider provider,
                  int status,
                  std::string code = {},
                  std::string request_id = {});
 
    [[nodiscard]] Provider provider() const noexcept;
 
    [[nodiscard]] int status() const noexcept;
 
    [[nodiscard]] const std::string& code() const noexcept;
 
    [[nodiscard]] const std::string& request_id() const noexcept;
 
private:
    Provider provider_;
    int status_;
    std::string code_;
    std::string request_id_;
};
 
[[nodiscard]] NEURALPLUS_API const char* to_string(Provider provider) noexcept;
 
[[nodiscard]] NEURALPLUS_API const char* to_string(Role role) noexcept;
 
[[nodiscard]] NEURALPLUS_API const char* to_string(FinishReason reason) noexcept;
 
}  // namespace neuralplus