SquillaRouter
SquillaRouter is OpenSquilla’s local model-routing layer. It helps the agent choose an appropriate model tier for each turn so routine work does not always run on the most expensive model.
Use this page when you want to enable routing, understand what it changes, or decide whether a fixed provider/model is better for a specific run.
Why Use It
SquillaRouter is useful when you want:
- lower cost for simple chat, edits, summaries, and routine tool work;
- stronger models reserved for hard reasoning, recovery, and long tasks;
- one OpenSquilla workflow that can route across provider profiles;
- local routing decisions without sending prompts to a separate external classifier just to choose the model.
It is not required. OpenSquilla can also run in direct single-model mode.
Base Model and Memory
Routing defaults to the packaged BERT-60M INT8 intent and LightGBM tier classifiers with
strategy = "lightgbm_model" and tier_policy = "model". An explicit
squilla_router.lightgbm_model_dir must contain the same verified model bundle.
squilla_router.v4_bundle_dir applies only to the explicit legacy_v4_phase3
strategy. Router self-learning and its feedback submission API have been removed. On upgrade,
the obsolete squilla_router.self_learning settings are discarded automatically;
credentials, model tiers, explicit model paths, and Dream settings are preserved.
A failed automatic config backup or rewrite does not prevent loading the migrated
settings in memory. Explicit save failures still report an error.
Historical learned-model pointers, samples, and training directories are left in place and are no longer read. Model choices may therefore differ from a previously personalized model. Routing diagnostics and manual model selection remain available. The model policy handles a classified correction or explicit Redo as a one-tier advance within the current task.
For an active task without an explicit intent control, the policy selects Redo
when p_redo >= 0.25 and p_redo > p_new; otherwise it selects New Task when
p_new >= 0.01, and Continue below that threshold. These thresholds change the
final intent, not the model probabilities. Audits retain the raw argmax prediction
and its confidence, and mark changed decisions with intent_thresholds_v1.
The first turn remains New Task; only explicit New Task resets context.
Tier classification uses only the current request text. Historical user messages, previous answers and usage, task anchors, route history, and historical context estimates do not enter its features. BERT intent classification retains that context. Continue and Redo keep their existing tier transition rules, and the actual provider request still uses the session’s normal context.
Chat thumbs up/down rate the answer independently of routing. Selections are kept only for the current page and reset on reload; they are not submitted or used for training. Clicking the selected thumb again clears it.
Memory Dream runs independently. Saving its enabled state or schedule reconciles its scheduled jobs; if that cannot take effect live, settings report that a restart is required. Dream’s preview and memory-writing behavior are unchanged.
Upgrading to the Model Policy
The BERT intent upgrade replaces the former LightGBM intent bundle. If you set
squilla_router.lightgbm_model_dir to a copy of the old bundle, remove that setting
to use the packaged models, or replace the entire external directory with the
current verified BERT intent + LightGBM tier bundle (including its shared BGE
resources). Mixing old manifests with new weights is not supported. A recognized
old bundle produces this migration guidance at startup; it is never loaded
silently or substituted without changing your explicit setting.
Saved strategy = "v4_phase3" configurations now load as lightgbm_model.
An omitted strategy also selects the new default. An explicitly disabled router
stays disabled. Check custom ladders and budget expectations before enabling the
new path; the following behavior changes apply even to an existing V4 configuration:
- A new task uses the tier classifier. Continue keeps the last admitted tier;
Redo advances it by one, capped at C3. Explicit New Task starts a new context
generation. BERT-60M INT8 classifies intent; the unchanged LightGBM model
classifies tiers. Both run locally under the existing
lightgbm_modelstrategy. When that generation exceeds the request window, the existing summarizer first condenses its own history under the configured budget. The summary is request-local: it neither reads an older task’s checkpoint nor rewrites the full transcript. With summarization disabled or unavailable, the temporary window still reports omitted history; repeated long requests may need to summarize again. - Confidence, probability-margin, difficulty, continuity, and initial budget-cap heuristics do not rewrite the selected tier. In particular, the existing router budget configuration does not demote or cap the initial model-policy choice. A quality retry still checks the current budget before advancing.
- Each tier executes one configured model; the model policy does not enter C3 Ensemble. For current, historical, or tool-produced images, execution checks the selected tier and then later C0–C3 tiers in order for proven image support, subject to capacity, budget, credentials, and provider continuity. This changes neither the configured order nor the admitted semantic tier. If no visual candidate is usable, the original target uses the existing text-marker projection; unknown capability retains the bounded native-image probe. Original image attachments remain intact, and marker projection adds no frontend notification. Other capability and request-admission checks remain authoritative. Quality retries record semantic and physical tiers separately.
- Reasoning capability is required only when the effective request enables
thinking. Explicit
llm.thinking = "off"remains authoritative, including withsquilla_router.auto_thinking = false. - A validation failure or repeated tool calls without progress can request one
quality upgrade. The complete target request must pass admission before its
tier is committed. Quality and transport retries share a maximum of three
additional provider calls, further bounded by
max_provider_retries. Supported stream-to-non-stream recovery and Codex credential refresh remain available before response output: the coordinator reserves the same allowance before retrying, with at most one credential refresh per request. Child agents have an independent allowance with the same configured bound; they do not inherit the parent’s routing state or quality-upgrade callback. - Missing or invalid model assets fail closed. Source checkouts must hydrate Git LFS model weights before starting the Gateway. Packaged builds validate the same frozen asset hashes.
To retain the prior routing behavior while reviewing this migration, explicitly set:
[squilla_router]
strategy = "legacy_v4_phase3"
To turn off routing altogether, use enabled = false in that section. Direct and
explicit Ensemble modes retain their own configuration; the single-model rule
above describes the new model-policy router.
Enable Routing
Recommended first-run setup:
opensquilla onboard --router recommended
Reconfigure an existing install:
opensquilla configure router --router recommended
Use the OpenRouter mixed defaults:
opensquilla configure router --router openrouter-mix
OpenRouter and TokenRhythm use the following recommended single-model tiers:
| Tier | OpenRouter | TokenRhythm |
|---|---|---|
| C0 | qwen/qwen3.7-flash | qwen3.7-flash |
| C1 | deepseek/deepseek-v4-flash | deepseek-v4-flash-0731 |
| C2 | deepseek/deepseek-v4-pro | deepseek-v4-pro-0813 |
| C3 | moonshotai/kimi-k3 | kimi-k3 |
The TokenRhythm ladder leaves tier thinking_level unset. Direct
requests without an explicit thinking setting preserve the provider default;
Router auto-thinking can still choose a per-turn level (normally low on C1).
Fresh and managed (preset_binding = "follow_primary") configurations receive
this ladder. The one-time configuration version 2 migration replaces old text
tiers with the saved primary provider’s recommended ladder when that primary is
OpenRouter or TokenRhythm. This includes custom and mixed text tiers from 0.5.4.
The migration preserves the routing mode, primary credentials, and other router
controls, and backs up the previous configuration before writing. Custom edits
made after this migration remain intact on subsequent loads.
OpenRouter retains high as its packaged tier thinking level.
Setting OpenRouter or TokenRhythm as primary also applies that provider’s recommended text tiers while preserving the current usage mode. The saved primary summary and recommended-tier button use the same primary provider. The reset button replaces the current ladder with that provider’s recommendation, including saved or unsaved custom tiers. Other primary providers do not show this shortcut. Restoring tiers keeps the current usage mode.
OpenRouter and TokenRhythm recommendations are checked in the background at each Gateway startup, including Desktop restarts, and every 24 hours while it stays running. A cached recommendation remains available during the check or if the request fails. Disabling background network checks in privacy settings also disables these checks.
The settings page announces a new recommendation only when its model selections change: the provider, model, or assigned tier/role. Thinking-level changes alone do not trigger an update notice. You can still preview and explicitly adopt the complete recommendation, including its thinking settings. Downloading a recommendation never replaces saved models automatically; confirmed changes apply to newly accepted tasks.
Saving explicit provider and model selections for executable text tiers enables
cross-provider routing automatically. Each selected provider uses its own configured
profile; no additional settings switch is needed. This also applies when saving an
existing mixed tier table after an upgrade. An explicit crossProviderTiers: false
API option remains authoritative.
Loading saved settings, switching the primary provider, or re-enabling routing without submitting tier selections does not enable cross-provider execution. Existing primary-switch and legacy-router conflict checks still apply. Dormant single-model settings under a static C3 fusion plan do not enable it either.
Legacy V4 Deployment Behavior
The following fusion and image-fallback behavior applies to legacy_v4_phase3.
C3 can optionally use the shared multi-model fusion plan configured under
llm_ensemble. Enabling fusion on C3 makes it use that plan instead of its
single-model route. If the plan falls back to a single model, it uses the global
provider/model configured under [llm].
For a newly configured C3 fusion tier, the tier-local runtime-policy defaults are one
successful proposer out of the four-member lineup, one retry after each
proposer’s initial attempt, and all_failed_policy = "fallback_single". These
defaults fill only fields that the operator has not set. Explicit
min_successful_proposers, proposer_max_retries, and all_failed_policy
values remain authoritative for both global/custom Ensemble use and C3. In
particular, all_failed_policy = "error" is a valid terminal policy and does
not start the fixed fallback. A global/custom configuration with no explicit
retry field keeps the historical zero-retry default.
Packaged static B5 lineups use a 120-second total budget per proposer and a
180-second aggregator idle budget. Operator-authored custom_b5 lineups use
300 and 480 seconds respectively unless explicitly configured otherwise.
Image routing considers only the configured C0–C3 single-model deployments;
C3 fusion is excluded. Image input capability is resolved automatically from
the shared provider model catalog, including API-provided deployment metadata
and offline catalog fallback. The web and desktop clients do not expose a
manual image-capability switch. Legacy tier supports_image values remain
readable but do not override the deployment’s capability, and image_model
is retained for compatibility without creating an executable fifth route.
When capability is unknown, the configured model may receive a native image request. A recognized image-input rejection can advance through the remaining configured tiers before falling back to explicit not-analyzed/analysis-failed text markers. Direct retries only its configured model with markers; Ensemble uses text markers for all members. These retries stop after visible output or tool effects. Projection never deletes the canonical attachment, so switching back to a vision-capable model can recover earlier images after history compression.
Direct Mode
Disable routing and use the configured provider/model directly:
opensquilla configure router --router disabled
Inspect Provider Support
Check the provider catalog available in your install:
opensquilla providers list
If the gateway is running, inspect runtime provider health:
opensquilla providers status
Router-supported profiles depend on the installed OpenSquilla version, optional dependencies, and configured provider credentials. Common profiles include OpenRouter, OpenAI, DeepSeek, Gemini, DashScope, Moonshot, Volcengine, Zhipu, and compatible provider tiers exposed by the local catalog.
What the Router Can Affect
Depending on configuration, SquillaRouter may influence:
- selected model tier;
- direct model fallback in the legacy V4 strategy;
- reasoning level;
- response policy;
- image-capable execution selection and text-marker projection;
- cache-continuity safeguards for recent higher-tier turns in legacy V4.
The exact decision is available through runtime metadata and diagnostics surfaces. Turn on diagnostics when you need to understand why a turn was routed to a particular model:
opensquilla diagnostics on
Terminal Router HUD
Interactive terminal chat can surface routing decisions through a TUI Router HUD when router metadata is present and the selected backend supports the structured UI/plugin surface. In the current implementation, the OpenTUI footer is the primary terminal display for this HUD. The HUD is display-only: it consumes the same turn metadata and does not change model selection.
The HUD can show the selected tier, selected model, baseline model, route source, confidence, estimated savings, fallback state, thinking mode, prompt policy, whether routing was applied, and rollout phase.
Full routing is shown as an active route. Observe-only routing is shown as an observe decision, which means OpenSquilla recorded what the router would have chosen while keeping the configured baseline behavior. Fallback decisions use a warning style so provider or policy recovery is visible during the turn.
Recommended Operating Modes
| Goal | Suggested mode |
|---|---|
| General personal-agent use | recommended |
| Multi-provider cost optimization through OpenRouter | openrouter-mix |
| Provider evaluation, billing audit, or reproducible benchmark run | disabled |
| Debugging one provider-specific behavior | disabled |
For routine use, start with recommended. Disable routing only when the model
choice itself is the thing you are testing.
Example Requests
Good router-friendly requests describe the outcome, not the tier:
Summarize this long issue thread and list the decision points.
Review my current diff and point out the highest-risk changes.
Avoid asking the router to behave like a manual model picker unless you are debugging:
Use exactly this one model for every turn.
For exact-model work, configure direct routing instead.
Troubleshooting
If routing does not appear to work:
-
Confirm the router is enabled:
opensquilla config get router.enabled opensquilla config get llm.provider -
Check provider readiness:
opensquilla providers status opensquilla doctor -
The model policy fails closed on missing dependencies or invalid assets. Install the recommended dependencies and restore the model resources, or explicitly disable routing to use direct single-model execution. On Windows, ONNX Runtime may require the Visual C++ Redistributable. On macOS terminal installs, LightGBM may require
libompfrom Homebrew:brew install libomp opensquilla gateway restart -
If you need deterministic model behavior for a run, disable routing:
opensquilla configure router --router disabled
Docs index · Product guide · Improve this page · Report a docs issue