@providerprotocol/ai 0.0.4 → 0.0.6

package/src/providers/openrouter/transform.completions.ts

@@ -11,7 +11,7 @@ import {
   isToolResultMessage,
 } from '../../types/messages.ts';
 import type {
-  OpenRouterLLMParams,
+  OpenRouterCompletionsParams,
   OpenRouterCompletionsRequest,
   OpenRouterCompletionsMessage,
   OpenRouterUserContent,
@@ -23,94 +23,30 @@ import type {
 
 /**
  * Transform UPP request to OpenRouter Chat Completions format
+ *
+ * Params are spread directly to allow pass-through of any OpenRouter API fields,
+ * even those not explicitly defined in our type. This enables developers to
+ * use new API features without waiting for library updates.
  */
-export function transformRequest<TParams extends OpenRouterLLMParams>(
-  request: LLMRequest<TParams>,
+export function transformRequest(
+  request: LLMRequest<OpenRouterCompletionsParams>,
   modelId: string
 ): OpenRouterCompletionsRequest {
-  const params: OpenRouterLLMParams = request.params ?? {};
+  const params = request.params ?? ({} as OpenRouterCompletionsParams);
 
+  // Spread params to pass through all fields, then set required fields
   const openrouterRequest: OpenRouterCompletionsRequest = {
+    ...params,
     model: modelId,
     messages: transformMessages(request.messages, request.system),
   };
 
-  // Model parameters
-  if (params.temperature !== undefined) {
-    openrouterRequest.temperature = params.temperature;
-  }
-  if (params.top_p !== undefined) {
-    openrouterRequest.top_p = params.top_p;
-  }
-  if (params.top_k !== undefined) {
-    openrouterRequest.top_k = params.top_k;
-  }
-  if (params.min_p !== undefined) {
-    openrouterRequest.min_p = params.min_p;
-  }
-  if (params.top_a !== undefined) {
-    openrouterRequest.top_a = params.top_a;
-  }
-  if (params.max_tokens !== undefined) {
-    openrouterRequest.max_tokens = params.max_tokens;
-  }
-  if (params.frequency_penalty !== undefined) {
-    openrouterRequest.frequency_penalty = params.frequency_penalty;
-  }
-  if (params.presence_penalty !== undefined) {
-    openrouterRequest.presence_penalty = params.presence_penalty;
-  }
-  if (params.repetition_penalty !== undefined) {
-    openrouterRequest.repetition_penalty = params.repetition_penalty;
-  }
-  if (params.stop !== undefined) {
-    openrouterRequest.stop = params.stop;
-  }
-  if (params.logprobs !== undefined) {
-    openrouterRequest.logprobs = params.logprobs;
-  }
-  if (params.top_logprobs !== undefined) {
-    openrouterRequest.top_logprobs = params.top_logprobs;
-  }
-  if (params.seed !== undefined) {
-    openrouterRequest.seed = params.seed;
-  }
-  if (params.user !== undefined) {
-    openrouterRequest.user = params.user;
-  }
-  if (params.logit_bias !== undefined) {
-    openrouterRequest.logit_bias = params.logit_bias;
-  }
-  if (params.prediction !== undefined) {
-    openrouterRequest.prediction = params.prediction;
-  }
-
-  // OpenRouter-specific parameters
-  if (params.transforms !== undefined) {
-    openrouterRequest.transforms = params.transforms;
-  }
-  if (params.models !== undefined) {
-    openrouterRequest.models = params.models;
-  }
-  if (params.route !== undefined) {
-    openrouterRequest.route = params.route;
-  }
-  if (params.provider !== undefined) {
-    openrouterRequest.provider = params.provider;
-  }
-  if (params.debug !== undefined) {
-    openrouterRequest.debug = params.debug;
-  }
-
-  // Tools
+  // Tools come from request, not params
   if (request.tools && request.tools.length > 0) {
     openrouterRequest.tools = request.tools.map(transformTool);
-    if (params.parallel_tool_calls !== undefined) {
-      openrouterRequest.parallel_tool_calls = params.parallel_tool_calls;
-    }
   }
 
-  // Structured output via response_format
+  // Structured output via response_format (overrides params.response_format if set)
   if (request.structure) {
     const schema: Record<string, unknown> = {
       type: 'object',
@@ -133,9 +69,6 @@ export function transformRequest<TParams extends OpenRouterLLMParams>(
         strict: true,
       },
     };
-  } else if (params.response_format !== undefined) {
-    // Pass through response_format from params if no structure is defined
-    openrouterRequest.response_format = params.response_format;
   }
 
   return openrouterRequest;

package/src/providers/openrouter/transform.responses.ts

@@ -11,7 +11,7 @@ import {
   isToolResultMessage,
 } from '../../types/messages.ts';
 import type {
-  OpenRouterLLMParams,
+  OpenRouterResponsesParams,
   OpenRouterResponsesRequest,
   OpenRouterResponsesInputItem,
   OpenRouterResponsesContentPart,
@@ -25,43 +25,30 @@ import type {
 
 /**
  * Transform UPP request to OpenRouter Responses API format
+ *
+ * Params are spread directly to allow pass-through of any OpenRouter API fields,
+ * even those not explicitly defined in our type. This enables developers to
+ * use new API features without waiting for library updates.
  */
-export function transformRequest<TParams extends OpenRouterLLMParams>(
-  request: LLMRequest<TParams>,
+export function transformRequest(
+  request: LLMRequest<OpenRouterResponsesParams>,
   modelId: string
 ): OpenRouterResponsesRequest {
-  const params: OpenRouterLLMParams = request.params ?? {};
+  const params = request.params ?? ({} as OpenRouterResponsesParams);
 
+  // Spread params to pass through all fields, then set required fields
   const openrouterRequest: OpenRouterResponsesRequest = {
+    ...params,
     model: modelId,
     input: transformInputItems(request.messages, request.system),
   };
 
-  // Model parameters
-  if (params.temperature !== undefined) {
-    openrouterRequest.temperature = params.temperature;
-  }
-  if (params.top_p !== undefined) {
-    openrouterRequest.top_p = params.top_p;
-  }
-  if (params.max_output_tokens !== undefined) {
-    openrouterRequest.max_output_tokens = params.max_output_tokens;
-  } else if (params.max_tokens !== undefined) {
-    openrouterRequest.max_output_tokens = params.max_tokens;
-  }
-  if (params.reasoning !== undefined) {
-    openrouterRequest.reasoning = { ...params.reasoning };
-  }
-
-  // Tools
+  // Tools come from request, not params
   if (request.tools && request.tools.length > 0) {
     openrouterRequest.tools = request.tools.map(transformTool);
-    if (params.parallel_tool_calls !== undefined) {
-      openrouterRequest.parallel_tool_calls = params.parallel_tool_calls;
-    }
   }
 
-  // Structured output via text.format
+  // Structured output via text.format (overrides params.text if set)
   if (request.structure) {
     const schema: Record<string, unknown> = {
       type: 'object',

package/src/providers/openrouter/types.ts

@@ -1,18 +1,11 @@
 /**
- * OpenRouter-specific LLM parameters
- * These are passed through to the OpenRouter APIs
+ * OpenRouter Chat Completions API parameters
+ * These are passed through to the /api/v1/chat/completions endpoint
  */
-export interface OpenRouterLLMParams {
-  // ============================================
-  // Common Parameters (both APIs)
-  // ============================================
-
+export interface OpenRouterCompletionsParams {
   /** Maximum number of tokens to generate */
   max_tokens?: number;
 
-  /** Maximum output tokens (Responses API) */
-  max_output_tokens?: number;
-
   /** Temperature for randomness (0.0 - 2.0) */
   temperature?: number;
 
@@ -55,24 +48,12 @@ export interface OpenRouterLLMParams {
   /** Top-a sampling threshold (0.0 - 1.0) */
   top_a?: number;
 
-  // ============================================
-  // Tool Calling
-  // ============================================
-
   /** Whether to enable parallel tool calls */
   parallel_tool_calls?: boolean;
 
-  // ============================================
-  // Structured Output
-  // ============================================
-
-  /** Response format for structured output (Chat Completions API only) */
+  /** Response format for structured output */
   response_format?: OpenRouterResponseFormat;
 
-  // ============================================
-  // OpenRouter-Specific Parameters
-  // ============================================
-
   /**
    * Prompt transforms to apply
    * See: https://openrouter.ai/docs/guides/features/message-transforms
@@ -98,7 +79,6 @@ export interface OpenRouterLLMParams {
 
   /**
    * Predicted output for latency optimization
-   * https://platform.openai.com/docs/guides/latency-optimization#use-predicted-outputs
    */
   prediction?: {
     type: 'content';
@@ -112,13 +92,27 @@ export interface OpenRouterLLMParams {
     /** If true, returns the transformed request body sent to the provider */
     echo_upstream_body?: boolean;
   };
+}
 
-  // ============================================
-  // Responses API Specific
-  // ============================================
+/**
+ * OpenRouter Responses API parameters (Beta)
+ * These are passed through to the /api/v1/responses endpoint
+ */
+export interface OpenRouterResponsesParams {
+  /** Maximum output tokens */
+  max_output_tokens?: number;
+
+  /** Temperature for randomness (0.0 - 2.0) */
+  temperature?: number;
+
+  /** Top-p (nucleus) sampling (0.0 - 1.0) */
+  top_p?: number;
+
+  /** Whether to enable parallel tool calls */
+  parallel_tool_calls?: boolean;
 
   /**
-   * Reasoning configuration (Responses API)
+   * Reasoning configuration
    */
   reasoning?: {
     effort?: 'low' | 'medium' | 'high';

package/src/providers/xai/index.ts

@@ -0,0 +1,223 @@
+import type {
+  Provider,
+  ModelReference,
+  LLMHandler,
+  LLMProvider,
+} from '../../types/provider.ts';
+import { createCompletionsLLMHandler } from './llm.completions.ts';
+import { createResponsesLLMHandler } from './llm.responses.ts';
+import { createMessagesLLMHandler } from './llm.messages.ts';
+import type { XAICompletionsParams, XAIResponsesParams, XAIMessagesParams, XAIConfig, XAIAPIMode } from './types.ts';
+
+/** Union type for modalities interface */
+type XAILLMParamsUnion = XAICompletionsParams | XAIResponsesParams | XAIMessagesParams;
+
+/**
+ * xAI provider options
+ */
+export interface XAIProviderOptions {
+  /**
+   * Which API to use:
+   * - 'completions': Chat Completions API (OpenAI-compatible, default)
+   * - 'responses': Responses API (OpenAI Responses-compatible, stateful)
+   * - 'messages': Messages API (Anthropic-compatible)
+   */
+  api?: XAIAPIMode;
+}
+
+/**
+ * xAI provider with configurable API mode
+ *
+ * xAI's APIs are compatible with OpenAI and Anthropic SDKs, supporting three API modes:
+ * - Chat Completions API (OpenAI-compatible) - default, recommended
+ * - Responses API (OpenAI Responses-compatible) - stateful conversations
+ * - Messages API (Anthropic-compatible) - for migration from Anthropic
+ *
+ * @example
+ * // Using the Chat Completions API (default)
+ * const model = xai('grok-4');
+ *
+ * @example
+ * // Using the Responses API (stateful)
+ * const model = xai('grok-4', { api: 'responses' });
+ *
+ * @example
+ * // Using the Messages API (Anthropic-compatible)
+ * const model = xai('grok-4', { api: 'messages' });
+ */
+export interface XAIProvider extends Provider<XAIProviderOptions> {
+  /**
+   * Create a model reference
+   * @param modelId - The model identifier (e.g., 'grok-4', 'grok-4.1-fast', 'grok-3-mini')
+   * @param options - Provider options including API selection
+   */
+  (modelId: string, options?: XAIProviderOptions): ModelReference<XAIProviderOptions>;
+
+  /** Provider name */
+  readonly name: 'xai';
+
+  /** Provider version */
+  readonly version: string;
+
+  /** Supported modalities */
+  readonly modalities: {
+    llm: LLMHandler<XAILLMParamsUnion>;
+  };
+}
+
+/**
+ * Create the xAI provider
+ */
+function createXAIProvider(): XAIProvider {
+  // Track which API mode is currently active for the modalities
+  // Default to 'completions' (recommended for most use cases)
+  let currentApiMode: XAIAPIMode = 'completions';
+
+  // Create handlers eagerly so we can inject provider reference
+  const completionsHandler = createCompletionsLLMHandler();
+  const responsesHandler = createResponsesLLMHandler();
+  const messagesHandler = createMessagesLLMHandler();
+
+  const fn = function (
+    modelId: string,
+    options?: XAIProviderOptions
+  ): ModelReference<XAIProviderOptions> {
+    const apiMode = options?.api ?? 'completions';
+    currentApiMode = apiMode;
+    return { modelId, provider };
+  };
+
+  // Create a dynamic modalities object that returns the correct handler
+  const modalities = {
+    get llm(): LLMHandler<XAILLMParamsUnion> {
+      switch (currentApiMode) {
+        case 'responses':
+          return responsesHandler as unknown as LLMHandler<XAILLMParamsUnion>;
+        case 'messages':
+          return messagesHandler as unknown as LLMHandler<XAILLMParamsUnion>;
+        case 'completions':
+        default:
+          return completionsHandler as unknown as LLMHandler<XAILLMParamsUnion>;
+      }
+    },
+  };
+
+  // Define properties
+  Object.defineProperties(fn, {
+    name: {
+      value: 'xai',
+      writable: false,
+      configurable: true,
+    },
+    version: {
+      value: '1.0.0',
+      writable: false,
+      configurable: true,
+    },
+    modalities: {
+      value: modalities,
+      writable: false,
+      configurable: true,
+    },
+  });
+
+  const provider = fn as XAIProvider;
+
+  // Inject provider reference into all handlers (spec compliance)
+  completionsHandler._setProvider?.(provider as unknown as LLMProvider<XAICompletionsParams>);
+  responsesHandler._setProvider?.(provider as unknown as LLMProvider<XAIResponsesParams>);
+  messagesHandler._setProvider?.(provider as unknown as LLMProvider<XAIMessagesParams>);
+
+  return provider;
+}
+
+/**
+ * xAI provider
+ *
+ * Supports three API modes:
+ * - Chat Completions API (default, OpenAI-compatible)
+ * - Responses API (stateful, OpenAI Responses-compatible)
+ * - Messages API (Anthropic-compatible)
+ *
+ * xAI's Grok models support:
+ * - Real-time search via Live Search API (deprecated Dec 2025) or Agent Tools API
+ * - Reasoning with `reasoning_effort` parameter (for Grok 3 Mini)
+ * - Tool/function calling
+ * - Image input
+ * - Streaming responses
+ * - Structured output (JSON mode)
+ *
+ * @example
+ * ```ts
+ * import { xai } from './providers/xai';
+ * import { llm } from './core/llm';
+ *
+ * // Using Chat Completions API (default, recommended)
+ * const model = llm({
+ *   model: xai('grok-4'),
+ *   params: { max_tokens: 1000 }
+ * });
+ *
+ * // Using Responses API (stateful conversations)
+ * const statefulModel = llm({
+ *   model: xai('grok-4', { api: 'responses' }),
+ *   params: {
+ *     max_output_tokens: 1000,
+ *     store: true, // Enable stateful storage
+ *   }
+ * });
+ *
+ * // Continue a previous conversation
+ * const continuedModel = llm({
+ *   model: xai('grok-4', { api: 'responses' }),
+ *   params: {
+ *     previous_response_id: 'resp_123...',
+ *   }
+ * });
+ *
+ * // Using Messages API (Anthropic-compatible)
+ * const anthropicModel = llm({
+ *   model: xai('grok-4', { api: 'messages' }),
+ *   params: { max_tokens: 1000 }
+ * });
+ *
+ * // Using reasoning effort (Grok 3 Mini only)
+ * const reasoningModel = llm({
+ *   model: xai('grok-3-mini'),
+ *   params: {
+ *     max_tokens: 1000,
+ *     reasoning_effort: 'high', // 'low' or 'high'
+ *   }
+ * });
+ *
+ * // Using Live Search (deprecated Dec 2025)
+ * const searchModel = llm({
+ *   model: xai('grok-4'),
+ *   params: {
+ *     max_tokens: 1000,
+ *     search_parameters: {
+ *       mode: 'auto',
+ *       sources: ['web', 'x', 'news'],
+ *     }
+ *   }
+ * });
+ *
+ * // Generate
+ * const turn = await model.generate('Hello!');
+ * console.log(turn.response.text);
+ * ```
+ */
+export const xai = createXAIProvider();
+
+// Re-export types
+export type {
+  XAICompletionsParams,
+  XAIResponsesParams,
+  XAIMessagesParams,
+  XAIConfig,
+  XAIAPIMode,
+  XAIModelOptions,
+  XAIModelReference,
+  XAISearchParameters,
+  XAIAgentTool,
+} from './types.ts';

package/src/providers/xai/llm.completions.ts

@@ -0,0 +1,201 @@
+import type { LLMHandler, BoundLLMModel, LLMRequest, LLMResponse, LLMStreamResult, LLMCapabilities } from '../../types/llm.ts';
+import type { StreamEvent } from '../../types/stream.ts';
+import type { LLMProvider } from '../../types/provider.ts';
+import { UPPError } from '../../types/errors.ts';
+import { resolveApiKey } from '../../http/keys.ts';
+import { doFetch, doStreamFetch } from '../../http/fetch.ts';
+import { parseSSEStream } from '../../http/sse.ts';
+import { normalizeHttpError } from '../../http/errors.ts';
+import type { XAICompletionsParams, XAICompletionsResponse, XAICompletionsStreamChunk } from './types.ts';
+import {
+  transformRequest,
+  transformResponse,
+  transformStreamEvent,
+  createStreamState,
+  buildResponseFromState,
+} from './transform.completions.ts';
+
+const XAI_COMPLETIONS_API_URL = 'https://api.x.ai/v1/chat/completions';
+
+/**
+ * xAI Chat Completions API capabilities
+ */
+const XAI_COMPLETIONS_CAPABILITIES: LLMCapabilities = {
+  streaming: true,
+  tools: true,
+  structuredOutput: true,
+  imageInput: true,
+  videoInput: false,
+  audioInput: false,
+};
+
+/**
+ * Create xAI Chat Completions LLM handler
+ */
+export function createCompletionsLLMHandler(): LLMHandler<XAICompletionsParams> {
+  // Provider reference injected by createProvider() or xAI's custom factory
+  let providerRef: LLMProvider<XAICompletionsParams> | null = null;
+
+  return {
+    _setProvider(provider: LLMProvider<XAICompletionsParams>) {
+      providerRef = provider;
+    },
+
+    bind(modelId: string): BoundLLMModel<XAICompletionsParams> {
+      // Use the injected provider reference
+      if (!providerRef) {
+        throw new UPPError(
+          'Provider reference not set. Handler must be used with createProvider() or have _setProvider called.',
+          'INVALID_REQUEST',
+          'xai',
+          'llm'
+        );
+      }
+
+      const model: BoundLLMModel<XAICompletionsParams> = {
+        modelId,
+        capabilities: XAI_COMPLETIONS_CAPABILITIES,
+
+        get provider(): LLMProvider<XAICompletionsParams> {
+          return providerRef!;
+        },
+
+        async complete(request: LLMRequest<XAICompletionsParams>): Promise<LLMResponse> {
+          const apiKey = await resolveApiKey(
+            request.config,
+            'XAI_API_KEY',
+            'xai',
+            'llm'
+          );
+
+          const baseUrl = request.config.baseUrl ?? XAI_COMPLETIONS_API_URL;
+          const body = transformRequest(request, modelId);
+
+          const response = await doFetch(
+            baseUrl,
+            {
+              method: 'POST',
+              headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${apiKey}`,
+              },
+              body: JSON.stringify(body),
+              signal: request.signal,
+            },
+            request.config,
+            'xai',
+            'llm'
+          );
+
+          const data = (await response.json()) as XAICompletionsResponse;
+          return transformResponse(data);
+        },
+
+        stream(request: LLMRequest<XAICompletionsParams>): LLMStreamResult {
+          const state = createStreamState();
+          let responseResolve: (value: LLMResponse) => void;
+          let responseReject: (error: Error) => void;
+
+          const responsePromise = new Promise<LLMResponse>((resolve, reject) => {
+            responseResolve = resolve;
+            responseReject = reject;
+          });
+
+          async function* generateEvents(): AsyncGenerator<StreamEvent, void, unknown> {
+            try {
+              const apiKey = await resolveApiKey(
+                request.config,
+                'XAI_API_KEY',
+                'xai',
+                'llm'
+              );
+
+              const baseUrl = request.config.baseUrl ?? XAI_COMPLETIONS_API_URL;
+              const body = transformRequest(request, modelId);
+              body.stream = true;
+              body.stream_options = { include_usage: true };
+
+              const response = await doStreamFetch(
+                baseUrl,
+                {
+                  method: 'POST',
+                  headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${apiKey}`,
+                  },
+                  body: JSON.stringify(body),
+                  signal: request.signal,
+                },
+                request.config,
+                'xai',
+                'llm'
+              );
+
+              if (!response.ok) {
+                const error = await normalizeHttpError(response, 'xai', 'llm');
+                responseReject(error);
+                throw error;
+              }
+
+              if (!response.body) {
+                const error = new UPPError(
+                  'No response body for streaming request',
+                  'PROVIDER_ERROR',
+                  'xai',
+                  'llm'
+                );
+                responseReject(error);
+                throw error;
+              }
+
+              for await (const data of parseSSEStream(response.body)) {
+                // Skip [DONE] marker
+                if (data === '[DONE]') {
+                  continue;
+                }
+
+                // Check for xAI error event
+                if (typeof data === 'object' && data !== null) {
+                  const chunk = data as XAICompletionsStreamChunk;
+
+                  // Check for error in chunk
+                  if ('error' in chunk && chunk.error) {
+                    const errorData = chunk.error as { message?: string; type?: string };
+                    const error = new UPPError(
+                      errorData.message ?? 'Unknown error',
+                      'PROVIDER_ERROR',
+                      'xai',
+                      'llm'
+                    );
+                    responseReject(error);
+                    throw error;
+                  }
+
+                  const uppEvents = transformStreamEvent(chunk, state);
+                  for (const event of uppEvents) {
+                    yield event;
+                  }
+                }
+              }
+
+              // Build final response
+              responseResolve(buildResponseFromState(state));
+            } catch (error) {
+              responseReject(error as Error);
+              throw error;
+            }
+          }
+
+          return {
+            [Symbol.asyncIterator]() {
+              return generateEvents();
+            },
+            response: responsePromise,
+          };
+        },
+      };
+
+      return model;
+    },
+  };
+}