instruments
Instrument Plugin System data models.
Defines the config-driven instrument profile system that allows CLI tools to be added as mzt instruments via YAML configuration files, without writing Python backend code.
An InstrumentProfile describes everything Marianne needs to execute prompts through an instrument: identity, capabilities, CLI flags, output parsing, error detection, and model metadata. Profiles are loaded from YAML files in ~/.marianne/instruments/ (organization) and .marianne/instruments/ (venue).
The music metaphor: an instrument is what the musician plays. The profile is the instrument's spec sheet — what it can do, how it's held, what sounds it makes. The musician doesn't need to know how the instrument was built — they just need to know how to play it.
v1: CLI instruments only. HTTP instruments designed for but not implemented. v1.1+: HTTP backends, code-mode techniques.
Classes¶
Bases: BaseModel
A TypeScript interface exposed to agent-generated code.
Part of the code-mode technique system (v1: foundation only, not wired). Instead of sequential MCP tool calls, agents write code against typed interfaces in a sandboxed runtime. Based on Cloudflare's Dynamic Workers pattern — 81% token reduction vs MCP.
Bases: BaseModel
Code-mode technique configuration.
v1: This type exists in the data model but is not wired into execution. The field on InstrumentProfile is populated from YAML but ignored at runtime. v1.1+: A sandboxed runtime (Deno subprocess or Node.js vm) runs agent-generated code against the declared interfaces.
Bases: BaseModel
Per-model metadata for cost tracking and context management.
Each instrument can offer multiple models (e.g., gemini-2.5-pro and gemini-2.5-flash). ModelCapacity records what each model can do and what it costs — used by the conductor for cost tracking, context budget calculation, and instrument selection.
Bases: BaseModel
How to build the CLI command for an instrument.
Maps Marianne execution concepts (prompt, model, auto-approve, output format) to CLI flags. When a field is None, the instrument doesn't support that concept via flags. When prompt_flag is None, the prompt is passed as a positional argument.
Bases: BaseModel
How to parse CLI output into an ExecutionResult.
Three output modes: - text: stdout is the result, no structured extraction - json: parse stdout as JSON, extract via dot-path - jsonl: split stdout into JSON lines, find completion event
Bases: BaseModel
How to detect errors from CLI instrument output.
Supplements Marianne's existing ErrorClassifier with instrument-specific patterns for rate limit detection and auth error recognition.
Bases: BaseModel
Everything needed to invoke a CLI instrument and parse its output.
Composed of three concerns: - command: how to build the CLI invocation - output: how to parse the result - errors: how to detect failures
Bases: BaseModel
HTTP instrument profile. Designed for, not implemented in v1.
Covers OpenAI-compatible, Anthropic API, and Gemini API endpoints. One HTTP handler will cover most of them via schema_family.
Bases: BaseModel
Everything Marianne needs to execute prompts through an instrument.
This is the top-level type for the instrument plugin system. Each instrument profile describes a CLI tool or HTTP API that Marianne can use as a backend. Profiles are loaded from YAML files and validated by Pydantic at conductor startup.
The profile carries: - Identity (name, display_name, kind) - Capabilities (what the instrument can do) - Models (what models are available, their costs and limits) - Execution config (CLI flags or HTTP endpoints) - Code-mode technique config (foundation — not wired in v1)