@providerprotocol/ai 0.0.5 → 0.0.7

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

@@ -6,7 +6,7 @@ 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 { XAILLMParams, XAICompletionsResponse, XAICompletionsStreamChunk } from './types.ts';
+import type { XAICompletionsParams, XAICompletionsResponse, XAICompletionsStreamChunk } from './types.ts';
 import {
   transformRequest,
   transformResponse,
@@ -32,16 +32,16 @@ const XAI_COMPLETIONS_CAPABILITIES: LLMCapabilities = {
 /**
  * Create xAI Chat Completions LLM handler
  */
-export function createCompletionsLLMHandler(): LLMHandler<XAILLMParams> {
+export function createCompletionsLLMHandler(): LLMHandler<XAICompletionsParams> {
   // Provider reference injected by createProvider() or xAI's custom factory
-  let providerRef: LLMProvider<XAILLMParams> | null = null;
+  let providerRef: LLMProvider<XAICompletionsParams> | null = null;
 
   return {
-    _setProvider(provider: LLMProvider<XAILLMParams>) {
+    _setProvider(provider: LLMProvider<XAICompletionsParams>) {
       providerRef = provider;
     },
 
-    bind(modelId: string): BoundLLMModel<XAILLMParams> {
+    bind(modelId: string): BoundLLMModel<XAICompletionsParams> {
       // Use the injected provider reference
       if (!providerRef) {
         throw new UPPError(
@@ -52,15 +52,15 @@ export function createCompletionsLLMHandler(): LLMHandler<XAILLMParams> {
         );
       }
 
-      const model: BoundLLMModel<XAILLMParams> = {
+      const model: BoundLLMModel<XAICompletionsParams> = {
         modelId,
         capabilities: XAI_COMPLETIONS_CAPABILITIES,
 
-        get provider(): LLMProvider<XAILLMParams> {
+        get provider(): LLMProvider<XAICompletionsParams> {
           return providerRef!;
         },
 
-        async complete(request: LLMRequest<XAILLMParams>): Promise<LLMResponse> {
+        async complete(request: LLMRequest<XAICompletionsParams>): Promise<LLMResponse> {
           const apiKey = await resolveApiKey(
             request.config,
             'XAI_API_KEY',
@@ -91,7 +91,7 @@ export function createCompletionsLLMHandler(): LLMHandler<XAILLMParams> {
           return transformResponse(data);
         },
 
-        stream(request: LLMRequest<XAILLMParams>): LLMStreamResult {
+        stream(request: LLMRequest<XAICompletionsParams>): LLMStreamResult {
           const state = createStreamState();
           let responseResolve: (value: LLMResponse) => void;
           let responseReject: (error: Error) => void;

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

@@ -6,7 +6,7 @@ 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 { XAILLMParams, XAIMessagesResponse, XAIMessagesStreamEvent } from './types.ts';
+import type { XAIMessagesParams, XAIMessagesResponse, XAIMessagesStreamEvent } from './types.ts';
 import {
   transformRequest,
   transformResponse,
@@ -32,16 +32,16 @@ const XAI_MESSAGES_CAPABILITIES: LLMCapabilities = {
 /**
  * Create xAI Messages API LLM handler (Anthropic-compatible)
  */
-export function createMessagesLLMHandler(): LLMHandler<XAILLMParams> {
+export function createMessagesLLMHandler(): LLMHandler<XAIMessagesParams> {
   // Provider reference injected by createProvider() or xAI's custom factory
-  let providerRef: LLMProvider<XAILLMParams> | null = null;
+  let providerRef: LLMProvider<XAIMessagesParams> | null = null;
 
   return {
-    _setProvider(provider: LLMProvider<XAILLMParams>) {
+    _setProvider(provider: LLMProvider<XAIMessagesParams>) {
       providerRef = provider;
     },
 
-    bind(modelId: string): BoundLLMModel<XAILLMParams> {
+    bind(modelId: string): BoundLLMModel<XAIMessagesParams> {
       // Use the injected provider reference
       if (!providerRef) {
         throw new UPPError(
@@ -52,15 +52,15 @@ export function createMessagesLLMHandler(): LLMHandler<XAILLMParams> {
         );
       }
 
-      const model: BoundLLMModel<XAILLMParams> = {
+      const model: BoundLLMModel<XAIMessagesParams> = {
         modelId,
         capabilities: XAI_MESSAGES_CAPABILITIES,
 
-        get provider(): LLMProvider<XAILLMParams> {
+        get provider(): LLMProvider<XAIMessagesParams> {
           return providerRef!;
         },
 
-        async complete(request: LLMRequest<XAILLMParams>): Promise<LLMResponse> {
+        async complete(request: LLMRequest<XAIMessagesParams>): Promise<LLMResponse> {
           const apiKey = await resolveApiKey(
             request.config,
             'XAI_API_KEY',
@@ -92,7 +92,7 @@ export function createMessagesLLMHandler(): LLMHandler<XAILLMParams> {
           return transformResponse(data);
         },
 
-        stream(request: LLMRequest<XAILLMParams>): LLMStreamResult {
+        stream(request: LLMRequest<XAIMessagesParams>): LLMStreamResult {
           const state = createStreamState();
           let responseResolve: (value: LLMResponse) => void;
           let responseReject: (error: Error) => void;

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

@@ -6,7 +6,7 @@ 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 { XAILLMParams, XAIResponsesResponse, XAIResponsesStreamEvent, XAIResponseErrorEvent } from './types.ts';
+import type { XAIResponsesParams, XAIResponsesResponse, XAIResponsesStreamEvent, XAIResponseErrorEvent } from './types.ts';
 import {
   transformRequest,
   transformResponse,
@@ -32,16 +32,16 @@ const XAI_RESPONSES_CAPABILITIES: LLMCapabilities = {
 /**
  * Create xAI Responses API LLM handler
  */
-export function createResponsesLLMHandler(): LLMHandler<XAILLMParams> {
+export function createResponsesLLMHandler(): LLMHandler<XAIResponsesParams> {
   // Provider reference injected by createProvider() or xAI's custom factory
-  let providerRef: LLMProvider<XAILLMParams> | null = null;
+  let providerRef: LLMProvider<XAIResponsesParams> | null = null;
 
   return {
-    _setProvider(provider: LLMProvider<XAILLMParams>) {
+    _setProvider(provider: LLMProvider<XAIResponsesParams>) {
       providerRef = provider;
     },
 
-    bind(modelId: string): BoundLLMModel<XAILLMParams> {
+    bind(modelId: string): BoundLLMModel<XAIResponsesParams> {
       // Use the injected provider reference
       if (!providerRef) {
         throw new UPPError(
@@ -52,15 +52,15 @@ export function createResponsesLLMHandler(): LLMHandler<XAILLMParams> {
         );
       }
 
-      const model: BoundLLMModel<XAILLMParams> = {
+      const model: BoundLLMModel<XAIResponsesParams> = {
         modelId,
         capabilities: XAI_RESPONSES_CAPABILITIES,
 
-        get provider(): LLMProvider<XAILLMParams> {
+        get provider(): LLMProvider<XAIResponsesParams> {
           return providerRef!;
         },
 
-        async complete(request: LLMRequest<XAILLMParams>): Promise<LLMResponse> {
+        async complete(request: LLMRequest<XAIResponsesParams>): Promise<LLMResponse> {
           const apiKey = await resolveApiKey(
             request.config,
             'XAI_API_KEY',
@@ -102,7 +102,7 @@ export function createResponsesLLMHandler(): LLMHandler<XAILLMParams> {
           return transformResponse(data);
         },
 
-        stream(request: LLMRequest<XAILLMParams>): LLMStreamResult {
+        stream(request: LLMRequest<XAIResponsesParams>): LLMStreamResult {
           const state = createStreamState();
           let responseResolve: (value: LLMResponse) => void;
           let responseReject: (error: Error) => void;

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

@@ -11,7 +11,7 @@ import {
   isToolResultMessage,
 } from '../../types/messages.ts';
 import type {
-  XAILLMParams,
+  XAICompletionsParams,
   XAICompletionsRequest,
   XAICompletionsMessage,
   XAIUserContent,
@@ -23,79 +23,30 @@ import type {
 
 /**
  * Transform UPP request to xAI Chat Completions format
+ *
+ * Params are spread directly to allow pass-through of any xAI 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 XAILLMParams>(
-  request: LLMRequest<TParams>,
+export function transformRequest(
+  request: LLMRequest<XAICompletionsParams>,
   modelId: string
 ): XAICompletionsRequest {
-  const params: XAILLMParams = request.params ?? {};
+  const params = request.params ?? ({} as XAICompletionsParams);
 
+  // Spread params to pass through all fields, then set required fields
   const xaiRequest: XAICompletionsRequest = {
+    ...params,
     model: modelId,
     messages: transformMessages(request.messages, request.system),
   };
 
-  // Model parameters
-  if (params.temperature !== undefined) {
-    xaiRequest.temperature = params.temperature;
-  }
-  if (params.top_p !== undefined) {
-    xaiRequest.top_p = params.top_p;
-  }
-  if (params.max_completion_tokens !== undefined) {
-    xaiRequest.max_completion_tokens = params.max_completion_tokens;
-  } else if (params.max_tokens !== undefined) {
-    xaiRequest.max_tokens = params.max_tokens;
-  }
-  if (params.frequency_penalty !== undefined) {
-    xaiRequest.frequency_penalty = params.frequency_penalty;
-  }
-  if (params.presence_penalty !== undefined) {
-    xaiRequest.presence_penalty = params.presence_penalty;
-  }
-  if (params.stop !== undefined) {
-    xaiRequest.stop = params.stop;
-  }
-  if (params.n !== undefined) {
-    xaiRequest.n = params.n;
-  }
-  if (params.logprobs !== undefined) {
-    xaiRequest.logprobs = params.logprobs;
-  }
-  if (params.top_logprobs !== undefined) {
-    xaiRequest.top_logprobs = params.top_logprobs;
-  }
-  if (params.seed !== undefined) {
-    xaiRequest.seed = params.seed;
-  }
-  if (params.user !== undefined) {
-    xaiRequest.user = params.user;
-  }
-  if (params.logit_bias !== undefined) {
-    xaiRequest.logit_bias = params.logit_bias;
-  }
-  if (params.reasoning_effort !== undefined) {
-    xaiRequest.reasoning_effort = params.reasoning_effort;
-  }
-  if (params.store !== undefined) {
-    xaiRequest.store = params.store;
-  }
-  if (params.metadata !== undefined) {
-    xaiRequest.metadata = params.metadata;
-  }
-  if (params.search_parameters !== undefined) {
-    xaiRequest.search_parameters = params.search_parameters;
-  }
-
-  // Tools
+  // Tools come from request, not params
   if (request.tools && request.tools.length > 0) {
     xaiRequest.tools = request.tools.map(transformTool);
-    if (params.parallel_tool_calls !== undefined) {
-      xaiRequest.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',
@@ -118,9 +69,6 @@ export function transformRequest<TParams extends XAILLMParams>(
         strict: true,
       },
     };
-  } else if (params.response_format !== undefined) {
-    // Pass through response_format from params if no structure is defined
-    xaiRequest.response_format = params.response_format;
   }
 
   return xaiRequest;

package/src/providers/xai/transform.messages.ts

@@ -11,7 +11,7 @@ import {
   isToolResultMessage,
 } from '../../types/messages.ts';
 import type {
-  XAILLMParams,
+  XAIMessagesParams,
   XAIMessagesRequest,
   XAIMessagesMessage,
   XAIMessagesContent,
@@ -23,49 +23,30 @@ import type {
 
 /**
  * Transform UPP request to xAI Messages API format (Anthropic-compatible)
+ *
+ * Params are spread directly to allow pass-through of any xAI 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 XAILLMParams>(
-  request: LLMRequest<TParams>,
+export function transformRequest(
+  request: LLMRequest<XAIMessagesParams>,
   modelId: string
 ): XAIMessagesRequest {
-  const params = (request.params ?? {}) as XAILLMParams;
+  const params = request.params ?? ({} as XAIMessagesParams);
 
+  // Spread params to pass through all fields, then set required fields
   const xaiRequest: XAIMessagesRequest = {
+    ...params,
     model: modelId,
     messages: request.messages.map(transformMessage),
   };
 
-  // Only include max_tokens if provided - let API enforce its requirement
-  if (params.max_tokens !== undefined) {
-    xaiRequest.max_tokens = params.max_tokens;
-  }
-
   // System prompt (top-level in Messages API)
   if (request.system) {
     xaiRequest.system = request.system;
   }
 
-  // Model parameters
-  if (params.temperature !== undefined) {
-    xaiRequest.temperature = params.temperature;
-  }
-  if (params.top_p !== undefined) {
-    xaiRequest.top_p = params.top_p;
-  }
-  if (params.top_k !== undefined) {
-    xaiRequest.top_k = params.top_k;
-  }
-  if (params.stop_sequences) {
-    xaiRequest.stop_sequences = params.stop_sequences;
-  }
-  if (params.messages_metadata) {
-    xaiRequest.metadata = params.messages_metadata;
-  }
-  if (params.thinking) {
-    xaiRequest.thinking = params.thinking;
-  }
-
-  // Tools
+  // Tools come from request, not params
   if (request.tools && request.tools.length > 0) {
     xaiRequest.tools = request.tools.map(transformTool);
     xaiRequest.tool_choice = { type: 'auto' };

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

@@ -11,7 +11,7 @@ import {
   isToolResultMessage,
 } from '../../types/messages.ts';
 import type {
-  XAILLMParams,
+  XAIResponsesParams,
   XAIResponsesRequest,
   XAIResponsesInputItem,
   XAIResponsesContentPart,
@@ -25,69 +25,30 @@ import type {
 
 /**
  * Transform UPP request to xAI Responses API format
+ *
+ * Params are spread directly to allow pass-through of any xAI 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 XAILLMParams>(
-  request: LLMRequest<TParams>,
+export function transformRequest(
+  request: LLMRequest<XAIResponsesParams>,
   modelId: string
 ): XAIResponsesRequest {
-  const params: XAILLMParams = request.params ?? {};
+  const params = request.params ?? ({} as XAIResponsesParams);
 
+  // Spread params to pass through all fields, then set required fields
   const xaiRequest: XAIResponsesRequest = {
+    ...params,
     model: modelId,
     input: transformInputItems(request.messages, request.system),
   };
 
-  // Model parameters
-  if (params.temperature !== undefined) {
-    xaiRequest.temperature = params.temperature;
-  }
-  if (params.top_p !== undefined) {
-    xaiRequest.top_p = params.top_p;
-  }
-  if (params.max_output_tokens !== undefined) {
-    xaiRequest.max_output_tokens = params.max_output_tokens;
-  } else if (params.max_completion_tokens !== undefined) {
-    xaiRequest.max_output_tokens = params.max_completion_tokens;
-  } else if (params.max_tokens !== undefined) {
-    xaiRequest.max_output_tokens = params.max_tokens;
-  }
-  if (params.store !== undefined) {
-    xaiRequest.store = params.store;
-  }
-  if (params.metadata !== undefined) {
-    xaiRequest.metadata = params.metadata;
-  }
-  if (params.truncation !== undefined) {
-    xaiRequest.truncation = params.truncation;
-  }
-  if (params.include !== undefined) {
-    xaiRequest.include = params.include;
-  }
-  if (params.previous_response_id !== undefined) {
-    xaiRequest.previous_response_id = params.previous_response_id;
-  }
-  if (params.reasoning !== undefined) {
-    xaiRequest.reasoning = { ...params.reasoning };
-  }
-  if (params.reasoning_effort !== undefined) {
-    xaiRequest.reasoning = {
-      ...(xaiRequest.reasoning ?? {}),
-      effort: params.reasoning_effort,
-    };
-  }
-  if (params.search_parameters !== undefined) {
-    xaiRequest.search_parameters = params.search_parameters;
-  }
-
-  // Tools
+  // Tools come from request, not params
   if (request.tools && request.tools.length > 0) {
     xaiRequest.tools = request.tools.map(transformTool);
-    if (params.parallel_tool_calls !== undefined) {
-      xaiRequest.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/xai/types.ts

@@ -1,31 +1,20 @@
 /**
- * xAI-specific LLM parameters
- * These are passed through to the relevant xAI APIs (Completions, Responses, Messages)
- *
- * xAI's APIs are compatible with OpenAI and Anthropic SDKs, supporting three API modes:
- * - Chat Completions API (OpenAI-compatible)
- * - Responses API (OpenAI Responses-compatible, with stateful conversations)
- * - Messages API (Anthropic-compatible)
- */
-export interface XAILLMParams {
+ * xAI Chat Completions API parameters (OpenAI-compatible)
+ * These are passed through to the /v1/chat/completions endpoint
+ */
+export interface XAICompletionsParams {
   /** Maximum number of tokens to generate */
   max_tokens?: number;
 
-  /** Maximum completion tokens (Chat Completions API) */
+  /** Maximum completion tokens */
   max_completion_tokens?: number;
 
-  /** Maximum output tokens (Responses API) */
-  max_output_tokens?: number;
-
   /** Temperature for randomness (0.0 - 2.0) */
   temperature?: number;
 
   /** Top-p (nucleus) sampling (0.0 - 1.0) */
   top_p?: number;
 
-  /** Top-k sampling (Messages API only) */
-  top_k?: number;
-
   /** Frequency penalty (-2.0 - 2.0) */
   frequency_penalty?: number;
 
@@ -35,9 +24,6 @@ export interface XAILLMParams {
   /** Custom stop sequences */
   stop?: string | string[];
 
-  /** Stop sequences (Messages API) */
-  stop_sequences?: string[];
-
   /** Number of completions to generate */
   n?: number;
 
@@ -53,7 +39,7 @@ export interface XAILLMParams {
   /** User identifier for abuse detection */
   user?: string;
 
-  /** Logit bias map (Chat Completions API) */
+  /** Logit bias map */
   logit_bias?: Record<string, number>;
 
   /** Whether to enable parallel tool calls */
@@ -62,56 +48,100 @@ export interface XAILLMParams {
   /**
    * Reasoning effort for Grok 3 Mini models
    * Note: Only 'low' and 'high' are supported by xAI
-   * Grok 4 does not support this parameter
    */
   reasoning_effort?: 'low' | 'high';
 
-  /** Reasoning configuration (Responses API) */
+  /** Store completion */
+  store?: boolean;
+
+  /** Metadata key-value pairs */
+  metadata?: Record<string, string>;
+
+  /** Response format for structured output */
+  response_format?: XAIResponseFormat;
+
+  /**
+   * Live Search parameters (deprecated, will be removed Dec 15, 2025)
+   * Use Agent Tools API instead for new implementations
+   */
+  search_parameters?: XAISearchParameters;
+}
+
+/**
+ * xAI Responses API parameters (OpenAI Responses-compatible)
+ * These are passed through to the /v1/responses endpoint
+ */
+export interface XAIResponsesParams {
+  /** 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 */
   reasoning?: {
     effort?: 'low' | 'high';
     /** Include encrypted reasoning content for continuation */
     encrypted_content?: boolean;
   };
 
-  /** Truncation strategy (Responses API) */
+  /** Truncation strategy */
   truncation?: 'auto' | 'disabled';
 
-  /** Fields to include in Responses API output */
+  /** Fields to include in output */
   include?: string[];
 
-  /** Continue from a previous response (Responses API) */
+  /** Continue from a previous response */
   previous_response_id?: string;
 
-  /** Store response for continuation (Responses API) */
+  /** Store response for continuation */
   store?: boolean;
 
-  /** Store messages on xAI servers (default: true for Responses API) */
+  /** Store messages on xAI servers (default: true) */
   store_messages?: boolean;
 
   /** Metadata key-value pairs */
   metadata?: Record<string, string>;
 
-  /** Response format for structured output (Chat Completions API only) */
-  response_format?: XAIResponseFormat;
-
   /**
    * Live Search parameters (deprecated, will be removed Dec 15, 2025)
    * Use Agent Tools API instead for new implementations
    */
   search_parameters?: XAISearchParameters;
+}
 
-  /**
-   * Server-side agentic tools (Agent Tools API)
-   * These are executed server-side by xAI
-   */
-  agent_tools?: XAIAgentTool[];
+/**
+ * xAI Messages API parameters (Anthropic-compatible)
+ * These are passed through to the /v1/messages endpoint
+ */
+export interface XAIMessagesParams {
+  /** Maximum number of tokens to generate */
+  max_tokens?: number;
+
+  /** Temperature for randomness (0.0 - 1.0) */
+  temperature?: number;
+
+  /** Top-p (nucleus) sampling (0.0 - 1.0) */
+  top_p?: number;
+
+  /** Top-k sampling */
+  top_k?: number;
+
+  /** Custom stop sequences */
+  stop_sequences?: string[];
 
-  /** Metadata for the request (Messages API) */
-  messages_metadata?: {
+  /** Metadata for the request */
+  metadata?: {
     user_id?: string;
   };
 
-  /** Extended thinking configuration (Messages API) */
+  /** Extended thinking configuration */
   thinking?: {
     type: 'enabled';
     budget_tokens: number;

package/src/xai/index.ts

@@ -29,7 +29,9 @@ export type {
   XAIProvider,
 } from '../providers/xai/index.ts';
 export type {
-  XAILLMParams,
+  XAICompletionsParams,
+  XAIResponsesParams,
+  XAIMessagesParams,
   XAIConfig,
   XAIAPIMode,
   XAIModelOptions,