@anjieyang/uncommon-route 0.2.7 → 0.2.9

package/README.md

@@ -1,8 +1,23 @@
+<p align="right"><strong>English</strong> | <a href="https://github.com/anjieyang/UncommonRoute/blob/main/README.zh-CN.md">简体中文</a></p>
+
 # @anjieyang/uncommon-route
 
-**OpenClaw plugin for [UncommonRoute](https://github.com/anjieyang/UncommonRoute)**
+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.
+
+If you use OpenClaw and want one local endpoint with smart routing behind it, this plugin is the shortest path.
 
-The local LLM router that cuts premium-model spend with smart routing.
+## Mental Model
+
+```text
+OpenClaw -> UncommonRoute -> your upstream API
+```
+
+This plugin:
+
+- installs the Python `uncommon-route` package if needed
+- starts `uncommon-route serve`
+- registers the local provider with OpenClaw
+- exposes the virtual routing profiles like `uncommon-route/auto`
 
 ## Install
 
@@ -11,29 +26,15 @@ openclaw plugins install @anjieyang/uncommon-route
 openclaw gateway restart
 ```
 
-That's it. The plugin auto-installs the Python package, starts the proxy, and registers everything.
-
-## What It Does
+That is enough to install the plugin.
 
-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.
+For real responses, you still need to configure an upstream model API.
 
-- **39-feature cascade classifier** — structural, unicode, and keyword analysis
-- **Step-aware agentic routing** — different models for different steps in a workflow
-- **Session persistence** — sticky model per task, auto-escalation on failure
-- **Spend control** — per-request, hourly, daily, session limits
-- **Dual protocol** — OpenAI (`/v1/chat/completions`) + Anthropic (`/v1/messages`)
+## Configure An Upstream
 
-## Commands
+UncommonRoute does not host models. It routes to an upstream OpenAI-compatible API.
 
-| Command | Description |
-|---|---|
-| `/route <prompt>` | Preview which model would be selected |
-| `/spend status` | View current spending and limits |
-| `/spend set hourly 5.00` | Set an hourly spending limit |
-| `/feedback ok\|weak\|strong` | Rate the last routing decision |
-| `/sessions` | View active routing sessions |
-
-## Configuration
+Example plugin config:
 
 ```yaml
 plugins:
@@ -46,21 +47,61 @@ plugins:
         daily: 20.00
 ```
 
-## Upstream Providers
-
-Works with any OpenAI-compatible API:
+Common upstream choices:
 
 | Provider | URL |
 |---|---|
+| [Parallax](https://github.com/GradientHQ/parallax) | `http://127.0.0.1:3001/v1` |
 | [Commonstack](https://commonstack.ai) | `https://api.commonstack.ai/v1` |
 | OpenAI | `https://api.openai.com/v1` |
-| Local (Ollama) | `http://127.0.0.1:11434/v1` |
+| Local Ollama / vLLM | `http://127.0.0.1:11434/v1` |
+
+If your upstream needs a key, set `UNCOMMON_ROUTE_API_KEY` in the environment where OpenClaw runs.
+
+Parallax is best treated as an experimental local upstream for now: its public docs show `POST /v1/chat/completions`, but UncommonRoute model discovery may be limited because a public `/v1/models` route was not obvious in the repo.
+
+## What You Get
+
+- `uncommon-route/auto` for balanced smart routing
+- `uncommon-route/eco` for cheapest capable routing
+- `uncommon-route/premium` for quality-first routing
+- `uncommon-route/free` for free-first routing
+- `uncommon-route/agentic` for tool-heavy workflows
+
+The router also keeps a fallback chain, applies session-aware routing, and exposes a local dashboard at `http://127.0.0.1:8403/dashboard/`.
+
+## OpenClaw Commands
+
+| Command | Description |
+|---|---|
+| `/route <prompt>` | Preview which model the router would pick |
+| `/spend status` | Show current spending and limits |
+| `/spend set hourly 5.00` | Set an hourly spend limit |
+| `/feedback ok\|weak\|strong` | Rate the last routing decision |
+| `/sessions` | Show active routing sessions |
+
+## Troubleshooting
+
+If the plugin is installed but responses are failing:
+
+1. Make sure your upstream URL is configured.
+2. Make sure `UNCOMMON_ROUTE_API_KEY` is set if your provider requires one.
+3. Open `http://127.0.0.1:8403/health`.
+4. Open `http://127.0.0.1:8403/dashboard/`.
+
+## Benchmarks
+
+Current repo benchmarks:
+
+- 92.3% held-out routing accuracy
+- ~0.5ms average routing latency
+- 67% lower simulated cost than always using Claude Opus in a coding session
 
 ## Links
 
 - [GitHub](https://github.com/anjieyang/UncommonRoute)
 - [PyPI](https://pypi.org/project/uncommon-route/)
-- [Full Documentation](https://github.com/anjieyang/UncommonRoute#readme)
+- [Full README](https://github.com/anjieyang/UncommonRoute#readme)
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anjieyang/uncommon-route",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "description": "OpenClaw plugin for UncommonRoute, the local LLM router that cuts premium-model spend",
   "type": "module",
   "main": "src/index.js",

package/src/index.js

@@ -16,7 +16,7 @@
 import { spawn, execSync } from "node:child_process";
 import { setTimeout as sleep } from "node:timers/promises";
 
-const VERSION = "0.2.7";
+const VERSION = "0.2.9";
 const DEFAULT_PORT = 8403;
 const DEFAULT_UPSTREAM = "";
 const HEALTH_TIMEOUT_MS = 15_000;