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

package/src/gemma/provider.ts

@@ -0,0 +1,308 @@
+import OpenAI from 'openai';
+import { AbstractAIProvider, SilentLogger } from '@robota-sdk/agent-core';
+import type {
+  IAssistantMessage,
+  IChatOptions,
+  IProviderCapabilities,
+  TTextDeltaCallback,
+  TUniversalMessage,
+} from '@robota-sdk/agent-core';
+import {
+  assembleOpenAICompatibleStream,
+  convertToOpenAICompatibleMessages,
+  convertToOpenAICompatibleTools,
+  observeProviderNativeRawPayloadStream,
+} from '../shared/openai-compatible/index.js';
+import type { IOpenAICompatibleError } from '../shared/openai-compatible/index.js';
+import type { IGemmaProviderOptions } from './types';
+import { GemmaReasoningProjector } from './reasoning-projector';
+import { createGemmaToolCallProjector } from './tool-call-projector';
+import { parseGemmaChatCompletion, withGemmaProjectionMetadata } from './provider-projection';
+import {
+  createGemmaStreamProjectionState,
+  flushGemmaStreamProjection,
+  projectGemmaStreamChunk,
+} from './streaming-projection';
+
+export class GemmaProvider extends AbstractAIProvider {
+  override readonly name = 'gemma';
+  override readonly version = '1.0.0';
+
+  private readonly client?: OpenAI;
+  private readonly options: IGemmaProviderOptions;
+
+  onTextDelta?: TTextDeltaCallback;
+
+  constructor(options: IGemmaProviderOptions) {
+    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,
+          ...(options.baseURL !== undefined && { baseURL: options.baseURL }),
+          ...(options.timeout !== undefined && { timeout: options.timeout }),
+        });
+      } else {
+        throw new Error('Either Gemma client, apiKey, or executor is required');
+      }
+    }
+  }
+
+  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(
+          'Gemma Provider executor chat error:',
+          error instanceof Error ? error.message : String(error),
+        );
+        throw error;
+      }
+    }
+
+    if (!this.client) {
+      throw new Error(
+        'Gemma client not available. Either provide a client/apiKey or use an executor.',
+      );
+    }
+
+    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: 'gemma',
+        apiSurface: 'chat-completions',
+        payloadKind: 'request',
+        payload: requestParams,
+      });
+      const response = await this.client.chat.completions.create(requestParams);
+      options?.onProviderNativeRawPayload?.({
+        provider: 'gemma',
+        apiSurface: 'chat-completions',
+        payloadKind: 'response',
+        payload: response,
+      });
+      return parseGemmaChatCompletion(response, this.logger, options);
+    } catch (error) {
+      const gemmaError = error as IOpenAICompatibleError;
+      const errorMessage = gemmaError.message || 'Gemma API request failed';
+      throw new Error(`Gemma 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(
+          'Gemma Provider executor stream error:',
+          error instanceof Error ? error.message : String(error),
+        );
+        throw error;
+      }
+    }
+
+    if (!this.client) {
+      throw new Error(
+        'Gemma client not available. Either provide a client/apiKey or use an executor.',
+      );
+    }
+
+    try {
+      const requestParams = this.buildStreamingRequestParams(messages, options);
+      options?.onProviderNativeRawPayload?.({
+        provider: 'gemma',
+        apiSurface: 'chat-completions',
+        payloadKind: 'request',
+        payload: requestParams,
+      });
+      const stream = await this.client.chat.completions.create(requestParams);
+      const projectionState = createGemmaStreamProjectionState(this.logger, options?.tools);
+
+      const observedStream = observeProviderNativeRawPayloadStream(stream, {
+        provider: 'gemma',
+        apiSurface: 'chat-completions',
+        onProviderNativeRawPayload: options?.onProviderNativeRawPayload,
+      });
+
+      for await (const chunk of this.streamWithAbort(observedStream, options?.signal)) {
+        for (const message of projectGemmaStreamChunk(chunk, projectionState)) {
+          yield message;
+        }
+      }
+
+      for (const message of flushGemmaStreamProjection(projectionState)) {
+        yield message;
+      }
+    } catch (error) {
+      const gemmaError = error as IOpenAICompatibleError;
+      const errorMessage = gemmaError.message || 'Gemma API request failed';
+      throw new Error(`Gemma 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:
+            'Gemma OpenAI-compatible endpoints support declared function tools, not provider-native web search.',
+        },
+        webFetch: {
+          supported: false,
+          enabled: false,
+          source: 'openai-compatible-chat-completions',
+          reason:
+            'Gemma OpenAI-compatible endpoints support declared function tools, not provider-native web fetch.',
+        },
+      },
+    };
+  }
+
+  override validateConfig(): boolean {
+    return !!this.client && !!this.options;
+  }
+
+  override async dispose(): Promise<void> {
+    // OpenAI-compatible local clients do not need explicit cleanup.
+  }
+
+  protected override validateMessages(messages: TUniversalMessage[]): void {
+    super.validateMessages(messages);
+
+    for (const message of messages) {
+      if (message.role === 'assistant') {
+        const assistantMsg = message as IAssistantMessage;
+        if (
+          assistantMsg.toolCalls &&
+          assistantMsg.toolCalls.length > 0 &&
+          assistantMsg.content === ''
+        ) {
+          continue;
+        }
+      }
+    }
+  }
+
+  private buildRequestParams(
+    messages: TUniversalMessage[],
+    options: IChatOptions | undefined,
+  ): OpenAI.Chat.ChatCompletionCreateParamsNonStreaming {
+    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.',
+      );
+    }
+
+    const requestParams = {
+      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,
+      }),
+    };
+
+    return requestParams as OpenAI.Chat.ChatCompletionCreateParamsNonStreaming;
+  }
+
+  private buildStreamingRequestParams(
+    messages: TUniversalMessage[],
+    options: IChatOptions | undefined,
+  ): OpenAI.Chat.ChatCompletionCreateParamsStreaming {
+    return {
+      ...this.buildRequestParams(messages, options),
+      stream: true,
+    } as OpenAI.Chat.ChatCompletionCreateParamsStreaming;
+  }
+
+  private async chatWithStreamingAssembly(
+    requestParams: OpenAI.Chat.ChatCompletionCreateParamsStreaming,
+    options: IChatOptions,
+  ): Promise<TUniversalMessage> {
+    if (!this.client) {
+      throw new Error(
+        'Gemma client not available. Either provide a client/apiKey or use an executor.',
+      );
+    }
+
+    try {
+      options.onProviderNativeRawPayload?.({
+        provider: 'gemma',
+        apiSurface: 'chat-completions',
+        payloadKind: 'request',
+        payload: requestParams,
+      });
+      const stream = await this.client.chat.completions.create(
+        requestParams,
+        options.signal ? { signal: options.signal } : undefined,
+      );
+      const projector = new GemmaReasoningProjector();
+      const result = await assembleOpenAICompatibleStream({
+        stream: observeProviderNativeRawPayloadStream(stream, {
+          provider: 'gemma',
+          apiSurface: 'chat-completions',
+          onProviderNativeRawPayload: options.onProviderNativeRawPayload,
+        }),
+        onTextDelta: options.onTextDelta,
+        signal: options.signal,
+        textProjector: (text) => projector.project(text),
+        textProjectorFlush: () => projector.flush(),
+        toolCallTextProjector: createGemmaToolCallProjector(options.tools),
+      });
+
+      return withGemmaProjectionMetadata(result, projector.rawText, projector.removedReasoning);
+    } catch (error) {
+      const gemmaError = error as IOpenAICompatibleError;
+      const errorMessage = gemmaError.message || 'Gemma streaming request failed';
+      throw new Error(`Gemma stream failed: ${errorMessage}`);
+    }
+  }
+}

package/src/gemma/pseudo-command-envelope.ts

@@ -0,0 +1,58 @@
+import { findGemmaDeclaredToolName } from './pseudo-tool-call-tag-parser';
+import type { TGemmaJsonValue } from './pseudo-tool-call-types';
+
+export interface IGemmaPseudoCommandEnvelope {
+  toolName: string;
+  args: Record<string, TGemmaJsonValue>;
+}
+
+export function parseGemmaPseudoCommandEnvelopes(
+  rawText: string,
+  toolNames: readonly string[],
+): IGemmaPseudoCommandEnvelope[] {
+  const jsonEnvelope = parseGemmaPseudoCommandEnvelope(rawText, toolNames);
+  return jsonEnvelope ? [jsonEnvelope] : [];
+}
+
+export function parseGemmaPseudoCommandEnvelope(
+  rawText: string,
+  toolNames: readonly string[],
+): IGemmaPseudoCommandEnvelope | undefined {
+  const openEnd = rawText.indexOf('>');
+  const closeStart = rawText.lastIndexOf('</');
+  if (openEnd === -1 || closeStart === -1 || closeStart <= openEnd) {
+    return undefined;
+  }
+
+  const parsed = parseJsonValue(rawText.slice(openEnd + 1, closeStart).trim());
+  if (!isJsonRecord(parsed)) {
+    return undefined;
+  }
+
+  const command = parsed['command'];
+  const args = parsed['args'];
+  if (typeof command !== 'string' || !isJsonRecord(args)) {
+    return undefined;
+  }
+
+  const toolName = findGemmaDeclaredToolName(command, toolNames);
+  if (!toolName) {
+    return undefined;
+  }
+
+  return { toolName, args };
+}
+
+function parseJsonValue(text: string): TGemmaJsonValue | undefined {
+  try {
+    return JSON.parse(text) as TGemmaJsonValue;
+  } catch {
+    return undefined;
+  }
+}
+
+function isJsonRecord(
+  value: TGemmaJsonValue | undefined,
+): value is Record<string, TGemmaJsonValue> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/src/gemma/pseudo-tool-call-projector.ts

@@ -0,0 +1,243 @@
+import type { IToolCall } from '@robota-sdk/agent-core';
+import { parseGemmaPseudoCommandEnvelopes } from './pseudo-command-envelope';
+import {
+  consumeGemmaPseudoControlBlock,
+  consumeGemmaPseudoToolTag,
+  createGemmaPseudoStartMarkers,
+  findGemmaDeclaredToolName,
+  findNextGemmaPseudoStartMarker,
+  longestGemmaPseudoStartPrefixSuffixLength,
+  parseGemmaPseudoTag,
+} from './pseudo-tool-call-tag-parser';
+import type {
+  IGemmaConsumedPseudoBlock,
+  IGemmaParsedPseudoTag,
+  IGemmaPseudoProjectionOptions,
+  TGemmaJsonValue,
+} from './pseudo-tool-call-types';
+
+const DEFAULT_CALL_ID_PREFIX = 'gemma_call';
+
+export interface IGemmaPseudoToolCallProjection {
+  visibleText: string;
+  toolCalls: IToolCall[];
+  removedToolCallText: boolean;
+  rawToolCallTextParts: string[];
+}
+
+export interface IGemmaPseudoToolCallProjectorOptions {
+  toolNames: readonly string[];
+  callIdPrefix?: string;
+  startCallIndex?: number;
+}
+
+interface IProjectionState {
+  visibleParts: string[];
+  toolCalls: IToolCall[];
+  rawToolCallTextParts: string[];
+  removedToolCallText: boolean;
+}
+
+interface IProjectTagResult {
+  cursor: number;
+  completed: boolean;
+}
+
+export function projectGemmaPseudoToolCallText(
+  rawText: string,
+  options: IGemmaPseudoToolCallProjectorOptions,
+  projectionOptions: IGemmaPseudoProjectionOptions,
+): IGemmaPseudoToolCallProjection {
+  const state = createProjectionState();
+  const markers = createGemmaPseudoStartMarkers(options.toolNames);
+  let cursor = 0;
+
+  while (cursor < rawText.length) {
+    const nextMarker = findNextGemmaPseudoStartMarker(rawText, cursor, markers);
+    if (nextMarker === -1) {
+      appendVisibleTail(state, rawText.slice(cursor), projectionOptions, markers);
+      break;
+    }
+
+    appendVisibleTail(state, rawText.slice(cursor, nextMarker), projectionOptions, markers);
+    const result = projectTagAt(rawText, nextMarker, state, options, projectionOptions);
+    if (!result.completed) {
+      break;
+    }
+    cursor = result.cursor;
+  }
+
+  return {
+    visibleText: state.visibleParts.join(''),
+    toolCalls: state.toolCalls,
+    rawToolCallTextParts: state.rawToolCallTextParts,
+    removedToolCallText: state.removedToolCallText,
+  };
+}
+
+function projectTagAt(
+  rawText: string,
+  tagStart: number,
+  state: IProjectionState,
+  options: IGemmaPseudoToolCallProjectorOptions,
+  projectionOptions: IGemmaPseudoProjectionOptions,
+): IProjectTagResult {
+  const tag = parseGemmaPseudoTag(rawText, tagStart);
+  if (!tag) {
+    return projectMalformedTag(rawText, tagStart, state, projectionOptions);
+  }
+  const toolName = findGemmaDeclaredToolName(tag.tagName, options.toolNames);
+  if (toolName) {
+    return projectToolTag(rawText, tag, toolName, state, options);
+  }
+  return projectXmlArtifact(rawText, tagStart, tag, state, options, projectionOptions);
+}
+
+function projectMalformedTag(
+  rawText: string,
+  tagStart: number,
+  state: IProjectionState,
+  projectionOptions: IGemmaPseudoProjectionOptions,
+): IProjectTagResult {
+  if (!projectionOptions.final) {
+    return { cursor: tagStart, completed: false };
+  }
+  state.visibleParts.push(rawText[tagStart] ?? '');
+  return { cursor: tagStart + 1, completed: true };
+}
+
+function projectXmlArtifact(
+  rawText: string,
+  tagStart: number,
+  tag: IGemmaParsedPseudoTag,
+  state: IProjectionState,
+  options: IGemmaPseudoToolCallProjectorOptions,
+  projectionOptions: IGemmaPseudoProjectionOptions,
+): IProjectTagResult {
+  const block = consumeGemmaPseudoControlBlock(rawText, tag, projectionOptions);
+  if (!block.complete && !projectionOptions.final) {
+    return { cursor: tagStart, completed: false };
+  }
+
+  const rawControlText = rawText.slice(tagStart, block.end);
+  const rawPartCount = state.rawToolCallTextParts.length;
+  state.removedToolCallText = true;
+  appendCommandEnvelopeToolCall(state, rawControlText, options);
+  mergeProjection(state, projectControlBlockInner(block, state, options));
+  if (state.rawToolCallTextParts.length === rawPartCount) {
+    state.rawToolCallTextParts.push(rawControlText);
+  }
+  return { cursor: block.end, completed: true };
+}
+
+function projectControlBlockInner(
+  block: IGemmaConsumedPseudoBlock,
+  state: IProjectionState,
+  options: IGemmaPseudoToolCallProjectorOptions,
+): IGemmaPseudoToolCallProjection {
+  return projectGemmaPseudoToolCallText(
+    block.innerText,
+    {
+      ...options,
+      startCallIndex: getNextCallIndex(state, options),
+    },
+    { final: true },
+  );
+}
+
+function projectToolTag(
+  rawText: string,
+  tag: IGemmaParsedPseudoTag,
+  toolName: string,
+  state: IProjectionState,
+  options: IGemmaPseudoToolCallProjectorOptions,
+): IProjectTagResult {
+  const rawToolTag = consumeGemmaPseudoToolTag(rawText, tag);
+  appendToolCall(state, toolName, tag.attributes, rawToolTag.rawText, options);
+  return { cursor: rawToolTag.end, completed: true };
+}
+
+function appendVisibleTail(
+  state: IProjectionState,
+  tail: string,
+  options: IGemmaPseudoProjectionOptions,
+  markers: readonly string[],
+): void {
+  if (tail.length === 0) {
+    return;
+  }
+  if (options.final) {
+    state.visibleParts.push(tail);
+    return;
+  }
+  const heldLength = longestGemmaPseudoStartPrefixSuffixLength(tail, markers);
+  state.visibleParts.push(tail.slice(0, tail.length - heldLength));
+}
+
+function appendToolCall(
+  state: IProjectionState,
+  toolName: string,
+  args: Record<string, TGemmaJsonValue>,
+  rawText: string,
+  options: IGemmaPseudoToolCallProjectorOptions,
+): void {
+  if (Object.keys(args).length === 0) {
+    return;
+  }
+  state.toolCalls.push(createToolCall(toolName, args, options, state));
+  state.rawToolCallTextParts.push(rawText);
+  state.removedToolCallText = true;
+}
+
+function appendCommandEnvelopeToolCall(
+  state: IProjectionState,
+  rawText: string,
+  options: IGemmaPseudoToolCallProjectorOptions,
+): void {
+  const commands = parseGemmaPseudoCommandEnvelopes(rawText, options.toolNames);
+  for (const command of commands) {
+    state.toolCalls.push(createToolCall(command.toolName, command.args, options, state));
+    state.rawToolCallTextParts.push(rawText);
+  }
+}
+
+function createToolCall(
+  toolName: string,
+  args: Record<string, TGemmaJsonValue>,
+  options: IGemmaPseudoToolCallProjectorOptions,
+  state: IProjectionState,
+): IToolCall {
+  return {
+    id: `${options.callIdPrefix ?? DEFAULT_CALL_ID_PREFIX}_${getNextCallIndex(state, options)}`,
+    type: 'function',
+    function: {
+      name: toolName,
+      arguments: JSON.stringify(args),
+    },
+  };
+}
+
+function createProjectionState(): IProjectionState {
+  return {
+    visibleParts: [],
+    toolCalls: [],
+    rawToolCallTextParts: [],
+    removedToolCallText: false,
+  };
+}
+
+function mergeProjection(
+  state: IProjectionState,
+  projection: IGemmaPseudoToolCallProjection,
+): void {
+  state.toolCalls.push(...projection.toolCalls);
+  state.rawToolCallTextParts.push(...projection.rawToolCallTextParts);
+  state.removedToolCallText = state.removedToolCallText || projection.removedToolCallText;
+}
+
+function getNextCallIndex(
+  state: IProjectionState,
+  options: IGemmaPseudoToolCallProjectorOptions,
+): number {
+  return (options.startCallIndex ?? 0) + state.toolCalls.length;
+}