@robota-sdk/agent-provider 3.0.0-beta.64

package/src/openai/chat-completions-chat.ts

@@ -0,0 +1,189 @@
+import type OpenAI from 'openai';
+import type { IChatOptions, TTextDeltaCallback, TUniversalMessage } from '@robota-sdk/agent-core';
+import { observeProviderNativeRawPayloadStream } from '../shared/openai-compatible/index.js';
+import type { IPayloadLogger } from './interfaces/payload-logger';
+import type { IOpenAIError, IOpenAILogData } from './types/api-types';
+import type { IOpenAIProviderOptions } from './types';
+import { buildOpenAIChatResponseFormat } from './openai-request-format';
+import { convertToOpenAIMessages, convertToOpenAITools } from './message-converter';
+import { OpenAIResponseParser } from './parsers/response-parser';
+import { assembleOpenAIStream } from './streaming/stream-assembler';
+
+export interface IOpenAIChatCompletionsOptions {
+  client?: OpenAI;
+  messages: TUniversalMessage[];
+  chatOptions?: IChatOptions;
+  providerOptions: IOpenAIProviderOptions;
+  payloadLogger?: IPayloadLogger;
+  responseParser: OpenAIResponseParser;
+  onTextDelta?: TTextDeltaCallback;
+}
+
+export async function chatWithOpenAIChatCompletions(
+  input: IOpenAIChatCompletionsOptions,
+): Promise<TUniversalMessage> {
+  const client = requireClient(input.client);
+
+  try {
+    const requestParams = buildChatRequestParams(input);
+    const textDeltaCb = input.chatOptions?.onTextDelta ?? input.onTextDelta;
+    if (textDeltaCb) {
+      return await chatWithStreamingAssembly(client, input, {
+        ...requestParams,
+        stream: true,
+      });
+    }
+
+    await logPayload(input, requestParams, 'chat');
+    input.chatOptions?.onProviderNativeRawPayload?.({
+      provider: 'openai',
+      apiSurface: 'chat-completions',
+      payloadKind: 'request',
+      payload: requestParams,
+    });
+    const response = await client.chat.completions.create(requestParams);
+    input.chatOptions?.onProviderNativeRawPayload?.({
+      provider: 'openai',
+      apiSurface: 'chat-completions',
+      payloadKind: 'response',
+      payload: response,
+    });
+    return input.responseParser.parseResponse(response);
+  } catch (error) {
+    const openaiError = error as IOpenAIError;
+    const errorMessage = openaiError.message || 'OpenAI API request failed';
+    throw new Error(`OpenAI chat failed: ${errorMessage}`);
+  }
+}
+
+export async function* chatStreamWithOpenAIChatCompletions(
+  input: IOpenAIChatCompletionsOptions,
+): AsyncIterable<TUniversalMessage> {
+  const client = requireClient(input.client);
+
+  try {
+    const requestParams: OpenAI.Chat.ChatCompletionCreateParamsStreaming = {
+      ...buildChatRequestParams(input),
+      stream: true,
+    };
+
+    await logPayload(input, requestParams, 'stream');
+    input.chatOptions?.onProviderNativeRawPayload?.({
+      provider: 'openai',
+      apiSurface: 'chat-completions',
+      payloadKind: 'request',
+      payload: requestParams,
+    });
+    const stream = await client.chat.completions.create(
+      requestParams,
+      input.chatOptions?.signal ? { signal: input.chatOptions.signal } : undefined,
+    );
+
+    for await (const chunk of observeProviderNativeRawPayloadStream(stream, {
+      provider: 'openai',
+      apiSurface: 'chat-completions',
+      onProviderNativeRawPayload: input.chatOptions?.onProviderNativeRawPayload,
+    })) {
+      const universalMessage = input.responseParser.parseStreamingChunk(chunk);
+      if (universalMessage) {
+        yield universalMessage;
+      }
+    }
+  } catch (error) {
+    const openaiError = error as IOpenAIError;
+    const errorMessage = openaiError.message || 'OpenAI API request failed';
+    throw new Error(`OpenAI stream failed: ${errorMessage}`);
+  }
+}
+
+function buildChatRequestParams(
+  input: IOpenAIChatCompletionsOptions,
+): OpenAI.Chat.ChatCompletionCreateParamsNonStreaming {
+  const openaiMessages = convertToOpenAIMessages(input.messages);
+  const model = input.chatOptions?.model ?? input.providerOptions.defaultModel;
+  if (!model) {
+    throw new Error(
+      'Model is required in chat options. Please specify a model in defaultModel configuration.',
+    );
+  }
+
+  const responseFormat = buildOpenAIChatResponseFormat(input.providerOptions);
+  return {
+    model,
+    messages: openaiMessages,
+    ...(input.chatOptions?.temperature !== undefined && {
+      temperature: input.chatOptions.temperature,
+    }),
+    ...(input.chatOptions?.maxTokens !== undefined && { max_tokens: input.chatOptions.maxTokens }),
+    ...(input.chatOptions?.tools && {
+      tools: convertToOpenAITools(input.chatOptions.tools),
+      tool_choice: 'auto',
+    }),
+    ...(responseFormat !== undefined && { response_format: responseFormat }),
+  } as OpenAI.Chat.ChatCompletionCreateParamsNonStreaming;
+}
+
+async function chatWithStreamingAssembly(
+  client: OpenAI,
+  input: IOpenAIChatCompletionsOptions,
+  requestParams: OpenAI.Chat.ChatCompletionCreateParamsStreaming,
+): Promise<TUniversalMessage> {
+  try {
+    await logPayload(input, requestParams, 'stream');
+    input.chatOptions?.onProviderNativeRawPayload?.({
+      provider: 'openai',
+      apiSurface: 'chat-completions',
+      payloadKind: 'request',
+      payload: requestParams,
+    });
+    const stream = await client.chat.completions.create(
+      requestParams,
+      input.chatOptions?.signal ? { signal: input.chatOptions.signal } : undefined,
+    );
+
+    return assembleOpenAIStream({
+      stream: observeProviderNativeRawPayloadStream(stream, {
+        provider: 'openai',
+        apiSurface: 'chat-completions',
+        onProviderNativeRawPayload: input.chatOptions?.onProviderNativeRawPayload,
+      }),
+      onTextDelta: input.chatOptions?.onTextDelta ?? input.onTextDelta,
+      signal: input.chatOptions?.signal,
+    });
+  } catch (error) {
+    const openaiError = error as IOpenAIError;
+    const errorMessage = openaiError.message || 'OpenAI streaming request failed';
+    throw new Error(`OpenAI stream failed: ${errorMessage}`);
+  }
+}
+
+async function logPayload(
+  input: IOpenAIChatCompletionsOptions,
+  requestParams:
+    | OpenAI.Chat.ChatCompletionCreateParamsNonStreaming
+    | OpenAI.Chat.ChatCompletionCreateParamsStreaming,
+  type: 'chat' | 'stream',
+): Promise<void> {
+  if (!input.payloadLogger?.isEnabled()) {
+    return;
+  }
+
+  const logData: IOpenAILogData = {
+    model: requestParams.model,
+    messagesCount: requestParams.messages.length,
+    hasTools: !!requestParams.tools,
+    temperature: requestParams.temperature ?? undefined,
+    maxTokens: requestParams.max_tokens ?? undefined,
+    timestamp: new Date().toISOString(),
+  };
+  await input.payloadLogger.logPayload(logData, type);
+}
+
+function requireClient(client: OpenAI | undefined): OpenAI {
+  if (!client) {
+    throw new Error(
+      'OpenAI client not available. Either provide a client/apiKey or use an executor.',
+    );
+  }
+  return client;
+}

package/src/openai/executor-integration.test.ts

@@ -0,0 +1,206 @@
+import { vi } from 'vitest';
+import { OpenAIProvider } from './provider';
+import { LocalExecutor } from '@robota-sdk/agent-core';
+import type { TUniversalMessage } from '@robota-sdk/agent-core';
+
+describe('OpenAI Provider Executor Integration', () => {
+  let localExecutor: LocalExecutor;
+  let provider: OpenAIProvider;
+
+  beforeEach(() => {
+    localExecutor = new LocalExecutor();
+
+    // Create a mock provider to register with the executor
+    const mockProvider = {
+      name: 'openai',
+      async chat(messages: TUniversalMessage[]): Promise<TUniversalMessage> {
+        return {
+          id: 'msg-1',
+          state: 'complete' as const,
+          role: 'assistant' as const,
+          content: `Mock response: ${messages[messages.length - 1]?.content}`,
+          timestamp: new Date(),
+        };
+      },
+      async *chatStream(messages: TUniversalMessage[]): AsyncIterable<TUniversalMessage> {
+        const chunks = ['Mock', ' streaming', ' response'];
+        for (const chunk of chunks) {
+          yield {
+            id: 'msg-1',
+            state: 'complete' as const,
+            role: 'assistant' as const,
+            content: chunk,
+            timestamp: new Date(),
+          };
+        }
+      },
+      supportsTools: () => true,
+      validateConfig: () => true,
+      dispose: async () => {},
+    };
+
+    localExecutor.registerProvider('openai', mockProvider);
+
+    // Create provider with executor (no API key needed)
+    provider = new OpenAIProvider({
+      executor: localExecutor,
+    });
+  });
+
+  afterEach(async () => {
+    await provider.dispose();
+  });
+
+  describe('Provider with Executor', () => {
+    it('should use executor for chat requests', async () => {
+      const messages: TUniversalMessage[] = [
+        {
+          id: 'msg-1',
+          state: 'complete' as const,
+          role: 'user',
+          content: 'Hello!',
+          timestamp: new Date(),
+        },
+      ];
+
+      const options = {
+        model: 'gpt-4',
+        temperature: 0.7,
+      };
+
+      const response = await provider.chat(messages, options);
+
+      expect(response.role).toBe('assistant');
+      expect(response.content).toContain('Mock response: Hello!');
+    });
+
+    it('should use executor for streaming chat requests', async () => {
+      const messages: TUniversalMessage[] = [
+        {
+          id: 'msg-1',
+          state: 'complete' as const,
+          role: 'user',
+          content: 'Tell me a story',
+          timestamp: new Date(),
+        },
+      ];
+
+      const options = {
+        model: 'gpt-4',
+        temperature: 0.7,
+      };
+
+      const chunks: string[] = [];
+      for await (const chunk of provider.chatStream(messages, options)) {
+        if (chunk.content) {
+          chunks.push(chunk.content);
+        }
+      }
+
+      expect(chunks).toEqual(['Mock', ' streaming', ' response']);
+    });
+
+    it('should handle executor errors gracefully', async () => {
+      // Create provider with executor that doesn't have registered provider
+      const errorExecutor = new LocalExecutor();
+      const errorProvider = new OpenAIProvider({
+        executor: errorExecutor,
+      });
+
+      const messages: TUniversalMessage[] = [
+        {
+          id: 'msg-1',
+          state: 'complete' as const,
+          role: 'user',
+          content: 'Hello!',
+          timestamp: new Date(),
+        },
+      ];
+
+      await expect(errorProvider.chat(messages, { model: 'gpt-4' })).rejects.toThrow(
+        'Provider "openai" not registered with LocalExecutor',
+      );
+
+      await errorProvider.dispose();
+    });
+
+    it('should support tools when executor supports tools', () => {
+      expect(provider.supportsTools()).toBe(true);
+    });
+
+    it('should validate configuration with executor', () => {
+      // Provider with executor should validate successfully
+      expect(provider.supportsTools()).toBe(true);
+    });
+
+    it('should clean up executor when provider is disposed', async () => {
+      // Provider calls dispose on its executor when disposed
+      await provider.dispose();
+
+      // Check that provider was disposed successfully
+      expect(true).toBe(true); // Basic check that dispose completed
+    });
+  });
+
+  describe('Provider without Executor', () => {
+    it('should require either client, apiKey, or executor', () => {
+      expect(() => {
+        new OpenAIProvider({});
+      }).toThrow('Either OpenAI client, apiKey, or executor is required');
+    });
+
+    it('should work with API key (traditional mode)', () => {
+      const apiKeyProvider = new OpenAIProvider({
+        apiKey: 'sk-test-key',
+      });
+
+      expect(apiKeyProvider.name).toBe('openai');
+      expect(apiKeyProvider.version).toBe('1.0.0');
+    });
+
+    it('should work with client (traditional mode)', () => {
+      const mockClient = {} as any; // Mock OpenAI client
+      const clientProvider = new OpenAIProvider({
+        client: mockClient,
+      });
+
+      expect(clientProvider.name).toBe('openai');
+      expect(clientProvider.version).toBe('1.0.0');
+    });
+  });
+
+  describe('Mixed Mode Validation', () => {
+    it('should prioritize executor over direct API when both are provided', async () => {
+      const mixedProvider = new OpenAIProvider({
+        apiKey: 'sk-test-key',
+        executor: localExecutor,
+      });
+
+      // Should use executor, not direct API
+      const messages: TUniversalMessage[] = [
+        {
+          id: 'msg-1',
+          state: 'complete' as const,
+          role: 'user',
+          content: 'Hello!',
+          timestamp: new Date(),
+        },
+      ];
+
+      const response = await mixedProvider.chat(messages, { model: 'gpt-4' });
+      expect(response.content).toContain('Mock response:');
+
+      await mixedProvider.dispose();
+    });
+
+    it('should handle executor initialization properly', () => {
+      const provider = new OpenAIProvider({
+        executor: localExecutor,
+      });
+
+      // Check that executor was set correctly
+      expect((provider as any).executor).toBe(localExecutor);
+      expect((provider as any).client).toBeUndefined();
+    });
+  });
+});

package/src/openai/index.ts

@@ -0,0 +1,21 @@
+/**
+ * @robota-sdk/agent-provider (openai)
+ *
+ * Provides Provider implementation for using OpenAI API.
+ */
+
+// Export main provider (new architecture)
+export { OpenAIProvider } from './provider';
+
+// Export types and utilities
+export * from './types';
+export * from './adapter';
+export * from './model-catalog-refresh';
+export * from './provider-definition';
+
+// Export payload logging interfaces only (implementations are in separate subpaths)
+export type { IPayloadLogger, IPayloadLoggerOptions } from './interfaces/payload-logger';
+
+// Export modular components (optional - for advanced users)
+// export { OpenAIStreamHandler } from './streaming/stream-handler';
+// export { OpenAIResponseParser } from './parsers/response-parser';

package/src/openai/interfaces/payload-logger.ts

@@ -0,0 +1,48 @@
+import type { IOpenAILogData } from '../types/api-types';
+import type { ILogger } from '@robota-sdk/agent-core';
+
+/**
+ * IPayloadLogger interface for logging OpenAI API payloads
+ *
+ * This interface provides a contract for different logging implementations:
+ * - FilePayloadLogger: Node.js file-based logging
+ * - ConsolePayloadLogger: Browser console-based logging
+ * - Custom implementations: User-defined loggers
+ */
+export interface IPayloadLogger {
+  /**
+   * Check if logging is enabled
+   * @returns true if logging is active, false otherwise
+   */
+  isEnabled(): boolean;
+
+  /**
+   * Log API payload data
+   * @param payload - The API request/response payload data
+   * @param type - Type of operation ('chat' or 'stream')
+   */
+  logPayload(payload: IOpenAILogData, type: 'chat' | 'stream'): Promise<void>;
+}
+
+/**
+ * Configuration options for payload loggers
+ */
+export interface IPayloadLoggerOptions {
+  /**
+   * Whether logging is enabled
+   * @defaultValue true
+   */
+  enabled?: boolean;
+
+  /**
+   * Include timestamp in log entries
+   * @defaultValue true
+   */
+  includeTimestamp?: boolean;
+
+  /**
+   * Logger instance for console output
+   * @defaultValue SilentLogger
+   */
+  logger?: ILogger;
+}

package/src/openai/loggers/console-payload-logger.test.ts

@@ -0,0 +1,173 @@
+import { describe, it, expect, vi } from 'vitest';
+import { ConsolePayloadLogger } from './console-payload-logger';
+import type { ILogger } from '@robota-sdk/agent-core';
+import type { IOpenAILogData } from '../types/api-types';
+
+function createMockLogger(): ILogger & {
+  group: ReturnType<typeof vi.fn>;
+  groupEnd: ReturnType<typeof vi.fn>;
+} {
+  return {
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    debug: vi.fn(),
+    log: vi.fn(),
+    group: vi.fn(),
+    groupEnd: vi.fn(),
+  };
+}
+
+function createSamplePayload(): IOpenAILogData {
+  return {
+    model: 'gpt-4',
+    messagesCount: 3,
+    hasTools: true,
+    temperature: 0.7,
+    maxTokens: 1000,
+    timestamp: '2026-01-01T00:00:00.000Z',
+  };
+}
+
+describe('ConsolePayloadLogger', () => {
+  describe('constructor', () => {
+    it('should default to enabled', () => {
+      const logger = new ConsolePayloadLogger();
+      expect(logger.isEnabled()).toBe(true);
+    });
+
+    it('should respect enabled option set to false', () => {
+      const logger = new ConsolePayloadLogger({ enabled: false });
+      expect(logger.isEnabled()).toBe(false);
+    });
+
+    it('should accept custom logger', () => {
+      const mockLogger = createMockLogger();
+      const logger = new ConsolePayloadLogger({ logger: mockLogger });
+      expect(logger.isEnabled()).toBe(true);
+    });
+  });
+
+  describe('isEnabled', () => {
+    it('should return true when enabled', () => {
+      const logger = new ConsolePayloadLogger({ enabled: true });
+      expect(logger.isEnabled()).toBe(true);
+    });
+
+    it('should return false when disabled', () => {
+      const logger = new ConsolePayloadLogger({ enabled: false });
+      expect(logger.isEnabled()).toBe(false);
+    });
+  });
+
+  describe('logPayload', () => {
+    it('should log payload to console with chat type', async () => {
+      const mockLogger = createMockLogger();
+      const logger = new ConsolePayloadLogger({ logger: mockLogger });
+      const payload = createSamplePayload();
+
+      await logger.logPayload(payload, 'chat');
+
+      expect(mockLogger.group).toHaveBeenCalledWith(expect.stringContaining('[OpenAI CHAT]'));
+      expect(mockLogger.info).toHaveBeenCalled();
+      expect(mockLogger.debug).toHaveBeenCalled();
+      expect(mockLogger.groupEnd).toHaveBeenCalled();
+    });
+
+    it('should log payload with stream type', async () => {
+      const mockLogger = createMockLogger();
+      const logger = new ConsolePayloadLogger({ logger: mockLogger });
+      const payload = createSamplePayload();
+
+      await logger.logPayload(payload, 'stream');
+
+      expect(mockLogger.group).toHaveBeenCalledWith(expect.stringContaining('[OpenAI STREAM]'));
+    });
+
+    it('should include timestamp in group title when includeTimestamp is true', async () => {
+      const mockLogger = createMockLogger();
+      const logger = new ConsolePayloadLogger({
+        logger: mockLogger,
+        includeTimestamp: true,
+      });
+      const payload = createSamplePayload();
+
+      await logger.logPayload(payload, 'chat');
+
+      expect(mockLogger.group).toHaveBeenCalledWith(expect.stringContaining(payload.timestamp));
+    });
+
+    it('should not include timestamp when includeTimestamp is false', async () => {
+      const mockLogger = createMockLogger();
+      const logger = new ConsolePayloadLogger({
+        logger: mockLogger,
+        includeTimestamp: false,
+      });
+      const payload = createSamplePayload();
+
+      await logger.logPayload(payload, 'chat');
+
+      const groupCall = mockLogger.group.mock.calls[0][0] as string;
+      expect(groupCall).not.toContain(payload.timestamp);
+    });
+
+    it('should skip logging when disabled', async () => {
+      const mockLogger = createMockLogger();
+      const logger = new ConsolePayloadLogger({
+        logger: mockLogger,
+        enabled: false,
+      });
+      const payload = createSamplePayload();
+
+      await logger.logPayload(payload, 'chat');
+
+      expect(mockLogger.group).not.toHaveBeenCalled();
+      expect(mockLogger.info).not.toHaveBeenCalled();
+      expect(mockLogger.debug).not.toHaveBeenCalled();
+    });
+
+    it('should not throw on internal error and log the error', async () => {
+      const mockLogger = createMockLogger();
+      // Make group throw an error
+      mockLogger.group.mockImplementation(() => {
+        throw new Error('Console error');
+      });
+      const logger = new ConsolePayloadLogger({ logger: mockLogger });
+      const payload = createSamplePayload();
+
+      // Should not throw
+      await expect(logger.logPayload(payload, 'chat')).resolves.toBeUndefined();
+      expect(mockLogger.error).toHaveBeenCalledWith(
+        expect.stringContaining('[ConsolePayloadLogger]'),
+        expect.any(String),
+      );
+    });
+
+    it('should log request details with payload fields', async () => {
+      const mockLogger = createMockLogger();
+      const logger = new ConsolePayloadLogger({ logger: mockLogger });
+      const payload = createSamplePayload();
+
+      await logger.logPayload(payload, 'chat');
+
+      expect(mockLogger.info).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.objectContaining({
+          model: 'gpt-4',
+          messagesCount: 3,
+          hasTools: true,
+        }),
+      );
+    });
+
+    it('should default type to chat', async () => {
+      const mockLogger = createMockLogger();
+      const logger = new ConsolePayloadLogger({ logger: mockLogger });
+      const payload = createSamplePayload();
+
+      await logger.logPayload(payload, 'chat');
+
+      expect(mockLogger.group).toHaveBeenCalledWith(expect.stringContaining('CHAT'));
+    });
+  });
+});