0008. One command model, ready for people, remotes and AI

• Status: accepted
• Date: 2026-10-02

Context

Five features need the same thing: undo/redo, remote control from another device, show control over MIDI/OSC, end-to-end tests of a show, and AI assistants that prepare or run a show. Each of them needs every user action expressed as data that can be described, validated, previewed, applied, recorded and reversed.

AI assistants range from small models running locally (1 to 8 billion parameters, on a laptop or a phone) to large hosted models. Small models struggle with large tool catalogues, free-form JSON, long context, unknown identifiers and multi-step plans. Large models handle all of these and must not be held back.

Decision

1. Every user action is a command: a typed value with a name, a schema, a one-line description, example phrases and a risk level. Cores apply commands; nothing else mutates show state.
2. State is readable as snapshots at a chosen level of detail and within a size budget.
3. The AI layer is an adapter, like JUCE and Tracktion: a protocol adapter (MCP today) and a LanguageModel port (local llama.cpp/ONNX or hosted). Cores know nothing about AI.
4. Small-model first, no ceiling. Every aid for small models is a capability profile setting, never a restriction built into the core:

Aid	Small local model	Large model
command catalogue	only the group of the current context (prepare, live, mixer…)	the whole catalogue
output format	grammar-constrained decoding generated from the schema	native tool calling with the same schema
state given to the model	short summary within a small token budget	full snapshot, larger budget
plans	one command per turn	a plan of many commands, previewed and applied as one transaction
identifiers	names and phrases, resolved by the core	names or identifiers
common phrases	handled first by a deterministic parser, no model call	same parser available, optional

Safety rules are the same for every model: risk levels, preview before apply, human confirmation for destructive or live-sensitive commands during a show, never anything on the audio thread.

5. An evaluation suite (phrases with their expected commands) measures any model against the schema and guards the schema against regressions.

Consequences

• One mechanism serves undo, remotes, show control, tests and AI.
• A show can be run with no model at all (deterministic parser and UI), with a small local model, or with a large one; only quality changes, never the set of features.
• Commands become a public, versioned contract: renaming one is a breaking change and needs a migration.