130 lines
6.8 KiB
Markdown
130 lines
6.8 KiB
Markdown
# omniroute-plugin
|
||
|
||
OmniRoute gateway integration for the DeepSeek Harness (DSH): **model auto-import** (context window, max output, modalities, thinking levels) **provider quota tracking** under the composer, and a **web search toolkit** for the agent backed by OmniRoute's search/fetch providers.
|
||
|
||
## Features
|
||
|
||
- **Model discovery / import**: pulls models and combos from your OmniRoute gateway into an `llm-pi-ai` provider (default id `omni`, created if missing), with context window, output limit, input modalities and supported thinking levels (`off/minimal/low/medium/high/xhigh/max`).
|
||
- **Periodic re-import** (`syncMin`, default 60 min; 0 = manual only) and an *update existing models only* mode.
|
||
- **Include / exclude filters**: comma-separated glob patterns (`*`, `?`) on model ids, e.g. `claude*, gemini-*`; exclude always wins.
|
||
- **Manage imported models**: search, select and prune models from the provider.
|
||
- **Quota tracking**: provider quotas (5-hour, weekly, monthly, …) shown in the composer dock, refreshed every `pollSec` seconds (default 120); requires a management-scoped API key.
|
||
- **Web search toolkit for the agent** (see below): `omniroute_web_search`, `omniroute_web_fetch`, `omniroute_search_providers`, routed through the gateway's `/v1/search` and `/v1/web/fetch`.
|
||
- English and Chinese UI.
|
||
|
||
## Files
|
||
|
||
| File | Role |
|
||
| --- | --- |
|
||
| `index.js` | Host plugin. Injects `webServer`, `connection`, `credentials`, `settings`, `tools`. |
|
||
| `client.js` | Web client: settings panel (`plugins.bundle.config`) and quota dock (`conversation.composer.dock`). |
|
||
| `locale/*.json` | Plugin title/description (en, zh). |
|
||
| `cordis.patch.yml` | Bundle patch inserting the `omniroute` row. |
|
||
|
||
### Host routes (relative to the Web origin, behind the connection trust fence)
|
||
|
||
| Route | Purpose |
|
||
| --- | --- |
|
||
| `GET /omniroute/status` | Effective settings, key presence, last import |
|
||
| `POST /omniroute/config` | Save settings (+ optional write-only API key) |
|
||
| `POST /omniroute/test` | Probe the gateway with given or saved credentials |
|
||
| `GET /omniroute/models` | Models currently imported |
|
||
| `POST /omniroute/prune` | Remove selected imported models |
|
||
| `POST /omniroute/import` | Import models/combos into the `llm-pi-ai` provider |
|
||
| `GET /omniroute/quotas` | Provider quotas (`?model=<id>` narrows to that model's provider) |
|
||
| `GET /omniroute/search-providers` | Web search / fetch providers known to the gateway |
|
||
|
||
## Web search toolkit
|
||
|
||
While **Web search tools** is on (default), the plugin registers three agent tools. They use the same gateway URL and API key as the rest of the plugin, so nothing extra needs configuring. To use them, enable at least one search provider in OmniRoute (Dashboard → Search).
|
||
|
||
| Tool | What it does |
|
||
| --- | --- |
|
||
| `omniroute_web_search` | `POST /v1/search`. Params: `query` (required), `max_results` (1–20), `search_type` (`web`/`news`/`x`), `time_range` (`any/hour/day/week/month/year`), `include_domains`, `exclude_domains`, `country`, `language`, `provider`. Returns `{provider, query, results:[{n,title,url,snippet,published?,content?}], answer?}`. |
|
||
| `omniroute_web_fetch` | `POST /v1/web/fetch`. Params: `url` (required), `format` (`markdown`/`html`), `max_characters` (default 20000), `provider`. Returns the page content (truncated, with a `truncated` marker) and links. |
|
||
| `omniroute_search_providers` | Lists the gateway's search/fetch providers with `kind`, `status` (`configured`/`missing`), supported search types and cost per query. |
|
||
|
||
**Choosing a provider:**
|
||
1. The tool call's `provider` argument wins.
|
||
2. Otherwise the **Search provider** / **Fetch provider** setting is used.
|
||
3. If both are blank, the plugin picks the first provider OmniRoute reports as `configured`. The list is cached for 10 minutes and refreshed on save.
|
||
|
||
This matters because the gateway's built-in default (`duckduckgo-free`) often returns no results.
|
||
|
||
Every result is prefixed with a notice telling the model to treat web content as untrusted data. Turning the toggle off unregisters the tools immediately, with no restart. The tool names don't clash with DSH's built-in `web_search` / `web_fetch`, so both can be enabled at once.
|
||
|
||
## Installation
|
||
|
||
Requirements: a working DeepSeek Harness (`dsh`) install with the **web** profile (or any profile that includes the Web UI).
|
||
|
||
### Option A — install from git (recommended)
|
||
|
||
```bash
|
||
dsh plugin --profile web add git+https://git.rizzy.dev/DSH-Plugins/omniroute-plugin.git
|
||
```
|
||
|
||
You can also paste `git+https://git.rizzy.dev/DSH-Plugins/omniroute-plugin.git` into **Settings → Plugins → Install** in the Web UI, or ask the agent to install it with its `plugin_manager` tool (`install_bundle`).
|
||
|
||
The plugin manager adds `@local/omniroute` to `dependencies` and to `dsh.profile.bundles` in `~/.dsh/profiles/web/package.json`.
|
||
|
||
### Option B — local checkout (for development)
|
||
|
||
```bash
|
||
git clone https://git.rizzy.dev/DSH-Plugins/omniroute-plugin.git ~/dsh-plugins/omniroute-plugin
|
||
dsh plugin --profile web add link:$HOME/dsh-plugins/omniroute-plugin
|
||
```
|
||
|
||
With a `link:` install, edits in the checkout are picked up directly (client changes reload on page refresh, Host changes after a DSH restart or HMR reload).
|
||
|
||
### Enable / verify
|
||
|
||
1. Make sure `@local/omniroute` is listed in `dsh.profile.bundles` of `~/.dsh/profiles/web/package.json` (the installer does this; add it by hand if you edited `package.json` manually).
|
||
2. Restart DSH (`dsh web`) or reload the page.
|
||
3. Check **Settings → Plugins**: the `@local/omniroute` bundle should be enabled.
|
||
|
||
### Uninstall
|
||
|
||
```bash
|
||
dsh plugin --profile web remove @local/omniroute
|
||
```
|
||
|
||
### Updating
|
||
|
||
Re-run the `add` command from Option A (or `git pull` in your Option B checkout).
|
||
|
||
## Setup after install
|
||
|
||
1. Open **Settings → Plugins → OmniRoute**.
|
||
2. Enter the **Gateway URL** (e.g. `https://omniroute.example.com`) and paste your **API key**.
|
||
- The key is stored in the DSH credential store under `OMNIROUTE_API_KEY` (`keyRef`) and never leaves the Host.
|
||
- Use a management-scoped key if you want quota tracking.
|
||
3. Press **Test**, then **Save**, then **Re-discover models**.
|
||
4. Pick an `omni/…` model in the model selector. Quotas appear under the composer.
|
||
5. *(Optional)* Under **Web search tools**, set a preferred search/fetch provider and the default number of results.
|
||
|
||
### Configuration file
|
||
|
||
Non-secret settings live in `<profile>/omniroute.json` (`$DSH_PROFILE_DIR` or `~/.dsh/profiles/web/omniroute.json`):
|
||
|
||
```json
|
||
{
|
||
"url": "https://omniroute.example.com",
|
||
"keyRef": "OMNIROUTE_API_KEY",
|
||
"provider": "omni",
|
||
"discovery": true,
|
||
"updateOnly": false,
|
||
"include": "",
|
||
"exclude": "",
|
||
"discoverThinking": true,
|
||
"usage": true,
|
||
"pollSec": 120,
|
||
"syncMin": 60,
|
||
"webSearch": true,
|
||
"searchProvider": "",
|
||
"fetchProvider": "",
|
||
"searchMaxResults": 8
|
||
}
|
||
```
|
||
|
||
All of these are editable from the settings panel; `imported` and `lastImport` are maintained by the plugin.
|