OpenAnima

C++17 middleware for a world of agents: NPCs that talk to the player and reason about what they perceive, information sources that log what happens, and senses that decide what each NPC makes of it.

An NPC is not a chat box. It plays a persona, remembers what happened, and has to stay coherent while the player, the world and the other agents keep talking to it. The library holds that state, decides what the model needs to see next, and turns the answer into something the host application can act on. Which provider, which transport, and what to do with the text are decisions of the application, not of the library.

The conversation is one of three channels an NPC uses:

Channel What it carries Where it stands
The player dialogue turns, with a persona and a history behind them in place
The world what the application publishes into its sources, and what each NPC perceives of it planned, v0.5.0
Other NPCs shared rooms, and a ledger of who said what planned, v0.7.0

What it does today

What is still missing is a strategy for the context of a long conversation, which grows until it no longer fits and is not trimmed yet. The roadmap is what comes next.

A request, end to end

#include <iostream>

#include "OpenAnima/OpenAnima.h"

int main() {
    using namespace OpenAnima;

    Provider::RestProviderConfig config;
    config.baseUrl = "http://localhost:11434/v1";
    config.model = "qwen2.5:7b";

    Core::NPCBrain brain = makeNpc(config);
    brain.setSystemPrompt("You are a blacksmith in a small village.");

    const Core::Completion answer = brain.ask("Do you have any iron daggers?");
    std::cout << answer.text << '\n';

    if (answer.finishReason == Core::FinishReason::Length) {
        std::cout << "the answer was cut off\n";
    }
}

One include, a configuration and one line of setup. The library takes the values and nothing else, so where they come from is a choice of the caller: the clients in examples/ read their own environment variables, a test passes literals. When the pieces have to be told apart (a test, a local model, a custom transport), they are still there, one per header; makeNpc() just wires the default stack.

Streaming and asynchronous calls

The same turn can be read while it is being written, and asked for without waiting for it:

// Piece by piece, as they arrive, on the thread of the caller.
brain.ask("Do you have any iron daggers?",
          [](std::string_view piece) { std::cout << piece << std::flush; });

// Or on a thread of the brain's own, collected when it suits the caller.
const Core::RequestId turn = brain.askAsync("Do you have any iron daggers?");
for (;;) {
    const std::optional<Core::Event> event = brain.poll(std::chrono::milliseconds{100});
    if (!event.has_value()) {
        continue;  // Nothing happened yet.
    }
    if (event->kind == Core::EventKind::Delta) {
        std::cout << event->text << std::flush;
    }
    if (event->kind == Core::EventKind::Finished || event->kind == Core::EventKind::Failed) {
        break;
    }
}

Stopping a turn mid-answer is brain.cancel(turn). The call stops, whatever the model had produced arrives with the Finished event marked FinishReason::Cancelled, and the conversation is left as it was.

What comes with it:

The configuration is a struct, and the defaults are picked so that a local model needs two lines of it:

Field Required Default
baseUrl yes -
model yes -
apiKey no empty, sent only when set
timeoutSeconds no 60, from 1 to 3600
temperature no 0.7, from 0 to 2
maxTokens no 512, from 1 to 200000

A local server needs no key at all:

Provider::RestProviderConfig config;
config.baseUrl = "http://localhost:11434/v1";
config.model = "llama3.1";

The clients in examples/ fill the same struct from their own variables, prefixed with the name of the client: OPENANIMA_CLI_* for the command line and OPENANIMA_TUI_* for the console one, so the two can point at different models. The harnesses page has the names.

Errors

Every failure is a subclass of OpenAnima::OpenAnimaError, so one catch covers the whole library:

Type Raised when
ConfigError A required variable is missing, or a value is out of range
TransportError The request never arrived: DNS, TLS, refused connection, timeout
ProviderError The provider answered with an error, carrying its HTTP status
ParseError A response arrived but could not be read