OpenSparX/MasterAgent

An embeddable, local-first C++17 agent runtime: turn input into validated tool execution, with deterministic skills before model inference.

0.4.0-alpha.3 — open reference runtime with contextual tools and durable receipts. Public source now builds a working sparx CLI and an installable C++ SDK. This is a small synchronous runtime, not the proprietary durable kernel described by the legacy interfaces.

中文：开源版现可独立构建、运行，并作为 C++ SDK 集成。先匹配确定性技能，再按需调用模型； 工具名称和参数必须通过校验。默认使用内存；显式启用 SQLite 后，支持跨重启请求去重、历史恢复、UNKNOWN 故障恢复和人工对账。

Requires CMake 3.18+, C++17, and libcurl development files for the optional HTTP adapter, plus SQLite development files for durable storage. Tests/packaging require Python 3. The release CI targets Linux and macOS.

git clone https://github.com/OpenSparX/MasterAgent.git
cd MasterAgent
# Ubuntu HTTP dependency: sudo apt-get install libcurl4-openssl-dev libsqlite3-dev
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel 4
ctest --test-dir build --output-on-failure
./build/cli/sparx demo automotive

The demo sets an in-memory simulated AC temperature, then reads it back. It needs no model, credentials, network, or vehicle hardware. Each output is JSON.

./build/cli/sparx run --input '把空调调到22度'
./build/cli/sparx run --input 'vehicle status'

Each process starts a new demo state. To preserve state between requests in a single process, run sparx run and enter one input per line until EOF. An unmatched phrase returns NO_ROUTE unless a model is explicitly configured.

Start a compatible llama-server separately with your chosen GGUF model, then:

./build/cli/sparx run --endpoint 127.0.0.1:8080 --model local \
  --input 'Set the AC to 24 degrees'

The adapter sends non-streaming /v1/chat/completions requests. The runtime asks for a JSON response or a single tool call, rejects unknown tools and invalid arguments, and returns the actual tool result. Model compliance depends on the model; malformed output produces an error, never a guessed tool call. No model is downloaded or started by this CLI. A full HTTP(S) endpoint URL may also be provided explicitly; no cloud fallback happens automatically.

A request timeout can be set with --timeout-ms 3000. To use an authenticated endpoint, pass the environment-variable name via --api-key-env MODEL_API_KEY; credentials are not supplied as CLI arguments.

For an SDK and deterministic CLI without libcurl:

cmake -S . -B build-offline -DMASTER_AGENT_ENABLE_HTTP=OFF -DBUILD_EVAL=OFF
cmake --build build-offline --parallel 4

./build/cli/sparx run --state ./state/agent.db --session alice --request-id ac-001 \
  --input 'set AC to 22 degrees'
./build/cli/sparx recover --state ./state/agent.db

Repeating the same request after restarting returns the recorded outcome without calling the tool again. Unfinished requests become UNKNOWN, require external verification, and can be explicitly reconciled. A database failure blocks further execution instead of silently switching to memory. See the recovery guide for JSONL input, ownership locks, audit notes, backups and failure behavior.

Only execution receipts/history are persisted; the AC simulator itself still resets on process restart. There is no transaction spanning a real device and SQLite, so this is not a distributed exactly-once guarantee. Storage is not encrypted.

To omit both optional dependencies, build with MASTER_AGENT_ENABLE_HTTP=OFF and MASTER_AGENT_ENABLE_STORAGE=OFF.

cmake --install build --prefix "$PWD/install-sdk"
cmake -S examples/reference_agent -B build-consumer \
  -DCMAKE_PREFIX_PATH="$PWD/install-sdk"
cmake --build build-consumer
ctest --test-dir build-consumer --output-on-failure

Consumer CMake:

find_package(MasterAgent CONFIG REQUIRED)
target_link_libraries(your_app PRIVATE MasterAgent::Core)
# Optional HTTP adapter:
# target_link_libraries(your_app PRIVATE MasterAgent::Http)

The public reference API is in reference_runtime.h. Register a tool with a supported parameter schema and callback, register exact phrase skills, optionally set a model callback, then call Runtime::run(). See the integration contract for errors, schema support, sessions, request replay, and concurrency limitations.

Context-aware tools receive the session/request identity, a stable scoped idempotency key, deadline and cooperative cancellation signal. They return an explicit committed, failed or unknown outcome. The existing registerTool() API remains available. See the execution contract.

The inventory example talks to a separate HTTP service that commits inventory and an idempotency receipt in its own SQLite database. Its integration test deliberately drops a response after commit, checks UNKNOWN recovery, reconciles against the service receipt and proves no second stock decrement after either process restarts. This is a local business-service integration example, not a real-model or third-party production validation.

Other headers under include/master_agent/ describe legacy kernel contracts; including them does not mean their factories have public implementations. Use master_agent::reference for the supported open runtime entry point.

ctest --test-dir build --output-on-failure
bash eval/run_all.sh
bash scripts/package.sh build dist/sparx-sdk.tar.gz

Evaluations use synthetic workloads (learning includes a simulated model), not end-to-end evidence for real-model latency, personalization, or NPU performance. Results are written to build/eval-results/. Missing or failed evaluations return a nonzero status. BUILD_EVAL=OFF excludes them from an SDK-only build.

The package script installs the SDK and CLI, unpacks the archive in a new location, runs the demo, and builds an external consumer before publishing the archive. The archive also includes the inventory example; HTTP/storage-enabled packages build and exercise it after unpacking. The archive includes BUILD_INFO.json and a SHA-256 sidecar. The package uses platform system dependencies, including libcurl and SQLite when enabled; it is not a universally static binary.

See CONTRIBUTING.md. Changes must keep Release assertions active and pass the CLI, HTTP protocol fixture, installed consumer, and runtime failure tests. Hardware and actual model validation should record the model, quantization, device, workload, and latency distribution separately.

Apache-2.0. See LICENSE.