Nuntius

Nuntius

Ruby License Tests


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


Installation


gem install nuntius-rb

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: Flash family (Free-Tier)


Key ID
:flash_latest gemini-flash-latest
:flash_3_7 gemini-3.7-flash
:flash_3_6 gemini-3.6-flash
:flash_3_5 gemini-3.5-flash
:flash_3_5_lite gemini-3.5-flash-lite
:flash_3_preview gemini-3-flash-preview
:flash_3_1_lite gemini-3.1-flash-lite
:flash_2_5 gemini-2.5-flash
:flash_2_0 gemini-2.0-flash

Short aliases: :flash uses gemini-3.7-flash (default), :flash_fallback uses gemini-3.6-flash, and :flash_lite uses gemini-3.1-flash-lite. Legacy :pro_2_0 maps to gemini-2.0-flash. Pro models (gemini-pro-latest, gemini-3.1-pro-preview, gemini-2.5-pro) are retired for Free-Tier, as they resolve to the 3.1-pro backend and hit quota 0. Use billing to enable.


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.7-flash (fallback gemini-3.6-flash for large diffs). Override with NUNTIUS_GEMINI_MODEL. Retrieval context is off unless enabled in nuntius/config.yaml. Only verified generateContent Flash models are listed as supported. See API GET /v1beta/models for existence, not quota.


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 app 

<a href="https://github.com/apps/nuntius-review"><code>Nuntius Review</code></a>