wai - Workflow-AI

A symbolic cognitive framework in C++20: reasoning modeled as probabilistic collapse over a knowledge graph, not neural networks. Instead of weights and gradients, wai stores explicit tokens and weighted edges, and an agent walks that graph one deterministic-per-seed step at a time, spending a bounded budget of energy. Every decision is inspectable, replayable, and editable after the fact.

Concept

Knowledge is a directed graph of Cell nodes connected by q16 fixed-point probability edges. An agent has short-term memory, an energy budget, and a set of tunable parameters. A collapse is one reasoning step: gather the candidate successors of the current token (its own edges, its class edges, and short-term memory), score them, select one, fire its action, and record the step. Chaining collapses produces a walk through the graph - a line of "thought" that you can audit, undo, stamp, and restore.

Highlights

• q16 fixed-point beliefs: probabilities are uint16_t (0..65535 maps to 0.0..1.0) with saturating, mostly integer arithmetic - no floats on the hot path.
• Templated ID width: IdT is selectable as u16, u32, or u64 at runtime through the C API; all three are compiled into one shared library.
• Pluggable strategies by default (decay, normalize, class-merge, select, redistribute, distribute) via function pointers, or compiled-in defaults with -DWAI_STATIC_STRATEGIES=ON.
• Stable C ABI (include/wai/wai_c_api.h) for dlopen/dlsym and language bindings.
• wai_engine: a line-oriented JSON process for driving the engine from any language.
• wai_tui: an FTXUI terminal UI that drives the engine.
• Python demos and a native binding wrapper for integration/experimentation.

Build

Requires CMake >= 3.20 and a C++20 compiler. FTXUI and GoogleTest are fetched at configure time, so the first configure needs network access.

cmake -S . -B build
cmake --build build

Build options (pass as -D<option>=<value> to the configure step):

cmake -S . -B build -DWAI_OPT_LEVEL=release      # debug|release|size|native (default: release)
cmake -S . -B build -DWAI_STATIC_STRATEGIES=ON   # inline strategies, drop function pointers (default: OFF)
cmake -S . -B build -DWAI_FAST_MATH=ON           # aggressive FP (-ffast-math); implies WAI_STATIC_STRATEGIES (default: OFF)

WAI_OPT_LEVEL maps to -O0 -g (debug), -O2 -DNDEBUG (release), -Os -DNDEBUG (size), and -O3 -march=native -mtune=native -DNDEBUG (native).

Artifacts

All land in build/:

• libwai.so - shared library (Python bindings, benchmarks).
• libwai_static.a - static library (single-binary executables).
• wai_engine - JSON-over-stdio engine process, statically linked to wai.
• wai_tui - FTXUI terminal UI.

Quickstart (C API)

Link against libwai (or libwai_static.a plus -lm) and include wai/wai_c_api.h.

#include <stdio.h>
#include <wai/wai_c_api.h>

int main(void) {
    wai_context_t* ctx = wai_context_create(/*seed=*/42, WAI_ID_U32);

    wai_token_t hello = wai_declare(ctx, "hello");
    wai_token_t world = wai_declare(ctx, "world");
    wai_connect(ctx, hello, world, 1.0f);          /* hello -> world, prob 1.0 */

    wai_agent_id_t agent = wai_create_agent(ctx);
    wai_collapse_result_t r = wai_collapse(ctx, agent, hello);
    if (r.has_selection)
        printf("collapsed to: %s\n", r.output);     /* -> "world" */

    wai_context_destroy(ctx);
    return 0;
}

wai_version() returns "WAI v3.0 (q16)"; the CMake project version is 3.0.0.

Run the TUI

cmake --build build --target run    # launches wai_tui driving wai_engine

Tests

ctest --test-dir build              # q16, collapse, and memory suites

Repo layout

Path	Contents
include/wai/core/	q16 arithmetic, Cell, Dictionary, strategies, blends, actions
include/wai/knowledge/	Knowledge<IdT> graph, class inheritance, .wai template deltas
include/wai/agent/	Context<IdT>, AgentParams, memory, the collapse algorithm
include/wai/ipc/	JSON utilities and the plugin registry
include/wai/wai_c_api.h	the stable C ABI
src/capi/	C API implementation (runtime ID-width dispatch)
src/engine/	wai_engine JSON-over-stdio process
src/tui/	FTXUI terminal UI
tests/	GoogleTest C++ suites and Python tests
demos/	Python demos driving the engine / shared library
docs/spec.md	full technical reference

Reference

See docs/spec.md for the full technical reference: numeric model, data model, the collapse algorithm, strategies, the C ABI, and the engine JSON protocol.