OpenAnima roadmap
What the library is meant to become, milestone by milestone.
[x]in place[~]partially in place; the note says what is missing[ ]not started
The scope, in one line: middleware for a world of agents. The host application creates a world and, inside it, actors: NPCs, which converse and reason, and information sources, logs the application publishes what happens in the world into. Everything in a world can interact, but nothing in it knows everything: an NPC reads the sources its host subscribed it to, and what reaches its context is not the record but what its senses make of it. The channel with the player works end to end; the world and the other agents drive the milestones below.
The shape of a world
- A world is what the application creates, and what everything else lives in.
- An actor is what a world holds: an NPC, an entity with a persona, a memory and senses, or an information source, a log the application publishes what happens in the world into.
- An NPC does not read the world. The application subscribes it to the sources it should follow, and to those only, so two of them in the same room can stand next to two different accounts of what is happening.
- A sense belongs to the NPC and decides how much of a source, and in which form, reaches its context. The source keeps the whole record; the NPC gets what its senses made of it.
An apple falls off a table, and the source that logs it keeps the moment and the millimetres. An NPC with sight and hearing, subscribed to that source, reads that something small landed nearby when it is looking elsewhere, and reads an apple of a colour, falling in a way, at about the distance its eye can tell when it happens to be looking that way. The record is exact; the context is what the senses let through.
v0.1.0 - Foundations and scaffolding
-
- nlohmann/json v3.12.0, Catch2 v3.16.1 and libcurl. The
system libcurl is used when
find_packagefinds it; otherwise curl is built from source with Schannel on Windows and OpenSSL elsewhere, so no runner needs a manual install.
- nlohmann/json v3.12.0, Catch2 v3.16.1 and libcurl. The
system libcurl is used when
-
.github/workflows/ci.yml: ubuntu and windows, each Debug and Release, plus a job that builds the documentation and fails on a Doxygen warning.
-
- Dependabot for the workflow actions, Renovate for the CMake pins, a workflow that submits the dependency graph, and branch protection with code owner review.
-
OpenAnima::Core,OpenAnima::HttpandOpenAnima::Provider, with the error taxonomy shared at the root. A public header and its implementation share a path, soCore/NPCBrain.his implemented byCore/NPCBrain.cpp.
-
- The suite is Catch2, and no case in it touches the network.
-
- clang-format, clang-tidy, clangd, build and debug configurations, and a compile database that both tools read.
v0.2.0 - Abstraction and asynchrony
-
Core::ChatMessagewithRole, andCore::CompletionwithFinishReasonandTokenUsage.Completioncarries the answer text, the model that answered, why generation stopped and the reported token usage, which is empty when the provider reports none.
-
OpenAnima::Provider::IProvider.complete()returns aCompletion, so the metadata survives the call instead of being thrown away while parsing.
-
Provider::RestProvideroverHttp::CurlHttpTransport. Verified against a real OpenAI call and against Ollama's contract. LM Studio speaks the same one.
-
OPENANIMA_BASE_URLandOPENANIMA_MODELare required, the rest have defaults, and a value out of range is rejected with aConfigErrorthat names the variable and the bounds. The reader takes a lookup function, so a test never has to patch the process environment.
-
ConfigError,TransportError,ProviderError(which carries the HTTP status) andParseError, all derived fromOpenAnimaError, so onecatchin the host application covers the whole library.
-
IProvider::complete()takes a sink and reports every piece as it arrives, andRestProviderreads thetext/event-streamthe contract answers with, so a caller can paint an answer while the model is still writing it. Under it,HttpTransportreports the status and the body as they land, an exchange can be abandoned through a short write, and what is bounded is the silence rather than the whole exchange. A heartbeat (datawith nothing after it) is dropped rather than read as a chunk, and a callback that throws cannot escape into libcurl: the failure is raised once the handle has been released.
-
NPCBrain::askAsync()hands a turn to a thread of its own and reports it as events:poll()collects them,cancel()stops a turn and reports what it had produced, andisBusy()says whether one is still open. The conversation is written on the caller's thread, when the last event of the turn is collected, so a client that draws an answer still owns the order the turns are written in. A turn that was cancelled is not written: the conversation stays as it was.
v0.3.0 - Strict parsing (data structuring)
-
Core::ResponseFormattravels with the call: free text, a JSON object, or a JSON Schema sent asresponse_formatwhere the contract knows the field. The answer comes back read as well as raw, and an answer that is not the JSON that was asked for is aParseErrorrather than something the caller discovers later. The contract of an NPC's own answer is the next point.
-
askTurn()andaskTurnAsync()ask the answer in the schema kept indata/reply-schema.json, with the actions of anActionCataloguefilled in, read it back as anNpcReplyand keep the whole document in the history. The contract also travels in the instruction sent with the prompt, so a provider that ignores the schema still answers in it, and the dialogue is read out of the document while it arrives, so a sink paints words rather than JSON.
-
- The validation half is in place:
ParseErrorandProviderErrorreject anything that cannot be read or that the provider refused, and the error carries the HTTP status. The fallback is not: a rejected answer reaches the caller with no second attempt.
- The validation half is in place:
v0.3.1 - Resilience
-
- Today a 429, a 500 or a timeout reaches the caller as an exception on the first try.
- Open question: retries could live in
RestProvider, or wrapHttpTransportas a decorator. The decorator keepsRestProviderfree of the policy, but it needs the transport to know which failures are worth repeating.
v0.4.0 - Memory and knowledge
-
historygrows without bound: no window, no truncation, no summarisation, so a long session will eventually exceed the model context. First priority overall, now that the asynchronous core is in place.
-
setSystemPrompt()stores one fixed string, deliberately kept out of the history so the persona can change mid-conversation. Nothing assembles it from state or events yet.
-
- A persona is prose, and prose invites invention: state a
past in one sentence and the model writes the battle. What
an NPC knows goes in as data, with identifiers and apart
from the persona, and anything outside that list is not
known. Over it, a level per category (
forbid,hedge,allow), written into the prompt and checked on the way out, because a prohibition that is not checked is a suggestion. The check is a judgment over a closed set, so it does not have to be an LLM: anything that answers only inside the options it is given can serve, behind one interface, with a narrow question to the model as the default.
- A persona is prose, and prose invites invention: state a
past in one sentence and the model writes the battle. What
an NPC knows goes in as data, with identifiers and apart
from the persona, and anything outside that list is not
known. Over it, a level per category (
-
- The world channel in its simplest form: the host
application reports what happened around the agent, so the
agent can react to it instead of only answering questions.
It is the pipe the world of
v0.5.0is built on.
- The world channel in its simplest form: the host
application reports what happened around the agent, so the
agent can react to it instead of only answering questions.
It is the pipe the world of
v0.5.0 - The world and perception
- The world channel: what the application publishes into its sources, and what each NPC makes of it. It is what the milestones after this one assume.
-
makeNpc()hands out a brain on its own today, and the rest of the state stays with the application. The world is where the brains, the sources they follow and everything the application publishes live together, and it is what the milestones after this one assume.
-
- An actor that carries records. The application publishes what happens in the world into it, a door opening or an apple falling, and the source keeps them whole, in order and exact.
-
- The application decides, from the moment the NPC is made, and an NPC reads nothing else. It is what lets a world be shared without the knowledge being.
-
- One per way of perceiving, owned by the NPC, each turning a source record into the approximation that reaches the prompt. A pass-through is the first one, so the pipeline exists before any sense is clever.
- Open question: whether a sense is configuration of the NPC or an interface the host implements. The apple above wants the second; the first is enough to start.
v0.6.0 - State machine and narrative agenda
v0.7.0 - Multi-agent architecture (pub/sub)
- The other-NPCs channel: several agents in one room, over
the subscriptions
v0.5.0leaves in place. The room is shared and the knowledge is not: each agent reads what it is subscribed to, and perceives it through senses of its own.
v0.8.0 - Native local inference
-
- Note the distinction:
RestProvideralready talks to a llama.cpp server. What is missing here is in-process inference with no intermediate server, which is what a shipped game needs.
- Note the distinction:
v0.9.0 - Concurrency safety and scheduler
-
- Each brain runs its turn on a thread of its own today, which is enough for a client driving one agent and not enough for a room of them sharing one machine.
-
- A brain is driven from one thread: the asynchronous
calls run a turn on a thread of the library's own and hand
its events to whoever collects them, but two threads calling
ask()on the same brain would still race on the history. The transport is closer, with one curl handle per call,CURLOPT_NOSIGNALand astd::call_onceinitialisation.
- A brain is driven from one thread: the asynchronous
calls run a turn on a thread of the library's own and hand
its events to whoever collects them, but two threads calling
v0.10.0 - Polish, profiling and examples
- [~] Interactive CLI harness under
examples/.examples/cliHarnesstakes every setting as an option, with its own variables and.envas the fallback, keeps one conversation per NPC across turns (/create,/enter,/npcs,/leave,/clear), and prints the turn in the order of the reply contract, with the raw document behind--rawor/raw. What is left is a case in the suite that drives the binary itself.
- [~] Terminal client under
examples/.examples/tuiHarness, designed in the harnesses page: a full screen with a conversation of its own to scroll, a prompt pinned at the bottom with its command palette, and a world of NPCs reached by identifier with/create,/enter,/npcsand/leave, plus/rawto read the document the model wrote. Built over its own terminal layer (Unix termios, Windows console) and split by what each part is allowed to know:domain/for the model and the keys,presentation/for the frame,application/for the loop and what the pointer does, andterminal/for the console. What is left is the client test over a pseudo-terminal inside the suite, and letting several NPCs share one conversation, which needs the library to carry it.- It is provisional on purpose: the client is where the shape of the library is tried out, so it is expected to be reshaped as the API grows towards what the milestones above ask for. What it does today is in the harnesses page; nothing here is frozen until the API is.
-
- The only output today is a stderr note from the harness and the exception messages. A library should let the host application decide where the logs go.
-
- No sanitizer configuration in CMake or in CI, and
curl_global_cleanupis registered at exit, which is not the same as having measured anything. The one measurement so far was made by hand, with a probe outside the suite: it caught a libcurl handle leaked by an exception leaving a callback, since fixed, and nothing runs it again on a change.
- No sanitizer configuration in CMake or in CI, and
-
- It is the only component verified by hand instead of by the suite.
v1.0.0 - Release candidate (MVP)
- [~] Documentation.
- The reference is generated from the headers and published together with the development guide and this roadmap at https://losadgm.github.io/OpenAnima/, and CI builds it on every change. What is missing is a written guide for integrating the library into a host application.
-
- There are no
install()rules and no exported targets, so consuming the library from another CMake project means FetchContent. There is no release workflow either.
- There are no
Next steps
- A bounded context (v0.4.0). The history grows without limit, and the FIFO window is already the planned fix. It is the first thing a long session hits.
- The world (v0.5.0). The library creates
worlds in the plan and hands out a brain in the code:
makeNpc()is all of it today, and the sources, the subscriptions and the senses the milestones above assume are what turns one brain into a world. - One queue for every brain (v0.9.0). Each brain runs its turn on a thread of its own today, which is enough for a client driving one agent and not enough for a room of them sharing one machine.
- Drop
NPCBrain::ping()before the API freeze. It only proves that the library links.
Beyond the MVP
Not planned, and no milestone: where the project may go once the release candidate is out, in one place so the ideas are not lost.
- Long-term memory with retrieval. The
window of
v0.4.0bounds the conversation, and what falls out of it is gone. A diary an NPC writes what it perceives into, and reads back from by relevance, is the other half of the memory: the short window keeps the exchange and the diary keeps the history. It needs a route for embeddings (the contract has one, and the provider interface is chat only today), an index that stays in process so the library stays light, and a retrieval policy, which is what separates an NPC that remembers from a search box. A summary of the window may be enough before any of that is needed. - A turn that thinks in rounds. One
request is one reply today: the model answers once and the
turn is closed. A deeper conclusion sometimes needs a second
pass, either to look at its own answer again or, more
usefully, to go and get something it did not have - its
memory, the world, another NPC - and think again with it in
hand. Reasoning over the same context reorders what is
already there rather than finding anything new, so the round
earns its cost when it brings an observation back, which is
the world of
v0.5.0and the tools behindRole::Tool. What is missing is the stop condition - a number of rounds, a word from the model itself, or a judge - and that is what has kept it out of the stages. What it cannot change: intermediary rounds are not turns, they do not enter the history, and only the last reply is kept.
CMakeLists.txt carries version 0.2.0: the
milestone is closed, with the asynchronous core verified
against a real provider before the number moved.