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"}'
• 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.