@dbx-tools/model 0.1.42 → 0.1.56

package/dist/src/resolve.js

@@ -1,21 +1,116 @@
 /**
  * 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 { classifyEndpoints, ModelClass, } from "@dbx-tools/model-shared";
+import { CHAT_CLASS_ORDER, classesAtOrBelow, MODEL_CLASS_ORDER } from "./classes.js";
+import { FALLBACK_MODEL_IDS, modelsForClass } from "./fallback.js";
+import { listServingEndpoints, searchServingEndpoints, } from "./serving.js";
+/**
+ * Round a Fuse score to the display precision so version siblings that
+ * match a token identically (e.g. `opus-4-7` vs `opus-4-8` for the
+ * query `"opus"`) tie on match and let the class / within-class rank
+ * decide - which is what surfaces the newer, higher-quality sibling.
+ */
+function matchBucket(score) {
+    return Math.round((score ?? 0) * 1000);
+}
+/**
+ * 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 function rankModels(endpoints, query = {}) {
+    const classified = classifyEndpoints(endpoints);
+    const eligible = query.modelClass !== undefined
+        ? classesAtOrBelow(query.modelClass)
+        : CHAT_CLASS_ORDER;
+    // Flatten eligible classes in capability order, carrying each
+    // endpoint's class; bucket order is already best-first.
+    const candidates = [];
+    for (const modelClass of eligible) {
+        for (const endpoint of classified[modelClass])
+            candidates.push({ endpoint, modelClass });
+    }
+    const search = query.search?.trim();
+    let ranked;
+    if (search) {
+        const scores = new Map();
+        for (const match of searchServingEndpoints(search, candidates.map((c) => c.endpoint), query.threshold !== undefined ? { threshold: query.threshold } : {})) {
+            scores.set(match.endpoint.name, match.score);
+        }
+        // `Array.prototype.sort` is stable, so endpoints equal on match and
+        // class keep their best-first within-class order.
+        ranked = candidates
+            .filter((c) => scores.has(c.endpoint.name))
+            .map((c) => ({ ...c, score: scores.get(c.endpoint.name) }))
+            .sort((a, b) => {
+            const byMatch = matchBucket(a.score) - matchBucket(b.score);
+            if (byMatch !== 0)
+                return byMatch;
+            return (MODEL_CLASS_ORDER.indexOf(a.modelClass) -
+                MODEL_CLASS_ORDER.indexOf(b.modelClass));
+        });
+    }
+    else {
+        ranked = candidates;
+    }
+    return query.limit !== undefined ? ranked.slice(0, Math.max(0, query.limit)) : ranked;
+}
+/**
+ * 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()`.
  */
-import { classifyEndpoints, ModelTier, } from "@dbx-tools/model-shared";
-import { FALLBACK_MODEL_IDS, modelsForTier } from "./fallback.js";
-import { listServingEndpoints, resolveModelId, } from "./serving.js";
+export async function searchModels(client, host, input = {}) {
+    const endpoints = await listServingEndpoints(client, host, input.ttlMs !== undefined ? { ttlMs: input.ttlMs } : {});
+    return rankModels(endpoints, input);
+}
 /**
  * Resolve a model id for a workspace in one call: list its
  * `/serving-endpoints` (cached) and run {@link resolveModel} over the
@@ -42,61 +137,52 @@ export async function selectModel(client, host, input = {}) {
     return resolveModel(endpoints, input);
 }
 /**
- * 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 function resolveModel(endpoints, input = {}) {
     if (input.explicit !== undefined) {
         if (input.fuzzy === false) {
             return { modelId: input.explicit, source: "explicit" };
         }
-        const { modelId } = resolveModelId(input.explicit, endpoints, {
-            threshold: input.threshold,
-        });
-        return { modelId, source: "fuzzy-match" };
+        const [top] = rankModels(endpoints, buildQuery(input, input.explicit));
+        return { modelId: top?.endpoint.name ?? input.explicit, source: "fuzzy-match" };
     }
-    const classified = classifyEndpoints(endpoints);
-    const chain = input.tier !== undefined
-        ? tierChain(classified, input.tier)
-        : defaultChain(classified, input.fallbacks);
+    // Operator-pinned fallbacks win when present and live (e.g. a
+    // regulated workspace restricted to an approved subset).
+    if (input.modelClass === undefined && input.fallbacks && input.fallbacks.length > 0) {
+        const present = new Set(endpoints.map((e) => e.name));
+        const pinned = input.fallbacks.find((id) => present.has(id));
+        if (pinned)
+            return { modelId: pinned, source: "fallback" };
+    }
+    const source = input.modelClass !== undefined ? "class" : "fallback";
+    const [top] = rankModels(endpoints, buildQuery(input, undefined));
+    if (top)
+        return { modelId: top.endpoint.name, source };
+    // Live catalogue yielded nothing in range: walk the static floor.
+    const floor = input.modelClass !== undefined
+        ? dedupe([...modelsForClass(input.modelClass), ...FALLBACK_MODEL_IDS])
+        : dedupe([...(input.fallbacks ?? []), ...FALLBACK_MODEL_IDS]);
+    return { modelId: pickFirstAvailable(floor, endpoints), source };
+}
+/** Build a {@link ModelQuery} from {@link ResolveModelInput} for the `limit: 1` delegation. */
+function buildQuery(input, search) {
     return {
-        modelId: pickFirstAvailable(chain, endpoints),
-        source: input.tier !== undefined ? "tier" : "fallback",
+        ...(search !== undefined ? { search } : {}),
+        ...(input.modelClass !== undefined ? { modelClass: input.modelClass } : {}),
+        ...(input.threshold !== undefined ? { threshold: input.threshold } : {}),
+        limit: 1,
     };
 }
-/**
- * Candidate chain for an explicit {@link ModelTier} ask: live models
- * classified into that tier (best-first), then the tier's small static
- * list, then the full fallback floor as a last resort.
- */
-function tierChain(classified, tier) {
-    return dedupe([
-        ...classified[tier].map((e) => e.name),
-        ...modelsForTier(tier),
-        ...FALLBACK_MODEL_IDS,
-    ]);
-}
-/**
- * Candidate chain for the no-explicit default: any operator-supplied
- * `fallbacks` first, then the live score-classified catalogue in
- * descending tier order, then the static fallback floor.
- */
-function defaultChain(classified, fallbacks) {
-    const live = [
-        ...classified[ModelTier.Thinking],
-        ...classified[ModelTier.Balanced],
-        ...classified[ModelTier.Fast],
-    ].map((e) => e.name);
-    return dedupe([...(fallbacks ?? []), ...live, ...FALLBACK_MODEL_IDS]);
-}
 /** Drop duplicate ids while preserving first-seen order. */
 function dedupe(ids) {
     return [...new Set(ids)];

package/dist/src/serving.d.ts

@@ -6,24 +6,39 @@
  * callers sharing one in-flight promise (the coalescing pattern of
  * Python's `cachetools-async`). Surfaces each endpoint as a stable
  * {@link ServingEndpointSummary} - including the Foundation Model API
- * `quality` / `speed` / `cost` profile when present - and snaps loose,
- * human-typed names to real endpoint ids through `fuse.js` extended
- * search so tokens like `"claude sonnet"` resolve to
- * `databricks-claude-sonnet-4-6`.
+ * `quality` / `speed` / `cost` profile when present, the classified
+ * {@link ModelClass}, and (for embedding endpoints) the measured vector
+ * `dimension` - and snaps loose, human-typed names to real endpoint ids
+ * through `fuse.js` extended search so tokens like `"claude sonnet"`
+ * resolve to `databricks-claude-sonnet-4-6`.
+ *
+ * The class stamp and embedding dimension are computed once per cache
+ * load: every embedding endpoint is "pinged" in parallel and the
+ * resulting vector length recorded, so the cost is paid on a cache miss,
+ * not per read. The ping is best-effort - a failure logs at debug and
+ * leaves `dimension` unset rather than failing the whole listing.
  */
-import { type getExecutionContext } from "@databricks/appkit";
-import type { ServingEndpointSummary } from "@dbx-tools/model-shared";
+import { type ServingEndpointSummary } from "@dbx-tools/model-shared";
+import type { appkitUtils } from "@dbx-tools/shared";
 /**
- * Structural type for the Databricks workspace client. Derived from
- * AppKit's `ExecutionContext` so this module doesn't take a direct
- * dependency on `@databricks/sdk-experimental`; the dep flows in
- * transitively through `@databricks/appkit`.
+ * Structural type for the Databricks workspace client, re-exported from
+ * `@dbx-tools/shared` so the rest of this package can keep importing it
+ * from here. See `appkitUtils.WorkspaceClientLike` for the canonical
+ * definition.
  */
-export type WorkspaceClientLike = ReturnType<typeof getExecutionContext>["client"];
+export type WorkspaceClientLike = appkitUtils.WorkspaceClientLike;
 /** Default TTL for the in-memory endpoint cache. Matches the Databricks SDK's session lifetime budget. */
 export declare const DEFAULT_MODEL_CACHE_TTL_MS: number;
 /** Default Fuse.js score threshold below which a fuzzy match is accepted. */
 export declare const DEFAULT_FUZZY_THRESHOLD = 0.4;
+/** Options for {@link listServingEndpoints}. */
+export interface ListServingEndpointsOptions {
+    /**
+     * Override the default cache TTL for this call, in milliseconds.
+     * Forwarded to `CacheManager` as seconds.
+     */
+    ttlMs?: number;
+}
 /**
  * List Model Serving endpoints for the workspace owning `client`,
  * routed through AppKit's `CacheManager`. The manager gives us
@@ -43,12 +58,10 @@ export declare const DEFAULT_FUZZY_THRESHOLD = 0.4;
  * @param host - Workspace host used as the cache key. Pass the value
  *   resolved from `client.config.getHost()` so multi-host apps share
  *   one entry per workspace.
- * @param opts.ttlMs - Override the default TTL just for this call.
+ * @param options.ttlMs - Override the default TTL just for this call.
  *   Forwarded to `CacheManager` as seconds.
  */
-export declare function listServingEndpoints(client: WorkspaceClientLike, host: string, opts?: {
-    ttlMs?: number;
-}): Promise<ServingEndpointSummary[]>;
+export declare function listServingEndpoints(client: WorkspaceClientLike, host: string, options?: ListServingEndpointsOptions): Promise<ServingEndpointSummary[]>;
 /**
  * Force-evict cached endpoint listings via AppKit's `CacheManager`.
  * With a `host` deletes that one workspace's entry; without one
@@ -69,28 +82,41 @@ export interface ResolvedModel {
     matched: boolean;
     score?: number;
 }
-/** Options accepted by {@link resolveModelId}. */
+/** Options accepted by {@link resolveModelId} / {@link searchServingEndpoints}. */
 export interface ResolveModelOptions {
     /** Fuse.js threshold (0 = exact, 1 = anything). Default `0.4`. */
     threshold?: number;
 }
+/** A serving endpoint paired with its fuzzy-match distance for a query. */
+export interface ScoredEndpoint {
+    endpoint: ServingEndpointSummary;
+    /** Fuse.js distance: `0` is exact, `1` is no match. */
+    score: number;
+}
 /**
- * Snap a user-supplied model name to the closest configured serving
- * endpoint:
+ * Fuzzy-rank endpoints by how closely their `name` matches `input`,
+ * best (lowest score) first, keeping only those within `threshold`:
  *
- * 1. Exact name match wins immediately (no fuzzy needed).
+ * 1. An exact name match short-circuits to a single `score: 0` result.
  * 2. Otherwise the input is tokenized (dashes / underscores / spaces
- *    become separators) and fed through Fuse.js extended search,
- *    which AND-s each token with fuzzy matching enabled. This is the
- *    "tokenized fuzzy match" the user reaches for when they type
- *    `"claude sonnet"` instead of the full endpoint name.
- * 3. If the best Fuse score is above `threshold`, return the input
- *    unchanged and let the upstream call surface the 404. This keeps
- *    deliberate model ids (e.g. brand new endpoints) from being
- *    silently rewritten to a similar-looking neighbour.
+ *    become separators) and fed through Fuse.js extended search, which
+ *    AND-s each token with fuzzy matching enabled - the "tokenized
+ *    fuzzy match" a caller reaches for when they type `"claude sonnet"`
+ *    instead of the full endpoint name.
  *
- * Pass an empty endpoint list to short-circuit fuzzy matching - the
- * input is returned verbatim. This is what callers do when the
- * workspace client can't be reached at resolve time.
+ * Returns `[]` for an empty endpoint list or when `input` tokenizes to
+ * nothing, so callers fall back to the raw input and let Databricks
+ * surface a clean 404. This multi-result core is shared by
+ * {@link resolveModelId} (single best) and the ranked `rankModels`
+ * selector.
+ */
+export declare function searchServingEndpoints(input: string, endpoints: readonly ServingEndpointSummary[], options?: ResolveModelOptions): ScoredEndpoint[];
+/**
+ * Snap a user-supplied model name to the single closest configured
+ * serving endpoint via {@link searchServingEndpoints}. Returns the
+ * input unchanged with `matched: false` when nothing scores within the
+ * threshold (or the catalogue is empty), so a deliberate model id is
+ * never silently rewritten to a similar-looking neighbour and the
+ * upstream call surfaces the canonical 404.
  */
-export declare function resolveModelId(input: string, endpoints: readonly ServingEndpointSummary[], opts?: ResolveModelOptions): ResolvedModel;
+export declare function resolveModelId(input: string, endpoints: readonly ServingEndpointSummary[], options?: ResolveModelOptions): ResolvedModel;

package/dist/src/serving.js

@@ -6,14 +6,23 @@
  * callers sharing one in-flight promise (the coalescing pattern of
  * Python's `cachetools-async`). Surfaces each endpoint as a stable
  * {@link ServingEndpointSummary} - including the Foundation Model API
- * `quality` / `speed` / `cost` profile when present - and snaps loose,
- * human-typed names to real endpoint ids through `fuse.js` extended
- * search so tokens like `"claude sonnet"` resolve to
- * `databricks-claude-sonnet-4-6`.
+ * `quality` / `speed` / `cost` profile when present, the classified
+ * {@link ModelClass}, and (for embedding endpoints) the measured vector
+ * `dimension` - and snaps loose, human-typed names to real endpoint ids
+ * through `fuse.js` extended search so tokens like `"claude sonnet"`
+ * resolve to `databricks-claude-sonnet-4-6`.
+ *
+ * The class stamp and embedding dimension are computed once per cache
+ * load: every embedding endpoint is "pinged" in parallel and the
+ * resulting vector length recorded, so the cost is paid on a cache miss,
+ * not per read. The ping is best-effort - a failure logs at debug and
+ * leaves `dimension` unset rather than failing the whole listing.
  */
 import { CacheManager } from "@databricks/appkit";
-import { logUtils, stringUtils } from "@dbx-tools/shared";
+import { classifyEndpoints, ModelClass, } from "@dbx-tools/model-shared";
+import { commonUtils, logUtils, stringUtils } from "@dbx-tools/shared";
 import Fuse from "fuse.js";
+import { MODEL_CLASS_ORDER } from "./classes.js";
 const log = logUtils.logger("model/serving");
 /** Default TTL for the in-memory endpoint cache. Matches the Databricks SDK's session lifetime budget. */
 export const DEFAULT_MODEL_CACHE_TTL_MS = 5 * 60 * 1000;
@@ -49,11 +58,11 @@ const SHARED_USER_KEY = "model-shared";
  * @param host - Workspace host used as the cache key. Pass the value
  *   resolved from `client.config.getHost()` so multi-host apps share
  *   one entry per workspace.
- * @param opts.ttlMs - Override the default TTL just for this call.
+ * @param options.ttlMs - Override the default TTL just for this call.
  *   Forwarded to `CacheManager` as seconds.
  */
-export async function listServingEndpoints(client, host, opts = {}) {
-    const ttlSec = Math.max(1, Math.round((opts.ttlMs ?? DEFAULT_MODEL_CACHE_TTL_MS) / 1000));
+export async function listServingEndpoints(client, host, options = {}) {
+    const ttlSec = Math.max(1, Math.round((options.ttlMs ?? DEFAULT_MODEL_CACHE_TTL_MS) / 1000));
     return CacheManager.getInstanceSync().getOrExecute([CACHE_KEY_NAMESPACE, host], () => fetchEndpoints(client), SHARED_USER_KEY, { ttl: ttlSec });
 }
 async function fetchEndpoints(client) {
@@ -71,9 +80,68 @@ async function fetchEndpoints(client) {
             ...(profile ? { profile } : {}),
         });
     }
+    stampModelClasses(out);
+    await measureEmbeddingDimensions(client, out);
     log.debug("listed", { count: out.length, elapsedMs: Date.now() - startedAt });
     return out;
 }
+/**
+ * Stamp each summary's {@link ServingEndpointSummary.class} from the
+ * relative classification of the whole set. Mutates `summaries` in
+ * place. Endpoints the classifier doesn't recognize (custom, unscored,
+ * non-LLM) are left without a class.
+ */
+function stampModelClasses(summaries) {
+    const buckets = classifyEndpoints(summaries);
+    const classOf = new Map();
+    for (const cls of MODEL_CLASS_ORDER) {
+        for (const ep of buckets[cls])
+            classOf.set(ep.name, cls);
+    }
+    for (const summary of summaries) {
+        const cls = classOf.get(summary.name);
+        if (cls !== undefined)
+            summary.class = cls;
+    }
+}
+/**
+ * Measure the embedding vector dimension of every
+ * {@link ModelClass.Embedding} endpoint by pinging it once, all in
+ * parallel. Mutates the matching summaries in place with the resulting
+ * `dimension`. Runs only on a cache miss (it's called from
+ * {@link fetchEndpoints}), so the probe cost is amortized across the
+ * cached TTL window. Per-endpoint failures are swallowed (logged at
+ * warn) so one unreachable embedding model never fails the listing.
+ */
+async function measureEmbeddingDimensions(client, summaries) {
+    await Promise.all(summaries
+        .filter((s) => s.class === ModelClass.Embedding)
+        .map(async (summary) => {
+        const dimension = await pingEmbeddingDimension(client, summary.name);
+        if (dimension !== undefined)
+            summary.dimension = dimension;
+    }));
+}
+/**
+ * Best-effort embedding dimension probe: query `name` with a tiny
+ * `"ping"` input and return the length of the returned vector. Returns
+ * `undefined` (and logs at warn) when the endpoint can't be queried or
+ * returns no vector - the dimension is informational, never required.
+ */
+async function pingEmbeddingDimension(client, name) {
+    try {
+        const response = await client.servingEndpoints.query({ name, input: "ping" });
+        const dimension = response.data?.[0]?.embedding?.length;
+        if (typeof dimension === "number" && dimension > 0)
+            return dimension;
+        log.warn("embedding ping returned no vector", { name });
+        return undefined;
+    }
+    catch (err) {
+        log.warn("embedding ping failed", { name, error: commonUtils.errorMessage(err) });
+        return undefined;
+    }
+}
 /**
  * Pull the Foundation Model API `quality` / `speed` / `cost` scores
  * off a serving-endpoint listing entry. Databricks returns these
@@ -122,36 +190,37 @@ export async function clearServingEndpointsCache(host) {
     }
 }
 /**
- * Snap a user-supplied model name to the closest configured serving
- * endpoint:
+ * Fuzzy-rank endpoints by how closely their `name` matches `input`,
+ * best (lowest score) first, keeping only those within `threshold`:
  *
- * 1. Exact name match wins immediately (no fuzzy needed).
+ * 1. An exact name match short-circuits to a single `score: 0` result.
  * 2. Otherwise the input is tokenized (dashes / underscores / spaces
- *    become separators) and fed through Fuse.js extended search,
- *    which AND-s each token with fuzzy matching enabled. This is the
- *    "tokenized fuzzy match" the user reaches for when they type
- *    `"claude sonnet"` instead of the full endpoint name.
- * 3. If the best Fuse score is above `threshold`, return the input
- *    unchanged and let the upstream call surface the 404. This keeps
- *    deliberate model ids (e.g. brand new endpoints) from being
- *    silently rewritten to a similar-looking neighbour.
+ *    become separators) and fed through Fuse.js extended search, which
+ *    AND-s each token with fuzzy matching enabled - the "tokenized
+ *    fuzzy match" a caller reaches for when they type `"claude sonnet"`
+ *    instead of the full endpoint name.
  *
- * Pass an empty endpoint list to short-circuit fuzzy matching - the
- * input is returned verbatim. This is what callers do when the
- * workspace client can't be reached at resolve time.
+ * Returns `[]` for an empty endpoint list or when `input` tokenizes to
+ * nothing, so callers fall back to the raw input and let Databricks
+ * surface a clean 404. This multi-result core is shared by
+ * {@link resolveModelId} (single best) and the ranked `rankModels`
+ * selector.
  */
-export function resolveModelId(input, endpoints, opts = {}) {
-    if (endpoints.length === 0) {
-        log.debug("resolve:no-endpoints", { input });
-        return { modelId: input, matched: false };
-    }
+export function searchServingEndpoints(input, endpoints, options = {}) {
+    if (endpoints.length === 0)
+        return [];
     for (const ep of endpoints) {
-        if (ep.name === input) {
-            log.debug("resolve:exact", { input });
-            return { modelId: ep.name, matched: true, score: 0 };
-        }
+        if (ep.name === input)
+            return [{ endpoint: ep, score: 0 }];
     }
-    const threshold = opts.threshold ?? DEFAULT_FUZZY_THRESHOLD;
+    const threshold = options.threshold ?? DEFAULT_FUZZY_THRESHOLD;
+    // Fuse 7.3 has no built-in tokenize hook; in extended search,
+    // space-separated tokens are AND-ed with fuzzy matching enabled. We
+    // lean on the shared tokenizer so the splitting rules stay
+    // consistent with the rest of the toolkit.
+    const query = Array.from(stringUtils.tokenizeWithOptions({ lowerCase: true, camelCase: false }, input)).join(" ");
+    if (!query)
+        return [];
     const fuse = new Fuse(endpoints, {
         keys: ["name"],
         threshold,
@@ -160,29 +229,23 @@ export function resolveModelId(input, endpoints, opts = {}) {
         useExtendedSearch: true,
         isCaseSensitive: false,
     });
-    // Fuse 7.3 has no built-in tokenize hook; in extended search,
-    // space-separated tokens are AND-ed with fuzzy matching enabled. We
-    // lean on the shared tokenizer so the splitting rules stay
-    // consistent with the rest of the toolkit.
-    const query = Array.from(stringUtils.tokenizeWithOptions({ lowerCase: true, camelCase: false }, input)).join(" ");
-    if (!query) {
-        log.debug("resolve:empty-tokens", { input });
-        return { modelId: input, matched: false };
-    }
-    const results = fuse.search(query);
-    const best = results[0];
-    if (best?.item.name && (best.score ?? 0) <= threshold) {
-        log.debug("resolve:fuzzy-match", {
-            input,
-            modelId: best.item.name,
-            score: best.score,
-        });
-        return { modelId: best.item.name, matched: true, score: best.score };
+    return fuse
+        .search(query)
+        .filter((r) => (r.score ?? 0) <= threshold)
+        .map((r) => ({ endpoint: r.item, score: r.score ?? 0 }));
+}
+/**
+ * Snap a user-supplied model name to the single closest configured
+ * serving endpoint via {@link searchServingEndpoints}. Returns the
+ * input unchanged with `matched: false` when nothing scores within the
+ * threshold (or the catalogue is empty), so a deliberate model id is
+ * never silently rewritten to a similar-looking neighbour and the
+ * upstream call surfaces the canonical 404.
+ */
+export function resolveModelId(input, endpoints, options = {}) {
+    const [best] = searchServingEndpoints(input, endpoints, options);
+    if (best) {
+        return { modelId: best.endpoint.name, matched: true, score: best.score };
     }
-    log.debug("resolve:no-match", {
-        input,
-        bestScore: best?.score,
-        threshold,
-    });
     return { modelId: input, matched: false };
 }