@strands-agents/sdk 0.1.6 → 0.2.1

package/dist/src/models/gemini/adapters.js

@@ -0,0 +1,119 @@
+/**
+ * Adapters for converting between Strands SDK types and Gemini API format.
+ *
+ * @internal This module is not part of the public API.
+ */
+import { FinishReason as GeminiFinishReason, } from '@google/genai';
+/**
+ * Mapping of Gemini finish reasons to SDK stop reasons.
+ * Only MAX_TOKENS needs explicit mapping; everything else defaults to endTurn.
+ * TOOL_USE is handled separately via hasToolCalls flag.
+ *
+ * @internal
+ */
+export const FINISH_REASON_MAP = {
+    [GeminiFinishReason.MAX_TOKENS]: 'maxTokens',
+};
+// =============================================================================
+// Strands → Gemini
+// =============================================================================
+/**
+ * Formats an array of messages for the Gemini API.
+ *
+ * @param messages - SDK messages to format
+ * @returns Gemini-formatted contents array
+ *
+ * @internal
+ */
+export function formatMessages(messages) {
+    const contents = [];
+    for (const message of messages) {
+        const parts = [];
+        for (const block of message.content) {
+            if (block.type === 'textBlock') {
+                parts.push({ text: block.text });
+            }
+        }
+        if (parts.length > 0) {
+            contents.push({
+                role: message.role === 'assistant' ? 'model' : 'user',
+                parts,
+            });
+        }
+    }
+    return contents;
+}
+// =============================================================================
+// Gemini → Strands
+// =============================================================================
+/**
+ * Maps a Gemini response chunk to SDK streaming events.
+ *
+ * @param chunk - Gemini response chunk
+ * @param streamState - Mutable state object tracking message and content block state
+ * @returns Array of SDK streaming events
+ *
+ * @internal
+ */
+export function mapChunkToEvents(chunk, streamState) {
+    const events = [];
+    // Extract usage metadata if available
+    if (chunk.usageMetadata) {
+        const promptTokens = chunk.usageMetadata.promptTokenCount || 0;
+        const totalTokens = chunk.usageMetadata.totalTokenCount || 0;
+        streamState.inputTokens = promptTokens;
+        streamState.outputTokens = totalTokens - promptTokens;
+    }
+    const candidates = chunk.candidates;
+    if (!candidates || candidates.length === 0) {
+        return events;
+    }
+    const candidate = candidates[0];
+    if (!candidate) {
+        return events;
+    }
+    // Handle message start
+    if (!streamState.messageStarted) {
+        streamState.messageStarted = true;
+        events.push({
+            type: 'modelMessageStartEvent',
+            role: 'assistant',
+        });
+    }
+    // Process content parts
+    const content = candidate.content;
+    if (content && content.parts) {
+        for (const part of content.parts) {
+            // Handle text content
+            if ('text' in part && part.text) {
+                if (!streamState.textContentBlockStarted) {
+                    streamState.textContentBlockStarted = true;
+                    events.push({ type: 'modelContentBlockStartEvent' });
+                }
+                events.push({
+                    type: 'modelContentBlockDeltaEvent',
+                    delta: {
+                        type: 'textDelta',
+                        text: part.text,
+                    },
+                });
+            }
+        }
+    }
+    // Handle finish reason
+    const finishReason = candidate.finishReason;
+    if (finishReason && finishReason !== GeminiFinishReason.FINISH_REASON_UNSPECIFIED) {
+        // Close text content block if still open
+        if (streamState.textContentBlockStarted) {
+            events.push({ type: 'modelContentBlockStopEvent' });
+            streamState.textContentBlockStarted = false;
+        }
+        const stopReason = FINISH_REASON_MAP[finishReason] || 'endTurn';
+        events.push({
+            type: 'modelMessageStopEvent',
+            stopReason,
+        });
+    }
+    return events;
+}
+//# sourceMappingURL=adapters.js.map

package/dist/src/models/gemini/adapters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapters.js","sourceRoot":"","sources":["../../../../src/models/gemini/adapters.ts"],"names":[],"mappings":"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"}

package/dist/src/models/gemini/errors.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Error handling utilities for the Gemini model provider.
+ *
+ * @internal This module is not part of the public API.
+ */
+/**
+ * Recognized error types from Gemini API responses.
+ *
+ * This union type will expand as more error types are supported
+ * (e.g., 'throttling', 'invalidRequest').
+ */
+export type GeminiErrorType = 'contextOverflow';
+/**
+ * Configuration for handling a specific error status.
+ * If messagePatterns is provided, the error message must match one of the patterns.
+ * If messagePatterns is not provided, the status alone triggers the error type.
+ */
+export interface ErrorStatusConfig {
+    type: GeminiErrorType;
+    messagePatterns?: Set<string>;
+}
+/**
+ * Mapping of Gemini API error statuses to error handling configuration.
+ * Maps status codes to either direct error types or message-pattern-based detection.
+ */
+export declare const ERROR_STATUS_MAP: Record<string, ErrorStatusConfig>;
+/**
+ * Classifies a Gemini API error based on status and message patterns.
+ * Returns the error type if recognized, undefined otherwise.
+ *
+ * @param error - The error to classify
+ * @returns The error type if recognized, undefined otherwise
+ *
+ * @internal
+ */
+export declare function classifyGeminiError(error: Error): GeminiErrorType | undefined;
+//# sourceMappingURL=errors.d.ts.map

package/dist/src/models/gemini/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../../src/models/gemini/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,iBAAiB,CAAA;AAE/C;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,eAAe,CAAA;IACrB,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;CAC9B;AAED;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAK9D,CAAA;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,KAAK,GAAG,eAAe,GAAG,SAAS,CAoC7E"}

package/dist/src/models/gemini/errors.js

@@ -0,0 +1,58 @@
+/**
+ * Error handling utilities for the Gemini model provider.
+ *
+ * @internal This module is not part of the public API.
+ */
+import { logger } from '../../logging/logger.js';
+/**
+ * Mapping of Gemini API error statuses to error handling configuration.
+ * Maps status codes to either direct error types or message-pattern-based detection.
+ */
+export const ERROR_STATUS_MAP = {
+    INVALID_ARGUMENT: {
+        type: 'contextOverflow',
+        messagePatterns: new Set(['exceeds the maximum number of tokens']),
+    },
+};
+/**
+ * Classifies a Gemini API error based on status and message patterns.
+ * Returns the error type if recognized, undefined otherwise.
+ *
+ * @param error - The error to classify
+ * @returns The error type if recognized, undefined otherwise
+ *
+ * @internal
+ */
+export function classifyGeminiError(error) {
+    if (!error.message) {
+        return undefined;
+    }
+    let status;
+    let message;
+    try {
+        const parsed = JSON.parse(error.message);
+        status = parsed?.error?.status || '';
+        message = parsed?.error?.message || '';
+    }
+    catch {
+        logger.debug(`error_message=<${error.message}> | gemini api returned non-json error`);
+        return undefined;
+    }
+    const config = ERROR_STATUS_MAP[status.toUpperCase()];
+    if (!config) {
+        return undefined;
+    }
+    // If no message patterns required, status alone determines the error type
+    if (!config.messagePatterns) {
+        return config.type;
+    }
+    // Check if message matches any of the patterns
+    const lowerMessage = message.toLowerCase();
+    for (const pattern of config.messagePatterns) {
+        if (lowerMessage.includes(pattern)) {
+            return config.type;
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=errors.js.map

package/dist/src/models/gemini/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../../src/models/gemini/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAA;AAoBhD;;;GAGG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAsC;IACjE,gBAAgB,EAAE;QAChB,IAAI,EAAE,iBAAiB;QACvB,eAAe,EAAE,IAAI,GAAG,CAAC,CAAC,sCAAsC,CAAC,CAAC;KACnE;CACF,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAY;IAC9C,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;QACnB,OAAO,SAAS,CAAA;IAClB,CAAC;IAED,IAAI,MAAc,CAAA;IAClB,IAAI,OAAe,CAAA;IAEnB,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;QACxC,MAAM,GAAG,MAAM,EAAE,KAAK,EAAE,MAAM,IAAI,EAAE,CAAA;QACpC,OAAO,GAAG,MAAM,EAAE,KAAK,EAAE,OAAO,IAAI,EAAE,CAAA;IACxC,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,CAAC,KAAK,CAAC,kBAAkB,KAAK,CAAC,OAAO,wCAAwC,CAAC,CAAA;QACrF,OAAO,SAAS,CAAA;IAClB,CAAC;IAED,MAAM,MAAM,GAAG,gBAAgB,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC,CAAA;IACrD,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,SAAS,CAAA;IAClB,CAAC;IAED,0EAA0E;IAC1E,IAAI,CAAC,MAAM,CAAC,eAAe,EAAE,CAAC;QAC5B,OAAO,MAAM,CAAC,IAAI,CAAA;IACpB,CAAC;IAED,+CAA+C;IAC/C,MAAM,YAAY,GAAG,OAAO,CAAC,WAAW,EAAE,CAAA;IAC1C,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,eAAe,EAAE,CAAC;QAC7C,IAAI,YAAY,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YACnC,OAAO,MAAM,CAAC,IAAI,CAAA;QACpB,CAAC;IACH,CAAC;IAED,OAAO,SAAS,CAAA;AAClB,CAAC"}

package/dist/src/models/gemini/model.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Google Gemini model provider implementation.
+ *
+ * This module provides integration with Google's Gemini API,
+ * supporting streaming responses and configurable model parameters.
+ *
+ * @see https://ai.google.dev/docs
+ */
+import { Model } from '../model.js';
+import type { StreamOptions } from '../model.js';
+import type { Message } from '../../types/messages.js';
+import type { ModelStreamEvent } from '../streaming.js';
+import type { GeminiModelConfig, GeminiModelOptions } from './types.js';
+export type { GeminiModelConfig, GeminiModelOptions };
+/**
+ * Google Gemini model provider implementation.
+ *
+ * Implements the Model interface for Google Gemini using the Generative AI API.
+ * Supports streaming responses and comprehensive configuration.
+ *
+ * @example
+ * ```typescript
+ * const provider = new GeminiModel({
+ *   apiKey: 'your-api-key',
+ *   modelId: 'gemini-2.5-flash',
+ *   params: { temperature: 0.7, maxOutputTokens: 1024 }
+ * })
+ *
+ * const messages: Message[] = [
+ *   { role: 'user', content: [{ type: 'textBlock', text: 'Hello!' }] }
+ * ]
+ *
+ * for await (const event of provider.stream(messages)) {
+ *   if (event.type === 'modelContentBlockDeltaEvent' && event.delta.type === 'textDelta') {
+ *     process.stdout.write(event.delta.text)
+ *   }
+ * }
+ * ```
+ */
+export declare class GeminiModel extends Model<GeminiModelConfig> {
+    private _config;
+    private _client;
+    /**
+     * Creates a new GeminiModel instance.
+     *
+     * @param options - Configuration for model and client
+     *
+     * @example
+     * ```typescript
+     * // Minimal configuration with API key
+     * const provider = new GeminiModel({
+     *   apiKey: 'your-api-key'
+     * })
+     *
+     * // With model configuration
+     * const provider = new GeminiModel({
+     *   apiKey: 'your-api-key',
+     *   modelId: 'gemini-2.5-flash',
+     *   params: { temperature: 0.8, maxOutputTokens: 2048 }
+     * })
+     *
+     * // Using environment variable for API key
+     * const provider = new GeminiModel({
+     *   modelId: 'gemini-2.5-flash'
+     * })
+     *
+     * // Using a pre-configured client instance
+     * const client = new GoogleGenAI({ apiKey: 'your-api-key' })
+     * const provider = new GeminiModel({
+     *   client
+     * })
+     * ```
+     */
+    constructor(options?: GeminiModelOptions);
+    /**
+     * Updates the model configuration.
+     * Merges the provided configuration with existing settings.
+     *
+     * @param modelConfig - Configuration object with model-specific settings to update
+     *
+     * @example
+     * ```typescript
+     * // Update model parameters
+     * provider.updateConfig({
+     *   params: { temperature: 0.9, maxOutputTokens: 2048 }
+     * })
+     * ```
+     */
+    updateConfig(modelConfig: GeminiModelConfig): void;
+    /**
+     * Retrieves the current model configuration.
+     *
+     * @returns The current configuration object
+     *
+     * @example
+     * ```typescript
+     * const config = provider.getConfig()
+     * console.log(config.modelId)
+     * ```
+     */
+    getConfig(): GeminiModelConfig;
+    /**
+     * Streams a conversation with the Gemini model.
+     * Returns an async iterable that yields streaming events as they occur.
+     *
+     * @param messages - Array of conversation messages
+     * @param options - Optional streaming configuration
+     * @returns Async iterable of streaming events
+     *
+     * @throws \{ContextWindowOverflowError\} When input exceeds the model's context window
+     *
+     * @example
+     * ```typescript
+     * const provider = new GeminiModel({ apiKey: 'your-api-key' })
+     * const messages: Message[] = [
+     *   { role: 'user', content: [{ type: 'textBlock', text: 'What is 2+2?' }] }
+     * ]
+     *
+     * for await (const event of provider.stream(messages)) {
+     *   if (event.type === 'modelContentBlockDeltaEvent' && event.delta.type === 'textDelta') {
+     *     process.stdout.write(event.delta.text)
+     *   }
+     * }
+     * ```
+     */
+    stream(messages: Message[], options?: StreamOptions): AsyncIterable<ModelStreamEvent>;
+    /**
+     * Gets API key from environment variables.
+     */
+    private static _getEnvApiKey;
+    /**
+     * Formats a request for the Gemini API.
+     */
+    private _formatRequest;
+}
+//# sourceMappingURL=model.d.ts.map

package/dist/src/models/gemini/model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../../../../src/models/gemini/model.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAA;AACnC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAChD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAA;AACtD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AAEvD,OAAO,KAAK,EAAE,iBAAiB,EAAE,kBAAkB,EAAqB,MAAM,YAAY,CAAA;AAC1F,YAAY,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,CAAA;AASrD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,WAAY,SAAQ,KAAK,CAAC,iBAAiB,CAAC;IACvD,OAAO,CAAC,OAAO,CAAmB;IAClC,OAAO,CAAC,OAAO,CAAa;IAE5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;gBACS,OAAO,CAAC,EAAE,kBAAkB;IAwBxC;;;;;;;;;;;;;OAaG;IACH,YAAY,CAAC,WAAW,EAAE,iBAAiB,GAAG,IAAI;IAIlD;;;;;;;;;;OAUG;IACH,SAAS,IAAI,iBAAiB;IAI9B;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACI,MAAM,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,aAAa,CAAC,gBAAgB,CAAC;IA4C5F;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,aAAa;IAI5B;;OAEG;IACH,OAAO,CAAC,cAAc;CAoCvB"}

package/dist/src/models/gemini/model.js

@@ -0,0 +1,230 @@
+/**
+ * Google Gemini model provider implementation.
+ *
+ * This module provides integration with Google's Gemini API,
+ * supporting streaming responses and configurable model parameters.
+ *
+ * @see https://ai.google.dev/docs
+ */
+import { GoogleGenAI } from '@google/genai';
+import { Model } from '../model.js';
+import { ContextWindowOverflowError } from '../../errors.js';
+import { classifyGeminiError } from './errors.js';
+import { formatMessages, mapChunkToEvents } from './adapters.js';
+/**
+ * Default Gemini model ID.
+ */
+const DEFAULT_GEMINI_MODEL_ID = 'gemini-2.5-flash';
+/**
+ * Google Gemini model provider implementation.
+ *
+ * Implements the Model interface for Google Gemini using the Generative AI API.
+ * Supports streaming responses and comprehensive configuration.
+ *
+ * @example
+ * ```typescript
+ * const provider = new GeminiModel({
+ *   apiKey: 'your-api-key',
+ *   modelId: 'gemini-2.5-flash',
+ *   params: { temperature: 0.7, maxOutputTokens: 1024 }
+ * })
+ *
+ * const messages: Message[] = [
+ *   { role: 'user', content: [{ type: 'textBlock', text: 'Hello!' }] }
+ * ]
+ *
+ * for await (const event of provider.stream(messages)) {
+ *   if (event.type === 'modelContentBlockDeltaEvent' && event.delta.type === 'textDelta') {
+ *     process.stdout.write(event.delta.text)
+ *   }
+ * }
+ * ```
+ */
+export class GeminiModel extends Model {
+    _config;
+    _client;
+    /**
+     * Creates a new GeminiModel instance.
+     *
+     * @param options - Configuration for model and client
+     *
+     * @example
+     * ```typescript
+     * // Minimal configuration with API key
+     * const provider = new GeminiModel({
+     *   apiKey: 'your-api-key'
+     * })
+     *
+     * // With model configuration
+     * const provider = new GeminiModel({
+     *   apiKey: 'your-api-key',
+     *   modelId: 'gemini-2.5-flash',
+     *   params: { temperature: 0.8, maxOutputTokens: 2048 }
+     * })
+     *
+     * // Using environment variable for API key
+     * const provider = new GeminiModel({
+     *   modelId: 'gemini-2.5-flash'
+     * })
+     *
+     * // Using a pre-configured client instance
+     * const client = new GoogleGenAI({ apiKey: 'your-api-key' })
+     * const provider = new GeminiModel({
+     *   client
+     * })
+     * ```
+     */
+    constructor(options) {
+        super();
+        const { apiKey, client, clientConfig, ...modelConfig } = options || {};
+        this._config = modelConfig;
+        if (client) {
+            this._client = client;
+        }
+        else {
+            const resolvedApiKey = apiKey || GeminiModel._getEnvApiKey();
+            if (!resolvedApiKey) {
+                throw new Error("Gemini API key is required. Provide it via the 'apiKey' option or set the GEMINI_API_KEY environment variable.");
+            }
+            this._client = new GoogleGenAI({
+                apiKey: resolvedApiKey,
+                ...clientConfig,
+            });
+        }
+    }
+    /**
+     * Updates the model configuration.
+     * Merges the provided configuration with existing settings.
+     *
+     * @param modelConfig - Configuration object with model-specific settings to update
+     *
+     * @example
+     * ```typescript
+     * // Update model parameters
+     * provider.updateConfig({
+     *   params: { temperature: 0.9, maxOutputTokens: 2048 }
+     * })
+     * ```
+     */
+    updateConfig(modelConfig) {
+        this._config = { ...this._config, ...modelConfig };
+    }
+    /**
+     * Retrieves the current model configuration.
+     *
+     * @returns The current configuration object
+     *
+     * @example
+     * ```typescript
+     * const config = provider.getConfig()
+     * console.log(config.modelId)
+     * ```
+     */
+    getConfig() {
+        return this._config;
+    }
+    /**
+     * Streams a conversation with the Gemini model.
+     * Returns an async iterable that yields streaming events as they occur.
+     *
+     * @param messages - Array of conversation messages
+     * @param options - Optional streaming configuration
+     * @returns Async iterable of streaming events
+     *
+     * @throws \{ContextWindowOverflowError\} When input exceeds the model's context window
+     *
+     * @example
+     * ```typescript
+     * const provider = new GeminiModel({ apiKey: 'your-api-key' })
+     * const messages: Message[] = [
+     *   { role: 'user', content: [{ type: 'textBlock', text: 'What is 2+2?' }] }
+     * ]
+     *
+     * for await (const event of provider.stream(messages)) {
+     *   if (event.type === 'modelContentBlockDeltaEvent' && event.delta.type === 'textDelta') {
+     *     process.stdout.write(event.delta.text)
+     *   }
+     * }
+     * ```
+     */
+    async *stream(messages, options) {
+        if (!messages || messages.length === 0) {
+            throw new Error('At least one message is required');
+        }
+        try {
+            const params = this._formatRequest(messages, options);
+            const stream = await this._client.models.generateContentStream(params);
+            const streamState = {
+                messageStarted: false,
+                textContentBlockStarted: false,
+                inputTokens: 0,
+                outputTokens: 0,
+            };
+            for await (const chunk of stream) {
+                yield* mapChunkToEvents(chunk, streamState);
+            }
+            if (streamState.inputTokens > 0 || streamState.outputTokens > 0) {
+                yield {
+                    type: 'modelMetadataEvent',
+                    usage: {
+                        inputTokens: streamState.inputTokens,
+                        outputTokens: streamState.outputTokens,
+                        totalTokens: streamState.inputTokens + streamState.outputTokens,
+                    },
+                };
+            }
+        }
+        catch (error) {
+            if (!(error instanceof Error)) {
+                throw error;
+            }
+            const errorType = classifyGeminiError(error);
+            if (errorType === 'contextOverflow') {
+                throw new ContextWindowOverflowError(error.message);
+            }
+            throw error;
+        }
+    }
+    /**
+     * Gets API key from environment variables.
+     */
+    static _getEnvApiKey() {
+        return globalThis?.process?.env?.GEMINI_API_KEY;
+    }
+    /**
+     * Formats a request for the Gemini API.
+     */
+    _formatRequest(messages, options) {
+        const contents = formatMessages(messages);
+        const config = {};
+        // Add system instruction
+        if (options?.systemPrompt !== undefined) {
+            if (typeof options.systemPrompt === 'string') {
+                if (options.systemPrompt.trim().length > 0) {
+                    config.systemInstruction = options.systemPrompt;
+                }
+            }
+            else if (Array.isArray(options.systemPrompt) && options.systemPrompt.length > 0) {
+                const textBlocks = [];
+                for (const block of options.systemPrompt) {
+                    if (block.type === 'textBlock') {
+                        textBlocks.push(block.text);
+                    }
+                }
+                if (textBlocks.length > 0) {
+                    config.systemInstruction = textBlocks.join('');
+                }
+            }
+        }
+        // Spread params object for forward compatibility
+        if (this._config.params) {
+            Object.assign(config, this._config.params);
+        }
+        return {
+            model: this._config.modelId ?? DEFAULT_GEMINI_MODEL_ID,
+            contents,
+            config,
+        };
+    }
+}
+//# sourceMappingURL=model.js.map

package/dist/src/models/gemini/model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.js","sourceRoot":"","sources":["../../../../src/models/gemini/model.ts"],"names":[],"mappings":"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"}

package/dist/src/models/gemini/types.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Type definitions for the Gemini model provider.
+ */
+import type { GoogleGenAI, GoogleGenAIOptions } from '@google/genai';
+import type { BaseModelConfig } from '../model.js';
+/**
+ * Configuration interface for Gemini model provider.
+ *
+ * @example
+ * ```typescript
+ * const config: GeminiModelConfig = {
+ *   modelId: 'gemini-2.5-flash',
+ *   params: { temperature: 0.7, maxOutputTokens: 1024 }
+ * }
+ * ```
+ *
+ * @see https://ai.google.dev/api/generate-content#generationconfig
+ */
+export interface GeminiModelConfig extends BaseModelConfig {
+    /**
+     * Gemini model identifier (e.g., gemini-2.5-flash, gemini-2.5-pro).
+     *
+     * @defaultValue 'gemini-2.5-flash'
+     * @see https://ai.google.dev/gemini-api/docs/models
+     */
+    modelId?: string;
+    /**
+     * Additional parameters to pass to the Gemini API (e.g., temperature, maxOutputTokens).
+     *
+     * @see https://ai.google.dev/api/generate-content#generationconfig
+     */
+    params?: Record<string, unknown>;
+}
+/**
+ * Options interface for creating a GeminiModel instance.
+ */
+export interface GeminiModelOptions extends GeminiModelConfig {
+    /**
+     * Gemini API key (falls back to GEMINI_API_KEY environment variable).
+     */
+    apiKey?: string;
+    /**
+     * Pre-configured Google GenAI client instance.
+     * If provided, this client will be used instead of creating a new one.
+     */
+    client?: GoogleGenAI;
+    /**
+     * Additional Google GenAI client configuration.
+     * Only used if client is not provided.
+     */
+    clientConfig?: Omit<GoogleGenAIOptions, 'apiKey'>;
+}
+/**
+ * Internal state for tracking streaming progress.
+ */
+export interface GeminiStreamState {
+    messageStarted: boolean;
+    textContentBlockStarted: boolean;
+    inputTokens: number;
+    outputTokens: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/src/models/gemini/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/models/gemini/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA;AACpE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAElD;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,iBAAkB,SAAQ,eAAe;IACxD;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAEhB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,kBAAmB,SAAQ,iBAAiB;IAC3D;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf;;;OAGG;IACH,MAAM,CAAC,EAAE,WAAW,CAAA;IAEpB;;;OAGG;IACH,YAAY,CAAC,EAAE,IAAI,CAAC,kBAAkB,EAAE,QAAQ,CAAC,CAAA;CAClD;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,cAAc,EAAE,OAAO,CAAA;IACvB,uBAAuB,EAAE,OAAO,CAAA;IAChC,WAAW,EAAE,MAAM,CAAA;IACnB,YAAY,EAAE,MAAM,CAAA;CACrB"}

package/dist/src/models/gemini/types.js

@@ -0,0 +1,5 @@
+/**
+ * Type definitions for the Gemini model provider.
+ */
+export {};
+//# sourceMappingURL=types.js.map