@dbx-tools/model 0.9.32 → 0.9.37

package/src/_ranking.ts

@@ -52,15 +52,28 @@ export function rankEndpoints(
   const requestedClass = options.modelClass ?? query.modelClass;
   const eligible = requestedClass ? classesAtOrBelow(requestedClass) : CHAT_CLASS_ORDER;
   const candidates: RankedModel[] = [];
-  for (const modelClass of eligible) {
-    for (const endpoint of classified[modelClass]) {
+  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 (query.requiresTools && !endpointCapabilities(endpoint).tools) continue;
-      candidates.push({ endpoint, modelClass });
+      const capabilities = endpointCapabilities(endpoint);
+      if (!capabilities.chat || (query.requiresTools && !capabilities.tools)) continue;
+      candidates.push({
+        endpoint,
+        modelClass: classByName.get(endpoint.name) ?? ModelClass.ChatBalanced,
+      });
+    }
+  } else {
+    for (const modelClass of eligible) {
+      for (const endpoint of classified[modelClass]) {
+        if (!options.includeDeprecated && endpoint.status?.deprecated) continue;
+        if (query.requiresTools && !endpointCapabilities(endpoint).tools) continue;
+        candidates.push({ endpoint, modelClass });
+      }
     }
   }
 
-  const search = query.search?.trim();
   let ranked = candidates;
   if (search) {
     const exact = candidates.find((candidate) => candidate.endpoint.name === search);
@@ -147,11 +160,19 @@ export function normalizeEndpoints(endpoints: readonly unknown[]): ServingEndpoi
           stringValue(record(entity.foundation_model).name) ?? stringValue(entity.entity_name),
       )
       .find(Boolean);
-    const family = identities.map(modelFamily).find(Boolean);
+    const foundationModels = entities.map((entity) => record(entity.foundation_model));
+    const family =
+      foundationModels.map((model) => stringValue(model.model_class)).find(Boolean) ??
+      identities.map(modelFamily).find(Boolean);
     const reasoningEfforts =
       identities.map(modelReasoningEfforts).sort((left, right) => right.length - left.length)[0] ??
       [];
     const profile = entities.map(modelProfile).find(Boolean);
+    const capabilitiesRecord = record(endpoint.capabilities);
+    const foundationDescription = foundationModels
+      .map((model) => stringValue(model.description))
+      .find(Boolean);
+    const description = stringValue(endpoint.description) ?? foundationDescription;
     const summary: ServingEndpointSummary = {
       name,
       displayName: toModelDisplayName(name, providedDisplayName(endpoint, entities)),
@@ -160,10 +181,9 @@ export function normalizeEndpoints(endpoints: readonly unknown[]): ServingEndpoi
       ...(stringValue(record(endpoint.state).ready)
         ? { state: stringValue(record(endpoint.state).ready) }
         : {}),
-      ...(stringValue(endpoint.description)
-        ? { description: stringValue(endpoint.description) }
-        : {}),
-      supportsTools: identities.some(supportsToolsByFamily),
+      ...(description ? { description } : {}),
+      supportsTools:
+        booleanValue(capabilitiesRecord.function_calling) ?? identities.some(supportsToolsByFamily),
       ...(profile ? { profile } : {}),
       serviceNames: Object.assign({}, ...identities.map(modelServiceNames)),
       ...(modelServiceName ? { modelServiceName } : {}),
@@ -236,7 +256,12 @@ function providedDisplayName(
     const value = stringValue(tag.value);
     if (value) return value;
   }
-  return entities.map((entity) => stringValue(record(entity.external_model).name)).find(Boolean);
+  return (
+    entities
+      .map((entity) => stringValue(record(entity.foundation_model).display_name))
+      .find(Boolean) ??
+    entities.map((entity) => stringValue(record(entity.external_model).name)).find(Boolean)
+  );
 }
 
 function record(value: unknown): Record<string, unknown> {
@@ -258,3 +283,7 @@ function stringValue(value: unknown): string | undefined {
 function finiteNumber(value: unknown): number | undefined {
   return typeof value === "number" && Number.isFinite(value) ? value : undefined;
 }
+
+function booleanValue(value: unknown): boolean | undefined {
+  return typeof value === "boolean" ? value : undefined;
+}

package/src/_selection.ts

@@ -5,36 +5,21 @@
  */
 import * as object from "@dbx-tools/shared-core/object";
 import type {
-  ModelClass,
   ModelQuery,
   RankedModel,
+  ResolvedModel,
+  ResolvedModelSelection,
+  ResolveModelInput,
+  ResolveModelOptions,
   ServingEndpointSummary,
 } from "@dbx-tools/shared-model/contracts";
 
 import { rankEndpoints } from "./_ranking.ts";
 import { FALLBACK_MODEL_IDS, modelsForClass } from "./fallback.ts";
-import type { ResolvedModel, ResolveModelOptions } from "./model-catalog.ts";
 import { endpointSupportsTools } from "./policy.ts";
 
 const DEFAULT_MODEL_FAMILY_SEARCH = "gpt";
 
-/** Caller intent passed to {@link resolveModel}. */
-export interface ResolveModelInput {
-  explicit?: string;
-  fuzzy?: boolean;
-  threshold?: number;
-  requiresTools?: boolean;
-  modelClass?: ModelClass;
-  fallbacks?: readonly string[];
-  liveOnly?: boolean;
-}
-
-/** Outcome of {@link resolveModel}: the chosen id plus how it was reached. */
-export interface ResolvedModelSelection {
-  modelId: string;
-  source: "explicit" | "fuzzy-match" | "class" | "fallback";
-}
-
 /** Rank a catalogue against a model query, best-first. */
 export function lookupModels(
   endpoints: readonly ServingEndpointSummary[],

package/src/classify.ts

@@ -27,6 +27,8 @@
  */
 
 import {
+  type EndpointCapabilities,
+  type FamilyClass,
   ModelClass as ModelClassValues,
   type ModelClass as ModelClassType,
   type ServingEndpointSummary,
@@ -41,16 +43,6 @@ const CHAT_TASK = "llm/v1/chat";
 /** Task hint Databricks stamps on embedding endpoints. */
 const EMBEDDING_TASK = "llm/v1/embeddings";
 
-/** What an endpoint can be asked to do, as derived by {@link endpointCapabilities}. */
-export interface EndpointCapabilities {
-  /** OpenAI chat/completions + Responses: the surface a chat agent needs. */
-  chat: boolean;
-  /** Embedding (vector) endpoint. */
-  embedding: boolean;
-  /** Complete function-tool round-trip (call plus function_call_output replay). */
-  tools: boolean;
-}
-
 /**
  * Provider families verified against Databricks Responses/Open Responses with
  * both a forced function call and a stateless `function_call_output` replay.
@@ -92,14 +84,6 @@ export function endpointCapabilities(endpoint: ServingEndpointSummary): Endpoint
   return { chat, embedding, tools };
 }
 
-/** 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

package/src/generated/model-reasoning.json

@@ -0,0 +1,147 @@
+{
+  "generatedAt": 1791233726,
+  "catalogue": {
+    "models": {
+      "claude-5-1-fable": [
+        "low",
+        "medium",
+        "high",
+        "extra-high",
+        "max"
+      ],
+      "claude-5-5-opus": [
+        "low",
+        "medium",
+        "high",
+        "extra-high",
+        "max"
+      ],
+      "deepseek-4-1-flash": [
+        "low",
+        "high",
+        "extra-high",
+        "max"
+      ],
+      "deepseek-4-flash-0731": [
+        "low",
+        "high",
+        "max"
+      ],
+      "deepseek-4-pro-0813": [
+        "low",
+        "high",
+        "max"
+      ],
+      "gemini-3-1-flash-lite": [
+        "low",
+        "medium",
+        "high"
+      ],
+      "gemini-3-1-pro": [
+        "low",
+        "medium",
+        "high"
+      ],
+      "gemini-3-5-flash": [
+        "low",
+        "medium",
+        "high"
+      ],
+      "gemini-3-5-flash-lite": [
+        "low",
+        "medium",
+        "high"
+      ],
+      "gemini-3-6-flash": [
+        "low",
+        "medium",
+        "high"
+      ],
+      "gemini-3-7-flash": [
+        "low",
+        "medium",
+        "high"
+      ],
+      "gemini-3-8-flash": [
+        "low",
+        "medium",
+        "high"
+      ],
+      "gemini-3-flash": [
+        "low",
+        "medium",
+        "high"
+      ],
+      "glm-5-2": [
+        "high",
+        "max"
+      ],
+      "glm-5-3": [
+        "low",
+        "high",
+        "max"
+      ],
+      "glm-5-3-flash": [
+        "low",
+        "high",
+        "max"
+      ],
+      "gpt-6-1-sol": [
+        "low",
+        "medium",
+        "high",
+        "extra-high",
+        "max"
+      ],
+      "gpt-6-astra": [
+        "low",
+        "medium",
+        "high",
+        "extra-high",
+        "max"
+      ],
+      "gpt-6-luna": [
+        "low",
+        "medium",
+        "high",
+        "extra-high",
+        "max"
+      ],
+      "gpt-6-sol": [
+        "low",
+        "medium",
+        "high",
+        "extra-high",
+        "max"
+      ],
+      "gpt-oss-120b": [
+        "low",
+        "medium",
+        "high"
+      ],
+      "gpt-oss-20b": [
+        "low",
+        "medium",
+        "high"
+      ],
+      "grok-4-6": [
+        "low",
+        "medium",
+        "high",
+        "extra-high"
+      ],
+      "inkling": [
+        "low",
+        "medium",
+        "high",
+        "extra-high",
+        "max"
+      ],
+      "kimi-3": [
+        "low",
+        "high",
+        "max"
+      ]
+    }
+  }
+}

package/src/invoke.ts

@@ -48,6 +48,12 @@ export const OPEN_RESPONSES_PATH = "serving-endpoints/open-responses";
  */
 export const CHAT_COMPLETIONS_PATH = "serving-endpoints/chat/completions";
 
+/** Unity Gateway OpenAI Responses path used by Codex-compatible model services. */
+export const AI_GATEWAY_CODEX_RESPONSES_PATH = "ai-gateway/codex/v1/responses";
+
+/** Workspace Anthropic Messages path for native Claude requests. */
+export const ANTHROPIC_MESSAGES_PATH = "serving-endpoints/anthropic/v1/messages";
+
 /**
  * The OpenAI-compatible chat-completions invocations URL for an endpoint id.
  *
@@ -77,6 +83,16 @@ export function chatCompletionsUrl(host: string): string {
   return new URL(CHAT_COMPLETIONS_PATH, host).toString();
 }
 
+/** Unity Gateway Codex Responses URL (`POST`, model service in the body). */
+export function aiGatewayCodexResponsesUrl(host: string): string {
+  return new URL(AI_GATEWAY_CODEX_RESPONSES_PATH, host).toString();
+}
+
+/** Workspace Anthropic Messages URL (`POST`, model in the body). */
+export function anthropicMessagesUrl(host: string): string {
+  return new URL(ANTHROPIC_MESSAGES_PATH, host).toString();
+}
+
 /**
  * True when the endpoint is known to reject Chat Completions `/invocations`
  * and require the Responses API (Codex models today). Callers should route

package/src/metadata-cache.ts

@@ -0,0 +1,322 @@
+/**
+ * Agnostic daily metadata cache on {@link https://www.npmjs.com/package/cacache | cacache}.
+ *
+ * Uses cacache's built-in memory memoization (`memoize: true` on put; gets read
+ * the in-memory layer by default) with content-addressed disk under
+ * `env-paths("dbx-tools").cache/model-gateway/<version>/`. Disk persistence is
+ * disabled inside a Databricks App ({@link environmentUtils.isDatabricksAppEnv});
+ * those processes keep a process-local Map only.
+ *
+ * Each cache owns a key, hard-coded fallback, optional network loader, and a
+ * merger that combines fresh / previous / fallback values. Freshness is the
+ * envelope `refreshedAt` window (default one day), not cacache's short LRU TTL.
+ *
+ * @module
+ */
+
+import { resolve } from "node:path";
+
+import * as environmentUtils from "@dbx-tools/shared-core/environment-utils";
+import * as log from "@dbx-tools/shared-core/log";
+import cacache from "cacache";
+import envPaths from "env-paths";
+
+import { MODEL_METADATA_TTL_MS } from "./_metadata-contract.ts";
+
+const logger = log.logger("model/metadata-cache");
+
+interface PackageIdentity {
+  readonly identifier: string;
+  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;
+}
+
+/** Envelope stored as JSON bytes in cacache for every key. */
+export interface MetadataCacheRecord<T> {
+  readonly refreshedAt: number;
+  readonly value: T;
+}
+
+/** Factory inputs for one named metadata cache. */
+export interface MetadataCacheOptions<T> {
+  /** Stable cacache key. */
+  readonly key: string;
+  /** Hard-coded / committed baseline used when store and load both miss. */
+  readonly fallback: T;
+  /**
+   * Refresh source. When omitted the cache only serves store + fallback and
+   * {@link MetadataCache.update} mutations (for example error-learned values).
+   */
+  readonly load?: () => Promise<T>;
+  /** Combine a fresh load, prior store value, and the hard-coded fallback. */
+  readonly merge: (input: MetadataCacheMergeInput<T>) => T;
+  /** Freshness window; defaults to {@link MODEL_METADATA_TTL_MS} (one day). */
+  readonly ttlMs?: number;
+  /** Package version segment in the cache path. Defaults to this package. */
+  readonly version?: string;
+  /** Override the cacache root directory (tests). */
+  readonly cacheDir?: string;
+  /**
+   * Force disk on/off. Defaults to off inside Databricks Apps, on otherwise.
+   */
+  readonly disk?: boolean;
+  /** Clock override for tests. */
+  readonly now?: () => number;
+}
+
+/** Arguments passed to a cache merger. */
+export interface MetadataCacheMergeInput<T> {
+  readonly fresh: T | undefined;
+  readonly previous: T | undefined;
+  readonly fallback: T;
+}
+
+/** One versioned metadata cache (cacache memory + optional disk). */
+export interface MetadataCache<T> {
+  /** Absolute cacache root for this package version (unused when disk is off). */
+  readonly path: string;
+  /** Whether cacache disk persistence is enabled for this instance. */
+  readonly diskEnabled: boolean;
+  /** Return a fresh-or-fallback value, refreshing when stale. */
+  get(): Promise<T>;
+  /** Read memory / disk without refreshing. */
+  peek(): Promise<T | undefined>;
+  /** Mutate the cached value and persist it. */
+  update(mutator: (current: T) => T): Promise<T>;
+  /** Force a refresh attempt even when the entry is still fresh. */
+  refresh(): Promise<T>;
+}
+
+const inflight = new Map<string, Promise<unknown>>();
+
+/** Default cacache root for a package version under the dbx-tools cache dir. */
+export function defaultMetadataCacheDir(version: string): string {
+  const cacheDirectory = envPaths("dbx-tools", { suffix: "" }).cache;
+  return resolve(cacheDirectory, "model-gateway", version);
+}
+
+/** Whether metadata caches should persist to disk in this process. */
+export function metadataCacheDiskEnabled(environment: NodeJS.ProcessEnv = process.env): boolean {
+  return !environmentUtils.isDatabricksAppEnv(environment);
+}
+
+/**
+ * Create one daily cache backed by cacache memoization, with optional disk.
+ */
+export function createMetadataCache<T>(options: MetadataCacheOptions<T>): MetadataCache<T> {
+  const ttlMs = options.ttlMs ?? MODEL_METADATA_TTL_MS;
+  const diskEnabled = options.disk ?? metadataCacheDiskEnabled();
+  const now = options.now ?? Date.now;
+  const pathPromise = resolveCacheDir(options);
+  let path = options.cacheDir;
+
+  const flightKey = (cachePath: string, suffix = ""): string =>
+    `${cachePath}::${options.key}${suffix}`;
+
+  /** Process-local store used when disk is off (Databricks Apps). */
+  const memoryOnly = new Map<string, MetadataCacheRecord<T>>();
+
+  const resolveValue = (input: MetadataCacheMergeInput<T>): T => options.merge(input);
+
+  const isFresh = (record: MetadataCacheRecord<T> | undefined): boolean =>
+    Boolean(record && now() - record.refreshedAt < ttlMs);
+
+  const cachePath = async (): Promise<string> => {
+    path ??= await pathPromise;
+    return path;
+  };
+
+  const readRecord = async (): Promise<MetadataCacheRecord<T> | undefined> => {
+    if (!diskEnabled) return memoryOnly.get(options.key);
+    const resolvedPath = await cachePath();
+    try {
+      // cacache reads its in-memory memo first unless memoize is false
+      const entry = await cacache.get(resolvedPath, options.key);
+      return decodeRecord<T>(entry.data);
+    } catch (error) {
+      if (isCacheMiss(error)) return undefined;
+      logger.warn("metadata cache cacache read failed", {
+        key: options.key,
+        path: resolvedPath,
+        error,
+      });
+      return undefined;
+    }
+  };
+
+  const writeRecord = async (record: MetadataCacheRecord<T>): Promise<void> => {
+    if (!diskEnabled) {
+      memoryOnly.set(options.key, record);
+      return;
+    }
+    const resolvedPath = await cachePath();
+    try {
+      await cacache.put(resolvedPath, options.key, `${JSON.stringify(record)}\n`, {
+        memoize: true,
+        metadata: { refreshedAt: record.refreshedAt },
+      });
+    } catch (error) {
+      logger.warn("metadata cache cacache write failed", {
+        key: options.key,
+        path: resolvedPath,
+        error,
+      });
+    }
+  };
+
+  const persist = async (value: T, refreshedAt = now()): Promise<T> => {
+    await writeRecord({ refreshedAt, value });
+    return value;
+  };
+
+  const refresh = async (force: boolean): Promise<T> => {
+    const resolvedPath = await cachePath();
+    return coalesce(flightKey(resolvedPath), async () => {
+      const previous = await readRecord();
+      if (!force && isFresh(previous)) {
+        return resolveValue({
+          fresh: undefined,
+          previous: previous?.value,
+          fallback: options.fallback,
+        });
+      }
+
+      let fresh: T | undefined;
+      if (options.load) {
+        try {
+          fresh = await options.load();
+        } catch (error) {
+          logger.warn("metadata cache refresh failed; keeping last known good", {
+            key: options.key,
+            error,
+            path: resolvedPath,
+            diskEnabled,
+          });
+        }
+      }
+
+      const value = resolveValue({
+        fresh,
+        previous: previous?.value,
+        fallback: options.fallback,
+      });
+      if (fresh !== undefined || !previous) {
+        await persist(value);
+      }
+      return value;
+    });
+  };
+
+  return {
+    get path() {
+      if (!path) {
+        throw new Error("metadata cache path is not resolved until the first cache read");
+      }
+      return path;
+    },
+    diskEnabled,
+    get: () => refresh(false),
+    peek: async () => (await readRecord())?.value,
+    refresh: () => refresh(true),
+    update: async (mutator) => {
+      const resolvedPath = await cachePath();
+      return coalesce(flightKey(resolvedPath, ":update"), async () => {
+        const previous = await readRecord();
+        const baseline = resolveValue({
+          fresh: undefined,
+          previous: previous?.value,
+          fallback: options.fallback,
+        });
+        return persist(mutator(baseline));
+      });
+    },
+  };
+}
+
+async function resolveCacheDir(options: {
+  readonly cacheDir?: string;
+  readonly version?: string;
+}): Promise<string> {
+  if (options.cacheDir) return options.cacheDir;
+  const version = options.version ?? (await packageIdentity()).version;
+  return defaultMetadataCacheDir(version);
+}
+
+/** Prefer a non-empty fresh array, else previous, else fallback. */
+export function mergePreferFreshList<T>(input: MetadataCacheMergeInput<readonly T[]>): T[] {
+  if (input.fresh && input.fresh.length > 0) return [...input.fresh];
+  if (input.previous && input.previous.length > 0) return [...input.previous];
+  return [...input.fallback];
+}
+
+/**
+ * Shallow-merge record catalogues: fallback, then previous, then fresh keys.
+ * Fresh values win per key.
+ */
+export function mergePreferFreshRecord<T>(
+  input: MetadataCacheMergeInput<Readonly<Record<string, T>>>,
+): Record<string, T> {
+  return {
+    ...input.fallback,
+    ...(input.previous ?? {}),
+    ...(input.fresh ?? {}),
+  };
+}
+
+/** Test helper: wipe a cacache root and clear cacache memoization. */
+export async function resetMetadataCacheDir(cacheDir: string): Promise<void> {
+  try {
+    await cacache.rm.all(cacheDir);
+  } catch {
+    // empty / missing cache is fine
+  }
+  cacache.clearMemoized();
+  for (const key of [...inflight.keys()]) {
+    if (key.startsWith(`${cacheDir}::`)) inflight.delete(key);
+  }
+}
+
+function coalesce<T>(key: string, work: () => Promise<T>): Promise<T> {
+  const existing = inflight.get(key);
+  if (existing) return existing as Promise<T>;
+  const pending = work().finally(() => {
+    if (inflight.get(key) === pending) inflight.delete(key);
+  });
+  inflight.set(key, pending);
+  return pending;
+}
+
+function decodeRecord<T>(data: Buffer): MetadataCacheRecord<T> | undefined {
+  try {
+    const parsed = JSON.parse(data.toString("utf8")) as unknown;
+    if (
+      !parsed ||
+      typeof parsed !== "object" ||
+      typeof (parsed as MetadataCacheRecord<T>).refreshedAt !== "number"
+    ) {
+      return undefined;
+    }
+    return parsed as MetadataCacheRecord<T>;
+  } catch {
+    return undefined;
+  }
+}
+
+function isCacheMiss(error: unknown): boolean {
+  return Boolean(
+    error &&
+    typeof error === "object" &&
+    "code" in error &&
+    (error as { code?: string }).code === "ENOENT",
+  );
+}
+