70 lines
3.0 KiB
Markdown
70 lines
3.0 KiB
Markdown
# 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 an action dictionary for small-model training and 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`
|
|
|
|
## 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 action definitions.
|
|
- `dictionary/actions.jsonl` is generated canonical training data.
|
|
- `dictionary/actions.index.json` is the generated runtime lookup file.
|
|
- Regenerate dictionary files with `cargo run -- dictionary generate` after changing registered actions.
|
|
- Do not manually edit generated dictionary files.
|
|
|
|
## Dispatch Rules
|
|
|
|
- Dispatch only exact `action_id` values present in `dictionary/actions.index.json`.
|
|
- 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`
|
|
|
|
## CI And Hooks
|
|
|
|
- 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 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.
|