@providerprotocol/ai 0.0.11 → 0.0.13

package/src/providers/xai/index.ts

@@ -1,223 +0,0 @@
-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

@@ -1,201 +0,0 @@
-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;
-    },
-  };
-}

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

@@ -1,195 +0,0 @@
-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 { XAIMessagesParams, XAIMessagesResponse, XAIMessagesStreamEvent } from './types.ts';
-import {
-  transformRequest,
-  transformResponse,
-  transformStreamEvent,
-  createStreamState,
-  buildResponseFromState,
-} from './transform.messages.ts';
-
-const XAI_MESSAGES_API_URL = 'https://api.x.ai/v1/messages';
-
-/**
- * xAI Messages API capabilities (Anthropic-compatible)
- */
-const XAI_MESSAGES_CAPABILITIES: LLMCapabilities = {
-  streaming: true,
-  tools: true,
-  structuredOutput: true,
-  imageInput: true,
-  videoInput: false,
-  audioInput: false,
-};
-
-/**
- * Create xAI Messages API LLM handler (Anthropic-compatible)
- */
-export function createMessagesLLMHandler(): LLMHandler<XAIMessagesParams> {
-  // Provider reference injected by createProvider() or xAI's custom factory
-  let providerRef: LLMProvider<XAIMessagesParams> | null = null;
-
-  return {
-    _setProvider(provider: LLMProvider<XAIMessagesParams>) {
-      providerRef = provider;
-    },
-
-    bind(modelId: string): BoundLLMModel<XAIMessagesParams> {
-      // 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<XAIMessagesParams> = {
-        modelId,
-        capabilities: XAI_MESSAGES_CAPABILITIES,
-
-        get provider(): LLMProvider<XAIMessagesParams> {
-          return providerRef!;
-        },
-
-        async complete(request: LLMRequest<XAIMessagesParams>): Promise<LLMResponse> {
-          const apiKey = await resolveApiKey(
-            request.config,
-            'XAI_API_KEY',
-            'xai',
-            'llm'
-          );
-
-          const baseUrl = request.config.baseUrl ?? XAI_MESSAGES_API_URL;
-          const body = transformRequest(request, modelId);
-
-          const response = await doFetch(
-            baseUrl,
-            {
-              method: 'POST',
-              headers: {
-                'Content-Type': 'application/json',
-                'x-api-key': apiKey,
-                'anthropic-version': '2023-06-01',
-              },
-              body: JSON.stringify(body),
-              signal: request.signal,
-            },
-            request.config,
-            'xai',
-            'llm'
-          );
-
-          const data = (await response.json()) as XAIMessagesResponse;
-          return transformResponse(data);
-        },
-
-        stream(request: LLMRequest<XAIMessagesParams>): 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_MESSAGES_API_URL;
-              const body = transformRequest(request, modelId);
-              body.stream = true;
-
-              const response = await doStreamFetch(
-                baseUrl,
-                {
-                  method: 'POST',
-                  headers: {
-                    'Content-Type': 'application/json',
-                    'x-api-key': apiKey,
-                    'anthropic-version': '2023-06-01',
-                  },
-                  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)) {
-                // Check for xAI error event
-                if (typeof data === 'object' && data !== null && 'type' in data) {
-                  const event = data as XAIMessagesStreamEvent;
-
-                  if (event.type === 'error') {
-                    const error = new UPPError(
-                      event.error.message,
-                      'PROVIDER_ERROR',
-                      'xai',
-                      'llm'
-                    );
-                    responseReject(error);
-                    throw error;
-                  }
-
-                  const uppEvent = transformStreamEvent(event, state);
-                  if (uppEvent) {
-                    yield uppEvent;
-                  }
-                }
-              }
-
-              // Build final response
-              responseResolve(buildResponseFromState(state));
-            } catch (error) {
-              responseReject(error as Error);
-              throw error;
-            }
-          }
-
-          return {
-            [Symbol.asyncIterator]() {
-              return generateEvents();
-            },
-            response: responsePromise,
-          };
-        },
-      };
-
-      return model;
-    },
-  };
-}