@anjieyang/uncommon-route 0.2.6 → 0.2.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +62 -26
  2. package/package.json +1 -1
  3. package/src/index.js +1 -1
package/README.md CHANGED
@@ -1,8 +1,21 @@
1
1
  # @anjieyang/uncommon-route
2
2
 
3
- **OpenClaw plugin for [UncommonRoute](https://github.com/anjieyang/UncommonRoute)**
3
+ OpenClaw plugin for [UncommonRoute](https://github.com/anjieyang/UncommonRoute), the local LLM router that sends easy requests to cheaper models and saves stronger models for harder work.
4
4
 
5
- The local LLM router that cuts premium-model spend with smart routing.
5
+ If you use OpenClaw and want one local endpoint with smart routing behind it, this plugin is the shortest path.
6
+
7
+ ## Mental Model
8
+
9
+ ```text
10
+ OpenClaw -> UncommonRoute -> your upstream API
11
+ ```
12
+
13
+ This plugin:
14
+
15
+ - installs the Python `uncommon-route` package if needed
16
+ - starts `uncommon-route serve`
17
+ - registers the local provider with OpenClaw
18
+ - exposes the virtual routing profiles like `uncommon-route/auto`
6
19
 
7
20
  ## Install
8
21
 
@@ -11,29 +24,15 @@ openclaw plugins install @anjieyang/uncommon-route
11
24
  openclaw gateway restart
12
25
  ```
13
26
 
14
- That's it. The plugin auto-installs the Python package, starts the proxy, and registers everything.
27
+ That is enough to install the plugin.
15
28
 
16
- ## What It Does
29
+ For real responses, you still need to configure an upstream model API.
17
30
 
18
- Routes every LLM request to the **cheapest model that can handle it** — simple questions go to budget models, complex tasks go to frontier models. In the repo's real coding-session simulation, UncommonRoute cuts cost by **67%** vs always using Claude Opus while retaining **93.5%** quality.
31
+ ## Configure An Upstream
19
32
 
20
- - **39-feature cascade classifier** — structural, unicode, and keyword analysis
21
- - **Step-aware agentic routing** — different models for different steps in a workflow
22
- - **Session persistence** — sticky model per task, auto-escalation on failure
23
- - **Spend control** — per-request, hourly, daily, session limits
24
- - **Dual protocol** — OpenAI (`/v1/chat/completions`) + Anthropic (`/v1/messages`)
33
+ UncommonRoute does not host models. It routes to an upstream OpenAI-compatible API.
25
34
 
26
- ## Commands
27
-
28
- | Command | Description |
29
- |---|---|
30
- | `/route <prompt>` | Preview which model would be selected |
31
- | `/spend status` | View current spending and limits |
32
- | `/spend set hourly 5.00` | Set an hourly spending limit |
33
- | `/feedback ok\|weak\|strong` | Rate the last routing decision |
34
- | `/sessions` | View active routing sessions |
35
-
36
- ## Configuration
35
+ Example plugin config:
37
36
 
38
37
  ```yaml
39
38
  plugins:
@@ -46,21 +45,58 @@ plugins:
46
45
  daily: 20.00
47
46
  ```
48
47
 
49
- ## Upstream Providers
50
-
51
- Works with any OpenAI-compatible API:
48
+ Common upstream choices:
52
49
 
53
50
  | Provider | URL |
54
51
  |---|---|
55
52
  | [Commonstack](https://commonstack.ai) | `https://api.commonstack.ai/v1` |
56
53
  | OpenAI | `https://api.openai.com/v1` |
57
- | Local (Ollama) | `http://127.0.0.1:11434/v1` |
54
+ | Local Ollama / vLLM | `http://127.0.0.1:11434/v1` |
55
+
56
+ If your upstream needs a key, set `UNCOMMON_ROUTE_API_KEY` in the environment where OpenClaw runs.
57
+
58
+ ## What You Get
59
+
60
+ - `uncommon-route/auto` for balanced smart routing
61
+ - `uncommon-route/eco` for cheapest capable routing
62
+ - `uncommon-route/premium` for quality-first routing
63
+ - `uncommon-route/free` for free-first routing
64
+ - `uncommon-route/agentic` for tool-heavy workflows
65
+
66
+ The router also keeps a fallback chain, applies session-aware routing, and exposes a local dashboard at `http://127.0.0.1:8403/dashboard/`.
67
+
68
+ ## OpenClaw Commands
69
+
70
+ | Command | Description |
71
+ |---|---|
72
+ | `/route <prompt>` | Preview which model the router would pick |
73
+ | `/spend status` | Show current spending and limits |
74
+ | `/spend set hourly 5.00` | Set an hourly spend limit |
75
+ | `/feedback ok\|weak\|strong` | Rate the last routing decision |
76
+ | `/sessions` | Show active routing sessions |
77
+
78
+ ## Troubleshooting
79
+
80
+ If the plugin is installed but responses are failing:
81
+
82
+ 1. Make sure your upstream URL is configured.
83
+ 2. Make sure `UNCOMMON_ROUTE_API_KEY` is set if your provider requires one.
84
+ 3. Open `http://127.0.0.1:8403/health`.
85
+ 4. Open `http://127.0.0.1:8403/dashboard/`.
86
+
87
+ ## Benchmarks
88
+
89
+ Current repo benchmarks:
90
+
91
+ - 92.3% held-out routing accuracy
92
+ - ~0.5ms average routing latency
93
+ - 67% lower simulated cost than always using Claude Opus in a coding session
58
94
 
59
95
  ## Links
60
96
 
61
97
  - [GitHub](https://github.com/anjieyang/UncommonRoute)
62
98
  - [PyPI](https://pypi.org/project/uncommon-route/)
63
- - [Full Documentation](https://github.com/anjieyang/UncommonRoute#readme)
99
+ - [Full README](https://github.com/anjieyang/UncommonRoute#readme)
64
100
 
65
101
  ## License
66
102
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@anjieyang/uncommon-route",
3
- "version": "0.2.6",
3
+ "version": "0.2.8",
4
4
  "description": "OpenClaw plugin for UncommonRoute, the local LLM router that cuts premium-model spend",
5
5
  "type": "module",
6
6
  "main": "src/index.js",
package/src/index.js CHANGED
@@ -16,7 +16,7 @@
16
16
  import { spawn, execSync } from "node:child_process";
17
17
  import { setTimeout as sleep } from "node:timers/promises";
18
18
 
19
- const VERSION = "0.2.6";
19
+ const VERSION = "0.2.8";
20
20
  const DEFAULT_PORT = 8403;
21
21
  const DEFAULT_UPSTREAM = "";
22
22
  const HEALTH_TIMEOUT_MS = 15_000;