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

package/src/gemini/tool-schema-converter.ts

@@ -0,0 +1,78 @@
+import { Type } from '@google/genai';
+import type { FunctionDeclaration, Schema } from '@google/genai';
+import type { IParameterSchema, IToolSchema, TJSONSchemaKind } from '@robota-sdk/agent-core';
+
+const GOOGLE_SCHEMA_TYPE_BY_JSON_KIND: Record<Exclude<TJSONSchemaKind, 'null'>, Type> = {
+  string: Type.STRING,
+  number: Type.NUMBER,
+  integer: Type.INTEGER,
+  boolean: Type.BOOLEAN,
+  array: Type.ARRAY,
+  object: Type.OBJECT,
+};
+
+/** Converts Robota tool schemas to Gemini function declarations. */
+export function convertToolsToGeminiFormat(tools: IToolSchema[]): FunctionDeclaration[] {
+  return tools.map((tool) => ({
+    name: tool.name,
+    description: tool.description,
+    parameters: {
+      type: Type.OBJECT,
+      properties: convertParameterProperties(tool.parameters.properties),
+      required: tool.parameters.required,
+    },
+  }));
+}
+
+function convertParameterProperties(
+  properties: Record<string, IParameterSchema>,
+): Record<string, Schema> {
+  const convertedProperties: Record<string, Schema> = {};
+  for (const [key, value] of Object.entries(properties)) {
+    convertedProperties[key] = convertParameterSchema(value);
+  }
+  return convertedProperties;
+}
+
+function convertParameterSchema(schema: IParameterSchema): Schema {
+  const convertedSchema: Schema = {};
+  const schemaType = convertSchemaKind(schema.type);
+  if (schemaType) {
+    convertedSchema.type = schemaType;
+  }
+  if (schema.description) {
+    convertedSchema.description = schema.description;
+  }
+  if (schema.enum) {
+    convertedSchema.enum = schema.enum.map(String);
+  }
+  if (schema.items) {
+    convertedSchema.items = convertParameterSchema(schema.items);
+  }
+  if (schema.properties) {
+    convertedSchema.properties = convertParameterProperties(schema.properties);
+  }
+  if (typeof schema.minimum === 'number') {
+    convertedSchema.minimum = schema.minimum;
+  }
+  if (typeof schema.maximum === 'number') {
+    convertedSchema.maximum = schema.maximum;
+  }
+  if (schema.pattern) {
+    convertedSchema.pattern = schema.pattern;
+  }
+  if (schema.format) {
+    convertedSchema.format = schema.format;
+  }
+  if (schema.default !== undefined) {
+    convertedSchema.default = schema.default;
+  }
+  return convertedSchema;
+}
+
+function convertSchemaKind(kind: TJSONSchemaKind): Type | undefined {
+  if (kind === 'null') {
+    return undefined;
+  }
+  return GOOGLE_SCHEMA_TYPE_BY_JSON_KIND[kind];
+}

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

@@ -0,0 +1,235 @@
+/**
+ * Google AI API-specific type definitions
+ *
+ * This file contains type definitions specific to Google AI's Gemini API,
+ * ensuring complete type safety without any/unknown types.
+ */
+
+// Google AI Request Types
+export interface IGoogleModelConfig {
+  temperature?: number;
+  topK?: number;
+  topP?: number;
+  maxOutputTokens?: number;
+  stopSequences?: string[];
+  candidateCount?: number;
+  responseMimeType?: string;
+  responseSchema?: Record<string, TGoogleJsonValue>;
+  responseJsonSchema?: Record<string, TGoogleJsonValue>;
+  responseModalities?: Array<'TEXT' | 'IMAGE'>;
+  tools?: IGoogleTool[];
+  toolConfig?: Record<string, TGoogleJsonValue>;
+  safetySettings?: IGoogleSafetySetting[];
+  thinkingConfig?: IGoogleThinkingConfig;
+}
+
+export interface IGoogleGenerateContentRequest {
+  model: string;
+  contents: IGoogleContent[];
+  systemInstruction?: IGoogleContent;
+  config?: IGoogleModelConfig;
+}
+
+export interface IGoogleStreamGenerateContentRequest extends IGoogleGenerateContentRequest {
+  // Streaming uses the same request structure
+}
+
+// Content Types
+export interface IGoogleContent {
+  parts: IGooglePart[];
+  role?: 'user' | 'model';
+}
+
+export interface IGooglePart {
+  text?: string;
+  inlineData?: {
+    mimeType: string;
+    data: string;
+  };
+  functionCall?: IGoogleFunctionCall;
+  functionResponse?: IGoogleFunctionResponse;
+}
+
+export interface IGoogleFunctionCall {
+  id?: string;
+  name: string;
+  args: Record<string, string | number | boolean | object>;
+}
+
+export interface IGoogleFunctionResponse {
+  id?: string;
+  name: string;
+  response: Record<string, TGoogleJsonValue>;
+}
+
+export type TGoogleJsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | TGoogleJsonValue[]
+  | { [key: string]: TGoogleJsonValue };
+
+export interface IGoogleSafetySetting {
+  category: string;
+  threshold: string;
+}
+
+export interface IGoogleThinkingConfig {
+  includeThoughts?: boolean;
+  thinkingBudget?: number;
+  thinkingLevel?: string;
+}
+
+// Tool Types
+export interface IGoogleTool {
+  functionDeclarations: IGoogleFunctionDeclaration[];
+}
+
+export interface IGoogleFunctionDeclaration {
+  name: string;
+  description?: string;
+  parameters: IGoogleFunctionParameters;
+}
+
+export interface IGoogleFunctionParameters {
+  type: 'object';
+  properties: Record<string, IGooglePropertySchema>;
+  required?: string[];
+}
+
+export interface IGooglePropertySchema {
+  type: 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'object';
+  description?: string;
+  enum?: string[];
+  items?: IGooglePropertySchema;
+  properties?: Record<string, IGooglePropertySchema>;
+}
+
+// Response Types
+export interface IGoogleGenerateContentResponse {
+  candidates: IGoogleCandidate[];
+  promptFeedback?: IGooglePromptFeedback;
+  usageMetadata?: IGoogleUsageMetadata;
+}
+
+export interface IGoogleCandidate {
+  content: IGoogleContent;
+  finishReason?: TGoogleFinishReason;
+  index: number;
+  safetyRatings?: IGoogleSafetyRating[];
+  citationMetadata?: IGoogleCitationMetadata;
+}
+
+export type TGoogleFinishReason =
+  | 'FINISH_REASON_UNSPECIFIED'
+  | 'STOP'
+  | 'MAX_TOKENS'
+  | 'SAFETY'
+  | 'RECITATION'
+  | 'OTHER';
+
+export interface IGoogleSafetyRating {
+  category: TGoogleHarmCategory;
+  probability: TGoogleHarmProbability;
+}
+
+export type TGoogleHarmCategory =
+  | 'HARM_CATEGORY_UNSPECIFIED'
+  | 'HARM_CATEGORY_DEROGATORY'
+  | 'HARM_CATEGORY_TOXICITY'
+  | 'HARM_CATEGORY_VIOLENCE'
+  | 'HARM_CATEGORY_SEXUAL'
+  | 'HARM_CATEGORY_MEDICAL'
+  | 'HARM_CATEGORY_DANGEROUS';
+
+export type TGoogleHarmProbability =
+  | 'HARM_PROBABILITY_UNSPECIFIED'
+  | 'NEGLIGIBLE'
+  | 'LOW'
+  | 'MEDIUM'
+  | 'HIGH';
+
+export interface IGoogleCitationMetadata {
+  citationSources: IGoogleCitationSource[];
+}
+
+export interface IGoogleCitationSource {
+  startIndex?: number;
+  endIndex?: number;
+  uri?: string;
+  license?: string;
+}
+
+export interface IGooglePromptFeedback {
+  blockReason?: TGoogleBlockReason;
+  safetyRatings?: IGoogleSafetyRating[];
+}
+
+export type TGoogleBlockReason = 'BLOCK_REASON_UNSPECIFIED' | 'SAFETY' | 'OTHER';
+
+export interface IGoogleUsageMetadata {
+  promptTokenCount: number;
+  candidatesTokenCount: number;
+  totalTokenCount: number;
+}
+
+// Streaming Types
+export interface IGoogleStreamChunk {
+  candidates?: IGoogleCandidate[];
+  promptFeedback?: IGooglePromptFeedback;
+  usageMetadata?: IGoogleUsageMetadata;
+}
+
+// Error Types
+export interface IGoogleError {
+  error: {
+    code: number;
+    message: string;
+    status: string;
+    details?: IGoogleErrorDetail[];
+  };
+}
+
+export interface IGoogleErrorDetail {
+  '@type': string;
+  reason?: string;
+  domain?: string;
+  metadata?: Record<string, string>;
+}
+
+// Provider Configuration
+export interface IGoogleLogData {
+  model: string;
+  messagesCount: number;
+  hasTools: boolean;
+  temperature?: number;
+  maxOutputTokens?: number;
+  timestamp: string;
+  requestId?: string;
+  usage?: IGoogleUsageMetadata;
+}
+
+// Tool Call Types for Internal Processing
+export interface IGoogleToolCall {
+  id: string;
+  type: 'function';
+  function: {
+    name: string;
+    arguments: string;
+  };
+}
+
+// Message Conversion Types
+export interface IGoogleMessageConversionResult {
+  contents: IGoogleContent[];
+  systemInstruction?: IGoogleContent;
+}
+
+// Stream Context for Managing State
+export interface IGoogleStreamContext {
+  currentMessage: string;
+  currentToolCalls: IGoogleToolCall[];
+  isComplete: boolean;
+  usage?: IGoogleUsageMetadata;
+}

package/src/gemini/types.ts

@@ -0,0 +1,121 @@
+import type { IExecutor, TProviderOptionValueBase } from '@robota-sdk/agent-core';
+
+/**
+ * Valid provider option value types
+ */
+export type TGeminiProviderOptionValue =
+  | string
+  | number
+  | boolean
+  | undefined
+  | null
+  | IExecutor
+  | TProviderOptionValueBase
+  | TGeminiProviderOptionValue[]
+  | { [key: string]: TGeminiProviderOptionValue };
+
+export interface IGeminiSafetySetting {
+  [key: string]: TGeminiProviderOptionValue;
+  category: string;
+  threshold: string;
+  method?: string;
+}
+
+export interface IGeminiThinkingConfig {
+  [key: string]: TGeminiProviderOptionValue;
+  includeThoughts?: boolean;
+  thinkingBudget?: number;
+  thinkingLevel?: string;
+}
+
+/**
+ * Gemini API provider options
+ */
+export interface IGeminiProviderOptions {
+  /**
+   * Additional provider-specific options
+   */
+  [key: string]: TGeminiProviderOptionValue;
+
+  /** Google AI API key */
+  apiKey: string;
+
+  /**
+   * Default model used when chat options do not provide a model.
+   */
+  defaultModel?: string;
+
+  /**
+   * Response MIME type
+   * - 'text/plain': Plain text response (default)
+   * - 'application/json': JSON response format
+   */
+  responseMimeType?: 'text/plain' | 'application/json';
+
+  /**
+   * Response schema for JSON output (only used when responseMimeType is 'application/json')
+   */
+  responseSchema?: Record<string, TGeminiProviderOptionValue>;
+
+  /**
+   * JSON Schema response format for current Gemini structured output support.
+   * Mutually exclusive with responseSchema.
+   */
+  responseJsonSchema?: Record<string, TGeminiProviderOptionValue>;
+
+  /**
+   * Default safety settings applied to every direct Gemini request.
+   * Per-request google.safetySettings overrides this value.
+   */
+  safetySettings?: IGeminiSafetySetting[];
+
+  /**
+   * Default thinking configuration for Gemini models that support thinking.
+   */
+  thinkingConfig?: IGeminiThinkingConfig;
+
+  /**
+   * Provider-level function calling config passed through to Gemini config.
+   */
+  toolConfig?: Record<string, TGeminiProviderOptionValue>;
+
+  /**
+   * Optional default response modalities for Gemini generation config.
+   * Example: ['TEXT', 'IMAGE']
+   */
+  defaultResponseModalities?: Array<'TEXT' | 'IMAGE'>;
+
+  /**
+   * Optional allowlist of models that support image generation/editing.
+   * If not provided, provider validates using model name heuristics.
+   */
+  imageCapableModels?: string[];
+
+  /**
+   * Optional executor for handling AI requests
+   *
+   * When provided, the provider will delegate all chat operations to this executor
+   * instead of making direct API calls. This enables remote execution capabilities.
+   *
+   * @example
+   * ```typescript
+   * import { LocalExecutor, RemoteExecutor } from '@robota-sdk/agent-core';
+   *
+   * // Local execution (registers this provider)
+   * const localExecutor = new LocalExecutor();
+   * localExecutor.registerProvider('gemini', new GeminiProvider({ apiKey: 'AIza...' }));
+   *
+   * // Remote execution
+   * const remoteExecutor = new RemoteExecutor({
+   *   serverUrl: 'https://api.robota.io',
+   *   userApiKey: 'user-token-123'
+   * });
+   *
+   * const provider = new GeminiProvider({
+   *   apiKey: 'placeholder', // Required for type safety but not used
+   *   executor: remoteExecutor
+   * });
+   * ```
+   */
+  executor?: IExecutor;
+}

package/src/gemma/index.ts

@@ -0,0 +1,5 @@
+export * from './types';
+export * from './reasoning-projector';
+export * from './tool-call-projector';
+export * from './provider';
+export * from './provider-definition';

package/src/gemma/message-factory.ts

@@ -0,0 +1,38 @@
+import { randomUUID } from 'node:crypto';
+import type OpenAI from 'openai';
+import type { IToolCall, TUniversalMessage } from '@robota-sdk/agent-core';
+
+export function createStreamTextMessage(
+  content: string,
+  finishReason: OpenAI.Chat.ChatCompletionChunk.Choice['finish_reason'],
+): TUniversalMessage {
+  return {
+    id: randomUUID(),
+    role: 'assistant',
+    content,
+    state: 'complete',
+    timestamp: new Date(),
+    metadata: {
+      isStreamChunk: true,
+      isComplete: finishReason === 'stop' || finishReason === 'tool_calls',
+    },
+  };
+}
+
+export function createStreamToolCallMessage(
+  toolCalls: IToolCall[],
+  finishReason: OpenAI.Chat.ChatCompletionChunk.Choice['finish_reason'],
+): TUniversalMessage {
+  return {
+    id: randomUUID(),
+    role: 'assistant',
+    content: '',
+    toolCalls,
+    state: 'complete',
+    timestamp: new Date(),
+    metadata: {
+      isStreamChunk: true,
+      isComplete: finishReason === 'stop' || finishReason === 'tool_calls',
+    },
+  };
+}

package/src/gemma/provider-definition.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it, vi } from 'vitest';
+import { createGemmaProviderDefinition, GemmaProvider } from './index';
+
+vi.mock('openai', () => {
+  const MockOpenAI = vi.fn().mockImplementation(() => ({
+    chat: {
+      completions: {
+        create: vi.fn(),
+      },
+    },
+  }));
+  return { default: MockOpenAI };
+});
+
+describe('createGemmaProviderDefinition', () => {
+  it('exposes local setup help through the provider-definition contract', () => {
+    const definition = createGemmaProviderDefinition();
+
+    expect(definition.type).toBe('gemma');
+    expect(definition.setupHelpLinks).toEqual([
+      {
+        kind: 'official',
+        label: 'LM Studio local API documentation',
+        url: 'https://lmstudio.ai/docs/developer',
+        sourceUrl: 'https://lmstudio.ai/docs/developer',
+        lastVerifiedAt: '2026-05-08',
+      },
+    ]);
+  });
+
+  it('creates a GemmaProvider from a resolved provider profile', () => {
+    const definition = createGemmaProviderDefinition();
+
+    const provider = definition.createProvider({
+      name: 'gemma',
+      model: 'supergemma4-26b-uncensored-v2',
+      apiKey: 'lm-studio',
+      baseURL: 'http://localhost:1234/v1',
+    });
+
+    expect(provider).toBeInstanceOf(GemmaProvider);
+  });
+});

package/src/gemma/provider-definition.ts

@@ -0,0 +1,84 @@
+import type { IProviderDefinition } from '@robota-sdk/agent-core';
+import { probeOpenAICompatibleProfile } from '../shared/openai-compatible/index.js';
+import { GemmaProvider } from './provider';
+
+export const DEFAULT_GEMMA_PROVIDER_MODEL = 'supergemma4-26b-uncensored-v2';
+export const DEFAULT_GEMMA_PROVIDER_API_KEY = 'lm-studio';
+export const DEFAULT_GEMMA_PROVIDER_BASE_URL = 'http://localhost:1234/v1';
+const GEMMA_MODEL_SOURCE_URL = 'https://ai.google.dev/gemma';
+const GEMMA_MODEL_LAST_VERIFIED_AT = '2026-05-04';
+const GEMMA_SETUP_URL = 'https://lmstudio.ai/docs/developer';
+const GEMMA_SETUP_LAST_VERIFIED_AT = '2026-05-08';
+const GEMMA_SETUP_HELP_LINKS: NonNullable<IProviderDefinition['setupHelpLinks']> = [
+  {
+    kind: 'official',
+    label: 'LM Studio local API documentation',
+    url: GEMMA_SETUP_URL,
+    sourceUrl: GEMMA_SETUP_URL,
+    lastVerifiedAt: GEMMA_SETUP_LAST_VERIFIED_AT,
+  },
+];
+const GEMMA_MODEL_CATALOG: NonNullable<IProviderDefinition['modelCatalog']> = {
+  status: 'fallback',
+  sourceUrl: GEMMA_MODEL_SOURCE_URL,
+  lastVerifiedAt: GEMMA_MODEL_LAST_VERIFIED_AT,
+  entries: [
+    {
+      id: DEFAULT_GEMMA_PROVIDER_MODEL,
+      displayName: 'SuperGemma 4 26B',
+      capabilities: ['tools', 'streaming'],
+      lifecycle: 'active',
+      sourceUrl: GEMMA_MODEL_SOURCE_URL,
+      lastVerifiedAt: GEMMA_MODEL_LAST_VERIFIED_AT,
+    },
+  ],
+};
+
+export function createGemmaProviderDefinition(): IProviderDefinition {
+  return {
+    type: 'gemma',
+    displayName: 'Gemma',
+    description: 'Gemma-family local models through an OpenAI-compatible endpoint',
+    defaults: {
+      model: DEFAULT_GEMMA_PROVIDER_MODEL,
+      apiKey: DEFAULT_GEMMA_PROVIDER_API_KEY,
+      baseURL: DEFAULT_GEMMA_PROVIDER_BASE_URL,
+    },
+    modelCatalog: GEMMA_MODEL_CATALOG,
+    setupHelpLinks: GEMMA_SETUP_HELP_LINKS,
+    setupSteps: [
+      {
+        key: 'baseURL',
+        title: 'Gemma OpenAI-compatible base URL',
+        defaultValue: DEFAULT_GEMMA_PROVIDER_BASE_URL,
+      },
+      {
+        key: 'model',
+        title: 'Gemma model',
+        defaultValue: DEFAULT_GEMMA_PROVIDER_MODEL,
+      },
+      {
+        key: 'apiKey',
+        title: 'Gemma OpenAI-compatible API key',
+        defaultValue: DEFAULT_GEMMA_PROVIDER_API_KEY,
+        masked: true,
+      },
+    ],
+    requiresApiKey: true,
+    probeProfile: probeOpenAICompatibleProfile,
+    createProvider: (config) =>
+      new GemmaProvider({
+        apiKey: requireApiKey(config.apiKey),
+        ...(config.baseURL !== undefined && { baseURL: config.baseURL }),
+        ...(config.timeout !== undefined && { timeout: config.timeout }),
+        defaultModel: config.model,
+      }),
+  };
+}
+
+function requireApiKey(apiKey: string | undefined): string {
+  if (!apiKey) {
+    throw new Error('Provider gemma requires apiKey');
+  }
+  return apiKey;
+}

package/src/gemma/provider-projection.ts

@@ -0,0 +1,49 @@
+import type OpenAI from 'openai';
+import type { IChatOptions, ILogger, TUniversalMessage } from '@robota-sdk/agent-core';
+import { OpenAICompatibleResponseParser } from '../shared/openai-compatible/index.js';
+import { projectGemmaReasoningText } from './reasoning-projector';
+import { createGemmaToolCallProjector } from './tool-call-projector';
+
+export function parseGemmaChatCompletion(
+  response: OpenAI.Chat.ChatCompletion,
+  logger: ILogger,
+  options: IChatOptions | undefined,
+): TUniversalMessage {
+  const rawContent = response.choices?.[0]?.message.content || '';
+  const parser = new OpenAICompatibleResponseParser({
+    logger,
+    ...(options?.tools && {
+      toolCallTextProjector: createGemmaToolCallProjector(options.tools),
+    }),
+  });
+  const parsed = parser.parseResponse(response);
+  const projection = projectGemmaReasoningText(parsed.content ?? '');
+
+  return withGemmaProjectionMetadata(
+    {
+      ...parsed,
+      content: projection.visibleText,
+    },
+    rawContent,
+    projection.removedReasoning,
+  );
+}
+
+export function withGemmaProjectionMetadata(
+  message: TUniversalMessage,
+  rawContent: string,
+  removedReasoning: boolean,
+): TUniversalMessage {
+  if (!removedReasoning) {
+    return message;
+  }
+
+  return {
+    ...message,
+    metadata: {
+      ...(message.metadata ?? {}),
+      gemmaReasoningFiltered: true,
+      gemmaRawContent: rawContent,
+    },
+  };
+}