mp-ai-module-controller/AGENTS.md

# 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 verbose and compact action dictionaries for small-model training/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"}'`
- Direct math dispatch: `cargo run -- run calculate --payload '{"expression":"2 + 2 * 3"}'`
- Direct text dispatch: `cargo run -- run to_slug --payload '{"text":"Hello, World!"}'`
- Direct file dispatch: `cargo run -- run write_note --payload '{"filename":"hello.txt","content":"hello"}'`
- Codex setup: `scripts/codex-setup.sh`
- Codex logger smoke test: `scripts/codex-run-logger.sh`
- Precommit/CI check: `scripts/precommit-check.sh`
- Codex environment: `.codex/environments/environment.toml`
- Training data dry run: `python3 scripts/generate_training_data.py --dry-run`
- Local training data bridge: `python3 scripts/generate_training_data.py`
- Deploy training data to Zoe: `scripts/deploy_training_data.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 executable action definitions.
- `dictionary/static-base.json` is the tracked static compact-code base. Change it only when the compact protocol changes.
- `dictionary/actions.jsonl` is generated canonical verbose training/action data.
- `dictionary/actions.index.json` is the generated verbose runtime lookup file.
- `dictionary/model.codebook.json` is the generated model-facing compact codebook.
- `dictionary/model.examples.jsonl` is generated template/example data for future synthetic-data tooling.
- Registered action suites are Math & Conversion, Text Utilities, File Operations, and Logger.
- Regenerate dictionary files with `cargo run -- dictionary generate` after changing registered actions.
- Do not manually edit generated dictionary files.
- Generated metadata includes `dictionary_version`, `registry_checksum`, `static_base_checksum`, and `codebook_checksum`.

## SDG Bridge Rules

- `SDG_BRIDGE_PLAN.md` documents the local-to-Data-Designer bridge design.
- `scripts/generate_training_data.py` reads generated dictionary artifacts and produces instruction-format seed datasets.
- Default output is `/Volumes/Zoe/custom-local-llm/training-data/module_controller_intents_<unix_ts>/`.
- Default manifest patch target is `/Volumes/Zoe/custom-local-llm/manifest.llm.json`.
- `/Volumes/Zoe/custom-local-llm` has its own `README.md`, `AGENTS.md`, `manifest.llm.json`, and `llm.txt`.
- Use `--dry-run` for validation; it must not write output data or patch manifests.
- Mimir/Data Designer expansion only runs when `--sdg-host`, `--sdg-user`, and `--sdg-key` are all provided.
- Do not start or restart Mimir llama.cpp/Keiro from this bridge.
- If Mimir expansion fails, the bridge keeps the local seed dataset, writes `SDG_ERROR.txt`, patches the manifest with `generated_local_remote_failed`, and exits non-zero.
- Woodpecker deploys training data on main-branch pushes with `scripts/deploy_training_data.sh`.

## Dispatch Rules

- Dispatch only exact `action_id` values present in `dictionary/actions.index.json`.
- Compact model outputs must include matching `v` and `c` values from `dictionary/model.codebook.json` before expansion.
- 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.
- File operation scripts must remain confined to project-local `notes/` paths and reject absolute paths or path traversal.

## Generated Paths

- `target/`
- `logs/`
- `runtime/`
- `notes/`
- `dictionary/actions.jsonl`
- `dictionary/actions.index.json`
- `dictionary/model.codebook.json`
- `dictionary/model.examples.jsonl`

## CI And Hooks

- Codex environment actions live at `.codex/environments/environment.toml`.
- 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 full 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.
- Add stdlib Python tests for bridge behavior in `tests/` when changing `scripts/generate_training_data.py`.
- Run `cargo test` before handing off code changes.