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.