@dbx-tools/model 0.1.111 → 0.3.1

package/src/resolve.ts

@@ -0,0 +1,275 @@
+/**
+ * Workspace-aware model selection.
+ *
+ * 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}.
+ *
+ * Two shapes of selection, each in a pure form (over an endpoint list the
+ * caller already holds) and an I/O wrapper (that lists `/serving-endpoints`
+ * first): ranking, which returns a match- then class-ordered list, and
+ * single-selection, which collapses to one id plus how it was reached and
+ * layers the operator-pinned fallback / static-floor safety net on top. A chat
+ * `modelClass` acts as a ceiling: 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`.
+ */
+
+import {
+  classify,
+  model,
+  type ModelQuery,
+  type RankedModel,
+  type ServingEndpointSummary,
+} from "@dbx-tools/shared-model";
+import { object } from "@dbx-tools/shared-core";
+
+import { CHAT_CLASS_ORDER, classesAtOrBelow, MODEL_CLASS_ORDER } from "./classes";
+import { FALLBACK_MODEL_IDS, modelsForClass } from "./fallback";
+import { listServingEndpoints, searchServingEndpoints, type WorkspaceClientLike } from "./serving";
+
+type ModelClass = model.ModelClass;
+
+/** 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 `modelClass` and `fallbacks`.
+   */
+  explicit?: string;
+  /**
+   * Fuzzy-match an `explicit` name against the live catalogue so loose names
+   * like `"claude sonnet"` resolve. Default `true`. When `false` the explicit
+   * input is returned verbatim (Databricks surfaces the canonical 404 if it
+   * doesn't exist).
+   */
+  fuzzy?: boolean;
+  /** Fuse.js threshold forwarded to the fuzzy `search` match ({@link searchServingEndpoints}). */
+  threshold?: number;
+  /**
+   * 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.
+   */
+  modelClass?: ModelClass;
+  /**
+   * Operator-supplied fallback ids tried *first* in the no-explicit, no-class
+   * path (e.g. a regulated workspace pinned to an approved subset), ahead of
+   * the auto-classified catalogue.
+   */
+  fallbacks?: readonly string[];
+}
+
+/** Outcome of {@link resolveModel}: the chosen id plus how it was reached. */
+export interface ResolvedModelSelection {
+  modelId: string;
+  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;
+}
+
+/**
+ * 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: number | undefined): number {
+  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 classify.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: readonly ServingEndpointSummary[],
+  query: ModelQuery = {},
+): RankedModel[] {
+  const classified = classify.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: RankedModel[] = [];
+  for (const modelClass of eligible) {
+    for (const endpoint of classified[modelClass]) candidates.push({ endpoint, modelClass });
+  }
+
+  const search = query.search?.trim();
+  let ranked: RankedModel[];
+  if (search) {
+    const scores = new Map<string, number>();
+    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()`.
+ */
+export async function searchModels(
+  client: WorkspaceClientLike,
+  host: string,
+  input: SearchModelsInput = {},
+): Promise<RankedModel[]> {
+  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 result. This is the entry
+ * point for any consumer that holds a `WorkspaceClient` and just wants a usable
+ * model name - a Lakeflow job, a one-off script, or the Mastra plugin alike.
+ *
+ * Cheap exit: when an `explicit` name is given and `fuzzy` is off, the
+ * catalogue is never fetched - the name is returned verbatim and Databricks
+ * surfaces the canonical 404 if it doesn't exist. Catalogue fetches otherwise
+ * fail loud: network / auth errors propagate so the caller sees the real SDK
+ * message instead of a silent fallback.
+ *
+ * @param host - Workspace host used as the cache key. Pass the value resolved
+ *   from `client.config.getHost()`.
+ */
+export async function selectModel(
+  client: WorkspaceClientLike,
+  host: string,
+  input: SelectModelInput = {},
+): Promise<ResolvedModelSelection> {
+  if (input.explicit !== undefined && input.fuzzy === false) {
+    return { modelId: input.explicit, source: "explicit" };
+  }
+  const endpoints = await listServingEndpoints(client, host, {
+    ...(input.ttlMs !== undefined ? { ttlMs: input.ttlMs } : {}),
+  });
+  return resolveModel(endpoints, input);
+}
+
+/**
+ * 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
+ *    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: readonly ServingEndpointSummary[],
+  input: ResolveModelInput = {},
+): ResolvedModelSelection {
+  if (input.explicit !== undefined) {
+    if (input.fuzzy === false) {
+      return { modelId: input.explicit, source: "explicit" };
+    }
+    const [top] = rankModels(endpoints, buildQuery(input, input.explicit));
+    return { modelId: top?.endpoint.name ?? input.explicit, source: "fuzzy-match" };
+  }
+
+  // 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 floorSource =
+    input.modelClass !== undefined ? modelsForClass(input.modelClass) : (input.fallbacks ?? []);
+  const floor = object.sequence(floorSource).concat(FALLBACK_MODEL_IDS).distinct().toArray();
+  return { modelId: pickFirstAvailable(floor, endpoints), source };
+}
+
+/** Build a {@link ModelQuery} from {@link ResolveModelInput} for the `limit: 1` delegation. */
+function buildQuery(input: ResolveModelInput, search: string | undefined): ModelQuery {
+  return {
+    ...(search !== undefined ? { search } : {}),
+    ...(input.modelClass !== undefined ? { modelClass: input.modelClass } : {}),
+    ...(input.threshold !== undefined ? { threshold: input.threshold } : {}),
+    limit: 1,
+  };
+}
+
+/**
+ * Find the first id in `candidates` whose endpoint is present in `endpoints`.
+ * Returns the top candidate when the workspace has none of them so callers
+ * always get a string; an offline workspace then receives a clean 404 from
+ * Databricks instead of a malformed config.
+ */
+function pickFirstAvailable(
+  candidates: readonly string[],
+  endpoints: readonly ServingEndpointSummary[],
+): string {
+  const present = new Set(endpoints.map((e) => e.name));
+  for (const candidate of candidates) {
+    if (present.has(candidate)) return candidate;
+  }
+  return candidates[0] ?? FALLBACK_MODEL_IDS[0]!;
+}

package/src/serving.ts

@@ -0,0 +1,381 @@
+/**
+ * Live Databricks Model Serving catalogue access.
+ *
+ * Lists the workspace's `/serving-endpoints` once per host and caches the
+ * result with a TTL via AppKit's `CacheManager`, with concurrent 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, 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 { error, log, string } from "@dbx-tools/shared-core";
+import {
+  classify,
+  display,
+  model,
+  type ModelProfile,
+  type ServingEndpointSummary,
+} from "@dbx-tools/shared-model";
+import { appkit } from "@dbx-tools/appkit";
+import { CacheManager } from "@databricks/appkit";
+import Fuse from "fuse.js";
+
+import { MODEL_CLASS_ORDER } from "./classes";
+
+const { ModelClass } = model;
+
+const logger = log.logger("model/serving");
+
+/**
+ * Structural type for the Databricks workspace client, re-exported so the rest
+ * of this package can keep importing it from here. See
+ * `appkit.WorkspaceClientLike` (node-appkit) for the canonical definition.
+ */
+export type WorkspaceClientLike = appkit.WorkspaceClientLike;
+
+/** 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;
+
+/** Default Fuse.js score threshold below which a fuzzy match is accepted. */
+export const DEFAULT_FUZZY_THRESHOLD = 0.4;
+
+/** Cache key parts under which endpoint listings are stored. */
+const CACHE_KEY_NAMESPACE = "serving-endpoints";
+
+/**
+ * Stable `userKey` arg for AppKit's `CacheManager.getOrExecute`. Endpoint
+ * visibility is effectively workspace-scoped (we cache by host in the key
+ * parts), so a single shared key lets every user of the same workspace share
+ * one cached fetch and coalesce on the in-flight promise. Permissions can
+ * differ in theory, but the Foundation Model API catalogue is the same view for
+ * every caller.
+ */
+const SHARED_USER_KEY = "model-shared";
+
+/** 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 everything
+ * `cachetools.TTLCache` provides plus what `cachetools-async` adds on top:
+ * per-entry TTL, in-flight request coalescing (concurrent callers share one
+ * fetch via the manager's internal `inFlightRequests` map), bounded size,
+ * telemetry spans (`cache.getOrExecute`), and optional Lakebase persistence so
+ * the catalogue survives restarts when the lakebase plugin is wired up.
+ *
+ * Returns plain {@link ServingEndpointSummary} objects (a stable subset of the
+ * SDK type) so cache hits never expose stale SDK internals. Errors from
+ * `CacheManager` or the SDK fetch propagate to the caller - we don't swallow
+ * them so users see the real auth / network issue.
+ *
+ * @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 options.ttlMs - Override the default TTL just for this call. Forwarded
+ *   to `CacheManager` as seconds.
+ */
+export async function listServingEndpoints(
+  client: WorkspaceClientLike,
+  host: string,
+  options: ListServingEndpointsOptions = {},
+): Promise<ServingEndpointSummary[]> {
+  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 },
+  );
+}
+
+/**
+ * List the workspace's serving endpoints as minimal
+ * {@link ServingEndpointSummary} objects straight from the SDK: no caching, and
+ * none of the cache-load enrichment ({@link listServingEndpoints} adds the
+ * {@link ModelClass} stamp and the embedding-dimension probe). Use this for a
+ * one-shot, dependency-light listing - e.g. a CLI that only needs names/tasks
+ * for fuzzy resolution and doesn't want AppKit's `CacheManager` or the
+ * per-embedding ping cost. Prefer {@link listServingEndpoints} for the cached,
+ * enriched view.
+ */
+export async function listServingEndpointsUncached(
+  client: WorkspaceClientLike,
+): Promise<ServingEndpointSummary[]> {
+  const out: ServingEndpointSummary[] = [];
+  for await (const ep of client.servingEndpoints.list()) {
+    if (!ep.name) continue;
+    const profile = extractProfile(ep);
+    out.push({
+      name: ep.name,
+      // Prefer a Databricks-provided human name (a display-name tag or an
+      // external-model name); else derive a title-cased label from the id.
+      displayName: display.toModelDisplayName(ep.name, providedDisplayName(ep)),
+      ...(ep.task !== undefined ? { task: ep.task } : {}),
+      ...(ep.state?.ready !== undefined ? { state: String(ep.state.ready) } : {}),
+      ...(ep.description !== undefined ? { description: ep.description } : {}),
+      ...(profile ? { profile } : {}),
+    });
+  }
+  return out;
+}
+
+/**
+ * Pull a Databricks-provided human name off a serving endpoint, if any:
+ * a `display_name` / `displayName` / `name` tag first, then an
+ * external-model `name` from the served-entity config. Returns `null`
+ * when the endpoint carries no explicit name (the common case for
+ * Foundation Model API endpoints), so the caller falls back to deriving
+ * one from the id.
+ */
+function providedDisplayName(ep: {
+  tags?: Array<{ key: string; value?: string }>;
+  config?: { served_entities?: Array<{ external_model?: { name?: string } }> };
+}): string | null {
+  const tag = ep.tags?.find(
+    (t) => t.key === "display_name" || t.key === "displayName" || t.key === "name",
+  );
+  const fromTag = string.trimToNull(tag?.value);
+  if (fromTag) return fromTag;
+  for (const entity of ep.config?.served_entities ?? []) {
+    const external = string.trimToNull(entity.external_model?.name);
+    if (external) return external;
+  }
+  return null;
+}
+
+async function fetchEndpoints(client: WorkspaceClientLike): Promise<ServingEndpointSummary[]> {
+  const startedAt = Date.now();
+  const out = await listServingEndpointsUncached(client);
+  stampModelClasses(out);
+  await measureEmbeddingDimensions(client, out);
+  logger.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: ServingEndpointSummary[]): void {
+  const buckets = classify.classifyEndpoints(summaries);
+  const classOf = new Map<string, model.ModelClass>();
+  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: WorkspaceClientLike,
+  summaries: ServingEndpointSummary[],
+): Promise<void> {
+  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: WorkspaceClientLike,
+  name: string,
+): Promise<number | undefined> {
+  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;
+    logger.warn("embedding ping returned no vector", { name });
+    return undefined;
+  } catch (err) {
+    logger.warn("embedding ping failed", { name, error: error.errorMessage(err) });
+    return undefined;
+  }
+}
+
+/**
+ * Pull the Foundation Model API `quality` / `speed` / `cost` scores off a
+ * serving-endpoint listing entry. Databricks returns these under
+ * `config.served_entities[].foundation_model.ai_gateway_model_profile`
+ * (snake_case at the wire level, preserved verbatim by the SDK), but the field
+ * is newer than the typed `FoundationModel` interface, so we read it through a
+ * structural cast. Returns `undefined` when no served entity carries a profile
+ * (custom models, embeddings, and brand-new endpoints that Databricks has not
+ * scored yet).
+ */
+function extractProfile(ep: unknown): ModelProfile | undefined {
+  const entities = (
+    ep as {
+      config?: {
+        served_entities?: Array<{
+          foundation_model?: {
+            ai_gateway_model_profile?: {
+              quality?: number;
+              speed?: number;
+              cost?: number;
+            };
+          };
+        }>;
+      };
+    }
+  ).config?.served_entities;
+  if (!entities) return undefined;
+  for (const entity of entities) {
+    const raw = entity.foundation_model?.ai_gateway_model_profile;
+    if (!raw) continue;
+    const profile: ModelProfile = {};
+    if (Number.isFinite(raw.quality)) profile.quality = raw.quality;
+    if (Number.isFinite(raw.speed)) profile.speed = raw.speed;
+    if (Number.isFinite(raw.cost)) profile.cost = raw.cost;
+    if (Object.keys(profile).length > 0) return profile;
+  }
+  return undefined;
+}
+
+/**
+ * Force-evict cached endpoint listings via AppKit's `CacheManager`. With a
+ * `host` deletes that one workspace's entry; without one clears every cache
+ * entry on the manager (since `CacheManager` doesn't expose a namespace-scoped
+ * clear, this is the brute-force path - fine for tests, avoid in steady-state
+ * code).
+ */
+export async function clearServingEndpointsCache(host?: string): Promise<void> {
+  const cache = CacheManager.getInstanceSync();
+  if (host) {
+    const key = cache.generateKey([CACHE_KEY_NAMESPACE, host], SHARED_USER_KEY);
+    await cache.delete(key);
+  } else {
+    await cache.clear();
+  }
+}
+
+/**
+ * Result of fuzzy-resolving a user-supplied model name against the live
+ * endpoint list. `score` is Fuse.js's distance (`0` is exact, `1` is no match);
+ * `matched` is `false` when the score exceeds the configured threshold so
+ * callers can fall back to the original input (Databricks will then return a
+ * clean 404).
+ */
+export interface ResolvedModel {
+  modelId: string;
+  matched: boolean;
+  score?: number;
+}
+
+/** 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;
+}
+
+/**
+ * Fuzzy-rank endpoints by how closely their `name` matches `input`, best
+ * (lowest score) first, keeping only those within `threshold`:
+ *
+ * 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 - the "tokenized fuzzy match" a caller
+ *    reaches for when they type `"claude sonnet"` instead of the full endpoint
+ *    name.
+ *
+ * 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 searchServingEndpoints(
+  input: string,
+  endpoints: readonly ServingEndpointSummary[],
+  options: ResolveModelOptions = {},
+): ScoredEndpoint[] {
+  if (endpoints.length === 0) return [];
+  for (const ep of endpoints) {
+    if (ep.name === input) return [{ endpoint: ep, score: 0 }];
+  }
+  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(
+    string.tokenizeWithOptions({ lowerCase: true, camelCase: false }, input),
+  ).join(" ");
+  if (!query) return [];
+  const fuse = new Fuse(endpoints, {
+    keys: ["name"],
+    threshold,
+    ignoreLocation: true,
+    includeScore: true,
+    useExtendedSearch: true,
+    isCaseSensitive: false,
+  });
+  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: string,
+  endpoints: readonly ServingEndpointSummary[],
+  options: ResolveModelOptions = {},
+): ResolvedModel {
+  const [best] = searchServingEndpoints(input, endpoints, options);
+  if (best) {
+    return { modelId: best.endpoint.name, matched: true, score: best.score };
+  }
+  return { modelId: input, matched: false };
+}