@dbx-tools/shared-model 0.1.2

package/README.md

@@ -0,0 +1,81 @@
+# @dbx-tools/shared-model
+
+Browser-safe model-selection contract and classifier.
+
+Import this package when UI code, route handlers, tools, or tests need to
+validate model lookup requests, type ranked model responses, or classify serving
+endpoints without talking to Databricks. Live workspace listing and fuzzy
+resolution live in [`@dbx-tools/node-model`](../../node/model).
+
+Key features:
+
+- Shared `ModelClass` taxonomy for chat-thinking, chat-balanced, chat-fast, and
+  embedding workloads.
+- Browser-safe zod schemas for lookup requests, endpoint summaries, ranked
+  results, and profile metadata.
+- Endpoint classifier that groups serving endpoints by score profile and family
+  naming conventions.
+- Version/family parsing helpers for model catalogues and tests.
+- Types that match the server selection API without depending on the Databricks
+  SDK.
+
+## Validate A Model Lookup Request
+
+```ts
+import { model } from "@dbx-tools/shared-model";
+
+const query = model.ModelQuerySchema.parse({
+  search: "claude sonnet",
+  modelClass: "chat-balanced",
+  limit: 5,
+});
+```
+
+Use `model.ModelQuerySchema` for route query/body validation and agent tool
+inputs. It keeps client model pickers and backend resolution endpoints on the
+same request shape.
+
+## Type Ranked Results
+
+```ts
+import { model, type RankedModel } from "@dbx-tools/shared-model";
+
+const ranked: RankedModel = model.RankedModelSchema.parse(response);
+```
+
+`model.ServingEndpointSummarySchema` describes the stable endpoint fields exposed
+to clients: endpoint name, task, state, optional profile scores, classified
+class, and embedding dimension.
+
+## Classify Endpoint Catalogues
+
+```ts
+import { classify, model } from "@dbx-tools/shared-model";
+
+const byClass = classify.classifyEndpoints(endpoints);
+const fast = byClass[model.ModelClass.ChatFast];
+```
+
+The classifier uses Foundation Model API quality/speed/cost scores when present
+and family-name heuristics when scores are missing. This is useful for client
+grouping, tests, and offline catalogue analysis.
+
+## Parse Model Families
+
+```ts
+const family = classify.classifyByFamily("databricks-claude-sonnet-4-6");
+const version = classify.versionTuple("llama-3-1-70b");
+```
+
+Family parsing helps callers bucket custom lists or explain why an endpoint
+landed in a class before the live workspace scores are available.
+
+## Modules
+
+- `model` - `ModelClass`, zod schemas, and inferred types for profiles,
+  endpoint summaries, lookup requests, and ranked results.
+- `classify` - family parsing, version tuple parsing, and endpoint
+  classification.
+
+Server-side selection, cache, and fuzzy endpoint matching are in
+[`@dbx-tools/node-model`](../../node/model).

package/index.ts

@@ -0,0 +1,8 @@
+// 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 classify from "./src/classify";
+export * as model from "./src/model";
+export type { FamilyClass } from "./src/classify";
+export type { ModelProfile, ServingEndpointSummary, ModelQuery, RankedModel } from "./src/model";

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@dbx-tools/shared-model",
+  "devDependencies": {
+    "@types/node": "^24.6.0",
+    "tsx": "^4.23.0",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "zod": "^4.3.6",
+    "@dbx-tools/shared-core": "0.1.2"
+  },
+  "main": "index.ts",
+  "license": "UNLICENSED",
+  "version": "0.1.2",
+  "types": "index.ts",
+  "type": "module",
+  "exports": {
+    ".": "./index.ts",
+    "./package.json": "./package.json"
+  },
+  "dbxToolsConfig": {
+    "tags": [
+      "shared"
+    ]
+  },
+  "//": "~~ 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/classify.ts

@@ -0,0 +1,264 @@
+/**
+ * Model-class classification for Databricks Model Serving endpoints.
+ *
+ * Chat capability bands are derived from the live workspace catalogue
+ * rather than a hand-maintained table. Databricks publishes
+ * per-endpoint `quality` / `speed` / `cost` scores (the AI Playground
+ * bars) on the serving list; {@link classifyEndpoints} buckets scored
+ * chat models into the chat {@link ModelClass} bands by the *relative*
+ * distribution of those scores (quantiles, not fixed cut-offs) so a
+ * brand-new model that lands outside today's score range still slots in
+ * next to its peers. Embedding endpoints (`task === "llm/v1/embeddings"`)
+ * are bucketed into {@link ModelClass.Embedding} by task, independent of
+ * any score.
+ *
+ * Unscored-but-recognizable chat endpoints are still placed by a small
+ * family heuristic ({@link classifyByFamily}) so a workspace whose
+ * models predate Foundation Model API scoring keeps working. The
+ * offline fallback floor - the hard-coded model list reached for when
+ * the live catalogue can't be read at all - is a server concern and
+ * lives in `@dbx-tools/model`, not here: a browser client never talks
+ * to Databricks directly, so it has nothing to fall back to.
+ *
+ * Pure (no Node-only imports), so a client can classify a `/models`
+ * response without server dependencies.
+ */
+
+import { ModelClass, type ServingEndpointSummary } from "./model";
+
+/** Task hint Databricks stamps on chat completion endpoints. */
+const CHAT_TASK = "llm/v1/chat";
+
+/** Task hint Databricks stamps on embedding endpoints. */
+const EMBEDDING_TASK = "llm/v1/embeddings";
+
+/** Family-heuristic classification of a single endpoint name. */
+export interface FamilyClass {
+  /** Chat capability band the family maps to (never embedding). */
+  class: ModelClass;
+  /** Intra-family ordering hint (higher is newer / more capable). */
+  rank: number;
+}
+
+/**
+ * Numeric `[major, minor, patch]` version parsed from an endpoint
+ * name, used to order siblings within a family/tier. Starts at the
+ * first digit in the name, then reads successive separator-delimited,
+ * digit-prefixed chunks as the three components (missing ones default
+ * to `0`):
+ *
+ *   - `databricks-claude-opus-4-8`   -> `[4, 8, 0]`
+ *   - `databricks-claude-opus-4-10`  -> `[4, 10, 0]` (sorts above 4-8)
+ *   - `databricks-meta-llama-3-3-70b`-> `[3, 3, 70]`
+ *   - `databricks-bge-large-en`      -> `[0, 0, 0]` (no digits)
+ *
+ * Component-wise comparison (not a decimal collapse) so `4.10` beats
+ * `4.8` - the bug a `major + minor/10` score would hit.
+ */
+export function versionTuple(name: string): [number, number, number] {
+  const start = name.search(/\d/);
+  if (start < 0) return [0, 0, 0];
+  const nums = name
+    .slice(start)
+    .split(/[^a-z0-9]+/i)
+    .map((chunk) => chunk.match(/^\d+/)?.[0])
+    .filter((digits): digits is string => digits !== undefined)
+    .map(Number);
+  return [nums[0] ?? 0, nums[1] ?? 0, nums[2] ?? 0];
+}
+
+/** Compare two version tuples so the higher version sorts first (descending). */
+function compareVersionDesc(a: readonly number[], b: readonly number[]): number {
+  for (let i = 0; i < 3; i++) {
+    const diff = (b[i] ?? 0) - (a[i] ?? 0);
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}
+
+/**
+ * Monotonic version key for ordering siblings within a family/tier
+ * (e.g. `opus-4-8` over `opus-4-7`). Encodes the {@link versionTuple}
+ * as a single number so callers that need a scalar rank (the family
+ * heuristic, the static fallback ordering) keep working; the encoding
+ * preserves component order without the decimal-collapse bug.
+ */
+function versionScore(name: string): number {
+  const [major, minor, patch] = versionTuple(name);
+  return major * 1_000_000 + minor * 1_000 + patch;
+}
+
+/**
+ * Best-effort chat capability band for an endpoint we have no live
+ * score for, keyed off provider family and the well-known variant words
+ * in the name (`opus`/`sonnet`/`haiku`, `pro`/`mini`/`nano`,
+ * `flash`/`flash-lite`, Llama parameter sizes, etc). Returns `null` for
+ * names we don't recognize so unknown custom endpoints are never
+ * auto-selected as a default. The accompanying `rank` orders siblings
+ * within a class. Only ever returns a chat band - embedding endpoints
+ * are classified by task, not name.
+ */
+export function classifyByFamily(name: string): FamilyClass | null {
+  const n = name.toLowerCase();
+  const at = (cls: ModelClass): FamilyClass => ({ class: cls, rank: versionScore(n) });
+
+  // Anthropic Claude
+  if (n.includes("opus")) return at(ModelClass.ChatThinking);
+  if (n.includes("sonnet")) return at(ModelClass.ChatBalanced);
+  if (n.includes("haiku")) return at(ModelClass.ChatFast);
+
+  // OpenAI open-weights (check before the generic gpt branch)
+  if (n.includes("gpt-oss")) {
+    return at(n.includes("120b") ? ModelClass.ChatBalanced : ModelClass.ChatFast);
+  }
+  // OpenAI GPT family
+  if (n.includes("gpt")) {
+    if (n.includes("pro")) return at(ModelClass.ChatThinking);
+    if (n.includes("mini") || n.includes("nano")) return at(ModelClass.ChatFast);
+    return at(ModelClass.ChatBalanced);
+  }
+
+  // Google Gemini / Gemma
+  if (n.includes("gemini")) {
+    if (n.includes("flash-lite")) return at(ModelClass.ChatFast);
+    if (n.includes("pro")) return at(ModelClass.ChatThinking);
+    return at(ModelClass.ChatBalanced);
+  }
+  if (n.includes("gemma")) return at(ModelClass.ChatFast);
+
+  // Meta Llama
+  if (n.includes("llama")) {
+    if (n.includes("maverick") || n.includes("405b")) return at(ModelClass.ChatThinking);
+    if (n.includes("70b")) return at(ModelClass.ChatBalanced);
+    if (n.includes("8b") || n.includes("1b")) return at(ModelClass.ChatFast);
+    return at(ModelClass.ChatBalanced);
+  }
+
+  // Alibaba Qwen
+  if (n.includes("qwen")) return at(ModelClass.ChatBalanced);
+
+  return null;
+}
+
+/** Linear-interpolated quantile of an ascending-sorted numeric array. */
+function quantile(sortedAsc: readonly number[], p: number): number {
+  if (sortedAsc.length === 0) return Number.NaN;
+  const idx = (sortedAsc.length - 1) * p;
+  const lo = Math.floor(idx);
+  const hi = Math.ceil(idx);
+  if (lo === hi) return sortedAsc[lo]!;
+  return sortedAsc[lo]! + (sortedAsc[hi]! - sortedAsc[lo]!) * (idx - lo);
+}
+
+/** Internal sortable wrapper carrying the ordering keys for a bucket entry. */
+interface Ranked {
+  ep: ServingEndpointSummary;
+  /** Quality (scored) or family version (unscored) - higher first. */
+  sort: number;
+  /** Scored endpoints rank ahead of family-only guesses. */
+  scored: boolean;
+  tieCost: number;
+  tieSpeed: number;
+  /** Parsed name version, the final tie-breaker (newer sibling first). */
+  version: readonly number[];
+}
+
+function rankOrder(a: Ranked, b: Ranked): number {
+  if (a.scored !== b.scored) return a.scored ? -1 : 1;
+  if (b.sort !== a.sort) return b.sort - a.sort;
+  if (a.tieCost !== b.tieCost) return a.tieCost - b.tieCost;
+  if (b.tieSpeed !== a.tieSpeed) return b.tieSpeed - a.tieSpeed;
+  // Same scored-ness, quality, cost, and speed (e.g. several Claude
+  // Opus point releases): prefer the newer parsed version so
+  // `opus-4-8` beats `opus-4-7`.
+  return compareVersionDesc(a.version, b.version);
+}
+
+/**
+ * Bucket live endpoints into {@link ModelClass}es, ranked best-first
+ * within each chat band.
+ *
+ * Embedding endpoints (`task === "llm/v1/embeddings"`) go into
+ * {@link ModelClass.Embedding} by task, in listing order (they carry no
+ * capability score to rank on).
+ *
+ * Chat endpoints (`task === "llm/v1/chat"`) split into the three chat
+ * bands. Scored endpoints (those carrying a `profile.quality`) drive
+ * the banding: the observed quality distribution is split at its 1/3
+ * and 2/3 quantiles, so the top third is {@link ModelClass.ChatThinking},
+ * the bottom third {@link ModelClass.ChatFast}, and the middle
+ * {@link ModelClass.ChatBalanced}. Because the thresholds come from the
+ * data, the split adapts as Databricks adds or rescores models -
+ * nothing is pinned to a fixed score band.
+ *
+ * Unscored chat endpoints are placed by {@link classifyByFamily} and
+ * ranked after the scored ones in their band; unrecognized, unscored
+ * endpoints (e.g. custom external models) are omitted entirely so they
+ * are never picked as an automatic default.
+ *
+ * Within a chat band, scored models sort by `quality` desc, then `cost`
+ * asc, then `speed` desc, then parsed name version desc; family-only
+ * models sort by version rank then parsed version. The version
+ * tie-break ({@link versionTuple}) is what separates point releases
+ * that share a score profile (e.g. `opus-4-8` ahead of `opus-4-7`).
+ */
+export function classifyEndpoints(
+  endpoints: readonly ServingEndpointSummary[],
+): Record<ModelClass, ServingEndpointSummary[]> {
+  const chat = endpoints.filter((e) => e.task === CHAT_TASK);
+  const qualities = chat
+    .map((e) => e.profile?.quality)
+    .filter((q): q is number => Number.isFinite(q))
+    .sort((a, b) => a - b);
+  const low = quantile(qualities, 1 / 3);
+  const high = quantile(qualities, 2 / 3);
+
+  const buckets: Record<ModelClass, Ranked[]> = {
+    [ModelClass.ChatThinking]: [],
+    [ModelClass.ChatBalanced]: [],
+    [ModelClass.ChatFast]: [],
+    [ModelClass.Embedding]: [],
+  };
+
+  for (const ep of chat) {
+    const q = ep.profile?.quality;
+    if (Number.isFinite(q)) {
+      const quality = q as number;
+      const cls =
+        quality >= high
+          ? ModelClass.ChatThinking
+          : quality <= low
+            ? ModelClass.ChatFast
+            : ModelClass.ChatBalanced;
+      buckets[cls].push({
+        ep,
+        sort: quality,
+        scored: true,
+        tieCost: ep.profile?.cost ?? Number.POSITIVE_INFINITY,
+        tieSpeed: ep.profile?.speed ?? 0,
+        version: versionTuple(ep.name),
+      });
+      continue;
+    }
+    const family = classifyByFamily(ep.name);
+    if (!family) continue;
+    buckets[family.class].push({
+      ep,
+      sort: family.rank,
+      scored: false,
+      tieCost: Number.POSITIVE_INFINITY,
+      tieSpeed: 0,
+      version: versionTuple(ep.name),
+    });
+  }
+
+  // Embeddings are bucketed by task in listing order - no score to rank.
+  const embeddings = endpoints.filter((e) => e.task === EMBEDDING_TASK);
+
+  return {
+    [ModelClass.ChatThinking]: buckets[ModelClass.ChatThinking].sort(rankOrder).map((x) => x.ep),
+    [ModelClass.ChatBalanced]: buckets[ModelClass.ChatBalanced].sort(rankOrder).map((x) => x.ep),
+    [ModelClass.ChatFast]: buckets[ModelClass.ChatFast].sort(rankOrder).map((x) => x.ep),
+    [ModelClass.Embedding]: embeddings,
+  };
+}

package/src/model.ts

@@ -0,0 +1,147 @@
+/**
+ * Wire-format types for the model toolkit: the model class taxonomy,
+ * the Foundation Model API score profile, the minimal serving-endpoint
+ * descriptor, and the model-lookup request / ranked-result contract.
+ * Pure types and zod schemas - no Node-only imports - so a browser
+ * client (or an agent tool's `inputSchema`) can validate a lookup
+ * request and type a ranked response without dragging in server
+ * dependencies.
+ */
+
+import { z } from "zod";
+
+/**
+ * Class of a Databricks Model Serving endpoint - its modality plus,
+ * for chat models, a capability band. Chat endpoints split by measured
+ * `quality` into a three-rung ladder; embeddings are a separate
+ * modality, not a rung on that ladder.
+ *
+ * String enum so the value is the slug used in cache keys, logs, query
+ * strings, and serialized configs - and is what a client sends to
+ * request a class.
+ */
+export enum ModelClass {
+  ChatThinking = "chat-thinking",
+  ChatBalanced = "chat-balanced",
+  ChatFast = "chat-fast",
+  Embedding = "embedding",
+}
+
+const ModelClassDescriptions: Record<ModelClass, string> = {
+  [ModelClass.ChatThinking]:
+    "Most capable reasoning for hard, multi-step tasks; slowest and most expensive.",
+  [ModelClass.ChatBalanced]:
+    "Good default for most chat and agent work; balances quality, speed, and cost.",
+  [ModelClass.ChatFast]:
+    "Fastest and cheapest; best for simple tasks like classification, routing, and short summaries.",
+  [ModelClass.Embedding]:
+    "Produces text embeddings (vectors), not chat replies; not interchangeable with chat models.",
+};
+
+export const ModelClassSchema = z.enum(ModelClass).describe(
+  `Endpoint class slug: ${(Object.values(ModelClass) as ModelClass[])
+    .map((modelClass) => {
+      return `'${modelClass}' (${ModelClassDescriptions[modelClass]})`;
+    })
+    .join(", ")}.`,
+);
+
+/**
+ * Foundation Model API quality / speed / cost scores Databricks
+ * publishes per pay-per-token endpoint (the bars shown in the AI
+ * Playground). Surfaced from the serving list under
+ * `config.served_entities[].foundation_model.ai_gateway_model_profile`
+ * so the class classifier can rank models from live, workspace-local
+ * numbers instead of a hand-maintained table. Scales are relative and
+ * unitless; all axes are absent for custom or brand-new endpoints that
+ * have no profile yet.
+ */
+export const ModelProfileSchema = z.object({
+  quality: z.number().optional().describe("Relative quality score; higher is better."),
+  speed: z.number().optional().describe("Relative throughput score; higher is faster."),
+  cost: z.number().optional().describe("Relative price score; lower is cheaper."),
+});
+export type ModelProfile = z.infer<typeof ModelProfileSchema>;
+
+/**
+ * Minimal descriptor for a Databricks Model Serving endpoint - a
+ * stable subset of the SDK type so cache hits and `/models` responses
+ * never expose SDK internals.
+ */
+export const ServingEndpointSummarySchema = z.object({
+  name: z
+    .string()
+    .describe(
+      "Endpoint name as listed by the Model Serving REST API; the id used to invoke the model.",
+    ),
+  task: z.string().optional().describe("Task hint, e.g. 'llm/v1/chat' or 'llm/v1/embeddings'."),
+  state: z.string().optional().describe("Deployment state, e.g. ready, updating, or failed."),
+  description: z.string().optional().describe("Free-form endpoint description; informational."),
+  profile: ModelProfileSchema.optional().describe(
+    "Foundation Model API quality/speed/cost scores when the endpoint is a scored pay-per-token model; absent otherwise.",
+  ),
+  class: ModelClassSchema.optional().describe(
+    "Class the endpoint was classified into; absent when the classifier doesn't recognize it.",
+  ),
+  dimension: z
+    .number()
+    .optional()
+    .describe(
+      "Embedding vector length, measured by a best-effort server-side ping. Only set for embedding endpoints, and only when the probe succeeded.",
+    ),
+});
+export type ServingEndpointSummary = z.infer<typeof ServingEndpointSummarySchema>;
+
+/**
+ * A model-lookup request: search string, capability ceiling, both, or
+ * nothing. This is the caller-facing query the `@dbx-tools/model`
+ * ranker reads - shaped as a zod schema (with per-field descriptions)
+ * so an agent tool can adopt it directly as its `inputSchema` and a
+ * browser client can validate args before calling the model service.
+ *
+ * Every field is optional: an empty query ranks the live catalogue by
+ * class alone. The "this class and below" ceiling semantics and the
+ * match-then-class ordering live in the service, not here - this
+ * surface is declarative.
+ */
+export const ModelQuerySchema = z.object({
+  search: z
+    .string()
+    .optional()
+    .describe(
+      "Loose name fuzzy-matched against endpoint names, e.g. 'claude sonnet'. Omit to rank by class alone.",
+    ),
+  modelClass: ModelClassSchema.optional().describe(
+    "Capability ceiling: a chat class restricts to that band and the less-capable chat bands below it; 'embedding' restricts to embedding endpoints. Omit to consider every chat band.",
+  ),
+  limit: z
+    .number()
+    .int()
+    .positive()
+    .max(50)
+    .optional()
+    .describe("Maximum number of ranked results to return."),
+  threshold: z
+    .number()
+    .min(0)
+    .max(1)
+    .optional()
+    .describe("Fuzzy-match distance cutoff (0 = exact, 1 = match anything). Default 0.4."),
+});
+export type ModelQuery = z.infer<typeof ModelQuerySchema>;
+
+/**
+ * One ranked lookup result. Backs an agent tool's `outputSchema` and a
+ * `/models` ranked response.
+ */
+export const RankedModelSchema = z.object({
+  endpoint: ServingEndpointSummarySchema.describe("The matched serving endpoint."),
+  modelClass: ModelClassSchema.describe("Class the endpoint was classified into."),
+  score: z
+    .number()
+    .optional()
+    .describe(
+      "Fuzzy-match distance (0 = exact .. 1 = worst) when the query carried a search; absent for class-only ranking.",
+    ),
+});
+export type RankedModel = z.infer<typeof RankedModelSchema>;

package/test/classify.test.ts

@@ -0,0 +1,159 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { classifyByFamily, classifyEndpoints, versionTuple } from "../src/classify";
+import { ModelClass, type ModelProfile, type ServingEndpointSummary } from "../src/model";
+
+const CHAT_TASK = "llm/v1/chat";
+const EMBEDDING_TASK = "llm/v1/embeddings";
+
+/** Build a chat serving endpoint, optionally scored, for classifier fixtures. */
+function chat(name: string, profile?: ModelProfile): ServingEndpointSummary {
+  return { name, task: CHAT_TASK, ...(profile ? { profile } : {}) };
+}
+
+/** Build an embedding serving endpoint for classifier fixtures. */
+function embedding(name: string): ServingEndpointSummary {
+  return { name, task: EMBEDDING_TASK };
+}
+
+/** Names of the endpoints classified into `cls`, in ranked order. */
+function classNames(
+  buckets: Record<ModelClass, ServingEndpointSummary[]>,
+  cls: ModelClass,
+): string[] {
+  return buckets[cls].map((e) => e.name);
+}
+
+describe("versionTuple", () => {
+  it("reads major.minor.patch starting at the first digit", () => {
+    assert.deepEqual(versionTuple("databricks-claude-opus-4-8"), [4, 8, 0]);
+    assert.deepEqual(versionTuple("databricks-claude-opus-4-7"), [4, 7, 0]);
+    assert.deepEqual(versionTuple("databricks-gpt-5-5"), [5, 5, 0]);
+  });
+
+  it("keeps double-digit components numeric (no decimal collapse)", () => {
+    assert.deepEqual(versionTuple("databricks-claude-opus-4-10"), [4, 10, 0]);
+    // 4.10 must sort ABOVE 4.8 - the bug a `major + minor/10` score hit.
+    const [, tenMinor] = versionTuple("databricks-claude-opus-4-10");
+    const [, eightMinor] = versionTuple("databricks-claude-opus-4-8");
+    assert.ok(tenMinor > eightMinor);
+  });
+
+  it("reads a parameter-size suffix as the patch component", () => {
+    assert.deepEqual(versionTuple("databricks-meta-llama-3-3-70b-instruct"), [3, 3, 70]);
+    assert.deepEqual(versionTuple("databricks-gpt-oss-120b"), [120, 0, 0]);
+  });
+
+  it("returns all-zero for names with no digits", () => {
+    assert.deepEqual(versionTuple("databricks-bge-large-en"), [0, 0, 0]);
+  });
+});
+
+describe("classifyEndpoints", () => {
+  it("buckets scored models by quality quantiles, best-first", () => {
+    // Three clear quality bands (gaps keep the 1/3 and 2/3 quantiles
+    // between bands), two models per chat band.
+    const buckets = classifyEndpoints([
+      chat("databricks-claude-opus-4-8", { quality: 90, cost: 10, speed: 44 }),
+      chat("databricks-claude-opus-4-7", { quality: 88, cost: 10, speed: 44 }),
+      chat("databricks-claude-sonnet-4-6", { quality: 50, cost: 18, speed: 55 }),
+      chat("databricks-gpt-5-5", { quality: 48, cost: 20, speed: 50 }),
+      chat("databricks-claude-haiku-4-5", { quality: 10, cost: 5, speed: 80 }),
+      chat("databricks-meta-llama-3-1-8b-instruct", { quality: 8, cost: 3, speed: 90 }),
+    ]);
+    assert.deepEqual(classNames(buckets, ModelClass.ChatThinking), [
+      "databricks-claude-opus-4-8",
+      "databricks-claude-opus-4-7",
+    ]);
+    assert.deepEqual(classNames(buckets, ModelClass.ChatBalanced), [
+      "databricks-claude-sonnet-4-6",
+      "databricks-gpt-5-5",
+    ]);
+    assert.deepEqual(classNames(buckets, ModelClass.ChatFast), [
+      "databricks-claude-haiku-4-5",
+      "databricks-meta-llama-3-1-8b-instruct",
+    ]);
+  });
+
+  it("breaks a scored tie (same quality/cost/speed) by parsed version", () => {
+    // All identical except the trailing version: only versionTuple can
+    // order them. This is the live `q=46` Opus case.
+    const buckets = classifyEndpoints([
+      chat("databricks-claude-opus-4-6", { quality: 90, cost: 10, speed: 44 }),
+      chat("databricks-claude-opus-4-8", { quality: 90, cost: 10, speed: 44 }),
+      chat("databricks-claude-opus-4-7", { quality: 90, cost: 10, speed: 44 }),
+    ]);
+    assert.deepEqual(classNames(buckets, ModelClass.ChatThinking), [
+      "databricks-claude-opus-4-8",
+      "databricks-claude-opus-4-7",
+      "databricks-claude-opus-4-6",
+    ]);
+  });
+
+  it("orders a double-digit point release above a single-digit one", () => {
+    const buckets = classifyEndpoints([
+      chat("databricks-claude-opus-4-9", { quality: 90, cost: 10, speed: 44 }),
+      chat("databricks-claude-opus-4-10", { quality: 90, cost: 10, speed: 44 }),
+    ]);
+    assert.deepEqual(classNames(buckets, ModelClass.ChatThinking), [
+      "databricks-claude-opus-4-10",
+      "databricks-claude-opus-4-9",
+    ]);
+  });
+
+  it("places unscored but recognizable chat endpoints by family heuristic", () => {
+    const buckets = classifyEndpoints([
+      chat("databricks-claude-opus-4-1"),
+      chat("databricks-claude-sonnet-4-0"),
+      chat("databricks-claude-haiku-3-5"),
+    ]);
+    assert.deepEqual(classNames(buckets, ModelClass.ChatThinking), [
+      "databricks-claude-opus-4-1",
+    ]);
+    assert.deepEqual(classNames(buckets, ModelClass.ChatBalanced), [
+      "databricks-claude-sonnet-4-0",
+    ]);
+    assert.deepEqual(classNames(buckets, ModelClass.ChatFast), [
+      "databricks-claude-haiku-3-5",
+    ]);
+  });
+
+  it("buckets embedding endpoints by task, regardless of name or score", () => {
+    const buckets = classifyEndpoints([
+      chat("databricks-claude-opus-4-1"),
+      embedding("databricks-gte-large-en"),
+      embedding("databricks-bge-large-en"),
+    ]);
+    assert.deepEqual(classNames(buckets, ModelClass.Embedding), [
+      "databricks-gte-large-en",
+      "databricks-bge-large-en",
+    ]);
+    // Embeddings never leak into a chat band.
+    assert.deepEqual(classNames(buckets, ModelClass.ChatThinking), [
+      "databricks-claude-opus-4-1",
+    ]);
+  });
+
+  it("omits unrecognized unscored chat endpoints from every chat band", () => {
+    const buckets = classifyEndpoints([
+      chat("databricks-claude-opus-4-1"),
+      chat("databricks-some-custom-thing"),
+    ]);
+    const chatNames = [
+      ...buckets[ModelClass.ChatThinking],
+      ...buckets[ModelClass.ChatBalanced],
+      ...buckets[ModelClass.ChatFast],
+    ].map((e) => e.name);
+    assert.deepEqual(chatNames, ["databricks-claude-opus-4-1"]);
+  });
+});
+
+describe("classifyByFamily", () => {
+  it("maps well-known variants to chat classes and returns null for unknowns", () => {
+    assert.equal(classifyByFamily("databricks-claude-opus-4-8")?.class, ModelClass.ChatThinking);
+    assert.equal(classifyByFamily("databricks-claude-sonnet-4-6")?.class, ModelClass.ChatBalanced);
+    assert.equal(classifyByFamily("databricks-claude-haiku-4-5")?.class, ModelClass.ChatFast);
+    assert.equal(classifyByFamily("databricks-gpt-5-nano")?.class, ModelClass.ChatFast);
+    assert.equal(classifyByFamily("databricks-some-custom-thing"), null);
+  });
+});

package/tsconfig.json

@@ -0,0 +1,40 @@
+// ~~ 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",
+      "WebWorker"
+    ],
+    "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": [],
+    "moduleResolution": "bundler",
+    "skipLibCheck": true
+  },
+  "include": [
+    "src/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}