Nuntius

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

Installation

gem install nuntius-rb --pre

With Bundler:

gem 'nuntius-rb', require: 'nuntius'

The package is published as nuntius-rb. The runtime entrypoint is nuntius.

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 'nuntius'
Nuntius.load_env

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

Use a different model when needed:

fast_client = Nuntius::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

Nuntius 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 Nuntius::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 Nuntius::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 'nuntius'

Nuntius::Client.logger.level = Logger::INFO
client = Nuntius::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 nuntius-rb.gemspec

Review App

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

For setup details, see nuntius/Nuntius.md.

Examples

Text Generation

client = Nuntius::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 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.

Nuntius Review