@robota-sdk/openai

import OpenAI from 'openai'; import { ProviderOptions, BaseAIProvider, Context, ModelResponse, StreamingResponseChunk, UniversalMessage } from '@robota-sdk/core'; import { FunctionSchema } from '@robota-sdk/tools'; /** * OpenAI provider options */ interface OpenAIProviderOptions extends ProviderOptions { /** * Model name to use (default: gpt-3.5-turbo) */ model: string; /** * Temperature (0~1) */ temperature?: number; /** * Maximum number of tokens */ maxTokens?: number; /** * OpenAI API key (optional: not required when using client) */ apiKey?: string; /** * OpenAI organization ID (optional) */ organization?: string; /** * API request timeout (milliseconds) */ timeout?: number; /** * API base URL (default: 'https://api.openai.com/v1') */ baseURL?: string; /** * Response format (default: 'text') * - 'text': Plain text response * - 'json_object': Legacy JSON mode (requires system message) * - 'json_schema': Structured Outputs with schema validation */ responseFormat?: 'text' | 'json_object' | 'json_schema'; /** * JSON schema for structured outputs (required when responseFormat is 'json_schema') */ jsonSchema?: { name: string; description?: string; schema?: Record<string, unknown>; strict?: boolean; }; /** * OpenAI client instance (required) */ client: OpenAI; /** * Enable API payload logging to files * When enabled, saves API request payloads to log files * * @defaultValue false */ enablePayloadLogging?: boolean; /** * Directory path for storing API payload log files * * @defaultValue './logs/api-payloads' */ payloadLogDir?: string; /** * Include timestamp in payload log filenames * * @defaultValue true */ includeTimestampInLogFiles?: boolean; } /** * OpenAI AI provider implementation for Robota * * Provides integration with OpenAI's GPT models and other services. * Extends BaseAIProvider for common functionality and tool calling support. * * @see {@link ../../../apps/examples/03-integrations | Provider Integration Examples} * * @public */ declare class OpenAIProvider extends BaseAIProvider { /** * Provider identifier name * @readonly */ readonly name: string; /** * OpenAI client instance * @internal */ private readonly client; /** * Client type identifier * @readonly */ readonly type: string; /** * OpenAI client instance (alias for backwards compatibility) * @readonly * @deprecated Use the private client property instead */ readonly instance: OpenAI; /** * Provider configuration options * @readonly */ readonly options: OpenAIProviderOptions; /** * Payload logger for API request logging * @internal */ private readonly payloadLogger; /** * Create a new OpenAI provider instance * * @param options - Configuration options for the OpenAI provider * * @throws {Error} When client is not provided in options */ constructor(options: OpenAIProviderOptions); /** * Convert function definitions to OpenAI tool format * * Transforms universal function definitions into OpenAI's specific tool format * required by the Chat Completions API. * * @param functions - Array of universal function definitions * @returns Array of OpenAI-formatted tools */ formatFunctions(functions: FunctionSchema[]): OpenAI.Chat.ChatCompletionTool[]; /** * Filter conversation history for OpenAI API compatibility * * Converts messages to OpenAI format and filters out invalid tool messages. * * @param messages - Array of messages to filter * @returns OpenAI-formatted messages array */ private filterHistory; /** * Configure tools for OpenAI API request * * Transforms function schemas into OpenAI tool format and sets tool_choice. * * @param tools - Array of function schemas * @returns OpenAI tool configuration object */ protected configureTools(tools?: FunctionSchema[]): { tools: OpenAI.Chat.ChatCompletionTool[]; tool_choice: 'auto'; } | undefined; /** * Send a chat request to OpenAI and receive a complete response * * Processes the provided context and sends it to OpenAI's Chat Completions API. * Handles message format conversion, error handling, and response parsing. * * @param model - Model name to use (e.g., 'gpt-4', 'gpt-3.5-turbo') * @param context - Context object containing messages and system prompt * @param options - Optional generation parameters and tools * @returns Promise resolving to the model's response * * @throws {Error} When context is invalid * @throws {Error} When messages array is invalid * @throws {Error} When message format conversion fails * @throws {Error} When OpenAI API call fails */ chat(model: string, context: Context, options?: any): Promise<ModelResponse>; /** * Convert OpenAI API response to universal ModelResponse format * * Transforms the OpenAI-specific response format into the standard format * used across all providers in Robota. * * @param response - Raw response from OpenAI Chat Completions API * @returns Parsed model response in universal format * * @internal */ parseResponse(response: OpenAI.Chat.ChatCompletion): ModelResponse; /** * Convert OpenAI streaming response chunk to universal format * * Transforms individual chunks from OpenAI's streaming response into the * standard StreamingResponseChunk format used across all providers. * * @param chunk - Raw chunk from OpenAI streaming API * @returns Parsed streaming response chunk * * @internal */ parseStreamingChunk(chunk: OpenAI.Chat.ChatCompletionChunk): StreamingResponseChunk; /** * Send a streaming chat request to OpenAI and receive response chunks * * Similar to chat() but returns an async iterator that yields response chunks * as they arrive from OpenAI's streaming API. Useful for real-time display * of responses or handling large responses incrementally. * * @param model - Model name to use * @param context - Context object containing messages and system prompt * @param options - Optional generation parameters and tools * @returns Async generator yielding response chunks * * @throws {Error} When context is invalid * @throws {Error} When messages array is invalid * @throws {Error} When message format conversion fails * @throws {Error} When OpenAI streaming API call fails * * @see {@link ../../../apps/examples/01-basic | Basic Usage Examples} */ chatStream(model: string, context: Context, options?: any): AsyncGenerator<StreamingResponseChunk, void, unknown>; /** * Release resources and close connections * * Performs cleanup operations when the provider is no longer needed. * OpenAI client doesn't require explicit cleanup, so this is a no-op. * * @returns Promise that resolves when cleanup is complete */ close(): Promise<void>; } /** * OpenAI ConversationHistory adapter * * Converts UniversalMessage to OpenAI Chat Completions API format */ declare class OpenAIConversationAdapter { /** * Filter messages for OpenAI compatibility * * OpenAI has specific requirements: * - Tool messages must have valid toolCallId * - Messages must be in proper sequence * - Tool messages without toolCallId should be excluded */ static filterMessagesForOpenAI(messages: UniversalMessage[]): UniversalMessage[]; /** * Convert UniversalMessage array to OpenAI message format * Now properly handles tool messages for OpenAI's tool calling feature */ static toOpenAIFormat(messages: UniversalMessage[]): OpenAI.Chat.ChatCompletionMessageParam[]; /** * Convert a single UniversalMessage to OpenAI format * Handles all message types including tool messages */ static convertMessage(msg: UniversalMessage): OpenAI.Chat.ChatCompletionMessageParam; /** * Add system prompt to message array if needed */ static addSystemPromptIfNeeded(messages: OpenAI.Chat.ChatCompletionMessageParam[], systemPrompt?: string): OpenAI.Chat.ChatCompletionMessageParam[]; } /** * Utility class for logging OpenAI API payloads to files */ declare class PayloadLogger { private readonly enabled; private readonly logDir; private readonly includeTimestamp; constructor(enabled?: boolean, logDir?: string, includeTimestamp?: boolean); /** * Log API payload to file * @param payload - The API request payload * @param type - Type of request ('chat' or 'stream') */ logPayload(payload: any, type?: 'chat' | 'stream'): Promise<void>; /** * Ensure log directory exists */ private ensureLogDirectoryExists; /** * Sanitize payload to remove sensitive information * @param payload - Raw payload object * @returns Sanitized payload */ private sanitizePayload; /** * Check if logging is enabled */ isEnabled(): boolean; } export { OpenAIConversationAdapter, OpenAIProvider, type OpenAIProviderOptions, PayloadLogger };