@dbx-tools/shared-model-gateway 0.9.40 → 0.9.43

package/src/contracts.ts

@@ -7,105 +7,125 @@
 import { model } from "@dbx-tools/shared-model";
 import { z } from "zod";
 
-/** Client protocol accepted by the gateway. */
-export const ClientProtocolSchema = z.enum([
-  "openai-responses",
-  "openai-chat",
-  "anthropic-messages",
-  "openai-embeddings",
-]);
-/** Client protocol accepted by the gateway. */
+export const ClientProtocolSchema = z
+  .enum(["openai-responses", "openai-chat", "anthropic-messages", "openai-embeddings"])
+  .describe("Client protocol accepted by the gateway.");
+
 export type ClientProtocol = z.infer<typeof ClientProtocolSchema>;
 
-/** Upstream protocol selected by capability routing. */
-export const UpstreamProtocolSchema = z.enum([
-  "databricks-ai-gateway-codex",
-  "databricks-responses",
-  "databricks-open-responses",
-  "databricks-chat",
-  "databricks-anthropic",
-  "databricks-embeddings",
-  "ai-sdk",
-]);
-/** Upstream protocol selected by capability routing. */
+export const UpstreamProtocolSchema = z
+  .enum([
+    "databricks-ai-gateway-codex",
+    "databricks-responses",
+    "databricks-open-responses",
+    "databricks-chat",
+    "databricks-anthropic",
+    "databricks-embeddings",
+    "ai-sdk",
+  ])
+  .describe("Upstream protocol selected by capability routing.");
+
 export type UpstreamProtocol = z.infer<typeof UpstreamProtocolSchema>;
 
-/** Capabilities used to determine whether a request can remain on a direct path. */
-export const ModelCapabilitiesSchema = z.object({
-  responses: z.boolean(),
-  openResponses: z.boolean(),
-  chat: z.boolean(),
-  anthropic: z.boolean(),
-  embeddings: z.boolean(),
-  aiGatewayCodex: z.boolean(),
-  tools: z.boolean(),
-  reasoning: z.boolean(),
-  streaming: z.boolean(),
-  parallelTools: z.boolean(),
-  customTools: z.boolean(),
-  structuredOutput: z.boolean(),
-  webSearch: z.boolean(),
-});
-/** Capabilities used to determine whether a request can remain on a direct path. */
+export const ModelCapabilitiesSchema = z
+  .object({
+    responses: z.boolean().describe("True when the model can serve the Databricks Responses API."),
+    openResponses: z.boolean().describe("True when the model can serve OpenAI Responses."),
+    chat: z.boolean().describe("True when the model can serve Chat Completions."),
+    anthropic: z.boolean().describe("True when the model can serve Anthropic Messages."),
+    embeddings: z.boolean().describe("True when the model can serve embeddings."),
+    aiGatewayCodex: z
+      .boolean()
+      .describe("True when the model is reachable through AI Gateway Codex."),
+    tools: z.boolean().describe("True when the model accepts tools."),
+    reasoning: z.boolean().describe("True when the model accepts reasoning effort."),
+    streaming: z.boolean().describe("True when the model can stream tokens."),
+    parallelTools: z.boolean().describe("True when the model can run multiple tools in one turn."),
+    customTools: z.boolean().describe("True when the model accepts custom tool definitions."),
+    structuredOutput: z.boolean().describe("True when the model can return structured output."),
+    webSearch: z.boolean().describe("True when the model can use web search."),
+  })
+  .describe("Capabilities used to determine whether a request can remain on a direct path.");
+
 export type ModelCapabilities = z.infer<typeof ModelCapabilitiesSchema>;
 
-/** One discovered model plus every alias accepted by the gateway. */
-export const ModelTargetSchema = z.object({
-  id: z.string().min(1),
-  aliases: z.array(z.string().min(1)),
-  displayName: z.string().min(1),
-  family: z.string().optional(),
-  modelServiceName: z.string().optional(),
-  endpoint: model.ServingEndpointSummarySchema.optional(),
-  capabilities: ModelCapabilitiesSchema,
-  reasoningEfforts: z.array(model.ReasoningEffortSchema),
-});
-/** One discovered model plus every alias accepted by the gateway. */
+export const ModelTargetSchema = z
+  .object({
+    id: z.string().min(1).describe("Canonical model id advertised by the gateway."),
+    aliases: z.array(z.string().min(1)).describe("Additional names that resolve to this model."),
+    displayName: z.string().min(1).describe("Human-readable label shown to clients."),
+    family: z.string().optional().describe("Detected model family used for grouping."),
+    modelServiceName: z
+      .string()
+      .optional()
+      .describe("Canonical model-service name for metadata lookup."),
+    endpoint: model.ServingEndpointSummarySchema.optional().describe(
+      "Normalized serving endpoint backing this target, when discovered.",
+    ),
+    capabilities: ModelCapabilitiesSchema.describe(
+      "Protocol and feature capabilities for this target.",
+    ),
+    reasoningEfforts: z
+      .array(model.ReasoningEffortSchema)
+      .describe("Reasoning effort values this target accepts."),
+  })
+  .describe("One discovered model plus every alias accepted by the gateway.");
+
 export type ModelTarget = z.infer<typeof ModelTargetSchema>;
 
-/** Request features that constrain direct protocol routes. */
-export const RequestedFeaturesSchema = z.object({
-  background: z.boolean(),
-  customTools: z.boolean(),
-  parallelTools: z.boolean(),
-  previousResponse: z.boolean(),
-  reasoning: z.boolean(),
-  storage: z.boolean(),
-  structuredOutput: z.boolean(),
-  tools: z.boolean(),
-  unsupportedOpenResponsesTools: z.boolean(),
-  webSearch: z.boolean(),
-});
-/** Request features that constrain direct protocol routes. */
+export const RequestedFeaturesSchema = z
+  .object({
+    background: z.boolean().describe("True when the client requested a background run."),
+    customTools: z.boolean().describe("True when the request includes custom tools."),
+    parallelTools: z.boolean().describe("True when the request asks for parallel tool calls."),
+    previousResponse: z.boolean().describe("True when the request continues a stored response."),
+    reasoning: z.boolean().describe("True when the request sets reasoning effort."),
+    storage: z
+      .boolean()
+      .describe("True when the request asks the provider to persist the response."),
+    structuredOutput: z.boolean().describe("True when the request requires structured output."),
+    tools: z.boolean().describe("True when the request includes tools."),
+    unsupportedOpenResponsesTools: z
+      .boolean()
+      .describe("True when tools cannot ride the Open Responses fast path."),
+    webSearch: z.boolean().describe("True when the request includes web search."),
+  })
+  .describe("Request features that constrain direct protocol routes.");
+
 export type RequestedFeatures = z.infer<typeof RequestedFeaturesSchema>;
 
-/** Deterministic route selected for one gateway request. */
-export const GatewayRouteSchema = z.object({
-  clientProtocol: ClientProtocolSchema,
-  upstreamProtocol: UpstreamProtocolSchema,
-  target: ModelTargetSchema,
-  upstreamModel: z.string().min(1),
-  translateRequest: z.boolean(),
-  translateResponse: z.boolean(),
-});
-/** Deterministic route selected for one gateway request. */
+export const GatewayRouteSchema = z
+  .object({
+    clientProtocol: ClientProtocolSchema.describe("Protocol the caller used."),
+    upstreamProtocol: UpstreamProtocolSchema.describe("Protocol selected for the upstream call."),
+    target: ModelTargetSchema.describe("Discovered model this request will invoke."),
+    upstreamModel: z.string().min(1).describe("Model identifier sent to the upstream provider."),
+    translateRequest: z.boolean().describe("True when the request body must be translated."),
+    translateResponse: z.boolean().describe("True when the response body must be translated."),
+  })
+  .describe("Deterministic route selected for one gateway request.");
+
 export type GatewayRoute = z.infer<typeof GatewayRouteSchema>;
 
-/** Typed capability changes for one dynamically discovered model. */
-export const ModelCapabilityOverrideSchema = z.object({
-  model: z.string().min(1),
-  capabilities: ModelCapabilitiesSchema.partial(),
-});
-/** Typed capability changes for one dynamically discovered model. */
+export const ModelCapabilityOverrideSchema = z
+  .object({
+    model: z.string().min(1).describe("Model id or alias whose capabilities are overridden."),
+    capabilities: ModelCapabilitiesSchema.partial().describe(
+      "Capability flags to merge onto the discovered model.",
+    ),
+  })
+  .describe("Typed capability changes for one dynamically discovered model.");
+
 export type ModelCapabilityOverride = z.infer<typeof ModelCapabilityOverrideSchema>;
 
-/** Inputs required to select one deterministic gateway route. */
-export const ResolveRouteInputSchema = z.object({
-  clientProtocol: ClientProtocolSchema,
-  requestedModel: z.string().min(1),
-  originator: z.string().optional(),
-  features: RequestedFeaturesSchema,
-  target: ModelTargetSchema,
-});
-/** Inputs required to select one deterministic gateway route. */
+export const ResolveRouteInputSchema = z
+  .object({
+    clientProtocol: ClientProtocolSchema.describe("Protocol the caller used."),
+    requestedModel: z.string().min(1).describe("Model id or alias requested by the caller."),
+    originator: z.string().optional().describe("Optional Originator header, such as codex."),
+    features: RequestedFeaturesSchema.describe("Request features that constrain routing."),
+    target: ModelTargetSchema.describe("Discovered model selected for this request."),
+  })
+  .describe("Inputs required to select one deterministic gateway route.");
+
 export type ResolveRouteInput = z.infer<typeof ResolveRouteInputSchema>;

package/src/models.ts

@@ -17,6 +17,7 @@ export const OpenAIModelCapabilitiesSchema = z.object({
   embeddings: z.boolean(),
   ai_gateway_codex: z.boolean(),
   streaming: z.boolean(),
+  web_search: z.boolean(),
 });
 /** Capabilities published with an OpenAI-compatible model entry. */
 export type OpenAIModelCapabilities = z.infer<typeof OpenAIModelCapabilitiesSchema>;

package/src/options.ts

@@ -0,0 +1,59 @@
+/**
+ * Browser-safe model-gateway runtime and CLI configuration.
+ *
+ * Field names and descriptions are the single source for derived Commander
+ * flags, environment names, generated help, JavaScript callers, and services.
+ *
+ * @module
+ */
+
+import { options } from "@dbx-tools/shared-core";
+import { z } from "zod";
+
+export const ModelGatewayOptionsSchema = z
+  .object({
+    listen: options
+      .listenAddressSchema({ port: 4000, loopback: true })
+      .describe("Loopback listener address."),
+    profile: options.DatabricksOptionsSchema.shape.profile.describe(
+      "Databricks profile used for model discovery and requests.",
+    ),
+    bodyLimit: z
+      .string()
+      .trim()
+      .min(1)
+      .default("100mb")
+      .describe("Maximum JSON request body size."),
+  })
+  .strict()
+  .describe("Model-gateway server configuration.");
+
+export const ModelGatewayCliOptionsSchema = ModelGatewayOptionsSchema.extend({
+  runtimeInfo: z.boolean().default(false).describe("Print runtime implementation metadata."),
+})
+  .refine((options) => options.listen.port > 0, {
+    message: "Port must be an integer from 1 through 65535.",
+    path: ["listen"],
+  })
+  .describe("Model-gateway command-line configuration.");
+
+export type ModelGatewayOptions = z.input<typeof ModelGatewayOptionsSchema>;
+
+export type ResolvedModelGatewayOptions = z.output<typeof ModelGatewayOptionsSchema>;
+
+export type ModelGatewayCliOptions = z.output<typeof ModelGatewayCliOptionsSchema>;
+
+/** Defaults parsed from the owning runtime schema. */
+export const MODEL_GATEWAY_DEFAULTS = Object.freeze(ModelGatewayOptionsSchema.parse({}));
+
+/** Validate and default model-gateway server options. */
+export function resolveModelGatewayOptions(
+  options: ModelGatewayOptions = {},
+): ResolvedModelGatewayOptions {
+  return ModelGatewayOptionsSchema.parse(options);
+}
+
+/** Validate and default model-gateway command-line options. */
+export function resolveModelGatewayCliOptions(options: unknown): ModelGatewayCliOptions {
+  return ModelGatewayCliOptionsSchema.parse(options);
+}

package/src/upstream.ts

@@ -0,0 +1,35 @@
+/**
+ * Browser-safe Databricks upstream URLs for deterministic gateway routes.
+ *
+ * This module owns direct-route URL construction for browser, edge, and Node
+ * consumers. Reuse {@link upstreamUrl} instead of duplicating Databricks model
+ * serving paths in transports or user interfaces.
+ *
+ * @module
+ */
+
+import type { GatewayRoute } from "./contracts.ts";
+
+/** Resolve the exact upstream URL for a deterministic direct route. */
+export function upstreamUrl(host: string, route: GatewayRoute): string {
+  switch (route.upstreamProtocol) {
+    case "databricks-ai-gateway-codex":
+      return url(host, "/ai-gateway/codex/v1/responses");
+    case "databricks-responses":
+      return url(host, "/serving-endpoints/responses");
+    case "databricks-open-responses":
+      return url(host, "/serving-endpoints/open-responses");
+    case "databricks-chat":
+      return url(host, "/serving-endpoints/chat/completions");
+    case "databricks-anthropic":
+      return url(host, "/serving-endpoints/anthropic/v1/messages");
+    case "databricks-embeddings":
+      return url(host, `/serving-endpoints/${encodeURIComponent(route.upstreamModel)}/invocations`);
+    case "ai-sdk":
+      throw new Error("AI SDK routes do not use the direct Databricks transport");
+  }
+}
+
+function url(host: string, path: string): string {
+  return new URL(path, `${host.replace(/\/$/, "")}/`).toString();
+}