@rungate/llmrouter 0.1.0

package/README.md

@@ -0,0 +1,97 @@
+# llm_router
+
+Minimal OpenClaw-first LLM router.
+
+For the end-to-end runtime walkthrough of how the router itself works, see [docs/REQUEST_FLOW.md](docs/REQUEST_FLOW.md).
+
+Included in this reset:
+
+- local OpenAI-compatible proxy
+- simple prompt classifier
+- x402 payment retry client
+- OpenClaw plugin with `/wallet`
+
+Not included yet:
+
+- advanced routing heuristics
+- weighted scoring
+- provenance receipts
+- complex fallback chains
+
+## Dev
+
+```bash
+npm install
+npm run typecheck
+npm run dev:proxy
+```
+
+## Production Install
+
+Install the published package into OpenClaw:
+
+```bash
+openclaw plugins install @rungate/llmrouter
+openclaw gateway restart
+```
+
+Recommended production environment:
+
+```bash
+INFERENCE_PROVIDER_BASE_URL=https://api.rungate.ai
+X402_NETWORK=eip155:8453
+```
+
+`llm_router` remains local-only in this setup. OpenClaw still talks to the local proxy at `http://127.0.0.1:3000/v1`; the remote upstream is configured by environment.
+
+## Local OpenClaw Install
+
+For local unpublished development, install from a packaged tarball:
+
+```bash
+npm run build
+npm pack
+openclaw plugins install ./rungate-llmrouter-0.1.0.tgz
+openclaw gateway restart
+```
+
+For Docker/tempclaw-style testing, stage the tarball into the container and install it there with:
+
+```bash
+openclaw plugins install /staging/rungate-llmrouter-0.1.0.tgz
+```
+
+## Environment
+
+```bash
+LLM_ROUTER_HOST=127.0.0.1
+LLM_ROUTER_PORT=3000
+INFERENCE_PROVIDER_BASE_URL=http://127.0.0.1:8787
+X402_NETWORK=eip155:84532
+```
+
+For production, point the upstream at Rungate and use Base mainnet:
+
+```bash
+INFERENCE_PROVIDER_BASE_URL=https://api.rungate.ai
+X402_NETWORK=eip155:8453
+```
+
+## OpenClaw Models
+
+- `llmrouter/auto`
+- `llmrouter/simple`
+- `llmrouter/coding`
+- `llmrouter/reasoning`
+- `llmrouter/vision`
+
+## Release Workflow
+
+```bash
+npm run typecheck
+npm run build
+npm pack
+npm publish
+```
+
+Use `npm pack` as the final sanity check before publishing. The packed artifact should contain the built plugin entrypoint in `dist`, the plugin manifest, and only runtime files.

package/dist/scripts/proxy.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/scripts/proxy.js

@@ -0,0 +1,3 @@
+import { startProxyServer } from '../src/proxy/server.js';
+const server = await startProxyServer();
+console.log(`llm_router proxy listening on http://${server.host}:${server.port}`);

package/dist/src/index.d.ts

@@ -0,0 +1,6 @@
+export { startProxyServer } from './proxy/server.js';
+export { classifyPrompt } from './router/classify.js';
+export { routeRequest } from './router/route.js';
+export { createPaymentFetch } from './payment/x402.js';
+export { resolveOrGenerateWalletKey, walletFilePath } from './payment/wallet.js';
+export type { RouterRequest, PromptClassification, RouteDecision, WalletInfo } from './types.js';

package/dist/src/index.js

@@ -0,0 +1,5 @@
+export { startProxyServer } from './proxy/server.js';
+export { classifyPrompt } from './router/classify.js';
+export { routeRequest } from './router/route.js';
+export { createPaymentFetch } from './payment/x402.js';
+export { resolveOrGenerateWalletKey, walletFilePath } from './payment/wallet.js';

package/dist/src/openclaw/config.d.ts

@@ -0,0 +1 @@
+export declare function ensureOpenClawProviderConfig(config: Record<string, unknown>, baseUrl: string): void;

package/dist/src/openclaw/config.js

@@ -0,0 +1,38 @@
+const MODEL_LIST = [
+    { id: 'auto', name: 'LLM Router Auto', reasoning: true },
+    { id: 'simple', name: 'LLM Router Simple', reasoning: false },
+    { id: 'coding', name: 'LLM Router Coding', reasoning: true },
+    { id: 'reasoning', name: 'LLM Router Reasoning', reasoning: true },
+    { id: 'vision', name: 'LLM Router Vision', reasoning: true },
+];
+// Inject the provider block and default model so OpenClaw can talk to the local proxy.
+export function ensureOpenClawProviderConfig(config, baseUrl) {
+    const models = config.models ?? {};
+    const providers = models.providers ?? {};
+    providers.llmrouter = {
+        baseUrl,
+        apiKey: 'llmrouter-local-proxy',
+        api: 'openai-completions',
+        models: MODEL_LIST.map((model) => ({
+            id: model.id,
+            name: model.name,
+            api: 'openai-completions',
+            reasoning: model.reasoning,
+            input: ['text'],
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+            contextWindow: 262144,
+            maxTokens: 65536,
+        })),
+    };
+    models.providers = providers;
+    config.models = models;
+    const agents = config.agents ?? {};
+    const defaults = agents.defaults ?? {};
+    const modelConfig = defaults.model ?? {};
+    if (typeof modelConfig.primary !== 'string' || modelConfig.primary.length === 0) {
+        modelConfig.primary = 'llmrouter/auto';
+    }
+    defaults.model = modelConfig;
+    agents.defaults = defaults;
+    config.agents = agents;
+}

package/dist/src/openclaw/plugin.d.ts

@@ -0,0 +1,30 @@
+type OpenClawPluginApi = {
+    config: Record<string, unknown>;
+    logger: {
+        info: (message: string) => void;
+    };
+    registerProvider: (provider: {
+        id: string;
+        label: string;
+        auth: unknown[];
+    }) => void;
+    registerCommand: (command: {
+        name: string;
+        description: string;
+        acceptsArgs?: boolean;
+        requireAuth?: boolean;
+        handler: () => Promise<{
+            text: string;
+        }> | {
+            text: string;
+        };
+    }) => void;
+};
+type OpenClawPluginDefinition = {
+    id: string;
+    name: string;
+    description: string;
+    register: (api: OpenClawPluginApi) => void | Promise<void>;
+};
+declare const plugin: OpenClawPluginDefinition;
+export default plugin;

package/dist/src/openclaw/plugin.js

@@ -0,0 +1,47 @@
+import { getWalletInfo, resolveOrGenerateWalletKey } from '../payment/wallet.js';
+import { ensureOpenClawProviderConfig } from './config.js';
+import { ensureLocalProxy, logWalletBootstrap } from './runtime.js';
+const provider = {
+    id: 'llmrouter',
+    label: 'llmrouter',
+    auth: [],
+};
+// Format the wallet details for the native /wallet command.
+async function formatWalletText() {
+    const wallet = await getWalletInfo(process.env);
+    return [
+        'llm_router Wallet',
+        '',
+        `Address: ${wallet.address}`,
+        `Network: ${wallet.network}`,
+        `USDC balance: ${wallet.usdcBalance ?? 'unknown'} USDC`,
+        `Native balance: ${wallet.nativeBalance ?? 'unknown'} ${wallet.nativeSymbol ?? 'ETH'}`,
+        `Wallet file: ${wallet.walletFile}`,
+        `Source: ${wallet.source}`,
+    ].join('\n');
+}
+const plugin = {
+    id: 'llmrouter',
+    name: 'llm_router',
+    description: 'Minimal OpenClaw-first LLM router',
+    register: async (api) => {
+        ensureOpenClawProviderConfig(api.config, 'http://127.0.0.1:3000/v1');
+        api.registerProvider(provider);
+        api.logger.info('llm_router provider registered');
+        api.registerCommand({
+            name: 'wallet',
+            description: 'Show llm_router wallet info',
+            acceptsArgs: false,
+            requireAuth: false,
+            handler: async () => ({ text: await formatWalletText() }),
+        });
+        const wallet = resolveOrGenerateWalletKey(process.env);
+        logWalletBootstrap(api.logger, wallet);
+        if (!process.argv.includes('gateway')) {
+            api.logger.info('llm_router loaded outside gateway process; local proxy startup skipped');
+            return;
+        }
+        await ensureLocalProxy(api.logger);
+    },
+};
+export default plugin;

package/dist/src/openclaw/runtime.d.ts

@@ -0,0 +1,8 @@
+import type { WalletInfo } from '../types.js';
+export type OpenClawLogger = {
+    info: (message: string) => void;
+};
+export declare function ensureLocalProxy(logger: OpenClawLogger): Promise<void>;
+export declare function logWalletBootstrap(logger: OpenClawLogger, wallet: {
+    info: Pick<WalletInfo, 'address' | 'walletFile' | 'source' | 'network'>;
+}): void;

package/dist/src/openclaw/runtime.js

@@ -0,0 +1,86 @@
+import { startProxyServer } from '../proxy/server.js';
+let proxy;
+let proxyClosePromise;
+let shutdownHooksInstalled = false;
+function resolveProxyEndpoint() {
+    const host = process.env.LLM_ROUTER_HOST ?? '127.0.0.1';
+    const port = Number(process.env.LLM_ROUTER_PORT ?? 3000);
+    return {
+        host,
+        port,
+        baseUrl: `http://${host}:${port}`,
+    };
+}
+async function looksLikeLlmRouter(baseUrl) {
+    const response = await fetch(new URL('/v1/models', baseUrl), {
+        headers: { accept: 'application/json' },
+        signal: AbortSignal.timeout(2_000),
+    });
+    if (!response.ok)
+        return false;
+    const body = await response.json();
+    return Array.isArray(body.data) && body.data.some((model) => model.id === 'llmrouter/auto');
+}
+function closeProxyOnShutdown() {
+    if (!proxy || proxyClosePromise)
+        return;
+    proxyClosePromise = proxy.close()
+        .catch(() => undefined)
+        .finally(() => {
+        proxy = undefined;
+        proxyClosePromise = undefined;
+    });
+}
+function installProxyShutdownHooks(logger) {
+    if (shutdownHooksInstalled)
+        return;
+    shutdownHooksInstalled = true;
+    const handleSignal = (signal) => {
+        logger.info(`llm_router shutting down local proxy before ${signal}`);
+        closeProxyOnShutdown();
+    };
+    process.on('SIGUSR1', () => handleSignal('SIGUSR1'));
+    process.on('SIGTERM', () => handleSignal('SIGTERM'));
+    process.on('SIGINT', () => handleSignal('SIGINT'));
+    process.on('beforeExit', () => closeProxyOnShutdown());
+    process.on('exit', () => closeProxyOnShutdown());
+}
+export async function ensureLocalProxy(logger) {
+    if (proxy || !process.argv.includes('gateway'))
+        return;
+    const endpoint = resolveProxyEndpoint();
+    try {
+        proxy = await startProxyServer();
+        installProxyShutdownHooks(logger);
+        logger.info(`llm_router proxy listening on http://${proxy.host}:${proxy.port}`);
+    }
+    catch (error) {
+        if (error instanceof Error &&
+            'code' in error &&
+            error.code === 'EADDRINUSE') {
+            try {
+                if (await looksLikeLlmRouter(endpoint.baseUrl)) {
+                    logger.info(`llm_router proxy already running on ${endpoint.baseUrl}`);
+                    return;
+                }
+            }
+            catch {
+                // Fall through and surface the original bind error.
+            }
+        }
+        throw error;
+    }
+}
+export function logWalletBootstrap(logger, wallet) {
+    if (wallet.info.source === 'generated') {
+        logger.info('════════════════════════════════════════════════');
+        logger.info('  NEW llm_router WALLET GENERATED');
+        logger.info(`  Address : ${wallet.info.address}`);
+        logger.info(`  Network : ${wallet.info.network}`);
+        logger.info(`  Wallet  : ${wallet.info.walletFile}`);
+        logger.info('  Back up this private key before funding it');
+        logger.info('════════════════════════════════════════════════');
+        return;
+    }
+    logger.info(`llm_router wallet loaded (${wallet.info.source}) ${wallet.info.address} ${wallet.info.walletFile}`);
+}