feat: scaffold rust llm module controller

2026-07-21 11:10:20 -05:00
commit b445d8a117
23 changed files with 2888 additions and 0 deletions
@@ -0,0 +1,41 @@
+# 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`
+
+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.
+
+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.