mp-ai-module-controller/llm.txt

# mp-ai-module-controller

Rust CLI for local llama.cpp action dispatch with verbose and compact dictionary-coded model outputs.

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`.
- `dictionary/static-base.json`: tracked static compact-code base.
- `dictionary/model.codebook.json`: generated compact codebook.
- `dictionary/model.examples.jsonl`: generated templates/examples for future synthetic-data tooling.
- `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"}'`
- `cargo run -- run calculate --payload '{"expression":"2 + 2 * 3"}'`
- `cargo run -- run to_slug --payload '{"text":"Hello, World!"}'`
- `cargo run -- run write_note --payload '{"filename":"hello.txt","content":"hello"}'`
- `scripts/codex-setup.sh`
- `scripts/codex-run-logger.sh`
- `scripts/precommit-check.sh`
- `scripts/generate_training_data.py --dry-run`
- `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 may return verbose JSON like `{"action_id":"logger","payload":{"message":"hello"}}` or compact codebook JSON like `{"v":"1.0.0","c":"<codebook_checksum>","a":"A001","p":{"F001":"hello"}}`. Compact outputs must match `dictionary/model.codebook.json` version and checksum before expansion. 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.

Registered suites:

- Math & Conversion: `calculate`, `convert_units`, `generate_uuid`, `random_number`.
- Text Utilities: `count_words`, `to_slug`, `hash_string`, `truncate_text`.
- File Operations: `write_note`, `append_to_file`, `read_file`, `delete_file`.
- Logger: `logger`.

File operations are sandboxed to project-local `notes/`.

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.

SDG bridge: `scripts/generate_training_data.py` reads `dictionary/actions.index.json`, `dictionary/model.codebook.json`, and `dictionary/model.examples.jsonl`, then writes instruction-format datasets to `../workspace_Data/data/module_controller_intents_<unix_ts>/` and patches `../workspace_Data/manifest.llm.json`. Use `--dry-run` to validate without writes. Optional Mimir expansion requires `--sdg-host`, `--sdg-user`, and `--sdg-key`; failed remote expansion leaves local seeds and writes `SDG_ERROR.txt`.