@yzj01/llm-router 1.0.0

package/dist/proxy-CrRX9deF.d.ts

@@ -0,0 +1,222 @@
+type Tier = "SIMPLE" | "MEDIUM" | "COMPLEX" | "REASONING";
+interface ProxyConfig {
+    port: number;
+    upstreamUrl: string;
+    apiKey?: string;
+    headers?: Record<string, string>;
+    trace?: "off" | "summary" | "debug";
+}
+interface PhysicalModel {
+    id: string;
+    name: string;
+    inputPrice: number;
+    outputPrice: number;
+    contextWindow: number;
+    maxOutput: number;
+    reasoning: boolean;
+    toolCalling: boolean;
+}
+type PublicModelMetadata = {
+    name: string;
+    reasoning: boolean;
+    contextWindow: number;
+    maxTokens: number;
+    cost: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+    };
+};
+interface PublicModelRouter {
+    kind: "router";
+    metadata: PublicModelMetadata;
+}
+interface PublicModelAlias {
+    kind: "alias";
+    candidates: string[];
+    selection?: "cheapest" | "first";
+    metadata?: PublicModelMetadata;
+}
+type PublicModelConfig = PublicModelRouter | PublicModelAlias;
+interface TierEntry {
+    publicModel: string;
+    fallback?: string[];
+}
+interface RoutingTierBoundaries {
+    simpleMedium: number;
+    mediumComplex: number;
+    complexReasoning: number;
+}
+interface RoutingSpec {
+    tiers: Record<Tier, TierEntry>;
+    structuredOutputMinTier?: Tier;
+    ambiguousDefaultTier?: Tier;
+    tierBoundaries?: RoutingTierBoundaries;
+    confidenceThreshold?: number;
+}
+interface RawConfig {
+    version: number;
+    proxy: ProxyConfig;
+    models: PhysicalModel[];
+    publicModels: Record<string, PublicModelConfig>;
+    routing: RoutingSpec;
+}
+type ConfigSource = {
+    kind: "inline";
+    config: RawConfig;
+} | {
+    kind: "file";
+    path: string;
+};
+
+type TraceMode = "off" | "summary" | "debug";
+type TraceReason = "first-pass" | "user" | "reasoning" | "error";
+type TraceSessionAction = "none" | "set" | "reuse";
+type TraceAttempt = {
+    model: string;
+    status: "success" | "error";
+    error?: string;
+};
+type TraceSummaryInput = {
+    requestedModel: string;
+    routedModel: string;
+    actualModel: string;
+    tier: Tier;
+    profile: string;
+    reason: TraceReason;
+    routed: boolean;
+    explicit: boolean;
+    fallback: boolean;
+};
+type RouteTraceLog = TraceSummaryInput & {
+    trace: string;
+    method?: string;
+    confidence?: number;
+    score?: number;
+    agenticScore?: number;
+    attempts: TraceAttempt[];
+    sessionAction: TraceSessionAction;
+    promptPreview?: string;
+};
+type TraceWriter = (message: string) => void;
+type TraceLogger = {
+    debug?: TraceWriter;
+    info?: TraceWriter;
+};
+declare function resolveTraceWriter(logger?: TraceLogger): TraceWriter;
+declare function normalizeTraceMode(mode: unknown): TraceMode;
+declare function getPromptPreview(prompt: string): string;
+declare function buildTraceSummary(input: TraceSummaryInput): string;
+declare function emitRouteTrace(mode: TraceMode, detail: RouteTraceLog, writer?: TraceWriter): void;
+
+/**
+ * 自动路由请求的 session pinning 状态。
+ *
+ * 这里缓存的是最近一次稳定命中的 alias / physical model 组合，用来减少同一
+ * 会话内的 tier 抖动。
+ */
+type SessionEntry = {
+    sessionId: string;
+    physicalModelId: string;
+    routedPublicModel: string;
+    pinnedTier: Tier;
+    createdAt: number;
+    updatedAt: number;
+    expiresAt: number;
+    inputTokens: number;
+    outputTokens: number;
+    costEstimate: number;
+};
+type SessionConfig = {
+    enabled: boolean;
+    ttlMs: number;
+    cleanupIntervalMs: number;
+};
+declare const DEFAULT_SESSION_CONFIG: SessionConfig;
+type SessionStats = {
+    enabled: boolean;
+    size: number;
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    totalCostEstimate: number;
+};
+/**
+ * 仅服务于 `auto` 路由的轻量内存 session store。
+ *
+ * 它不是通用会话数据库；这里只关心 pinning、TTL 和少量成本统计。
+ */
+declare class SessionStore {
+    private readonly config;
+    private readonly sessions;
+    private readonly cleanupTimer?;
+    constructor(config?: Partial<SessionConfig>);
+    /**
+     * 读取一个未过期 session；如果已经过期，会顺手删除并返回 undefined。
+     */
+    getSession(sessionId: string | undefined): SessionEntry | undefined;
+    /**
+     * 创建或更新某个 session 的 pinning 结果，同时保留历史用量累计值。
+     */
+    setSession(sessionId: string | undefined, input: {
+        physicalModelId: string;
+        routedPublicModel: string;
+        pinnedTier: Tier;
+    }): SessionEntry | undefined;
+    /**
+     * 只刷新 TTL，不改动当前 alias / physical model 选择结果。
+     */
+    touchSession(sessionId: string | undefined): boolean;
+    clearSession(sessionId: string | undefined): boolean;
+    clearAll(): void;
+    /**
+     * 返回清理过期项后的聚合统计。
+     */
+    getStats(): SessionStats;
+    /**
+     * 把一次上游调用的 token / cost 增量累计到 session 上。
+     */
+    recordUsage(sessionId: string | undefined, usage: {
+        inputTokens?: number;
+        outputTokens?: number;
+        costEstimate?: number;
+    }): void;
+    /**
+     * 停止后台清理定时器。
+     */
+    close(): void;
+    private cleanupExpired;
+    private isExpired;
+}
+/**
+ * 把请求文本和工具集合归一化后压缩成稳定短哈希，作为隐式 session key。
+ */
+declare function hashRequestContent(content: string, toolNames?: string[]): string;
+/**
+ * 优先读取显式 `x-session-id`，否则退化为首条 user 消息内容哈希。
+ */
+declare function deriveSessionId(headers: Record<string, string | string[] | undefined>, messages: unknown[]): string | undefined;
+
+declare const VERSION = "1.0.0";
+/**
+ * 启动本地 HTTP proxy 所需的全部输入。
+ */
+type ProxyOptions = {
+    config: RawConfig;
+    traceLogger?: TraceLogger;
+    session?: Partial<SessionConfig>;
+};
+/**
+ * 已启动 proxy 的可关闭句柄。
+ */
+type ProxyHandle = {
+    port: number;
+    baseUrl: string;
+    close: () => Promise<void>;
+};
+/**
+ * 启动本地 Router HTTP 服务。
+ */
+declare function startProxy(options: ProxyOptions): Promise<ProxyHandle>;
+
+export { type ConfigSource as C, DEFAULT_SESSION_CONFIG as D, type ProxyOptions as P, type RawConfig as R, type SessionConfig as S, type Tier as T, VERSION as V, type ProxyHandle as a, type PhysicalModel as b, type TraceMode as c, type TraceLogger as d, type PublicModelConfig as e, type PublicModelMetadata as f, type RouteTraceLog as g, type SessionEntry as h, type SessionStats as i, SessionStore as j, type TierEntry as k, type TraceAttempt as l, type TraceReason as m, type TraceSessionAction as n, type TraceSummaryInput as o, type TraceWriter as p, buildTraceSummary as q, deriveSessionId as r, emitRouteTrace as s, getPromptPreview as t, hashRequestContent as u, normalizeTraceMode as v, resolveTraceWriter as w, startProxy as x };

package/openclaw.plugin.json

@@ -0,0 +1,37 @@
+{
+  "id": "llm-router",
+  "name": "LLM Router",
+  "description": "LLM Router local routing proxy for OpenClaw",
+  "version": "1.0.0",
+  "main": "./dist/index.js",
+  "activation": {
+    "onStartup": true
+  },
+  "configSchema": {
+    "type": "object",
+    "description": "Provide either llm-router config or llm-router configPath. port, upstreamUrl, and trace override config.proxy.* at runtime.",
+    "properties": {
+      "config": {
+        "type": "object",
+        "description": "Inline RawConfig passed directly to llm-router."
+      },
+      "configPath": {
+        "type": "string",
+        "description": "Path to a RawConfig JSON file for llm-router."
+      },
+      "port": {
+        "type": "number",
+        "description": "Runtime override config.proxy.port. Optional; if omitted, use the value from pluginConfig.config / configPath."
+      },
+      "upstreamUrl": {
+        "type": "string",
+        "description": "Runtime override config.proxy.upstreamUrl. Optional; if omitted, use the value from pluginConfig.config / configPath."
+      },
+      "trace": {
+        "type": "string",
+        "enum": ["off", "summary", "debug"],
+        "description": "Runtime override config.proxy.trace."
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@yzj01/llm-router",
+  "version": "1.0.0",
+  "description": "LLM Router local routing proxy for OpenAI-compatible Chat Completions APIs.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "llm-router": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "openclaw.plugin.json"
+  ],
+  "openclaw": {
+    "extensions": [
+      "./dist/index.js"
+    ]
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/ test/ scripts/ --no-error-on-unmatched-pattern",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "bench": "npx tsx scripts/bench.ts"
+  },
+  "keywords": [
+    "deepseek",
+    "llm-router",
+    "local-proxy",
+    "openai-compatible",
+    "model-routing"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^22.10.0",
+    "eslint": "^10.2.0",
+    "prettier": "^3.8.1",
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0",
+    "typescript-eslint": "^8.58.1",
+    "vitest": "^4.1.3"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}