auto-router — effort-based local↔cloud routing + fusion

Package scope and prerequisites

This catalog ships instructions, not the executable runtime. Python modules, scripts, local services and optional tools named below must be installed separately from the upstream project. Check their availability before running commands; if they are missing, explain the prerequisite instead of claiming execution or results. The host agent may use model tokens while following these instructions.

Commands, APIs and runtime behavior described below are conditional examples for a compatible upstream installation; they are not evidence of execution in this package.

The upstream workflow estimates task effort and selects among configured backends. Selection depends on available capability, budgets and compatible provider configuration; verify those inputs before routing. Extends tiered_router (cost tiers) and llm_backends (local discovery) with a cloud catalog and ensemble strategies.

When to use

• "Pick local or cloud automatically based on how hard the task is."
• "Use DeepSeek / GLM / Nemotron / Grok / Gemma alongside my local models."
• "Have a local model draft and a stronger model refine" (fusion).
• The user mentions effort routing, model fusion/ensemble, OpenRouter, or any of the cloud providers above.

Auto-decision

python -m skills.auto_router.cli route "classify: bug or feature?"   # example routing query
python -m skills.auto_router.cli route "design a distributed cache and prove correctness"
python -m skills.auto_router.cli run   "summarize this PR in 2 lines" --max-tokens 200
python -m skills.auto_router.cli dry-run .                          # simulate adaptations from session events
python -m skills.auto_router.cli dry-run . --json

Effort is scored from prompt signals (length, code, stack traces, reasoning vs trivial vocabulary, multi-file scope) → a Tier. Tier ≤ LOCAL with a local backend is a candidate for local execution; higher tiers consider configured cloud models and budget settings. Check actual provider access and local capacity. If no compatible backend is available, report the prerequisite instead of assuming a successful fallback.

Cloud providers

python -m skills.auto_router.cli providers   # catalog + which are available now

Data-driven catalog in providers.py — DeepSeek (chat/reasoner), Zhipu GLM, NVIDIA Nemotron, xAI Grok, Google Gemma. Reach them two ways:

• OpenRouter — set OPENROUTER_API_KEY, every model by slug, one endpoint.
• Native — set the provider's own key (DEEPSEEK_API_KEY, XAI_API_KEY, ZHIPUAI_API_KEY, NVIDIA_API_KEY), used in preference to OpenRouter.

The upstream configuration uses keys and catalog entries to identify candidate providers. A configured key does not prove authorization or availability; confirm access and compatible model identifiers before execution.

Fusion (models collaborating)

python -m skills.auto_router.cli fusion cascade "is 17 prime?"            # cheap→escalate
python -m skills.auto_router.cli fusion draft   "explain the CAP theorem" # local drafts, cloud refines
python -m skills.auto_router.cli fusion vote    "capital of France, one word?"  # consensus

• cascade — local/cheap first; escalate to a stronger model only if the answer looks low-confidence.
• draft_refine — local model drafts, a stronger cloud model polishes. This is the "local + cloud together" mode.
• vote — several models answer; return the consensus (great for classification).

Fusion requires compatible configured backends. With no cloud access, inspect whether the installed implementation supports a suitable local-only path; otherwise report the missing prerequisite.

MCP

Exposed via [[llm-mcp]] as tools auto_route and fusion, so an agent can route and fuse on its own. Related: tiered_router, llm_backends, response_cache.