Vesper

Ruby client for Gemini generateContent. Includes a CLI and a PR review app.

Installation

gem install friday_gemini_ai

With Bundler:

gem'friday_gemini_ai',require: 'vesper'

The package is published as friday_gemini_ai. The runtime entrypoint is vesper.

Set your API key in .env:

GEMINI_API_KEY=your_api_key

Note

Ensure your API key is kept secure and not committed to version control.

Usage

Basic Setup

require'vesper'GeminiAI.load_envclient=GeminiAI::Client.newputsclient.generate_text('Write a haiku about Ruby')

Use a different model when needed:

fast_client=GeminiAI::Client.new(model: :flash)putsfast_client.generate_text('Explain Ruby in one sentence')

generateContent Text Models

Key	ID
:flash_latest	gemini-flash-latest
:pro_latest	gemini-pro-latest
:flash_3_5	gemini-3.5-flash
:pro_3_preview	gemini-3-pro-preview
:flash_3_preview	gemini-3-flash-preview
:pro_3_1_preview	gemini-3.1-pro-preview
:flash_3_1_lite	gemini-3.1-flash-lite
:pro_2_5	gemini-2.5-pro
:flash_2_5	gemini-2.5-flash
:flash_2_0	gemini-2.0-flash

Short aliases: :pro uses gemini-pro-latest, :flash uses gemini-3.5-flash, and :flash_lite uses gemini-3.1-flash-lite. Legacy :pro_2_0 maps to gemini-2.0-flash.

The gem does not wrap embeddings, Imagen, or Veo APIs.

Capabilities

Vesper supports text generation, chat, image input for generateContent, model aliases, safety settings, API key masking, retries, and a local CLI.

Handling Errors

Client validation and API failures raise GeminiAI::Error with a readable message. HTTP 429 responses are retried automatically up to three times with exponential backoff.

beginresponse=client.generate_text('Hello')putsresponserescueGeminiAI::Error=>errwarn"Generation failed: #{err.message}"end

Common failures include:

• Missing or invalid GEMINI_API_KEY
• Empty prompts
• Prompts over the configured maximum length
• Gemini API errors returned by the service
• Network errors raised by HTTParty

Retries

Rate-limit responses (429) are retried up to three times with waits of 5, 10, and 20 seconds.

Timeouts

Requests use a 30 second HTTParty timeout.

Logging

require'vesper'GeminiAI::Client.logger.level=Logger::INFOclient=GeminiAI::Client.new

Requirements

Ruby 3.3 or later. Linux and macOS are tested.

Environment Variables

GEMINI_API_KEY=your_api_key_here

Repo CLI

./bin/gemini test
./bin/gemini generate "Your prompt"
./bin/gemini chat

Local Development & Testing

bundle exec rake test# Run tests
bundle exec rake docs # Build API docs
gem build friday_gemini_ai.gemspec

Review App

Vesper Review is the PR review app in this repo. It defaults to gemini-3.5-flash; retrieval context is off unless enabled in vesper/config.yaml.

For setup details, see vesper/Vesper.md.

Examples

Text Generation

client=GeminiAI::Client.newputsclient.generate_text('Write a haiku about Ruby')

Image Analysis

image_data=Base64.strict_encode64(File.binread('path/to/image.jpg'))putsclient.generate_image_text(image_data,'Describe this image')

Chat

messages=[{role: 'user',content: 'Hello!'},{role: 'model',content: 'Hi there!'},{role: 'user',content: 'Tell me about Ruby.'}]putsclient.chat(messages,system_instruction: 'Be concise.')

Documentation

Need	Link
Start	Quickstart
API	Reference
Recipes	Cookbook
Practice	Best practices
Automation	Workflows
Project	Contributing

Contributing

Fork the repo and open a pull request.

License

MIT → see LICENSE.

Vesper Review