KAI - Distributed Object Model for C++

KAI is a network distributed Object Model for C++ with full runtime reflection, persistence, and incremental garbage collection. No macros are needed to expose fields or methods to the scripting runtime, including external code from other libraries.

Objects and compute can be distributed across Nodes in a Domain.

Demo

▶ Live Interactive Demo

Animated walk-through of agent migration, Pi-guided routing, load balancing, and snapshot-based recovery after a simulated host failure. Source of truth: ContinuationMobilityDemo.rho.

The demo has three layers: the interactive RhoMog visualization explains the idea, ./Bin/ContinuationMobilityDemo runs the deterministic executable model, and ./Scripts/network/run_continuation_migration_demo.sh proves the runtime path by freezing a stateful Pi workflow in one process, sending it to another process, thawing it, resuming it, and returning 42.

Requires GitHub Pages enabled from the master branch root.

System Architecture Overview

The KAI system provides a multi-layered architecture that enables distributed object programming with multiple language frontends.

Project Overview - Learn about the core CppKAI runtime and KAI-aware shared web layer.

See the full diagram: System Architecture Overview (Mermaid, rendered on GitHub).

Key System Components

• Multi-Language Frontend: Rho (infix), Pi (stack-based), and Tau (IDL) languages with seamless interoperability
• Interactive Console: Real-time REPL with peer-to-peer networking capabilities
• Distributed Object Model: Network-transparent objects with type safety across node boundaries
• Stack-based Execution: High-performance virtual machine with continuation support and binary migration between nodes
• LLM Tooling: RepoIndex builds a local repo knowledge base and RhoDataset exports incremental training corpus records from Rho, Pi, Tau, tests, scripts, Logs/, history files, README files, and Scripts/Training. The generated manifest is the training memory.
• Incremental Garbage Collection: Smooth memory management without performance spikes
• Code Generation: Tau IDL generates proxy/agent pairs for network communication
• Cross-platform Support: Linux, WSL2, Windows (native), macOS
• RhoMog Model: Live interactive demo of continuation mobility — agent migration, Pi-guided routing, load balancing, and snapshot-based recovery after host failure

Demo Views

Pi is a postfix language.

Window illustrates how Rho is transpiled to Pi:

Documentation & Architecture

Main Documentation Hub

Documentation Guide - Start here for organized navigation of all documentation | Doc/ README

System Architecture

Architecture Resources - Comprehensive system architecture documentation and diagrams

• Overall System Architecture - High-level component relationships and data flow
• Language System Architecture - Pi/Rho/Tau translation pipeline and interoperability
• Console Networking Architecture - P2P communication model and protocols
• Build System Architecture - CMake structure and dependencies
• Test System Architecture - Test infrastructure and validation workflows
• System Overview - Complete architectural analysis with statistics

Development Guides

• Building: Build Guide | Out-of-Source Build Notes | Installation | CMake Guide
• Languages: Pi Tutorial | Rho Tutorial | Tau Tutorial | Language System
• Networking: Overview | Architecture | Console Networking
• Testing: Test Guide | Connection Testing | Test Overview
• Code Generation: Tau Code Generation | Tau Generate
• Project Status: TODO | Test Summary

Component Documentation

• LLM Overview: LmmReadme.md - Cache, repo indexing, and Rho dataset export
• Core System: Core README | Registry | Config
• Executor: Executor README - Virtual machine and execution engine
• Console: Console README - Interactive shell with networking
• Languages: Common | Pi | Rho | Tau
• Platform Support: Platforms | Linux | Windows | macOS

Testing & Examples

• Test Suites: Test Overview | Language Tests | Console Tests | Network Tests
• Example Code: Examples - Sample applications and use cases
• Scripts: Scripts - Build and demo scripts

External Dependencies

• External Libraries: Ext/ - Third-party dependencies and libraries
• Build System: CMake - Build configuration and macros

Quick Start

Linux / WSL2 / macOS:

• Build with ./Scripts/build.sh (quick Debug build), or plain CMake from a build/ directory for full control over options — networking is enabled by default (-DKAI_NETWORKING=OFF to disable)
• Test binaries are written to ./Bin/Test, including TestNetwork and TestTau
• Run ./Scripts/run_rho_demo.sh for a comprehensive demo of Rho language features
• Run ./Scripts/calc_test.sh for a demonstration of network calculation
• Run ./Scripts/network/run_continuation_migration_demo.sh to prove continuation migration across two processes
• Run ./Scripts/network/run_continuation_migration_tmux_demo.sh for a tmux-recordable migration demo

Windows (native):

• py build.py — configure and build
• py run.py console — build and launch the Console
• py run.py tests (or py run_tests.py) — build and run all tests
• py run.py window (or py run_window.py) — build and launch the ImGui/Window frontend (requires glfw3, and GLEW on Windows — e.g. vcpkg install glfw3 glew)
• py run.py --help — full option list

Key Features

• Zero-Macro Reflection: Expose C++ types and methods to scripting without macros or source modifications
• Distributed Computing: Share both data and computation across networked nodes
• Console Networking: Real-time console-to-console communication with command sharing
• Multiple Languages: Use Pi (stack-based), Rho (infix), or Tau (IDL) as needed
• Type Safety: Full type checking across network boundaries
• Incremental GC: Smooth, constant-time garbage collection with no spikes
• Cross-Platform: Linux, WSL2, Windows (native, VS 2022/2026), macOS, Unity3D
• Network Transparency: Access remote objects as if they were local
• Dynamic Load Balancing: Automatically distribute workload across network nodes
• RhoMog Model: Live interactive demo of continuation mobility with fantasy-themed visualisation

Core Components

• Registry: Type-safe object factory for creating, managing, and reflecting C++ objects
• Domain: A collection of registries across network nodes
• Executor: Stack-based virtual machine for executing code
• Memory Management: Incremental tri-color garbage collector

Languages

KAI is built around three small languages with a deliberate division of labor, not one general-purpose language wearing three hats.

• Pi (π): The execution substrate. A minimal, imperative RPN stack language, inspired by Forth, prompt: π. The executor runs Pi directly; the data stack plus instruction pointer are the complete continuation state, nothing implicit is held elsewhere. That is what makes it possible to freeze a running computation, send it across the network, and resume it on a different executor with no data loss.

• Rho (ρ): The scripting layer. A structured, Python-like infix language, prompt: ρ, that compiles down to Pi bytecode. It exists so people do not have to write Pi by hand. For example:

  let a = 3
  let b = 4
  let c = a + b
  

  compiles to:

  3 4 +
  // stack: [ 7 ]
  

• Tau (τ): Interface Definition Language (IDL) for distributed object contracts across process boundaries. Tau is orthogonal to Pi and Rho, it describes the shape of a network interface rather than compiling into either of the other two.

The prompt shows only the active language symbol. Command numbers remain available through history and !n; history persists in ~/.kai/{pi,rho}.history. The complete data stack is printed after each command, top-first, with [0] on the bottom line.

Console Networking

KAI consoles can communicate with each other over the network in real-time:

# Console 1 (Server)
./Console
π /network start 14600
π 2 3 +

# Console 2 (Client)
./Console
π /network start 14601
π /connect localhost 14600
π /@0 10 *              # Multiply Console 1's result by 10
π /broadcast stack      # Show stack on all connected consoles

localhost, ::1, and 127.0.0.1 are treated as the same loopback endpoint by the ENet transport, so local console peers can use whichever form is most convenient.

Network Commands:

• /network start [port] - Enable networking
• /connect <host> <port> - Connect to peer console
• /@<peer> <command> - Execute command on specific peer
• /broadcast <command> - Execute command on all peers
• /peers - List connected consoles

See Console Networking Guide for complete documentation.

Example Code

Pi (Stack-based)

{ dup * } 'square #  // Define a function that squares its input
5 square @           // Retrieve the function
&                    // Execute the function

Rho (Infix)

fun square(x) {
    return x * x
}
result = square(5)  // result is 25

Distributed Computing

node = createNetworkNode()
node.listen(14589)
node.connect("192.168.1.10", 14589)

data = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
fun square(x) { return x * x }

result = acrossAllNodes(node, data, square)
print(result)  // [1, 4, 9, 16, 25, 36, 49, 64, 81, 100]

Nested Futures (C++)

Future<T> is a thin wrapper around a shared_ptr<State<T>>, so it nests cleanly: a Future<Future<T>> is just an outer future whose value happens to be another future. Resolving the outer future delivers the inner future object, not the inner value; the inner future can still be pending, and resolving it later is visible through any copy you already unwrapped, since the state is shared.

using namespace kai::net;

Future<int> inner;
Future<Future<int>> outer;

// Resolve the outer future first, carrying the still-pending inner future.
outer.SetValue(inner);
outer.SetResponse(ResponseType::Returned);
outer.SetComplete(true);

Future<int> unwrapped = outer.GetValue();
assert(!unwrapped.IsComplete());  // inner is still pending

// Resolving the original inner future is visible through the unwrapped copy.
inner.SetValue(42);
inner.SetResponse(ResponseType::Returned);
inner.SetComplete(true);

assert(unwrapped.IsComplete());
assert(unwrapped.GetValue() == 42);

Nesting isn't limited to one level either; Future<Future<Future<T>>> resolves the same way, one layer at a time, outside-in.

See Test/Network/NestedFutureTest.cpp, Test/Network/NestedFutureParamTests.cpp, and Test/Network/NestedFutureTripleTest.cpp for the full test coverage of this pattern (24 tests). Note this covers the Future<T> class itself; nested futures as arguments across a network RPC call have not been verified and are a separate, unproven path.

Getting Started

Prerequisites

• C++23 compiler: Clang 16+ (default on Linux/macOS; also supported natively on Windows), GCC 13+, or MSVC 19.5+ (VS 2022/2026)
• CMake 3.28+
• Python 3.10+ (Windows build scripts)
• Ninja (optional, faster builds on Linux/macOS)

Building on Linux / WSL2 / macOS

git clone https://github.com/cschladetsch/CppKAI.git
cd CppKAI
git submodule init && git submodule update

./Scripts/build.sh                          # Quick Debug build (Clang, Ninja)

# Or plain CMake for full control over options:
mkdir -p build && cd build
cmake ..                                    # Networking on by default
cmake .. -DKAI_NETWORKING=OFF               # Build without networking
cmake .. -DBUILD_GCC=ON                     # Use GCC instead of Clang
cmake --build .

Building on Windows (native)

git clone https://github.com/cschladetsch/CppKAI.git
cd CppKAI
git submodule init
git submodule update --recursive

py build.py                     # Release build (Clang + Ninja by default, shell syntax OFF)
py build.py --config Debug      # Debug build
py build.py --msvc              # Use MSVC + Visual Studio generator + vcpkg instead
py build.py --no-network        # Disable networking
py build.py --imgui             # Build the ImGui/Window frontend (needs glfw3, and GLEW on Windows)
py build.py --reconfigure       # Clean and reconfigure

py run.py console               # Build + launch Console (Pi mode)
py run.py rho                   # Build + launch Console in Rho mode
py run.py tests                 # Build + run all tests (same as py run_tests.py)
py run.py test-pi               # Build + run TestPi only
py run.py demo                  # Build + run ContinuationMobilityDemo
py run.py window                # Build + launch the ImGui/Window frontend (same as py run_window.py)
py run.py console --no-build    # Just launch (skip build)

Building on Windows with Clang

py build.py already does this by default (Ninja + auto-detected clang++/clang, erroring out with instructions if either is missing). Two ways to do it manually instead, e.g. for a separate build directory:

# clang-cl (MSVC-compatible driver, uses the same VS toolchain/SDK)
cmake -B build-clang -G "Visual Studio 17 2022" -A x64 -T ClangCL
cmake --build build-clang --config Release

# real clang/clang++ (GNU-style driver, needs Ninja instead of the VS generator)
cmake -B build-clang -G Ninja -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++
cmake --build build-clang --target Console

Run the Ninja variant from a Developer PowerShell for VS (or the x64 Native Tools Command Prompt) so Clang can find the MSVC headers/libs it still links against on Windows.

To use MSVC + Visual Studio instead, pass --msvc to build.py (or use py build.py --msvc --clean if switching an existing Ninja-configured build/ directory — CMake refuses to change generator in place).

Security Configuration

Shell operations (backtick syntax, e.g. `pwd` in Rho/Pi) are disabled by default (ENABLE_SHELL_SYNTAX=OFF) — evaluating Pi/Rho source that contains a backtick expression runs a real shell command, so this is opt-in rather than opt-out. When enabled, native Windows routes commands through WSL2's bash (wsl.exe) — a WSL2 distro with bash/coreutils installed and wsl on PATH is required there for backtick expressions to work — while Linux/macOS/WSL2 use the system shell directly. To enable it:

cmake .. -DENABLE_SHELL_SYNTAX=ON

On Windows, py build.py --enable-shell does the same.

Applications

Console

./Console                    # Interactive Pi mode (default)
./Console -l rho             # Interactive Rho mode
./Console script.pi          # Execute Pi script
./Console -t 2 script.rho    # Execute with trace level 2

Interactive Session:

KAI Console v0.3.0
Type 'help' for available commands.

π 2 3 +
[0]: 5

π rho
Switched to Rho language mode

ρ x = 42; y = x * 2; y
[0]: 84

Features:

• Plain language prompts: π, ρ, and $
• Stack contents shown after every command, top-first with [0] at the bottom
• Per-language persistent history saved to ~/.kai/pi.history and ~/.kai/rho.history
• Context-sensitive help system
• Shell integration (backtick expansion, disabled by default - opt in with -DENABLE_SHELL_SYNTAX=ON; native Windows then routes commands through WSL2's bash)
• Color-coded stack display; floating-point values use the neutral value color
• Native KAI Logger initialization for Console lifecycle, inspection, debugger attachment/action, and failure records

Network Applications

Networking is enabled by default. The build includes the ENet transport layer, Tau IDL libraries, and all network tests. The old NetworkGenerate command-line tool has been removed; Tau proxy/agent generation remains available through the Tau generator library.

Continuations are serialized as binary payloads — suspended execution can be frozen on one node, transferred over the network, and resumed on another node.

// Domain A: register a service
Node nodeA;
nodeA.Listen(IpAddress("127.0.0.1"), 14600);
ISensorAgent agent(nodeA);

// Domain B: call it remotely
Node nodeB;
nodeB.Connect(IpAddress("127.0.0.1"), 14600);
ISensorProxy proxy(nodeB, agent.Handle());
auto future = proxy.Value();          // returns Future<int> immediately
nodeB.Step();

namespace Sensor {
    interface ISensor {
        int Value;
        Future<int> Measure(float range);
    }
}

Embed the Tau generator APIs when proxy/agent headers need to be produced from IDL as part of a tool or build step.

Project Structure

• Bin: Executable output files
• build: Build directory (out-of-source)
• CMake: Auxiliary CMake modules
• Doc: Documentation and tutorials
• Ext: External dependencies (git submodules)
• Include: Global include path
• Source: Project source code
• Test: Unit tests
• build.py: Windows build script (Clang + Ninja by default; --msvc for Visual Studio + vcpkg)
• run.py: Windows build-and-run script (console, tests, demo, etc.)

Platforms

• Windows 10/11 (VS 2022, VS 2026)
• Linux (Ubuntu, Debian, WSL2)
• macOS (Sierra and newer)
• Unity3D (2017+)

License

This project is licensed under the MIT License — see the LICENSE file for details.

---

Project Statistics

• 629+ C++ source files
• 3 integrated programming languages (Pi / Rho / Tau)
• 1,780+ passing tests across Pi, Rho, Tau, and network suites (TestPi alone has 585+) — see Doc/TEST_SUMMARY.md for the per-suite breakdown and Doc/TODO.md for currently-tracked language gaps and failing tests
• Full Agent/Proxy/Domain networking over ENet UDP
• Tau IDL generates type-safe proxy/agent pairs from .tau interfaces
• Networking on by default — disable with ./b --no-network
• Single flag KAI_BUILD_LLM=ON enables the local model-cache layer
• Model storage: ~/.cache/deepseek/models by default
• Repo knowledge base: ./Bin/RepoIndex builds a local code/test index
• Training corpus: ./Bin/RhoDataset exports code, tests, scripts, Logs/, history, README files, and Scripts/Training lessons. It is silent by default and only asks when a proposed corpus change would have large impact.

Start exploring: Begin with the Documentation Guide or dive into System Architecture for technical details.