juwanxu/dsh-free-router
Request-level routing and failover across free models in DSH, reusing the official pi-ai adapter so sessions keep the real provider/model.
Routes each primary-agent request across free models instead of pinning one, and fails over in the same step when the chosen model cannot serve it. Candidates come from a statically verified NVIDIA NIM list and the live OpenRouter free-model catalog, filtered to models confirmed to support tool calling and to satisfy the context-window and tier constraints. Ranking is by availability, then tier, then average first-token latency, then success rate, and recovery covers RATE_LIMIT, SERVER, TIMEOUT, TRANSPORT, authentication and quota failures, capped at four models per turn/step by default. Two design decisions keep it honest with the rest of the harness: routing decisions stay out of the durable DSH session event log so sessions remain restorable, and the cache at $DSH_HOME/cache/free-router.json holds only an allowlisted projection — version, timestamps, public model metadata and health values — with an expired cache used solely as a cold-start ranking hint rather than as a claim that a model is currently available. The README also documents a manual verification path, for when a free endpoint silently stops answering.
Install
dsh plugin --profile web add dsh-free-routerThe npm line from the README's Scope/Installation section. A local-development route is documented too, and it is two steps rather than one: build the repository root with pnpm run build, then dsh plugin --profile web add "file:$(pwd)". The README also shows an allow-version invocation for testing against a specific DSH release (dsh plugin --profile <temporary-profile> allow-version dsh-free-router@0.1.4 --dsh-version 0.2.0-rc.2 --accept-risk), which exists because it is a routing layer and therefore version-sensitive.
Compatibility
Prerequisites are Node.js 22.19+, pnpm 11+, and a full DSH profile that includes llm, agent, settings and @deepseek-ai/dsh-llm-pi-ai — the last one because the plugin reuses the official adapter for actual requests instead of shipping its own transport. It never registers a virtual provider, so session history, usage and errors always retain the real provider/model, which is what makes sessions restorable across Harness versions. It is designed to coexist with dsh-camel and dsh-continue in one profile provided each failure class has one owner: Continue should own only transient network failures such as TIMEOUT, TRANSPORT and SERVER. Catalog behaviour is configurable — by default zero-priced models are accepted even without a :free suffix, and catalog.zeroPricedWithoutSuffix: false restores the suffix-only rule; routing.minimumTier: '?' allows models without a curated tier rating.
Details
- Repo: juwanxu/dsh-free-router
- Category: Models & Providers
- Stars: 1
- Version: 0.1.4 (npm)
Alternatives
dushaobindoudou/dsh-freeroute · BruceLanLan/dsh-tier-router · penguin-oo/dsh-delegate-router