@dbx-tools/shared-model 0.9.31 → 0.9.36

package/src/contracts.ts

@@ -1,13 +1,17 @@
 /** Browser-safe model contracts owned by the TypeScript model runtime. */
 
+/** Intent-oriented endpoint class slug. */
+export type ModelClass = "chat-thinking" | "chat-balanced" | "chat-fast" | "embedding";
+
 export const ModelClass = {
   ChatThinking: "chat-thinking",
   ChatBalanced: "chat-balanced",
   ChatFast: "chat-fast",
   Embedding: "embedding",
-} as const;
-/** Intent-oriented endpoint class slug. */
-export type ModelClass = (typeof ModelClass)[keyof typeof ModelClass];
+} as const satisfies Record<string, ModelClass>;
+
+/** Reasoning effort value accepted by compatible model endpoints. */
+export type ReasoningEffort = "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
 
 export const ReasoningEffort = {
   None: "none",
@@ -17,9 +21,7 @@ export const ReasoningEffort = {
   High: "high",
   Xhigh: "xhigh",
   Max: "max",
-} as const;
-/** Reasoning effort value accepted by compatible model endpoints. */
-export type ReasoningEffort = (typeof ReasoningEffort)[keyof typeof ReasoningEffort];
+} as const satisfies Record<string, ReasoningEffort>;
 
 /** Relative quality, speed, and cost scores for an endpoint. */
 export interface ModelProfile {
@@ -33,7 +35,11 @@ export interface ModelProfile {
 
 /** Model retirement status. */
 export interface ModelStatus {
-  /** Whether Databricks lists the model as retired or deprecated. */
+  /**
+   * Whether Databricks lists the model as retired or deprecated.
+   *
+   * @default false
+   */
   readonly deprecated: boolean;
 }
 
@@ -58,11 +64,11 @@ export interface ServingEndpointSummary {
   /** Intent-oriented endpoint class. */
   readonly class?: ModelClass;
   /** Provider names mapped to provider-specific model names. */
-  readonly serviceNames?: Readonly<Record<string, string>>;
+  readonly serviceNames?: Record<string, string>;
   /** Foundation model name reported by the served entity. */
   readonly modelServiceName?: string;
   /** Reasoning effort values accepted by the endpoint. */
-  readonly reasoningEfforts?: readonly ReasoningEffort[];
+  readonly reasoningEfforts?: ReasoningEffort[];
   /** Retirement status for the served model. */
   readonly status?: ModelStatus;
   /** Embedding vector dimension measured by the caller, when available. */
@@ -79,9 +85,18 @@ export interface ModelQuery {
   readonly requiresTools?: boolean;
   /** Whether retired models remain eligible. */
   readonly includeDeprecated?: boolean;
-  /** Maximum number of results. */
+  /**
+   * Maximum number of results.
+   *
+   * @schema number().int().min(1).max(50).optional()
+   */
   readonly limit?: number;
-  /** Maximum fuzzy-match distance. */
+  /**
+   * Maximum fuzzy-match distance.
+   *
+   * @minimum 0
+   * @maximum 1
+   */
   readonly threshold?: number;
 }
 
@@ -91,6 +106,113 @@ export interface RankedModel {
   readonly endpoint: ServingEndpointSummary;
   /** Intent-oriented endpoint class. */
   readonly modelClass: ModelClass;
-  /** Fuzzy-match distance, where lower values are closer. */
+  /**
+   * Fuzzy-match distance, where lower values are closer.
+   *
+   * @minimum 0
+   * @maximum 1
+   */
+  readonly score?: number;
+}
+
+/** Capabilities derived from one normalized serving endpoint. */
+export interface EndpointCapabilities {
+  /** Whether the endpoint accepts chat or Responses requests. */
+  readonly chat: boolean;
+  /** Whether the endpoint produces embedding vectors. */
+  readonly embedding: boolean;
+  /** Whether the endpoint supports a complete function-tool round trip. */
+  readonly tools: boolean;
+}
+
+/** Fallback class and rank for an unscored recognized model family. */
+export interface FamilyClass {
+  /** Chat capability band assigned to the family. */
+  readonly class: ModelClass;
+  /**
+   * Intra-family ordering hint.
+   *
+   * @minimum 0
+   */
+  readonly rank: number;
+}
+
+/** Documented capabilities resolved for one model identity. */
+export interface ModelCapabilities {
+  readonly responses: boolean;
+  readonly imageInput: boolean;
+  readonly applyPatch: boolean;
+  readonly webSearch: boolean;
+}
+
+/** Published pay-per-token limits for one model. */
+export interface ModelRateLimits {
+  /** @schema number().int().min(0).nullable() */
+  readonly inputTokensPerMinute: number | null;
+  /** @schema number().int().min(0).nullable() */
+  readonly outputTokensPerMinute: number | null;
+  /** @schema number().int().min(0).nullable() */
+  readonly queriesPerHour: number | null;
+}
+
+/** Combined retirement, capability, and rate-limit metadata. */
+export interface ModelMetadata {
+  readonly status: ModelStatus;
+  readonly capabilities: ModelCapabilities;
+  readonly rateLimits?: ModelRateLimits;
+}
+
+/** Result of resolving a fuzzy model identifier. */
+export interface ResolvedModel {
+  readonly modelId: string;
+  readonly matched: boolean;
+  /**
+   * @minimum 0
+   * @maximum 1
+   */
   readonly score?: number;
 }
+
+/** Pure controls for fuzzy endpoint resolution. */
+export interface ResolveModelOptions {
+  /**
+   * Maximum fuzzy-match distance.
+   *
+   * @minimum 0
+   * @maximum 1
+   */
+  readonly threshold?: number;
+  /** Whether candidates must support tool calling. */
+  readonly requiresTools?: boolean;
+}
+
+/** One endpoint paired with its fuzzy-match distance. */
+export interface ScoredEndpoint {
+  readonly endpoint: ServingEndpointSummary;
+  /**
+   * @minimum 0
+   * @maximum 1
+   */
+  readonly score: number;
+}
+
+/** Caller intent used to resolve one model from a catalogue. */
+export interface ResolveModelInput {
+  readonly explicit?: string;
+  readonly fuzzy?: boolean;
+  /**
+   * @minimum 0
+   * @maximum 1
+   */
+  readonly threshold?: number;
+  readonly requiresTools?: boolean;
+  readonly modelClass?: ModelClass;
+  readonly fallbacks?: string[];
+  readonly liveOnly?: boolean;
+}
+
+/** Selected model identifier and the policy branch that selected it. */
+export interface ResolvedModelSelection {
+  readonly modelId: string;
+  readonly source: "explicit" | "fuzzy-match" | "class" | "fallback";
+}

package/src/generated/_schemas.ts

@@ -1,136 +1,127 @@
 // Generated by ts-to-zod
 import { z } from "zod";
 
+/** Browser-safe model contracts owned by the TypeScript model runtime. */
+/** Intent-oriented endpoint class slug. */
 export const modelClassSchema = z.union([z.literal("chat-thinking"), z.literal("chat-balanced"), z.literal("chat-fast"), z.literal("embedding")]);
 
+/** Reasoning effort value accepted by compatible model endpoints. */
 export const reasoningEffortSchema = z.union([z.literal("none"), z.literal("minimal"), z.literal("low"), z.literal("medium"), z.literal("high"), z.literal("xhigh"), z.literal("max")]);
 
+/** Relative quality, speed, and cost scores for an endpoint. */
 export const modelProfileSchema = z.object({
-    /**
-     * Relative model quality score.
-     */
     quality: z.number().optional(),
-    /**
-     * Relative model speed score.
-     */
     speed: z.number().optional(),
-    /**
-     * Relative model cost score.
-     */
     cost: z.number().optional()
 });
 
+/** Model retirement status. */
 export const modelStatusSchema = z.object({
-    /**
-     * Whether Databricks lists the model as retired or deprecated.
-     *
-     * @default false
-     */
     deprecated: z.boolean().default(false)
 });
 
+/** Browser-safe normalized Model Serving endpoint metadata. */
 export const servingEndpointSummarySchema = z.object({
-    /**
-     * Model Serving endpoint name used for invocation.
-     */
     name: z.string(),
-    /**
-     * Human-readable endpoint or model name.
-     */
     displayName: z.string().optional(),
-    /**
-     * Normalized model family parsed from the endpoint identities.
-     */
     family: z.string().optional(),
-    /**
-     * Endpoint task, such as chat or embeddings.
-     */
     task: z.string().optional(),
-    /**
-     * Endpoint readiness state.
-     */
     state: z.string().optional(),
-    /**
-     * Endpoint description supplied by Databricks.
-     */
     description: z.string().optional(),
-    /**
-     * Whether the endpoint supports tool calling.
-     */
     supportsTools: z.boolean().optional(),
-    /**
-     * AI Gateway model profile scores.
-     */
     profile: modelProfileSchema.optional(),
-    /**
-     * Intent-oriented endpoint class.
-     */
     class: modelClassSchema.optional(),
-    /**
-     * Provider names mapped to provider-specific model names.
-     */
     serviceNames: z.record(z.string(), z.string()).optional(),
-    /**
-     * Foundation model name reported by the served entity.
-     */
     modelServiceName: z.string().optional(),
-    /**
-     * Reasoning effort values accepted by the endpoint.
-     */
     reasoningEfforts: z.array(reasoningEffortSchema).optional(),
-    /**
-     * Retirement status for the served model.
-     */
     status: modelStatusSchema.optional(),
-    /**
-     * Embedding vector dimension measured by the caller, when available.
-     */
     dimension: z.number().optional()
 });
 
+/** Browser-safe model catalogue search and ranking controls. */
 export const modelQuerySchema = z.object({
-    /**
-     * Optional fuzzy model-name search.
-     */
     search: z.string().optional(),
-    /**
-     * Requested model-class ceiling, or the exact embedding class.
-     */
     modelClass: modelClassSchema.optional(),
-    /**
-     * Whether candidates must support tool calling.
-     */
     requiresTools: z.boolean().optional(),
-    /**
-     * Whether retired models remain eligible.
-     */
     includeDeprecated: z.boolean().optional(),
-    /**
-     * Maximum number of results.
-     *
-     * @schema number().int().min(1).max(50).optional()
-     */
     limit: z.number().int().min(1).max(50).optional(),
-    /**
-     * Maximum fuzzy-match distance.
-     *
-     * @minimum 0
-     * @maximum 1
-     */
     threshold: z.number().min(0).max(1).optional()
 });
 
+/** One ranked model-search result. */
 export const rankedModelSchema = z.object({
-    /**
-     * Matching endpoint metadata.
-     */
     endpoint: servingEndpointSummarySchema,
-    /**
-     * Intent-oriented endpoint class.
-     */
     modelClass: modelClassSchema,
-    /**
-     * Fuzzy-match distance, where lower values are closer.
-     */
-    score: z.number().optional()
+    score: z.number().min(0).max(1).optional()
+});
+
+/** Capabilities derived from one normalized serving endpoint. */
+export const endpointCapabilitiesSchema = z.object({
+    chat: z.boolean(),
+    embedding: z.boolean(),
+    tools: z.boolean()
+});
+
+/** Fallback class and rank for an unscored recognized model family. */
+export const familyClassSchema = z.object({
+    class: modelClassSchema,
+    rank: z.number().min(0)
+});
+
+/** Documented capabilities resolved for one model identity. */
+export const modelCapabilitiesSchema = z.object({
+    responses: z.boolean(),
+    imageInput: z.boolean(),
+    applyPatch: z.boolean(),
+    webSearch: z.boolean()
+});
+
+/** Published pay-per-token limits for one model. */
+export const modelRateLimitsSchema = z.object({
+    inputTokensPerMinute: z.number().int().min(0).nullable(),
+    outputTokensPerMinute: z.number().int().min(0).nullable(),
+    queriesPerHour: z.number().int().min(0).nullable()
+});
+
+/** Combined retirement, capability, and rate-limit metadata. */
+export const modelMetadataSchema = z.object({
+    status: modelStatusSchema,
+    capabilities: modelCapabilitiesSchema,
+    rateLimits: modelRateLimitsSchema.optional()
+});
+
+/** Result of resolving a fuzzy model identifier. */
+export const resolvedModelSchema = z.object({
+    modelId: z.string(),
+    matched: z.boolean(),
+    score: z.number().min(0).max(1).optional()
+});
+
+/** Pure controls for fuzzy endpoint resolution. */
+export const resolveModelOptionsSchema = z.object({
+    threshold: z.number().min(0).max(1).optional(),
+    requiresTools: z.boolean().optional()
+});
+
+/** One endpoint paired with its fuzzy-match distance. */
+export const scoredEndpointSchema = z.object({
+    endpoint: servingEndpointSummarySchema,
+    score: z.number().min(0).max(1)
+});
+
+/** Caller intent used to resolve one model from a catalogue. */
+export const resolveModelInputSchema = z.object({
+    explicit: z.string().optional(),
+    fuzzy: z.boolean().optional(),
+    threshold: z.number().min(0).max(1).optional(),
+    requiresTools: z.boolean().optional(),
+    modelClass: modelClassSchema.optional(),
+    fallbacks: z.array(z.string()).optional(),
+    liveOnly: z.boolean().optional()
+});
+
+/** Selected model identifier and the policy branch that selected it. */
+export const resolvedModelSelectionSchema = z.object({
+    modelId: z.string(),
+    source: z.union([z.literal("explicit"), z.literal("fuzzy-match"), z.literal("class"), z.literal("fallback")])
 });

package/src/model.ts

@@ -5,26 +5,50 @@
  */
 
 import {
+  type EndpointCapabilities as GeneratedEndpointCapabilities,
+  type FamilyClass as GeneratedFamilyClass,
   ModelClass as GeneratedModelClass,
+  type ModelCapabilities as GeneratedModelCapabilities,
+  type ModelMetadata as GeneratedModelMetadata,
   ReasoningEffort as GeneratedReasoningEffort,
   type ModelClass as GeneratedModelClassType,
   type ModelProfile as GeneratedModelProfile,
   type ModelQuery as GeneratedModelQuery,
+  type ModelRateLimits as GeneratedModelRateLimits,
   type ModelStatus as GeneratedModelStatus,
   type RankedModel as GeneratedRankedModel,
   type ReasoningEffort as GeneratedReasoningEffortType,
+  type ResolvedModel as GeneratedResolvedModel,
+  type ResolvedModelSelection as GeneratedResolvedModelSelection,
+  type ResolveModelInput as GeneratedResolveModelInput,
+  type ResolveModelOptions as GeneratedResolveModelOptions,
+  type ScoredEndpoint as GeneratedScoredEndpoint,
   type ServingEndpointSummary as GeneratedServingEndpointSummary,
 } from "./contracts.ts";
 import {
+  endpointCapabilitiesSchema,
+  familyClassSchema,
   modelClassSchema,
+  modelCapabilitiesSchema,
+  modelMetadataSchema,
   modelProfileSchema,
   modelQuerySchema,
+  modelRateLimitsSchema,
   modelStatusSchema,
   rankedModelSchema,
   reasoningEffortSchema,
+  resolvedModelSchema,
+  resolvedModelSelectionSchema,
+  resolveModelInputSchema,
+  resolveModelOptionsSchema,
+  scoredEndpointSchema,
   servingEndpointSummarySchema,
 } from "./generated/_schemas.ts";
 
+/** Capabilities derived from one normalized endpoint. */
+export type EndpointCapabilities = GeneratedEndpointCapabilities;
+/** Family fallback classification for an unscored model. */
+export type FamilyClass = GeneratedFamilyClass;
 /** Runtime values for the model class contract. */
 export const ModelClass = GeneratedModelClass;
 /** Class of a Databricks Model Serving endpoint. */
@@ -35,12 +59,28 @@ export const ReasoningEffortValues = GeneratedReasoningEffort;
 export type ModelProfile = GeneratedModelProfile;
 /** Model catalogue query controls. */
 export type ModelQuery = GeneratedModelQuery;
+/** Published model capability metadata. */
+export type ModelCapabilities = GeneratedModelCapabilities;
+/** Combined model metadata. */
+export type ModelMetadata = GeneratedModelMetadata;
+/** Published model rate limits. */
+export type ModelRateLimits = GeneratedModelRateLimits;
 /** Model lifecycle status. */
 export type ModelStatus = GeneratedModelStatus;
 /** A ranked endpoint result. */
 export type RankedModel = GeneratedRankedModel;
 /** Provider wire value accepted as a reasoning effort. */
 export type ReasoningEffort = GeneratedReasoningEffortType;
+/** Fuzzy endpoint resolution result. */
+export type ResolvedModel = GeneratedResolvedModel;
+/** Selected model and policy source. */
+export type ResolvedModelSelection = GeneratedResolvedModelSelection;
+/** Model selection intent. */
+export type ResolveModelInput = GeneratedResolveModelInput;
+/** Fuzzy endpoint resolution controls. */
+export type ResolveModelOptions = GeneratedResolveModelOptions;
+/** Endpoint plus fuzzy-match score. */
+export type ScoredEndpoint = GeneratedScoredEndpoint;
 /** Normalized metadata for a Databricks Model Serving endpoint. */
 export type ServingEndpointSummary = GeneratedServingEndpointSummary;
 
@@ -66,3 +106,24 @@ export const ModelQuerySchema = modelQuerySchema;
 
 /** Runtime schema for a ranked endpoint result. */
 export const RankedModelSchema = rankedModelSchema;
+
+/** Runtime schema for endpoint capabilities. */
+export const EndpointCapabilitiesSchema = endpointCapabilitiesSchema;
+/** Runtime schema for a family fallback classification. */
+export const FamilyClassSchema = familyClassSchema;
+/** Runtime schema for documented model capabilities. */
+export const ModelCapabilitiesSchema = modelCapabilitiesSchema;
+/** Runtime schema for combined model metadata. */
+export const ModelMetadataSchema = modelMetadataSchema;
+/** Runtime schema for published model rate limits. */
+export const ModelRateLimitsSchema = modelRateLimitsSchema;
+/** Runtime schema for a fuzzy endpoint resolution result. */
+export const ResolvedModelSchema = resolvedModelSchema;
+/** Runtime schema for fuzzy endpoint resolution controls. */
+export const ResolveModelOptionsSchema = resolveModelOptionsSchema;
+/** Runtime schema for an endpoint plus fuzzy score. */
+export const ScoredEndpointSchema = scoredEndpointSchema;
+/** Runtime schema for model selection intent. */
+export const ResolveModelInputSchema = resolveModelInputSchema;
+/** Runtime schema for a selected model and policy source. */
+export const ResolvedModelSelectionSchema = resolvedModelSelectionSchema;