dsh-llm-fallback

Readme

# dsh-llm-fallback

A [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) plugin that adds a provider/model fallback chain to the agent loop.

When a model request fails with an eligible error code (e.g. `RATE_LIMIT` from a 429, or `QUOTA`), instead of only retrying the same model, the plugin transparently moves to the next provider/model in the configured chain.

## Install

```sh
dsh plugin --profile web add github:morphlinglan/dsh-llm-fallback
```

Then restart `dsh web` if it is already running.

## Usage

Add an `insert` entry to the profile's `cordis.patch.yml` (or rely on the bundle default and configure it through your profile patch layer):

```yaml
- insert:
    - id: dsh-llm-fallback
      name: dsh-llm-fallback
      config:
        codes:
          - RATE_LIMIT
          - QUOTA
        scope: turn
        fallbacks:
          # Replace these with your own backup providers/models.
          - provider: backup-provider-a
            model: backup-model-a
          - provider: backup-provider-b
            model: backup-model-b
```

The providers/models above are **placeholders only**. Replace them with providers and models you actually have access to.

### Config

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `codes` | `string[]` | `["RATE_LIMIT", "QUOTA"]` | Failure codes that trigger a fallback. |
| `fallbacks` | `{ provider, model }[]` | `[]` | Ordered chain of backup providers/models. |
| `scope` | `"step" \| "turn" \| "session"` | `"turn"` | How long the sticky fallback selection persists. |

### Scope behavior

- `step`: each step starts on the primary model; only retries within one step walk the chain.
- `turn`: once a fallback is selected, it is reused for the rest of the current turn; the next turn tries the primary again.
- `session`: once a fallback is selected, it stays selected until the chain is exhausted; best when the primary is durably down.

## License

MIT