feat: scaffold rust llm module controller

README.md

@@ -0,0 +1,75 @@
+# mp-ai-module-controller
+
+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
+
+```sh
+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
+
+```sh
+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:
+
+```sh
+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:
+
+```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:
+
+- `.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:
+
+```sh
+git config core.hooksPath .githooks
+```