https://github.com/palmshed/vesper
gemini client.
https://github.com/palmshed/vesper
gemini ruby
Last synced: 25 days ago
JSON representation
gemini client.
- Host: GitHub
- URL: https://github.com/palmshed/vesper
- Owner: palmshed
- License: mit
- Created: 2025-02-28T19:43:43.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2026-06-06T08:48:41.000Z (27 days ago)
- Last Synced: 2026-06-06T10:20:01.970Z (27 days ago)
- Topics: gemini, ruby
- Language: Python
- Homepage: https://palmshed.github.io/vesper/
- Size: 1.71 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: docs/CONTRIBUTING.md
- License: LICENSE
- Code of conduct: docs/CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Security: .github/SECURITY.md
Awesome Lists containing this project
README
# Vesper
[](https://rubygems.org/gems/friday_gemini_ai)
[](LICENSE)
Ruby client for Gemini `generateContent`. Includes a CLI and a PR review app.
# Installation
```bash
gem install friday_gemini_ai
```
With Bundler:
```ruby
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
```ruby
require 'vesper'
GeminiAI.load_env
client = GeminiAI::Client.new
puts client.generate_text('Write a haiku about Ruby')
```
Use a different model when needed:
```ruby
fast_client = GeminiAI::Client.new(model: :flash)
puts fast_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.
```ruby
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
```ruby
require 'vesper'
GeminiAI::Client.logger.level = Logger::INFO
client = GeminiAI::Client.new
```
# Requirements
Ruby 3.3 or later. Linux and macOS are tested.
# Environment Variables
```bash
GEMINI_API_KEY=your_api_key_here
```
# Repo CLI
```bash
./bin/gemini test
./bin/gemini generate "Your prompt"
./bin/gemini chat
```
# Local Development & Testing
```bash
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`](vesper/Vesper.md).
# Examples
# Text Generation
```ruby
client = GeminiAI::Client.new
puts client.generate_text('Write a haiku about Ruby')
```
# Image Analysis
```ruby
image_data = Base64.strict_encode64(File.binread('path/to/image.jpg'))
puts client.generate_image_text(image_data, 'Describe this image')
```
# Chat
```ruby
messages = [
{ role: 'user', content: 'Hello!' },
{ role: 'model', content: 'Hi there!' },
{ role: 'user', content: 'Tell me about Ruby.' }
]
puts client.chat(messages, system_instruction: 'Be concise.')
```
# Documentation
| Need | Link |
| --- | --- |
| Start | [`Quickstart`](docs/start/quickstart.md) |
| API | [`Reference`](docs/reference/api.md) |
| Recipes | [`Cookbook`](docs/reference/cookbook.md) |
| Practice | [`Best practices`](docs/guides/practices.md) |
| Automation | [`Workflows`](docs/guides/workflows.md) |
| Project | [`Contributing`](docs/CONTRIBUTING.md) |
# Contributing
Fork the repo and open a pull request.
# License
MIT → see [`LICENSE`](LICENSE).
