@tanstack/ai-llmgateway 0.0.0

package/src/adapters/summarize.ts

@@ -0,0 +1,79 @@
+import { ChatStreamSummarizeAdapter } from '@tanstack/ai/adapters'
+import { getLLMGatewayApiKeyFromEnv } from '../utils/client'
+import { LLMGatewayTextAdapter } from './text'
+import type { InferTextProviderOptions } from '@tanstack/ai/adapters'
+import type { LLMGatewayModelId } from '../model-meta'
+import type { LLMGatewayClientConfig } from '../utils/client'
+
+/**
+ * Configuration for LLM Gateway summarize adapter
+ */
+export interface LLMGatewaySummarizeConfig extends LLMGatewayClientConfig {}
+
+/** Model type for LLM Gateway summarization */
+export type LLMGatewaySummarizeModel = LLMGatewayModelId
+
+/**
+ * Creates an LLM Gateway summarize adapter with explicit API key.
+ * Type resolution happens here at the call site.
+ *
+ * @param model - The model id (e.g., 'gpt-5.6-terra')
+ * @param apiKey - Your LLM Gateway API key
+ * @param config - Optional additional configuration
+ * @returns Configured LLM Gateway summarize adapter instance with resolved types
+ *
+ * @example
+ * ```typescript
+ * const adapter = createLLMGatewaySummarize('gpt-5.6-terra', "llmgtwy_...");
+ * ```
+ */
+export function createLLMGatewaySummarize<
+  TModel extends LLMGatewaySummarizeModel,
+>(
+  model: TModel,
+  apiKey: string,
+  config?: Omit<LLMGatewaySummarizeConfig, 'apiKey'>,
+): ChatStreamSummarizeAdapter<
+  TModel,
+  InferTextProviderOptions<LLMGatewayTextAdapter<TModel>>
+> {
+  return new ChatStreamSummarizeAdapter(
+    new LLMGatewayTextAdapter({ apiKey, ...config }, model),
+    model,
+    'llmgateway',
+  )
+}
+
+/**
+ * Creates an LLM Gateway summarize adapter with automatic API key detection
+ * from environment variables. Type resolution happens here at the call site.
+ *
+ * Looks for `LLM_GATEWAY_API_KEY` in:
+ * - `process.env` (Node.js)
+ * - `window.env` (Browser with injected env)
+ *
+ * @param model - The model id (e.g., 'gpt-5.6-terra')
+ * @param config - Optional configuration (excluding apiKey which is auto-detected)
+ * @returns Configured LLM Gateway summarize adapter instance with resolved types
+ * @throws Error if LLM_GATEWAY_API_KEY is not found in environment
+ *
+ * @example
+ * ```typescript
+ * // Automatically uses LLM_GATEWAY_API_KEY from environment
+ * const adapter = llmGatewaySummarize('gpt-5.6-terra');
+ *
+ * await summarize({
+ *   adapter,
+ *   text: "Long article text..."
+ * });
+ * ```
+ */
+export function llmGatewaySummarize<TModel extends LLMGatewaySummarizeModel>(
+  model: TModel,
+  config?: Omit<LLMGatewaySummarizeConfig, 'apiKey'>,
+): ChatStreamSummarizeAdapter<
+  TModel,
+  InferTextProviderOptions<LLMGatewayTextAdapter<TModel>>
+> {
+  return createLLMGatewaySummarize(model, getLLMGatewayApiKeyFromEnv(), config)
+}

package/src/adapters/text.ts

@@ -0,0 +1,119 @@
+import OpenAI from 'openai'
+import { OpenAIBaseChatCompletionsTextAdapter } from '@tanstack/openai-base'
+import {
+  getLLMGatewayApiKeyFromEnv,
+  withLLMGatewayDefaults,
+} from '../utils/client'
+import type { Modality } from '@tanstack/ai'
+import type {
+  LLMGatewayChatModelToolCapabilitiesByName,
+  LLMGatewayModelId,
+  ResolveInputModalities,
+  ResolveProviderOptions,
+} from '../model-meta'
+import type { LLMGatewayMessageMetadataByModality } from '../message-types'
+import type { LLMGatewayClientConfig } from '../utils/client'
+
+type ResolveToolCapabilities<TModel extends string> =
+  TModel extends keyof LLMGatewayChatModelToolCapabilitiesByName
+    ? NonNullable<LLMGatewayChatModelToolCapabilitiesByName[TModel]>
+    : readonly []
+
+/**
+ * Configuration for LLM Gateway text adapter
+ */
+export interface LLMGatewayTextConfig extends LLMGatewayClientConfig {}
+
+/**
+ * Re-export of the public provider options type
+ */
+export type { ExternalTextProviderOptions as LLMGatewayTextProviderOptions } from '../text/text-provider-options'
+
+/**
+ * LLM Gateway Text (Chat) Adapter
+ *
+ * Tree-shakeable adapter for LLM Gateway chat/text completion. LLM Gateway
+ * exposes one OpenAI-compatible Chat Completions endpoint that routes to
+ * hundreds of models across many providers, so the adapter drives it with
+ * the OpenAI SDK via a `baseURL` override (the same pattern as `ai-grok`
+ * and `ai-groq`).
+ *
+ * Model ids are open-ended: curated ids get per-model type metadata, and
+ * any other id from https://llmgateway.io/models works with text-only
+ * defaults. A `provider/model` id (e.g. `openai/gpt-5.5`) pins routing to
+ * that provider; a bare id lets the gateway pick.
+ */
+export class LLMGatewayTextAdapter<
+  TModel extends LLMGatewayModelId,
+  TProviderOptions extends Record<string, any> = ResolveProviderOptions<TModel>,
+  TInputModalities extends ReadonlyArray<Modality> =
+    ResolveInputModalities<TModel>,
+  TToolCapabilities extends ReadonlyArray<string> =
+    ResolveToolCapabilities<TModel>,
+> extends OpenAIBaseChatCompletionsTextAdapter<
+  TModel,
+  TProviderOptions,
+  TInputModalities,
+  LLMGatewayMessageMetadataByModality,
+  TToolCapabilities
+> {
+  override readonly kind = 'text' as const
+  override readonly name = 'llmgateway' as const
+
+  constructor(config: LLMGatewayTextConfig, model: TModel) {
+    super(model, 'llmgateway', new OpenAI(withLLMGatewayDefaults(config)))
+  }
+
+  /**
+   * Surfaces reasoning deltas during streaming. LLM Gateway normalizes
+   * upstream reasoning output to `delta.reasoning_content` on the OpenAI
+   * Chat Completions wire format (the DeepSeek-style field most
+   * OpenAI-compatible providers emit); some routed providers emit
+   * `delta.reasoning` instead, so both are read.
+   */
+  protected override extractReasoning(
+    chunk: OpenAI.Chat.Completions.ChatCompletionChunk,
+  ): { text: string } | undefined {
+    const delta = chunk.choices[0]?.delta as
+      | { reasoning?: unknown; reasoning_content?: unknown }
+      | undefined
+    const raw = delta?.reasoning_content ?? delta?.reasoning
+    if (typeof raw === 'string' && raw.length > 0) {
+      return { text: raw }
+    }
+    return undefined
+  }
+}
+
+/**
+ * Creates an LLM Gateway text adapter with explicit API key.
+ *
+ * @example
+ * ```typescript
+ * const adapter = createLLMGatewayText('gpt-5.6-terra', "llmgtwy_...");
+ * ```
+ */
+export function createLLMGatewayText<TModel extends LLMGatewayModelId>(
+  model: TModel,
+  apiKey: string,
+  config?: Omit<LLMGatewayTextConfig, 'apiKey'>,
+): LLMGatewayTextAdapter<TModel> {
+  return new LLMGatewayTextAdapter({ apiKey, ...config }, model)
+}
+
+/**
+ * Creates an LLM Gateway text adapter with API key from
+ * `LLM_GATEWAY_API_KEY`.
+ *
+ * @example
+ * ```typescript
+ * const adapter = llmGatewayText('gpt-5.6-terra');
+ * ```
+ */
+export function llmGatewayText<TModel extends LLMGatewayModelId>(
+  model: TModel,
+  config?: Omit<LLMGatewayTextConfig, 'apiKey'>,
+): LLMGatewayTextAdapter<TModel> {
+  const apiKey = getLLMGatewayApiKeyFromEnv()
+  return createLLMGatewayText(model, apiKey, config)
+}

package/src/index.ts

@@ -0,0 +1,52 @@
+/**
+ * @module @tanstack/ai-llmgateway
+ *
+ * LLM Gateway provider adapter for TanStack AI.
+ * Provides tree-shakeable adapters for LLM Gateway's OpenAI-compatible Chat
+ * Completions API, which routes one endpoint to hundreds of models across
+ * many providers.
+ */
+
+// Text (Chat) adapter
+export {
+  LLMGatewayTextAdapter,
+  createLLMGatewayText,
+  llmGatewayText,
+  type LLMGatewayTextConfig,
+  type LLMGatewayTextProviderOptions,
+} from './adapters/text'
+
+// Summarize - thin factory functions over @tanstack/ai's ChatStreamSummarizeAdapter
+export {
+  createLLMGatewaySummarize,
+  llmGatewaySummarize,
+  type LLMGatewaySummarizeConfig,
+  type LLMGatewaySummarizeModel,
+} from './adapters/summarize'
+
+// Types
+export type {
+  LLMGatewayChatModelProviderOptionsByName,
+  LLMGatewayChatModelToolCapabilitiesByName,
+  LLMGatewayModelInputModalitiesByName,
+  ResolveProviderOptions,
+  ResolveInputModalities,
+  LLMGatewayChatModels,
+  LLMGatewayModelId,
+} from './model-meta'
+export { LLMGATEWAY_CHAT_MODELS } from './model-meta'
+export type {
+  LLMGatewayTextMetadata,
+  LLMGatewayImageMetadata,
+  LLMGatewayAudioMetadata,
+  LLMGatewayVideoMetadata,
+  LLMGatewayDocumentMetadata,
+  LLMGatewayMessageMetadataByModality,
+} from './message-types'
+
+// Utils
+export {
+  getLLMGatewayApiKeyFromEnv,
+  withLLMGatewayDefaults,
+  type LLMGatewayClientConfig,
+} from './utils/client'

package/src/message-types.ts

@@ -0,0 +1,130 @@
+/**
+ * LLM Gateway-specific message types for the Chat Completions API.
+ *
+ * LLM Gateway's wire format is OpenAI Chat Completions — the gateway
+ * translates it to each routed provider's native format server-side. These
+ * type definitions describe that wire shape directly; the adapter drives
+ * the endpoint with the OpenAI SDK pointed at the gateway's base URL.
+ *
+ * @see https://docs.llmgateway.io
+ */
+
+export interface ChatCompletionNamedToolChoice {
+  /** Always `function` for a named tool choice. */
+  type: 'function'
+  function: {
+    /** The name of the function to call. */
+    name: string
+  }
+}
+
+/**
+ * Controls which (if any) tool is called by the model.
+ *
+ * - `none` — the model will not call any tool and instead generates a message
+ * - `auto` — the model can pick between generating a message or calling tools
+ * - `required` — the model must call one or more tools
+ * - Named tool choice — forces the model to call a specific tool
+ */
+export type ChatCompletionToolChoiceOption =
+  | 'none'
+  | 'auto'
+  | 'required'
+  | ChatCompletionNamedToolChoice
+
+export interface ResponseFormatText {
+  /** The type of response format being defined. Always `text`. */
+  type: 'text'
+}
+
+export interface ResponseFormatJsonSchemaJsonSchema {
+  /**
+   * The name of the response format. Must be a-z, A-Z, 0-9, or contain
+   * underscores and dashes, with a maximum length of 64.
+   */
+  name: string
+
+  /**
+   * A description of what the response format is for, used by the model to
+   * determine how to respond in the format.
+   */
+  description?: string
+
+  /**
+   * The schema for the response format, described as a JSON Schema object.
+   * @see https://json-schema.org/
+   */
+  schema?: { [key: string]: unknown }
+
+  /**
+   * Whether to enable strict schema adherence when generating the output. If
+   * set to true, the model will always follow the exact schema defined in the
+   * `schema` field. Only a subset of JSON Schema is supported when `strict`
+   * is `true`.
+   */
+  strict?: boolean | null
+}
+
+export interface ResponseFormatJsonSchema {
+  /** Structured Outputs configuration options, including a JSON Schema. */
+  json_schema: ResponseFormatJsonSchemaJsonSchema
+
+  /** The type of response format being defined. Always `json_schema`. */
+  type: 'json_schema'
+}
+
+export interface ResponseFormatJsonObject {
+  /** The type of response format being defined. Always `json_object`. */
+  type: 'json_object'
+}
+
+/**
+ * Metadata for LLM Gateway document content parts.
+ */
+export interface LLMGatewayDocumentMetadata {}
+
+/**
+ * Metadata for LLM Gateway text content parts.
+ * Currently no specific metadata options for text.
+ */
+export interface LLMGatewayTextMetadata {}
+
+/**
+ * Metadata for LLM Gateway image content parts.
+ * Controls how the model processes and analyzes images.
+ */
+export interface LLMGatewayImageMetadata {
+  /**
+   * Specifies the detail level of the image.
+   * - 'auto': Let the model decide based on image size and content
+   * - 'low': Use low resolution processing (faster, cheaper, less detail)
+   * - 'high': Use high resolution processing (slower, more expensive, more detail)
+   *
+   * @default 'auto'
+   */
+  detail?: 'auto' | 'low' | 'high'
+}
+
+/**
+ * Metadata for LLM Gateway audio content parts.
+ * Note: audio input support depends on the routed model.
+ */
+export interface LLMGatewayAudioMetadata {}
+
+/**
+ * Metadata for LLM Gateway video content parts.
+ * Note: video input support depends on the routed model.
+ */
+export interface LLMGatewayVideoMetadata {}
+
+/**
+ * Map of modality types to their LLM Gateway-specific metadata types.
+ * Used for type inference when constructing multimodal messages.
+ */
+export interface LLMGatewayMessageMetadataByModality {
+  text: LLMGatewayTextMetadata
+  image: LLMGatewayImageMetadata
+  audio: LLMGatewayAudioMetadata
+  video: LLMGatewayVideoMetadata
+  document: LLMGatewayDocumentMetadata
+}