@robota-sdk/google/dist/index.d.cts

Google AI integration for Robota SDK - Gemini Pro, Gemini Flash, function calling, and tool integration with Google's Generative AI

import { BaseAIProvider, Context, ModelResponse, StreamingResponseChunk, UniversalMessage } from '@robota-sdk/core';
import { FunctionSchema } from '@robota-sdk/tools';
import { GoogleGenerativeAI, Content } from '@google/generative-ai';

/**
 * Google AI Provider options
 */
interface GoogleProviderOptions {
    /** Google AI client instance */
    client: GoogleGenerativeAI;
    /** Default model to use */
    model?: string;
    /** Temperature setting (0.0 ~ 1.0) */
    temperature?: number;
    /** Maximum number of tokens */
    maxTokens?: number;
    /**
     * 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, unknown>;
}

/**
 * Google AI provider implementation for Robota
 *
 * Provides integration with Google's Generative AI services including Gemini models.
 * Extends BaseAIProvider for common functionality and tool calling support.
 *
 * @see {@link ../../../apps/examples/03-integrations | Provider Integration Examples}
 *
 * @public
 */
declare class GoogleProvider extends BaseAIProvider {
    /**
     * Provider identifier name
     * @readonly
     */
    readonly name: string;
    /**
     * Google AI client instance
     * @internal
     */
    private readonly client;
    /**
     * Provider configuration options
     * @readonly
     */
    readonly options: GoogleProviderOptions;
    /**
     * Create a new Google AI provider instance
     *
     * @param options - Configuration options for the Google provider
     *
     * @throws {Error} When client is not provided in options
     */
    constructor(options: GoogleProviderOptions);
    /**
     * Send a chat request to Google AI and receive a complete response
     *
     * @param model - Model name to use (e.g., 'gemini-1.5-pro', 'gemini-1.5-flash')
     * @param context - Context object containing messages and system prompt
     * @param options - Optional generation parameters and tools
     * @returns Promise resolving to the model's response
     *
     * @throws {Error} When context is invalid
     * @throws {Error} When messages array is invalid
     * @throws {Error} When Google AI API call fails
     */
    chat(model: string, context: Context, options?: any): Promise<ModelResponse>;
    /**
     * Send a streaming chat request to Google AI and receive response chunks
     *
     * Generates an async iterator that yields response chunks as they arrive.
     * Useful for real-time display of responses or handling large responses incrementally.
     *
     * @param model - Model name to use
     * @param context - Context object containing messages and system prompt
     * @param options - Optional generation parameters and tools
     * @returns Async generator yielding response chunks
     *
     * @throws {Error} When context is invalid
     * @throws {Error} When messages array is invalid
     * @throws {Error} When Google AI API streaming call fails
     */
    chatStream(model: string, context: Context, options?: any): AsyncGenerator<StreamingResponseChunk, void, unknown>;
    /**
     * Configure tools for Google AI API request
     *
     * Google AI supports function calling with Gemini models.
     * Transforms function schemas into Google AI tool format.
     *
     * @param tools - Array of function schemas
     * @returns Google AI tool configuration object or undefined
     */
    protected configureTools(tools?: FunctionSchema[]): {
        tools: any[];
    } | undefined;
    /**
     * Parse Google AI response into universal ModelResponse format
     *
     * Extracts content, usage information, and metadata from the Google AI response
     * and converts it to the standard format used across all providers.
     * Supports function calling with Gemini models.
     *
     * @param response - Raw response from Google AI API
     * @returns Parsed model response in universal format
     *
     * @internal
     */
    parseResponse(response: any): ModelResponse;
    /**
     * Parse Google AI streaming response chunk into universal format
     *
     * Converts individual chunks from the streaming response into the standard
     * StreamingResponseChunk format used across all providers.
     *
     * @param chunk - Raw chunk from Google AI streaming API
     * @returns Parsed streaming response chunk
     *
     * @internal
     */
    parseStreamingChunk(chunk: any): StreamingResponseChunk;
    /**
     * Release resources and close connections
     *
     * Performs cleanup operations when the provider is no longer needed.
     * Google AI client doesn't require explicit cleanup, so this is a no-op.
     *
     * @returns Promise that resolves when cleanup is complete
     */
    close(): Promise<void>;
}

/**
 * Google AI ConversationHistory adapter
 *
 * Converts UniversalMessage to Google Generative AI format
 */
declare class GoogleConversationAdapter {
    /**
     * Convert UniversalMessage array to Google AI message format
     */
    static toGoogleFormat(messages: UniversalMessage[]): Content[];
    /**
     * Convert a single UniversalMessage to Google AI format
     */
    static convertMessage(msg: UniversalMessage): Content;
    /**
     * Extract system messages and combine them as system instruction
     */
    static extractSystemInstruction(messages: UniversalMessage[], fallbackSystemPrompt?: string): string | undefined;
    /**
     * Complete message conversion pipeline
     */
    static processMessages(messages: UniversalMessage[], systemPrompt?: string): {
        contents: Content[];
        systemInstruction?: string;
    };
}

export { GoogleConversationAdapter, GoogleProvider, type GoogleProviderOptions };