@dbx-tools/model 0.1.42 → 0.1.48

package/README.md

@@ -0,0 +1,76 @@
+# @dbx-tools/model
+
+Workspace-aware model selection for Databricks Model Serving: list a
+workspace's `/serving-endpoints` (cached), fuzzy-match loose names like
+`"claude sonnet"` to real endpoint ids, rank endpoints by capability
+class, and resolve a single usable model id with an offline fallback
+floor.
+
+This is the server-side package (it holds a `WorkspaceClient` and
+AppKit's cache). Browser consumers want the pure
+[`@dbx-tools/model-shared`](../model-shared) surface, which this package
+re-exports.
+
+## Install
+
+```bash
+npm install @dbx-tools/model
+```
+
+Peer: `@databricks/appkit` (provides the cache the listing runs through).
+
+## Usage
+
+Hold a `WorkspaceClient` and just want a usable model id? `selectModel`
+lists the catalogue (cached) and resolves in one call. An `explicit`
+name is fuzzy-matched; without one, a `modelClass` ceiling (or the
+operator `fallbacks`, then the static floor) decides.
+
+```ts
+import { WorkspaceClient } from "@databricks/sdk-experimental";
+import { selectModel, searchModels } from "@dbx-tools/model";
+
+const client = new WorkspaceClient({});
+const host = (await client.config.getHost()).toString();
+
+// Fuzzy name -> real endpoint id (+ how it was reached).
+const { modelId, source } = await selectModel(client, host, {
+  explicit: "claude sonnet",
+}); // -> { modelId: "databricks-claude-sonnet-4-6", source: "fuzzy-match" }
+
+// Best balanced-or-cheaper chat model the workspace actually has.
+const fast = await selectModel(client, host, { modelClass: "chat-balanced" });
+
+// Or get the full ranked list (model picker / CLI).
+const ranked = await searchModels(client, host, { search: "opus", limit: 5 });
+```
+
+The capability class acts as a **ceiling**: `chat-balanced` can fall to
+`chat-fast` but never escalate to `chat-thinking`. Embedding endpoints
+surface only when `modelClass` is explicitly `embedding`.
+
+### Pure helpers (no I/O)
+
+If you already hold the endpoint list (e.g. from a cached `/models`
+response), use the pure functions directly:
+
+```ts
+import { resolveModelId, rankModels, resolveModel } from "@dbx-tools/model";
+
+resolveModelId("claude sonnet", endpoints); // single best fuzzy match
+rankModels(endpoints, { search: "opus", limit: 3 }); // ranked list
+resolveModel(endpoints, { modelClass: "chat-fast" }); // single id + source
+```
+
+## How resolution works
+
+1. **Explicit ask** - fuzzy-matched within the optional class ceiling
+   (or returned verbatim when `fuzzy: false`).
+2. **No explicit ask** - an operator-pinned `fallback` that exists in
+   the live catalogue wins first, then the ranked live catalogue, then a
+   small static `FALLBACK_MODEL_IDS` floor when the catalogue yields
+   nothing in range (so a model id is always returned even offline).
+
+Capability bands are derived from the live workspace catalogue (the
+Foundation Model API quality/speed/cost scores), not a hand-maintained
+table - see `@dbx-tools/model-shared` for the classifier.

package/dist/index.d.ts

@@ -4,7 +4,7 @@
  * Bundles the package's Node-side Model Serving access (cached
  * `/serving-endpoints` listing plus fuzzy name resolution), the
  * workspace-aware {@link resolveModel} selector, and the server-only
- * offline fallback opinion (`FALLBACK_MODEL_IDS` / `modelsForTier`)
+ * offline fallback opinion (`FALLBACK_MODEL_IDS` / `modelsForClass`)
  * with a re-export of the pure `@dbx-tools/model-shared` surface
  * (capability tiers, the score profile, the endpoint descriptor, and
  * the tier classifier) so a single `from "@dbx-tools/model"` import
@@ -16,6 +16,7 @@
  * pure (types + sync functions) and safe for any runtime.
  */
 export * from "@dbx-tools/model-shared";
+export * from "./src/classes.js";
 export * from "./src/fallback.js";
 export * from "./src/resolve.js";
 export * from "./src/serving.js";

package/dist/index.js

@@ -4,7 +4,7 @@
  * Bundles the package's Node-side Model Serving access (cached
  * `/serving-endpoints` listing plus fuzzy name resolution), the
  * workspace-aware {@link resolveModel} selector, and the server-only
- * offline fallback opinion (`FALLBACK_MODEL_IDS` / `modelsForTier`)
+ * offline fallback opinion (`FALLBACK_MODEL_IDS` / `modelsForClass`)
  * with a re-export of the pure `@dbx-tools/model-shared` surface
  * (capability tiers, the score profile, the endpoint descriptor, and
  * the tier classifier) so a single `from "@dbx-tools/model"` import
@@ -16,6 +16,7 @@
  * pure (types + sync functions) and safe for any runtime.
  */
 export * from "@dbx-tools/model-shared";
+export * from "./src/classes.js";
 export * from "./src/fallback.js";
 export * from "./src/resolve.js";
 export * from "./src/serving.js";

package/dist/src/classes.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Model-class ordering for the model service.
+ *
+ * `@dbx-tools/model-shared` declares the {@link ModelClass} values and
+ * their schema; the *behavior* over those values - the chat capability
+ * order, the "this class and below" ceiling, and coercing loose request
+ * input to a class - lives here in the service so the shared
+ * wire-format surface stays purely declarative.
+ */
+import { ModelClass } from "@dbx-tools/model-shared";
+/**
+ * Chat capability ladder in descending order - most capable
+ * ({@link ModelClass.ChatThinking}) first, least
+ * ({@link ModelClass.ChatFast}) last. {@link ModelClass.Embedding} is a
+ * separate modality and is deliberately absent: the ceiling never spans
+ * it. This is the order used to filter "this class and below" and to
+ * break ranking ties toward the more capable model.
+ */
+export declare const CHAT_CLASS_ORDER: readonly ModelClass[];
+/**
+ * Every class in display order: the chat ladder followed by
+ * {@link ModelClass.Embedding}. Used when flattening a full
+ * classification (e.g. stamping the class onto each cached endpoint).
+ */
+export declare const MODEL_CLASS_ORDER: readonly ModelClass[];
+/** Whether `cls` is one of the chat capability bands (vs. embedding). */
+export declare function isChatClass(cls: ModelClass): boolean;
+/**
+ * Coerce an arbitrary value (query string, header, body field) to a
+ * {@link ModelClass}, returning `null` when it isn't a known class.
+ * Lets a route accept a class request without throwing on junk input.
+ *
+ * Matches the full slug first (`"chat-fast"`, `"embedding"`), then -
+ * for a bare chat band - retries with a `chat-` prefix, so the shorthand
+ * `"thinking"` / `"balanced"` / `"fast"` resolves to the corresponding
+ * `chat-*` class.
+ */
+export declare function parseModelClass(value: unknown): ModelClass | null;
+/**
+ * Classes at or below `cls` in chat capability: the class itself plus
+ * every less-capable chat band, in {@link CHAT_CLASS_ORDER}. Treats a
+ * chat `cls` as a ceiling - requesting {@link ModelClass.ChatBalanced}
+ * yields `[ChatBalanced, ChatFast]`, never
+ * {@link ModelClass.ChatThinking} - so a class ask can degrade downward
+ * to a smaller chat model but never escalate to a larger one.
+ *
+ * {@link ModelClass.Embedding} is its own modality, not a rung on the
+ * chat ladder, so it yields just `[Embedding]`. An unrecognized class
+ * yields the full chat ladder.
+ */
+export declare function classesAtOrBelow(cls: ModelClass): ModelClass[];

package/dist/src/classes.js

@@ -0,0 +1,71 @@
+/**
+ * Model-class ordering for the model service.
+ *
+ * `@dbx-tools/model-shared` declares the {@link ModelClass} values and
+ * their schema; the *behavior* over those values - the chat capability
+ * order, the "this class and below" ceiling, and coercing loose request
+ * input to a class - lives here in the service so the shared
+ * wire-format surface stays purely declarative.
+ */
+import { ModelClass, ModelClassSchema } from "@dbx-tools/model-shared";
+/**
+ * Chat capability ladder in descending order - most capable
+ * ({@link ModelClass.ChatThinking}) first, least
+ * ({@link ModelClass.ChatFast}) last. {@link ModelClass.Embedding} is a
+ * separate modality and is deliberately absent: the ceiling never spans
+ * it. This is the order used to filter "this class and below" and to
+ * break ranking ties toward the more capable model.
+ */
+export const CHAT_CLASS_ORDER = [
+    ModelClass.ChatThinking,
+    ModelClass.ChatBalanced,
+    ModelClass.ChatFast,
+];
+/**
+ * Every class in display order: the chat ladder followed by
+ * {@link ModelClass.Embedding}. Used when flattening a full
+ * classification (e.g. stamping the class onto each cached endpoint).
+ */
+export const MODEL_CLASS_ORDER = [
+    ...CHAT_CLASS_ORDER,
+    ModelClass.Embedding,
+];
+/** Whether `cls` is one of the chat capability bands (vs. embedding). */
+export function isChatClass(cls) {
+    return CHAT_CLASS_ORDER.includes(cls);
+}
+/**
+ * Coerce an arbitrary value (query string, header, body field) to a
+ * {@link ModelClass}, returning `null` when it isn't a known class.
+ * Lets a route accept a class request without throwing on junk input.
+ *
+ * Matches the full slug first (`"chat-fast"`, `"embedding"`), then -
+ * for a bare chat band - retries with a `chat-` prefix, so the shorthand
+ * `"thinking"` / `"balanced"` / `"fast"` resolves to the corresponding
+ * `chat-*` class.
+ */
+export function parseModelClass(value) {
+    const exact = ModelClassSchema.safeParse(value);
+    if (exact.success)
+        return exact.data;
+    const prefixed = ModelClassSchema.safeParse(`chat-${value}`);
+    return prefixed.success ? prefixed.data : null;
+}
+/**
+ * Classes at or below `cls` in chat capability: the class itself plus
+ * every less-capable chat band, in {@link CHAT_CLASS_ORDER}. Treats a
+ * chat `cls` as a ceiling - requesting {@link ModelClass.ChatBalanced}
+ * yields `[ChatBalanced, ChatFast]`, never
+ * {@link ModelClass.ChatThinking} - so a class ask can degrade downward
+ * to a smaller chat model but never escalate to a larger one.
+ *
+ * {@link ModelClass.Embedding} is its own modality, not a rung on the
+ * chat ladder, so it yields just `[Embedding]`. An unrecognized class
+ * yields the full chat ladder.
+ */
+export function classesAtOrBelow(cls) {
+    if (cls === ModelClass.Embedding)
+        return [ModelClass.Embedding];
+    const index = CHAT_CLASS_ORDER.indexOf(cls);
+    return index < 0 ? [...CHAT_CLASS_ORDER] : [...CHAT_CLASS_ORDER.slice(index)];
+}

package/dist/src/fallback.d.ts

@@ -5,9 +5,9 @@
  * no user token, the service principal can't list, or the workspace is
  * unreachable - the resolver still has to name *some* endpoint. This
  * module holds that floor: a small, hard-coded set of well-known
- * Foundation Model API endpoint names, each bucketed into a
- * {@link ModelTier} by the shared {@link classifyByFamily} heuristic
- * (no tiers are hard-coded here) and ordered best-first.
+ * Foundation Model API endpoint names, each bucketed into a chat
+ * {@link ModelClass} by the shared {@link classifyByFamily} heuristic
+ * (no classes are hard-coded here) and ordered best-first.
  *
  * This is deliberately *server-only*. A browser client never talks to
  * Databricks directly - it always goes through this server - so it has
@@ -15,21 +15,22 @@
  * list; it consumes the live `/models` response instead. The pure
  * classifier ({@link classifyEndpoints}) is what the client shares.
  */
-import { ModelTier } from "@dbx-tools/model-shared";
+import { ModelClass } from "@dbx-tools/model-shared";
 /**
- * Static fallback model ids for a tier, drawn from the small built-in
- * {@link FALLBACK_MODEL_NAMES} list and ordered best-first by family
- * rank. Sync and workspace-independent: this is the *fallback opinion*
- * used to seed default lists or when the live catalogue is unreachable
- * - live resolution prefers `classifyEndpoints`.
+ * Static fallback model ids for a chat class, drawn from the small
+ * built-in {@link FALLBACK_MODEL_NAMES} list and ordered best-first by
+ * family rank. Sync and workspace-independent: this is the *fallback
+ * opinion* used to seed default lists or when the live catalogue is
+ * unreachable - live resolution prefers `classifyEndpoints`. Returns
+ * `[]` for {@link ModelClass.Embedding} (the floor is chat-only).
  */
-export declare function modelsForTier(tier: ModelTier): readonly string[];
-/** Top static fallback model id for a tier. */
-export declare function modelForTier(tier: ModelTier): string;
+export declare function modelsForClass(cls: ModelClass): readonly string[];
+/** Top static fallback model id for a chat class. */
+export declare function modelForClass(cls: ModelClass): string;
 /**
- * Priority-ordered fallback chain (Thinking -> Balanced -> Fast) over
- * the small built-in list. The floor walked at resolve time when no
- * agent / plugin / env / request model is set *and* the live
- * catalogue yields nothing.
+ * Priority-ordered fallback chain (ChatThinking -> ChatBalanced ->
+ * ChatFast) over the small built-in list. The floor walked at resolve
+ * time when no agent / plugin / env / request model is set *and* the
+ * live catalogue yields nothing.
  */
 export declare const FALLBACK_MODEL_IDS: readonly string[];

package/dist/src/fallback.js

@@ -5,9 +5,9 @@
  * no user token, the service principal can't list, or the workspace is
  * unreachable - the resolver still has to name *some* endpoint. This
  * module holds that floor: a small, hard-coded set of well-known
- * Foundation Model API endpoint names, each bucketed into a
- * {@link ModelTier} by the shared {@link classifyByFamily} heuristic
- * (no tiers are hard-coded here) and ordered best-first.
+ * Foundation Model API endpoint names, each bucketed into a chat
+ * {@link ModelClass} by the shared {@link classifyByFamily} heuristic
+ * (no classes are hard-coded here) and ordered best-first.
  *
  * This is deliberately *server-only*. A browser client never talks to
  * Databricks directly - it always goes through this server - so it has
@@ -15,13 +15,13 @@
  * list; it consumes the live `/models` response instead. The pure
  * classifier ({@link classifyEndpoints}) is what the client shares.
  */
-import { classifyByFamily, ModelTier } from "@dbx-tools/model-shared";
+import { classifyByFamily, ModelClass, } from "@dbx-tools/model-shared";
 /**
  * Small, last-resort set of well-known Foundation Model API endpoint
- * names, ordered best-first within each tier by {@link classifyByFamily}.
+ * names, ordered best-first within each class by {@link classifyByFamily}.
  * Used only as the floor when the live `/serving-endpoints` catalogue
  * can't be read at resolve time; the live, score-driven classification
- * supersedes it whenever the workspace listing is available. Tiers are
+ * supersedes it whenever the workspace listing is available. Classes are
  * not hard-coded here - each name is classified by family heuristic.
  */
 const FALLBACK_MODEL_NAMES = [
@@ -36,30 +36,31 @@ const FALLBACK_MODEL_NAMES = [
     "databricks-meta-llama-3-1-8b-instruct",
 ];
 /**
- * Static fallback model ids for a tier, drawn from the small built-in
- * {@link FALLBACK_MODEL_NAMES} list and ordered best-first by family
- * rank. Sync and workspace-independent: this is the *fallback opinion*
- * used to seed default lists or when the live catalogue is unreachable
- * - live resolution prefers `classifyEndpoints`.
+ * Static fallback model ids for a chat class, drawn from the small
+ * built-in {@link FALLBACK_MODEL_NAMES} list and ordered best-first by
+ * family rank. Sync and workspace-independent: this is the *fallback
+ * opinion* used to seed default lists or when the live catalogue is
+ * unreachable - live resolution prefers `classifyEndpoints`. Returns
+ * `[]` for {@link ModelClass.Embedding} (the floor is chat-only).
  */
-export function modelsForTier(tier) {
+export function modelsForClass(cls) {
     return FALLBACK_MODEL_NAMES.map((name) => ({ name, c: classifyByFamily(name) }))
-        .filter((x) => x.c !== null && x.c.tier === tier)
+        .filter((x) => x.c !== null && x.c.class === cls)
         .sort((a, b) => b.c.rank - a.c.rank)
         .map((x) => x.name);
 }
-/** Top static fallback model id for a tier. */
-export function modelForTier(tier) {
-    return modelsForTier(tier)[0];
+/** Top static fallback model id for a chat class. */
+export function modelForClass(cls) {
+    return modelsForClass(cls)[0];
 }
 /**
- * Priority-ordered fallback chain (Thinking -> Balanced -> Fast) over
- * the small built-in list. The floor walked at resolve time when no
- * agent / plugin / env / request model is set *and* the live
- * catalogue yields nothing.
+ * Priority-ordered fallback chain (ChatThinking -> ChatBalanced ->
+ * ChatFast) over the small built-in list. The floor walked at resolve
+ * time when no agent / plugin / env / request model is set *and* the
+ * live catalogue yields nothing.
  */
 export const FALLBACK_MODEL_IDS = [
-    ...modelsForTier(ModelTier.Thinking),
-    ...modelsForTier(ModelTier.Balanced),
-    ...modelsForTier(ModelTier.Fast),
+    ...modelsForClass(ModelClass.ChatThinking),
+    ...modelsForClass(ModelClass.ChatBalanced),
+    ...modelsForClass(ModelClass.ChatFast),
 ];

package/dist/src/resolve.d.ts

@@ -1,26 +1,40 @@
 /**
  * Workspace-aware model selection.
  *
- * Given a caller's intent (an explicit name, a capability
- * {@link ModelTier}, or nothing), the resolver returns the endpoint id
- * to use - always one the workspace actually has, degrading from "best
- * in tier" down to the static fallback floor. Two entry points:
+ * Given a caller's intent - a search string, a capability
+ * {@link ModelClass} ceiling, both, or nothing - the toolkit returns
+ * matching endpoints ranked by match quality then class, or collapses
+ * to the single best id the workspace actually has, degrading from
+ * "best in range" down to the static fallback floor. Selection is
+ * chat-only: embedding endpoints surface only when `modelClass` is
+ * explicitly {@link ModelClass.Embedding}.
  *
- *   - {@link selectModel} is the high-level, I/O-doing call: hand it a
- *     `WorkspaceClient` and intent and it lists `/serving-endpoints`
- *     (cached) and resolves in one step. This is what a non-Mastra
- *     consumer (e.g. a job that just needs a model name) reaches for.
- *   - {@link resolveModel} is the pure form over an endpoint list you
- *     already hold; `selectModel` is a thin wrapper over it.
+ * Ranking entry points (return a ranked list):
+ *
+ *   - {@link rankModels} is the pure ranker over an endpoint list you
+ *     already hold. A chat `modelClass` acts as a ceiling: only that
+ *     band and the less-capable chat bands below it are eligible (see
+ *     {@link classesAtOrBelow}), so a `chat-balanced` ask can fall to
+ *     `chat-fast` but never escalate to `chat-thinking`.
+ *   - {@link searchModels} is the I/O wrapper: hand it a
+ *     `WorkspaceClient` and it lists `/serving-endpoints` (cached) then
+ *     ranks in one step.
+ *
+ * Single-selection entry points (return one id + how it was reached):
+ *
+ *   - {@link resolveModel} is the pure selector; it delegates to
+ *     {@link rankModels} with `limit: 1` and adds the operator-pinned
+ *     fallback / static-floor safety net.
+ *   - {@link selectModel} is the I/O wrapper over {@link resolveModel}.
  */
-import { ModelTier, type ServingEndpointSummary } from "@dbx-tools/model-shared";
+import { ModelClass, type ModelQuery, type RankedModel, type ServingEndpointSummary } from "@dbx-tools/model-shared";
 import { type WorkspaceClientLike } from "./serving.js";
 /** Caller intent passed to {@link resolveModel}. */
 export interface ResolveModelInput {
     /**
      * Explicit model id / loose name (per-request override, agent /
-     * plugin default, or env var). When set it wins over `tier` and
-     * `fallbacks`.
+     * plugin default, or env var). When set it wins over `modelClass`
+     * and `fallbacks`.
      */
     explicit?: string;
     /**
@@ -33,15 +47,15 @@ export interface ResolveModelInput {
     /** Fuse.js threshold forwarded to {@link resolveModelId}. */
     threshold?: number;
     /**
-     * Capability tier to resolve when no `explicit` id is given. The
-     * live catalogue is classified by its Foundation Model API scores
-     * and the top available model in the tier wins, falling back to the
-     * tier's small static list.
+     * Chat capability class to resolve when no `explicit` id is given.
+     * The live catalogue is classified by its Foundation Model API scores
+     * and the top available model in the class (and the chat bands below
+     * it) wins, falling back to the class's small static list.
      */
-    tier?: ModelTier;
+    modelClass?: ModelClass;
     /**
      * Operator-supplied fallback ids tried *first* in the no-explicit,
-     * no-tier path (e.g. a regulated workspace pinned to an approved
+     * no-class path (e.g. a regulated workspace pinned to an approved
      * subset), ahead of the auto-classified catalogue.
      */
     fallbacks?: readonly string[];
@@ -49,13 +63,50 @@ export interface ResolveModelInput {
 /** Outcome of {@link resolveModel}: the chosen id plus how it was reached. */
 export interface ResolvedModelSelection {
     modelId: string;
-    source: "explicit" | "fuzzy-match" | "tier" | "fallback";
+    source: "explicit" | "fuzzy-match" | "class" | "fallback";
 }
 /** Intent + catalogue knobs passed to {@link selectModel}. */
 export interface SelectModelInput extends ResolveModelInput {
     /** TTL override for the cached `/serving-endpoints` listing, in ms. */
     ttlMs?: number;
 }
+/** TTL override merged into a {@link ModelQuery} for {@link searchModels}. */
+export interface SearchModelsInput extends ModelQuery {
+    /** TTL override for the cached `/serving-endpoints` listing, in ms. */
+    ttlMs?: number;
+}
+/**
+ * Rank the live catalogue against a {@link ModelQuery}, best-first.
+ *
+ * Candidates are the classified endpoints in the eligible classes:
+ * {@link classesAtOrBelow} the requested `modelClass`, or - when none is
+ * given - the chat bands only ({@link CHAT_CLASS_ORDER}), so a general
+ * ask never surfaces an embedding endpoint. Each class bucket is
+ * already best-first from {@link classifyEndpoints}. Ranking is **match
+ * then class**:
+ *
+ * 1. With a `search`, only endpoints matching it survive, ordered by
+ *    match distance (bucketed via {@link matchBucket} so near-identical
+ *    scores tie), then by class (more capable first), then by the stable
+ *    within-class rank.
+ * 2. Without a `search`, the class-then-rank candidate order stands.
+ *
+ * A `limit` truncates the result. Returns `[]` when nothing is
+ * eligible or matches - callers layer their own fallback.
+ */
+export declare function rankModels(endpoints: readonly ServingEndpointSummary[], query?: ModelQuery): RankedModel[];
+/**
+ * Rank a workspace's catalogue in one call: list its
+ * `/serving-endpoints` (cached) and run {@link rankModels} over the
+ * result. The list counterpart to {@link selectModel}, for a consumer
+ * that wants the full ranked set (a model picker, a CLI) rather than a
+ * single id. Catalogue fetches fail loud: network / auth errors
+ * propagate so the caller sees the real SDK message.
+ *
+ * @param host - Workspace host used as the cache key. Pass the value
+ *   resolved from `client.config.getHost()`.
+ */
+export declare function searchModels(client: WorkspaceClientLike, host: string, input?: SearchModelsInput): Promise<RankedModel[]>;
 /**
  * Resolve a model id for a workspace in one call: list its
  * `/serving-endpoints` (cached) and run {@link resolveModel} over the
@@ -74,15 +125,15 @@ export interface SelectModelInput extends ResolveModelInput {
  */
 export declare function selectModel(client: WorkspaceClientLike, host: string, input?: SelectModelInput): Promise<ResolvedModelSelection>;
 /**
- * Resolve a model id from the live catalogue and caller intent.
+ * Resolve a single model id from the live catalogue and caller intent,
+ * delegating the live selection to {@link rankModels} with `limit: 1`.
  *
  * 1. **Explicit ask**: with `fuzzy` off, returned verbatim; otherwise
- *    snapped to the closest live endpoint via {@link resolveModelId}.
- * 2. **Tier intent**: classify the live catalogue and return the top
- *    available model in that tier, then the tier's static list, then
- *    the {@link FALLBACK_MODEL_IDS} floor.
- * 3. **Neither**: walk `fallbacks` first, then the live
- *    score-classified catalogue (Thinking -> Balanced -> Fast), then
- *    the static floor, and return the first id actually present.
+ *    fuzzy-ranked within the (optional) class ceiling and the best taken,
+ *    falling back to the input verbatim when nothing matches.
+ * 2. **No explicit ask**: an operator-pinned `fallback` that exists in
+ *    the live catalogue wins first; then the ranked live catalogue
+ *    (class ceiling applied); then the static {@link FALLBACK_MODEL_IDS}
+ *    floor when the catalogue yields nothing in range.
  */
 export declare function resolveModel(endpoints: readonly ServingEndpointSummary[], input?: ResolveModelInput): ResolvedModelSelection;