Docs navigation
Docs / SquillaRouter

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_model strategy. 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 with squilla_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:

TierOpenRouterTokenRhythm
C0qwen/qwen3.7-flashqwen3.7-flash
C1deepseek/deepseek-v4-flashdeepseek-v4-flash-0731
C2deepseek/deepseek-v4-prodeepseek-v4-pro-0813
C3moonshotai/kimi-k3kimi-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.

GoalSuggested mode
General personal-agent userecommended
Multi-provider cost optimization through OpenRouteropenrouter-mix
Provider evaluation, billing audit, or reproducible benchmark rundisabled
Debugging one provider-specific behaviordisabled

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:

  1. Confirm the router is enabled:

    opensquilla config get router.enabled
    opensquilla config get llm.provider
  2. Check provider readiness:

    opensquilla providers status
    opensquilla doctor
  3. 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 libomp from Homebrew:

    brew install libomp
    opensquilla gateway restart
  4. 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

Edit this page on GitHub OpenSquilla docs · synced from main