> ## Documentation Index
> Fetch the complete documentation index at: https://songbird.studiocollective.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# songbird-agent

# songbird-agent

Agentic orchestration for Songbird's copilot: single converged pipeline with
complexity-based model tier routing and multi-round tool execution.

## What it owns

* Prompt complexity classification (ML-based with heuristic fallback)
* MiniLM-L6-v2 embedding + logistic regression head for simple/complex routing
* Model tier selection: Simple → Speed (fast, no thinking) / Complex → Thinker (reasoning, planning)
* Intent classification for tool filtering (Chat, BirdEdit, Mixer, etc.)
* DAW tool registry (maps agent actions to sync-engine commands)
* Chat orchestrator for streaming multi-round conversations with tool execution

## Architecture

```text theme={null}
User prompt
  → classify_complexity() → Simple | Complex
  → select model tier    → Speed (flash-lite) | Thinker (pro + thinking)
  → classify_intent()    → filter tool subset
  → streaming LLM call   → text/thinking/tool-call events
  → tool execution loop   → dispatch via sync engine, feed results back
  → repeat (max 5 rounds) or complete
```

## Classification

The classifier routes user prompts to Speed (simple) or Thinker (complex):

* **ML path** (`ml-classifier` feature): MiniLM-L6-v2 sentence embeddings → trained logistic regression head. \~15ms on CPU. Trained on 345 synthetic DAW prompts (196 simple, 149 complex) with 100% test accuracy.
* **Heuristic fallback**: keyword pattern matching against the tool registry. Used when the MiniLM model isn't available.

Weights are bundled at compile time via `include_bytes!` (`models/classifier_weights.bin`).

## Public API

* `ChatOrchestrator` — primary entry point: classify complexity/intent, streaming multi-round chat with tool execution
* `ModelTier` — Speed (fast) or Thinker (reasoning) tier, selected by complexity classification
* `Complexity` — Simple or Complex, from the classifier
* `AgentConfig` — model assignments, planner depth, thinking settings, fallback routing
* `ChatOrchestrationResult` — content, thinking, tool calls executed, model, rounds
* `RoundOutcome` — Complete / NeedsToolResults / Error
* `OrchestratorEvent` — streaming events (TextDelta, ThinkingDelta, ToolCallRequested, Done, Error)
* `ToolRegistry` — DAW tool definitions with intent-based filtering and sync-engine command mappings
* `AgentPipeline` — **deprecated**, retained as reference for future local-model planner integration

## Feature flags

* `ml-classifier` (default): enables MiniLM embedding-based classification. Requires `songbird-inference/embeddings`.

## Where tests live

`cargo test -p songbird-agent` — classifier accuracy, weight parsing, plan parsing, tool registry, orchestrator, model tier routing.