Refactor LLM route-first provider API (#28523)

packages/llm/src/providers/amazon-bedrock.ts

@@ -1,12 +1,12 @@
-import { Route, type RouteModelInput } from "../route/client"
-import { Provider } from "../provider"
+import type { RouteDefaultsInput } from "../route/client"
+import { Auth } from "../route/auth"
 import { ProviderID, type ModelID } from "../schema"
 import * as BedrockConverse from "../protocols/bedrock-converse"
 import type { BedrockCredentials } from "../protocols/bedrock-converse"
 
 export const id = ProviderID.make("amazon-bedrock")
 
-export type ModelOptions = Omit<RouteModelInput, "id" | "baseURL"> & {
+export type Config = RouteDefaultsInput & {
   readonly apiKey?: string
   readonly headers?: Record<string, string>
   readonly credentials?: BedrockCredentials
@@ -15,34 +15,29 @@ export type ModelOptions = Omit<RouteModelInput, "id" | "baseURL"> & {
   /** Override the computed `https://bedrock-runtime.<region>.amazonaws.com` URL. */
   readonly baseURL?: string
 }
-type ModelInput = ModelOptions & Pick<RouteModelInput, "id">
-
 export const routes = [BedrockConverse.route]
 
 const bedrockBaseURL = (region: string) => `https://bedrock-runtime.${region}.amazonaws.com`
 
-const converseModel = Route.model<ModelInput>(
-  BedrockConverse.route,
-  {
-    provider: "amazon-bedrock",
-  },
-  {
-    mapInput: (input) => {
-      const { credentials, region, baseURL, ...rest } = input
-      const resolvedRegion = region ?? credentials?.region ?? "us-east-1"
-      return {
-        ...rest,
-        baseURL: baseURL ?? bedrockBaseURL(resolvedRegion),
-        native: BedrockConverse.nativeCredentials(input.native, credentials),
-      }
-    },
-  },
-)
+const configuredRoute = (input: Config) => {
+  const { apiKey, credentials, region, baseURL, ...rest } = input
+  const resolvedRegion = region ?? credentials?.region ?? "us-east-1"
+  return BedrockConverse.route.with({
+    ...rest,
+    provider: id,
+    endpoint: { baseURL: baseURL ?? bedrockBaseURL(resolvedRegion) },
+    auth: apiKey === undefined ? BedrockConverse.sigV4Auth(credentials) : Auth.bearer(apiKey),
+  })
+}
 
-export const model = (modelID: string | ModelID, options: ModelOptions = {}) =>
-  converseModel({ ...options, id: modelID })
+export const configure = (input: Config = {}) => {
+  const route = configuredRoute(input)
+  return {
+    id,
+    model: (modelID: string | ModelID) => route.model({ id: modelID }),
+    configure,
+  }
+}
 
-export const provider = Provider.make({
-  id,
-  model,
-})
+export const provider = configure()
+export const model = provider.model

packages/llm/src/providers/anthropic.ts

@@ -1,5 +1,6 @@
-import type { RouteModelInput } from "../route/client"
-import { Provider } from "../provider"
+import type { RouteDefaultsInput } from "../route/client"
+import { Auth } from "../route/auth"
+import type { ProviderAuthOption } from "../route/auth-options"
 import { ProviderID, type ModelID } from "../schema"
 import * as AnthropicMessages from "../protocols/anthropic-messages"
 
@@ -7,12 +8,28 @@ export const id = ProviderID.make("anthropic")
 
 export const routes = [AnthropicMessages.route]
 
-export const model = (
-  id: string | ModelID,
-  options: Omit<RouteModelInput, "id" | "baseURL"> & { readonly baseURL?: string } = {},
-) => AnthropicMessages.model({ ...options, id })
+export type Config = RouteDefaultsInput & ProviderAuthOption<"optional"> & { readonly baseURL?: string }
 
-export const provider = Provider.make({
-  id,
-  model,
-})
+const auth = (options: ProviderAuthOption<"optional">) => {
+  if ("auth" in options && options.auth) return options.auth
+  return Auth.optional("apiKey" in options ? options.apiKey : undefined, "apiKey")
+    .orElse(Auth.config("ANTHROPIC_API_KEY"))
+    .pipe(Auth.header("x-api-key"))
+}
+
+const configuredRoute = (input: Config) => {
+  const { apiKey: _, auth: _auth, baseURL, ...rest } = input
+  return AnthropicMessages.route.with({ ...rest, endpoint: { baseURL }, auth: auth(input) })
+}
+
+export const configure = (input: Config = {}) => {
+  const route = configuredRoute(input)
+  return {
+    id,
+    model: (modelID: string | ModelID) => route.model({ id: modelID }),
+    configure,
+  }
+}
+
+export const provider = configure()
+export const model = provider.model

packages/llm/src/providers/azure.ts

@@ -1,83 +1,110 @@
 import { Auth } from "../route/auth"
 import { type AtLeastOne, type ProviderAuthOption } from "../route/auth-options"
-import { Route } from "../route/client"
-import type { ModelInput } from "../llm"
-import { Provider } from "../provider"
+import type { Route as RouteDef, RouteDefaultsInput } from "../route/client"
 import { ProviderID, type ModelID } from "../schema"
 import * as OpenAIChat from "../protocols/openai-chat"
 import * as OpenAIResponses from "../protocols/openai-responses"
 import { withOpenAIOptions, type OpenAIProviderOptionsInput } from "./openai-options"
 
 export const id = ProviderID.make("azure")
-const routeAuth = Auth.remove("authorization").andThen(Auth.apiKeyHeader("api-key"))
+const routeAuth = Auth.remove("authorization")
 
 // Azure needs the customer's resource URL; supply either `resourceName`
 // (helper builds the URL) or `baseURL` directly.
 type AzureURL = AtLeastOne<{ readonly resourceName: string; readonly baseURL: string }>
 
 export type ModelOptions = AzureURL &
-  Omit<ModelInput, "id" | "provider" | "route" | "apiKey" | "auth" | "baseURL"> &
+  RouteDefaultsInput &
   ProviderAuthOption<"optional"> & {
     readonly apiVersion?: string
+    readonly queryParams?: Record<string, string>
     readonly useCompletionUrls?: boolean
     readonly providerOptions?: OpenAIProviderOptionsInput
   }
-type AzureModelInput = ModelOptions & Pick<ModelInput, "id">
+export type Config = ModelOptions
 
 const resourceBaseURL = (resourceName: string) => `https://${resourceName.trim()}.openai.azure.com/openai/v1`
 
 const responsesRoute = OpenAIResponses.route.with({
   id: "azure-openai-responses",
   provider: id,
-  transport: OpenAIResponses.httpTransport.with({ auth: routeAuth }),
+  auth: routeAuth,
+  endpoint: {
+    query: { "api-version": "v1" },
+  },
 })
 
 const chatRoute = OpenAIChat.route.with({
   id: "azure-openai-chat",
   provider: id,
-  transport: OpenAIChat.httpTransport.with({ auth: routeAuth }),
+  auth: routeAuth,
+  endpoint: {
+    query: { "api-version": "v1" },
+  },
 })
 
 export const routes = [responsesRoute, chatRoute]
 
-const mapInput = (input: AzureModelInput) => {
-  const { apiKey: _, apiVersion, resourceName, useCompletionUrls, ...rest } = input
-  return {
-    ...withOpenAIOptions(input.id, rest),
-    auth:
-      "auth" in input && input.auth
-        ? input.auth
-        : Auth.remove("authorization").andThen(
-            Auth.optional("apiKey" in input ? input.apiKey : undefined, "apiKey")
-              .orElse(Auth.config("AZURE_OPENAI_API_KEY"))
-              .pipe(Auth.header("api-key")),
-          ),
-    // AtLeastOne guarantees at least one is set; baseURL wins if both are.
-    baseURL: rest.baseURL ?? resourceBaseURL(resourceName!),
-    queryParams: {
-      ...rest.queryParams,
-      "api-version": apiVersion ?? rest.queryParams?.["api-version"] ?? "v1",
+const defaults = (input: Config) => {
+  const {
+    apiKey: _,
+    apiVersion: _apiVersion,
+    resourceName: _resourceName,
+    useCompletionUrls: _useCompletionUrls,
+    baseURL: _baseURL,
+    queryParams: _queryParams,
+    ...rest
+  } = input
+  if ("auth" in rest) {
+    const { auth: _, ...withoutAuth } = rest
+    return withoutAuth
+  }
+  return rest
+}
+
+const auth = (input: Config) => {
+  if ("auth" in input && input.auth) return input.auth
+  return Auth.remove("authorization").andThen(
+    Auth.optional("apiKey" in input ? input.apiKey : undefined, "apiKey")
+      .orElse(Auth.config("AZURE_OPENAI_API_KEY"))
+      .pipe(Auth.header("api-key")),
+  )
+}
+
+const configuredRoute = <Body, Prepared>(route: RouteDef<Body, Prepared>, input: Config) =>
+  route.with({
+    auth: auth(input),
+    endpoint: {
+      // AtLeastOne guarantees at least one is set; baseURL wins if both are.
+      baseURL: input.baseURL ?? resourceBaseURL(input.resourceName!),
+      query: {
+        ...(input.apiVersion ? { "api-version": input.apiVersion } : {}),
+        ...input.queryParams,
+      },
     },
+  })
+
+export const configure = (input: Config) => {
+  const configuredResponsesRoute = configuredRoute(responsesRoute, input)
+  const configuredChatRoute = configuredRoute(chatRoute, input)
+  const modelDefaults = defaults(input)
+
+  const responses = (modelID: string | ModelID) =>
+    configuredResponsesRoute.with(withOpenAIOptions(modelID, modelDefaults)).model({ id: modelID })
+
+  const chat = (modelID: string | ModelID) =>
+    configuredChatRoute.with(withOpenAIOptions(modelID, modelDefaults)).model({ id: modelID })
+
+  return {
+    id,
+    model: (modelID: string | ModelID) => (input.useCompletionUrls === true ? chat(modelID) : responses(modelID)),
+    responses,
+    chat,
+    configure,
   }
 }
 
-const chatModel = Route.model<AzureModelInput>(chatRoute, {}, { mapInput })
-const responsesModel = Route.model<AzureModelInput>(responsesRoute, {}, { mapInput })
-
-export const responses = (modelID: string | ModelID, options: ModelOptions) =>
-  responsesModel({ ...options, id: modelID })
-
-export const chat = (modelID: string | ModelID, options: ModelOptions) => chatModel({ ...options, id: modelID })
-
-export const model = (modelID: string | ModelID, options: ModelOptions) => {
-  if (options.useCompletionUrls === true) return chat(modelID, options)
-  return responses(modelID, options)
-}
-
-export const provider = Provider.make({
+export const provider = {
   id,
-  model,
-  apis: { responses, chat },
-})
-
-export const apis = provider.apis
+  configure,
+}

packages/llm/src/providers/cloudflare.ts

@@ -1,19 +1,16 @@
 import type { Config, Redacted } from "effect"
-import { type ModelInput } from "../llm"
-import { Provider } from "../provider"
 import * as OpenAICompatibleChat from "../protocols/openai-compatible-chat"
 import { Auth } from "../route/auth"
 import { AuthOptions, type AtLeastOne, type ProviderAuthOption } from "../route/auth-options"
-import { Route } from "../route/client"
+import type { RouteDefaultsInput } from "../route/client"
 import { ProviderID, type ModelID } from "../schema"
 
 export const aiGatewayID = ProviderID.make("cloudflare-ai-gateway")
 export const workersAIID = ProviderID.make("cloudflare-workers-ai")
-export const id = aiGatewayID
 export const aiGatewayAuthEnvVars = ["CLOUDFLARE_API_TOKEN", "CF_AIG_TOKEN"] as const
 export const workersAIAuthEnvVars = ["CLOUDFLARE_API_KEY", "CLOUDFLARE_WORKERS_AI_TOKEN"] as const
 
-type CloudflareSecret = string | Redacted.Redacted<string> | Config.Config<string | Redacted.Redacted<string>>
+type CloudflareSecret = string | Redacted.Redacted | Config.Config<string | Redacted.Redacted>
 
 type GatewayURL = AtLeastOne<{
   readonly accountId: string
@@ -23,32 +20,26 @@ type GatewayURL = AtLeastOne<{
 }
 
 export type AIGatewayOptions = GatewayURL &
-  Omit<ModelInput, "id" | "provider" | "route" | "baseURL" | "apiKey" | "auth"> &
+  RouteDefaultsInput &
   ProviderAuthOption<"optional"> & {
     /** Cloudflare AI Gateway authentication token. Sent as `cf-aig-authorization`. */
     readonly gatewayApiKey?: CloudflareSecret
   }
 
-type AIGatewayInput = AIGatewayOptions & Pick<ModelInput, "id">
-
 type WorkersAIURL = AtLeastOne<{
   readonly accountId: string
   readonly baseURL: string
 }>
 
-export type WorkersAIOptions = WorkersAIURL &
-  Omit<ModelInput, "id" | "provider" | "route" | "baseURL" | "apiKey" | "auth"> &
-  ProviderAuthOption<"optional">
-
-type WorkersAIInput = WorkersAIOptions & Pick<ModelInput, "id">
+export type WorkersAIOptions = WorkersAIURL & RouteDefaultsInput & ProviderAuthOption<"optional">
 
 export const aiGatewayBaseURL = (input: GatewayURL) => {
   if (input.baseURL) return input.baseURL
-  if (!input.accountId) throw new Error("Cloudflare.aiGateway requires accountId unless baseURL is supplied")
+  if (!input.accountId) throw new Error("CloudflareAIGateway.configure requires accountId unless baseURL is supplied")
   return `https://gateway.ai.cloudflare.com/v1/${encodeURIComponent(input.accountId)}/${encodeURIComponent(input.gatewayId?.trim() || "default")}/compat`
 }
 
-const aiGatewayAuth = (input: AIGatewayInput) => {
+const aiGatewayAuth = (input: AIGatewayOptions) => {
   if ("auth" in input && input.auth) return input.auth
   const gateway = Auth.optional(input.gatewayApiKey, "gatewayApiKey")
     .orElse(Auth.config("CLOUDFLARE_API_TOKEN"))
@@ -61,11 +52,11 @@ const aiGatewayAuth = (input: AIGatewayInput) => {
 
 export const workersAIBaseURL = (input: WorkersAIURL) => {
   if (input.baseURL) return input.baseURL
-  if (!input.accountId) throw new Error("Cloudflare.workersAI requires accountId unless baseURL is supplied")
+  if (!input.accountId) throw new Error("CloudflareWorkersAI.configure requires accountId unless baseURL is supplied")
   return `https://api.cloudflare.com/client/v4/accounts/${encodeURIComponent(input.accountId)}/ai/v1`
 }
 
-const workersAIAuth = (input: WorkersAIInput) => {
+const workersAIAuth = (input: WorkersAIOptions) => {
   return AuthOptions.bearer(input, workersAIAuthEnvVars)
 }
 
@@ -81,59 +72,56 @@ export const workersAIRoute = OpenAICompatibleChat.route.with({
 
 export const routes = [aiGatewayRoute, workersAIRoute]
 
-const aiGatewayModel = Route.model<AIGatewayInput>(
-  aiGatewayRoute,
-  {
-    provider: id,
-  },
-  {
-    mapInput: (input) => {
-      const {
-        accountId: _accountId,
-        gatewayId: _gatewayId,
-        apiKey: _apiKey,
-        gatewayApiKey: _gatewayApiKey,
-        auth: _auth,
-        ...rest
-      } = input
-      return {
-        ...rest,
-        auth: aiGatewayAuth(input),
-        baseURL: aiGatewayBaseURL(input),
-      }
-    },
-  },
-)
+const aiGatewayDefaults = (options: AIGatewayOptions) => {
+  const {
+    accountId: _accountId,
+    gatewayId: _gatewayId,
+    apiKey: _apiKey,
+    gatewayApiKey: _gatewayApiKey,
+    baseURL: _baseURL,
+    auth: _auth,
+    ...rest
+  } = options
+  return rest
+}
 
-const workersAIModel = Route.model<WorkersAIInput>(
-  workersAIRoute,
-  {
-    provider: workersAIID,
-  },
-  {
-    mapInput: (input) => {
-      const { accountId: _accountId, apiKey: _apiKey, auth: _auth, ...rest } = input
-      return {
-        ...rest,
-        auth: workersAIAuth(input),
-        baseURL: workersAIBaseURL(input),
-      }
-    },
-  },
-)
+const workersAIDefaults = (options: WorkersAIOptions) => {
+  const { accountId: _accountId, apiKey: _apiKey, auth: _auth, baseURL: _baseURL, ...rest } = options
+  return rest
+}
 
-export const aiGateway = (modelID: string | ModelID, options: AIGatewayOptions) =>
-  aiGatewayModel({ ...options, id: modelID })
+const configureAIGateway = (options: AIGatewayOptions) => {
+  const route = aiGatewayRoute.with({
+    ...aiGatewayDefaults(options),
+    endpoint: { baseURL: aiGatewayBaseURL(options) },
+    auth: aiGatewayAuth(options),
+  })
+  return {
+    id: aiGatewayID,
+    model: (modelID: string | ModelID) => route.model({ id: modelID }),
+    configure: configureAIGateway,
+  }
+}
 
-export const workersAI = (modelID: string | ModelID, options: WorkersAIOptions) =>
-  workersAIModel({ ...options, id: modelID })
+const configureWorkersAI = (options: WorkersAIOptions) => {
+  const route = workersAIRoute.with({
+    ...workersAIDefaults(options),
+    endpoint: { baseURL: workersAIBaseURL(options) },
+    auth: workersAIAuth(options),
+  })
+  return {
+    id: workersAIID,
+    model: (modelID: string | ModelID) => route.model({ id: modelID }),
+    configure: configureWorkersAI,
+  }
+}
 
-export const model = aiGateway
+export const CloudflareAIGateway = {
+  id: aiGatewayID,
+  configure: configureAIGateway,
+}
 
-export const provider = Provider.make({
-  id,
-  model,
-  apis: { aiGateway, workersAI },
-})
-
-export const apis = provider.apis
+export const CloudflareWorkersAI = {
+  id: workersAIID,
+  configure: configureWorkersAI,
+}

packages/llm/src/providers/github-copilot.ts

@@ -1,6 +1,5 @@
-import { Route } from "../route/client"
-import type { ModelInput } from "../llm"
-import { Provider } from "../provider"
+import { AuthOptions, type ProviderAuthOption } from "../route/auth-options"
+import type { RouteDefaultsInput } from "../route/client"
 import { ProviderID, type ModelID } from "../schema"
 import * as OpenAIChat from "../protocols/openai-chat"
 import * as OpenAIResponses from "../protocols/openai-responses"
@@ -10,10 +9,11 @@ export const id = ProviderID.make("github-copilot")
 
 // GitHub Copilot has no canonical public URL — callers (opencode, etc.) must
 // supply `baseURL` explicitly.
-export type ModelOptions = Omit<ModelInput, "id" | "provider" | "route"> & {
-  readonly providerOptions?: OpenAIProviderOptionsInput
-}
-type CopilotModelInput = ModelOptions & Pick<ModelInput, "id">
+export type ModelOptions = Omit<RouteDefaultsInput, "providerOptions"> &
+  ProviderAuthOption<"optional"> & {
+    readonly baseURL: string
+    readonly providerOptions?: OpenAIProviderOptionsInput
+  }
 
 export const shouldUseResponsesApi = (modelID: string | ModelID) => {
   const model = String(modelID)
@@ -24,25 +24,43 @@ export const shouldUseResponsesApi = (modelID: string | ModelID) => {
 
 export const routes = [OpenAIResponses.route, OpenAIChat.route]
 
-const mapInput = (input: CopilotModelInput) => withOpenAIOptions(input.id, input)
+const chatRoute = OpenAIChat.route.with({ provider: id })
+const responsesRoute = OpenAIResponses.route.with({ provider: id })
 
-const chatModel = Route.model<CopilotModelInput>(OpenAIChat.route, { provider: id }, { mapInput })
-const responsesModel = Route.model<CopilotModelInput>(OpenAIResponses.route, { provider: id }, { mapInput })
-
-export const responses = (modelID: string | ModelID, options: ModelOptions) =>
-  responsesModel({ ...options, id: modelID })
-
-export const chat = (modelID: string | ModelID, options: ModelOptions) => chatModel({ ...options, id: modelID })
-
-export const model = (modelID: string | ModelID, options: ModelOptions) => {
-  const create = shouldUseResponsesApi(modelID) ? responsesModel : chatModel
-  return create({ ...options, id: modelID })
+const defaults = (options: ModelOptions) => {
+  const { apiKey: _, auth: _auth, baseURL: _baseURL, ...rest } = options
+  return rest
 }
 
-export const provider = Provider.make({
-  id,
-  model,
-  apis: { responses, chat },
-})
+const configuredResponsesRoute = (options: ModelOptions) =>
+  responsesRoute.with({
+    endpoint: { baseURL: options.baseURL },
+    auth: AuthOptions.bearer(options, []),
+  })
 
-export const apis = provider.apis
+const configuredChatRoute = (options: ModelOptions) =>
+  chatRoute.with({
+    endpoint: { baseURL: options.baseURL },
+    auth: AuthOptions.bearer(options, []),
+  })
+
+export const configure = (options: ModelOptions) => {
+  const responsesRoute = configuredResponsesRoute(options)
+  const chatRoute = configuredChatRoute(options)
+  const responses = (modelID: string | ModelID) =>
+    responsesRoute.with(withOpenAIOptions(modelID, defaults(options))).model({ id: modelID })
+  const chat = (modelID: string | ModelID) =>
+    chatRoute.with(withOpenAIOptions(modelID, defaults(options))).model({ id: modelID })
+  return {
+    id,
+    model: (modelID: string | ModelID) => (shouldUseResponsesApi(modelID) ? responses(modelID) : chat(modelID)),
+    responses,
+    chat,
+    configure,
+  }
+}
+
+export const provider = {
+  id,
+  configure,
+}

packages/llm/src/providers/google.ts

@@ -1,5 +1,6 @@
-import type { RouteModelInput } from "../route/client"
-import { Provider } from "../provider"
+import type { RouteDefaultsInput } from "../route/client"
+import { Auth } from "../route/auth"
+import type { ProviderAuthOption } from "../route/auth-options"
 import { ProviderID, type ModelID } from "../schema"
 import * as Gemini from "../protocols/gemini"
 
@@ -7,12 +8,28 @@ export const id = ProviderID.make("google")
 
 export const routes = [Gemini.route]
 
-export const model = (
-  id: string | ModelID,
-  options: Omit<RouteModelInput, "id" | "baseURL"> & { readonly baseURL?: string } = {},
-) => Gemini.model({ ...options, id })
+export type Config = RouteDefaultsInput & ProviderAuthOption<"optional"> & { readonly baseURL?: string }
 
-export const provider = Provider.make({
-  id,
-  model,
-})
+const auth = (options: ProviderAuthOption<"optional">) => {
+  if ("auth" in options && options.auth) return options.auth
+  return Auth.optional("apiKey" in options ? options.apiKey : undefined, "apiKey")
+    .orElse(Auth.config("GOOGLE_GENERATIVE_AI_API_KEY"))
+    .pipe(Auth.header("x-goog-api-key"))
+}
+
+const configuredRoute = (input: Config) => {
+  const { apiKey: _, auth: _auth, baseURL, ...rest } = input
+  return Gemini.route.with({ ...rest, endpoint: { baseURL }, auth: auth(input) })
+}
+
+export const configure = (input: Config = {}) => {
+  const route = configuredRoute(input)
+  return {
+    id,
+    model: (modelID: string | ModelID) => route.model({ id: modelID }),
+    configure,
+  }
+}
+
+export const provider = configure()
+export const model = provider.model

packages/llm/src/providers/index.ts

@@ -2,6 +2,7 @@ export * as Anthropic from "./anthropic"
 export * as AmazonBedrock from "./amazon-bedrock"
 export * as Azure from "./azure"
 export * as Cloudflare from "./cloudflare"
+export { CloudflareAIGateway, CloudflareWorkersAI } from "./cloudflare"
 export * as GitHubCopilot from "./github-copilot"
 export * as Google from "./google"
 export * as OpenAI from "./openai"

packages/llm/src/providers/openai-compatible.ts

@@ -1,56 +1,60 @@
-import { Provider } from "../provider"
 import { ProviderID, type ModelID } from "../schema"
 import * as OpenAICompatibleChat from "../protocols/openai-compatible-chat"
-import type { OpenAICompatibleChatModelInput } from "../protocols/openai-compatible-chat"
+import type { RouteDefaultsInput } from "../route/client"
+import { AuthOptions, type ProviderAuthOption } from "../route/auth-options"
 import { profiles, type OpenAICompatibleProfile } from "./openai-compatible-profile"
 
 export const id = ProviderID.make("openai-compatible")
 
-export type ModelOptions = Omit<OpenAICompatibleChatModelInput, "id" | "provider"> & {
-  readonly provider: string
-}
+type GenericModelOptions = RouteDefaultsInput &
+  ProviderAuthOption<"optional"> & {
+    readonly provider?: string
+    readonly baseURL: string
+  }
 
-type GenericModelOptions = Omit<ModelOptions, "provider"> & {
-  readonly provider?: string
-}
-
-export type FamilyModelOptions = Omit<OpenAICompatibleChatModelInput, "id" | "provider" | "baseURL"> & {
-  readonly baseURL?: string
-}
+export type FamilyModelOptions = RouteDefaultsInput &
+  ProviderAuthOption<"optional"> & {
+    readonly baseURL?: string
+  }
 
 export const routes = [OpenAICompatibleChat.route]
 
-export const model = (id: string | ModelID, options: ModelOptions) => {
-  return OpenAICompatibleChat.model({
-    ...options,
-    id,
-    provider: ProviderID.make(options.provider),
+export const configure = (input: GenericModelOptions) => {
+  const provider = input.provider ?? "openai-compatible"
+  const { provider: _, baseURL, apiKey: _apiKey, auth: _auth, ...rest } = input
+  const route = OpenAICompatibleChat.route.with({
+    ...rest,
+    provider,
+    endpoint: { baseURL },
+    auth: AuthOptions.bearer(input, []),
   })
+  return {
+    id: ProviderID.make(provider),
+    model: (modelID: string | ModelID) => route.model({ id: modelID, provider: ProviderID.make(provider) }),
+    configure,
+  }
 }
 
-export const profileModel = (
-  profile: OpenAICompatibleProfile,
-  id: string | ModelID,
-  options: FamilyModelOptions = {},
-) =>
-  OpenAICompatibleChat.model({
-    ...options,
-    id,
-    provider: profile.provider,
-    baseURL: options.baseURL ?? profile.baseURL,
-  })
+const define = (profile: OpenAICompatibleProfile) => {
+  const configureProfile = (input: FamilyModelOptions = {}) => {
+    const facade = configure({
+      ...input,
+      baseURL: input.baseURL ?? profile.baseURL,
+      provider: profile.provider,
+    })
+    return {
+      id: ProviderID.make(profile.provider),
+      model: facade.model,
+      configure: configureProfile,
+    }
+  }
+  return configureProfile()
+}
 
-const define = (profile: OpenAICompatibleProfile) =>
-  Provider.make({
-    id: ProviderID.make(profile.provider),
-    model: (id: string | ModelID, options: FamilyModelOptions = {}) => profileModel(profile, id, options),
-  })
-
-export const provider = Provider.make({
+export const provider = {
   id,
-  model: (id: string | ModelID, options: GenericModelOptions) =>
-    model(id, { ...options, provider: options.provider ?? "openai-compatible" }),
-})
+  configure,
+}
 
 export const baseten = define(profiles.baseten)
 export const cerebras = define(profiles.cerebras)

packages/llm/src/providers/openai-options.ts

@@ -59,10 +59,9 @@ export const withOpenAIOptions = <Options extends { readonly providerOptions?: O
   modelID: string,
   options: Options,
   defaults: { readonly textVerbosity?: boolean } = {},
-): Options & { readonly id: string; readonly providerOptions?: ProviderOptions } => {
+): Omit<Options, "providerOptions"> & { readonly providerOptions?: ProviderOptions } => {
   return {
     ...options,
-    id: modelID,
     providerOptions: mergeProviderOptions(openAIDefaultOptions(modelID, defaults), options.providerOptions),
   }
 }

packages/llm/src/providers/openai.ts

@@ -1,6 +1,5 @@
 import { AuthOptions, type ProviderAuthOption } from "../route/auth-options"
-import type { RouteModelInput } from "../route/client"
-import { Provider } from "../provider"
+import type { Route, RouteDefaultsInput } from "../route/client"
 import { ProviderID, type ModelID } from "../schema"
 import * as OpenAIChat from "../protocols/openai-chat"
 import * as OpenAIResponses from "../protocols/openai-responses"
@@ -15,39 +14,50 @@ export const routes = [OpenAIResponses.route, OpenAIResponses.webSocketRoute, Op
 // This provider facade wraps the lower-level Responses and Chat model factories
 // with OpenAI-specific conveniences: typed options, API-key sugar, env fallback,
 // and default option normalization.
-type OpenAIModelInput<ModelInput> = Omit<ModelInput, "apiKey" | "auth" | "baseURL"> &
+export type Config = RouteDefaultsInput &
   ProviderAuthOption<"optional"> & {
     readonly baseURL?: string
+    readonly queryParams?: Record<string, string>
     readonly providerOptions?: OpenAIProviderOptionsInput
   }
 
 const auth = (options: ProviderAuthOption<"optional">) => AuthOptions.bearer(options, "OPENAI_API_KEY")
 
-export const responses = (id: string | ModelID, options: OpenAIModelInput<Omit<RouteModelInput, "id">> = {}) => {
-  const { apiKey: _, ...rest } = options
-  return OpenAIResponses.model(withOpenAIOptions(id, { ...rest, auth: auth(options) }, { textVerbosity: true }))
+const defaults = (input: Config) => {
+  const { apiKey: _, auth: _auth, baseURL: _baseURL, queryParams: _queryParams, ...rest } = input
+  return rest
 }
 
-export const responsesWebSocket = (
-  id: string | ModelID,
-  options: OpenAIModelInput<Omit<RouteModelInput, "id">> = {},
-) => {
-  const { apiKey: _, ...rest } = options
-  return OpenAIResponses.webSocketModel(
-    withOpenAIOptions(id, { ...rest, auth: auth(options) }, { textVerbosity: true }),
-  )
+const configuredRoute = <Body, Prepared>(route: Route<Body, Prepared>, input: Config) =>
+  route.with({
+    auth: auth(input),
+    endpoint: { baseURL: input.baseURL, query: input.queryParams },
+  })
+
+export const configure = (input: Config = {}) => {
+  const responsesRoute = configuredRoute(OpenAIResponses.route, input)
+  const responsesWebSocketRoute = configuredRoute(OpenAIResponses.webSocketRoute, input)
+  const chatRoute = configuredRoute(OpenAIChat.route, input)
+  const modelDefaults = defaults(input)
+  const responses = (id: string | ModelID) =>
+    responsesRoute.with(withOpenAIOptions(id, modelDefaults, { textVerbosity: true })).model({ id })
+  const responsesWebSocket = (id: string | ModelID) =>
+    responsesWebSocketRoute.with(withOpenAIOptions(id, modelDefaults, { textVerbosity: true })).model({ id })
+  const chat = (id: string | ModelID) => chatRoute.with(withOpenAIOptions(id, modelDefaults)).model({ id })
+
+  return {
+    id,
+    model: responses,
+    responses,
+    responsesWebSocket,
+    chat,
+    configure,
+  }
 }
 
-export const chat = (id: string | ModelID, options: OpenAIModelInput<Omit<RouteModelInput, "id">> = {}) => {
-  const { apiKey: _, ...rest } = options
-  return OpenAIChat.model(withOpenAIOptions(id, { ...rest, auth: auth(options) }))
-}
-
-export const provider = Provider.make({
-  id,
-  model: responses,
-  apis: { responses, responsesWebSocket, chat },
-})
+export const provider = configure()
 
 export const model = provider.model
-export const apis = provider.apis
+export const responses = provider.responses
+export const responsesWebSocket = provider.responsesWebSocket
+export const chat = provider.chat

packages/llm/src/providers/openrouter.ts

@@ -1,9 +1,9 @@
 import { Effect, Schema } from "effect"
-import { Route, type RouteModelInput } from "../route/client"
+import { Route, type RouteDefaultsInput } from "../route/client"
 import { Endpoint } from "../route/endpoint"
 import { Framing } from "../route/framing"
-import { Provider } from "../provider"
 import { Protocol } from "../route/protocol"
+import { AuthOptions, type ProviderAuthOption } from "../route/auth-options"
 import { ProviderID, type ModelID, type ProviderOptions } from "../schema"
 import * as OpenAICompatibleProfiles from "./openai-compatible-profile"
 import * as OpenAIChat from "../protocols/openai-chat"
@@ -24,11 +24,11 @@ export type OpenRouterProviderOptionsInput = ProviderOptions & {
   readonly openrouter?: OpenRouterOptions
 }
 
-export type ModelOptions = Omit<RouteModelInput, "id" | "baseURL" | "providerOptions"> & {
-  readonly baseURL?: string
-  readonly providerOptions?: OpenRouterProviderOptionsInput
-}
-type ModelInput = ModelOptions & Pick<RouteModelInput, "id">
+export type ModelOptions = Omit<RouteDefaultsInput, "providerOptions"> &
+  ProviderAuthOption<"optional"> & {
+    readonly baseURL?: string
+    readonly providerOptions?: OpenRouterProviderOptionsInput
+  }
 
 const OpenRouterBody = Schema.StructWithRest(Schema.Struct(OpenAIChat.bodyFields), [
   Schema.Record(Schema.String, Schema.Any),
@@ -68,21 +68,31 @@ const bodyOptions = (input: unknown) => {
 
 export const route = Route.make({
   id: ADAPTER,
+  provider: profile.provider,
   protocol,
-  endpoint: Endpoint.path("/chat/completions"),
+  endpoint: Endpoint.path("/chat/completions", { baseURL: profile.baseURL }),
   framing: Framing.sse,
 })
 
 export const routes = [route]
 
-const modelRef = Route.model<ModelInput>(route, {
-  provider: profile.provider,
-  baseURL: profile.baseURL,
-})
+const configuredRoute = (input: ModelOptions) => {
+  const { apiKey: _, auth: _auth, baseURL, ...rest } = input
+  return route.with({
+    ...rest,
+    endpoint: { baseURL: baseURL ?? profile.baseURL },
+    auth: AuthOptions.bearer(input, "OPENROUTER_API_KEY"),
+  })
+}
 
-export const model = (id: string | ModelID, options: ModelOptions = {}) => modelRef({ ...options, id })
+export const configure = (input: ModelOptions = {}) => {
+  const route = configuredRoute(input)
+  return {
+    id,
+    model: (modelID: string | ModelID) => route.model({ id: modelID }),
+    configure,
+  }
+}
 
-export const provider = Provider.make({
-  id,
-  model,
-})
+export const provider = configure()
+export const model = provider.model

packages/llm/src/providers/xai.ts

@@ -1,7 +1,5 @@
 import { AuthOptions, type ProviderAuthOption } from "../route/auth-options"
-import { Route } from "../route/client"
-import type { RouteModelInput } from "../route/client"
-import { Provider } from "../provider"
+import type { RouteDefaultsInput } from "../route/client"
 import { ProviderID, type ModelID } from "../schema"
 import * as OpenAICompatibleProfiles from "./openai-compatible-profile"
 import * as OpenAICompatibleChat from "../protocols/openai-compatible-chat"
@@ -9,44 +7,50 @@ import * as OpenAIResponses from "../protocols/openai-responses"
 
 export const id = ProviderID.make("xai")
 
-export type ModelOptions = Omit<RouteModelInput, "id" | "apiKey" | "auth" | "baseURL"> &
+export type ModelOptions = RouteDefaultsInput &
   ProviderAuthOption<"optional"> & {
     readonly baseURL?: string
   }
 
 export const routes = [OpenAIResponses.route, OpenAICompatibleChat.route]
 
-const responsesModel = Route.model(OpenAIResponses.route, { provider: id })
-const chatModel = OpenAICompatibleChat.model
-
 const auth = (options: ProviderAuthOption<"optional">) => AuthOptions.bearer(options, "XAI_API_KEY")
 
-export const responses = (modelID: string | ModelID, options: ModelOptions = {}) => {
-  const { apiKey: _, ...rest } = options
-  return responsesModel({
+const configuredResponsesRoute = (input: ModelOptions) => {
+  const { apiKey: _, auth: _auth, baseURL, ...rest } = input
+  return OpenAIResponses.route.with({
     ...rest,
-    auth: auth(options),
-    id: modelID,
-    baseURL: options.baseURL ?? OpenAICompatibleProfiles.profiles.xai.baseURL,
-  })
-}
-
-export const chat = (modelID: string | ModelID, options: ModelOptions = {}) => {
-  const { apiKey: _, ...rest } = options
-  return chatModel({
-    ...rest,
-    auth: auth(options),
-    id: modelID,
     provider: id,
-    baseURL: options.baseURL ?? OpenAICompatibleProfiles.profiles.xai.baseURL,
+    endpoint: { baseURL: baseURL ?? OpenAICompatibleProfiles.profiles.xai.baseURL },
+    auth: auth(input),
   })
 }
 
-export const provider = Provider.make({
-  id,
-  model: responses,
-  apis: { responses, chat },
-})
+const configuredChatRoute = (input: ModelOptions) => {
+  const { apiKey: _, auth: _auth, baseURL, ...rest } = input
+  return OpenAICompatibleChat.route.with({
+    ...rest,
+    provider: id,
+    endpoint: { baseURL: baseURL ?? OpenAICompatibleProfiles.profiles.xai.baseURL },
+    auth: auth(input),
+  })
+}
 
+export const configure = (input: ModelOptions = {}) => {
+  const responsesRoute = configuredResponsesRoute(input)
+  const chatRoute = configuredChatRoute(input)
+  const responses = (modelID: string | ModelID) => responsesRoute.model({ id: modelID })
+  const chat = (modelID: string | ModelID) => chatRoute.model({ id: modelID })
+  return {
+    id,
+    model: responses,
+    responses,
+    chat,
+    configure,
+  }
+}
+
+export const provider = configure()
 export const model = provider.model
-export const apis = provider.apis
+export const responses = provider.responses
+export const chat = provider.chat