Development guide

How to build the library, run the tests, and publish these pages.

Requirements

Build and test

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++
cmake --build build
ctest --test-dir build --output-on-failure

The tests never touch the network. FakeHttpTransport and FakeProvider live in tests/support/, and a test that needs a provider uses one of them. Keep it that way: a test that reaches for a real endpoint is a test that fails on a plane.

Options

Option Default What it does
OPENANIMA_BUILD_EXAMPLES ON Builds the clients under examples/
OPENANIMA_ENABLE_CLANG_TIDY OFF Runs clang-tidy while compiling
OPENANIMA_ENABLE_DOCS OFF Adds the docs target, which generates the API reference

No option changes the public headers. What a consumer can call is the same everywhere.

Layout

include/OpenAnima/     public headers
    OpenAnima.h        umbrella header, and the makeNpc() entry point
    Core/              the NPC and the conversation types
    Http/              the transport interface and the libcurl implementation
    Provider/          the backend interface, the settings, the REST provider
src/OpenAnima/         the implementation, mirroring the headers
tests/                 Catch2 tests, one directory per package
examples/cliHarness/  a runnable client: takes its settings from flags and .env, sends a
                      prompt, prints the turn in the order of the reply contract
examples/common/      shared by both clients: the loader for `.env`
examples/tuiHarness/  the terminal client: full screen, transcript, mouse and clipboard
data/                  the words and the contract: prompts, reply schema and client texts
docs/                  these pages, the Doxyfile template and the site template
.github/scripts/       helpers used by the pipeline, including the site builder
.github/instructions/  the conventions of this repository, for editor tooling

A header and its implementation share a path: OpenAnima/Core/NPCBrain.h is implemented by OpenAnima/Core/NPCBrain.cpp under src/.

data/ holds the words and the contract: prompts.json for the instruction the library sends, reply-schema.json for the schema the answer is asked for in, and tui-texts.json for what the terminal client says. CMake embeds each one in the target that uses it, so none of them opens a file at run time: editing the json and building again is the whole workflow. The library reads them in ActionCatalogue, where the schema is embedded as it is and the instruction takes the description of every property from it, so a property is described once. The client reads its texts once through Domain::texts(), where a {name} in a text is filled with Domain::fill().

Conventions

Threads

Core::NPCBrain::askAsync() runs a turn on a thread of the library's own, and the target links Threads::Threads publicly, so a consumer that links OpenAnima::OpenAnima gets it without asking. Nothing else starts a thread: the synchronous calls, the provider and the transport work on the thread that called them, and the conversation is written on that thread when the events of a turn are collected.

Turns and their rounds

A turn is the exchange the conversation adds up as one: the prompt, and the reply the model answers it with. Today a turn is one request, and the reply is one document with the three variables of the contract in it: reasoning, dialogue and actions. That is deliberate.

A round is a request inside a turn. Rounds are what a deeper turn needs, and a round earns its cost when it brings something new back: memory, the world, another NPC. Reasoning again over the same context only reorders what is already there. The plan is in "Beyond the MVP" of the roadmap, and the invariants it has to respect are these.

What is missing to turn any of that on is the source of the observations, which is the world of v0.5.0, and the stop condition: a number of rounds, a word from the model or a judge. Until those exist a turn has one round, and the client sees no difference.

Documentation

There is one source of truth per thing:

All of it is published together at losadgm.github.io/OpenAnima.

Building the site locally

cmake -S . -B build -DOPENANIMA_ENABLE_DOCS=ON
cmake --build build --target docs          # writes build/docs/html
python3 .github/scripts/build_docs.py      # writes build/site
python3 -m http.server -d build/site 8000  # http://localhost:8000

The first step needs Doxygen and the second needs pandoc. The script itself only needs python3, no packages to install.

Adding a page

  1. Write it as Markdown in docs/. The file name becomes the URL: docs/naming.md is published as naming.html.
  2. Add a link to the navigation in docs/site/template.html, otherwise the page is reachable only by URL.
  3. Every docs/*.md is rendered, so nothing else is needed.

Note that pandoc does not run diagram tools. A diagram has to be committed as an image (SVG is preferred: it stays readable when zoomed) and linked from the Markdown.

Pandoc appends its own stylesheet for highlighted code after docs/site/style.css, so a rule there and a rule here that select the same element are won by that one, and by class rather than by element. A rule that has to hold for code blocks names the class: pre.sourceCode, not pre. The horizontal scroll of a long line is one of those.

Continuous integration

Workflow What it checks
ci.yml Builds and tests Debug and Release on Ubuntu and Windows, and builds the API reference with warnings treated as errors
pages.yml Publishes these pages and the reference to GitHub Pages on every push to main
dependency-graph.yml Submits the CMake dependencies to the dependency graph

Renovate keeps the pins in CMakeLists.txt current, Dependabot the GitHub Actions versions.