@dbx-tools/model 0.1.9

package/README.md

@@ -0,0 +1,165 @@
+# @dbx-tools/node-model
+
+Workspace-aware Databricks Model Serving selection.
+
+Import this package when server-side code needs to turn a loose model request
+like `"claude sonnet"` or `"chat-fast"` into a concrete serving endpoint in the
+current workspace. It lists `/serving-endpoints`, caches and enriches the
+catalogue, classifies endpoints by capability, fuzzy-matches names, and falls
+back to a small static floor when the live catalogue is unavailable.
+
+Browser-safe request/result schemas and endpoint classification types live in
+[`@dbx-tools/shared-model`](../../shared/model).
+
+Key features:
+
+- Lists Databricks Model Serving endpoints through the SDK and normalizes them
+  into a stable summary shape.
+- Classifies endpoints into chat-thinking, chat-balanced, chat-fast, and
+  embedding classes using Foundation Model API scores and family heuristics.
+- Resolves loose user input such as `"sonnet"` or `"chat fast"` to a concrete
+  endpoint id.
+- Supports class ceilings so callers can ask for a capability band without
+  accidentally escalating to a larger model.
+- Caches enriched catalogues per workspace host through AppKit cache utilities.
+- Provides a small static fallback floor for local tools and degraded workspace
+  access.
+
+## Why Not Just AppKit Serving?
+
+Native AppKit's Model Serving plugin is the right choice when you already know
+the endpoint alias you want. It gives you authenticated invoke/stream routes,
+OBO execution, generated endpoint types, request-body filtering, and frontend
+hooks.
+
+Use this package before or beside that layer when the hard part is choosing the
+endpoint:
+
+- resolve loose human input such as `"sonnet"` or `"fast"` against the live
+  workspace catalogue;
+- group endpoints into capability classes like `chat-thinking`, `chat-balanced`,
+  `chat-fast`, and `embedding`;
+- enforce class ceilings so a caller can degrade to smaller models without
+  escalating to a larger one;
+- build model pickers and debug routes from a cached, enriched endpoint list;
+- keep local agents and CLIs working with a static fallback when catalogue
+  access is unavailable.
+
+## Select One Model
+
+```ts
+import { WorkspaceClient } from "@databricks/sdk-experimental";
+import { resolve } from "@dbx-tools/node-model";
+
+const client = new WorkspaceClient({});
+const host = String(await client.config.getHost());
+
+const selected = await resolve.selectModel(client, host, {
+  explicit: "claude sonnet",
+});
+
+console.log(selected.modelId, selected.source);
+```
+
+`selectModel()` is the high-level helper for agents and CLIs. It reads the live
+catalogue, applies fuzzy matching when an explicit string is present, then
+returns a single `modelId` plus a source label explaining why that endpoint won.
+
+The `source` label is useful for logs and debug UIs. It distinguishes explicit
+matches from class-based selection, environment defaults, and fallback results,
+so operators can tell whether a request used the intended model policy.
+
+## Build A Model Picker
+
+```ts
+import { resolve } from "@dbx-tools/node-model";
+
+const ranked = await resolve.searchModels(client, host, {
+  search: "opus",
+  modelClass: "chat-thinking",
+  limit: 5,
+});
+```
+
+Use `searchModels()` for UI pickers and debug routes. It returns ranked models
+with match scores and endpoint summaries, using the same fuzzy threshold and
+class ceiling logic as `selectModel()`.
+
+## Work With A Held Catalogue
+
+When you already have endpoint summaries, use the pure resolver functions from
+`resolve` and `serving` without another workspace call:
+
+```ts
+import { resolve, serving } from "@dbx-tools/node-model";
+
+const endpoints = await serving.listServingEndpoints(client, host);
+const ranked = resolve.rankModels(endpoints, { search: "sonnet", limit: 3 });
+const picked = resolve.resolveModel(endpoints, {
+  explicit: "claude sonnet",
+  modelClass: "chat-balanced",
+});
+```
+
+The class acts as a ceiling. `chat-balanced` may fall back to `chat-fast`, but
+will not escalate to `chat-thinking`. Embedding endpoints are considered only
+when the requested class is `embedding`.
+
+## List And Cache Serving Endpoints
+
+```ts
+import { serving } from "@dbx-tools/node-model";
+
+const endpoints = await serving.listServingEndpoints(client, host, {
+  ttlMs: 5 * 60_000,
+});
+
+const raw = await serving.listServingEndpointsUncached(client);
+await serving.clearServingEndpointsCache(host);
+```
+
+`listServingEndpoints()` uses AppKit's `CacheManager`, enriches endpoints with
+classification and embedding dimensions, and keys the cache by workspace host.
+`listServingEndpointsUncached()` is useful for simple scripts that only need the
+SDK response and do not want a cache dependency.
+
+## Fuzzy Resolve Endpoint Names
+
+```ts
+const matches = serving.searchServingEndpoints("claude sonnet", endpoints, {
+  threshold: 0.35,
+});
+
+const endpointName = serving.resolveModelId("sonnet", endpoints);
+```
+
+Fuzzy matching is intentionally a server concern because it depends on the live
+workspace catalogue and may re-list on misses. Disable it in callers that require
+exact endpoint ids.
+
+## Use Static Fallbacks
+
+```ts
+import { classes, fallback } from "@dbx-tools/node-model";
+import { model } from "@dbx-tools/shared-model";
+
+const cls = classes.parseModelClass("chat-fast") ?? model.ModelClass.ChatFast;
+const modelId = fallback.modelForClass(cls);
+```
+
+The fallback floor gives agents and local scripts a stable answer when a
+workspace cannot list endpoints. Prefer live catalogue resolution for production
+policy decisions; fallbacks are a last resort.
+
+## Modules
+
+- `resolve` - high-level `selectModel`, ranked search, and catalogue-held
+  resolver functions.
+- `serving` - Databricks serving-endpoint listing, cache management, fuzzy
+  search, and endpoint-id resolution.
+- `classes` - model-class parsing, ordering, and class-ceiling helpers.
+- `fallback` - static fallback model ids per class.
+
+The AppKit-Mastra integration uses this package through
+[`@dbx-tools/node-appkit-mastra`](../appkit-mastra); the local OpenAI-compatible
+gateway uses it through [`@dbx-tools/model-proxy`](../../cli/model-proxy).

package/index.ts

@@ -0,0 +1,10 @@
+// GENERATED by projen watch - DO NOT EDIT.
+// Regenerated from the exporting modules in ./src.
+// Hand edits are overwritten on the next watch; this file is read-only.
+
+export * as classes from "./src/classes";
+export * as fallback from "./src/fallback";
+export * as resolve from "./src/resolve";
+export * as serving from "./src/serving";
+export type { ResolveModelInput, ResolvedModelSelection, SelectModelInput, SearchModelsInput } from "./src/resolve";
+export type { WorkspaceClientLike, ListServingEndpointsOptions, ResolvedModel, ResolveModelOptions, ScoredEndpoint } from "./src/serving";

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@dbx-tools/model",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/reggie-db/dbx-tools.git",
+    "directory": "workspaces/node/model"
+  },
+  "devDependencies": {
+    "@types/node": "^24.6.0",
+    "tsx": "^4.23.0",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@databricks/appkit": "^0.43.0",
+    "fuse.js": "^7.4.2",
+    "@dbx-tools/shared-core": "0.1.9",
+    "@dbx-tools/appkit": "0.1.9",
+    "@dbx-tools/shared-model": "0.1.9"
+  },
+  "main": "index.ts",
+  "license": "UNLICENSED",
+  "version": "0.1.9",
+  "types": "index.ts",
+  "type": "module",
+  "exports": {
+    ".": "./index.ts",
+    "./package.json": "./package.json"
+  },
+  "dbxToolsConfig": {
+    "tags": [
+      "node"
+    ]
+  },
+  "//": "~~ Generated by projen. To modify, edit .projenrc.js and run \"pnpm exec projen\".",
+  "scripts": {
+    "build": "projen build",
+    "compile": "projen compile",
+    "default": "projen default",
+    "package": "projen package",
+    "post-compile": "projen post-compile",
+    "pre-compile": "projen pre-compile",
+    "test": "projen test",
+    "watch": "projen watch",
+    "projen": "projen"
+  }
+}

package/src/classes.ts

@@ -0,0 +1,73 @@
+/**
+ * Model-class ordering for the model service.
+ *
+ * `@dbx-tools/shared-model` 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 { model } from "@dbx-tools/shared-model";
+
+type ModelClass = model.ModelClass;
+const { ModelClass, ModelClassSchema } = model;
+
+/**
+ * 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

@@ -0,0 +1,73 @@
+/**
+ * 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 classify.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 classify.classifyEndpoints}) is what the client shares.
+ */
+
+import { classify, model, type FamilyClass } from "@dbx-tools/shared-model";
+
+type ModelClass = model.ModelClass;
+const { ModelClass } = model;
+
+/**
+ * Small, last-resort set of well-known Foundation Model API endpoint names,
+ * ordered best-first within each class by {@link classify.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
+ * {@link classify.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: classify.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/resolve.ts

@@ -0,0 +1,280 @@
+/**
+ * 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 { 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 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

@@ -0,0 +1,353 @@
+/**
+ * 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,
+  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,
+      ...(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);
+  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 };
+}

package/test/classes.test.ts

@@ -0,0 +1,74 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+
+import { model } from "@dbx-tools/shared-model";
+
+import {
+  CHAT_CLASS_ORDER,
+  classesAtOrBelow,
+  isChatClass,
+  MODEL_CLASS_ORDER,
+  parseModelClass,
+} from "../src/classes";
+
+const { ModelClass } = model;
+
+describe("CHAT_CLASS_ORDER / MODEL_CLASS_ORDER", () => {
+  it("orders chat bands most-capable first, embedding excluded from the ladder", () => {
+    assert.deepEqual(CHAT_CLASS_ORDER, [
+      ModelClass.ChatThinking,
+      ModelClass.ChatBalanced,
+      ModelClass.ChatFast,
+    ]);
+    assert.deepEqual(MODEL_CLASS_ORDER, [
+      ModelClass.ChatThinking,
+      ModelClass.ChatBalanced,
+      ModelClass.ChatFast,
+      ModelClass.Embedding,
+    ]);
+  });
+});
+
+describe("isChatClass", () => {
+  it("is true for chat bands and false for embedding", () => {
+    assert.equal(isChatClass(ModelClass.ChatThinking), true);
+    assert.equal(isChatClass(ModelClass.ChatFast), true);
+    assert.equal(isChatClass(ModelClass.Embedding), false);
+  });
+});
+
+describe("classesAtOrBelow", () => {
+  it("treats a chat band as a ceiling - the band and everything below it", () => {
+    assert.deepEqual(classesAtOrBelow(ModelClass.ChatThinking), [
+      ModelClass.ChatThinking,
+      ModelClass.ChatBalanced,
+      ModelClass.ChatFast,
+    ]);
+    assert.deepEqual(classesAtOrBelow(ModelClass.ChatBalanced), [
+      ModelClass.ChatBalanced,
+      ModelClass.ChatFast,
+    ]);
+    assert.deepEqual(classesAtOrBelow(ModelClass.ChatFast), [ModelClass.ChatFast]);
+  });
+
+  it("keeps embedding to itself - it is not a rung on the chat ladder", () => {
+    assert.deepEqual(classesAtOrBelow(ModelClass.Embedding), [ModelClass.Embedding]);
+  });
+});
+
+describe("parseModelClass", () => {
+  it("accepts full slugs and rejects junk", () => {
+    assert.equal(parseModelClass("chat-thinking"), ModelClass.ChatThinking);
+    assert.equal(parseModelClass("chat-balanced"), ModelClass.ChatBalanced);
+    assert.equal(parseModelClass("chat-fast"), ModelClass.ChatFast);
+    assert.equal(parseModelClass("embedding"), ModelClass.Embedding);
+    assert.equal(parseModelClass("medium"), null);
+    assert.equal(parseModelClass(undefined), null);
+  });
+
+  it("resolves a bare chat band via the chat- prefix shorthand", () => {
+    assert.equal(parseModelClass("thinking"), ModelClass.ChatThinking);
+    assert.equal(parseModelClass("balanced"), ModelClass.ChatBalanced);
+    assert.equal(parseModelClass("fast"), ModelClass.ChatFast);
+  });
+});

package/test/resolve.test.ts

@@ -0,0 +1,169 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+
+import { model, type ServingEndpointSummary } from "@dbx-tools/shared-model";
+
+import { FALLBACK_MODEL_IDS, modelsForClass } from "../src/fallback";
+import { rankModels, resolveModel } from "../src/resolve";
+import { resolveModelId, searchServingEndpoints } from "../src/serving";
+
+const { ModelClass } = model;
+
+const CHAT_TASK = "llm/v1/chat";
+const EMBEDDING_TASK = "llm/v1/embeddings";
+
+/**
+ * Unscored chat endpoints classify deterministically by family name (opus ->
+ * ChatThinking, sonnet -> ChatBalanced, haiku -> ChatFast), so class membership
+ * in these tests doesn't depend on quality quantiles.
+ */
+function chat(name: string): ServingEndpointSummary {
+  return { name, task: CHAT_TASK };
+}
+
+/** An embedding endpoint - classified into ModelClass.Embedding by task. */
+function embedding(name: string): ServingEndpointSummary {
+  return { name, task: EMBEDDING_TASK };
+}
+
+const OPUS_8 = "databricks-claude-opus-4-8";
+const OPUS_7 = "databricks-claude-opus-4-7";
+const OPUS_6 = "databricks-claude-opus-4-6";
+const SONNET = "databricks-claude-sonnet-4-6";
+const HAIKU_5 = "databricks-claude-haiku-4-5";
+const HAIKU_3 = "databricks-claude-haiku-4-3";
+const GTE = "databricks-gte-large-en";
+const BGE = "databricks-bge-large-en";
+
+/** opus (ChatThinking) / sonnet (ChatBalanced) / haiku (ChatFast) - one per band. */
+const TIERED = [chat(OPUS_8), chat(SONNET), chat(HAIKU_5)];
+
+function names(models: { endpoint: ServingEndpointSummary }[]): string[] {
+  return models.map((m) => m.endpoint.name);
+}
+
+describe("searchServingEndpoints / resolveModelId", () => {
+  const endpoints = [chat(OPUS_8), chat(SONNET), chat(HAIKU_5)];
+
+  it("short-circuits an exact name to score 0", () => {
+    const [best] = searchServingEndpoints(SONNET, endpoints);
+    assert.equal(best?.endpoint.name, SONNET);
+    assert.equal(best?.score, 0);
+  });
+
+  it("tokenized fuzzy-matches a loose name", () => {
+    const result = resolveModelId("claude sonnet", endpoints);
+    assert.equal(result.matched, true);
+    assert.equal(result.modelId, SONNET);
+  });
+
+  it("returns the input verbatim when nothing matches", () => {
+    const result = resolveModelId("zzz-no-such-model", endpoints);
+    assert.equal(result.matched, false);
+    assert.equal(result.modelId, "zzz-no-such-model");
+  });
+
+  it("returns [] for an empty catalogue", () => {
+    assert.deepEqual(searchServingEndpoints("opus", []), []);
+  });
+});
+
+describe("rankModels", () => {
+  it("ranks a search match-then-class, version breaking the tie", () => {
+    const ranked = rankModels([chat(OPUS_6), chat(OPUS_8), chat(OPUS_7)], {
+      search: "opus",
+    });
+    assert.deepEqual(names(ranked), [OPUS_8, OPUS_7, OPUS_6]);
+  });
+
+  it("with no search, orders by class then within-class rank", () => {
+    const ranked = rankModels(TIERED);
+    assert.deepEqual(names(ranked), [OPUS_8, SONNET, HAIKU_5]);
+    assert.deepEqual(
+      ranked.map((m) => m.modelClass),
+      [ModelClass.ChatThinking, ModelClass.ChatBalanced, ModelClass.ChatFast],
+    );
+  });
+
+  it("excludes embeddings from the default (chat-only) ranking", () => {
+    const ranked = rankModels([chat(OPUS_8), embedding(GTE), embedding(BGE)]);
+    assert.deepEqual(names(ranked), [OPUS_8]);
+  });
+
+  it("ranks embeddings only when ModelClass.Embedding is requested", () => {
+    const ranked = rankModels([chat(OPUS_8), embedding(GTE), embedding(BGE)], {
+      modelClass: ModelClass.Embedding,
+    });
+    assert.deepEqual(names(ranked), [GTE, BGE]); // no chat model leaks in
+  });
+
+  it("treats a chat class as a ceiling: that band and below, never above", () => {
+    const ranked = rankModels(TIERED, { modelClass: ModelClass.ChatBalanced });
+    assert.deepEqual(names(ranked), [SONNET, HAIKU_5]); // no opus (ChatThinking)
+  });
+
+  it("degrades to a lower band when the requested band is empty", () => {
+    // "medium" requested but only "small" exists -> the highest small is
+    // returned, never a "large".
+    const ranked = rankModels([chat(OPUS_8), chat(HAIKU_5), chat(HAIKU_3)], {
+      modelClass: ModelClass.ChatBalanced,
+      limit: 1,
+    });
+    assert.deepEqual(names(ranked), [HAIKU_5]);
+  });
+
+  it("scopes a search to the class ceiling", () => {
+    const ranked = rankModels(TIERED, {
+      search: "claude",
+      modelClass: ModelClass.ChatFast,
+    });
+    assert.deepEqual(names(ranked), [HAIKU_5]); // opus / sonnet excluded by ceiling
+  });
+
+  it("applies a limit", () => {
+    assert.equal(rankModels(TIERED, { limit: 2 }).length, 2);
+  });
+});
+
+describe("resolveModel", () => {
+  it("fuzzy-resolves an explicit name to the best ranked match (limit 1)", () => {
+    const result = resolveModel([chat(OPUS_6), chat(OPUS_8), chat(OPUS_7)], {
+      explicit: "opus",
+    });
+    assert.deepEqual(result, { modelId: OPUS_8, source: "fuzzy-match" });
+  });
+
+  it("returns an explicit name verbatim when fuzzy is off", () => {
+    const result = resolveModel(TIERED, { explicit: "my-pinned-model", fuzzy: false });
+    assert.deepEqual(result, { modelId: "my-pinned-model", source: "explicit" });
+  });
+
+  it("resolves a class ask to the top of that band and below", () => {
+    const result = resolveModel(TIERED, { modelClass: ModelClass.ChatBalanced });
+    assert.deepEqual(result, { modelId: SONNET, source: "class" });
+  });
+
+  it("never selects an embedding model for a general (chat) ask", () => {
+    const result = resolveModel([embedding(GTE), chat(SONNET)]);
+    assert.equal(result.modelId, SONNET);
+  });
+
+  it("lets an operator-pinned fallback present in the catalogue win", () => {
+    const pinned = "databricks-approved-custom";
+    const result = resolveModel([...TIERED, chat(pinned)], { fallbacks: [pinned] });
+    assert.deepEqual(result, { modelId: pinned, source: "fallback" });
+  });
+
+  it("falls back to the class's static floor for an empty catalogue", () => {
+    const result = resolveModel([], { modelClass: ModelClass.ChatBalanced });
+    assert.deepEqual(result, {
+      modelId: modelsForClass(ModelClass.ChatBalanced)[0]!,
+      source: "class",
+    });
+  });
+
+  it("falls back to the static floor with no intent and an empty catalogue", () => {
+    const result = resolveModel([], {});
+    assert.deepEqual(result, { modelId: FALLBACK_MODEL_IDS[0]!, source: "fallback" });
+  });
+});

package/tsconfig.json

@@ -0,0 +1,41 @@
+// ~~ Generated by projen. To modify, edit .projenrc.js and run "pnpm exec projen".
+{
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib",
+    "alwaysStrict": true,
+    "declaration": true,
+    "esModuleInterop": true,
+    "experimentalDecorators": true,
+    "inlineSourceMap": true,
+    "inlineSources": true,
+    "lib": [
+      "ES2022"
+    ],
+    "module": "ESNext",
+    "noEmitOnError": false,
+    "noFallthroughCasesInSwitch": true,
+    "noImplicitAny": true,
+    "noImplicitReturns": true,
+    "noImplicitThis": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "resolveJsonModule": true,
+    "strict": true,
+    "strictNullChecks": true,
+    "strictPropertyInitialization": true,
+    "stripInternal": true,
+    "target": "ES2022",
+    "types": [
+      "node"
+    ],
+    "moduleResolution": "bundler",
+    "skipLibCheck": true
+  },
+  "include": [
+    "src/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}