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,69 @@
+# AGENTS.md
+
+## Project
+
+`mp-ai-module-controller` is a Rust CLI scaffold for local llama.cpp-driven action dispatch. It starts a local `llama-server`, generates an action dictionary for small-model training and runtime lookup, queries the server through its OpenAI-compatible chat endpoint, and dispatches exact-match Rust scripts.
+
+## Commands
+
+- Build: `cargo build`
+- Test: `cargo test`
+- Generate dictionary: `cargo run -- dictionary generate`
+- Start llama.cpp: `cargo run -- serve`
+- Query local model: `cargo run -- query "log hello from codex"`
+- Direct proof-of-concept dispatch: `cargo run -- run logger --payload '{"message":"hello from codex"}'`
+- Codex setup: `scripts/codex-setup.sh`
+- Codex logger smoke test: `scripts/codex-run-logger.sh`
+- Precommit/CI check: `scripts/precommit-check.sh`
+
+## Environment
+
+Configuration is read from environment variables:
+
+- `LLAMA_MODEL_PATH`: required GGUF model path for `cargo run -- serve`.
+- `LLAMA_HOST`: llama.cpp host. Default: `127.0.0.1`.
+- `LLAMA_PORT`: llama.cpp port. Default: `8080`.
+- `LLAMA_CONTEXT_SIZE`: optional value passed as `--ctx-size`.
+- `LLAMA_EXTRA_ARGS`: optional shell-split arguments appended to `llama-server`.
+- `CONTROLLER_LOG_LEVEL`: tracing log level. Default: `info`.
+
+Use `.env` for local values and keep it out of git. Update `.env.example`, `README.md`, `manifest.llm.json`, and `llm.txt` when environment variables or commands change.
+
+## Dictionary Rules
+
+- `src/registry.rs` is the source of truth for action definitions.
+- `dictionary/actions.jsonl` is generated canonical training data.
+- `dictionary/actions.index.json` is the generated runtime lookup file.
+- Regenerate dictionary files with `cargo run -- dictionary generate` after changing registered actions.
+- Do not manually edit generated dictionary files.
+
+## Dispatch Rules
+
+- Dispatch only exact `action_id` values present in `dictionary/actions.index.json`.
+- Aliases and intent examples are training hints only; they are not executable ids.
+- Unknown, malformed, ambiguous, missing, or empty action ids must be rejected without running scripts.
+- Script processes are detached. The controller spawns them and does not monitor completion.
+- Keep script payload validation strict and local to the script module.
+
+## Generated Paths
+
+- `target/`
+- `logs/`
+- `runtime/`
+- `dictionary/actions.jsonl`
+- `dictionary/actions.index.json`
+
+## CI And Hooks
+
+- Gitea Actions workflow lives at `.gitea/workflows/ci.yml`.
+- Woodpecker workflow lives at `.woodpecker.yml`.
+- The committed pre-commit hook lives at `.githooks/pre-commit`.
+- Configure local hooks with `git config core.hooksPath .githooks`.
+- All CI and pre-commit checks should call `scripts/precommit-check.sh` so dictionary generation stays validated consistently.
+
+## Coding Guidelines
+
+- Keep the CLI Rust-first and small.
+- Prefer adding scripts under `src/scripts/` and registering them in `src/registry.rs`.
+- Add focused tests for parsing, dictionary generation, action lookup, and payload validation.
+- Run `cargo test` before handing off code changes.