/ 
Langertha-0.100
/ Langertha::Engine::Gemini

NAME

Langertha::Engine::Gemini - Google Gemini API

VERSION

version 0.100

SYNOPSIS

use Langertha::Engine::Gemini;

# Basic usage
my $gemini = Langertha::Engine::Gemini->new(
  api_key => $ENV{GEMINI_API_KEY},
  model => 'gemini-2.0-flash',
  response_size => 4096,
  temperature => 0.7,
);

# Simple chat
my $response = $gemini->simple_chat('Explain quantum computing in simple terms');
print $response;

# Streaming
$gemini->simple_chat_stream(sub {
  my ($chunk) = @_;
  print $chunk->content;
}, 'Write a poem about Perl');

# Async with Future::AsyncAwait
use Future::AsyncAwait;

async sub ask_gemini {
  my $response = await $gemini->simple_chat_f('What are the benefits of functional programming?');
  say $response;
}

async sub stream_gemini {
  my ($content, $chunks) = await $gemini->simple_chat_stream_realtime_f(
    sub { print shift->content },
    'Tell me about neural networks'
  );
  say "\nReceived ", scalar(@$chunks), " chunks";
}

DESCRIPTION

This module provides access to Google's Gemini models via their Generative Language API. Gemini is Google's family of multimodal AI models capable of understanding and generating text, code, images, audio, and video.

Available Models:

  • gemini-2.0-flash - Latest, fastest model with multimodal capabilities (default)

  • gemini-1.5-pro - Most capable model, best for complex reasoning tasks

  • gemini-1.5-flash - Fast and efficient model for high-volume tasks

Features:

  • Streaming support (SSE-based)

  • System prompts (via systemInstruction)

  • Temperature control (0.0 - 2.0)

  • Response size limits (maxOutputTokens)

  • Async/await support via Future::AsyncAwait

  • Multimodal capabilities (text, code, images)

  • Dynamic model discovery via API

LISTING AVAILABLE MODELS

Dynamically fetch available models from the Gemini API (with token pagination):

# Get simple list of model IDs
my $model_ids = $engine->list_models;
# Returns: ['gemini-2.0-flash-exp', 'gemini-1.5-pro', ...]

# Get full model objects with metadata
my $models = $engine->list_models(full => 1);

# Force refresh (bypass cache)
my $models = $engine->list_models(force_refresh => 1);

Note: Model IDs have the "models/" prefix stripped for convenience.

Caching: Results are cached for 1 hour. Configure TTL via models_cache_ttl or clear manually with clear_models_cache.

Deprecation Notice: The all_models() method returns a hardcoded list. Use list_models() for current availability.

Key Capabilities:

Gemini models support:

  • Long context windows (up to 2M tokens for Gemini 1.5 Pro)

  • Multimodal understanding (text, images, video, audio)

  • Function calling and tool use

  • Code generation and understanding

  • JSON mode for structured outputs

THIS API IS WORK IN PROGRESS

GETTING AN API KEY

Get your API key from https://aistudio.google.com/app/apikey

You can use Gemini for free with rate limits, or upgrade to paid tiers for higher usage.

Set the environment variable:

export GEMINI_API_KEY=your-key-here
# Or use LANGERTHA_GEMINI_API_KEY

EXAMPLES

Basic Chat

my $gemini = Langertha::Engine::Gemini->new(
  api_key => $ENV{GEMINI_API_KEY},
  model => 'gemini-2.0-flash',
);

my $answer = $gemini->simple_chat('What is the capital of France?');
print $answer;

With System Prompt

my $gemini = Langertha::Engine::Gemini->new(
  api_key => $ENV{GEMINI_API_KEY},
  model => 'gemini-1.5-pro',
  system_prompt => 'You are a helpful coding assistant specializing in Perl',
);

my $code = $gemini->simple_chat('Write a function to parse JSON');
print $code;

Streaming Response

$gemini->simple_chat_stream(sub {
  my ($chunk) = @_;
  print $chunk->content;
  STDOUT->flush;
}, 'Write a short story about a robot learning to paint');

Async/Await Pattern

use Future::AsyncAwait;

async sub multi_question {
  my ($gemini) = @_;

  my $q1 = await $gemini->simple_chat_f('What is Perl?');
  say "Answer 1: $q1\n";

  my $q2 = await $gemini->simple_chat_f('What is Moose?');
  say "Answer 2: $q2\n";
}

multi_question($gemini)->get;

Controlled Generation

my $gemini = Langertha::Engine::Gemini->new(
  api_key => $ENV{GEMINI_API_KEY},
  model => 'gemini-2.0-flash',
  temperature => 0.2,      # Lower = more deterministic
  response_size => 1024,   # Limit output tokens
);

MODEL SELECTION

gemini-2.0-flash (Default)

Latest and fastest model. Best for: - General chat and conversation - Quick responses - High-volume applications - Multimodal tasks

gemini-1.5-pro

Most capable model. Best for: - Complex reasoning and analysis - Long-form content generation - Tasks requiring deep understanding - Maximum context window (2M tokens)

gemini-1.5-flash

Fast and efficient. Best for: - High-volume processing - Real-time applications - Cost-sensitive deployments - Simple to moderate complexity tasks

SEE ALSO

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/langertha/issues.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHOR

Torsten Raudssus <torsten@raudssus.de> https://raudss.us/

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.