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

package/src/gemini/message-converter.ts

@@ -0,0 +1,140 @@
+import { randomUUID } from 'node:crypto';
+import type { Part, FunctionCall, GenerateContentResponse } from '@google/genai';
+import type {
+  TUniversalMessage,
+  IAssistantMessage,
+  TUniversalMessagePart,
+} from '@robota-sdk/agent-core';
+
+const RANDOM_ID_RADIX = 36;
+const RANDOM_ID_LENGTH = 9;
+
+interface ICollectedGeminiParts {
+  textValues: string[];
+  messageParts: TUniversalMessagePart[];
+  functionCalls: FunctionCall[];
+}
+
+export {
+  convertToGeminiFormat,
+  convertToGeminiFormatWithInlineSystem,
+  convertToGeminiRequestFormat,
+  mapMessagePartsToGeminiParts,
+} from './request-converter';
+export type { IGeminiMessageConversionResult } from './request-converter';
+
+/** Generates a unique call identifier for function call responses. */
+export function generateCallId(): string {
+  return `call_${Date.now()}_${Math.random().toString(RANDOM_ID_RADIX).substr(2, RANDOM_ID_LENGTH)}`;
+}
+
+/** Converts a Gemini API response into a universal message. */
+export function convertFromGeminiResponse(response: GenerateContentResponse): TUniversalMessage {
+  const candidate = response.candidates?.[0];
+  if (!candidate) {
+    throw new Error('No candidate in Gemini response');
+  }
+
+  const content = candidate.content;
+  if (!content || !content.parts || content.parts.length === 0) {
+    throw new Error('No content in Gemini response');
+  }
+
+  const collectedParts = collectGeminiParts(content.parts);
+
+  const result: TUniversalMessage = {
+    id: randomUUID(),
+    state: 'complete' as const,
+    role: 'assistant',
+    content: collectedParts.textValues.length > 0 ? collectedParts.textValues.join('') : null,
+    parts: collectedParts.messageParts,
+    timestamp: new Date(),
+  };
+
+  if (collectedParts.functionCalls.length > 0) {
+    const assistantResult = result as IAssistantMessage;
+    assistantResult.toolCalls = collectedParts.functionCalls.map((fc) => ({
+      id: fc.id ?? generateCallId(),
+      type: 'function' as const,
+      function: {
+        name: requireFunctionCallName(fc),
+        arguments: JSON.stringify(fc.args ?? {}),
+      },
+    }));
+  }
+
+  const usageMetadata = mapUsageMetadata(response);
+  if (usageMetadata) {
+    result.metadata = usageMetadata;
+  }
+
+  return result;
+}
+
+function collectGeminiParts(parts: Part[]): ICollectedGeminiParts {
+  const textValues: string[] = [];
+  const messageParts: TUniversalMessagePart[] = [];
+  const functionCalls: FunctionCall[] = [];
+
+  for (const part of parts) {
+    collectTextPart(part, textValues, messageParts);
+    collectInlineImagePart(part, messageParts);
+    if (part.functionCall) {
+      functionCalls.push(part.functionCall);
+    }
+  }
+
+  return { textValues, messageParts, functionCalls };
+}
+
+function collectTextPart(
+  part: Part,
+  textValues: string[],
+  messageParts: TUniversalMessagePart[],
+): void {
+  if (typeof part.text !== 'string') {
+    return;
+  }
+  textValues.push(part.text);
+  messageParts.push({ type: 'text', text: part.text });
+}
+
+function collectInlineImagePart(part: Part, messageParts: TUniversalMessagePart[]): void {
+  if (
+    !part.inlineData ||
+    typeof part.inlineData.data !== 'string' ||
+    typeof part.inlineData.mimeType !== 'string'
+  ) {
+    return;
+  }
+  messageParts.push({
+    type: 'image_inline',
+    data: part.inlineData.data,
+    mimeType: part.inlineData.mimeType,
+  });
+}
+
+function mapUsageMetadata(response: GenerateContentResponse): TUniversalMessage['metadata'] {
+  if (
+    !response.usageMetadata ||
+    typeof response.usageMetadata.promptTokenCount !== 'number' ||
+    typeof response.usageMetadata.candidatesTokenCount !== 'number' ||
+    typeof response.usageMetadata.totalTokenCount !== 'number'
+  ) {
+    return undefined;
+  }
+  return {
+    promptTokens: response.usageMetadata.promptTokenCount,
+    completionTokens: response.usageMetadata.candidatesTokenCount,
+    totalTokens: response.usageMetadata.totalTokenCount,
+  };
+}
+
+export { convertToolsToGeminiFormat } from './tool-schema-converter';
+
+function requireFunctionCallName(functionCall: FunctionCall): string {
+  if (!functionCall.name || functionCall.name.trim().length === 0) {
+    throw new Error('Gemini function call is missing a function name.');
+  }
+  return functionCall.name;
+}

package/src/gemini/model-catalog-refresh.test.ts

@@ -0,0 +1,107 @@
+import { describe, expect, it, vi } from 'vitest';
+import { refreshGeminiModelCatalog } from './model-catalog-refresh';
+
+describe('refreshGeminiModelCatalog', () => {
+  it('maps the live Gemini /models response into provider model catalog entries, filtering non-generateContent models', async () => {
+    const fetcher = vi.fn(async () => ({
+      ok: true,
+      status: 200,
+      json: async () => ({
+        models: [
+          {
+            name: 'models/gemini-2.0-flash',
+            displayName: 'Gemini 2.0 Flash',
+            description: 'Fast model',
+            inputTokenLimit: 1048576,
+            outputTokenLimit: 8192,
+            supportedGenerationMethods: ['generateContent', 'streamGenerateContent'],
+          },
+          {
+            name: 'models/gemini-2.0-pro',
+            displayName: 'Gemini 2.0 Pro',
+            description: 'Pro model',
+            inputTokenLimit: 1048576,
+            outputTokenLimit: 8192,
+            supportedGenerationMethods: ['generateContent'],
+          },
+          {
+            name: 'models/embedding-001',
+            displayName: 'Embedding 001',
+            description: 'Embedding model only',
+            inputTokenLimit: 2048,
+            outputTokenLimit: 1,
+            supportedGenerationMethods: ['embedContent'],
+          },
+        ],
+      }),
+    }));
+
+    const catalog = await refreshGeminiModelCatalog({ apiKey: 'gemini-key' }, fetcher);
+
+    expect(fetcher).toHaveBeenCalledWith(
+      'https://generativelanguage.googleapis.com/v1beta/models?key=gemini-key',
+    );
+    expect(catalog.status).toBe('live');
+    expect(catalog.entries?.map((entry) => entry.id)).toEqual([
+      'gemini-2.0-flash',
+      'gemini-2.0-pro',
+    ]);
+    expect(catalog.entries?.[0]).toMatchObject({
+      id: 'gemini-2.0-flash',
+      displayName: 'Gemini 2.0 Flash',
+      lifecycle: 'active',
+    });
+  });
+
+  it('sets lifecycle to preview when model name contains "preview"', async () => {
+    const fetcher = vi.fn(async () => ({
+      ok: true,
+      status: 200,
+      json: async () => ({
+        models: [
+          {
+            name: 'models/gemini-3-flash-preview',
+            displayName: 'Gemini 3 Flash Preview',
+            supportedGenerationMethods: ['generateContent', 'streamGenerateContent'],
+          },
+        ],
+      }),
+    }));
+
+    const catalog = await refreshGeminiModelCatalog({}, fetcher);
+
+    expect(catalog.status).toBe('live');
+    expect(catalog.entries?.[0]).toMatchObject({
+      id: 'gemini-3-flash-preview',
+      displayName: 'Gemini 3 Flash Preview',
+      lifecycle: 'preview',
+    });
+  });
+
+  it('returns an unavailable catalog when the live model refresh fails', async () => {
+    const fetcher = vi.fn(async () => ({
+      ok: false,
+      status: 403,
+      json: async () => ({ models: [] }),
+    }));
+
+    const catalog = await refreshGeminiModelCatalog({}, fetcher);
+
+    expect(catalog).toMatchObject({
+      status: 'unavailable',
+      message: 'Gemini model refresh failed: HTTP 403',
+    });
+  });
+
+  it('builds URL without key param when no apiKey is provided', async () => {
+    const fetcher = vi.fn(async () => ({
+      ok: true,
+      status: 200,
+      json: async () => ({ models: [] }),
+    }));
+
+    await refreshGeminiModelCatalog({}, fetcher);
+
+    expect(fetcher).toHaveBeenCalledWith('https://generativelanguage.googleapis.com/v1beta/models');
+  });
+});

package/src/gemini/model-catalog-refresh.ts

@@ -0,0 +1,92 @@
+import type {
+  IProviderModelCatalog,
+  IProviderModelCatalogEntry,
+  IProviderProfileConfig,
+} from '@robota-sdk/agent-core';
+import { GEMINI_MODEL_LAST_VERIFIED_AT, GEMINI_MODEL_SOURCE_URL } from './provider-definition';
+
+const GEMINI_API_ENDPOINT = 'https://generativelanguage.googleapis.com/v1beta/models';
+
+export interface IGeminiModelInfo {
+  name?: string;
+  displayName?: string;
+  description?: string;
+  inputTokenLimit?: number;
+  outputTokenLimit?: number;
+  supportedGenerationMethods?: string[];
+}
+
+export interface IGeminiModelsResponse {
+  models?: IGeminiModelInfo[];
+  nextPageToken?: string;
+}
+
+export interface IGeminiFetchInit {
+  headers?: Record<string, string>;
+}
+
+export interface IGeminiFetchResponse {
+  ok: boolean;
+  status: number;
+  json: () => Promise<IGeminiModelsResponse>;
+}
+
+export type TGeminiFetch = (url: string, init?: IGeminiFetchInit) => Promise<IGeminiFetchResponse>;
+
+export async function refreshGeminiModelCatalog(
+  profile: IProviderProfileConfig,
+  fetcher: TGeminiFetch = defaultGeminiFetch,
+): Promise<IProviderModelCatalog> {
+  const url = profile.apiKey ? `${GEMINI_API_ENDPOINT}?key=${profile.apiKey}` : GEMINI_API_ENDPOINT;
+
+  const response = await fetcher(url);
+
+  if (!response.ok) {
+    return {
+      status: 'unavailable',
+      sourceUrl: GEMINI_MODEL_SOURCE_URL,
+      message: `Gemini model refresh failed: HTTP ${response.status}`,
+    };
+  }
+
+  const body = await response.json();
+  const entries = (body.models ?? []).filter(supportsGenerateContent).map(toModelCatalogEntry);
+
+  return {
+    status: 'live',
+    sourceUrl: GEMINI_MODEL_SOURCE_URL,
+    lastVerifiedAt: new Date().toISOString(),
+    entries,
+    message: `Fetched ${entries.length} Gemini models`,
+  };
+}
+
+function supportsGenerateContent(model: IGeminiModelInfo): boolean {
+  return model.supportedGenerationMethods?.includes('generateContent') === true;
+}
+
+function toModelCatalogEntry(model: IGeminiModelInfo): IProviderModelCatalogEntry {
+  const rawName = model.name ?? '';
+  const id = rawName.startsWith('models/') ? rawName.slice('models/'.length) : rawName;
+  const lifecycle = rawName.includes('preview') ? 'preview' : 'active';
+
+  return {
+    id,
+    displayName: model.displayName ?? id,
+    lifecycle,
+    sourceUrl: GEMINI_MODEL_SOURCE_URL,
+    lastVerifiedAt: GEMINI_MODEL_LAST_VERIFIED_AT,
+  };
+}
+
+async function defaultGeminiFetch(
+  url: string,
+  _init?: IGeminiFetchInit,
+): Promise<IGeminiFetchResponse> {
+  const response = await fetch(url);
+  return {
+    ok: response.ok,
+    status: response.status,
+    json: () => response.json() as Promise<IGeminiModelsResponse>,
+  };
+}

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

@@ -0,0 +1,70 @@
+import { describe, expect, it, vi } from 'vitest';
+import { GeminiProvider } from './provider';
+import {
+  DEFAULT_GEMINI_PROVIDER_API_KEY_REFERENCE,
+  DEFAULT_GEMINI_PROVIDER_MODEL,
+  createGeminiProviderDefinition,
+} from './provider-definition';
+
+vi.mock('@google/genai', () => {
+  class GoogleGenAI {
+    public constructor(_options: { apiKey: string }) {}
+  }
+  return {
+    GoogleGenAI,
+    Type: {
+      STRING: 'STRING',
+      NUMBER: 'NUMBER',
+      INTEGER: 'INTEGER',
+      BOOLEAN: 'BOOLEAN',
+      ARRAY: 'ARRAY',
+      OBJECT: 'OBJECT',
+    },
+  };
+});
+
+describe('createGeminiProviderDefinition', () => {
+  it('exposes Gemini as the canonical provider type with Google compatibility alias', () => {
+    const definition = createGeminiProviderDefinition();
+
+    expect(definition.type).toBe('gemini');
+    expect(definition.aliases).toEqual(['google']);
+    expect(definition.displayName).toBe('Gemini');
+    expect(definition.defaults).toEqual({
+      model: DEFAULT_GEMINI_PROVIDER_MODEL,
+      apiKey: DEFAULT_GEMINI_PROVIDER_API_KEY_REFERENCE,
+    });
+    expect(definition.setupHelpLinks).toEqual([
+      {
+        kind: 'api-key',
+        label: 'Google AI Studio API keys',
+        url: 'https://aistudio.google.com/apikey',
+        sourceUrl: 'https://ai.google.dev/gemini-api/docs/api-key',
+        lastVerifiedAt: '2026-05-08',
+      },
+    ]);
+  });
+
+  it('creates the Gemini API provider implementation from generic provider config', () => {
+    const definition = createGeminiProviderDefinition();
+
+    const provider = definition.createProvider({
+      name: 'gemini',
+      model: 'gemini-3-flash-preview',
+      apiKey: 'gemini-key',
+    });
+
+    expect(provider).toBeInstanceOf(GeminiProvider);
+  });
+
+  it('fails clearly when apiKey is missing', () => {
+    const definition = createGeminiProviderDefinition();
+
+    expect(() =>
+      definition.createProvider({
+        name: 'gemini',
+        model: 'gemini-3-flash-preview',
+      }),
+    ).toThrow('Provider gemini requires apiKey');
+  });
+});

package/src/gemini/provider-definition.ts

@@ -0,0 +1,78 @@
+import type { IProviderDefinition } from '@robota-sdk/agent-core';
+import { refreshGeminiModelCatalog } from './model-catalog-refresh';
+import { GeminiProvider } from './provider';
+
+export const DEFAULT_GEMINI_PROVIDER_API_KEY_ENV = 'GEMINI_API_KEY';
+export const DEFAULT_GEMINI_PROVIDER_API_KEY_REFERENCE = `$ENV:${DEFAULT_GEMINI_PROVIDER_API_KEY_ENV}`;
+export const DEFAULT_GEMINI_PROVIDER_MODEL = 'gemini-3-flash-preview';
+export const GEMINI_MODEL_SOURCE_URL = 'https://ai.google.dev/api/models';
+export const GEMINI_MODEL_LAST_VERIFIED_AT = '2026-05-04';
+const GEMINI_API_KEY_URL = 'https://aistudio.google.com/apikey';
+const GEMINI_SETUP_SOURCE_URL = 'https://ai.google.dev/gemini-api/docs/api-key';
+const GEMINI_SETUP_LAST_VERIFIED_AT = '2026-05-08';
+const GEMINI_SETUP_HELP_LINKS: NonNullable<IProviderDefinition['setupHelpLinks']> = [
+  {
+    kind: 'api-key',
+    label: 'Google AI Studio API keys',
+    url: GEMINI_API_KEY_URL,
+    sourceUrl: GEMINI_SETUP_SOURCE_URL,
+    lastVerifiedAt: GEMINI_SETUP_LAST_VERIFIED_AT,
+  },
+];
+
+export function createGeminiProviderDefinition(): IProviderDefinition {
+  return {
+    type: 'gemini',
+    aliases: ['google'],
+    displayName: 'Gemini',
+    description: 'Google Gemini API provider',
+    defaults: {
+      model: DEFAULT_GEMINI_PROVIDER_MODEL,
+      apiKey: DEFAULT_GEMINI_PROVIDER_API_KEY_REFERENCE,
+    },
+    modelCatalog: {
+      status: 'fallback',
+      sourceUrl: GEMINI_MODEL_SOURCE_URL,
+      lastVerifiedAt: GEMINI_MODEL_LAST_VERIFIED_AT,
+      entries: [
+        {
+          id: DEFAULT_GEMINI_PROVIDER_MODEL,
+          displayName: 'Gemini 3 Flash Preview',
+          capabilities: ['tools', 'vision', 'json_schema', 'reasoning', 'streaming'],
+          lifecycle: 'preview',
+          sourceUrl: GEMINI_MODEL_SOURCE_URL,
+          lastVerifiedAt: GEMINI_MODEL_LAST_VERIFIED_AT,
+        },
+      ],
+    },
+    setupHelpLinks: GEMINI_SETUP_HELP_LINKS,
+    setupSteps: [
+      {
+        key: 'model',
+        title: 'Gemini model',
+        defaultValue: DEFAULT_GEMINI_PROVIDER_MODEL,
+      },
+      {
+        key: 'apiKey',
+        title: 'Gemini API key',
+        defaultValue: DEFAULT_GEMINI_PROVIDER_API_KEY_REFERENCE,
+        masked: true,
+      },
+    ],
+    requiresApiKey: true,
+    refreshModelCatalog: ({ profile }) => refreshGeminiModelCatalog(profile),
+    modelCatalogCacheTtlSeconds: 86400,
+    createProvider: (config) =>
+      new GeminiProvider({
+        apiKey: requireApiKey(config.apiKey),
+        defaultModel: config.model,
+      }),
+  };
+}
+
+function requireApiKey(apiKey: string | undefined): string {
+  if (!apiKey) {
+    throw new Error('Provider gemini requires apiKey');
+  }
+  return apiKey;
+}