# mp-ai-module-controller

Rust controller for starting a local `llama.cpp` server, asking it to map natural-language requests to known local actions, and dispatching exact-match Rust scripts. It supports both verbose action JSON and compact dictionary-coded outputs for hypersmall local models.

## Setup

```sh
cp .env.example .env
# edit LLAMA_MODEL_PATH in .env
cargo build
cargo run -- dictionary generate
git config core.hooksPath .githooks
```

The controller expects `llama-server` from `llama.cpp` to be installed. On this machine the planned binary is `/opt/homebrew/bin/llama-server`; if that path is not present, the controller falls back to `llama-server` on `PATH`.

## Commands

```sh
cargo run -- dictionary generate
cargo run -- serve
cargo run -- query "log hello from codex"
cargo run -- run logger --payload '{"message":"hello from direct dispatch"}'
scripts/precommit-check.sh
```

`serve` starts:

```sh
llama-server --model "$LLAMA_MODEL_PATH" --host "$LLAMA_HOST" --port "$LLAMA_PORT"
```

Optional environment variables:

- `LLAMA_CONTEXT_SIZE`: appended as `--ctx-size`.
- `LLAMA_EXTRA_ARGS`: shell-split and appended to `llama-server`.
- `CONTROLLER_LOG_LEVEL`: tracing log level, default `info`.

## Dictionary

Run `cargo run -- dictionary generate` to create:

- `dictionary/actions.jsonl`: canonical training dictionary, one action record per line.
- `dictionary/actions.index.json`: compact runtime lookup index.
- `dictionary/model.codebook.json`: static-plus-adaptive compact codebook.
- `dictionary/model.examples.jsonl`: hand-authored examples/templates for future synthetic-data tooling.

`dictionary/static-base.json` is the tracked static base dictionary. Generated metadata includes `dictionary_version`, `registry_checksum`, `static_base_checksum`, and `codebook_checksum`.

The runtime only dispatches exact `action_id` matches from `actions.index.json`. Aliases and examples are training hints, not executable ids. Compact model outputs must match the generated codebook version and checksum before expansion.

## LLM Response Contract

The local model must return compact JSON:

```json
{"action_id":"logger","payload":{"message":"hello"}}
```

It may also return compact codebook JSON:

```json
{"v":"1.0.0","c":"<codebook_checksum>","a":"A001","p":{"F001":"hello"}}
```

Malformed JSON, missing action codes, stale versions/checksums, aliases, and unknown action ids are rejected without running anything.

## Initial Script

The first registered script is `logger`. It writes JSONL records to `logs/controller-actions.jsonl`. Dispatch is detached: after the controller spawns the script process, it does not monitor completion.

## CI And Hooks

The project includes:

- `.codex/environments/environment.toml` for Codex setup and run actions.
- `.gitea/workflows/ci.yml` for Gitea Actions.
- `.woodpecker.yml` for Woodpecker.
- `.githooks/pre-commit` for local pre-commit checks.
- `scripts/precommit-check.sh` as the shared validation entrypoint.

Enable the hook after cloning:

```sh
git config core.hooksPath .githooks
```