@dbx-tools/model 0.9.166 → 0.9.173

package/src/generated/retired-models.json

@@ -1,11 +1,13 @@
 {
-  "generatedAt": 1791144427,
+  "generatedAt": 1793283170,
   "models": [
     "Anthropic Claude 3.7 Sonnet",
     "Anthropic Claude Sonnet 4",
     "DBRX",
     "DBRX Instruct",
+    "DeepSeek V4 Flash (0731)",
     "DeepSeek V4 Pro (0813)",
+    "DeepSeek V4.1 Flash",
     "Gemini 2.5 Flash",
     "Gemini 2.5 Pro",
     "Gemini 3 Pro",

package/src/metadata-contract.ts

@@ -23,6 +23,12 @@ export const MODEL_RATE_LIMITS_URL =
 export const QUERY_REASON_MODELS_URL =
   "https://docs.databricks.com/aws/en/machine-learning/model-serving/query-reason-models";
 
+/** models.dev provider catalogue URL. */
+export const MODELS_DEV_API_URL = "https://models.dev/api.json";
+
+/** modelparams.dev normalized model-parameter catalogue URL. */
+export const MODELPARAMS_DEV_MODELS_URL = "https://modelparams.dev/api/v1/models.json";
+
 /** Build-generated retired-model snapshot. */
 export interface RetiredModelsSnapshot {
   readonly generatedAt: number;
@@ -64,3 +70,30 @@ export interface ReasoningModelsSnapshot {
   readonly generatedAt: number;
   readonly catalogue: ReasoningModelCatalogue;
 }
+
+/** Portable capability sets normalized from models.dev. */
+export interface ModelsDevCapabilityCatalogue {
+  readonly imageInput: readonly string[];
+  readonly reasoning: readonly string[];
+  readonly tools: readonly string[];
+  readonly structuredOutput: readonly string[];
+  readonly temperatureSupported: readonly string[];
+  readonly temperatureUnsupported: readonly string[];
+}
+
+/** Build-generated models.dev capability and reasoning snapshot. */
+export interface ModelsDevSnapshot {
+  readonly generatedAt: number;
+  readonly capabilities: ModelsDevCapabilityCatalogue;
+}
+
+/** Reasoning support and discrete effort levels normalized from modelparams.dev. */
+export interface ModelParamsCatalogue extends ReasoningModelCatalogue {
+  readonly reasoning: readonly string[];
+}
+
+/** Build-generated modelparams.dev reasoning snapshot. */
+export interface ModelParamsSnapshot {
+  readonly generatedAt: number;
+  readonly catalogue: ModelParamsCatalogue;
+}

package/src/metadata.ts

@@ -1,13 +1,13 @@
 /**
- * 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.
+ * Build-generated Databricks and public model capability metadata, plus a
+ * daily write-through cache for refreshed sources and error-learned reasoning
+ * ladders.
  *
  * Committed snapshots seed every process. {@link refreshModelMetadata} pulls
- * documentation through the shared memory-first {@link createMetadataCache} and
- * rebuilds the in-memory index. Error-learned efforts use the same store via
- * {@link rememberReasoningLevels}. Known-good values are written behind to the
- * shared model project cache.
+ * Databricks documentation, models.dev, and modelparams.dev through the shared
+ * memory-first {@link createMetadataCache} and rebuilds the in-memory index.
+ * Error-learned efforts use the same store via {@link rememberReasoningLevels}.
+ * Known-good values are written behind to the shared model project cache.
  *
  * @module
  */
@@ -20,12 +20,16 @@ import type {
 } from "@dbx-tools/shared-model";
 
 import {
+  parseModelParams,
   parseModelCapabilities,
   parseModelRateLimits,
+  parseModelsDev,
   parseReasoningModels,
   parseRetiredModels,
 } from "./_metadata-generator.ts";
 import capabilitiesSnapshotJson from "./generated/model-capabilities.json" with { type: "json" };
+import modelParamsSnapshotJson from "./generated/modelparams-reasoning.json" with { type: "json" };
+import modelsDevSnapshotJson from "./generated/models-dev-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 {
@@ -35,17 +39,29 @@ import {
   type MetadataCache,
 } from "./metadata-cache.ts";
 import {
+  MODELPARAMS_DEV_MODELS_URL,
+  MODELS_DEV_API_URL,
   MODEL_RATE_LIMITS_URL,
   OPENAI_RESPONSES_MODELS_URL,
   QUERY_REASON_MODELS_URL,
   RETIRED_MODELS_URL,
   WEB_SEARCH_MODELS_URL,
+  type ModelParamsCatalogue,
+  type ModelParamsSnapshot,
   type ModelCapabilitiesSnapshot,
   type ModelCapabilityCatalogue,
   type ModelRateLimitsSnapshot,
+  type ModelsDevCapabilityCatalogue,
+  type ModelsDevSnapshot,
   type ReasoningModelsSnapshot,
 } from "./metadata-contract.ts";
-import { inheritsNativeWebSearch, isFoundationModelIdentity, modelSearchQuery } from "./policy.ts";
+import {
+  inheritsNativeWebSearch,
+  isFoundationModelIdentity,
+  modelReasoningEfforts,
+  modelSearchQuery,
+  modelSupportsTools,
+} from "./policy.ts";
 import {
   defaultReasoningLevels,
   documentedReasoningLevels,
@@ -63,19 +79,25 @@ import {
 } from "./retirement.ts";
 
 const capabilitiesSnapshot = capabilitiesSnapshotJson as ModelCapabilitiesSnapshot;
+const modelParamsSnapshot = modelParamsSnapshotJson as ModelParamsSnapshot;
+const modelsDevSnapshot = modelsDevSnapshotJson as ModelsDevSnapshot;
 const rateLimitsSnapshot = rateLimitsSnapshotJson as ModelRateLimitsSnapshot;
 const reasoningSnapshot = reasoningSnapshotJson as ReasoningModelsSnapshot;
 
 interface MetadataIndex {
   readonly capabilities: {
-    readonly [Key in keyof ModelCapabilityCatalogue]: ReadonlySet<string>;
+    readonly [Key in keyof ModelCapabilities]: ReadonlySet<string>;
   };
   readonly rateLimits: ReadonlyMap<string, ModelRateLimits>;
   readonly reasoning: ReasoningModelCatalogue;
+  readonly reasoningDocs: ReasoningModelCatalogue;
+  readonly modelParamsReasoning: ReasoningModelCatalogue;
   readonly learnedReasoning: ReasoningModelCatalogue;
+  readonly temperatureUnsupported: ReadonlySet<string>;
 }
 
 type CapabilitySets = ModelCapabilityCatalogue;
+type ModelsDevData = ModelsDevCapabilityCatalogue;
 
 const USER_AGENT = "dbx-tools-model-metadata/1";
 
@@ -136,6 +158,35 @@ const reasoningDocsCache = createMetadataCache<Readonly<Record<string, readonly
   merge: mergePreferFreshRecord,
 });
 
+const modelsDevCache = createMetadataCache<ModelsDevData>({
+  key: "models-dev-capabilities",
+  fallback: modelsDevSnapshot.capabilities,
+  load: async () => {
+    const snapshot = parseModelsDev(await loadJson(MODELS_DEV_API_URL), nowSeconds());
+    return snapshot.capabilities;
+  },
+  merge: mergeModelsDevData,
+});
+
+const modelParamsCache = createMetadataCache<ModelParamsCatalogue>({
+  key: "modelparams-reasoning",
+  fallback: modelParamsSnapshot.catalogue,
+  load: async () =>
+    parseModelParams(await loadJson(MODELPARAMS_DEV_MODELS_URL), nowSeconds()).catalogue,
+  merge: (input) => ({
+    reasoning: mergePreferFreshList({
+      fresh: input.fresh?.reasoning,
+      previous: input.previous?.reasoning,
+      fallback: input.fallback.reasoning,
+    }),
+    models: mergePreferFreshRecord({
+      fresh: input.fresh?.models,
+      previous: input.previous?.models,
+      fallback: input.fallback.models,
+    }),
+  }),
+});
+
 const learnedReasoningCache = createMetadataCache<
   Readonly<Record<string, readonly ReasoningLevel[]>>
 >({
@@ -146,12 +197,18 @@ const learnedReasoningCache = createMetadataCache<
 
 let liveIndex: MetadataIndex | undefined;
 
-const metadataIndex = memoize<MetadataIndex>(() => liveIndex ?? buildIndexFromCommitted());
+const committedMetadataIndex = memoize<MetadataIndex>(buildIndexFromCommitted);
+
+function metadataIndex(): MetadataIndex {
+  return liveIndex ?? committedMetadataIndex();
+}
 
 function buildIndexFromCommitted(): MetadataIndex {
   return buildIndex({
     retiredNames: COMMITTED_RETIRED_MODELS,
     capabilities: capabilitiesSnapshot.capabilities,
+    modelsDev: modelsDevSnapshot.capabilities,
+    modelParams: modelParamsSnapshot.catalogue,
     rateLimits: rateLimitsSnapshot.catalogue.models,
     reasoning: reasoningSnapshot.catalogue.models,
     learnedReasoning: {},
@@ -161,21 +218,41 @@ function buildIndexFromCommitted(): MetadataIndex {
 function buildIndex(input: {
   readonly retiredNames: readonly string[];
   readonly capabilities: CapabilitySets;
+  readonly modelsDev: ModelsDevData;
+  readonly modelParams: ModelParamsCatalogue;
   readonly rateLimits: Readonly<Record<string, ModelRateLimits>>;
   readonly reasoning: Readonly<Record<string, readonly string[]>>;
   readonly learnedReasoning: Readonly<Record<string, readonly ReasoningLevel[]>>;
 }): MetadataIndex {
   replaceRetiredModelNames(input.retiredNames);
+  const reasoningDocs = freezeReasoningCatalogue(input.reasoning);
+  const modelParamsReasoning = freezeReasoningCatalogue(input.modelParams.models);
   return {
     capabilities: {
       responses: new Set(input.capabilities.responses),
-      imageInput: new Set(input.capabilities.imageInput),
+      imageInput: new Set([
+        ...input.capabilities.imageInput,
+        ...input.modelsDev.imageInput,
+      ]),
       applyPatch: new Set(input.capabilities.applyPatch),
       webSearch: new Set(input.capabilities.webSearch),
+      reasoning: new Set([
+        ...input.modelsDev.reasoning,
+        ...input.modelParams.reasoning,
+      ]),
+      tools: new Set(input.modelsDev.tools),
+      structuredOutput: new Set(input.modelsDev.structuredOutput),
+      temperature: new Set(input.modelsDev.temperatureSupported),
     },
     rateLimits: new Map(Object.entries(input.rateLimits)),
-    reasoning: freezeReasoningCatalogue(input.reasoning),
+    reasoning: Object.freeze({
+      ...modelParamsReasoning,
+      ...reasoningDocs,
+    }),
+    reasoningDocs,
+    modelParamsReasoning,
     learnedReasoning: freezeLearnedCatalogue(input.learnedReasoning),
+    temperatureUnsupported: new Set(input.modelsDev.temperatureUnsupported),
   };
 }
 
@@ -217,18 +294,28 @@ 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,
+      modelsDev,
+      modelParams,
+      rateLimits,
+      reasoning,
+      learnedReasoning,
+    ] = await Promise.all([
+      retiredCache.get(),
+      capabilitiesCache.get(),
+      modelsDevCache.get(),
+      modelParamsCache.get(),
+      rateLimitsCache.get(),
+      reasoningDocsCache.get(),
+      learnedReasoningCache.get(),
+    ]);
     liveIndex = buildIndex({
       retiredNames,
       capabilities,
+      modelsDev,
+      modelParams,
       rateLimits,
       reasoning,
       learnedReasoning,
@@ -242,9 +329,19 @@ export async function refreshModelMetadata(): Promise<MetadataIndex> {
 
 /** Load shared cache entries without forcing a network refresh. */
 export async function hydrateModelMetadata(): Promise<MetadataIndex> {
-  const [retiredNames, capabilities, rateLimits, reasoning, learnedReasoning] = await Promise.all([
+  const [
+    retiredNames,
+    capabilities,
+    modelsDev,
+    modelParams,
+    rateLimits,
+    reasoning,
+    learnedReasoning,
+  ] = await Promise.all([
     peekOrFallback(retiredCache, COMMITTED_RETIRED_MODELS),
     peekOrFallback(capabilitiesCache, capabilitiesSnapshot.capabilities),
+    peekOrFallback(modelsDevCache, modelsDevSnapshot.capabilities),
+    peekOrFallback(modelParamsCache, modelParamsSnapshot.catalogue),
     peekOrFallback(rateLimitsCache, rateLimitsSnapshot.catalogue.models),
     peekOrFallback(reasoningDocsCache, reasoningSnapshot.catalogue.models),
     peekOrFallback(learnedReasoningCache, {}),
@@ -252,6 +349,8 @@ export async function hydrateModelMetadata(): Promise<MetadataIndex> {
   liveIndex = buildIndex({
     retiredNames,
     capabilities,
+    modelsDev,
+    modelParams,
     rateLimits,
     reasoning,
     learnedReasoning,
@@ -305,17 +404,21 @@ export async function rememberReasoningLevels(
  * 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 cached.
+ * Returns a published ladder without parsing or storing error-derived levels
+ * when one exists. Otherwise returns the levels that were stored, or the
+ * current fallback when parsing yields nothing. The raw error body is never
+ * cached.
  */
 export async function learnReasoningLevelsFromError(
   model: string,
   body: unknown,
 ): Promise<ReasoningLevel[]> {
+  const published = publishedReasoningLevelsFor(model, metadataIndex());
+  if (published) return published;
   return rememberReasoningLevels(model, parseReasoningLevels(body));
 }
 
-/** Resolve documented model capabilities from a name or endpoint summary. */
+/** Resolve published model capabilities from a name or endpoint summary. */
 export function modelCapabilitiesFor(model: string | ServingEndpointSummary): ModelCapabilities {
   const capabilities = metadataIndex().capabilities;
   const identities = modelIdentities(model, false);
@@ -332,9 +435,27 @@ export function modelCapabilitiesFor(model: string | ServingEndpointSummary): Mo
           isFoundationModelIdentity(identity) &&
           inheritsNativeWebSearch(identity, capabilities.webSearch),
       ),
+    reasoning:
+      keys.some((key) => capabilities.reasoning.has(key)) ||
+      identities.some((identity) => modelReasoningEfforts(identity).length > 0),
+    tools:
+      keys.some((key) => capabilities.tools.has(key)) || identities.some(modelSupportsTools),
+    structuredOutput: keys.some((key) => capabilities.structuredOutput.has(key)),
+    temperature: modelTemperatureSupportFor(model) === true,
   };
 }
 
+/** Resolve explicit Databricks temperature support, or undefined when unpublished. */
+export function modelTemperatureSupportFor(
+  model: string | ServingEndpointSummary,
+): boolean | undefined {
+  const index = metadataIndex();
+  const keys = modelIdentities(model).flatMap((identity) => modelKey(identity) ?? []);
+  if (keys.some((key) => index.temperatureUnsupported.has(key))) return false;
+  if (keys.some((key) => index.capabilities.temperature.has(key))) return true;
+  return undefined;
+}
+
 /** Resolve published ITPM, OTPM, and QPH limits from a model identity. */
 export function modelRateLimitsFor(
   model: string | ServingEndpointSummary,
@@ -350,26 +471,40 @@ export function modelRateLimitsFor(
 }
 
 /**
- * Resolve reasoning levels: learned from errors, then documentation, then
- * family defaults.
+ * Resolve reasoning levels: Databricks documentation, modelparams.dev,
+ * learned errors, then family defaults.
  *
- * Does not parse error bodies; callers should use {@link parseReasoningLevels}
- * and then {@link rememberReasoningLevels}.
+ * Does not parse error bodies; callers handling an upstream error should use
+ * {@link learnReasoningLevelsFromError} so published levels keep precedence.
  */
 export function modelReasoningLevelsFor(model: string | ServingEndpointSummary): ReasoningLevel[] {
   const index = metadataIndex();
+  const published = publishedReasoningLevelsFor(model, index);
+  if (published) return published;
   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);
 }
 
+function publishedReasoningLevelsFor(
+  model: string | ServingEndpointSummary,
+  index: MetadataIndex,
+): ReasoningLevel[] | undefined {
+  const identities = modelIdentities(model);
+  for (const identity of identities) {
+    const documented = documentedReasoningLevels(identity, index.reasoningDocs);
+    if (documented?.length) return documented;
+  }
+  for (const identity of identities) {
+    const modelParams = documentedReasoningLevels(identity, index.modelParamsReasoning);
+    if (modelParams?.length) return modelParams;
+  }
+  return undefined;
+}
+
 /** Resolve retirement, capability, and rate-limit metadata together. */
 export function modelMetadataFor(model: string | ServingEndpointSummary): ModelMetadata {
   const rateLimits = modelRateLimitsFor(model);
@@ -384,12 +519,16 @@ export function modelMetadataFor(model: string | ServingEndpointSummary): ModelM
 export function modelMetadataGeneratedAt(): Readonly<{
   retiredModels: number;
   capabilities: number;
+  modelsDev: number;
+  modelParams: number;
   rateLimits: number;
   reasoning: number;
 }> {
   return {
     retiredModels: RETIRED_MODELS_GENERATED_AT,
     capabilities: capabilitiesSnapshot.generatedAt,
+    modelsDev: modelsDevSnapshot.generatedAt,
+    modelParams: modelParamsSnapshot.generatedAt,
     rateLimits: rateLimitsSnapshot.generatedAt,
     reasoning: reasoningSnapshot.generatedAt,
   };
@@ -423,6 +562,38 @@ async function loadPage(url: string): Promise<string> {
   return response.text();
 }
 
+async function loadJson(url: string): Promise<unknown> {
+  const response = await fetch(url, {
+    headers: { "user-agent": USER_AGENT },
+    signal: AbortSignal.timeout(15_000),
+  });
+  if (!response.ok) {
+    throw new Error(`Model metadata source returned HTTP ${response.status}: ${url}`);
+  }
+  return response.json();
+}
+
+function mergeModelsDevData(input: {
+  readonly fresh: ModelsDevData | undefined;
+  readonly previous: ModelsDevData | undefined;
+  readonly fallback: ModelsDevData;
+}): ModelsDevData {
+  const capability = (key: keyof ModelsDevCapabilityCatalogue) =>
+    mergePreferFreshList({
+      fresh: input.fresh?.[key],
+      previous: input.previous?.[key],
+      fallback: input.fallback[key],
+    });
+  return {
+    imageInput: capability("imageInput"),
+    reasoning: capability("reasoning"),
+    tools: capability("tools"),
+    structuredOutput: capability("structuredOutput"),
+    temperatureSupported: capability("temperatureSupported"),
+    temperatureUnsupported: capability("temperatureUnsupported"),
+  };
+}
+
 function nowSeconds(): number {
   return Math.floor(Date.now() / 1000);
 }

package/src/reasoning-translation.ts

@@ -273,23 +273,24 @@ const DISABLED_REASONING_TOKENS = new Set(["none", "off", "disable", "disabled"]
 /**
  * Remap a requested effort onto the nearest supported {@link ReasoningLevel}.
  *
- * `none` / `off` (and disable aliases) are not a low budget: when the model
- * requires reasoning, they snap to the supported level closest to
- * {@link ReasoningLevel.Medium}. Other requests prefer the highest allowed
- * level at or below the request, otherwise the lowest allowed level.
+ * `none` / `off` (and disable aliases), null, and unrecognized explicit values
+ * are not treated as a low budget: when the model requires reasoning, they
+ * snap to the supported level closest to {@link ReasoningLevel.Medium}. Other
+ * requests prefer the highest allowed level at or below the request, otherwise
+ * the lowest allowed level.
  *
- * Returns `undefined` when the request cannot be parsed or `levels` is empty.
+ * Returns `undefined` only when `levels` is empty.
  */
 export function remapReasoning(
   requested: unknown,
   levels: readonly ReasoningLevel[],
 ): ReasoningLevel | undefined {
   if (levels.length === 0) return undefined;
-  if (isDisabledReasoningToken(requested)) {
+  if (requested == null || isDisabledReasoningToken(requested)) {
     return nearestReasoning(ReasoningLevel.Medium, levels);
   }
   const parsed = parseReasoning(requested);
-  if (!parsed) return undefined;
+  if (!parsed) return nearestReasoning(ReasoningLevel.Medium, levels);
   if (levels.includes(parsed)) return parsed;
   const requestedIndex = REASONING_LEVELS.indexOf(parsed);
   let best: ReasoningLevel | undefined;
@@ -349,7 +350,8 @@ export interface AdaptedRequestReasoning {
  * Rewrite `reasoning_effort` / `reasoning.effort` onto a supported ladder.
  *
  * Model-agnostic: callers supply the allowed levels (learned, documented, or
- * defaults). Bodies without reasoning fields are returned unchanged.
+ * defaults). Explicit null or unrecognized values use the medium-centered
+ * fallback. Bodies without reasoning fields are returned unchanged.
  */
 export function adaptRequestReasoning(
   body: Readonly<Record<string, unknown>>,
@@ -357,11 +359,13 @@ export function adaptRequestReasoning(
 ): AdaptedRequestReasoning {
   if (levels.length === 0) return { body, changed: false };
 
+  const hasTopLevel = Object.hasOwn(body, "reasoning_effort");
   const topLevel = body.reasoning_effort;
   const reasoning = isRecord(body.reasoning) ? body.reasoning : undefined;
+  const hasNested = reasoning ? Object.hasOwn(reasoning, "effort") : false;
   const nested = reasoning?.effort;
-  const requested = topLevel ?? nested;
-  if (requested === undefined) return { body, changed: false };
+  if (!hasTopLevel && !hasNested) return { body, changed: false };
+  const requested = hasTopLevel ? topLevel : nested;
 
   const remapped = remapReasoning(requested, levels);
   if (!remapped) return { body, changed: false };
@@ -370,13 +374,13 @@ export function adaptRequestReasoning(
   let changed = false;
   let next: Record<string, unknown> = { ...body };
 
-  if (typeof topLevel === "string" || typeof topLevel === "number") {
+  if (hasTopLevel) {
     if (String(topLevel) !== wire) {
       next = { ...next, reasoning_effort: wire };
       changed = true;
     }
   }
-  if (reasoning && (typeof nested === "string" || typeof nested === "number")) {
+  if (reasoning && hasNested) {
     if (String(nested) !== wire) {
       next = { ...next, reasoning: { ...reasoning, effort: wire } };
       changed = true;