NeuralPlus

NeuralPlus

NeuralPlus is an open-source, provider-independent C++17 AI SDK and LLM client library for OpenAI, Anthropic, Gemini, tool calling, session state, and tracing.

‍Status: General Availability. Version 0.2.0 is the first supported release of the simplified NeuralPlus API.

The design in five pieces

• AIClient owns the complete conversation/tool loop.
• OpenAIClient, AnthropicClient, GeminiClient, and OpenAICompatibleClient translate one provider round.
• Session owns conversation messages plus a thread-safe, process-local cache.
• Tool is the formal executable extension point; FunctionTool covers most applications without a new subclass.
• Any number of Tracer objects can be attached to a client. Built-ins cover console, JSON Lines files, memory, callbacks, and POSIX syslog.

A model name is data (ModelDescriptor::id), not a new C++ type. This keeps the class tree stable when providers add models. Typed configurations for common current models provide readable defaults without restricting custom model IDs.

Build

Prerequisites are CMake 3.20+, a C++17 compiler, libcurl development files, and Threads. CMake first looks for nlohmann/json 3.12.0 and otherwise downloads its checksum-pinned release archive.

cmake --preset dev
cmake --build --preset dev
ctest --preset dev

The dev and release build presets build the library, tests, and all examples. To build only the examples, use the matching examples preset:

cmake --build --preset dev-examples
# Or: cmake --build --preset release-examples

Example executables are placed in build/dev/examples/ or build/release/examples/.

The equivalent generator-independent commands are documented in Getting started.

OpenAI client example

The factory returns the common AIClient interface. The OpenAI configuration reads OPENAI_API_KEY when config.api_key is not set:

#include <neuralplus/neuralplus.hpp>
 
#include <iostream>
#include <utility>
 
int main() {
    auto config = neuralplus::models::openai::gpt_5_6_terra();
    auto client = neuralplus::make_client(std::move(config));
    neuralplus::Session session;
 
    const auto response =
        client->generate(session, "Explain RAII in one sentence.");
    std::cout << response.message.text() << '\n';
}

Change only the typed configuration passed to make_client to select another provider. The same Session, tools, and tracers work with every built-in provider. Credentials can also be assigned directly to the provider configuration; see Credentials.

The catalog includes current OpenAI, Anthropic, and Gemini configurations: Model configurations. An arbitrary provider model remains one typed configuration constructor away.

More LLM client examples

The built-in clients make real provider requests. They use ANTHROPIC_API_KEY, GEMINI_API_KEY/GOOGLE_API_KEY, and OPENAI_API_KEY when an explicit key is not assigned.

Anthropic conversation

auto config = neuralplus::models::anthropic::claude_sonnet_5();
auto client = neuralplus::make_client(std::move(config));
 
neuralplus::Session session;
session.set_system("Answer as a concise C++ mentor.");
 
const auto response =
    client->generate(session, "When should I use std::string_view?");
std::cout << response.message.text() << '\n';

Gemini conversation

auto config = neuralplus::models::gemini::gemini_3_6_flash();
auto client = neuralplus::make_client(std::move(config));
neuralplus::Session session;
 
const auto response =
    client->generate(session, "Give me three practical RAII examples.");
std::cout << response.message.text() << '\n';

OpenAI-compatible server

Use the same interface with a local or hosted Chat Completions-compatible server:

neuralplus::OpenAICompatibleConfig config(
    "local-model", "http://localhost:8000/v1");
config.api_key_environment = "LOCAL_LLM_API_KEY";  // Optional.
 
auto client = neuralplus::make_client(std::move(config));
const auto response = client->generate("Explain move semantics simply.");
std::cout << response.message.text() << '\n';

Multimodal request

auto config = neuralplus::models::openai::gpt_5_6_terra();
auto client = neuralplus::make_client(std::move(config));
 
neuralplus::Message::Contents contents;
contents.push_back(
    neuralplus::Content::text("Describe the architecture in this image."));
contents.push_back(neuralplus::Content::image_url(
    "https://example.com/architecture.png", "image/png"));
 
const auto response =
    client->generate(neuralplus::Message::user(std::move(contents)));
std::cout << response.message.text() << '\n';

Complete, runnable programs:

Scenario	OpenAI	Anthropic	Gemini	Compatible server
Chatbot	source	source	source	source
Custom model/config	source	source	source	source
Multimodal	source	source	source	source

Add a stateful tool and tracers

neuralplus::ToolSpec spec;
spec.name = "increment";
spec.description = "Increment this session's counter.";
spec.input_schema = {
    {"type", "object"},
    {"properties", {{"delta", {{"type", "integer"}}}}},
    {"required", {"delta"}},
};
 
auto tool = std::make_shared<neuralplus::FunctionTool>(
    std::move(spec),
    [](neuralplus::ToolContext& context,
       const neuralplus::JsonValue& arguments) {
        const int delta = arguments.at("delta").get<int>();
        const int value = context.state().update<int>(
            "counter", 0, [delta](int current) { return current + delta; });
        return neuralplus::ToolOutput::json({{"counter", value}});
    });
 
neuralplus::ClientOptions options;
options.tools = {tool};
options.tracers = {
    std::make_shared<neuralplus::ConsoleTracer>(),
    std::make_shared<neuralplus::FileTracer>("trace.jsonl"),
};

Trace output is metadata-only by default. capture_trace_payloads makes payloads available to in-memory, callback, and custom tracers. FileTracer also requires FileTracerOptions::include_payloads; console and syslog output remain metadata-only. New trace files are created with mode 0600 on POSIX. Provider rounds, total tool calls, concurrent tool callbacks, and HTTP response sizes all have configurable bounds. Tool declarations are validated and snapshotted when the client is constructed.

The complete credential-free example uses FunctionAIClient: examples/simple_session.cpp. Ready-to-run chatbots, custom-model programs, and multimodal examples use the real built-in provider clients: Provider examples.

Documentation

• Published documentation and example source
• Getting started
• Architecture and class diagram
• Model configurations
• Provider examples
• Generating Doxygen documentation
• Extending clients, tools, and tracing
• Roadmap
• Contributing
• Contributors
• Code of Conduct
• Security policy

Generate API documentation with:

cmake --preset docs
cmake --build --preset docs

The generated entry page is build/docs/api/index.html, and CI publishes the same output from main to GitHub Pages. See the Doxygen guide for installation, refresh, publishing, and non-preset commands.

Supported environments

The library targets C++17 on Linux, macOS, and Windows. Every CI run covers Ubuntu 22.04/24.04, macOS 14, Windows Server 2022, Rocky Linux 9, Debian 12, Red Hat UBI 9, Oracle Linux 9, and CentOS Stream 9. UBI is a compatibility signal for RHEL 9, not Red Hat certification. See Getting started for compiler and platform details.

License

NeuralPlus is licensed under the Apache License 2.0. Dependency attributions and licenses are recorded in THIRD_PARTY_NOTICES.md.