dsh-model-pool 0.0.0-stage → 0.1.0

package/lib/grouping.js

@@ -0,0 +1,404 @@
+/**
+* Group every registered provider's models into logical pool models.
+* Pure: the caller supplies the registry snapshot; nothing here performs I/O.
+* @module dsh-model-pool/lib/grouping
+*/
+
+import { rankEfforts, rankOf, unionEfforts } from "./effort.js";
+
+/** Fallback priority base for providers missing from `providerOrder`. */
+const UNLISTED_PRIORITY = 1000;
+
+/** Placeholder protecting a `.` that sits between two digits (a version dot). */
+const VERSION_DOT = "\u0001";
+
+/**
+* Normalize a concrete model id into its pool id.
+* Strips a vendor prefix before the `/` (the last path segment wins, so every
+* vendor prefix is removed), lower-cases, collapses `-`/`_` runs to `-`, turns a
+* non-version `.` into `-`, drops a trailing `-latest` and collapses repeated `-`.
+* A `.` between digits is kept, so `deepseek-v4.1-flash` normalizes to itself.
+* @param raw - concrete model id, e.g. `openai/GPT-5_Latest`.
+* @returns the normalized pool id, or `""` for non-string input.
+*/
+export function normalizeModelId(raw) {
+	if (typeof raw !== "string") return "";
+	const slash = raw.lastIndexOf("/");
+	let id = (slash >= 0 ? raw.slice(slash + 1) : raw).trim().toLowerCase();
+	id = id.replace(/[-_]+/g, "-").replace(/(\d)\.(?=\d)/g, `$1${VERSION_DOT}`).replace(/\./g, "-");
+	id = id.replace(/-latest$/, "");
+	id = id.replace(/-+/g, "-").replace(/^-+|-+$/g, "").split(VERSION_DOT).join(".");
+	return id;
+}
+
+/**
+* Display name for a pool model.
+* @param model - concrete model entry.
+* @param fallback - id used when the entry has no name.
+* @returns the display name.
+*/
+function displayName(model, fallback) {
+	const name = model?.name;
+	return typeof name === "string" && name.trim() !== "" ? name : fallback;
+}
+
+/**
+* Priority of one provider.
+* @param providerId - provider id.
+* @param providerOrder - configured provider ids, highest priority first.
+* @param registrationIndex - index of the provider in registry order.
+* @returns the priority, `0`-based and ascending.
+*/
+function priorityOf(providerId, providerOrder, registrationIndex) {
+	const listed = (Array.isArray(providerOrder) ? providerOrder : []).indexOf(providerId);
+	return listed >= 0 ? listed : UNLISTED_PRIORITY + registrationIndex;
+}
+
+/**
+* Whether a provider passes the include/exclude filters.
+* @param providerId - provider id.
+* @param include - provider allowlist; empty means every provider.
+* @param exclude - provider denylist.
+* @returns true when the provider may join the pool.
+*/
+function providerAllowed(providerId, include, exclude) {
+	const allowed = Array.isArray(include) ? include : [];
+	const denied = Array.isArray(exclude) ? exclude : [];
+	if (allowed.length > 0 && !allowed.includes(providerId)) return false;
+	return !denied.includes(providerId);
+}
+
+/**
+* Whether a model is denied by `excludeModels`.
+* An entry matches when it equals the concrete id or is a case-insensitive substring
+* of the normalized pool id.
+* @param modelId - concrete model id.
+* @param poolId - normalized pool id.
+* @param excludeModels - configured deny entries.
+* @returns true when the model must be skipped.
+*/
+function modelExcluded(modelId, poolId, excludeModels) {
+	if (!Array.isArray(excludeModels)) return false;
+	return excludeModels.some((entry) => {
+		if (typeof entry !== "string" || entry === "") return false;
+		if (entry === modelId) return true;
+		return poolId.includes(entry.toLowerCase());
+	});
+}
+
+/**
+* Copy one candidate into a `PoolRoute`.
+* @param provider - provider entry.
+* @param model - concrete model entry.
+* @param priority - provider priority.
+* @param registrationIndex - provider registration index used as a tie-break.
+* @returns the pool route.
+*/
+function toRoute(provider, model, priority, registrationIndex) {
+	const route = {
+		provider: provider.id,
+		model: model.id,
+		name: displayName(model, model.id),
+		priority,
+		weight: Number.isFinite(model.weight) && model.weight >= 1 ? model.weight : 1,
+	};
+	// The provider's display name rides along so a surface can name the upstream
+	// without keeping its own copy of the registry.
+	if (typeof provider.name === "string" && provider.name !== "") route.providerName = provider.name;
+	if (typeof model.description === "string") route.description = model.description;
+	if (model.reasoning !== undefined && model.reasoning !== null) {
+		const efforts = rankEfforts(model.reasoning.efforts);
+		if (efforts.length > 0) {
+			route.reasoning = { efforts };
+			const defaultEffort = model.reasoning.defaultEffort;
+			if (typeof defaultEffort === "string" && efforts.some((effort) => effort.id === defaultEffort)) {
+				route.reasoning.defaultEffort = defaultEffort;
+			}
+		}
+	}
+	if (Number.isFinite(model.contextWindow) && model.contextWindow > 0) {
+		route.contextWindow = model.contextWindow;
+	}
+	route.registrationIndex = registrationIndex;
+	return route;
+}
+
+/**
+* Public copy of a route: drops the internal registration index and clones the
+* reasoning block so pools never share mutable state.
+* @param route - internal route.
+* @returns the route as exposed on a `PoolModel`.
+*/
+function routeForPool(route) {
+	const copy = {
+		provider: route.provider,
+		model: route.model,
+		name: route.name,
+		priority: route.priority,
+		weight: route.weight,
+	};
+	if (typeof route.providerName === "string") copy.providerName = route.providerName;
+	if (typeof route.description === "string") copy.description = route.description;
+	if (route.reasoning !== undefined) {
+		copy.reasoning = {
+			efforts: route.reasoning.efforts.map((effort) => ({ ...effort })),
+		};
+		if (typeof route.reasoning.defaultEffort === "string") {
+			copy.reasoning.defaultEffort = route.reasoning.defaultEffort;
+		}
+	}
+	if (route.contextWindow !== undefined) copy.contextWindow = route.contextWindow;
+	return copy;
+}
+
+/**
+* Aggregate the candidate routes of one pool model.
+* @param id - pool id.
+* @param routes - candidate routes, already priority-sorted.
+* @param name - display name override, used by manual groups.
+* @returns the `PoolModel`.
+*/
+function toPoolModel(id, routes, name = undefined) {
+	const ordered = [...routes].sort(
+		(left, right) => left.priority - right.priority || left.registrationIndex - right.registrationIndex,
+	);
+	const head = ordered[0];
+	const providerCount = new Set(ordered.map((route) => route.provider)).size;
+	const pool = {
+		id,
+		name: typeof name === "string" && name.trim() !== "" ? name : displayName(head, id),
+		description: `${providerCount} provider${providerCount === 1 ? "" : "s"}`,
+		routes: ordered.map((route) => routeForPool(route)),
+	};
+	// `unionEfforts` folds provider spellings of one tier (`off` / `disabled`) so
+	// the pool offers each tier once. Building the union inline would duplicate
+	// the label while the two entries still routed to different wire values.
+	const union = unionEfforts(ordered.map((route) => route.reasoning?.efforts ?? []));
+	if (union.length > 0) {
+		pool.reasoning = { efforts: union };
+		const shared = sharedDefaultEffort(ordered, union);
+		if (shared !== undefined) pool.reasoning.defaultEffort = shared;
+	}
+	const windows = ordered
+		.map((route) => route.contextWindow)
+		.filter((window) => Number.isFinite(window));
+	if (windows.length > 0) pool.contextWindow = Math.min(...windows);
+	return pool;
+}
+
+/**
+* Pick the effort id most candidates share; ties go to the highest canonical rank.
+* @param routes - candidate routes.
+* @param union - the ranked effort union of the pool.
+* @returns the shared default effort id, or undefined when no candidate declares one.
+*/
+function sharedDefaultEffort(routes, union) {
+	const counts = new Map();
+	for (const route of routes) {
+		const defaultEffort = route.reasoning?.defaultEffort;
+		if (typeof defaultEffort !== "string") continue;
+		counts.set(defaultEffort, (counts.get(defaultEffort) ?? 0) + 1);
+	}
+	if (counts.size === 0) return undefined;
+	let best;
+	let bestCount = -1;
+	for (const [effortId, count] of counts) {
+		const rank = rankOf(effortId);
+		const bestRank = best === undefined ? -1 : rankOf(best);
+		if (count > bestCount || (count === bestCount && rank > bestRank)) {
+			best = effortId;
+			bestCount = count;
+		}
+	}
+	if (!union.some((effort) => effort.id === best)) return undefined;
+	return best;
+}
+
+/**
+* Collect the candidate routes of every provider, keyed by pool id.
+* @param providers - registry providers, in registration order.
+* @param options - grouping config.
+* @returns `{ pools, routeIndex }`, where `routeIndex` lists every route in
+* registration order for manual groups.
+*/
+function collectPools(providers, options) {
+	const pools = new Map();
+	const routeIndex = [];
+	(Array.isArray(providers) ? providers : []).forEach((provider, registrationIndex) => {
+		if (provider === null || typeof provider !== "object" || typeof provider.id !== "string") return;
+		if (!providerAllowed(provider.id, options.include, options.exclude)) return;
+		if (provider.id === options.providerId) return;
+		const priority = priorityOf(provider.id, options.providerOrder, registrationIndex);
+		for (const model of Array.isArray(provider.models) ? provider.models : []) {
+			if (model === null || typeof model !== "object" || typeof model.id !== "string") continue;
+			const poolId = normalizeModelId(model.id);
+			if (poolId === "") continue;
+			if (modelExcluded(model.id, poolId, options.excludeModels)) continue;
+			const route = toRoute(provider, model, priority, registrationIndex);
+			if (!pools.has(poolId)) pools.set(poolId, []);
+			pools.get(poolId).push(route);
+			routeIndex.push({ route, poolId });
+		}
+	});
+	return { pools, routeIndex };
+}
+
+/**
+* Compile one group selector into a predicate over a concrete route.
+*
+* Accepted forms, matched against the concrete model id and the normalized pool
+* id (the last one is what makes a provider-prefixed id usable):
+*
+* - `provider/model` — exact concrete route, e.g. `workbuddy/deepseek-v4.1-flash`
+* - `model-id` — exact concrete id, e.g. `deepseek-v4.1-flash-free`
+* - `normalized-id` — the normalized pool id, e.g. `deepseek-v4.1-flash`
+* - any of the above with `*`/`?` glob wildcards, e.g. `deepseek-v4.1-flash*`
+*
+* Glob is a deliberate convenience: one pattern can claim every tier suffix of
+* the same model (`-free`, `-latest`, …) without listing each id.
+*
+* @param entry - one configured selector.
+* @returns a predicate, or undefined when the entry is not a usable string.
+*/
+function selectorFor(entry) {
+	if (typeof entry !== "string") return undefined;
+	const raw = entry.trim();
+	if (raw === "") return undefined;
+	const pattern = raw.toLowerCase();
+	const glob = pattern.includes("*") || pattern.includes("?");
+	const regex = glob ? globToRegExp(pattern) : undefined;
+	return ({ route, poolId }) => {
+		const concrete = `${route.provider}/${route.model}`.toLowerCase();
+		const model = route.model.toLowerCase();
+		const normalized = poolId;
+		if (regex !== undefined) return regex.test(concrete) || regex.test(model) || regex.test(normalized);
+		return pattern === concrete || pattern === model || pattern === normalized;
+	};
+}
+
+/**
+* Translate a `*`/`?` glob into an anchored regular expression.
+* Every other character is escaped, so a model id containing `.` or `+` matches
+* literally.
+* @param pattern - lower-cased glob.
+* @returns the compiled expression.
+*/
+function globToRegExp(pattern) {
+	let source = "";
+	for (const char of pattern) {
+		if (char === "*") source += ".*";
+		else if (char === "?") source += ".";
+		else source += char.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+	}
+	return new RegExp(`^${source}$`);
+}
+
+/**
+* Build the manual groups declared by `modelGroups`.
+*
+* A group **claims** the routes it selects: with `merge` (the default) those
+* routes leave their natural single-id pool, so one logical model served under
+* several different provider ids becomes one row instead of several. A natural
+* pool left with no routes disappears. With `merge: false` the group is instead
+* an additive curated pool and the natural pools keep their routes.
+*
+* Claims are first-come: a route is taken by the first group whose selectors
+* match it, so listing the same id in two groups is not an error — the earlier
+* group wins and the later one simply gets nothing from it.
+*
+* @param modelGroups - configured groups.
+* @param routeIndex - every route collected from the registry.
+* @returns `{ groups, claimed }` where `claimed` holds the merged-away routes.
+*/
+function buildManualGroups(modelGroups, routeIndex) {
+	const claimed = new Set();
+	const groups = [];
+	for (const group of Array.isArray(modelGroups) ? modelGroups : []) {
+		if (group === null || typeof group !== "object") continue;
+		if (typeof group.name !== "string" || group.name.trim() === "") continue;
+		const selectors = (Array.isArray(group.models) ? group.models : [])
+			.map(selectorFor)
+			.filter((predicate) => predicate !== undefined);
+		if (selectors.length === 0) continue;
+		const chosen = routeIndex.filter(
+			(entry) => !claimed.has(entry.route) && selectors.some((matches) => matches(entry)),
+		);
+		if (chosen.length === 0) continue;
+		const merge = group.merge !== false;
+		if (merge) for (const { route } of chosen) claimed.add(route);
+		const id = typeof group.id === "string" && group.id.trim() !== "" ? group.id.trim() : group.name.trim();
+		groups.push({
+			model: toPoolModel(id, chosen.map((entry) => entry.route), group.name.trim()),
+			merge,
+		});
+	}
+	return { groups, claimed };
+}
+
+/**
+* Build the pool snapshot from a registry read.
+* @param input - `{ providers, modelGroups, providerOrder, include, exclude,
+* excludeModels, providerId, failures }`.
+* @param optionsOrFailures - optional provider catalog failures, or a second options bag.
+* @param failures - optional provider catalog failures.
+* @returns `{ models, failures }` per the contract.
+*/
+export function buildPoolSnapshot(input = {}, optionsOrFailures = undefined, failures = undefined) {
+	const source = input ?? {};
+	const { providers, modelGroups, providerOrder, include, exclude, excludeModels, providerId } = source;
+	const { pools, routeIndex } = collectPools(providers, {
+		providerId,
+		providerOrder,
+		include,
+		exclude,
+		excludeModels,
+	});
+
+	// Manual groups run first: a merged group removes its routes from the natural
+	// single-id pools, which is what makes several provider ids collapse into one
+	// row. Additive groups leave the natural pools untouched.
+	const manual = buildManualGroups(modelGroups, routeIndex);
+	const natural = [...pools]
+		.map(([id, routes]) => [id, manual.claimed.size === 0 ? routes : routes.filter((route) => !manual.claimed.has(route))])
+		.filter(([, routes]) => routes.length > 0);
+
+	const byId = new Map(natural.map(([id, routes]) => [id, toPoolModel(id, routes)]));
+	for (const { model, merge } of manual.groups) {
+		// A merged group owns its id outright. An additive group must not silently
+		// replace a natural pool with the same id, so its id is suffixed instead.
+		const id = merge || !byId.has(model.id) ? model.id : uniqueGroupId(model.id, byId);
+		byId.set(id, id === model.id ? model : { ...model, id });
+	}
+
+	const models = [...byId.values()];
+	models.sort((left, right) => left.name.localeCompare(right.name, "en") || left.id.localeCompare(right.id, "en"));
+	return { models, failures: failureList(source, optionsOrFailures, failures) };
+}
+
+/**
+* Pick an id for an additive group whose name collides with a natural pool.
+* @param preferred - the configured group id.
+* @param byId - pools already built.
+* @returns the first free `preferred`, `preferred-2`, `preferred-3`, …
+*/
+function uniqueGroupId(preferred, byId) {
+	if (!byId.has(preferred)) return preferred;
+	for (let suffix = 2; ; suffix += 1) {
+		const candidate = `${preferred}-${suffix}`;
+		if (!byId.has(candidate)) return candidate;
+	}
+}
+
+/**
+* Resolve the provider catalog failures to report.
+* @param source - the input bag.
+* @param optionsOrFailures - array of failures, or an options bag carrying `failures`.
+* @param failures - explicit failures argument.
+* @returns the failure list.
+*/
+function failureList(source, optionsOrFailures, failures) {
+	if (Array.isArray(failures)) return failures;
+	if (Array.isArray(optionsOrFailures)) return optionsOrFailures;
+	const candidate = failures ?? optionsOrFailures?.failures ?? source.failures;
+	return Array.isArray(candidate) ? candidate : [];
+}

package/lib/health.js

@@ -0,0 +1,175 @@
+/**
+* In-memory availability and latency registry for pool routes.
+* Pure bookkeeping: no I/O, no timers; callers supply `now`.
+* @module dsh-model-pool/lib/health
+*/
+
+/** Weight of a fresh latency sample in the EWMA. */
+const EWMA_ALPHA = 0.3;
+
+/** Cooldown used when a caller omits one. */
+const DEFAULT_COOLDOWN_MS = 60_000;
+
+const SEPARATOR = "\u0000";
+
+/**
+* Registry key for one concrete route.
+* @param provider - provider id.
+* @param model - concrete model id.
+* @returns the `provider\0model` key.
+*/
+function routeKey(provider, model) {
+	return `${provider}${SEPARATOR}${model}`;
+}
+
+/**
+* Fresh health record for a route.
+* @param provider - provider id.
+* @param model - concrete model id.
+* @returns a record in the `unknown` state.
+*/
+function blankEntry(provider, model) {
+	return { provider, model, state: "unknown", failures: 0, successes: 0, uses: 0 };
+}
+
+/**
+* Per-route health: consecutive failures, successes, EWMA time-to-first-chunk and
+* cooldown state. One instance lives on the plugin; every method is synchronous.
+*/
+export class HealthRegistry {
+	constructor() {
+		/** @type {Map<string, object>} */
+		this.records = new Map();
+	}
+
+	/**
+	* Record a completed attempt and fold its latency into the EWMA.
+	* @param provider - provider id.
+	* @param model - concrete model id.
+	* @param latencyMs - time to first chunk, in milliseconds.
+	* @param now - clock reading for the success timestamp.
+	* @returns the updated record.
+	*/
+	recordSuccess(provider, model, latencyMs, now = Date.now()) {
+		const entry = this.#entry(provider, model);
+		entry.state = "ok";
+		entry.failures = 0;
+		entry.successes += 1;
+		entry.uses += 1;
+		entry.lastOkAt = now;
+		delete entry.reason;
+		delete entry.cooldownUntil;
+		if (Number.isFinite(latencyMs)) {
+			entry.latencyMs =
+				entry.latencyMs === undefined
+					? latencyMs
+					: (1 - EWMA_ALPHA) * entry.latencyMs + EWMA_ALPHA * latencyMs;
+		}
+		return entry;
+	}
+
+	/**
+	* Record a failed attempt and open its cooldown window.
+	* @param provider - provider id.
+	* @param model - concrete model id.
+	* @param reason - failure code or message.
+	* @param now - clock reading for the failure timestamp.
+	* @param cooldownMs - cooldown length used for the stored `cooldownUntil`.
+	* @returns the updated record.
+	*/
+	recordFailure(provider, model, reason, now = Date.now(), cooldownMs = DEFAULT_COOLDOWN_MS) {
+		const entry = this.#entry(provider, model);
+		entry.state = "unavailable";
+		entry.failures += 1;
+		entry.uses += 1;
+		entry.lastErrorAt = now;
+		entry.cooldownUntil = now + cooldownMs;
+		if (reason !== undefined) entry.reason = reason;
+		return entry;
+	}
+
+	/**
+	* Current state of a route at `now`.
+	* @param provider - provider id.
+	* @param model - concrete model id.
+	* @param now - clock reading.
+	* @param cooldownMs - cooldown length applied to the last error.
+	* @returns `unknown` before first use, `ok` while healthy, `unavailable` inside the
+	* cooldown window and `degraded` after it.
+	*/
+	statusOf(provider, model, now = Date.now(), cooldownMs = DEFAULT_COOLDOWN_MS) {
+		const entry = this.records.get(routeKey(provider, model));
+		if (entry === undefined) return "unknown";
+		if (entry.failures === 0) {
+			entry.state = entry.successes > 0 ? "ok" : "unknown";
+			delete entry.cooldownUntil;
+			return entry.state;
+		}
+		const cooldownUntil = (entry.lastErrorAt ?? now) + cooldownMs;
+		entry.cooldownUntil = cooldownUntil;
+		entry.state = now < cooldownUntil ? "unavailable" : "degraded";
+		return entry.state;
+	}
+
+	/**
+	* Whether a route may be routed to at `now`.
+	* @param provider - provider id.
+	* @param model - concrete model id.
+	* @param now - clock reading.
+	* @param cooldownMs - cooldown length applied to the last error.
+	* @returns false only inside the cooldown window.
+	*/
+	isAvailable(provider, model, now = Date.now(), cooldownMs = DEFAULT_COOLDOWN_MS) {
+		return this.statusOf(provider, model, now, cooldownMs) !== "unavailable";
+	}
+
+	/**
+	* Read one record without creating it.
+	* @param provider - provider id.
+	* @param model - concrete model id.
+	* @returns a copy of the record, or undefined when the route was never used.
+	*/
+	entryOf(provider, model) {
+		const entry = this.records.get(routeKey(provider, model));
+		return entry === undefined ? undefined : { ...entry };
+	}
+
+	/**
+	* Every record, in first-seen order.
+	* @returns copies of all records.
+	*/
+	entries() {
+		return [...this.records.values()].map((entry) => ({ ...entry }));
+	}
+
+	/**
+	* JSON-friendly view for the HTTP state route.
+	* @returns a `provider/model` keyed map of record copies.
+	*/
+	snapshot() {
+		const out = {};
+		for (const entry of this.records.values()) out[`${entry.provider}/${entry.model}`] = { ...entry };
+		return out;
+	}
+
+	/** Drop every record. */
+	reset() {
+		this.records.clear();
+	}
+
+	/**
+	* Get or create the record for a route.
+	* @param provider - provider id.
+	* @param model - concrete model id.
+	* @returns the live record.
+	*/
+	#entry(provider, model) {
+		const key = routeKey(provider, model);
+		let entry = this.records.get(key);
+		if (entry === undefined) {
+			entry = blankEntry(provider, model);
+			this.records.set(key, entry);
+		}
+		return entry;
+	}
+}