@providerprotocol/ai 0.0.3 → 0.0.5

package/dist/xai/index.d.ts

@@ -0,0 +1,282 @@
+import { b as Provider, M as ModelReference, a as LLMHandler } from '../provider-CUJWjgNl.js';
+
+/**
+ * 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)
+ */
+interface XAILLMParams {
+    /** Maximum number of tokens to generate */
+    max_tokens?: number;
+    /** Maximum completion tokens (Chat Completions API) */
+    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;
+    /** Presence penalty (-2.0 - 2.0) */
+    presence_penalty?: number;
+    /** Custom stop sequences */
+    stop?: string | string[];
+    /** Stop sequences (Messages API) */
+    stop_sequences?: string[];
+    /** Number of completions to generate */
+    n?: number;
+    /** Enable logprobs */
+    logprobs?: boolean;
+    /** Number of top logprobs to return (0-20) */
+    top_logprobs?: number;
+    /** Seed for deterministic sampling */
+    seed?: number;
+    /** User identifier for abuse detection */
+    user?: string;
+    /** Logit bias map (Chat Completions API) */
+    logit_bias?: Record<string, number>;
+    /** Whether to enable parallel tool calls */
+    parallel_tool_calls?: boolean;
+    /**
+     * 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) */
+    reasoning?: {
+        effort?: 'low' | 'high';
+        /** Include encrypted reasoning content for continuation */
+        encrypted_content?: boolean;
+    };
+    /** Truncation strategy (Responses API) */
+    truncation?: 'auto' | 'disabled';
+    /** Fields to include in Responses API output */
+    include?: string[];
+    /** Continue from a previous response (Responses API) */
+    previous_response_id?: string;
+    /** Store response for continuation (Responses API) */
+    store?: boolean;
+    /** Store messages on xAI servers (default: true for Responses API) */
+    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[];
+    /** Metadata for the request (Messages API) */
+    messages_metadata?: {
+        user_id?: string;
+    };
+    /** Extended thinking configuration (Messages API) */
+    thinking?: {
+        type: 'enabled';
+        budget_tokens: number;
+    };
+}
+/**
+ * API mode for xAI provider
+ */
+type XAIAPIMode = 'completions' | 'responses' | 'messages';
+/**
+ * Model options when creating a model reference
+ */
+interface XAIModelOptions {
+    /** Which API to use */
+    api?: XAIAPIMode;
+}
+/**
+ * Model reference with xAI-specific options
+ */
+interface XAIModelReference {
+    modelId: string;
+    options?: XAIModelOptions;
+}
+/**
+ * xAI provider configuration
+ */
+interface XAIConfig {
+    /** Which API to use: 'completions', 'responses', or 'messages' */
+    api?: XAIAPIMode;
+}
+/**
+ * Live Search parameters (deprecated)
+ */
+interface XAISearchParameters {
+    /** Search mode */
+    mode?: 'auto' | 'on' | 'off';
+    /** Limit search to specific date range */
+    from_date?: string;
+    /** End date for search range */
+    to_date?: string;
+    /** Sources to search */
+    sources?: Array<'web' | 'x' | 'news' | 'rss'>;
+    /** Maximum number of search results */
+    max_search_results?: number;
+}
+/**
+ * Server-side agentic tools
+ */
+interface XAIAgentTool {
+    type: 'web_search' | 'x_search' | 'code_execution';
+}
+/**
+ * Response format
+ */
+type XAIResponseFormat = {
+    type: 'text';
+} | {
+    type: 'json_object';
+} | {
+    type: 'json_schema';
+    json_schema: {
+        name: string;
+        description?: string;
+        schema: Record<string, unknown>;
+        strict?: boolean;
+    };
+};
+
+/**
+ * xAI provider options
+ */
+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' });
+ */
+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<XAILLMParams>;
+    };
+}
+/**
+ * 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);
+ * ```
+ */
+declare const xai: XAIProvider;
+
+export { type XAIAPIMode, type XAIAgentTool, type XAIConfig, type XAILLMParams, type XAIModelOptions, type XAIModelReference, type XAIProvider, type XAIProviderOptions, type XAISearchParameters, xai };