auto-model-router 0.1.0 → 0.1.1

package/.github/workflows/release.yml

@@ -0,0 +1,54 @@
+name: release
+
+# Release flow: push a version tag (v0.2.0) to publish to npm AND create a
+# visible GitHub Release. Bump package.json, commit, tag vX.Y.Z, push. The tag
+# triggers both the npm publish and the GitHub Release, so every update is
+# visible. If the version is already on npm (e.g. tagging an existing release),
+# the publish step is skipped and only the GitHub Release is created.
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: https://registry.npmjs.org
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Check if version already published
+        id: version
+        run: |
+          LOCAL=$(node -p "require('./package.json').version")
+          PUBLISHED=$(npm view auto-model-router version 2>/dev/null || echo "0.0.0")
+          echo "local=$LOCAL published=$PUBLISHED"
+          if [ "$LOCAL" != "$PUBLISHED" ]; then
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Publish to npm
+        if: steps.version.outputs.changed == 'true'
+        run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          name: auto-model-router ${{ github.ref_name }}
+          body: |
+            Published to npm as [`auto-model-router@${{ github.ref_name }}`](https://www.npmjs.com/package/auto-model-router).
+            Install with `pi install npm:auto-model-router`.

package/README.md

@@ -160,13 +160,20 @@ To publish to npm (which auto-indexes on pi.dev/packages):
 npm publish
 ```
 
-### Hermes (day-1 support)
+### Hermes
 
 Hermes speaks the OpenAI-compatible wire, so it connects to the router with no
-code change — just a custom provider pointing at the router's URL. Add a named
-provider to `~/.hermes/config.yaml`:
+code change. Two ways to run the router for Hermes:
+
+**Standalone server (recommended for Hermes):** run the router as its own
+process on a fixed port, then point Hermes at it:
+
+```bash
+auto-model-router serve --port 8788
+```
 
 ```yaml
+# ~/.hermes/config.yaml
 providers:
   auto-model-router:
     base_url: http://127.0.0.1:8788/v1
@@ -174,6 +181,11 @@ providers:
     default_model: auto
 ```
 
+**Hermes plugin (native):** copy `hermes-plugin/` to
+`$HERMES_HOME/plugins/model-providers/auto-model-router/` and restart Hermes.
+The plugin spawns the router as a subprocess on load and registers the provider
+profile, so Hermes routes each turn through the router automatically.
+
 The router serves `GET /v1/models` (returning the `auto`, `auto-cheap`,
 `auto-max` profiles) and `POST /v1/chat/completions`, which Hermes's custom
 endpoint discovery verifies. Select `auto-model-router/auto` as the model and
@@ -183,8 +195,6 @@ its own OpenRouter key.
 
 ### The OpenRouter key
 
-### The OpenRouter key
-
 There should be exactly one OpenRouter key on the machine, and omp already owns
 a credential store. Resolution order:
 

package/hermes-plugin/__init__.py

@@ -0,0 +1,81 @@
+"""Hermes provider plugin for auto-model-router.
+
+Requires auto-model-router installed globally via npm so its `serve` binary is
+on PATH:
+
+    npm install -g auto-model-router
+
+The plugin spawns `auto-model-router serve` as a subprocess on a fixed port and
+registers a ProviderProfile pointing at it, so Hermes routes each turn through
+the router's per-turn cost/complexity logic. The router is a Bun process; this
+Python plugin manages it as a child process (Hermes plugins may spawn
+subprocesses).
+
+Install by copying this directory to
+``$HERMES_HOME/plugins/model-providers/auto-model-router/`` (or symlinking it),
+then restart Hermes. Override the port with ``AUTO_MODEL_ROUTER_PORT``.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import time
+import urllib.request
+
+from providers import register_provider
+from providers.base import ProviderProfile
+
+# Fixed port the standalone router binds. Hermes points at this URL.
+PORT = int(os.environ.get("AUTO_MODEL_ROUTER_PORT", "8788"))
+BASE_URL = f"http://127.0.0.1:{PORT}/v1"
+
+# The router binary, provided by `npm install -g auto-model-router`.
+BIN = "auto-model-router"
+
+
+def _router_running() -> bool:
+    try:
+        with urllib.request.urlopen(f"http://127.0.0.1:{PORT}/health", timeout=1) as resp:
+            return resp.status == 200
+    except Exception:
+        return False
+
+
+def _spawn_router() -> None:
+    """Start the standalone router if it is not already running."""
+    if _router_running():
+        return
+    if shutil.which(BIN) is None:
+        raise RuntimeError(
+            "auto-model-router is not installed or not on PATH. "
+            "Run `npm install -g auto-model-router` first."
+        )
+    subprocess.Popen(
+        [BIN, "serve", "--port", str(PORT)],
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+        start_new_session=True,
+    )
+    # Wait for it to come up (bounded).
+    for _ in range(50):
+        if _router_running():
+            return
+        time.sleep(0.2)
+    raise RuntimeError(f"auto-model-router did not come up on port {PORT}")
+
+
+_spawn_router()
+
+profile = ProviderProfile(
+    name="auto-model-router",
+    api_mode="chat_completions",
+    base_url=BASE_URL,
+    auth_type="api_key",
+    env_vars=("AUTO_MODEL_ROUTER_API_KEY",),
+    fallback_models=("auto", "auto-cheap", "auto-max"),
+    display_name="auto-model-router",
+    description="Per-turn cost/complexity-aware model routing",
+)
+register_provider(profile)

package/hermes-plugin/plugin.yaml

@@ -0,0 +1,5 @@
+name: auto-model-router-provider
+kind: model-provider
+version: 1.0.0
+description: auto-model-router — per-turn cost/complexity-aware model routing
+author: drewappling

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auto-model-router",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "private": false,
   "description": "Local cost/complexity-aware model router for Oh My Pi, backed by OpenRouter",
   "type": "module",
@@ -10,7 +10,8 @@
   "scripts": {
     "typecheck": "tsc --noEmit",
     "test": "bun test",
-    "smoke": "bun run tools/smoke.ts"
+    "smoke": "bun run tools/smoke.ts",
+    "release": "npm version $1 && git push --follow-tags"
   },
   "dependencies": {
     "yaml": "^2.7.0",

package/src/cli/args.ts

@@ -27,6 +27,7 @@ const BOOLEAN_FLAGS: Record<string, true> = {
 };
 
 const COMMANDS: Record<string, true> = {
+	serve: true,
 	stats: true,
 	models: true,
 	explain: true,

package/src/cli/serve.ts

@@ -0,0 +1,67 @@
+/**
+ * Standalone `serve` command.
+ *
+ * Runs the router as its own process on a fixed port, independent of any omp
+ * session. This is how non-Bun harnesses (Hermes, Claude, any OpenAI-compatible
+ * client) connect: they point at `http://127.0.0.1:<port>/v1` and the router
+ * routes each turn. The embedded omp extension is the zero-management path;
+ * `serve` is the shared, always-on path for other harnesses.
+ *
+ * The core (`startServer`) is identical in both modes; only the process
+ * ownership and port differ.
+ */
+
+import { apiKeySource, loadConfig } from "../config/load.ts";
+import type { RouterConfig } from "../config/types.ts";
+import { startServer } from "../server/http.ts";
+import { createLogger } from "../util/log.ts";
+import { configOpts, flagInt, flagString, type CliArgs } from "./args.ts";
+
+const LOG_LEVELS = ["silent", "error", "warn", "info", "debug"] as const;
+
+export async function serveCommand(args: CliArgs): Promise<void> {
+	// Sparse by design: only flags actually given override; deep merge fills the rest.
+	const serverOverride: { host?: string; port?: number } = {};
+	const port = flagInt(args, "port");
+	if (port !== undefined) serverOverride.port = port;
+	const host = flagString(args, "host");
+	if (host !== undefined) serverOverride.host = host;
+
+	const overrides: { server?: typeof serverOverride; logLevel?: string } = {};
+	if (serverOverride.host !== undefined || serverOverride.port !== undefined) overrides.server = serverOverride;
+	const logLevel = flagString(args, "log");
+	if (logLevel !== undefined) {
+		if (!(LOG_LEVELS as readonly string[]).includes(logLevel)) {
+			throw new Error(`--log must be one of ${LOG_LEVELS.join(", ")}, got "${logLevel}"`);
+		}
+		overrides.logLevel = logLevel;
+	}
+
+	const cfg = loadConfig(configOpts(args, overrides as Partial<RouterConfig>));
+	const log = createLogger(cfg.logLevel);
+	const { server, stop } = startServer(cfg);
+
+	// Report the port the OS actually bound: `port: 0` asks for an ephemeral one.
+	const addr = `http://${cfg.server.host}:${server.port}`;
+	console.log(`auto-model-router listening on ${addr} (OpenAI-compatible endpoint at ${addr}/v1)`);
+
+	// State the credential provenance up front. Silence here is how you end up
+	// debugging 401s that were really "the key was never found".
+	const credential = apiKeySource(cfg);
+	if (credential.source === "none") {
+		console.warn(`WARNING: no OpenRouter key resolved - ${credential.detail}`);
+		console.warn("         the catalog will still load, but every completion will fail at dispatch");
+	} else {
+		console.log(`OpenRouter key: ${credential.detail}`);
+	}
+
+	let stopping = false;
+	const shutdown = (signal: string): void => {
+		if (stopping) return;
+		stopping = true;
+		log.info("shutting down", { signal });
+		void stop().then(() => process.exit(0));
+	};
+	process.on("SIGINT", () => shutdown("SIGINT"));
+	process.on("SIGTERM", () => shutdown("SIGTERM"));
+}

package/src/index.ts

@@ -12,13 +12,14 @@ import { parseArgv } from "./cli/args.ts";
 import { configCommand } from "./cli/config-cmd.ts";
 import { explainCommand } from "./cli/explain.ts";
 import { modelsCommand } from "./cli/models.ts";
+import { serveCommand } from "./cli/serve.ts";
 import { statsCommand } from "./cli/stats.ts";
 
 const USAGE = `auto-model-router - local cost/complexity-aware model router for omp, backed by OpenRouter
 
 Usage: auto-model-router <command> [options]
 
-Commands:
+  serve      Run the router as a standalone process (for non-omp harnesses)
   stats      Show routed spend, per-model share, and escalation rates
   models     Show what each complexity tier would consider, and why
   explain    Route a saved request without dispatching it, and explain the decision
@@ -30,7 +31,8 @@ Global options:
   --help, -h        Show help
   --version         Show version
 
-Command options:
+  serve    --port <n>  --host <addr>  --log <level>
+  stats    --days <n>  --json
   stats    --days <n>  --json
   models   --tier <trivial|simple|moderate|hard>  --limit <n>  --json
   explain  --file <request.json>  --json          (reads stdin when --file is absent)
@@ -58,12 +60,20 @@ async function main(): Promise<number> {
 		process.stdout.write(USAGE);
 		return args.flags.has("help") ? 0 : 1;
 	}
-	if (args.flags.has("help")) {
-		process.stdout.write(USAGE);
-		return 0;
-	}
-
 	switch (args.command) {
+		case "serve":
+			// Resolves once listening; the server itself keeps the loop alive.
+			await serveCommand(args);
+			return 0;
+		case "stats":
+			await statsCommand(args);
+			return 0;
+		case "models":
+
+		case "serve":
+			// Resolves once listening; the server itself keeps the loop alive.
+			await serveCommand(args);
+			return 0;
 		case "stats":
 			await statsCommand(args);
 			return 0;

package/.github/workflows/publish.yml

@@ -1,40 +0,0 @@
-name: publish
-
-# Publish to npm when a change lands on main AND the package version actually
-# changed. Doc-only commits (no version bump) are skipped, so npm stays in
-# sync with real releases without publishing noise on every push.
-on:
-  push:
-    branches: [main]
-
-jobs:
-  publish:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 20
-          registry-url: https://registry.npmjs.org
-
-      - name: Install dependencies
-        run: npm install
-
-      - name: Check if version changed
-        id: version
-        run: |
-          LOCAL=$(node -p "require('./package.json').version")
-          PUBLISHED=$(npm view auto-model-router version 2>/dev/null || echo "0.0.0")
-          echo "local=$LOCAL published=$PUBLISHED"
-          if [ "$LOCAL" != "$PUBLISHED" ]; then
-            echo "changed=true" >> "$GITHUB_OUTPUT"
-          else
-            echo "changed=false" >> "$GITHUB_OUTPUT"
-          fi
-
-      - name: Publish to npm
-        if: steps.version.outputs.changed == 'true'
-        run: npm publish
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}