Skip to main content

Model Routing

Paddles separates the planner and synthesizer into distinct roles, each routable to a different model. This lets operators match each workload to the smallest model that excels at it.

Two Roles​

RoleWhat it doesOptimized for
PlannerRecursive investigation: search, read, refine, branchTool use, multi-step reasoning, evidence gathering
SynthesizerFinal answer from evidence bundleAnswer quality, grounding, citation

By default, both roles use the same model. The --planner-model flag overrides the planner independently.

Current Model Lanes​

ModelRoleNotes
qwen-1.5bDefault synthesizer and plannerLightweight, fast inference
qwen3.5-2bOpt-in planner or synthesizerHeavier, better multi-step reasoning
qwen-coder-0.5b/1.5b/3bCoding-oriented variantsOptimized for code-heavy workloads
sift-directGatherer backendDirect local retrieval for search/refine actions
context-1Experimental boundarySpecialized planner/gatherer, fail-closed until ready

Search Contract Parameters​

search and refine planner actions share a gatherer contract that controls retrieval depth and strategy:

  • mode: linear or graph
  • strategy: lexical (BM25) or hybrid (BM25 + vector + RRF)
  • step_limit: per-call retrieve budget
  • max_items / max_snippet_chars / max_summary_chars: evidence bundle caps
  • retained_artifact_limit: number of retained artifacts preserved for planner trace

Current defaults are documented on the Search and Retrieval page.

Multi-Provider Support​

Paddles supports multiple HTTP API providers alongside local models:

  • OpenAI-compatible APIs
  • Anthropic API
  • Gemini API

Each provider is accessed through the same synthesizer or planner contract. Credentials are managed per-provider through the TUI login flow or environment variables.

Routing In Practice​

A lightweight synthesizer with a heavier planner:

paddles --model qwen-1.5b --planner-model qwen3.5-2b

A remote synthesizer with a local planner:

paddles --model kimi-k2.6 --planner-model qwen3.5-2b

The harness degrades gracefully — if a remote provider is unavailable, the turn fails closed with a clear error rather than producing an ungrounded answer.