Vesper

Ruby client for Google's Gemini models, with a small CLI and an optional PR-review companion.

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_env

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

Use a different model when needed:

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

Model Reference

Key	ID	Use case
:pro	gemini-2.5-pro	Most capable, complex reasoning
:flash	gemini-2.5-flash	Fast, general-purpose
:flash_2_0	gemini-2.0-flash	Legacy support
:flash_lite	gemini-2.0-flash-lite	Lightweight legacy

Capabilities

Vesper supports text generation, chat, image-to-text analysis, model aliases, safety settings, API key masking, retry handling, and a local CLI for quick prompts.

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.

begin
  response = client.generate_text('Hello')
  puts response
rescue GeminiAI::Error => err
  warn "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::INFO
client = GeminiAI::Client.new

Requirements

Ruby 3.1 or later. Linux and macOS are recommended.

Environment Variables

GEMINI_API_KEY=your_api_key_here
VESPER_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 rubocop       # Optional lint check
gem build *.gemspec            # Verify build

PR Review

Vesper is the optional PR-review companion included in this repo. For setup details, see vesper/Vesper.md.

Examples

Text Generation

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

Image Analysis

image_data = Base64.strict_encode64(File.binread('path/to/image.jpg'))
puts client.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.' }
]
puts client.chat(messages, system_instruction: 'Be helpful and 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