Query Router#

Routes every query to its best-fit model using three routing strategies combined:

1. Prefix routing — explicit user intent ( @codex, @mini, etc.)
2. Content-type detection — auto-detect vision/voice/tool/code/reasoning/qa
3. Complexity scoring — simple/moderate/complex tier routing

Usage#

Classify only#

bash

python3 skills/query-router/scripts/classify.py [--json] [--attachment .ext] <query>

Route (classify + switch model)#

bash

python3 skills/query-router/scripts/router.py [--json] [--dry-run] [--attachment .ext] <query>

Safety & Audit#

bash

python3 skills/query-router/scripts/router.py --check           # list available models
python3 skills/query-router/scripts/router.py --audit            # show recent routing log
python3 skills/query-router/scripts/router.py --no-lock          # disable lock protection
python3 skills/query-router/scripts/router.py --dry-run --no-verify  # preview without verify

Library usage#

python

from router import route_query

result = route_query(
    query="@codex write a complex python script",
    has_attachment=False,
    attachment_ext="",
    dry_run=True,       # True = preview, False = actually switch
    enable_lock=True,   # prevent concurrent routing
    enable_verify=True, # readback verify after switch
    enable_rollback=True,  # revert on failure
)
print(result["action"])        # route | recommend | skip | blocked
print(result["to_model"])      # recommended model name
print(result["classification"]) # full classification details

Routing Priority#

PrioritySignalExampleBehavior1Prefix@codex write a scriptForce switch to @codex model2Content-type (≥60%% conf)describe this imageAuto-switch to vision model3Complexity (<60%% conf)analyze Q3 dataRoute by complexity tier4Skip (<30%% conf)hi how are youKeep current model

Prefix Routing#

PrefixModelAliases@codex``openai-codex/gpt-5.3-codex``@c``@mini``minimax-m2.7:cloudCloud primary@cl``qwen3-coder-next:cloudCloud code@q``minimax-m2.7:cloudCloud fast Q&A@llava``qwen3.5:cloudCloud vision@whisper``whisper—

Content Types#

TypeDetected ByBest ModelvisionImage attachment or "describe/identify"qwen3.5:cloudvoiceAudio file or "transcribe/speech-to-text"whispertoolrun, fetch, send, check, syncminimax-m2.7:cloudcodescript, function, import, debugqwen3-coder-next:cloudreasoninganalyze, compare, plan, thinkminimax-m2.7:cloudqawhat is, how does, defineminimax-m2.7:cloud

Complexity Tiers#

TierPatternModelsimplegreetings, one-liners, short questionsminimax-m2.7:cloudmoderateemails, analysis, search, translateminimax-m2.7:cloudcomplexmulti-file code, deep research, architectminimax-m2.7:cloud

Safety Features#

• Lock protection — prevents concurrent routing ops ( fcntl)
• Verify-after-switch — confirms model actually changed
• Rollback — reverts to previous model on failure
• Audit log — JSONL log at scripts/.logs/router.log.jsonl

Merged Approaches#

SourceTechniqueopenclaw-model-router-skillPrefix syntax @codex/@mini, lock + verify + rollbacktask-complexity-routerComplexity tier scoring (simple/moderate/complex)query-router (original)Content-type detection (vision/voice/tool/code/qa)

All three combined into one unified router with confidence-based priority.