@dbx-tools/model 0.1.67 → 0.1.68

package/package.json

@@ -1,14 +1,13 @@
 {
   "name": "@dbx-tools/model",
-  "version": "0.1.67",
+  "version": "0.1.68",
   "dependencies": {
-    "@dbx-tools/model-shared": "0.1.67",
-    "@dbx-tools/shared": "0.1.67",
+    "@dbx-tools/model-shared": "0.1.68",
+    "@dbx-tools/shared": "0.1.68",
     "fuse.js": "^7.0.0"
   },
   "exports": {
     ".": {
-      "source": "./src/index.ts",
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     }
@@ -20,8 +19,7 @@
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
-    "dist",
-    "src"
+    "dist"
   ],
   "license": "Apache-2.0"
 }

package/src/classes.ts

@@ -1,75 +0,0 @@
-/**
- * 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: readonly ModelClass[] = [
-  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: readonly ModelClass[] = [
-  ...CHAT_CLASS_ORDER,
-  ModelClass.Embedding,
-];
-
-/** Whether `cls` is one of the chat capability bands (vs. embedding). */
-export function isChatClass(cls: ModelClass): boolean {
-  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: unknown): ModelClass | null {
-  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: ModelClass): ModelClass[] {
-  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/src/fallback.ts

@@ -1,77 +0,0 @@
-/**
- * Server-side offline fallback opinion for model selection.
- *
- * When the live `/serving-endpoints` catalogue can't be read at all -
- * 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 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
- * nothing to fall back to and must not assume a stale, baked-in model
- * list; it consumes the live `/models` response instead. The pure
- * classifier ({@link classifyEndpoints}) is what the client shares.
- */
-
-import {
-  classifyByFamily,
-  type FamilyClass,
-  ModelClass,
-} from "@dbx-tools/model-shared";
-
-/**
- * Small, last-resort set of well-known Foundation Model API endpoint
- * 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. Classes are
- * not hard-coded here - each name is classified by family heuristic.
- */
-const FALLBACK_MODEL_NAMES: readonly string[] = [
-  "databricks-claude-opus-4-8",
-  "databricks-gpt-5-5-pro",
-  "databricks-gemini-3-1-pro",
-  "databricks-claude-sonnet-4-6",
-  "databricks-gpt-5-5",
-  "databricks-meta-llama-3-3-70b-instruct",
-  "databricks-claude-haiku-4-5",
-  "databricks-gpt-5-nano",
-  "databricks-meta-llama-3-1-8b-instruct",
-];
-
-/**
- * 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 modelsForClass(cls: ModelClass): readonly string[] {
-  return FALLBACK_MODEL_NAMES.map((name) => ({ name, c: classifyByFamily(name) }))
-    .filter(
-      (x): x is { name: string; c: FamilyClass } => 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 chat class. */
-export function modelForClass(cls: ModelClass): string {
-  return modelsForClass(cls)[0]!;
-}
-
-/**
- * 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: readonly string[] = [
-  ...modelsForClass(ModelClass.ChatThinking),
-  ...modelsForClass(ModelClass.ChatBalanced),
-  ...modelsForClass(ModelClass.ChatFast),
-];

package/src/index.ts

@@ -1,23 +0,0 @@
-/**
- * `@dbx-tools/model` public surface.
- *
- * 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` / `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
- * serves server-side consumers.
- *
- * Browser-side consumers should import `@dbx-tools/model-shared`
- * directly: the serving driver pulls in `WorkspaceClient` and AppKit's
- * `CacheManager` and is Node-only, whereas the re-exported surface is
- * pure (types + sync functions) and safe for any runtime.
- */
-
-export * from "@dbx-tools/model-shared";
-export * from "./classes.js";
-export * from "./fallback.js";
-export * from "./resolve.js";
-export * from "./serving.js";

package/src/resolve.ts

@@ -1,303 +0,0 @@
-/**
- * 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}.
- *
- * 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,
-  type ModelQuery,
-  type RankedModel,
-  type ServingEndpointSummary,
-} 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,
-  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 `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 {@link resolveModelId}. */
-  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 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 = 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 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: ResolveModelInput, search: string | undefined): ModelQuery {
-  return {
-    ...(search !== undefined ? { search } : {}),
-    ...(input.modelClass !== undefined ? { modelClass: input.modelClass } : {}),
-    ...(input.threshold !== undefined ? { threshold: input.threshold } : {}),
-    limit: 1,
-  };
-}
-
-/** Drop duplicate ids while preserving first-seen order. */
-function dedupe(ids: readonly string[]): string[] {
-  return [...new Set(ids)];
-}
-
-/**
- * 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

@@ -1,363 +0,0 @@
-/**
- * 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 { CacheManager } from "@databricks/appkit";
-import {
-  classifyEndpoints,
-  ModelClass,
-  type ModelProfile,
-  type ServingEndpointSummary,
-} from "@dbx-tools/model-shared";
-import type { appkitUtils } from "@dbx-tools/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");
-
-/**
- * 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 = appkitUtils.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,
-      ...(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;
-}
-
-async function fetchEndpoints(
-  client: WorkspaceClientLike,
-): Promise<ServingEndpointSummary[]> {
-  const startedAt = Date.now();
-  const out = await listServingEndpointsUncached(client);
-  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: ServingEndpointSummary[]): void {
-  const buckets = classifyEndpoints(summaries);
-  const classOf = new Map<string, 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;
-    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
- * 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(
-    stringUtils.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 };
-}