tessl/maven-dev-langchain4j--langchain4j-google-ai-gemini

LangChain4j integration for Google AI Gemini models providing chat, streaming, embeddings, image generation, and batch processing capabilities

Overview

Eval results

Files

Advanced Configuration

Name: tessl/maven-dev-langchain4j--langchain4j-google-ai-gemini
Author: tessl

Advanced configuration classes for fine-grained control over generation behavior, structured outputs, and response parameters. These provide granular control beyond basic model parameters.

Capabilities

GeminiGenerationConfig

Record providing comprehensive generation control including temperature, token limits, structured output schemas, response modalities, and advanced parameters.

/**
 * Comprehensive generation configuration for Gemini models.
 * Controls all aspects of text generation behavior.
 */
public record GeminiGenerationConfig(
    /**
     * List of sequences where generation will stop.
     * Up to 5 stop sequences.
     */
    List<String> stopSequences,

    /**
     * MIME type for structured responses.
     * Examples: "application/json", "text/plain"
     */
    String responseMimeType,

    /**
     * Schema for structured JSON responses (internal schema format).
     * Used with responseMimeType="application/json".
     * Note: Schema is defined internally; use responseJsonSchema for custom schemas.
     */
    Object responseSchema,

    /**
     * Alternative JSON schema as Map for structured responses.
     * Can be used instead of responseSchema.
     */
    Map<String, Object> responseJsonSchema,

    /**
     * Number of response candidates to generate.
     * Default: 1. Only 1 is currently supported.
     */
    Integer candidateCount,

    /**
     * Maximum number of tokens to generate in response.
     * Controls output length.
     */
    Integer maxOutputTokens,

    /**
     * Sampling temperature (0.0 to 2.0).
     * Higher values increase randomness. Default varies by model.
     */
    Double temperature,

    /**
     * Top-K sampling parameter.
     * Limits token selection to top K options.
     */
    Integer topK,

    /**
     * Random seed for deterministic generation.
     * Same seed with same parameters produces same output.
     */
    Integer seed,

    /**
     * Top-P (nucleus) sampling parameter (0.0 to 1.0).
     * Limits token selection to cumulative probability P.
     */
    Double topP,

    /**
     * Presence penalty (-2.0 to 2.0).
     * Positive values discourage repeating topics.
     */
    Double presencePenalty,

    /**
     * Frequency penalty (-2.0 to 2.0).
     * Positive values discourage repeating tokens.
     */
    Double frequencyPenalty,

    /**
     * Configuration for thinking/reasoning mode.
     * Controls extended reasoning capabilities.
     */
    GeminiThinkingConfig thinkingConfig,

    /**
     * Whether to include log probabilities in response.
     * Provides confidence scores for generated tokens.
     */
    Boolean responseLogprobs,

    /**
     * Enable enhanced civic answers.
     * Improved responses for civic/political queries.
     */
    Boolean enableEnhancedCivicAnswers,

    /**
     * List of response modalities (TEXT, IMAGE).
     * Controls types of content in response.
     */
    List<GeminiResponseModality> responseModalities,

    /**
     * Configuration for image generation in responses.
     * Used when IMAGE response modality is enabled.
     */
    GeminiImageConfig imageConfig,

    /**
     * Number of log probabilities to return per token.
     * Requires responseLogprobs=true.
     */
    Integer logprobs,

    /**
     * Media resolution level for processing images/videos.
     * Controls quality vs speed tradeoff.
     */
    GeminiMediaResolutionLevel mediaResolution
) {
    /**
     * Creates a new builder for generation config.
     * @return Builder instance
     */
    public static Builder builder();
}

GeminiGenerationConfig.GeminiImageConfig

Nested record for image generation configuration.

/**
 * Configuration for image generation in responses.
 * Used when generating images as part of model output.
 */
public record GeminiImageConfig(
    /**
     * Aspect ratio for generated images.
     * Examples: "1:1", "16:9", "4:3", "9:16"
     */
    String aspectRatio,

    /**
     * Size specification for generated images.
     * Examples: "256x256", "512x512", "1024x1024", "2K", "4K"
     */
    String imageSize
) {
    /**
     * Creates a new builder for image config.
     * @return Builder instance
     */
    public static Builder builder();
}

Usage Examples

Basic Generation Configuration

import dev.langchain4j.model.googleai.GeminiGenerationConfig;
import dev.langchain4j.model.googleai.GoogleAiGeminiChatModel;

// Configure generation parameters
GeminiGenerationConfig config = GeminiGenerationConfig.builder()
    .maxOutputTokens(2048)
    .temperature(0.7)
    .topP(0.9)
    .topK(40)
    .build();

GoogleAiGeminiChatModel model = GoogleAiGeminiChatModel.builder()
    .apiKey(System.getenv("GOOGLE_AI_API_KEY"))
    .modelName("gemini-2.5-pro")
    .generationConfig(config)
    .build();

Structured JSON Output with Schema

import dev.langchain4j.model.output.structured.Description;
import dev.langchain4j.model.output.ResponseFormat;
import dev.langchain4j.model.output.ResponseFormatType;
import dev.langchain4j.model.output.JsonSchema;

// Define a Java record for structured output
record Person(
    @Description("Person's full name") String name,
    @Description("Person's age in years") int age,
    @Description("Email address") String email,
    @Description("List of interests") List<String> interests
) {}

// Use ResponseFormat with JSON schema from class
GoogleAiGeminiChatModel model = GoogleAiGeminiChatModel.builder()
    .apiKey(System.getenv("GOOGLE_AI_API_KEY"))
    .modelName("gemini-2.5-flash")
    .responseFormat(ResponseFormat.builder()
        .type(ResponseFormatType.JSON)
        .jsonSchema(JsonSchema.from(Person.class))
        .build())
    .build();

// Model will return structured JSON matching schema
var response = model.generate("Create a profile for John Smith, age 30");

Stop Sequences

// Stop generation at specific sequences
GeminiGenerationConfig config = GeminiGenerationConfig.builder()
    .stopSequences(List.of("\n\n", "END", "---"))
    .maxOutputTokens(1000)
    .build();

GoogleAiGeminiChatModel model = GoogleAiGeminiChatModel.builder()
    .apiKey(System.getenv("GOOGLE_AI_API_KEY"))
    .modelName("gemini-2.5-pro")
    .generationConfig(config)
    .build();

// Generation will stop when any stop sequence is encountered

Deterministic Generation with Seed

// Use seed for reproducible outputs
GeminiGenerationConfig config = GeminiGenerationConfig.builder()
    .seed(42)
    .temperature(0.0)
    .build();

GoogleAiGeminiChatModel model = GoogleAiGeminiChatModel.builder()
    .apiKey(System.getenv("GOOGLE_AI_API_KEY"))
    .modelName("gemini-2.5-flash")
    .generationConfig(config)
    .build();

// Same seed + same temperature = same output

Presence and Frequency Penalties

// Reduce repetition with penalties
GeminiGenerationConfig config = GeminiGenerationConfig.builder()
    .presencePenalty(0.6)  // Discourage repeating topics
    .frequencyPenalty(0.4) // Discourage repeating words
    .temperature(0.8)
    .build();

GoogleAiGeminiChatModel model = GoogleAiGeminiChatModel.builder()
    .apiKey(System.getenv("GOOGLE_AI_API_KEY"))
    .modelName("gemini-2.5-pro")
    .generationConfig(config)
    .build();

// Output will be more diverse with less repetition

Log Probabilities

// Get confidence scores for generated tokens
GeminiGenerationConfig config = GeminiGenerationConfig.builder()
    .responseLogprobs(true)
    .logprobs(5) // Return top 5 log probs per token
    .build();

GoogleAiGeminiChatModel model = GoogleAiGeminiChatModel.builder()
    .apiKey(System.getenv("GOOGLE_AI_API_KEY"))
    .modelName("gemini-2.5-flash")
    .generationConfig(config)
    .build();

// Response will include probability scores for tokens

Image Generation in Response

import dev.langchain4j.model.googleai.GeminiResponseModality;

// Configure image generation in response
GeminiGenerationConfig.GeminiImageConfig imageConfig =
    GeminiGenerationConfig.GeminiImageConfig.builder()
        .aspectRatio("16:9")
        .imageSize("1024x1024")
        .build();

GeminiGenerationConfig config = GeminiGenerationConfig.builder()
    .responseModalities(List.of(
        GeminiResponseModality.TEXT,
        GeminiResponseModality.IMAGE
    ))
    .imageConfig(imageConfig)
    .build();

GoogleAiGeminiChatModel model = GoogleAiGeminiChatModel.builder()
    .apiKey(System.getenv("GOOGLE_AI_API_KEY"))
    .modelName("gemini-2.5-flash")
    .generationConfig(config)
    .build();

// Model can generate both text and images in response

Complex Structured Schema

import dev.langchain4j.model.output.structured.Description;

// Define nested records for complex structured output
record Address(
    String street,
    String city,
    String zipCode
) {}

record Company(
    @Description("Company name") String name,
    @Description("Year founded") int founded,
    @Description("Number of employees") int employees,
    Address address,
    @Description("Publicly traded company") boolean isPublic,
    @Description("List of products") List<String> products
) {}

// Use ResponseFormat with nested schema
GoogleAiGeminiChatModel model = GoogleAiGeminiChatModel.builder()
    .apiKey(System.getenv("GOOGLE_AI_API_KEY"))
    .modelName("gemini-2.5-pro")
    .responseFormat(ResponseFormat.builder()
        .type(ResponseFormatType.JSON)
        .jsonSchema(JsonSchema.from(Company.class))
        .build())
    .build();

var response = model.generate("Provide information about Google");
// Returns structured JSON matching the complex schema

Enum Schema

// Define schema with enumerations using Java enums
enum Status { PENDING, APPROVED, REJECTED, IN_PROGRESS }
enum Priority { LOW, MEDIUM, HIGH, CRITICAL }

record Request(
    String id,
    Status status,
    Priority priority
) {}

GoogleAiGeminiChatModel model = GoogleAiGeminiChatModel.builder()
    .apiKey(System.getenv("GOOGLE_AI_API_KEY"))
    .modelName("gemini-2.5-pro")
    .responseFormat(ResponseFormat.builder()
        .type(ResponseFormatType.JSON)
        .jsonSchema(JsonSchema.from(Request.class))
        .build())
    .build();

// Model will only use enum values for status and priority

Alternative Schemas with JSON Maps

// For advanced schema needs, use responseJsonSchema with Map
Map<String, Object> schema = Map.of(
    "type", "object",
    "properties", Map.of(
        "value", Map.of(
            "description", "Can be either string or number",
            "anyOf", List.of(
                Map.of("type", "string"),
                Map.of("type", "number")
            )
        )
    )
);

GeminiGenerationConfig config = GeminiGenerationConfig.builder()
    .responseMimeType("application/json")
    .responseJsonSchema(schema)
    .build();

Enhanced Civic Answers

// Enable enhanced civic/political responses
GeminiGenerationConfig config = GeminiGenerationConfig.builder()
    .enableEnhancedCivicAnswers(true)
    .temperature(0.7)
    .build();

GoogleAiGeminiChatModel model = GoogleAiGeminiChatModel.builder()
    .apiKey(System.getenv("GOOGLE_AI_API_KEY"))
    .modelName("gemini-2.5-pro")
    .generationConfig(config)
    .build();

// Better responses for political and civic queries

Comprehensive Configuration

// Combine multiple configuration options
GeminiThinkingConfig thinkingConfig = GeminiThinkingConfig.builder()
    .includeThoughts(true)
    .thinkingLevel(GeminiThinkingLevel.HIGH)
    .thinkingBudget(2000)
    .build();

record Output(
    @Description("The main answer") String answer,
    @Description("Confidence score 0-1") double confidence
) {}

GoogleAiGeminiChatModel model = GoogleAiGeminiChatModel.builder()
    .apiKey(System.getenv("GOOGLE_AI_API_KEY"))
    .modelName("gemini-2.0-flash-thinking-exp")
    .maxOutputTokens(4096)
    .temperature(0.3)
    .topP(0.95)
    .topK(40)
    .presencePenalty(0.2)
    .frequencyPenalty(0.1)
    .stopSequences(List.of("END"))
    .responseFormat(ResponseFormat.builder()
        .type(ResponseFormatType.JSON)
        .jsonSchema(JsonSchema.from(Output.class))
        .build())
    .thinkingConfig(thinkingConfig)
    .responseLogprobs(true)
    .logprobs(3)
    .mediaResolution(GeminiMediaResolutionLevel.MEDIA_RESOLUTION_HIGH)
    .build();

Best Practices

Temperature: Use 0.0-0.3 for factual tasks, 0.7-1.0 for creative tasks
Top-P vs Top-K: Use top-P for most cases; top-K for more controlled diversity
Penalties: Start with small values (0.1-0.3); increase if repetition persists
Stop sequences: Useful for structured generation and section boundaries
Schemas: Always provide descriptions for better model understanding
Required fields: Mark critical fields as required in schemas
Seed: Use with temperature=0 for fully deterministic output
Max tokens: Set appropriate limits to control cost and response length
Response MIME type: Must be "application/json" when using schemas
Thinking config: Use for complex reasoning tasks requiring explanation

Integration Notes

GeminiGenerationConfig is set at model builder level and applies to all requests
Can be overridden per-request using ChatRequest parameters
Schema validation happens server-side; invalid schemas will cause errors
Not all models support all features (e.g., image generation, thinking mode)
Log probabilities increase response size; use only when needed

Install with Tessl CLI

npx tessl i tessl/maven-dev-langchain4j--langchain4j-google-ai-gemini@1.11.0

docs

advanced-configuration.md

tessl/maven-dev-langchain4j--langchain4j-google-ai-gemini