dsh-model-pool 0.0.0-stage → 0.1.0

package/lib/strategies.js

@@ -0,0 +1,215 @@
+/**
+* Candidate ordering per routing strategy.
+* Pure: ordering only — the health gate lives in the router, so no candidate is
+* ever dropped and the input array is never mutated.
+* @module dsh-model-pool/lib/strategies
+*/
+
+/** Supported strategy ids, in picker order. */
+export const STRATEGIES = [
+	"priority",
+	"round-robin",
+	"weighted-random",
+	"least-used",
+	"fastest",
+	"cheapest",
+];
+
+/** Picker metadata for each strategy. */
+export const STRATEGY_LABELS = {
+	priority: {
+		id: "priority",
+		label: "Priority",
+		description: "Try providers in the configured priority order.",
+	},
+	"round-robin": {
+		id: "round-robin",
+		label: "Round-robin",
+		description: "Rotate the starting provider on every call.",
+	},
+	"weighted-random": {
+		id: "weighted-random",
+		label: "Weighted random",
+		description: "Draw providers at random, honouring each route's weight.",
+	},
+	"least-used": {
+		id: "least-used",
+		label: "Least used",
+		description: "Prefer the provider that has served the fewest calls.",
+	},
+	fastest: {
+		id: "fastest",
+		label: "Fastest",
+		description: "Prefer the provider with the lowest recent time-to-first-chunk.",
+	},
+	cheapest: {
+		id: "cheapest",
+		label: "Cheapest",
+		description: "Prefer the provider with the lowest declared cost hint.",
+	},
+};
+
+/** Strategy used for unknown or missing ids. */
+const DEFAULT_STRATEGY = "priority";
+
+/**
+* Key identifying one concrete route in health/stats lookups.
+* @param route - pool route.
+* @returns `provider\0model`.
+*/
+function routeKey(route) {
+	return `${route.provider}\u0000${route.model}`;
+}
+
+/**
+* Stable sort helper: `compare` returns a number, ties keep input order.
+* @param items - items to sort.
+* @param compare - comparator over items.
+* @returns a new sorted array.
+*/
+function stableSort(items, compare) {
+	return items
+		.map((item, index) => ({ item, index }))
+		.sort((left, right) => compare(left.item, right.item) || left.index - right.index)
+		.map((wrapped) => wrapped.item);
+}
+
+/**
+* Read one route's health record.
+* @param ctx - ordering context.
+* @param route - pool route.
+* @returns the health entry, or undefined when unknown.
+*/
+function healthOf(ctx, route) {
+	const health = ctx?.health;
+	if (health === undefined || health === null) return undefined;
+	if (typeof health.entryOf === "function") return health.entryOf(route.provider, route.model);
+	if (typeof health.get === "function") return health.get(route.provider, route.model);
+	if (typeof health === "object") return health[routeKey(route)];
+	return undefined;
+}
+
+/**
+* Read one route's usage count from ctx.stats, falling back to health.
+* @param ctx - ordering context.
+* @param route - pool route.
+* @returns the recorded use count, defaulting to 0.
+*/
+function usesOf(ctx, route) {
+	const stats = ctx?.stats;
+	let uses;
+	if (stats !== undefined && stats !== null) {
+		if (typeof stats.get === "function") uses = stats.get(route.provider, route.model)?.uses ?? stats.get(routeKey(route))?.uses;
+		else if (typeof stats === "object") uses = stats[routeKey(route)]?.uses;
+	}
+	if (uses === undefined) uses = healthOf(ctx, route)?.uses;
+	return Number.isFinite(uses) ? uses : 0;
+}
+
+/**
+* Read one route's EWMA time-to-first-chunk.
+* @param ctx - ordering context.
+* @param route - pool route.
+* @returns the latency in milliseconds, or undefined without a sample.
+*/
+function latencyOf(ctx, route) {
+	const value = healthOf(ctx, route)?.latencyMs;
+	return Number.isFinite(value) ? value : undefined;
+}
+
+/**
+* Resolve a route's configured weight.
+* @param ctx - ordering context.
+* @param route - pool route.
+* @returns the weight, defaulting to 1 and never below 0.
+*/
+function weightOf(ctx, route) {
+	const configured = ctx?.weights?.[route.provider] ?? ctx?.weights?.[routeKey(route)];
+	const weight = Number.isFinite(configured) ? configured : route.weight;
+	return Number.isFinite(weight) ? Math.max(0, weight) : 1;
+}
+
+/**
+* Resolve a route's cost hint.
+* @param ctx - ordering context.
+* @param route - pool route.
+* @returns the cost, defaulting to 0.
+*/
+function costOf(ctx, route) {
+	const configured = ctx?.costs?.[route.provider] ?? ctx?.costs?.[routeKey(route)];
+	const cost = Number.isFinite(configured) ? configured : route.cost;
+	return Number.isFinite(cost) ? cost : 0;
+}
+
+/**
+* Weighted sampling without replacement.
+* @param routes - candidates in priority order.
+* Zero-weight routes are never dropped: they follow the weighted ones in priority
+* order once no positive weight remains.
+* @param ctx - ordering context.
+* @returns a new array holding every candidate exactly once.
+*/
+function weightedSample(routes, ctx) {
+	const random = typeof ctx?.random === "function" ? ctx.random : Math.random;
+	const pool = routes.map((route) => ({ route, weight: weightOf(ctx, route) }));
+	const out = [];
+	while (pool.length > 0) {
+		const total = pool.reduce((sum, item) => sum + item.weight, 0);
+		let index = pool.findLastIndex((item) => item.weight > 0);
+		if (index < 0) index = 0;
+		else {
+			let target = random() * total;
+			if (!(target >= 0)) target = 0;
+			for (let cursor = 0; cursor < pool.length; cursor += 1) {
+				target -= pool[cursor].weight;
+				// Floating-point residue must not skip the final eligible slot.
+				if (target < 0 || (cursor === index && target === 0)) {
+					index = cursor;
+					break;
+				}
+			}
+		}
+		out.push(pool.splice(index, 1)[0].route);
+	}
+	return out;
+}
+
+/**
+* Order candidates for one call.
+* `round-robin` advances `ctx.roundRobin.cursor`; no other strategy mutates `ctx`.
+* @param strategy - strategy id; unknown ids fall back to priority order.
+* @param candidates - pool routes, already priority-sorted.
+* @param ctx - `{ now, health, roundRobin, stats, weights, costs, random }`.
+* @returns a new ordered array containing every candidate.
+*/
+export function order(strategy, candidates, ctx = {}) {
+	const routes = [...(Array.isArray(candidates) ? candidates : [])];
+	if (routes.length <= 1) return routes;
+	switch (strategy) {
+		case "round-robin": {
+			const state = ctx?.roundRobin;
+			const raw = Math.trunc(Number.isFinite(state?.cursor) ? state.cursor : 0);
+			if (state !== undefined && state !== null) state.cursor = raw + 1;
+			const start = ((raw % routes.length) + routes.length) % routes.length;
+			return [...routes.slice(start), ...routes.slice(0, start)];
+		}
+		case "weighted-random":
+			return weightedSample(routes, ctx);
+		case "least-used":
+			return stableSort(routes, (left, right) => usesOf(ctx, left) - usesOf(ctx, right));
+		case "fastest":
+			return stableSort(routes, (left, right) => {
+				const leftLatency = latencyOf(ctx, left);
+				const rightLatency = latencyOf(ctx, right);
+				if (leftLatency === undefined && rightLatency === undefined) return 0;
+				if (leftLatency === undefined) return 1;
+				if (rightLatency === undefined) return -1;
+				return leftLatency - rightLatency;
+			});
+		case "cheapest":
+			return stableSort(routes, (left, right) => costOf(ctx, left) - costOf(ctx, right));
+		case DEFAULT_STRATEGY:
+		default:
+			return routes;
+	}
+}

package/locale/en.json

@@ -0,0 +1,7 @@
+{
+  "meta": {
+    "title": "Model Pool",
+    "description": "Aggregates every registered provider's models into one model pool: pick a pooled model once and a configurable strategy (priority, round-robin, weighted random, least used, fastest, cheapest) routes each call to a concrete provider, with thinking-depth selection, failover and unavailable-route markers. A peak/idle policy can also rank providers differently inside and outside working hours. The Chinese statutory holiday calendar is fetched from a maintained public dataset and cached automatically — no dates are ever entered by hand."
+  },
+  "nav": "Model Pool"
+}

package/locale/zh.json

@@ -0,0 +1,7 @@
+{
+  "meta": {
+    "title": "模型池",
+    "description": "把所有已注册提供方的模型聚合进一个模型池：只需选择池内模型，即可由可配置的策略（优先级、轮询、加权随机、最少使用、最快、最便宜）为每次调用挑选具体提供方，并支持思考深度选择、失败转移与不可用路由标记。还可按高峰与空闲时段分别配置提供方排序；法定节假日日历自动取自公开维护的数据源并缓存更新，无需手动录入任何日期。"
+  },
+  "nav": "模型池"
+}

package/package.json

@@ -1,6 +1,79 @@
 {
   "name": "dsh-model-pool",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Aggregate every registered provider's models into one model pool: pick a pooled model once and let a configurable strategy route each call to a concrete provider, with thinking-depth selection and unavailable-route markers.",
+  "type": "module",
+  "license": "MIT",
+  "author": {
+    "name": "Bruce Zhang",
+    "email": "zttt183525594@gmail.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BruceZhang1993/dsh-model-pool.git"
+  },
+  "bugs": {
+    "url": "https://github.com/BruceZhang1993/dsh-model-pool/issues"
+  },
+  "homepage": "https://github.com/BruceZhang1993/dsh-model-pool#readme",
+  "engines": {
+    "node": ">=20"
+  },
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./client": "./client.js",
+    "./locale/*.json": "./locale/*.json",
+    "./icon": "./icon.svg",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.js",
+    "client.js",
+    "lib/*.js",
+    "cordis.patch.yml",
+    "locale/*.json",
+    "icon.svg",
+    "README.md",
+    "README.zh-CN.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "docs/installation*.md"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "check": "for f in index.js client.js lib/*.js; do node --check \"$f\" || exit 1; done"
+  },
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "dsh-plugin",
+    "model-pool",
+    "llm-router",
+    "provider-routing",
+    "failover",
+    "load-balancing",
+    "thinking-depth",
+    "holiday-calendar"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-llm": ">=0.2.0-rc.2 <0.3.0-0",
+    "@deepseek-ai/schemastery": "~3.18.5"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-settings"
+      ]
+    }
+  }
+}