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

package/src/deepseek/provider.ts

@@ -0,0 +1,298 @@
+import OpenAI from 'openai';
+import { AbstractAIProvider, SilentLogger } from '@robota-sdk/agent-core';
+import type {
+  IChatOptions,
+  IProviderCapabilities,
+  TTextDeltaCallback,
+  TUniversalMessage,
+} from '@robota-sdk/agent-core';
+import {
+  assembleOpenAICompatibleStream,
+  convertToOpenAICompatibleMessages,
+  convertToOpenAICompatibleTools,
+  observeProviderNativeRawPayloadStream,
+  OpenAICompatibleResponseParser,
+} from '../shared/openai-compatible/index.js';
+import type { IOpenAICompatibleError } from '../shared/openai-compatible/index.js';
+import { DEFAULT_DEEPSEEK_PROVIDER_BASE_URL } from './defaults';
+import type {
+  IDeepSeekProviderOptions,
+  IDeepSeekThinkingConfig,
+  TDeepSeekReasoningEffort,
+} from './types';
+
+type TDeepSeekChatCompletionCreateParamsNonStreaming = Omit<
+  OpenAI.Chat.ChatCompletionCreateParamsNonStreaming,
+  'reasoning_effort'
+> & {
+  thinking?: IDeepSeekThinkingConfig;
+  reasoning_effort?: TDeepSeekReasoningEffort;
+};
+
+type TDeepSeekChatCompletionCreateParamsStreaming = Omit<
+  OpenAI.Chat.ChatCompletionCreateParamsStreaming,
+  'reasoning_effort'
+> & {
+  thinking?: IDeepSeekThinkingConfig;
+  reasoning_effort?: TDeepSeekReasoningEffort;
+};
+
+export class DeepSeekProvider extends AbstractAIProvider {
+  override readonly name = 'deepseek';
+  override readonly version = '1.0.0';
+
+  private readonly client?: OpenAI;
+  private readonly options: IDeepSeekProviderOptions;
+  private readonly responseParser: OpenAICompatibleResponseParser;
+
+  onTextDelta?: TTextDeltaCallback;
+
+  constructor(options: IDeepSeekProviderOptions) {
+    super(options.logger || SilentLogger);
+    this.options = options;
+
+    if (options.executor) {
+      this.executor = options.executor;
+    }
+
+    if (!this.executor) {
+      if (options.client) {
+        this.client = options.client;
+      } else if (options.apiKey) {
+        this.client = new OpenAI({
+          apiKey: options.apiKey,
+          baseURL: options.baseURL ?? DEFAULT_DEEPSEEK_PROVIDER_BASE_URL,
+          ...(options.timeout !== undefined && { timeout: options.timeout }),
+        });
+      } else {
+        throw new Error('Either DeepSeek client, apiKey, or executor is required');
+      }
+    }
+
+    this.responseParser = new OpenAICompatibleResponseParser({ logger: this.logger });
+  }
+
+  override async chat(
+    messages: TUniversalMessage[],
+    options?: IChatOptions,
+  ): Promise<TUniversalMessage> {
+    this.validateMessages(messages);
+    this.validateNativeWebTools(options?.nativeWebTools);
+
+    if (this.executor) {
+      try {
+        return await this.executeViaExecutorOrDirect(messages, options);
+      } catch (error) {
+        this.logger.error(
+          'DeepSeek Provider executor chat error:',
+          error instanceof Error ? error.message : String(error),
+        );
+        throw error;
+      }
+    }
+
+    const client = this.getClient();
+
+    try {
+      const requestParams = this.buildRequestParams(messages, options);
+      const textDeltaCb = options?.onTextDelta ?? this.onTextDelta;
+      if (textDeltaCb) {
+        return await this.chatWithStreamingAssembly(
+          { ...requestParams, stream: true },
+          { ...options, onTextDelta: textDeltaCb },
+        );
+      }
+
+      options?.onProviderNativeRawPayload?.({
+        provider: 'deepseek',
+        apiSurface: 'chat-completions',
+        payloadKind: 'request',
+        payload: requestParams,
+      });
+      const response = await client.chat.completions.create(
+        requestParams as OpenAI.Chat.ChatCompletionCreateParamsNonStreaming,
+      );
+      options?.onProviderNativeRawPayload?.({
+        provider: 'deepseek',
+        apiSurface: 'chat-completions',
+        payloadKind: 'response',
+        payload: response,
+      });
+      return this.responseParser.parseResponse(response);
+    } catch (error) {
+      const deepSeekError = error as IOpenAICompatibleError;
+      const errorMessage = deepSeekError.message || 'DeepSeek API request failed';
+      throw new Error(`DeepSeek chat failed: ${errorMessage}`);
+    }
+  }
+
+  override async *chatStream(
+    messages: TUniversalMessage[],
+    options?: IChatOptions,
+  ): AsyncIterable<TUniversalMessage> {
+    this.validateMessages(messages);
+    this.validateNativeWebTools(options?.nativeWebTools);
+
+    if (this.executor) {
+      try {
+        yield* this.executeStreamViaExecutorOrDirect(messages, options);
+        return;
+      } catch (error) {
+        this.logger.error(
+          'DeepSeek Provider executor stream error:',
+          error instanceof Error ? error.message : String(error),
+        );
+        throw error;
+      }
+    }
+
+    const client = this.getClient();
+
+    try {
+      const requestParams = this.buildStreamingRequestParams(messages, options);
+      options?.onProviderNativeRawPayload?.({
+        provider: 'deepseek',
+        apiSurface: 'chat-completions',
+        payloadKind: 'request',
+        payload: requestParams,
+      });
+      const stream = await client.chat.completions.create(
+        requestParams as OpenAI.Chat.ChatCompletionCreateParamsStreaming,
+      );
+      const observedStream = observeProviderNativeRawPayloadStream(stream, {
+        provider: 'deepseek',
+        apiSurface: 'chat-completions',
+        onProviderNativeRawPayload: options?.onProviderNativeRawPayload,
+      });
+
+      for await (const chunk of this.streamWithAbort(observedStream, options?.signal)) {
+        const universalMessage = this.responseParser.parseStreamingChunk(chunk);
+        if (universalMessage) {
+          yield universalMessage;
+        }
+      }
+    } catch (error) {
+      const deepSeekError = error as IOpenAICompatibleError;
+      const errorMessage = deepSeekError.message || 'DeepSeek API request failed';
+      throw new Error(`DeepSeek stream failed: ${errorMessage}`);
+    }
+  }
+
+  override supportsTools(): boolean {
+    return true;
+  }
+
+  override getCapabilities(): IProviderCapabilities {
+    return {
+      functionCalling: { supported: true },
+      nativeWebTools: {
+        webSearch: {
+          supported: false,
+          enabled: false,
+          source: 'openai-compatible-chat-completions',
+          reason:
+            'DeepSeek OpenAI-compatible Chat Completions supports declared function tools, not provider-native web search.',
+        },
+        webFetch: {
+          supported: false,
+          enabled: false,
+          source: 'openai-compatible-chat-completions',
+          reason:
+            'DeepSeek OpenAI-compatible Chat Completions supports declared function tools, not provider-native web fetch.',
+        },
+      },
+    };
+  }
+
+  override validateConfig(): boolean {
+    return !!this.client && !!this.options;
+  }
+
+  override async dispose(): Promise<void> {
+    // OpenAI-compatible DeepSeek clients do not need explicit cleanup.
+  }
+
+  private buildRequestParams(
+    messages: TUniversalMessage[],
+    options: IChatOptions | undefined,
+  ): TDeepSeekChatCompletionCreateParamsNonStreaming {
+    this.validateTools(options?.tools);
+    const model = options?.model ?? this.options.defaultModel;
+    if (!model) {
+      throw new Error(
+        'Model is required in chat options. Please specify a model in defaultModel configuration.',
+      );
+    }
+
+    return {
+      model,
+      messages: convertToOpenAICompatibleMessages(messages),
+      ...(options?.temperature !== undefined && { temperature: options.temperature }),
+      ...(options?.maxTokens !== undefined && { max_tokens: options.maxTokens }),
+      ...(options?.tools && {
+        tools: convertToOpenAICompatibleTools(options.tools),
+        tool_choice: 'auto' as const,
+      }),
+      ...(this.options.thinking !== undefined && {
+        thinking: { type: this.options.thinking },
+      }),
+      ...(this.options.reasoningEffort !== undefined && {
+        reasoning_effort: this.options.reasoningEffort,
+      }),
+    };
+  }
+
+  private buildStreamingRequestParams(
+    messages: TUniversalMessage[],
+    options: IChatOptions | undefined,
+  ): TDeepSeekChatCompletionCreateParamsStreaming {
+    return {
+      ...this.buildRequestParams(messages, options),
+      stream: true,
+    };
+  }
+
+  private getClient(): OpenAI {
+    if (!this.client) {
+      throw new Error(
+        'DeepSeek client not available. Either provide a client/apiKey or use an executor.',
+      );
+    }
+
+    return this.client;
+  }
+
+  private async chatWithStreamingAssembly(
+    requestParams: TDeepSeekChatCompletionCreateParamsStreaming,
+    options: IChatOptions,
+  ): Promise<TUniversalMessage> {
+    const client = this.getClient();
+
+    try {
+      options.onProviderNativeRawPayload?.({
+        provider: 'deepseek',
+        apiSurface: 'chat-completions',
+        payloadKind: 'request',
+        payload: requestParams,
+      });
+      const stream = await client.chat.completions.create(
+        requestParams as OpenAI.Chat.ChatCompletionCreateParamsStreaming,
+        options.signal ? { signal: options.signal } : undefined,
+      );
+
+      return assembleOpenAICompatibleStream({
+        stream: observeProviderNativeRawPayloadStream(stream, {
+          provider: 'deepseek',
+          apiSurface: 'chat-completions',
+          onProviderNativeRawPayload: options.onProviderNativeRawPayload,
+        }),
+        onTextDelta: options.onTextDelta,
+        signal: options.signal,
+      });
+    } catch (error) {
+      const deepSeekError = error as IOpenAICompatibleError;
+      const errorMessage = deepSeekError.message || 'DeepSeek streaming request failed';
+      throw new Error(`DeepSeek stream failed: ${errorMessage}`);
+    }
+  }
+}

package/src/deepseek/types.ts

@@ -0,0 +1,37 @@
+import type OpenAI from 'openai';
+import type { IExecutor, ILogger, TProviderOptionValueBase } from '@robota-sdk/agent-core';
+
+export type TDeepSeekThinkingMode = 'enabled' | 'disabled';
+export type TDeepSeekReasoningEffort = 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+
+export interface IDeepSeekThinkingConfig {
+  type: TDeepSeekThinkingMode;
+}
+
+export type TDeepSeekProviderOptionValue =
+  | string
+  | number
+  | boolean
+  | undefined
+  | null
+  | IDeepSeekThinkingConfig
+  | OpenAI
+  | ILogger
+  | IExecutor
+  | TProviderOptionValueBase
+  | TDeepSeekProviderOptionValue[]
+  | { [key: string]: TDeepSeekProviderOptionValue };
+
+export interface IDeepSeekProviderOptions {
+  [key: string]: TDeepSeekProviderOptionValue;
+
+  apiKey?: string;
+  baseURL?: string;
+  timeout?: number;
+  defaultModel?: string;
+  thinking?: TDeepSeekThinkingMode;
+  reasoningEffort?: TDeepSeekReasoningEffort;
+  client?: OpenAI;
+  executor?: IExecutor;
+  logger?: ILogger;
+}

package/src/gemini/execution-helpers.ts

@@ -0,0 +1,233 @@
+import { randomUUID } from 'node:crypto';
+import type { GoogleGenAI } from '@google/genai';
+import type { Content, GenerateContentParameters, GenerateContentResponse } from '@google/genai';
+import type { IGeminiProviderOptions } from './types';
+import type {
+  TUniversalMessage,
+  IChatOptions,
+  IImageGenerationResult,
+  TProviderMediaResult,
+} from '@robota-sdk/agent-core';
+import {
+  convertToGeminiRequestFormat,
+  convertFromGeminiResponse,
+  convertToolsToGeminiFormat,
+} from './message-converter';
+import {
+  hasImagePart,
+  mapInlineImagePartsToMediaOutputs,
+  buildResponseModalities,
+  buildGenerationConfig,
+} from './image-operations';
+
+/**
+ * Execute a direct (non-streaming) chat request against the Gemini API.
+ */
+export async function executeDirect(
+  client: GoogleGenAI,
+  providerOptions: IGeminiProviderOptions,
+  messages: TUniversalMessage[],
+  options?: IChatOptions,
+  providerName = 'gemini',
+): Promise<TUniversalMessage> {
+  const model = resolveGeminiModel(providerOptions, options);
+  const responseModalities = buildResponseModalities(
+    messages,
+    providerOptions.defaultResponseModalities,
+    options?.google?.responseModalities,
+  );
+
+  if (options?.onTextDelta && !responseModalities.includes('IMAGE')) {
+    return assembleStreamingChatResponse(client, providerOptions, messages, options, providerName);
+  }
+
+  const requestFormat = convertToGeminiRequestFormat(messages);
+  const genConfig = buildGenerationConfig(messages, providerOptions, { ...options, model });
+  const request = buildGenerateContentRequest(
+    model,
+    requestFormat.contents,
+    genConfig,
+    options,
+    requestFormat.systemInstruction,
+  );
+
+  emitGeminiNativeRawPayload(options, providerName, 'request', request);
+  const result = await client.models.generateContent(request);
+  emitGeminiNativeRawPayload(options, providerName, 'response', result);
+
+  const convertedResponse = convertFromGeminiResponse(result);
+  if (responseModalities.includes('IMAGE') && !hasImagePart(convertedResponse.parts)) {
+    throw new Error(
+      'Gemini response did not include an image part while IMAGE modality was requested.',
+    );
+  }
+  return convertedResponse;
+}
+
+/**
+ * Execute a streaming chat request against the Gemini API.
+ */
+export async function* executeDirectStream(
+  client: GoogleGenAI,
+  providerOptions: IGeminiProviderOptions,
+  messages: TUniversalMessage[],
+  options?: IChatOptions,
+  providerName = 'gemini',
+): AsyncIterable<TUniversalMessage> {
+  const model = resolveGeminiModel(providerOptions, options);
+  const responseModalities = buildResponseModalities(
+    messages,
+    providerOptions.defaultResponseModalities,
+    options?.google?.responseModalities,
+  );
+  if (responseModalities.includes('IMAGE')) {
+    throw new Error('Google provider does not support streaming image modality responses.');
+  }
+
+  const requestFormat = convertToGeminiRequestFormat(messages);
+  const genConfig = buildGenerationConfig(messages, providerOptions, { ...options, model });
+  const request = buildGenerateContentRequest(
+    model,
+    requestFormat.contents,
+    genConfig,
+    options,
+    requestFormat.systemInstruction,
+  );
+
+  emitGeminiNativeRawPayload(options, providerName, 'request', request);
+  const stream = await client.models.generateContentStream(request);
+
+  let sequence = 0;
+  for await (const chunk of stream) {
+    emitGeminiNativeRawPayload(options, providerName, 'stream_event', chunk, sequence);
+    sequence++;
+    const text = extractStreamText(chunk);
+    if (text) {
+      options?.onTextDelta?.(text);
+      yield {
+        id: randomUUID(),
+        role: 'assistant',
+        content: text,
+        state: 'complete' as const,
+        timestamp: new Date(),
+      };
+    }
+  }
+}
+
+function buildGenerateContentRequest(
+  model: string,
+  contents: Content[],
+  generationOptions: GenerateContentParameters['config'],
+  options?: IChatOptions,
+  systemInstruction?: string,
+): GenerateContentParameters {
+  const config: GenerateContentParameters['config'] = { ...generationOptions };
+  if (options?.tools && options.tools.length > 0) {
+    config.tools = [{ functionDeclarations: convertToolsToGeminiFormat(options.tools) }];
+  }
+  if (systemInstruction) {
+    config.systemInstruction = systemInstruction;
+  }
+  return {
+    model,
+    contents,
+    config,
+  };
+}
+
+function resolveGeminiModel(
+  providerOptions: IGeminiProviderOptions,
+  options?: IChatOptions,
+): string {
+  const model = options?.model ?? providerOptions.defaultModel;
+  if (!model) {
+    throw new Error(
+      'Model is required in chat options. Please specify a model in defaultModel configuration.',
+    );
+  }
+  return model;
+}
+
+async function assembleStreamingChatResponse(
+  client: GoogleGenAI,
+  providerOptions: IGeminiProviderOptions,
+  messages: TUniversalMessage[],
+  options: IChatOptions,
+  providerName = 'gemini',
+): Promise<TUniversalMessage> {
+  const textParts: string[] = [];
+  for await (const chunk of executeDirectStream(
+    client,
+    providerOptions,
+    messages,
+    options,
+    providerName,
+  )) {
+    if (typeof chunk.content === 'string') {
+      textParts.push(chunk.content);
+    }
+  }
+  const content = textParts.join('');
+  return {
+    id: randomUUID(),
+    role: 'assistant',
+    content,
+    parts: content.length > 0 ? [{ type: 'text', text: content }] : [],
+    state: 'complete',
+    timestamp: new Date(),
+  };
+}
+
+function emitGeminiNativeRawPayload(
+  options: IChatOptions | undefined,
+  providerName: string,
+  payloadKind: 'request' | 'response' | 'stream_event',
+  payload: object,
+  sequence?: number,
+): void {
+  options?.onProviderNativeRawPayload?.({
+    provider: providerName,
+    apiSurface: 'gemini-generate-content',
+    payloadKind,
+    ...(sequence !== undefined && { sequence }),
+    payload,
+  });
+}
+
+function extractStreamText(
+  chunk: GenerateContentResponse | { readonly text?: () => string },
+): string | undefined {
+  const textValue = chunk.text;
+  return typeof textValue === 'function' ? textValue() : textValue;
+}
+
+/**
+ * Run an image generation request through the chat API.
+ */
+export async function runImageRequest(
+  chatFn: (messages: TUniversalMessage[], options?: IChatOptions) => Promise<TUniversalMessage>,
+  messages: TUniversalMessage[],
+  model: string,
+): Promise<TProviderMediaResult<IImageGenerationResult>> {
+  try {
+    const response = await chatFn(messages, {
+      model,
+      google: { responseModalities: ['TEXT', 'IMAGE'] },
+    });
+    const outputs = mapInlineImagePartsToMediaOutputs(response.parts);
+    if (outputs.length === 0) {
+      return {
+        ok: false,
+        error: {
+          code: 'PROVIDER_UPSTREAM_ERROR',
+          message: 'Google image response did not include image output parts.',
+        },
+      };
+    }
+    return { ok: true, value: { outputs, model } };
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : 'Google image request failed.';
+    return { ok: false, error: { code: 'PROVIDER_UPSTREAM_ERROR', message: errorMessage } };
+  }
+}