Rust controller for starting a local llama.cpp server, asking it to map natural-language requests to known local actions, and dispatching exact-match Rust scripts.

Setup

cp .env.example .env
# edit LLAMA_MODEL_PATH in .env
cargo build
cargo run -- dictionary generate
git config core.hooksPath .githooks

The controller expects llama-server from llama.cpp to be installed. On this machine the planned binary is /opt/homebrew/bin/llama-server; if that path is not present, the controller falls back to llama-server on PATH.

Commands

cargo run -- dictionary generate
cargo run -- serve
cargo run -- query "log hello from codex"
cargo run -- run logger --payload '{"message":"hello from direct dispatch"}'
scripts/precommit-check.sh

serve starts:

llama-server --model "$LLAMA_MODEL_PATH" --host "$LLAMA_HOST" --port "$LLAMA_PORT"

Optional environment variables:

LLAMA_CONTEXT_SIZE: appended as --ctx-size.
LLAMA_EXTRA_ARGS: shell-split and appended to llama-server.
CONTROLLER_LOG_LEVEL: tracing log level, default info.

Dictionary

Run cargo run -- dictionary generate to create:

dictionary/actions.jsonl: canonical training dictionary, one action record per line.
dictionary/actions.index.json: compact runtime lookup index.

The runtime only dispatches exact action_id matches from actions.index.json. Aliases and examples are training hints, not executable ids.

LLM Response Contract

The local model must return compact JSON:

{"action_id":"logger","payload":{"message":"hello"}}

Malformed JSON, missing action_id, empty action_id, aliases, and unknown action ids are rejected without running anything.

Initial Script

The first registered script is logger. It writes JSONL records to logs/controller-actions.jsonl. Dispatch is detached: after the controller spawns the script process, it does not monitor completion.

CI And Hooks

The project includes:

.codex/environments/environment.toml for Codex setup and run actions.
.gitea/workflows/ci.yml for Gitea Actions.
.woodpecker.yml for Woodpecker.
.githooks/pre-commit for local pre-commit checks.
scripts/precommit-check.sh as the shared validation entrypoint.

Enable the hook after cloning:

git config core.hooksPath .githooks