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

package/src/openai/streaming/stream-handler.test.ts

@@ -0,0 +1,367 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { OpenAIStreamHandler } from './stream-handler';
+import type { IPayloadLogger } from '../interfaces/payload-logger';
+import type { ILogger } from '@robota-sdk/agent-core';
+import type { IOpenAIStreamRequestParams, IOpenAIChatRequestParams } from '../types/api-types';
+import type OpenAI from 'openai';
+
+function createMockLogger(): ILogger {
+  return {
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    debug: vi.fn(),
+    log: vi.fn(),
+  };
+}
+
+function createMockPayloadLogger(enabled = true): IPayloadLogger {
+  return {
+    isEnabled: vi.fn().mockReturnValue(enabled),
+    logPayload: vi.fn().mockResolvedValue(undefined),
+  };
+}
+
+// Create an async iterable from an array of chunks
+async function* asyncIterableFrom<T>(items: T[]): AsyncIterable<T> {
+  for (const item of items) {
+    yield item;
+  }
+}
+
+function createMockClient(chunks: OpenAI.Chat.ChatCompletionChunk[]): OpenAI {
+  return {
+    chat: {
+      completions: {
+        create: vi.fn().mockResolvedValue(asyncIterableFrom(chunks)),
+      },
+    },
+  } as unknown as OpenAI;
+}
+
+function createStreamChunk(
+  content: string,
+  finishReason: string | null = null,
+): OpenAI.Chat.ChatCompletionChunk {
+  return {
+    id: 'chatcmpl-chunk',
+    object: 'chat.completion.chunk',
+    created: Date.now(),
+    model: 'gpt-4',
+    choices: [
+      {
+        index: 0,
+        delta: { content },
+        finish_reason: finishReason,
+        logprobs: null,
+      },
+    ],
+  } as OpenAI.Chat.ChatCompletionChunk;
+}
+
+describe('OpenAIStreamHandler', () => {
+  let mockClient: OpenAI;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('handleStream', () => {
+    it('should yield parsed messages from stream', async () => {
+      const chunks = [
+        createStreamChunk('Hello'),
+        createStreamChunk(' world'),
+        createStreamChunk('', 'stop'),
+      ];
+      mockClient = createMockClient(chunks);
+      const handler = new OpenAIStreamHandler(mockClient);
+
+      const requestParams: IOpenAIStreamRequestParams = {
+        model: 'gpt-4',
+        messages: [{ role: 'user', content: 'Hi' }],
+        stream: true,
+      };
+
+      const results: Array<{ content: string | null }> = [];
+      for await (const msg of handler.handleStream(requestParams)) {
+        results.push(msg);
+      }
+
+      expect(results).toHaveLength(3);
+      expect(results[0].content).toBe('Hello');
+      expect(results[1].content).toBe(' world');
+    });
+
+    it('should log payload when payload logger is enabled', async () => {
+      const chunks = [createStreamChunk('Hi', 'stop')];
+      mockClient = createMockClient(chunks);
+      const payloadLogger = createMockPayloadLogger(true);
+      const handler = new OpenAIStreamHandler(mockClient, payloadLogger);
+
+      const requestParams: IOpenAIStreamRequestParams = {
+        model: 'gpt-4',
+        messages: [{ role: 'user', content: 'Hi' }],
+        stream: true,
+        temperature: 0.5,
+        max_tokens: 100,
+      };
+
+      const results = [];
+      for await (const msg of handler.handleStream(requestParams)) {
+        results.push(msg);
+      }
+
+      expect(payloadLogger.logPayload).toHaveBeenCalledWith(
+        expect.objectContaining({
+          model: 'gpt-4',
+          messagesCount: 1,
+          hasTools: false,
+          temperature: 0.5,
+          maxTokens: 100,
+        }),
+        'stream',
+      );
+    });
+
+    it('should not log payload when payload logger is disabled', async () => {
+      const chunks = [createStreamChunk('Hi', 'stop')];
+      mockClient = createMockClient(chunks);
+      const payloadLogger = createMockPayloadLogger(false);
+      const handler = new OpenAIStreamHandler(mockClient, payloadLogger);
+
+      const requestParams: IOpenAIStreamRequestParams = {
+        model: 'gpt-4',
+        messages: [{ role: 'user', content: 'Hi' }],
+        stream: true,
+      };
+
+      for await (const _msg of handler.handleStream(requestParams)) {
+        // consume stream
+      }
+
+      expect(payloadLogger.logPayload).not.toHaveBeenCalled();
+    });
+
+    it('should pass tools and tool_choice to API when provided', async () => {
+      const chunks = [createStreamChunk('Hi', 'stop')];
+      mockClient = createMockClient(chunks);
+      const handler = new OpenAIStreamHandler(mockClient);
+
+      const tools: OpenAI.Chat.ChatCompletionTool[] = [
+        {
+          type: 'function',
+          function: {
+            name: 'search',
+            description: 'Search the web',
+            parameters: { type: 'object', properties: {} },
+          },
+        },
+      ];
+
+      const requestParams: IOpenAIStreamRequestParams = {
+        model: 'gpt-4',
+        messages: [{ role: 'user', content: 'Hi' }],
+        stream: true,
+        tools,
+        tool_choice: 'auto',
+      };
+
+      for await (const _msg of handler.handleStream(requestParams)) {
+        // consume
+      }
+
+      const createCall = vi.mocked(mockClient.chat.completions.create);
+      expect(createCall).toHaveBeenCalledWith(
+        expect.objectContaining({
+          tools,
+          tool_choice: 'auto',
+          stream: true,
+        }),
+      );
+    });
+
+    it('should throw with descriptive error when API call fails', async () => {
+      mockClient = {
+        chat: {
+          completions: {
+            create: vi.fn().mockRejectedValue(new Error('API rate limit')),
+          },
+        },
+      } as unknown as OpenAI;
+
+      const logger = createMockLogger();
+      const handler = new OpenAIStreamHandler(mockClient, undefined, logger);
+
+      const requestParams: IOpenAIStreamRequestParams = {
+        model: 'gpt-4',
+        messages: [{ role: 'user', content: 'Hi' }],
+        stream: true,
+      };
+
+      const results = [];
+      await expect(async () => {
+        for await (const msg of handler.handleStream(requestParams)) {
+          results.push(msg);
+        }
+      }).rejects.toThrow('OpenAI streaming failed: API rate limit');
+      expect(logger.error).toHaveBeenCalled();
+    });
+
+    it('should handle empty stream', async () => {
+      mockClient = createMockClient([]);
+      const handler = new OpenAIStreamHandler(mockClient);
+
+      const requestParams: IOpenAIStreamRequestParams = {
+        model: 'gpt-4',
+        messages: [{ role: 'user', content: 'Hi' }],
+        stream: true,
+      };
+
+      const results = [];
+      for await (const msg of handler.handleStream(requestParams)) {
+        results.push(msg);
+      }
+
+      expect(results).toHaveLength(0);
+    });
+
+    it('should work without payload logger', async () => {
+      const chunks = [createStreamChunk('Hello', 'stop')];
+      mockClient = createMockClient(chunks);
+      const handler = new OpenAIStreamHandler(mockClient);
+
+      const requestParams: IOpenAIStreamRequestParams = {
+        model: 'gpt-4',
+        messages: [{ role: 'user', content: 'Hi' }],
+        stream: true,
+      };
+
+      const results = [];
+      for await (const msg of handler.handleStream(requestParams)) {
+        results.push(msg);
+      }
+
+      expect(results).toHaveLength(1);
+      expect(results[0].content).toBe('Hello');
+    });
+  });
+
+  describe('generateStreamingResponse', () => {
+    it('should convert chat request params and delegate to handleStream', async () => {
+      const chunks = [createStreamChunk('Response'), createStreamChunk('', 'stop')];
+      mockClient = createMockClient(chunks);
+      const handler = new OpenAIStreamHandler(mockClient);
+
+      const request: IOpenAIChatRequestParams = {
+        model: 'gpt-4',
+        messages: [{ role: 'user', content: 'Hi' }],
+        temperature: 0.8,
+        max_tokens: 200,
+      };
+
+      const results = [];
+      for await (const msg of handler.generateStreamingResponse(request)) {
+        results.push(msg);
+      }
+
+      expect(results).toHaveLength(2);
+      expect(results[0].content).toBe('Response');
+    });
+
+    it('should default model to gpt-4o-mini when not specified', async () => {
+      const chunks = [createStreamChunk('Hi', 'stop')];
+      mockClient = createMockClient(chunks);
+      const handler = new OpenAIStreamHandler(mockClient);
+
+      const request: IOpenAIChatRequestParams = {
+        model: '',
+        messages: [{ role: 'user', content: 'Hi' }],
+      };
+
+      for await (const _msg of handler.generateStreamingResponse(request)) {
+        // consume
+      }
+
+      const createCall = vi.mocked(mockClient.chat.completions.create);
+      expect(createCall).toHaveBeenCalledWith(expect.objectContaining({ model: 'gpt-4o-mini' }));
+    });
+
+    it('should include tools when provided in request', async () => {
+      const chunks = [createStreamChunk('Hi', 'stop')];
+      mockClient = createMockClient(chunks);
+      const handler = new OpenAIStreamHandler(mockClient);
+
+      const tools: OpenAI.Chat.ChatCompletionTool[] = [
+        {
+          type: 'function',
+          function: {
+            name: 'calc',
+            description: 'Calculate',
+            parameters: { type: 'object', properties: {} },
+          },
+        },
+      ];
+
+      const request: IOpenAIChatRequestParams = {
+        model: 'gpt-4',
+        messages: [{ role: 'user', content: 'Hi' }],
+        tools,
+      };
+
+      for await (const _msg of handler.generateStreamingResponse(request)) {
+        // consume
+      }
+
+      const createCall = vi.mocked(mockClient.chat.completions.create);
+      expect(createCall).toHaveBeenCalledWith(
+        expect.objectContaining({
+          tools,
+          tool_choice: 'auto',
+        }),
+      );
+    });
+
+    it('should throw and log error when streaming fails', async () => {
+      mockClient = {
+        chat: {
+          completions: {
+            create: vi.fn().mockRejectedValue(new Error('Network error')),
+          },
+        },
+      } as unknown as OpenAI;
+
+      const logger = createMockLogger();
+      const handler = new OpenAIStreamHandler(mockClient, undefined, logger);
+
+      const request: IOpenAIChatRequestParams = {
+        model: 'gpt-4',
+        messages: [{ role: 'user', content: 'Hi' }],
+      };
+
+      await expect(async () => {
+        for await (const _msg of handler.generateStreamingResponse(request)) {
+          // consume
+        }
+      }).rejects.toThrow();
+      expect(logger.error).toHaveBeenCalled();
+    });
+
+    it('should handle empty messages array', async () => {
+      const chunks = [createStreamChunk('Hi', 'stop')];
+      mockClient = createMockClient(chunks);
+      const handler = new OpenAIStreamHandler(mockClient);
+
+      const request: IOpenAIChatRequestParams = {
+        model: 'gpt-4',
+        messages: [],
+      };
+
+      const results = [];
+      for await (const msg of handler.generateStreamingResponse(request)) {
+        results.push(msg);
+      }
+
+      expect(results).toHaveLength(1);
+    });
+  });
+});

package/src/openai/streaming/stream-handler.ts

@@ -0,0 +1,119 @@
+import OpenAI from 'openai';
+import type { TUniversalMessage } from '@robota-sdk/agent-core';
+import type { IPayloadLogger } from '../interfaces/payload-logger';
+import type { IOpenAIChatRequestParams, IOpenAIStreamRequestParams } from '../types/api-types';
+import { SilentLogger, type ILogger } from '@robota-sdk/agent-core';
+import { OpenAIResponseParser } from '../parsers/response-parser';
+
+/**
+ * OpenAI streaming response handler
+ *
+ * Handles streaming chat completions from OpenAI API.
+ * Extracts streaming logic from the main provider for better modularity.
+ */
+export class OpenAIStreamHandler {
+  private readonly logger: ILogger;
+  private readonly parser: OpenAIResponseParser;
+
+  constructor(
+    private readonly client: OpenAI,
+    private readonly payloadLogger?: IPayloadLogger,
+    logger?: ILogger,
+  ) {
+    this.logger = logger || SilentLogger;
+    this.parser = new OpenAIResponseParser(logger);
+  }
+
+  /**
+   * Handle streaming response for OpenAI chat completions
+   *
+   * @param requestParams - OpenAI API request parameters
+   * @returns AsyncGenerator yielding universal messages
+   */
+  async *handleStream(
+    requestParams: IOpenAIStreamRequestParams,
+  ): AsyncGenerator<TUniversalMessage, void, undefined> {
+    try {
+      // Log payload for debugging if logger is available
+      if (this.payloadLogger?.isEnabled()) {
+        const logData = {
+          model: requestParams.model,
+          messagesCount: requestParams.messages.length,
+          hasTools: !!requestParams.tools,
+          temperature: requestParams.temperature,
+          maxTokens: requestParams.max_tokens,
+          timestamp: new Date().toISOString(),
+        };
+        await this.payloadLogger.logPayload(logData, 'stream');
+      }
+
+      // Create streaming chat completion with proper type-safe parameters
+      const streamParams: OpenAI.Chat.ChatCompletionCreateParamsStreaming = {
+        model: requestParams.model,
+        messages: requestParams.messages,
+        stream: true,
+        ...(requestParams.temperature !== undefined && { temperature: requestParams.temperature }),
+        ...(requestParams.max_tokens !== undefined && { max_tokens: requestParams.max_tokens }),
+        ...(requestParams.tools && {
+          tools: requestParams.tools,
+          tool_choice: requestParams.tool_choice || 'auto',
+        }),
+      };
+      const response = await this.client.chat.completions.create(streamParams);
+
+      // Process each chunk in the stream
+      for await (const chunk of response) {
+        const parsed = this.parser.parseStreamingChunk(chunk);
+        if (parsed) {
+          yield parsed;
+        }
+      }
+    } catch (error) {
+      const errorMessage =
+        error instanceof Error ? error.message : 'OpenAI streaming request failed';
+      this.logger.error('Stream creation failed', { error: errorMessage });
+      throw new Error(`OpenAI streaming failed: ${errorMessage}`);
+    }
+  }
+
+  /**
+   * Generate streaming response using raw request payload (for agents package compatibility)
+   *
+   * @param request - Raw request payload from ConversationService
+   * @returns AsyncGenerator yielding universal messages
+   */
+  async *generateStreamingResponse(
+    request: IOpenAIChatRequestParams,
+  ): AsyncGenerator<TUniversalMessage, void, undefined> {
+    try {
+      // Extract parameters from request payload
+      const model = request.model;
+      const messages = request.messages || [];
+      const temperature = request.temperature;
+      const maxTokens = request.max_tokens;
+      const tools = request.tools;
+
+      // Build OpenAI request parameters
+      const requestParams: IOpenAIStreamRequestParams = {
+        model: model || 'gpt-4o-mini',
+        messages,
+        temperature,
+        max_tokens: maxTokens,
+        stream: true,
+      };
+
+      // Add tools if provided
+      if (tools && Array.isArray(tools) && tools.length > 0) {
+        requestParams.tools = tools;
+        requestParams.tool_choice = 'auto';
+      }
+
+      // Use existing stream handler
+      yield* this.handleStream(requestParams);
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+      this.logger.error('OpenAI generateStreamingResponse error:', { message: errorMessage });
+      throw error;
+    }
+  }
+}

package/src/openai/types/api-types.ts

@@ -0,0 +1,112 @@
+import type OpenAI from 'openai';
+
+/**
+ * OpenAI API Request Parameters
+ * Replaces any types with specific OpenAI API structure
+ */
+export interface IOpenAIChatRequestParams {
+  model: string;
+  messages: OpenAI.Chat.ChatCompletionMessageParam[];
+  temperature?: number | undefined;
+  max_tokens?: number | undefined;
+  tools?: OpenAI.Chat.ChatCompletionTool[] | undefined;
+  tool_choice?: 'auto' | 'none' | OpenAI.Chat.ChatCompletionNamedToolChoice | undefined;
+  stream?: boolean | undefined;
+}
+
+/**
+ * OpenAI API streaming request parameters
+ */
+export interface IOpenAIStreamRequestParams extends Omit<IOpenAIChatRequestParams, 'stream'> {
+  stream: true;
+}
+
+/**
+ * OpenAI API tool call structure
+ */
+export interface IOpenAIToolCall {
+  id: string;
+  type: 'function';
+  function: {
+    name: string;
+    arguments: string;
+  };
+}
+
+/**
+ * OpenAI API message structure with tool calls
+ */
+export interface IOpenAIAssistantMessage {
+  role: 'assistant';
+  content: string | null;
+  tool_calls?: IOpenAIToolCall[];
+}
+
+/**
+ * OpenAI API tool message structure
+ */
+export interface IOpenAIToolMessage {
+  role: 'tool';
+  content: string;
+  tool_call_id: string;
+}
+
+/**
+ * OpenAI streaming chunk delta structure
+ */
+export interface IOpenAIStreamDelta {
+  role?: 'assistant';
+  content?: string | null;
+  tool_calls?: Array<{
+    index: number;
+    id?: string;
+    type?: 'function';
+    function?: {
+      name?: string;
+      arguments?: string;
+    };
+  }>;
+}
+
+/**
+ * OpenAI streaming chunk structure
+ */
+export interface IOpenAIStreamChunk {
+  id: string;
+  object: 'chat.completion.chunk';
+  created: number;
+  model: string;
+  choices: Array<{
+    index: number;
+    delta: IOpenAIStreamDelta;
+    finish_reason?: string | null;
+  }>;
+  usage?: {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+  };
+}
+
+/**
+ * OpenAI error structure for type-safe error handling
+ */
+export interface IOpenAIError {
+  message: string;
+  type?: string;
+  param?: string | null;
+  code?: string | null;
+}
+
+/**
+ * Payload logging data structure
+ */
+export interface IOpenAILogData {
+  model: string;
+  messagesCount: number;
+  hasTools: boolean;
+  temperature?: number | undefined;
+  maxTokens?: number | undefined;
+  timestamp: string;
+  requestId?: string | undefined;
+}