@dbx-tools/model 0.9.32 → 0.9.37

package/src/metadata.ts

@@ -1,66 +1,80 @@
 /**
- * Build-generated Databricks model retirement, capability, and rate-limit metadata.
+ * Build-generated Databricks model retirement, capability, rate-limit, and
+ * reasoning-effort metadata, plus a daily write-through cache for refreshed
+ * docs and error-learned reasoning ladders.
  *
- * The committed snapshots are refreshed by `bun run model:metadata`. Runtime
- * lookups build their normalized sets and maps once per process and perform no
- * documentation network requests.
+ * Committed snapshots seed every process. {@link refreshModelMetadata} pulls
+ * documentation through {@link createMetadataCache} (cacache memoize + disk) and
+ * rebuilds the in-memory index. Error-learned efforts use the same store via
+ * {@link rememberReasoningLevels}. Disk writes are skipped in Databricks Apps.
  *
  * @module
  */
 import * as functionUtils from "@dbx-tools/shared-core/function-utils";
-import type { ModelStatus, ServingEndpointSummary } from "@dbx-tools/shared-model/contracts";
+import * as log from "@dbx-tools/shared-core/log";
+import type {
+  ModelCapabilities,
+  ModelMetadata,
+  ModelRateLimits,
+  ModelStatus,
+  ServingEndpointSummary,
+} from "@dbx-tools/shared-model/contracts";
 
-import capabilitiesSnapshotJson from "./generated/model-capabilities.json" with { type: "json" };
-import rateLimitsSnapshotJson from "./generated/model-rate-limits.json" with { type: "json" };
-import retiredModelsSnapshotJson from "./generated/retired-models.json" with { type: "json" };
 import {
   MODEL_METADATA_TTL_MS,
   MODEL_RATE_LIMITS_URL,
   OPENAI_RESPONSES_MODELS_URL,
+  QUERY_REASON_MODELS_URL,
   RETIRED_MODELS_URL,
   WEB_SEARCH_MODELS_URL,
   type ModelCapabilitiesSnapshot,
   type ModelCapabilityCatalogue,
-  type ModelRateLimits,
   type ModelRateLimitsSnapshot,
+  type ReasoningModelsSnapshot,
   type RetiredModelsSnapshot,
 } from "./_metadata-contract.ts";
+import {
+  parseModelCapabilities,
+  parseModelRateLimits,
+  parseReasoningModels,
+  parseRetiredModels,
+} from "./_metadata-generator.ts";
+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 {
+  defaultReasoningLevels,
+  documentedReasoningLevels,
+  parseReasoning,
+  parseReasoningLevels,
+  type ReasoningLevel,
+  type ReasoningModelCatalogue,
+  uniqueReasoningLevels,
+} from "./reasoning-translation.ts";
 
 export {
   MODEL_METADATA_TTL_MS,
   MODEL_RATE_LIMITS_URL,
   OPENAI_RESPONSES_MODELS_URL,
+  QUERY_REASON_MODELS_URL,
   RETIRED_MODELS_URL,
   WEB_SEARCH_MODELS_URL,
 };
-export type {
-  ModelCapabilitiesSnapshot,
-  ModelCapabilityCatalogue,
-  ModelRateLimitCatalogue,
-  ModelRateLimits,
-  ModelRateLimitsSnapshot,
-  RetiredModelsSnapshot,
-} from "./_metadata-contract.ts";
+
+const logger = log.logger("model/metadata");
 
 const retiredModelsSnapshot = retiredModelsSnapshotJson as RetiredModelsSnapshot;
 const capabilitiesSnapshot = capabilitiesSnapshotJson as ModelCapabilitiesSnapshot;
 const rateLimitsSnapshot = rateLimitsSnapshotJson as ModelRateLimitsSnapshot;
-
-/** Documented capabilities resolved for one model identity. */
-export interface ModelCapabilities {
-  readonly responses: boolean;
-  readonly imageInput: boolean;
-  readonly applyPatch: boolean;
-  readonly webSearch: boolean;
-}
-
-/** Combined build-generated metadata resolved for one model identity. */
-export interface ModelMetadata {
-  readonly status: ModelStatus;
-  readonly capabilities: ModelCapabilities;
-  readonly rateLimits?: ModelRateLimits;
-}
+const reasoningSnapshot = reasoningSnapshotJson as ReasoningModelsSnapshot;
 
 interface MetadataIndex {
   readonly retiredNames: readonly string[];
@@ -69,25 +83,261 @@ interface MetadataIndex {
     readonly [Key in keyof ModelCapabilityCatalogue]: ReadonlySet<string>;
   };
   readonly rateLimits: ReadonlyMap<string, ModelRateLimits>;
+  readonly reasoning: ReasoningModelCatalogue;
+  readonly learnedReasoning: ReasoningModelCatalogue;
 }
 
-const metadataIndex = functionUtils.memoize<MetadataIndex>(() => ({
-  retiredNames: Object.freeze([...retiredModelsSnapshot.models]),
-  retiredKeys: new Set(retiredModelsSnapshot.models.map(retiredModelKey).filter(Boolean)),
-  capabilities: {
-    responses: new Set(capabilitiesSnapshot.capabilities.responses),
-    imageInput: new Set(capabilitiesSnapshot.capabilities.imageInput),
-    applyPatch: new Set(capabilitiesSnapshot.capabilities.applyPatch),
-    webSearch: new Set(capabilitiesSnapshot.capabilities.webSearch),
+type CapabilitySets = ModelCapabilityCatalogue;
+
+const USER_AGENT = "dbx-tools-model-metadata/1";
+
+const retiredCache = createMetadataCache<readonly string[]>({
+  key: "retired-models",
+  fallback: retiredModelsSnapshot.models,
+  load: async () => parseRetiredModels(await loadPage(RETIRED_MODELS_URL), nowSeconds()).models,
+  merge: mergePreferFreshList,
+});
+
+const capabilitiesCache = createMetadataCache<CapabilitySets>({
+  key: "model-capabilities",
+  fallback: capabilitiesSnapshot.capabilities,
+  load: async () => {
+    const [responsesHtml, webSearchHtml] = await Promise.all([
+      loadPage(OPENAI_RESPONSES_MODELS_URL),
+      loadPage(WEB_SEARCH_MODELS_URL),
+    ]);
+    return parseModelCapabilities(responsesHtml, webSearchHtml, nowSeconds()).capabilities;
   },
-  rateLimits: new Map(Object.entries(rateLimitsSnapshot.catalogue.models)),
-}));
+  merge: (input) => ({
+    responses: mergePreferFreshList({
+      fresh: input.fresh?.responses,
+      previous: input.previous?.responses,
+      fallback: input.fallback.responses,
+    }),
+    imageInput: mergePreferFreshList({
+      fresh: input.fresh?.imageInput,
+      previous: input.previous?.imageInput,
+      fallback: input.fallback.imageInput,
+    }),
+    applyPatch: mergePreferFreshList({
+      fresh: input.fresh?.applyPatch,
+      previous: input.previous?.applyPatch,
+      fallback: input.fallback.applyPatch,
+    }),
+    webSearch: mergePreferFreshList({
+      fresh: input.fresh?.webSearch,
+      previous: input.previous?.webSearch,
+      fallback: input.fallback.webSearch,
+    }),
+  }),
+});
+
+const rateLimitsCache = createMetadataCache<Readonly<Record<string, ModelRateLimits>>>({
+  key: "model-rate-limits",
+  fallback: rateLimitsSnapshot.catalogue.models,
+  load: async () =>
+    parseModelRateLimits(await loadPage(MODEL_RATE_LIMITS_URL), nowSeconds()).catalogue.models,
+  merge: mergePreferFreshRecord,
+});
+
+const reasoningDocsCache = createMetadataCache<Readonly<Record<string, readonly string[]>>>({
+  key: "model-reasoning",
+  fallback: reasoningSnapshot.catalogue.models,
+  load: async () =>
+    parseReasoningModels(await loadPage(QUERY_REASON_MODELS_URL), nowSeconds()).catalogue.models,
+  merge: mergePreferFreshRecord,
+});
+
+const learnedReasoningCache = createMetadataCache<Readonly<Record<string, readonly ReasoningLevel[]>>>({
+  key: "learned-reasoning",
+  fallback: {},
+  merge: mergePreferFreshRecord,
+});
+
+let liveIndex: MetadataIndex | undefined;
+
+const metadataIndex = functionUtils.memoize<MetadataIndex>(() => liveIndex ?? buildIndexFromCommitted());
+
+function buildIndexFromCommitted(): MetadataIndex {
+  return buildIndex({
+    retiredNames: retiredModelsSnapshot.models,
+    capabilities: capabilitiesSnapshot.capabilities,
+    rateLimits: rateLimitsSnapshot.catalogue.models,
+    reasoning: reasoningSnapshot.catalogue.models,
+    learnedReasoning: {},
+  });
+}
+
+function buildIndex(input: {
+  readonly retiredNames: readonly string[];
+  readonly capabilities: CapabilitySets;
+  readonly rateLimits: Readonly<Record<string, ModelRateLimits>>;
+  readonly reasoning: Readonly<Record<string, readonly string[]>>;
+  readonly learnedReasoning: Readonly<Record<string, readonly ReasoningLevel[]>>;
+}): MetadataIndex {
+  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),
+      applyPatch: new Set(input.capabilities.applyPatch),
+      webSearch: new Set(input.capabilities.webSearch),
+    },
+    rateLimits: new Map(Object.entries(input.rateLimits)),
+    reasoning: freezeReasoningCatalogue(input.reasoning),
+    learnedReasoning: freezeLearnedCatalogue(input.learnedReasoning),
+  };
+}
+
+function freezeReasoningCatalogue(
+  models: Readonly<Record<string, readonly string[]>>,
+): ReasoningModelCatalogue {
+  return Object.freeze(
+    Object.fromEntries(
+      Object.entries(models).map(([key, levels]) => [
+        key,
+        Object.freeze(
+          uniqueReasoningLevels(levels.flatMap((level) => parseReasoning(level) ?? [])),
+        ),
+      ]),
+    ),
+  );
+}
+
+function freezeLearnedCatalogue(
+  models: Readonly<Record<string, readonly ReasoningLevel[]>>,
+): ReasoningModelCatalogue {
+  return Object.freeze(
+    Object.fromEntries(
+      Object.entries(models).map(([key, levels]) => [
+        key,
+        Object.freeze(uniqueReasoningLevels(levels)),
+      ]),
+    ),
+  );
+}
+
+let refreshInflight: Promise<MetadataIndex> | undefined;
+
+/**
+ * Hydrate or refresh documentation + learned caches into the process index.
+ *
+ * Safe to call on gateway startup. Concurrent callers share one refresh.
+ */
+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(),
+    ]);
+    liveIndex = buildIndex({
+      retiredNames,
+      capabilities,
+      rateLimits,
+      reasoning,
+      learnedReasoning,
+    });
+    return liveIndex;
+  })().finally(() => {
+    refreshInflight = undefined;
+  });
+  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(capabilitiesCache, capabilitiesSnapshot.capabilities),
+    peekOrFallback(rateLimitsCache, rateLimitsSnapshot.catalogue.models),
+    peekOrFallback(reasoningDocsCache, reasoningSnapshot.catalogue.models),
+    peekOrFallback(learnedReasoningCache, {}),
+  ]);
+  liveIndex = buildIndex({
+    retiredNames,
+    capabilities,
+    rateLimits,
+    reasoning,
+    learnedReasoning,
+  });
+  return liveIndex;
+}
+
+async function peekOrFallback<T>(cache: MetadataCache<T>, fallback: T): Promise<T> {
+  const peeked = await cache.peek();
+  if (peeked !== undefined) return peeked;
+  return cache.get().catch(() => fallback);
+}
+
+/** Absolute cacache root used by the documentation / learned caches. */
+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;
 }
 
+/** Return the committed reasoning-effort catalogue. Cached per process. */
+export function reasoningModelCatalogue(): ReasoningModelCatalogue {
+  return metadataIndex().reasoning;
+}
+
+/** Return error-learned reasoning ladders persisted in the metadata cache. */
+export function learnedReasoningCatalogue(): ReasoningModelCatalogue {
+  return metadataIndex().learnedReasoning;
+}
+
+/**
+ * Store levels learned from an upstream error and persist them write-through.
+ *
+ * Empty lists are ignored so a failed parse cannot wipe defaults. Error bodies
+ * themselves are never stored - only the parsed ladder.
+ */
+export async function rememberReasoningLevels(
+  model: string,
+  levels: readonly ReasoningLevel[],
+): Promise<ReasoningLevel[]> {
+  const unique = uniqueReasoningLevels(levels);
+  if (unique.length === 0) return modelReasoningLevelsFor(model);
+  const key = modelKey(model);
+  if (!key) return modelReasoningLevelsFor(model);
+  const catalogue = await learnedReasoningCache.update((current) => ({
+    ...current,
+    [key]: unique,
+  }));
+  const current = metadataIndex();
+  liveIndex = {
+    ...current,
+    learnedReasoning: freezeLearnedCatalogue(catalogue),
+  };
+  return [...unique];
+}
+
+/**
+ * Parse an upstream error body and persist the supported ladder for `model`.
+ *
+ * Accepts the same nested Databricks envelopes as {@link parseReasoningLevels}.
+ * Returns the levels that were stored (or the current lookup when parse yields
+ * nothing). The raw error body is never written to disk.
+ */
+export async function learnReasoningLevelsFromError(
+  model: string,
+  body: unknown,
+): Promise<ReasoningLevel[]> {
+  return rememberReasoningLevels(model, parseReasoningLevels(body));
+}
+
 /** Resolve whether any supplied identity is listed in the retirement snapshot. */
 export function modelStatusFor(
   ...models: readonly (string | ServingEndpointSummary)[]
@@ -131,6 +381,30 @@ export function modelRateLimitsFor(
   return undefined;
 }
 
+/**
+ * Resolve reasoning levels: learned from errors, then documentation, then
+ * family defaults.
+ *
+ * Does not parse error bodies; callers should use {@link parseReasoningLevels}
+ * and then {@link rememberReasoningLevels}.
+ */
+export function modelReasoningLevelsFor(
+  model: string | ServingEndpointSummary,
+): ReasoningLevel[] {
+  const index = metadataIndex();
+  for (const identity of modelIdentities(model)) {
+    const learned = documentedReasoningLevels(identity, index.learnedReasoning);
+    if (learned?.length) return learned;
+  }
+  for (const identity of modelIdentities(model)) {
+    const documented = documentedReasoningLevels(identity, index.reasoning);
+    if (documented?.length) return documented;
+  }
+  const primary =
+    typeof model === "string" ? model : (model.modelServiceName ?? model.name);
+  return defaultReasoningLevels(primary);
+}
+
 /** Resolve retirement, capability, and rate-limit metadata together. */
 export function modelMetadataFor(model: string | ServingEndpointSummary): ModelMetadata {
   const rateLimits = modelRateLimitsFor(model);
@@ -141,16 +415,18 @@ export function modelMetadataFor(model: string | ServingEndpointSummary): ModelM
   };
 }
 
-/** Return generation timestamps for the three committed metadata snapshots. */
+/** Return generation timestamps for the committed metadata snapshots. */
 export function modelMetadataGeneratedAt(): Readonly<{
   retiredModels: number;
   capabilities: number;
   rateLimits: number;
+  reasoning: number;
 }> {
   return {
     retiredModels: retiredModelsSnapshot.generatedAt,
     capabilities: capabilitiesSnapshot.generatedAt,
     rateLimits: rateLimitsSnapshot.generatedAt,
+    reasoning: reasoningSnapshot.generatedAt,
   };
 }
 
@@ -187,3 +463,18 @@ function retiredModelKey(value: string): string {
   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 },
+    signal: AbortSignal.timeout(15_000),
+  });
+  if (!response.ok) {
+    throw new Error(`Databricks documentation returned HTTP ${response.status}: ${url}`);
+  }
+  return response.text();
+}
+
+function nowSeconds(): number {
+  return Math.floor(Date.now() / 1000);
+}

package/src/model-catalog.ts

@@ -25,7 +25,13 @@ import { createHash } from "node:crypto";
 import { CacheManager } from "@databricks/appkit";
 import { appkit } from "@dbx-tools/appkit";
 import { errorUtils, log } from "@dbx-tools/shared-core";
-import { model, type ServingEndpointSummary } from "@dbx-tools/shared-model";
+import {
+  model,
+  type ResolvedModel,
+  type ResolveModelOptions,
+  type ScoredEndpoint,
+  type ServingEndpointSummary,
+} from "@dbx-tools/shared-model";
 
 import { classifyEndpointClasses, normalizeEndpoints, rankEndpoints } from "./_ranking.ts";
 
@@ -140,9 +146,7 @@ async function fetchEndpoints(client: WorkspaceClientLike): Promise<ServingEndpo
  * classification of the whole set. Endpoints the classifier doesn't recognize
  * (custom, unscored, non-LLM) are left without a class.
  */
-function stampModelClasses(
-  summaries: readonly ServingEndpointSummary[],
-): ServingEndpointSummary[] {
+function stampModelClasses(summaries: readonly ServingEndpointSummary[]): ServingEndpointSummary[] {
   const classOf = classifyEndpointClasses(summaries);
   return summaries.map((summary) => {
     const cls = classOf.get(summary.name);
@@ -218,27 +222,6 @@ export async function clearServingEndpointsCache(
  * 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 {
-  /** Fuzzy distance threshold (0 = exact, 1 = anything). Default `0.4`. */
-  threshold?: number;
-  /** Require a model verified for a complete function-tool round-trip. */
-  requiresTools?: boolean;
-}
-
-/** A serving endpoint paired with its fuzzy-match distance for a query. */
-export interface ScoredEndpoint {
-  endpoint: ServingEndpointSummary;
-  /** Fuzzy 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`: