Support Gemini Image models in RubyLLM.paint

[danieldenis01]

Closes #473.

What this does

Fixes RubyLLM.paint for the Gemini Image model family (gemini-2.5-flash-image, gemini-3.1-flash-image-preview, gemini-3-pro-image-preview, nano-banana-pro-preview), which was hardcoded to the Imagen :predict protocol and unreachable.

The Gemini provider now branches on imagen?(model):

• Imagen keeps :predict with instances/parameters (byte-for-byte unchanged).
• Gemini Image routes to :generateContent with contents/parts and parses candidates[].content.parts[].inlineData, the same protocol Gemini chat uses.

On #473 you raised the concern that branching would require "a manual list of which model uses which interface, which is infeasible to maintain." This PR doesn't need one. The discriminator is a single prefix check — model.to_s.start_with?('imagen') — and the Gemini Image branch is the default fallthrough. Any new Gemini image model lands on the right path automatically (including nano-banana-pro-preview, which doesn't share the gemini- prefix). The check mirrors the existing /imagen/ pattern already in Gemini::Capabilities#pricing_family.

Improvements over the previous Gemini image generation

• Image-to-image editing (with:) — new capability. Before this PR the Gemini provider had no support for image references (with: was an unused method arg, rejected by the base validate_paint_inputs!). The Gemini Image branch now accepts one or more local files / URLs / Attachment instances via with:, reusing Gemini::Media#format_attachment to build inline_data parts. Imagen still rejects with:.
• size: is meaningful again on the Gemini Image branch. A small map translates the common DALL-E sizes (1024x1024, 1792x1024, 1024x1792, 1408x1024, 1024x1408) to Gemini aspectRatio. Unknown sizes default to 1:1 with a debug log. Imagen continues to ignore size:.
• params: deep-merges into the payload so users can override any nested generationConfig / imageConfig field without clobbering the rest.
• usageMetadata from Gemini Image responses is passed through to Image#usage.

The public signature RubyLLM.paint(prompt, model:, with:, size:, params:) is unchanged.

Reproduction (before this PR):

RubyLLM.paint('a red panda coding in Ruby', model: 'gemini-3.1-flash-image-preview')
# => RubyLLM::Error: ... is not supported for predict.

Type of change

• Bug fix
• New feature (image-to-image editing on the Gemini provider)
• Breaking change
• Documentation
• Performance improvement

Scope check

• I read the Contributing Guide
• This aligns with RubyLLM's focus on LLM communication
• This isn't application-specific logic that belongs in user code
• This benefits most users, not just my specific use case

Quality check

• I ran overcommit --install and all hooks pass
• I tested my changes thoroughly
  • Re-recorded VCR cassettes with bundle exec rake vcr:record[gemini]
  • All tests pass: bundle exec rspec
• I updated documentation if needed
• I didn't modify auto-generated files manually (models.json, aliases.json)

Tests added

Integration (VCR-backed, via IMAGE_GENERATION_MODELS):

• gemini-2.5-flash-image paint + image edit with with:
• gemini-3.1-flash-image-preview paint (the exact model from the bug report)

Unit-level (spec/ruby_llm/providers/gemini/images_spec.rb, no network):

• Imagen + with: raises UnsupportedAttachmentError
• Imagen response missing bytesBase64Encoded raises RubyLLM::Error
• Gemini Image + :unknown attachment type raises UnsupportedAttachmentError
• Gemini Image + unmapped size: defaults aspectRatio to 1:1

Coverage: lib/ruby_llm/providers/gemini/images.rb at 100% line / 79% branch.

AI-generated code

• I used AI tools to help write this code
• I have reviewed and understand all generated code

API changes

• Breaking change
• New public methods/classes
• Changed method signatures
• No API changes

Out of scope

• VertexAI has the same bug shape but no images.rb at all and needs OAuth — separate PR.
• Streaming image generation (:streamGenerateContent).
• Per-image pricing for the new Gemini Image entries (registry currently lacks pricing.images; Image#total_cost falls back to output_price_per_million).

[codecov]

Codecov Report

❌ Patch coverage is 91.30435% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 82.18%. Comparing base (f82711f) to head (5eaaed4).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
lib/ruby_llm/protocols/gemini/images.rb	91.30%	0 Missing and 4 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #750      +/-   ##
==========================================
+ Coverage   82.10%   82.18%   +0.07%     
==========================================
  Files         137      137              
  Lines        6344     6381      +37     
  Branches     1122     1133      +11     
==========================================
+ Hits         5209     5244      +35     
  Misses        684      684              
- Partials      451      453       +2     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[danieldenis01]

I'll implement the missing test cases.

[nathancolgate]

FWIW: When using gemini-3.1-flash-image-preview (Nano Banana) I had to create an initializer that allowed me to generate all of the available aspect ratios:

# https://ai.google.dev/gemini-api/docs/image-generation#go_3
RubyLLM::Providers::Gemini::Images.send(:remove_const, :SIZE_TO_ASPECT_RATIO)
RubyLLM::Providers::Gemini::Images.const_set(:SIZE_TO_ASPECT_RATIO, {
  "1:1" => "1:1",
  "1:4" => "1:4",
  "1:8" => "1:8",
  "2:3" => "2:3",
  "3:2" => "3:2",
  "3:4" => "3:4",
  "4:1" => "4:1",
  "4:3" => "4:3",
  "4:5" => "4:5",
  "5:4" => "5:4",
  "8:1" => "8:1",
  "9:16" => "9:16",
  "16:9" => "16:9",
  "21:9" => "21:9"
}.freeze)

[danieldenis01]

Thanks @nathancolgate — great catch, fair feedback that the WxH-only map was too restrictive.

Pushed 084bf50: aspect_ratio_for now also accepts any native X:Y string and passes it straight through to Gemini's aspectRatio. So RubyLLM.paint('...', size: '21:9') (or '2:3', '4:5', etc.) works directly — no more monkey-patching SIZE_TO_ASPECT_RATIO. The WxH map stays as a convenience for the default '1024x1024' that Image.paint sends.

This avoids hardcoding the supported set so any future ratio Google adds works without a code change.