@dbx-tools/model 0.9.40 → 0.9.46

package/package.json

@@ -27,11 +27,11 @@
   },
   "dependencies": {
     "@databricks/appkit": "0.81.0",
-    "@dbx-tools/appkit": "^0.9.40",
-    "@dbx-tools/auth": "^0.9.40",
-    "@dbx-tools/shared-auth": "^0.9.40",
-    "@dbx-tools/shared-core": "^0.9.40",
-    "@dbx-tools/shared-model": "^0.9.40",
+    "@dbx-tools/appkit": "^0.9.46",
+    "@dbx-tools/auth": "^0.9.46",
+    "@dbx-tools/shared-auth": "^0.9.46",
+    "@dbx-tools/shared-core": "^0.9.46",
+    "@dbx-tools/shared-model": "^0.9.46",
     "cacache": "^21.0.1",
     "env-paths": "^4.0.0",
     "fuse.js": "^7.4.2"
@@ -47,6 +47,10 @@
         "types": "./lib/index.d.ts",
         "default": "./lib/index.js"
       },
+      "./bindings": {
+        "types": "./lib/src/bindings.d.ts",
+        "default": "./lib/src/bindings.js"
+      },
       "./classes": {
         "types": "./lib/src/classes.d.ts",
         "default": "./lib/src/classes.js"
@@ -98,7 +102,7 @@
       "./package.json": "./package.json"
     }
   },
-  "version": "0.9.40",
+  "version": "0.9.46",
   "types": "./lib/index.d.ts",
   "dbxToolsConfig": {
     "tags": [
@@ -111,6 +115,10 @@
       "types": "./lib/index.d.ts",
       "default": "./lib/index.js"
     },
+    "./bindings": {
+      "types": "./lib/src/bindings.d.ts",
+      "default": "./lib/src/bindings.js"
+    },
     "./classes": {
       "types": "./lib/src/classes.d.ts",
       "default": "./lib/src/classes.js"

package/src/_metadata-generator.ts

@@ -7,7 +7,7 @@ import type {
   ReasoningModelsSnapshot,
   RetiredModelsSnapshot,
 } from "./_metadata-contract.ts";
-import { modelSearchQuery } from "./policy.ts";
+import { inheritsNativeWebSearch, modelSearchQuery } from "./policy.ts";
 import {
   parseReasoning,
   REASONING_LEVELS,
@@ -132,10 +132,7 @@ export function parseModelRateLimits(html: string, generatedAt: number): ModelRa
 }
 
 /** Parse reasoning-effort ladders from the Query reasoning models HTML table. */
-export function parseReasoningModels(
-  html: string,
-  generatedAt: number,
-): ReasoningModelsSnapshot {
+export function parseReasoningModels(html: string, generatedAt: number): ReasoningModelsSnapshot {
   const $ = load(html);
   const models: Record<string, ReasoningLevel[]> = {};
   $("table").each((_, table) => {
@@ -147,7 +144,10 @@ export function parseReasoningModels(
     if (!headers.some((header) => header.includes("model"))) return;
     if (!headers.some((header) => header.includes("parameter"))) return;
     rows.slice(1).each((__, row) => {
-      const cells = $(row).find("th, td").toArray().map((cell) => $(cell));
+      const cells = $(row)
+        .find("th, td")
+        .toArray()
+        .map((cell) => $(cell));
       if (cells.length < 2) return;
       const modelNames = reasoningModelNamesFromCell(cells[0]!, $);
       if (modelNames.length === 0) return;
@@ -268,7 +268,6 @@ function modelsAfterHeading($: CheerioAPI, headingId: string): string[] {
 }
 
 function nativeWebSearchModels($: CheerioAPI, responses: readonly string[]): string[] {
-  const families = new Set<string>();
   const models = new Set<string>();
   let nativeSection = false;
   for (const element of sectionElements($, "supported-models")) {
@@ -285,11 +284,10 @@ function nativeWebSearchModels($: CheerioAPI, responses: readonly string[]): str
       const model = modelKey(value);
       if (!model) continue;
       models.add(model);
-      families.add(model.split("-", 1)[0]);
     }
   }
   for (const model of responses) {
-    if (families.has(model.split("-", 1)[0])) models.add(model);
+    if (inheritsNativeWebSearch(model, models)) models.add(model);
   }
   return [...models].sort();
 }
@@ -307,11 +305,13 @@ function codeValuesAfterHeading($: CheerioAPI, headingId: string): string[] {
 
 function sectionElements($: CheerioAPI, headingId: string): Selection[] {
   const heading = $(`#${headingId}`).first();
-  if (heading.length === 0)
+  if (heading.length === 0) {
     throw new Error(`Databricks capability page is missing section ${headingId}`);
+  }
   const level = headingLevel(nodeTagName(heading.get(0)));
-  if (level === undefined)
+  if (level === undefined) {
     throw new Error(`Databricks capability section ${headingId} is not a heading`);
+  }
   const elements: Selection[] = [];
   let sibling = heading.next();
   while (sibling.length > 0) {

package/src/_ranking.ts

@@ -8,6 +8,7 @@ import {
 import { toModelDisplayName } from "@dbx-tools/shared-model/display";
 import Fuse from "fuse.js";
 
+import { modelStatusFor } from "./_retirement.ts";
 import { classesAtOrBelow, CHAT_CLASS_ORDER, MODEL_CLASS_ORDER } from "./classes.ts";
 import {
   classifyEndpoints,
@@ -15,7 +16,6 @@ import {
   supportsToolsByFamily,
   versionTuple,
 } from "./classify.ts";
-import { modelStatusFor } from "./metadata.ts";
 import { modelFamily, modelReasoningEfforts, modelServiceNames } from "./policy.ts";
 
 type ModelClass = ModelClassType;
@@ -34,8 +34,9 @@ export function rankEndpoints(
   query: ModelQuery = {},
   options: NativeRankingOptions = {},
 ): RankedModel[] {
-  const originalByName = new Map(endpoints.map((endpoint) => [endpoint.name, endpoint]));
-  const normalized = endpoints.map((endpoint) => ({
+  const filtered = endpoints.filter((endpoint) => matchesModelQuery(endpoint, query));
+  const originalByName = new Map(filtered.map((endpoint) => [endpoint.name, endpoint]));
+  const normalized = filtered.map((endpoint) => ({
     ...endpoint,
     ...(options.modelClass ? { class: options.modelClass } : {}),
     ...(options.task ? { task: options.task } : {}),
@@ -50,13 +51,14 @@ export function rankEndpoints(
       }
     : classifyEndpoints(normalized);
   const requestedClass = options.modelClass ?? query.modelClass;
+  const includeDeprecated = query.includeDeprecated ?? options.includeDeprecated ?? false;
   const eligible = requestedClass ? classesAtOrBelow(requestedClass) : CHAT_CLASS_ORDER;
   const candidates: RankedModel[] = [];
   const search = query.search?.trim();
   if (search && requestedClass === undefined) {
     const classByName = classifyEndpointClasses(normalized);
     for (const endpoint of normalized) {
-      if (!options.includeDeprecated && endpoint.status?.deprecated) continue;
+      if (!includeDeprecated && endpoint.status?.deprecated) continue;
       const capabilities = endpointCapabilities(endpoint);
       if (!capabilities.chat || (query.requiresTools && !capabilities.tools)) continue;
       candidates.push({
@@ -67,7 +69,7 @@ export function rankEndpoints(
   } else {
     for (const modelClass of eligible) {
       for (const endpoint of classified[modelClass]) {
-        if (!options.includeDeprecated && endpoint.status?.deprecated) continue;
+        if (!includeDeprecated && endpoint.status?.deprecated) continue;
         if (query.requiresTools && !endpointCapabilities(endpoint).tools) continue;
         candidates.push({ endpoint, modelClass });
       }
@@ -125,6 +127,28 @@ export function rankEndpoints(
   return query.limit === undefined ? restored : restored.slice(0, Math.max(0, query.limit));
 }
 
+function matchesModelQuery(endpoint: ServingEndpointSummary, query: ModelQuery): boolean {
+  if (query.name !== undefined && endpoint.name !== query.name) return false;
+  if (query.task !== undefined && endpoint.task !== query.task) return false;
+  if (
+    query.reasoningEffort !== undefined &&
+    !endpoint.reasoningEfforts?.includes(query.reasoningEffort)
+  ) {
+    return false;
+  }
+  if (
+    query.dimension !== undefined ||
+    query.minDimension !== undefined ||
+    query.maxDimension !== undefined
+  ) {
+    if (endpoint.dimension === undefined) return false;
+    if (query.dimension !== undefined && endpoint.dimension !== query.dimension) return false;
+    if (query.minDimension !== undefined && endpoint.dimension < query.minDimension) return false;
+    if (query.maxDimension !== undefined && endpoint.dimension > query.maxDimension) return false;
+  }
+  return true;
+}
+
 /** Classify chat and embedding endpoints through the TypeScript-owned policy. */
 export function classifyEndpointClasses(
   endpoints: readonly ServingEndpointSummary[],

package/src/_retirement.ts

@@ -0,0 +1,70 @@
+/** Lightweight model retirement state shared by discovery and metadata caches. */
+import type { ModelStatus, ServingEndpointSummary } from "@dbx-tools/shared-model/contracts";
+
+import type { RetiredModelsSnapshot } from "./_metadata-contract.ts";
+import retiredModelsSnapshotJson from "./generated/retired-models.json" with { type: "json" };
+
+const snapshot = retiredModelsSnapshotJson as RetiredModelsSnapshot;
+const RETIRED_MODEL_PREFIXES = new Set([
+  "ai",
+  "anthropic",
+  "databricks",
+  "dbx",
+  "google",
+  "meta",
+  "openai",
+  "system",
+]);
+
+let names: readonly string[] = Object.freeze([...snapshot.models]);
+let keys = retiredKeys(names);
+
+export const COMMITTED_RETIRED_MODELS = snapshot.models;
+export const RETIRED_MODELS_GENERATED_AT = snapshot.generatedAt;
+
+/** Replace retirement state after metadata cache hydration or refresh. */
+export function replaceRetiredModelNames(models: readonly string[]): void {
+  names = Object.freeze([...models]);
+  keys = retiredKeys(names);
+}
+
+/** Return the active retired-model names. */
+export function retiredModelNames(): readonly string[] {
+  return names;
+}
+
+/** Resolve whether any supplied identity is listed as retired. */
+export function modelStatusFor(
+  ...models: readonly (string | ServingEndpointSummary)[]
+): ModelStatus {
+  const deprecated = models
+    .flatMap((model) => modelIdentities(model))
+    .some((identity) => {
+      const candidate = retiredModelKey(identity);
+      for (const key of keys) {
+        if (candidate === key || candidate.startsWith(`${key}-`)) return true;
+      }
+      return false;
+    });
+  return { deprecated };
+}
+
+function retiredKeys(models: readonly string[]): ReadonlySet<string> {
+  return new Set(models.map(retiredModelKey).filter(Boolean));
+}
+
+function modelIdentities(model: string | ServingEndpointSummary): string[] {
+  if (typeof model === "string") return [model];
+  return [
+    model.name,
+    model.displayName,
+    model.modelServiceName,
+    ...Object.values(model.serviceNames ?? {}),
+  ].filter((value): value is string => Boolean(value));
+}
+
+function retiredModelKey(value: string): string {
+  const tokens = value.toLowerCase().match(/[a-z0-9]+/g) ?? [];
+  while (tokens[0] && RETIRED_MODEL_PREFIXES.has(tokens[0])) tokens.shift();
+  return tokens.join("-");
+}

package/src/bindings.ts

@@ -0,0 +1,11 @@
+/**
+ * Binding-safe facade for Databricks model discovery and routing.
+ *
+ * Generated language bindings create one canonical model client so
+ * authentication, catalogue caching, ranking, and route selection remain
+ * attached to that client.
+ *
+ * @module
+ */
+
+export { createModelClient } from "./model-client.ts";

package/src/classify.ts

@@ -111,15 +111,24 @@ export function versionTuple(name: string): [number, number, 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);
+/**
+ * Compare version tuples component-wise with missing parts as 0.
+ * Positive when `left` is newer.
+ */
+export function compareVersionTuples(left: readonly number[], right: readonly number[]): number {
+  const length = Math.max(left.length, right.length, 3);
+  for (let index = 0; index < length; index += 1) {
+    const diff = (left[index] ?? 0) - (right[index] ?? 0);
     if (diff !== 0) return diff;
   }
   return 0;
 }
 
+/** Compare two version tuples so the higher version sorts first (descending). */
+function compareVersionDesc(a: readonly number[], b: readonly number[]): number {
+  return compareVersionTuples(b, a);
+}
+
 /**
  * Monotonic version key for ordering siblings within a family/tier
  * (e.g. `opus-4-8` over `opus-4-7`). Encodes the {@link versionTuple}

package/src/metadata-cache.ts

@@ -21,6 +21,7 @@ import * as log from "@dbx-tools/shared-core/log";
 import cacache from "cacache";
 import envPaths from "env-paths";
 
+import packageManifest from "../package.json" with { type: "json" };
 import { MODEL_METADATA_TTL_MS } from "./_metadata-contract.ts";
 
 const logger = log.logger("model/metadata-cache");
@@ -30,15 +31,10 @@ interface PackageIdentity {
   readonly version: string;
 }
 
-let packageIdentityPromise: Promise<PackageIdentity> | undefined;
-
-function packageIdentity(): Promise<PackageIdentity> {
-  packageIdentityPromise ??= import("../index.ts").then((mod) => ({
-    identifier: mod.PACKAGE_IDENTIFIER,
-    version: mod.PACKAGE_VERSION,
-  }));
-  return packageIdentityPromise;
-}
+const PACKAGE_IDENTITY: PackageIdentity = {
+  identifier: packageManifest.name,
+  version: packageManifest.version,
+};
 
 /** Envelope stored as JSON bytes in cacache for every key. */
 export interface MetadataCacheRecord<T> {
@@ -247,7 +243,7 @@ async function resolveCacheDir(options: {
   readonly version?: string;
 }): Promise<string> {
   if (options.cacheDir) return options.cacheDir;
-  const version = options.version ?? (await packageIdentity()).version;
+  const version = options.version ?? PACKAGE_IDENTITY.version;
   return defaultMetadataCacheDir(version);
 }
 
@@ -319,4 +315,3 @@ function isCacheMiss(error: unknown): boolean {
     (error as { code?: string }).code === "ENOENT",
   );
 }
-

package/src/metadata.ts

@@ -11,12 +11,10 @@
  * @module
  */
 import * as functionUtils from "@dbx-tools/shared-core/function-utils";
-import * as log from "@dbx-tools/shared-core/log";
 import type {
   ModelCapabilities,
   ModelMetadata,
   ModelRateLimits,
-  ModelStatus,
   ServingEndpointSummary,
 } from "@dbx-tools/shared-model/contracts";
 
@@ -31,7 +29,6 @@ import {
   type ModelCapabilityCatalogue,
   type ModelRateLimitsSnapshot,
   type ReasoningModelsSnapshot,
-  type RetiredModelsSnapshot,
 } from "./_metadata-contract.ts";
 import {
   parseModelCapabilities,
@@ -39,17 +36,22 @@ import {
   parseReasoningModels,
   parseRetiredModels,
 } from "./_metadata-generator.ts";
+import {
+  COMMITTED_RETIRED_MODELS,
+  modelStatusFor,
+  replaceRetiredModelNames,
+  RETIRED_MODELS_GENERATED_AT,
+} from "./_retirement.ts";
+import capabilitiesSnapshotJson from "./generated/model-capabilities.json" with { type: "json" };
+import rateLimitsSnapshotJson from "./generated/model-rate-limits.json" with { type: "json" };
+import reasoningSnapshotJson from "./generated/model-reasoning.json" with { type: "json" };
 import {
   createMetadataCache,
   mergePreferFreshList,
   mergePreferFreshRecord,
   type MetadataCache,
 } from "./metadata-cache.ts";
-import capabilitiesSnapshotJson from "./generated/model-capabilities.json" with { type: "json" };
-import rateLimitsSnapshotJson from "./generated/model-rate-limits.json" with { type: "json" };
-import reasoningSnapshotJson from "./generated/model-reasoning.json" with { type: "json" };
-import retiredModelsSnapshotJson from "./generated/retired-models.json" with { type: "json" };
-import { modelSearchQuery } from "./policy.ts";
+import { inheritsNativeWebSearch, isFoundationModelIdentity, modelSearchQuery } from "./policy.ts";
 import {
   defaultReasoningLevels,
   documentedReasoningLevels,
@@ -69,16 +71,11 @@ export {
   WEB_SEARCH_MODELS_URL,
 };
 
-const logger = log.logger("model/metadata");
-
-const retiredModelsSnapshot = retiredModelsSnapshotJson as RetiredModelsSnapshot;
 const capabilitiesSnapshot = capabilitiesSnapshotJson as ModelCapabilitiesSnapshot;
 const rateLimitsSnapshot = rateLimitsSnapshotJson as ModelRateLimitsSnapshot;
 const reasoningSnapshot = reasoningSnapshotJson as ReasoningModelsSnapshot;
 
 interface MetadataIndex {
-  readonly retiredNames: readonly string[];
-  readonly retiredKeys: ReadonlySet<string>;
   readonly capabilities: {
     readonly [Key in keyof ModelCapabilityCatalogue]: ReadonlySet<string>;
   };
@@ -93,7 +90,7 @@ const USER_AGENT = "dbx-tools-model-metadata/1";
 
 const retiredCache = createMetadataCache<readonly string[]>({
   key: "retired-models",
-  fallback: retiredModelsSnapshot.models,
+  fallback: COMMITTED_RETIRED_MODELS,
   load: async () => parseRetiredModels(await loadPage(RETIRED_MODELS_URL), nowSeconds()).models,
   merge: mergePreferFreshList,
 });
@@ -148,7 +145,9 @@ const reasoningDocsCache = createMetadataCache<Readonly<Record<string, readonly
   merge: mergePreferFreshRecord,
 });
 
-const learnedReasoningCache = createMetadataCache<Readonly<Record<string, readonly ReasoningLevel[]>>>({
+const learnedReasoningCache = createMetadataCache<
+  Readonly<Record<string, readonly ReasoningLevel[]>>
+>({
   key: "learned-reasoning",
   fallback: {},
   merge: mergePreferFreshRecord,
@@ -156,11 +155,13 @@ const learnedReasoningCache = createMetadataCache<Readonly<Record<string, readon
 
 let liveIndex: MetadataIndex | undefined;
 
-const metadataIndex = functionUtils.memoize<MetadataIndex>(() => liveIndex ?? buildIndexFromCommitted());
+const metadataIndex = functionUtils.memoize<MetadataIndex>(
+  () => liveIndex ?? buildIndexFromCommitted(),
+);
 
 function buildIndexFromCommitted(): MetadataIndex {
   return buildIndex({
-    retiredNames: retiredModelsSnapshot.models,
+    retiredNames: COMMITTED_RETIRED_MODELS,
     capabilities: capabilitiesSnapshot.capabilities,
     rateLimits: rateLimitsSnapshot.catalogue.models,
     reasoning: reasoningSnapshot.catalogue.models,
@@ -175,9 +176,8 @@ function buildIndex(input: {
   readonly reasoning: Readonly<Record<string, readonly string[]>>;
   readonly learnedReasoning: Readonly<Record<string, readonly ReasoningLevel[]>>;
 }): MetadataIndex {
+  replaceRetiredModelNames(input.retiredNames);
   return {
-    retiredNames: Object.freeze([...input.retiredNames]),
-    retiredKeys: new Set(input.retiredNames.map(retiredModelKey).filter(Boolean)),
     capabilities: {
       responses: new Set(input.capabilities.responses),
       imageInput: new Set(input.capabilities.imageInput),
@@ -228,13 +228,15 @@ let refreshInflight: Promise<MetadataIndex> | undefined;
 export async function refreshModelMetadata(): Promise<MetadataIndex> {
   if (refreshInflight) return refreshInflight;
   refreshInflight = (async () => {
-    const [retiredNames, capabilities, rateLimits, reasoning, learnedReasoning] = await Promise.all([
-      retiredCache.get(),
-      capabilitiesCache.get(),
-      rateLimitsCache.get(),
-      reasoningDocsCache.get(),
-      learnedReasoningCache.get(),
-    ]);
+    const [retiredNames, capabilities, rateLimits, reasoning, learnedReasoning] = await Promise.all(
+      [
+        retiredCache.get(),
+        capabilitiesCache.get(),
+        rateLimitsCache.get(),
+        reasoningDocsCache.get(),
+        learnedReasoningCache.get(),
+      ],
+    );
     liveIndex = buildIndex({
       retiredNames,
       capabilities,
@@ -249,14 +251,10 @@ export async function refreshModelMetadata(): Promise<MetadataIndex> {
   return refreshInflight;
 }
 
-void hydrateModelMetadata().catch((error) => {
-  logger.warn("metadata cache hydrate failed; using committed snapshots", { error });
-});
-
 /** Load cacache / memory entries without forcing a network refresh. */
 export async function hydrateModelMetadata(): Promise<MetadataIndex> {
   const [retiredNames, capabilities, rateLimits, reasoning, learnedReasoning] = await Promise.all([
-    peekOrFallback(retiredCache, retiredModelsSnapshot.models),
+    peekOrFallback(retiredCache, COMMITTED_RETIRED_MODELS),
     peekOrFallback(capabilitiesCache, capabilitiesSnapshot.capabilities),
     peekOrFallback(rateLimitsCache, rateLimitsSnapshot.catalogue.models),
     peekOrFallback(reasoningDocsCache, reasoningSnapshot.catalogue.models),
@@ -283,10 +281,7 @@ export function modelMetadataCachePath(): string {
   return retiredCache.path;
 }
 
-/** Return the committed retired-model names. The array is cached and immutable. */
-export function retiredModelNames(): readonly string[] {
-  return metadataIndex().retiredNames;
-}
+export { modelStatusFor, retiredModelNames } from "./_retirement.ts";
 
 /** Return the committed reasoning-effort catalogue. Cached per process. */
 export function reasoningModelCatalogue(): ReasoningModelCatalogue {
@@ -338,32 +333,23 @@ export async function learnReasoningLevelsFromError(
   return rememberReasoningLevels(model, parseReasoningLevels(body));
 }
 
-/** Resolve whether any supplied identity is listed in the retirement snapshot. */
-export function modelStatusFor(
-  ...models: readonly (string | ServingEndpointSummary)[]
-): ModelStatus {
-  const retired = metadataIndex().retiredKeys;
-  const deprecated = models
-    .flatMap((model) => modelIdentities(model))
-    .some((identity) => {
-      const candidate = retiredModelKey(identity);
-      for (const key of retired) {
-        if (candidate === key || candidate.startsWith(`${key}-`)) return true;
-      }
-      return false;
-    });
-  return { deprecated };
-}
-
 /** Resolve documented model capabilities from a name or endpoint summary. */
 export function modelCapabilitiesFor(model: string | ServingEndpointSummary): ModelCapabilities {
   const capabilities = metadataIndex().capabilities;
-  const keys = modelIdentities(model, false).flatMap((identity) => modelKey(identity) ?? []);
+  const identities = modelIdentities(model, false);
+  const keys = identities.flatMap((identity) => modelKey(identity) ?? []);
   return {
     responses: keys.some((key) => capabilities.responses.has(key)),
     imageInput: keys.some((key) => capabilities.imageInput.has(key)),
     applyPatch: keys.some((key) => capabilities.applyPatch.has(key)),
-    webSearch: keys.some((key) => capabilities.webSearch.has(key)),
+    // Version inheritance only applies to hosted foundation identities.
+    webSearch:
+      keys.some((key) => capabilities.webSearch.has(key)) ||
+      identities.some(
+        (identity) =>
+          isFoundationModelIdentity(identity) &&
+          inheritsNativeWebSearch(identity, capabilities.webSearch),
+      ),
   };
 }
 
@@ -388,9 +374,7 @@ export function modelRateLimitsFor(
  * Does not parse error bodies; callers should use {@link parseReasoningLevels}
  * and then {@link rememberReasoningLevels}.
  */
-export function modelReasoningLevelsFor(
-  model: string | ServingEndpointSummary,
-): ReasoningLevel[] {
+export function modelReasoningLevelsFor(model: string | ServingEndpointSummary): ReasoningLevel[] {
   const index = metadataIndex();
   for (const identity of modelIdentities(model)) {
     const learned = documentedReasoningLevels(identity, index.learnedReasoning);
@@ -400,8 +384,7 @@ export function modelReasoningLevelsFor(
     const documented = documentedReasoningLevels(identity, index.reasoning);
     if (documented?.length) return documented;
   }
-  const primary =
-    typeof model === "string" ? model : (model.modelServiceName ?? model.name);
+  const primary = typeof model === "string" ? model : (model.modelServiceName ?? model.name);
   return defaultReasoningLevels(primary);
 }
 
@@ -423,7 +406,7 @@ export function modelMetadataGeneratedAt(): Readonly<{
   reasoning: number;
 }> {
   return {
-    retiredModels: retiredModelsSnapshot.generatedAt,
+    retiredModels: RETIRED_MODELS_GENERATED_AT,
     capabilities: capabilitiesSnapshot.generatedAt,
     rateLimits: rateLimitsSnapshot.generatedAt,
     reasoning: reasoningSnapshot.generatedAt,
@@ -447,23 +430,6 @@ function modelKey(value: string): string | undefined {
   return modelSearchQuery(value)?.replaceAll(" ", "-");
 }
 
-const RETIRED_MODEL_PREFIXES = new Set([
-  "ai",
-  "anthropic",
-  "databricks",
-  "dbx",
-  "google",
-  "meta",
-  "openai",
-  "system",
-]);
-
-function retiredModelKey(value: string): string {
-  const tokens = value.toLowerCase().match(/[a-z0-9]+/g) ?? [];
-  while (tokens[0] && RETIRED_MODEL_PREFIXES.has(tokens[0])) tokens.shift();
-  return tokens.join("-");
-}
-
 async function loadPage(url: string): Promise<string> {
   const response = await fetch(url, {
     headers: { "user-agent": USER_AGENT },

package/src/model-client.ts

@@ -3,16 +3,17 @@
  *
  * This is the portable entry point used by generated Python bindings. It keeps
  * authentication, endpoint discovery, caching, normalization, ranking, route
- * selection, and published metadata in Node while exposing one small client.
+ * selection, route construction, and published metadata in Node while exposing
+ * one small client.
  *
  * @module
  */
 import {
-  client as authClient,
-  profile as authProfile,
+  createAuthClient,
   type AuthClient,
   type DatabricksAuthDependencies,
-} from "@dbx-tools/auth";
+} from "@dbx-tools/auth/client";
+import { listProfiles as listAuthProfiles } from "@dbx-tools/auth/profile";
 import type { DatabricksProfileSummary } from "@dbx-tools/shared-auth";
 import * as log from "@dbx-tools/shared-core/log";
 import * as object from "@dbx-tools/shared-core/object";
@@ -29,7 +30,7 @@ import {
 import { normalizeEndpoints } from "./_ranking.ts";
 import { lookupModels, resolveModel } from "./_selection.ts";
 import { chatCompletionsUrl, invocationsUrl, responsesUpstreamUrl } from "./invoke.ts";
-import { modelMetadataFor } from "./metadata.ts";
+import { hydrateModelMetadata, modelMetadataFor } from "./metadata.ts";
 import { modelServingApi } from "./policy.ts";
 
 const logger = log.logger("model/client");
@@ -49,6 +50,8 @@ export interface ModelClientOptions {
   auth?: ModelAuthOptions;
   /** In-memory endpoint catalogue TTL in milliseconds. */
   cacheTtlMs?: number;
+  /** Hydrate Node-only metadata caches before constructing the client. */
+  hydrateMetadata?: boolean;
 }
 
 /** Secret-free runtime identity and cache configuration. */
@@ -246,15 +249,16 @@ class DefaultModelClient implements ModelClient {
 /** Create an authentication-aware Databricks model client. */
 export async function createModelClient(options: ModelClientOptions = {}): Promise<ModelClient> {
   const cacheTtlMs = validateCacheTtl(options.cacheTtlMs);
+  if (options.hydrateMetadata ?? true) await hydrateModelMetadata();
   return new DefaultModelClient(
-    new AuthenticatedModelClient(await authClient.createAuthClient(options.auth), globalThis.fetch),
+    new AuthenticatedModelClient(await createAuthClient(options.auth), globalThis.fetch),
     cacheTtlMs,
   );
 }
 
 /** List configured Databricks profiles outside the model client facade. */
 export function listProfiles(refresh = false): DatabricksProfileSummary[] {
-  return authProfile.listProfiles({ refresh });
+  return listAuthProfiles({ refresh });
 }
 
 /** @internal Construct a model client around a test or host-owned Databricks client. */
@@ -270,9 +274,10 @@ export async function createModelClientWithDependencies(
   options: ModelClientOptions,
   dependencies: DatabricksAuthDependencies,
 ): Promise<ModelClient> {
+  if (options.hydrateMetadata ?? true) await hydrateModelMetadata();
   return new DefaultModelClient(
     new AuthenticatedModelClient(
-      await authClient.createAuthClient(options.auth, dependencies),
+      await createAuthClient(options.auth, dependencies),
       dependencies.fetch ?? globalThis.fetch,
     ),
     validateCacheTtl(options.cacheTtlMs),