@flink-app/gemini-adapter

Google Gemini adapter for the Flink AI framework, built on the @google/genai SDK (the Gemini Developer API). The SDK is a regular dependency, nothing else needs installing.

Installation

npm install @flink-app/gemini-adapter

Usage

import { GeminiAdapter } from "@flink-app/gemini-adapter";
import { FlinkApp } from "@flink-app/flink";

const app = new FlinkApp({
  ai: {
    llms: {
      default: new GeminiAdapter({
        apiKey: process.env.GOOGLE_AI_API_KEY!,
        model: "gemini-2.0-flash",
      }),
    },
  },
});

Configuration

| Option | Type | Required | Description | |---------|-----------|----------|--------------------------------------------------------------------| | apiKey | string | Yes | Google AI API key | | model | string | Yes | Gemini model name (e.g. "gemini-2.0-flash", "gemini-1.5-pro") | | thinkingConfig | GeminiThinkingConfig | No | Passed through as config.thinkingConfig (includeThoughts, thinkingBudget, thinkingLevel, any future field) | | debug | boolean | No | Enable debug logging (default: false) |

Supported Models

• gemini-2.0-flash — Fast, cost-effective (recommended default)
• gemini-1.5-pro — High capability, longer context
• gemini-1.5-flash — Fast, balanced capability
• gemini-2.5-pro-preview-03-25 — Latest preview model

Thinking

Thinking models (Gemini 2.5 / 3 series) are configured with thinkingConfig, passed through verbatim as config.thinkingConfig:

const adapter = new GeminiAdapter({
  apiKey: process.env.GOOGLE_AI_API_KEY!,
  model: "gemini-2.5-pro",
  thinkingConfig: { includeThoughts: true, thinkingBudget: 2048 }, // optional
});

• With includeThoughts: true, thought summaries are streamed as reasoning chunks and surfaced by the agent as reasoning_delta events on fullStream. They never appear in textStream or result.message. Summaries are not sent back to Gemini.
• Thought signatures returned on text and function call parts are captured (providerData.gemini.signatures) and replayed on the same parts in later turns. Gemini 3 rejects tool-call continuations with a 400 when the first function call's signature is missing, so this happens regardless of thinkingConfig.
• Thinking tokens (thoughtsTokenCount) are included in the reported outputTokens.

Structured Output and Tool Choice

An agent's model.structuredOutput is sent as config.responseMimeType: "application/json" plus responseSchema. Gemini takes an OpenAPI-style subset of JSON Schema, so $schema, $ref, $defs, additionalProperties and default are stripped (the same sanitization tool schemas get). The parsed reply is available as result.structured.

Gemini does not accept a response schema together with function declarations. On steps that carry tools the schema is requested through the system instruction instead, and Flink validates the reply; the native response schema is used as soon as a step has no tools.

model.toolChoice is sent as toolConfig.functionCallingConfig: "auto" → AUTO, "none" → NONE, "required" → ANY, { type: "tool", name } → ANY with allowedFunctionNames: [name]. Only sent when the request carries tools.

Image Model

GeminiImageModel implements Flink's ImageModel interface for the image-capable Gemini models (gemini-3.1-flash-image, gemini-3-pro-image, gemini-3.1-flash-lite-image) through generateContent with image response modality.

import { GeminiImageModel } from "@flink-app/gemini-adapter";

const app = new FlinkApp<AppCtx>({
    ai: {
        images: {
            default: new GeminiImageModel({ apiKey: process.env.GEMINI_API_KEY!, model: "gemini-3.1-flash-image", imageSize: "2K" }),
        },
    },
});

const { images } = await ctx.ai.images.default.edit({
    prompt: "Make it night time, keep the car unchanged",
    images: [imageFromBuffer(file, "image/png")],
});

• Editing is prompt driven: Gemini takes no mask (capabilities.mask is false, a mask fails with unsupported)
• size is reduced to an aspect ratio with a warning; n above one is served by parallel requests
• Text returned alongside the image lands in providerMetadata.gemini.text; providerOptions.gemini is merged into the request config
• See the Image Models guide

Features

• ✅ Tool calling support
• ✅ Thinking (thinkingConfig passthrough), thought summaries as reasoning_delta, thought signatures replayed across turns
• ✅ Streaming responses (SSE / NDJSON)
• ✅ Alternating turn enforcement (consecutive same-role messages are merged)
• ✅ System instruction handling
• ✅ JSON Schema sanitization for Gemini compatibility
• ✅ Token usage tracking
• ✅ Debug logging

Using with FlinkAgent

import { FlinkAgent } from "@flink-app/flink";
import { GeminiAdapter } from "@flink-app/gemini-adapter";

export default class CarAgent extends FlinkAgent<AppContext> {
  instructions = "You are a helpful car assistant.";
  llm = new GeminiAdapter({
    apiKey: process.env.GOOGLE_AI_API_KEY!,
    model: "gemini-2.0-flash",
  });
}

License

MIT