# 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"}'`
- 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`

## 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.
- 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`.

## 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.

## Generated Paths

- `target/`
- `logs/`
- `runtime/`
- `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.
- Run `cargo test` before handing off code changes.