@providerprotocol/ai 0.0.12 → 0.0.13

package/dist/openai/index.d.ts

@@ -1,17 +1,40 @@
-import { b as Provider, M as ModelReference, a as LLMHandler } from '../provider-CUJWjgNl.js';
+import { b as Provider, M as ModelReference, a as LLMHandler } from '../provider-mKkz7Q9U.js';
 
 /**
- * Audio output configuration for Chat Completions
+ * @fileoverview OpenAI Provider Type Definitions
+ *
+ * This module contains all TypeScript type definitions for the OpenAI provider,
+ * including types for both the Chat Completions API and the Responses API.
+ *
+ * The types are organized into sections:
+ * - Audio Configuration Types
+ * - Web Search Configuration Types
+ * - Chat Completions API Parameters and Types
+ * - Responses API Parameters and Types
+ * - Built-in Tools for Responses API
+ * - Tool Helper Constructors
+ *
+ * @module providers/openai/types
+ */
+/**
+ * Audio output configuration for Chat Completions API.
+ *
+ * Enables audio output generation when using models that support
+ * the audio modality. Requires `modalities: ['text', 'audio']`.
  */
 interface OpenAIAudioConfig {
-    /** Audio format */
+    /** Audio format for the generated output */
     format: 'wav' | 'aac' | 'mp3' | 'flac' | 'opus' | 'pcm16';
-    /** Voice to use for audio generation */
+    /** Voice model to use for audio generation */
     voice: 'alloy' | 'ash' | 'ballad' | 'coral' | 'echo' | 'sage' | 'shimmer' | 'verse' | 'marin' | 'cedar';
 }
 /**
- * User location for web search context (Responses API format)
- * Fields are at the same level as type
+ * User location for web search context in the Responses API.
+ *
+ * Used to localize web search results based on the user's approximate location.
+ * In the Responses API, location fields are at the same level as the type field.
+ *
+ * @see {@link OpenAICompletionsWebSearchUserLocation} for the Chat Completions API version
  */
 interface OpenAIWebSearchUserLocation {
     /** Location type - must be 'approximate' */
@@ -26,8 +49,12 @@ interface OpenAIWebSearchUserLocation {
     timezone?: string;
 }
 /**
- * User location for web search context (Chat Completions API format)
- * Fields are nested under 'approximate' object
+ * User location for web search context in the Chat Completions API.
+ *
+ * Used to localize web search results based on the user's approximate location.
+ * In the Completions API, location fields are nested under an `approximate` object.
+ *
+ * @see {@link OpenAIWebSearchUserLocation} for the Responses API version
  */
 interface OpenAICompletionsWebSearchUserLocation {
     /** Location type - must be 'approximate' */
@@ -45,8 +72,10 @@ interface OpenAICompletionsWebSearchUserLocation {
     };
 }
 /**
- * Web search options for Chat Completions API
- * Use with gpt-5-search-api-* models
+ * Web search configuration options for the Chat Completions API.
+ *
+ * Enables web search capabilities when using search-enabled models.
+ * Use with models that support web search (e.g., gpt-4o-search-preview).
  */
 interface OpenAIWebSearchOptions {
     /**
@@ -58,8 +87,22 @@ interface OpenAIWebSearchOptions {
     user_location?: OpenAICompletionsWebSearchUserLocation | null;
 }
 /**
- * OpenAI Chat Completions API parameters
- * These are passed through to the /v1/chat/completions endpoint
+ * Parameters for the OpenAI Chat Completions API.
+ *
+ * These parameters are passed directly to the `/v1/chat/completions` endpoint.
+ * The Chat Completions API is the legacy API for chat interactions with
+ * OpenAI models. For the modern API with built-in tools, see {@link OpenAIResponsesParams}.
+ *
+ * @example
+ * ```typescript
+ * const params: OpenAICompletionsParams = {
+ *   temperature: 0.7,
+ *   max_tokens: 1000,
+ *   reasoning_effort: 'medium'
+ * };
+ * ```
+ *
+ * @see {@link OpenAIResponsesParams} for the modern Responses API parameters
  */
 interface OpenAICompletionsParams {
     /** Maximum number of tokens to generate (legacy, prefer max_completion_tokens) */
@@ -145,7 +188,9 @@ interface OpenAICompletionsParams {
     web_search_options?: OpenAIWebSearchOptions;
 }
 /**
- * Prompt template reference for Responses API
+ * Reference to a prompt template stored in OpenAI's system.
+ *
+ * Allows using pre-defined prompt templates with variable substitution.
  */
 interface OpenAIPromptTemplate {
     /** Prompt template ID */
@@ -154,16 +199,43 @@ interface OpenAIPromptTemplate {
     variables?: Record<string, string>;
 }
 /**
- * Conversation reference for Responses API
- * Items from this conversation are prepended to input_items
+ * Reference to an existing conversation for the Responses API.
+ *
+ * Items from this conversation are prepended to the input items,
+ * enabling multi-turn conversations without resending full history.
+ * Cannot be used together with `previous_response_id`.
  */
 interface OpenAIConversation {
     /** Conversation ID */
     id: string;
 }
 /**
- * OpenAI Responses API parameters
- * These are passed through to the /v1/responses endpoint
+ * Parameters for the OpenAI Responses API.
+ *
+ * These parameters are passed directly to the `/v1/responses` endpoint.
+ * The Responses API is the modern, recommended API that supports built-in
+ * tools like web search, image generation, file search, and code interpreter.
+ *
+ * @example Basic usage
+ * ```typescript
+ * const params: OpenAIResponsesParams = {
+ *   max_output_tokens: 1000,
+ *   temperature: 0.7,
+ *   reasoning: { effort: 'medium' }
+ * };
+ * ```
+ *
+ * @example With built-in tools
+ * ```typescript
+ * import { tools } from './types';
+ *
+ * const params: OpenAIResponsesParams = {
+ *   max_output_tokens: 2000,
+ *   tools: [tools.webSearch(), tools.imageGeneration()]
+ * };
+ * ```
+ *
+ * @see {@link OpenAICompletionsParams} for the legacy Chat Completions API parameters
  */
 interface OpenAIResponsesParams {
     /** Maximum output tokens */
@@ -259,32 +331,38 @@ interface OpenAIResponsesParams {
     tools?: OpenAIBuiltInTool[];
 }
 /**
- * API mode for OpenAI provider
+ * The API mode for the OpenAI provider.
+ *
+ * - `'responses'` - Modern Responses API (recommended)
+ * - `'completions'` - Legacy Chat Completions API
  */
 type OpenAIAPIMode = 'responses' | 'completions';
 /**
- * Model options when creating a model reference
+ * Options when creating an OpenAI model reference.
  */
 interface OpenAIModelOptions {
     /** Which API to use */
     api?: OpenAIAPIMode;
 }
 /**
- * Model reference with OpenAI-specific options
+ * Model reference with OpenAI-specific options.
+ * Used internally to track the selected model and API mode.
  */
 interface OpenAIModelReference {
+    /** The OpenAI model identifier (e.g., 'gpt-4o', 'o1-preview') */
     modelId: string;
+    /** Optional model-specific options */
     options?: OpenAIModelOptions;
 }
 /**
- * OpenAI provider configuration
+ * Configuration options for the OpenAI provider.
  */
 interface OpenAIConfig {
     /** Which API to use: 'responses' (modern) or 'completions' (legacy) */
     api?: 'responses' | 'completions';
 }
 /**
- * Response format
+ * Response format options for structured output.
  */
 type OpenAIResponseFormat = {
     type: 'text';
@@ -300,7 +378,8 @@ type OpenAIResponseFormat = {
     };
 };
 /**
- * Tool definition for Responses API
+ * Function tool definition for the Responses API.
+ * Uses a flatter structure than Chat Completions.
  */
 interface OpenAIResponsesTool {
     type: 'function';
@@ -467,15 +546,48 @@ type OpenAIBuiltInTool = OpenAIWebSearchTool | OpenAIFileSearchTool | OpenAICode
  */
 type OpenAIResponsesToolUnion = OpenAIResponsesTool | OpenAIBuiltInTool;
 /**
- * Helper to create a web search tool
- * Note: Configuration options are passed at the top level, not nested
+ * Creates a web search tool configuration for the Responses API.
+ *
+ * The web search tool enables the model to search the web for up-to-date information.
+ *
+ * @param options - Optional configuration for search behavior and user location
+ * @returns A web search tool configuration object
+ *
+ * @example
+ * ```typescript
+ * // Basic web search
+ * const search = webSearchTool();
+ *
+ * // With configuration
+ * const searchWithLocation = webSearchTool({
+ *   search_context_size: 'high',
+ *   user_location: {
+ *     type: 'approximate',
+ *     city: 'San Francisco',
+ *     country: 'US'
+ *   }
+ * });
+ * ```
  */
 declare function webSearchTool(options?: {
     search_context_size?: 'low' | 'medium' | 'high';
     user_location?: OpenAIWebSearchUserLocation | null;
 }): OpenAIWebSearchTool;
 /**
- * Helper to create a file search tool
+ * Creates a file search tool configuration for the Responses API.
+ *
+ * The file search tool enables the model to search through files in vector stores.
+ *
+ * @param options - Configuration including vector store IDs and search options
+ * @returns A file search tool configuration object
+ *
+ * @example
+ * ```typescript
+ * const fileSearch = fileSearchTool({
+ *   vector_store_ids: ['vs_abc123'],
+ *   max_num_results: 10
+ * });
+ * ```
  */
 declare function fileSearchTool(options: {
     vector_store_ids: string[];
@@ -487,13 +599,49 @@ declare function fileSearchTool(options: {
     filters?: Record<string, unknown>;
 }): OpenAIFileSearchTool;
 /**
- * Helper to create a code interpreter tool
+ * Creates a code interpreter tool configuration for the Responses API.
+ *
+ * The code interpreter tool allows the model to write and execute Python code
+ * in a sandboxed environment.
+ *
+ * @param options - Optional container configuration
+ * @returns A code interpreter tool configuration object
+ *
+ * @example
+ * ```typescript
+ * // Default configuration
+ * const interpreter = codeInterpreterTool();
+ *
+ * // With custom container settings
+ * const customInterpreter = codeInterpreterTool({
+ *   container: {
+ *     type: 'auto',
+ *     memory_limit: '4g',
+ *     file_ids: ['file_abc123']
+ *   }
+ * });
+ * ```
  */
 declare function codeInterpreterTool(options?: {
     container?: string | OpenAICodeInterpreterContainer;
 }): OpenAICodeInterpreterTool;
 /**
- * Helper to create a computer tool
+ * Creates a computer tool configuration for the Responses API.
+ *
+ * The computer tool enables the model to interact with computer interfaces
+ * through mouse and keyboard actions.
+ *
+ * @param options - Display configuration and environment settings
+ * @returns A computer tool configuration object
+ *
+ * @example
+ * ```typescript
+ * const computer = computerTool({
+ *   display_width: 1920,
+ *   display_height: 1080,
+ *   environment: { type: 'browser' }
+ * });
+ * ```
  */
 declare function computerTool(options: {
     display_width: number;
@@ -501,8 +649,25 @@ declare function computerTool(options: {
     environment?: OpenAIComputerEnvironment;
 }): OpenAIComputerTool;
 /**
- * Helper to create an image generation tool
- * Note: Configuration options are passed at the top level, not nested
+ * Creates an image generation tool configuration for the Responses API.
+ *
+ * The image generation tool allows the model to generate images based on prompts.
+ *
+ * @param options - Optional image generation settings
+ * @returns An image generation tool configuration object
+ *
+ * @example
+ * ```typescript
+ * // Default configuration
+ * const imageGen = imageGenerationTool();
+ *
+ * // With custom settings
+ * const customImageGen = imageGenerationTool({
+ *   quality: 'high',
+ *   size: '1024x1024',
+ *   background: 'transparent'
+ * });
+ * ```
  */
 declare function imageGenerationTool(options?: {
     background?: 'transparent' | 'opaque' | 'auto';
@@ -512,7 +677,22 @@ declare function imageGenerationTool(options?: {
     output_format?: 'png' | 'jpeg' | 'webp';
 }): OpenAIImageGenerationTool;
 /**
- * Helper to create an MCP tool
+ * Creates an MCP (Model Context Protocol) tool configuration for the Responses API.
+ *
+ * The MCP tool enables connections to external MCP servers, allowing the model
+ * to use tools and resources provided by those servers.
+ *
+ * @param options - MCP server configuration
+ * @returns An MCP tool configuration object
+ *
+ * @example
+ * ```typescript
+ * const mcp = mcpTool({
+ *   url: 'https://mcp-server.example.com',
+ *   name: 'my-mcp-server',
+ *   allowed_tools: ['tool1', 'tool2']
+ * });
+ * ```
  */
 declare function mcpTool(options: {
     url: string;
@@ -527,86 +707,185 @@ declare function mcpTool(options: {
     };
 }): OpenAIMcpTool;
 /**
- * Namespace for tool helper constructors
+ * Namespace object containing all tool helper constructors.
+ *
+ * Provides a convenient way to create built-in tool configurations
+ * for the Responses API.
+ *
+ * @example
+ * ```typescript
+ * import { tools } from './types';
+ *
+ * const params = {
+ *   tools: [
+ *     tools.webSearch(),
+ *     tools.imageGeneration({ quality: 'high' }),
+ *     tools.codeInterpreter()
+ *   ]
+ * };
+ * ```
  */
 declare const tools: {
+    /** Creates a web search tool configuration */
     webSearch: typeof webSearchTool;
+    /** Creates a file search tool configuration */
     fileSearch: typeof fileSearchTool;
+    /** Creates a code interpreter tool configuration */
     codeInterpreter: typeof codeInterpreterTool;
+    /** Creates a computer tool configuration */
     computer: typeof computerTool;
+    /** Creates an image generation tool configuration */
     imageGeneration: typeof imageGenerationTool;
+    /** Creates an MCP tool configuration */
     mcp: typeof mcpTool;
 };
 
-/** Union type for modalities interface */
+/**
+ * @fileoverview OpenAI Provider Factory
+ *
+ * This module provides the main OpenAI provider implementation that supports both
+ * the modern Responses API (default) and the legacy Chat Completions API.
+ *
+ * @example
+ * ```typescript
+ * import { openai } from './providers/openai';
+ * import { llm } from './core/llm';
+ *
+ * // Using the modern Responses API (default)
+ * const model = llm({
+ *   model: openai('gpt-4o'),
+ *   params: { max_output_tokens: 1000 }
+ * });
+ *
+ * // Using the legacy Chat Completions API
+ * const legacyModel = llm({
+ *   model: openai('gpt-4o', { api: 'completions' }),
+ *   params: { max_tokens: 1000 }
+ * });
+ * ```
+ *
+ * @module providers/openai
+ */
+
+/**
+ * Union type for the LLM handler that supports both API modes.
+ * Used internally for the dynamic handler selection based on API mode.
+ */
 type OpenAILLMParamsUnion = OpenAICompletionsParams | OpenAIResponsesParams;
 /**
- * OpenAI provider options
+ * Configuration options for the OpenAI provider.
+ *
+ * Controls which underlying OpenAI API endpoint is used when making requests.
+ * The Responses API is the modern, recommended approach while the Chat Completions
+ * API provides backward compatibility with existing integrations.
  */
 interface OpenAIProviderOptions {
     /**
-     * Which API to use:
-     * - 'responses': Modern Responses API (default, recommended)
-     * - 'completions': Legacy Chat Completions API
+     * Which API endpoint to use for requests.
+     *
+     * - `'responses'` - Modern Responses API (default, recommended). Supports built-in
+     *   tools like web search, image generation, file search, and code interpreter.
+     * - `'completions'` - Legacy Chat Completions API. Standard chat completion endpoint
+     *   with function calling support.
+     *
+     * @default 'responses'
      */
     api?: 'responses' | 'completions';
 }
 /**
- * OpenAI provider with configurable API mode
+ * OpenAI provider interface with configurable API mode.
  *
- * @example
- * // Using the modern Responses API (default)
+ * The provider is callable as a function to create model references, and also
+ * exposes metadata about the provider and its supported modalities.
+ *
+ * @example Creating model references
+ * ```typescript
+ * // Using the modern Responses API (default, recommended)
  * const model = openai('gpt-4o');
  *
- * @example
  * // Using the legacy Chat Completions API
- * const model = openai('gpt-4o', { api: 'completions' });
+ * const legacyModel = openai('gpt-4o', { api: 'completions' });
  *
- * @example
- * // Explicit Responses API
- * const model = openai('gpt-4o', { api: 'responses' });
+ * // Explicit Responses API selection
+ * const responsesModel = openai('gpt-4o', { api: 'responses' });
+ * ```
+ *
+ * @see {@link OpenAIProviderOptions} for available configuration options
+ * @see {@link OpenAIResponsesParams} for Responses API parameters
+ * @see {@link OpenAICompletionsParams} for Chat Completions API parameters
  */
 interface OpenAIProvider extends Provider<OpenAIProviderOptions> {
     /**
-     * Create a model reference
-     * @param modelId - The model identifier (e.g., 'gpt-4o', 'gpt-4-turbo', 'o1-preview')
-     * @param options - Provider options including API selection
+     * Creates a model reference for the specified OpenAI model.
+     *
+     * @param modelId - The OpenAI model identifier (e.g., 'gpt-4o', 'gpt-4-turbo', 'o1-preview', 'gpt-4o-mini')
+     * @param options - Optional provider configuration including API mode selection
+     * @returns A model reference that can be used with the LLM core functions
+     *
+     * @example
+     * ```typescript
+     * const gpt4o = openai('gpt-4o');
+     * const gpt4turbo = openai('gpt-4-turbo', { api: 'completions' });
+     * ```
      */
     (modelId: string, options?: OpenAIProviderOptions): ModelReference<OpenAIProviderOptions>;
-    /** Provider name */
+    /**
+     * The provider identifier.
+     * Always returns `'openai'` for this provider.
+     */
     readonly name: 'openai';
-    /** Provider version */
+    /**
+     * The provider version following semantic versioning.
+     */
     readonly version: string;
-    /** Supported modalities */
+    /**
+     * Supported modalities and their handlers.
+     * Currently supports LLM modality with both Responses and Completions API handlers.
+     */
     readonly modalities: {
+        /** The LLM handler for text generation and chat completion */
         llm: LLMHandler<OpenAILLMParamsUnion>;
     };
 }
 /**
- * OpenAI provider
+ * The OpenAI provider instance.
  *
- * Supports both the modern Responses API (default) and legacy Chat Completions API.
+ * Supports both the modern Responses API (default) and the legacy Chat Completions API.
+ * Use this provider to create model references for OpenAI models like GPT-4o, GPT-4 Turbo,
+ * and the o1 series.
  *
- * @example
- * ```ts
+ * @example Basic usage with Responses API (recommended)
+ * ```typescript
  * import { openai } from './providers/openai';
  * import { llm } from './core/llm';
  *
- * // Using Responses API (default, modern, recommended)
  * const model = llm({
  *   model: openai('gpt-4o'),
- *   params: { max_tokens: 1000 }
+ *   params: { max_output_tokens: 1000 }
  * });
  *
- * // Using Chat Completions API (legacy)
+ * const turn = await model.generate('Hello!');
+ * console.log(turn.response.text);
+ * ```
+ *
+ * @example Using Chat Completions API
+ * ```typescript
  * const legacyModel = llm({
  *   model: openai('gpt-4o', { api: 'completions' }),
  *   params: { max_tokens: 1000 }
  * });
+ * ```
  *
- * // Generate
- * const turn = await model.generate('Hello!');
- * console.log(turn.response.text);
+ * @example With built-in tools (Responses API only)
+ * ```typescript
+ * import { openai, tools } from './providers/openai';
+ *
+ * const model = llm({
+ *   model: openai('gpt-4o'),
+ *   params: {
+ *     tools: [tools.webSearch(), tools.imageGeneration()]
+ *   }
+ * });
  * ```
  */
 declare const openai: OpenAIProvider;