@providerprotocol/ai 0.0.14 → 0.0.15

package/dist/xai/index.d.ts

@@ -117,6 +117,40 @@ interface XAIResponsesParams {
      * Use Agent Tools API instead for new implementations
      */
     search_parameters?: XAISearchParameters;
+    /**
+     * Built-in agentic tools for server-side execution.
+     *
+     * Use the tool helper constructors from the `tools` namespace:
+     * - `tools.webSearch()` - Web search capability
+     * - `tools.xSearch()` - X (Twitter) search capability
+     * - `tools.codeExecution()` - Python code execution
+     * - `tools.fileSearch()` - Document/collections search
+     * - `tools.mcp()` - Remote MCP server connection
+     *
+     * Note: Only available via the Responses API (`api: 'responses'`).
+     *
+     * @example
+     * ```typescript
+     * import { xai, tools } from 'provider-protocol/xai';
+     *
+     * const model = llm({
+     *   model: xai('grok-4-1-fast', { api: 'responses' }),
+     *   params: {
+     *     builtInTools: [
+     *       tools.webSearch(),
+     *       tools.xSearch({ from_date: '2025-01-01' }),
+     *       tools.codeExecution(),
+     *     ],
+     *   },
+     * });
+     * ```
+     */
+    builtInTools?: XAIBuiltInTool[];
+    /**
+     * Maximum agent reasoning turns.
+     * Limits the number of assistant turns, not individual tool calls.
+     */
+    max_turns?: number;
 }
 /**
  * xAI Messages API parameters (Anthropic-compatible).
@@ -209,16 +243,329 @@ interface XAISearchParameters {
     max_search_results?: number;
 }
 /**
- * Server-side agentic tool configuration.
+ * Web search tool for real-time web information retrieval.
+ *
+ * Enables Grok to search the web for up-to-date information.
+ * Pricing: $5 per 1,000 successful tool invocations.
+ *
+ * @example
+ * ```typescript
+ * const tool: XAIWebSearchTool = {
+ *   type: 'web_search',
+ *   allowed_domains: ['wikipedia.org', 'github.com'],
+ * };
+ * ```
+ */
+interface XAIWebSearchTool {
+    /** Tool type identifier */
+    type: 'web_search';
+    /** Restrict to specific domains (max 5, mutually exclusive with excluded_domains) */
+    allowed_domains?: string[];
+    /** Exclude specific domains (max 5, mutually exclusive with allowed_domains) */
+    excluded_domains?: string[];
+    /** Enable image analysis from search results */
+    enable_image_understanding?: boolean;
+}
+/**
+ * X (Twitter) search tool for social media content.
+ *
+ * Enables Grok to search X posts and profiles in real-time.
+ * Pricing: $5 per 1,000 successful tool invocations.
+ *
+ * @example
+ * ```typescript
+ * const tool: XAIXSearchTool = {
+ *   type: 'x_search',
+ *   allowed_x_handles: ['elonmusk', 'xai'],
+ *   from_date: '2025-01-01',
+ * };
+ * ```
+ */
+interface XAIXSearchTool {
+    /** Tool type identifier */
+    type: 'x_search';
+    /** Limit to specific X handles (max 10, mutually exclusive with excluded_x_handles) */
+    allowed_x_handles?: string[];
+    /** Exclude specific X handles (max 10, "grok" excluded by default) */
+    excluded_x_handles?: string[];
+    /** Start date filter (YYYY-MM-DD) */
+    from_date?: string;
+    /** End date filter (YYYY-MM-DD) */
+    to_date?: string;
+    /** Enable image analysis in posts */
+    enable_image_understanding?: boolean;
+    /** Enable video analysis in posts */
+    enable_video_understanding?: boolean;
+}
+/**
+ * Code execution tool for Python in a sandbox.
+ *
+ * Enables Grok to write and execute Python code in a secure environment.
+ * Pricing: $5 per 1,000 successful tool invocations.
+ *
+ * @example
+ * ```typescript
+ * const tool: XAICodeExecutionTool = {
+ *   type: 'code_interpreter',
+ *   container: {
+ *     pip_packages: ['numpy', 'pandas'],
+ *   },
+ * };
+ * ```
+ */
+interface XAICodeExecutionTool {
+    /** Tool type identifier */
+    type: 'code_interpreter';
+    /** Container configuration */
+    container?: {
+        /** Additional pip packages to install */
+        pip_packages?: string[];
+    };
+}
+/**
+ * File/collections search tool for document retrieval.
+ *
+ * Enables Grok to search through uploaded document collections.
+ * Pricing: $2.50 per 1,000 successful tool invocations.
+ *
+ * @example
+ * ```typescript
+ * const tool: XAIFileSearchTool = {
+ *   type: 'file_search',
+ *   vector_store_ids: ['vs_abc123'],
+ *   max_num_results: 10,
+ * };
+ * ```
+ */
+interface XAIFileSearchTool {
+    /** Tool type identifier */
+    type: 'file_search';
+    /** Collection/vector store IDs to search */
+    vector_store_ids: string[];
+    /** Maximum results to return */
+    max_num_results?: number;
+    /** Retrieval mode configuration */
+    retrieval_mode?: {
+        type: 'keyword' | 'semantic' | 'hybrid';
+    };
+}
+/**
+ * Remote MCP server tool configuration.
+ *
+ * Enables Grok to connect to external Model Context Protocol servers.
+ * Pricing: Token-based only (no per-invocation charge).
+ *
+ * @example
+ * ```typescript
+ * const tool: XAIMcpTool = {
+ *   type: 'mcp',
+ *   server_url: 'https://my-mcp-server.com/sse',
+ *   server_label: 'my_tools',
+ * };
+ * ```
+ */
+interface XAIMcpTool {
+    /** Tool type identifier */
+    type: 'mcp';
+    /** MCP server URL (HTTP Streaming/SSE only) */
+    server_url: string;
+    /** Server label for tool call prefixing */
+    server_label?: string;
+    /** Description of server capabilities */
+    server_description?: string;
+    /** Specific tools to enable (empty = all available) */
+    allowed_tool_names?: string[];
+    /** Authentication token */
+    authorization?: string;
+    /** Custom request headers */
+    extra_headers?: Record<string, string>;
+}
+/**
+ * Union type for all xAI built-in tools.
+ *
+ * These tools are only available via the Responses API (`api: 'responses'`).
+ * They run server-side and provide agentic capabilities.
+ */
+type XAIBuiltInTool = XAIWebSearchTool | XAIXSearchTool | XAICodeExecutionTool | XAIFileSearchTool | XAIMcpTool;
+/**
+ * Server-side tool usage tracking returned in responses.
+ */
+interface XAIServerSideToolUsage {
+    /** Number of successful web searches */
+    web_search?: number;
+    /** Number of successful X searches */
+    x_search?: number;
+    /** Number of successful code executions */
+    code_execution?: number;
+    /** Number of successful file searches */
+    file_search?: number;
+}
+/**
+ * Creates a web search tool configuration.
+ *
+ * Enables Grok to search the web for up-to-date information.
+ * Pricing: $5 per 1,000 successful tool invocations.
+ *
+ * @param options - Optional configuration for search behavior
+ * @returns A web search tool configuration object
+ *
+ * @example
+ * ```typescript
+ * // Basic web search
+ * const search = webSearchTool();
+ *
+ * // With domain restrictions
+ * const searchWithDomains = webSearchTool({
+ *   allowed_domains: ['wikipedia.org', 'github.com'],
+ * });
+ * ```
+ */
+declare function webSearchTool(options?: {
+    allowed_domains?: string[];
+    excluded_domains?: string[];
+    enable_image_understanding?: boolean;
+}): XAIWebSearchTool;
+/**
+ * Creates an X (Twitter) search tool configuration.
+ *
+ * Enables Grok to search X posts and profiles in real-time.
+ * Pricing: $5 per 1,000 successful tool invocations.
+ *
+ * @param options - Optional configuration for search behavior
+ * @returns An X search tool configuration object
+ *
+ * @example
+ * ```typescript
+ * // Basic X search
+ * const xSearch = xSearchTool();
+ *
+ * // With handle and date filters
+ * const filteredSearch = xSearchTool({
+ *   allowed_x_handles: ['elonmusk', 'xai'],
+ *   from_date: '2025-01-01',
+ *   to_date: '2025-12-31',
+ * });
+ * ```
+ */
+declare function xSearchTool(options?: {
+    allowed_x_handles?: string[];
+    excluded_x_handles?: string[];
+    from_date?: string;
+    to_date?: string;
+    enable_image_understanding?: boolean;
+    enable_video_understanding?: boolean;
+}): XAIXSearchTool;
+/**
+ * Creates a code execution tool configuration.
+ *
+ * Enables Grok to write and execute Python code in a sandbox.
+ * Pricing: $5 per 1,000 successful tool invocations.
+ *
+ * @param options - Optional configuration for the execution environment
+ * @returns A code execution tool configuration object
+ *
+ * @example
+ * ```typescript
+ * // Basic code execution
+ * const codeExec = codeExecutionTool();
+ *
+ * // With additional packages
+ * const codeExecWithPackages = codeExecutionTool({
+ *   pip_packages: ['numpy', 'pandas', 'scipy'],
+ * });
+ * ```
+ */
+declare function codeExecutionTool(options?: {
+    pip_packages?: string[];
+}): XAICodeExecutionTool;
+/**
+ * Creates a file/collections search tool configuration.
+ *
+ * Enables Grok to search through uploaded document collections.
+ * Pricing: $2.50 per 1,000 successful tool invocations.
+ *
+ * @param options - File search configuration
+ * @returns A file search tool configuration object
+ *
+ * @example
+ * ```typescript
+ * const fileSearch = fileSearchTool({
+ *   vector_store_ids: ['vs_abc123'],
+ *   max_num_results: 10,
+ *   retrieval_mode: 'hybrid',
+ * });
+ * ```
+ */
+declare function fileSearchTool(options: {
+    vector_store_ids: string[];
+    max_num_results?: number;
+    retrieval_mode?: 'keyword' | 'semantic' | 'hybrid';
+}): XAIFileSearchTool;
+/**
+ * Creates a remote MCP server tool configuration.
+ *
+ * Enables Grok to connect to external Model Context Protocol servers.
+ * Pricing: Token-based only (no per-invocation charge).
+ *
+ * @param options - MCP server configuration
+ * @returns An MCP tool configuration object
+ *
+ * @example
+ * ```typescript
+ * const mcp = mcpTool({
+ *   server_url: 'https://my-mcp-server.com/sse',
+ *   server_label: 'my_tools',
+ *   allowed_tool_names: ['get_weather', 'search_db'],
+ * });
+ * ```
+ */
+declare function mcpTool(options: {
+    server_url: string;
+    server_label?: string;
+    server_description?: string;
+    allowed_tool_names?: string[];
+    authorization?: string;
+    extra_headers?: Record<string, string>;
+}): XAIMcpTool;
+/**
+ * Namespace object containing all xAI tool helper constructors.
  *
- * These tools run on xAI's servers and provide capabilities like
- * web search, X (Twitter) search, and code execution.
+ * Provides a convenient way to create built-in tool configurations.
+ * Note: These tools are only available via the Responses API (`api: 'responses'`).
  *
  * @example
  * ```typescript
- * const tool: XAIAgentTool = { type: 'web_search' };
+ * import { xai, tools } from 'provider-protocol/xai';
+ *
+ * const model = llm({
+ *   model: xai('grok-4-1-fast', { api: 'responses' }),
+ *   params: {
+ *     builtInTools: [
+ *       tools.webSearch(),
+ *       tools.xSearch({ from_date: '2025-01-01' }),
+ *       tools.codeExecution(),
+ *     ],
+ *     include: ['inline_citations', 'code_execution_call_output'],
+ *   },
+ * });
  * ```
  */
+declare const tools: {
+    /** Creates a web search tool configuration */
+    webSearch: typeof webSearchTool;
+    /** Creates an X (Twitter) search tool configuration */
+    xSearch: typeof xSearchTool;
+    /** Creates a code execution tool configuration */
+    codeExecution: typeof codeExecutionTool;
+    /** Creates a file/collections search tool configuration */
+    fileSearch: typeof fileSearchTool;
+    /** Creates a remote MCP server tool configuration */
+    mcp: typeof mcpTool;
+};
+/**
+ * @deprecated Use the specific tool interfaces and the `tools` namespace instead.
+ * This basic type is maintained for backwards compatibility.
+ */
 interface XAIAgentTool {
     /** The type of server-side tool to enable */
     type: 'web_search' | 'x_search' | 'code_execution';
@@ -243,6 +590,21 @@ type XAIResponseFormat = {
         strict?: boolean;
     };
 };
+/**
+ * xAI-specific HTTP headers for API requests.
+ *
+ * @example
+ * ```typescript
+ * const headers: XAIHeaders = {
+ *   'X-Client-Request-Id': 'trace-123',
+ * };
+ * ```
+ */
+interface XAIHeaders {
+    /** Client-generated request ID for tracing. */
+    'X-Client-Request-Id'?: string;
+    [key: string]: string | undefined;
+}
 
 /**
  * Union type for LLM parameters across all xAI API modes.
@@ -378,4 +740,4 @@ interface XAIProvider extends Provider<XAIProviderOptions> {
  */
 declare const xai: XAIProvider;
 
-export { type XAIAPIMode, type XAIAgentTool, type XAICompletionsParams, type XAIConfig, type XAIMessagesParams, type XAIModelOptions, type XAIModelReference, type XAIProvider, type XAIProviderOptions, type XAIResponsesParams, type XAISearchParameters, xai };
+export { type XAIAPIMode, type XAIAgentTool, type XAIBuiltInTool, type XAICodeExecutionTool, type XAICompletionsParams, type XAIConfig, type XAIFileSearchTool, type XAIHeaders, type XAIMcpTool, type XAIMessagesParams, type XAIModelOptions, type XAIModelReference, type XAIProvider, type XAIProviderOptions, type XAIResponsesParams, type XAISearchParameters, type XAIServerSideToolUsage, type XAIWebSearchTool, type XAIXSearchTool, tools, xai };

package/dist/xai/index.js

@@ -1726,6 +1726,52 @@ function createMessagesLLMHandler() {
   };
 }
 
+// src/providers/xai/types.ts
+function webSearchTool(options) {
+  return {
+    type: "web_search",
+    ...options
+  };
+}
+function xSearchTool(options) {
+  return {
+    type: "x_search",
+    ...options
+  };
+}
+function codeExecutionTool(options) {
+  return {
+    type: "code_interpreter",
+    ...options?.pip_packages && { container: { pip_packages: options.pip_packages } }
+  };
+}
+function fileSearchTool(options) {
+  return {
+    type: "file_search",
+    vector_store_ids: options.vector_store_ids,
+    ...options.max_num_results !== void 0 && { max_num_results: options.max_num_results },
+    ...options.retrieval_mode && { retrieval_mode: { type: options.retrieval_mode } }
+  };
+}
+function mcpTool(options) {
+  return {
+    type: "mcp",
+    ...options
+  };
+}
+var tools = {
+  /** Creates a web search tool configuration */
+  webSearch: webSearchTool,
+  /** Creates an X (Twitter) search tool configuration */
+  xSearch: xSearchTool,
+  /** Creates a code execution tool configuration */
+  codeExecution: codeExecutionTool,
+  /** Creates a file/collections search tool configuration */
+  fileSearch: fileSearchTool,
+  /** Creates a remote MCP server tool configuration */
+  mcp: mcpTool
+};
+
 // src/providers/xai/index.ts
 function createXAIProvider() {
   let currentApiMode = "completions";
@@ -1775,6 +1821,7 @@ function createXAIProvider() {
 }
 var xai = createXAIProvider();
 export {
+  tools,
   xai
 };
 //# sourceMappingURL=index.js.map