OpenSparX/MasterAgent

OpenSparX / MasterAgent – A Small, Embeddable C++ Agent Runtime

What it is

• An open‑source C++17 library (and accompanying CLI) that lets you build local‑first AI agents. It first matches a user’s utterance against a set of deterministic exact‑phrase skills (no model needed). If a skill is not matched, it can forward the request to a locally‑hosted LLM (e.g., a llama‑server) via a simple HTTP / JSON API.
• The runtime validates tool definitions (name, JSON schema for arguments) and guarantees that only declared tools are called, with checked parameters. Tool results are returned to the caller as structured JSON.
• It can run completely offline (no libcurl, no SQLite) or with optional HTTP support for model calls and optional SQLite storage for durable request receipts.

Key capabilities

Feature	How it works
Exact‑phrase skills	Pre‑registered phrases trigger a deterministic callback, bypassing any model.
Tool registration & validation	Developers supply a JSON‑schema‑like description and a C++ callback; the runtime checks tool name and arguments before execution.
Local model integration	When built with MASTER_AGENT_ENABLE_HTTP=ON, the CLI can talk to any server that implements the OpenAI‑compatible /v1/chat/completions endpoint (e.g., a llama‑cpp server serving a GGUF model).
Durable request receipts	With SQLite enabled, each request gets a unique ID; repeated calls are deduplicated and outcomes are replayed, enabling crash‑recovery and manual reconciliation of UNKNOWN states.
Context & cancellation	Every tool call receives session ID, request ID, idempotency key, deadline and a cooperative‑cancellation token.
CLI & SDK	sparx command‑line tool demonstrates the flow; the SDK can be installed via CMake and linked as MasterAgent::Core (and optionally MasterAgent::Http).
Extensible examples	A reference “inventory agent” shows how to call an external HTTP service, commit an idempotent receipt, and recover from lost responses.
Testing & evaluation	CI runs unit tests, synthetic evaluations, and a packaging script that builds the SDK, CLI, and example consumer.

Typical workflow

1. Define tools – In C++ register each tool with a name, a parameter schema, and a callback that performs the real work (e.g., talk to a car’s AC controller).
2. Add exact‑phrase skills – Map fixed user utterances (e.g., "把空调调到22度") to callbacks that invoke the appropriate tool.
3. Build – cmake -S . -B build -DCMAKE_BUILD_TYPE=Release (add -DMASTER_AGENT_ENABLE_HTTP=OFF to drop the HTTP adapter, -DMASTER_AGENT_ENABLE_STORAGE=OFF to drop SQLite).
4. Run – ./build/cli/sparx run --input '把空调调到22度'. The runtime matches the phrase, validates the tool, runs the callback, and prints a JSON receipt.
5. Optional model – If no exact phrase matches, start a local LLM server and call the CLI with --endpoint 127.0.0.1:8080 --model local. The model must return either a JSON‑formatted tool call or a plain JSON response; malformed output is rejected.
6. Persist & recover – Provide --state ./state/agent.db --session alice --request-id ac-001 to store the receipt in SQLite. After a crash, sparx recover --state ./state/agent.db replays successful outcomes and flags unfinished ones as UNKNOWN for manual reconciliation.

Why it matters

• Determinism first – By handling known commands without a model, the system avoids hallucinations and guarantees repeatable behavior.
• Safety – Tool names and arguments are strictly validated; the runtime never guesses a tool call from a stray model output.
• Local‑first – No cloud services are required; everything can run on a laptop, edge device, or inside a container.
• Durability – SQLite receipts give a simple audit trail and enable exactly‑once semantics for business‑critical operations (e.g., inventory decrement).

Getting started

# Clone and build (Ubuntu example)
git clone https://github.com/OpenSparX/MasterAgent.git
cd MasterAgent
sudo apt-get install libcurl4-openssl-dev libsqlite3-dev   # optional deps
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel 4
ctest --test-dir build --output-on-failure

# Run the demo (no model needed)
./build/cli/sparx demo automotive
./build/cli/sparx run --input '把空调调到22度'

License – Apache‑2.0.

---

All details above are taken directly from the repository’s README; no additional features are inferred.