@dbx-tools/shared-model 0.9.40 → 0.9.43

package/src/contracts.ts

@@ -1,8 +1,22 @@
-/** Browser-safe model contracts owned by the TypeScript model runtime. */
+/**
+ * Browser-safe Zod model contracts shared across dbx-tools runtimes.
+ *
+ * This module is the single owner for model wire validation and TypeScript
+ * types. Define schemas here and derive exported types with `z.infer`; do not
+ * maintain parallel interfaces or generated schema mirrors.
+ *
+ * @module
+ */
 
-/** Intent-oriented endpoint class slug. */
-export type ModelClass = "chat-thinking" | "chat-balanced" | "chat-fast" | "embedding";
+import { z } from "zod";
 
+export const ModelClassSchema = z
+  .enum(["chat-thinking", "chat-balanced", "chat-fast", "embedding"])
+  .describe("Intent-oriented Databricks Model Serving endpoint class.");
+
+export type ModelClass = z.infer<typeof ModelClassSchema>;
+
+/** Named runtime values for the model class contract. */
 export const ModelClass = {
   ChatThinking: "chat-thinking",
   ChatBalanced: "chat-balanced",
@@ -10,9 +24,13 @@ export const ModelClass = {
   Embedding: "embedding",
 } 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 ReasoningEffortSchema = z
+  .enum(["none", "minimal", "low", "medium", "high", "xhigh", "max"])
+  .describe("Reasoning effort value accepted by compatible model endpoints.");
+
+export type ReasoningEffort = z.infer<typeof ReasoningEffortSchema>;
 
+/** Named runtime values for the reasoning effort contract. */
 export const ReasoningEffort = {
   None: "none",
   Minimal: "minimal",
@@ -23,196 +41,257 @@ export const ReasoningEffort = {
   Max: "max",
 } as const satisfies Record<string, ReasoningEffort>;
 
-/** Relative quality, speed, and cost scores for an endpoint. */
-export interface ModelProfile {
-  /** Relative model quality score. */
-  readonly quality?: number;
-  /** Relative model speed score. */
-  readonly speed?: number;
-  /** Relative model cost score. */
-  readonly cost?: number;
-}
-
-/** Model retirement status. */
-export interface ModelStatus {
-  /**
-   * Whether Databricks lists the model as retired or deprecated.
-   *
-   * @default false
-   */
-  readonly deprecated: boolean;
-}
-
-/** Browser-safe normalized Model Serving endpoint metadata. */
-export interface ServingEndpointSummary {
-  /** Model Serving endpoint name used for invocation. */
-  readonly name: string;
-  /** Human-readable endpoint or model name. */
-  readonly displayName?: string;
-  /** Normalized model family parsed from the endpoint identities. */
-  readonly family?: string;
-  /** Endpoint task, such as chat or embeddings. */
-  readonly task?: string;
-  /** Endpoint readiness state. */
-  readonly state?: string;
-  /** Endpoint description supplied by Databricks. */
-  readonly description?: string;
-  /** Whether the endpoint supports tool calling. */
-  readonly supportsTools?: boolean;
-  /** AI Gateway model profile scores. */
-  readonly profile?: ModelProfile;
-  /** Intent-oriented endpoint class. */
-  readonly class?: ModelClass;
-  /** Provider names mapped to provider-specific model names. */
-  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?: ReasoningEffort[];
-  /** Retirement status for the served model. */
-  readonly status?: ModelStatus;
-  /** Embedding vector dimension measured by the caller, when available. */
-  readonly dimension?: number;
-}
-
-/** Browser-safe model catalogue search and ranking controls. */
-export interface ModelQuery {
-  /** Optional fuzzy model-name search. */
-  readonly search?: string;
-  /** Requested model-class ceiling, or the exact embedding class. */
-  readonly modelClass?: ModelClass;
-  /** Whether candidates must support tool calling. */
-  readonly requiresTools?: boolean;
-  /** Whether retired models remain eligible. */
-  readonly includeDeprecated?: boolean;
-  /**
-   * Maximum number of results.
-   *
-   * @schema number().int().min(1).max(50).optional()
-   */
-  readonly limit?: number;
-  /**
-   * Maximum fuzzy-match distance.
-   *
-   * @minimum 0
-   * @maximum 1
-   */
-  readonly threshold?: number;
-}
-
-/** One ranked model-search result. */
-export interface RankedModel {
-  /** Matching endpoint metadata. */
-  readonly endpoint: ServingEndpointSummary;
-  /** Intent-oriented endpoint class. */
-  readonly modelClass: ModelClass;
-  /**
-   * 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";
-}
+/** Existing public name for reasoning effort runtime values. */
+export const ReasoningEffortValues = ReasoningEffort;
+
+export const ModelProfileSchema = z
+  .object({
+    quality: z.number().optional().describe("Relative quality score for ranking."),
+    speed: z.number().optional().describe("Relative speed score for ranking."),
+    cost: z.number().optional().describe("Relative cost score for ranking."),
+  })
+  .describe("Relative quality, speed, and cost scores for an endpoint.");
+
+export type ModelProfile = z.infer<typeof ModelProfileSchema>;
+
+export const ModelStatusSchema = z
+  .object({
+    deprecated: z
+      .boolean()
+      .default(false)
+      .describe("True when the model should no longer be selected by default."),
+  })
+  .describe("Model retirement status.");
+
+export type ModelStatus = z.infer<typeof ModelStatusSchema>;
+
+export const ServingEndpointSummarySchema = z
+  .object({
+    name: z.string().describe("Serving endpoint invoke id."),
+    displayName: z
+      .string()
+      .optional()
+      .describe("Human-readable label when the workspace provides one."),
+    family: z
+      .string()
+      .optional()
+      .describe("Detected model family used for grouping and sort order."),
+    task: z.string().optional().describe("Databricks serving task reported for the endpoint."),
+    state: z.string().optional().describe("Serving endpoint lifecycle state."),
+    description: z.string().optional().describe("Workspace-provided endpoint description."),
+    supportsTools: z.boolean().optional().describe("True when the endpoint accepts tool calls."),
+    profile: ModelProfileSchema.optional().describe("Relative quality, speed, and cost scores."),
+    class: ModelClassSchema.optional().describe("Intent-oriented class assigned to this endpoint."),
+    serviceNames: z
+      .record(z.string(), z.string())
+      .optional()
+      .describe("Provider-specific service name aliases keyed by protocol."),
+    modelServiceName: z
+      .string()
+      .optional()
+      .describe("Canonical model-service name used for metadata lookup."),
+    reasoningEfforts: z
+      .array(ReasoningEffortSchema)
+      .optional()
+      .describe("Reasoning effort values this endpoint accepts."),
+    status: ModelStatusSchema.optional().describe("Retirement status for this endpoint."),
+    dimension: z
+      .number()
+      .optional()
+      .describe("Embedding vector size when the endpoint is an embedding model."),
+  })
+  .describe("Browser-safe normalized Model Serving endpoint metadata.");
+
+export type ServingEndpointSummary = z.infer<typeof ServingEndpointSummarySchema>;
+
+export const ModelQuerySchema = z
+  .object({
+    search: z
+      .string()
+      .optional()
+      .describe("Free-text query matched against endpoint names and labels."),
+    modelClass: ModelClassSchema.optional().describe(
+      "Restrict results to this intent-oriented class.",
+    ),
+    requiresTools: z
+      .boolean()
+      .optional()
+      .describe("When true, only endpoints that accept tools are returned."),
+    includeDeprecated: z
+      .boolean()
+      .optional()
+      .describe("When true, retired endpoints remain in the result set."),
+    limit: z
+      .number()
+      .int()
+      .min(1)
+      .max(50)
+      .optional()
+      .describe("Maximum number of ranked results to return."),
+    threshold: z
+      .number()
+      .min(0)
+      .max(1)
+      .optional()
+      .describe("Minimum fuzzy-match score in the range 0 to 1."),
+  })
+  .describe("Browser-safe model catalogue search and ranking controls.");
+
+export type ModelQuery = z.infer<typeof ModelQuerySchema>;
+
+export const RankedModelSchema = z
+  .object({
+    endpoint: ServingEndpointSummarySchema.describe("Normalized endpoint chosen for this result."),
+    modelClass: ModelClassSchema.describe("Class used to rank this result."),
+    score: z.number().min(0).max(1).optional().describe("Fuzzy-match score in the range 0 to 1."),
+  })
+  .describe("One ranked model-search result.");
+
+export type RankedModel = z.infer<typeof RankedModelSchema>;
+
+export const EndpointCapabilitiesSchema = z
+  .object({
+    chat: z.boolean().describe("True when the endpoint can serve chat completions."),
+    embedding: z.boolean().describe("True when the endpoint can serve embeddings."),
+    tools: z.boolean().describe("True when the endpoint accepts tool calls."),
+  })
+  .describe("Capabilities derived from one normalized serving endpoint.");
+
+export type EndpointCapabilities = z.infer<typeof EndpointCapabilitiesSchema>;
+
+export const FamilyClassSchema = z
+  .object({
+    class: ModelClassSchema.describe("Fallback class for an unscored recognized family."),
+    rank: z.number().min(0).describe("Relative rank among family fallbacks, starting at 0."),
+  })
+  .describe("Fallback class and rank for an unscored recognized model family.");
+
+export type FamilyClass = z.infer<typeof FamilyClassSchema>;
+
+export const ModelCapabilitiesSchema = z
+  .object({
+    responses: z.boolean().describe("True when the model supports the Responses API."),
+    imageInput: z.boolean().describe("True when the model accepts image inputs."),
+    applyPatch: z.boolean().describe("True when the model supports the apply-patch tool."),
+    webSearch: z.boolean().describe("True when the model supports web search."),
+  })
+  .describe("Documented capabilities resolved for one model identity.");
+
+export type ModelCapabilities = z.infer<typeof ModelCapabilitiesSchema>;
+
+export const ModelRateLimitsSchema = z
+  .object({
+    inputTokensPerMinute: z
+      .number()
+      .int()
+      .min(0)
+      .nullable()
+      .describe("Published input tokens per minute, or null when unpublished."),
+    outputTokensPerMinute: z
+      .number()
+      .int()
+      .min(0)
+      .nullable()
+      .describe("Published output tokens per minute, or null when unpublished."),
+    queriesPerHour: z
+      .number()
+      .int()
+      .min(0)
+      .nullable()
+      .describe("Published queries per hour, or null when unpublished."),
+  })
+  .describe("Published pay-per-token limits for one model.");
+
+export type ModelRateLimits = z.infer<typeof ModelRateLimitsSchema>;
+
+export const ModelMetadataSchema = z
+  .object({
+    status: ModelStatusSchema.describe("Retirement status for this model identity."),
+    capabilities: ModelCapabilitiesSchema.describe(
+      "Documented capabilities for this model identity.",
+    ),
+    rateLimits: ModelRateLimitsSchema.optional().describe("Published rate limits when available."),
+  })
+  .describe("Combined retirement, capability, and rate-limit metadata.");
+
+export type ModelMetadata = z.infer<typeof ModelMetadataSchema>;
+
+export const ResolvedModelSchema = z
+  .object({
+    modelId: z.string().describe("Resolved serving endpoint or model identifier."),
+    matched: z.boolean().describe("True when the identifier matched a catalogue entry."),
+    score: z.number().min(0).max(1).optional().describe("Fuzzy-match score in the range 0 to 1."),
+  })
+  .describe("Result of resolving a fuzzy model identifier.");
+
+export type ResolvedModel = z.infer<typeof ResolvedModelSchema>;
+
+export const ResolveModelOptionsSchema = z
+  .object({
+    threshold: z
+      .number()
+      .min(0)
+      .max(1)
+      .optional()
+      .describe("Minimum fuzzy-match score in the range 0 to 1."),
+    requiresTools: z
+      .boolean()
+      .optional()
+      .describe("When true, only tool-capable endpoints may match."),
+  })
+  .describe("Pure controls for fuzzy endpoint resolution.");
+
+export type ResolveModelOptions = z.infer<typeof ResolveModelOptionsSchema>;
+
+export const ScoredEndpointSchema = z
+  .object({
+    endpoint: ServingEndpointSummarySchema.describe("Candidate serving endpoint."),
+    score: z.number().min(0).max(1).describe("Fuzzy-match distance in the range 0 to 1."),
+  })
+  .describe("One endpoint paired with its fuzzy-match distance.");
+
+export type ScoredEndpoint = z.infer<typeof ScoredEndpointSchema>;
+
+export const ResolveModelInputSchema = z
+  .object({
+    explicit: z
+      .string()
+      .optional()
+      .describe("Exact model id or display name supplied by the caller."),
+    fuzzy: z.boolean().optional().describe("When true, unmatched explicit values may fuzzy-match."),
+    threshold: z
+      .number()
+      .min(0)
+      .max(1)
+      .optional()
+      .describe("Minimum fuzzy-match score in the range 0 to 1."),
+    requiresTools: z
+      .boolean()
+      .optional()
+      .describe("When true, only tool-capable endpoints may be selected."),
+    modelClass: ModelClassSchema.optional().describe(
+      "Preferred intent-oriented class when no explicit model matches.",
+    ),
+    fallbacks: z
+      .array(z.string())
+      .optional()
+      .describe("Ordered model ids tried after class selection fails."),
+    liveOnly: z
+      .boolean()
+      .optional()
+      .describe("When true, skip endpoints that are not currently ready."),
+  })
+  .describe("Caller intent used to resolve one model from a catalogue.");
+
+export type ResolveModelInput = z.infer<typeof ResolveModelInputSchema>;
+
+export const ResolvedModelSelectionSchema = z
+  .object({
+    modelId: z.string().describe("Selected serving endpoint identifier."),
+    source: z
+      .enum(["explicit", "fuzzy-match", "class", "fallback"])
+      .describe("Policy branch that selected this model."),
+  })
+  .describe("Selected model identifier and the policy branch that selected it.");
+
+export type ResolvedModelSelection = z.infer<typeof ResolvedModelSelectionSchema>;

package/src/model.ts

@@ -1,129 +1,10 @@
 /**
  * Browser-safe model contracts and runtime schemas.
  *
+ * The owning definitions live in `contracts.ts`; this module provides the
+ * established `model` namespace without maintaining a second contract surface.
+ *
  * @module
  */
 
-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. */
-export type ModelClass = GeneratedModelClassType;
-/** Runtime values for the reasoning effort contract. */
-export const ReasoningEffortValues = GeneratedReasoningEffort;
-/** Databricks AI Gateway profile scores. */
-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;
-
-/** Runtime schema for model class wire values. */
-export const ModelClassSchema = modelClassSchema.describe(
-  `Endpoint class slug: ${Object.values(GeneratedModelClass).join(", ")}.`,
-);
-
-/** Runtime schema for Databricks AI Gateway profile scores. */
-export const ModelProfileSchema = modelProfileSchema;
-
-/** Runtime schema for reasoning effort wire values. */
-export const ReasoningEffortSchema = reasoningEffortSchema;
-
-/** Runtime schema for model lifecycle status. */
-export const ModelStatusSchema = modelStatusSchema;
-
-/** Runtime schema for normalized endpoint metadata. */
-export const ServingEndpointSummarySchema = servingEndpointSummarySchema;
-
-/** Runtime schema for model catalogue query controls. */
-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;
+export * from "./contracts.ts";