dsh-adaptive-model-router

Readme

# dsh-adaptive-model-router

Deterministic per-turn adaptive model routing for DeepSeek Harness. Simple work uses an economy model; complex work and turns that stop making progress upgrade to a quality model.

The router does not call another model to classify the request. Routing is local, synchronous, reproducible, and adds no tokens or provider requests.

The package targets and has been composed against DeepSeek Harness `0.1.1-rc.2`.

## Install

```sh
dsh plugin --profile web add github:icyaaaww/dsh-adaptive-model-router
```

The package ships runnable ESM JavaScript, so a GitHub installation requires no `prepare` build or pnpm build-script allowance.

For this local checkout, run from its parent directory:

```sh
dsh plugin --profile web add ./dsh-adaptive-model-router
```

## Configuration

The included bundle defaults to DeepSeek Flash and Pro:

```yaml
- id: adaptive-model-router
  name: dsh-adaptive-model-router
  config:
    economy:
      provider: deepseek-official
      model: deepseek-v4-flash
    quality:
      provider: deepseek-official
      model: deepseek-v4-pro
    inputCharsThreshold: 1200
    complexityKeywords: [architecture, migration, security, 架构, 迁移, 安全]
    upgradeAfterStep: 2
    upgradeAfterToolFailures: 1
    failureExclude: [todo_write, job_output, job_list]
    preserveUnknownSelection: true
```

Each route also accepts optional `reasoningEffort` and `maxTokens`. A selected route without `reasoningEffort` clears the previous model's effort so the selected adapter can apply its own default; an omitted route `maxTokens` preserves an explicit request limit. Temperature, stop sequences, and every other request field remain unchanged.

## Routing behavior

At the first admitted step of each turn, the router selects Quality when the entering text reaches `inputCharsThreshold` or contains a configured case-insensitive keyword. Otherwise it selects Economy.

Within that turn routing has hysteresis: it may upgrade to Quality but never downgrade. It upgrades when either condition is met:

- The zero-based request step reaches `upgradeAfterStep`.
- Consecutive non-excluded tool failures reach `upgradeAfterToolFailures`.

A successful tracked tool resets only the failure counter; it does not downgrade a turn already upgraded. A new turn starts a fresh decision and may return to Economy.

With `preserveUnknownSelection: true`, requests currently targeting neither configured route pass through unchanged. This keeps an explicit user selection, another provider, or a specialized vision model from being silently replaced. Set it to `false` only when this plugin should own every conversation request.

## Model Experience

The router changes the logged request configuration and keeps the system prompt's `provider` and `model` template variables aligned with that route. It injects no prompt, tool, message, or hidden model-visible instruction. Existing `request/header` records make every route change durable and visible to replay, telemetry, and clients.

### Token effect

The plugin itself adds zero tokens. Savings depend on how many requests move to the economy route and provider pricing.

### KV cache effect

Changing provider or model starts a different provider cache identity. Per-turn hysteresis prevents oscillation inside one turn, while a new user turn may deliberately select a different route.

## Test

```sh
npm test
```

## Limitations

- Keyword and length rules estimate complexity; they do not measure answer quality.
- Tool failures produced by policy denial also count unless their tool is excluded.
- Already-running parallel tools can settle after the route has upgraded.
- The router does not verify model catalog membership; the selected provider owns availability diagnostics.
- Cost reporting is not included. Compare telemetry before and after deployment to tune thresholds.