mp-ai-module-controller/llm.txt

# mp-ai-module-controller

Rust CLI for local llama.cpp action dispatch.

Important files:

- `src/main.rs`: CLI entrypoint.
- `src/registry.rs`: source-of-truth action registry.
- `src/dictionary.rs`: generates `dictionary/actions.jsonl` and `dictionary/actions.index.json`.
- `src/llm.rs`: sends OpenAI-compatible chat requests to the local llama.cpp server and parses action JSON.
- `src/dispatcher.rs`: exact-match runtime dispatch and detached script spawning.
- `src/scripts/logger.rs`: proof-of-concept logger script.
- `AGENTS.md`: agent instructions.
- `manifest.llm.json`: machine-readable project metadata.
- `.env.example`: environment variable template.

Commands:

- `cargo build`
- `cargo test`
- `cargo run -- dictionary generate`
- `cargo run -- serve`
- `cargo run -- query "log hello from codex"`
- `cargo run -- run logger --payload '{"message":"hello from codex"}'`
- `scripts/codex-setup.sh`
- `scripts/codex-run-logger.sh`
- `scripts/precommit-check.sh`
- `git config core.hooksPath .githooks`
- `.codex/environments/environment.toml`

Environment:

- `LLAMA_MODEL_PATH`: required for `serve`; local GGUF model path.
- `LLAMA_HOST`: default `127.0.0.1`.
- `LLAMA_PORT`: default `8080`.
- `LLAMA_CONTEXT_SIZE`: optional `--ctx-size`.
- `LLAMA_EXTRA_ARGS`: optional extra llama-server args.
- `CONTROLLER_LOG_LEVEL`: default `info`.

The LLM must return compact JSON like `{"action_id":"logger","payload":{"message":"hello"}}`. The runtime only executes exact `action_id` matches from `dictionary/actions.index.json`; aliases are not executable. Invalid or unknown outputs are rejected without running anything.

Codex environment: `.codex/environments/environment.toml` defines setup plus Build, Test, Generate Dictionary, Precommit Check, Run Logger, Query Logger, and Serve Llama actions.

CI and hooks: `.gitea/workflows/ci.yml`, `.woodpecker.yml`, and `.githooks/pre-commit` all use `scripts/precommit-check.sh` to verify formatting, tests, and dictionary generation.