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
HARPERBOT_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

HarperBot

HarperBot is the optional PR-review companion included in this repo. For setup details, see harperbot/HarperBot.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.