gemini-ai 2.2.0 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c7c5bd6e6cd1d2195b7a437fb0664cd553dc0acbf0d293042d93c3d701e6b6e0
-  data.tar.gz: 665458cc152b00efae9f8e2b730fe000ef2caac63f835944c1e76a83b9a0e627
+  metadata.gz: 36be77448ab7ba00008ac7548c25fdca45b92980762303631de5d6bdbcd2d01a
+  data.tar.gz: e0772790afa6019424282e8ac665fb0049da13a76ecc43909b147655f6f95a3a
 SHA512:
-  metadata.gz: 0ca1f3f87c61276902259d937f4d57f324a756d1e63c1e5781680ba970313f3c3c29a2da49c4eb1ec0bf351f984bee378e86b22d1656b2423638e1a70bd5dddf
-  data.tar.gz: 50988d0881d37f561e0c75ac1beea4fc9b34c757d0f16fb2dcb2f63d3e63f867194e0f826800c8429ce9f33500dd74c3fa4c5d747a0975378c81cf3e0ad4a61b
+  metadata.gz: e4d6c7391dff2ce75a46e3ceb5c7ef9c07c6cdcfc55477df68be1df2e06f77ff77d795ee6e70abc9ad73001e8dd583d39949a394140b129d08c2db94c2b8f7c4
+  data.tar.gz: 2acedebdfe562b7b68d19046a2f2b06bec6fbe75768cc7066b7c1e31cb72bc4caa551a8d656ffc6537c714f0d11965f3cc9f74542e7bc9315f0998f35390d5f4

data/Gemfile.lock

@@ -1,9 +1,9 @@
 PATH
   remote: .
   specs:
-    gemini-ai (2.2.0)
+    gemini-ai (3.1.0)
       event_stream_parser (~> 1.0)
-      faraday (~> 2.7, >= 2.7.12)
+      faraday (~> 2.8, >= 2.8.1)
       googleauth (~> 1.9, >= 1.9.1)
 
 GEM
@@ -16,7 +16,7 @@ GEM
     byebug (11.1.3)
     coderay (1.1.3)
     event_stream_parser (1.0.0)
-    faraday (2.7.12)
+    faraday (2.8.1)
       base64
       faraday-net_http (>= 2.0, < 3.1)
       ruby2_keywords (>= 0.0.4)

data/README.md

@@ -9,7 +9,7 @@ A Ruby Gem for interacting with [Gemini](https://deepmind.google/technologies/ge
 ## TL;DR and Quick Start
 
 ```ruby
-gem 'gemini-ai', '~> 2.2.0'
+gem 'gemini-ai', '~> 3.1.0'
 ```
 
 ```ruby
@@ -21,7 +21,7 @@ client = Gemini.new(
     service: 'generative-language-api',
     api_key: ENV['GOOGLE_API_KEY']
   },
-  options: { model: 'gemini-pro', stream: false }
+  options: { model: 'gemini-pro', server_sent_events: true }
 )
 
 # With a Service Account Credentials File
@@ -31,7 +31,7 @@ client = Gemini.new(
     file_path: 'google-credentials.json',
     region: 'us-east4'
   },
-  options: { model: 'gemini-pro', stream: false }
+  options: { model: 'gemini-pro', server_sent_events: true }
 )
 
 # With Application Default Credentials
@@ -40,7 +40,7 @@ client = Gemini.new(
     service: 'vertex-ai-api',
     region: 'us-east4'
   },
-  options: { model: 'gemini-pro', stream: false }
+  options: { model: 'gemini-pro', server_sent_events: true }
 )
 
 result = client.stream_generate_content({
@@ -81,17 +81,23 @@ Result:
         - [Required Data](#required-data)
 - [Usage](#usage)
     - [Client](#client)
-    - [Generate Content](#generate-content)
-        - [Modes](#modes)
-            - [Text](#text)
-            - [Image](#image)
-            - [Video](#video)
-        - [Synchronous](#synchronous)
-        - [Streaming](#streaming)
-        - [Streaming Hang](#streaming-hang)
-        - [Back-and-Forth Conversations](#back-and-forth-conversations)
-        - [Tools (Functions) Calling](#tools-functions-calling)
+    - [Methods](#methods)
+        - [stream_generate_content](#stream_generate_content)
+            - [Receiving Stream Events](#receiving-stream-events)
+            - [Without Events](#without-events)
+        - [generate_content](#generate_content)
+    - [Modes](#modes)
+        - [Text](#text)
+        - [Image](#image)
+        - [Video](#video)
+    - [Streaming vs. Server-Sent Events (SSE)](#streaming-vs-server-sent-events-sse)
+        - [Server-Sent Events (SSE) Hang](#server-sent-events-sse-hang)
+        - [Non-Streaming](#non-streaming)
+    - [Back-and-Forth Conversations](#back-and-forth-conversations)
+    - [Tools (Functions) Calling](#tools-functions-calling)
     - [New Functionalities and APIs](#new-functionalities-and-apis)
+    - [Request Options](#request-options)
+        - [Timeout](#timeout)
     - [Error Handling](#error-handling)
         - [Rescuing](#rescuing)
         - [For Short](#for-short)
@@ -108,11 +114,11 @@ Result:
 ### Installing
 
 ```sh
-gem install gemini-ai -v 2.2.0
+gem install gemini-ai -v 3.1.0
 ```
 
 ```sh
-gem 'gemini-ai', '~> 2.2.0'
+gem 'gemini-ai', '~> 3.1.0'
 ```
 
 ### Credentials
@@ -279,7 +285,7 @@ client = Gemini.new(
     service: 'generative-language-api',
     api_key: ENV['GOOGLE_API_KEY']
   },
-  options: { model: 'gemini-pro', stream: false }
+  options: { model: 'gemini-pro', server_sent_events: true }
 )
 
 # With a Service Account Credentials File
@@ -289,7 +295,7 @@ client = Gemini.new(
     file_path: 'google-credentials.json',
     region: 'us-east4'
   },
-  options: { model: 'gemini-pro', stream: false }
+  options: { model: 'gemini-pro', server_sent_events: true }
 )
 
 # With Application Default Credentials
@@ -298,15 +304,118 @@ client = Gemini.new(
     service: 'vertex-ai-api',
     region: 'us-east4'
   },
-  options: { model: 'gemini-pro', stream: false }
+  options: { model: 'gemini-pro', server_sent_events: true }
 )
 ```
 
-### Generate Content
+### Methods
 
-#### Modes
+#### stream_generate_content
 
-##### Text
+##### Receiving Stream Events
+
+Ensure that you have enabled [Server-Sent Events](#streaming-vs-server-sent-events-sse) before using blocks for streaming:
+
+```ruby
+client.stream_generate_content(
+  { contents: { role: 'user', parts: { text: 'hi!' } } }
+) do |event, parsed, raw|
+  puts event
+end
+```
+
+Event:
+```ruby
+{ 'candidates' =>
+  [{ 'content' => {
+       'role' => 'model',
+       'parts' => [{ 'text' => 'Hello! How may I assist you?' }]
+     },
+     'finishReason' => 'STOP',
+     'safetyRatings' =>
+     [{ 'category' => 'HARM_CATEGORY_HARASSMENT', 'probability' => 'NEGLIGIBLE' },
+      { 'category' => 'HARM_CATEGORY_HATE_SPEECH', 'probability' => 'NEGLIGIBLE' },
+      { 'category' => 'HARM_CATEGORY_SEXUALLY_EXPLICIT', 'probability' => 'NEGLIGIBLE' },
+      { 'category' => 'HARM_CATEGORY_DANGEROUS_CONTENT', 'probability' => 'NEGLIGIBLE' }] }],
+  'usageMetadata' => {
+    'promptTokenCount' => 2,
+    'candidatesTokenCount' => 8,
+    'totalTokenCount' => 10
+  } }
+```
+
+##### Without Events
+
+You can use `stream_generate_content` without events:
+
+```ruby
+result = client.stream_generate_content(
+  { contents: { role: 'user', parts: { text: 'hi!' } } }
+)
+```
+
+In this case, the result will be an array with all the received events:
+
+```ruby
+[{ 'candidates' =>
+   [{ 'content' => {
+        'role' => 'model',
+        'parts' => [{ 'text' => 'Hello! How may I assist you?' }]
+      },
+      'finishReason' => 'STOP',
+      'safetyRatings' =>
+      [{ 'category' => 'HARM_CATEGORY_HARASSMENT', 'probability' => 'NEGLIGIBLE' },
+       { 'category' => 'HARM_CATEGORY_HATE_SPEECH', 'probability' => 'NEGLIGIBLE' },
+       { 'category' => 'HARM_CATEGORY_SEXUALLY_EXPLICIT', 'probability' => 'NEGLIGIBLE' },
+       { 'category' => 'HARM_CATEGORY_DANGEROUS_CONTENT', 'probability' => 'NEGLIGIBLE' }] }],
+   'usageMetadata' => {
+     'promptTokenCount' => 2,
+     'candidatesTokenCount' => 8,
+     'totalTokenCount' => 10
+   } }]
+```
+
+You can mix both as well:
+```ruby
+result = client.stream_generate_content(
+  { contents: { role: 'user', parts: { text: 'hi!' } } }
+) do |event, parsed, raw|
+  puts event
+end
+```
+
+#### generate_content
+
+```ruby
+result = client.generate_content(
+  { contents: { role: 'user', parts: { text: 'hi!' } } }
+)
+```
+
+Result:
+```ruby
+{ 'candidates' =>
+  [{ 'content' => { 'parts' => [{ 'text' => 'Hello! How can I assist you today?' }], 'role' => 'model' },
+     'finishReason' => 'STOP',
+     'index' => 0,
+     'safetyRatings' =>
+     [{ 'category' => 'HARM_CATEGORY_SEXUALLY_EXPLICIT', 'probability' => 'NEGLIGIBLE' },
+      { 'category' => 'HARM_CATEGORY_HATE_SPEECH', 'probability' => 'NEGLIGIBLE' },
+      { 'category' => 'HARM_CATEGORY_HARASSMENT', 'probability' => 'NEGLIGIBLE' },
+      { 'category' => 'HARM_CATEGORY_DANGEROUS_CONTENT', 'probability' => 'NEGLIGIBLE' }] }],
+  'promptFeedback' =>
+  { 'safetyRatings' =>
+    [{ 'category' => 'HARM_CATEGORY_SEXUALLY_EXPLICIT', 'probability' => 'NEGLIGIBLE' },
+     { 'category' => 'HARM_CATEGORY_HATE_SPEECH', 'probability' => 'NEGLIGIBLE' },
+     { 'category' => 'HARM_CATEGORY_HARASSMENT', 'probability' => 'NEGLIGIBLE' },
+     { 'category' => 'HARM_CATEGORY_DANGEROUS_CONTENT', 'probability' => 'NEGLIGIBLE' }] } }
+```
+
+As of the writing of this README, only the `generative-language-api` service supports the `generate_content` method; `vertex-ai-api` does not.
+
+### Modes
+
+#### Text
 
 ```ruby
 result = client.stream_generate_content({
@@ -334,7 +443,7 @@ Result:
    } }]
 ```
 
-##### Image
+#### Image
 
 ![A black and white image of an old piano. The piano is an upright model, with the keys on the right side of the image. The piano is sitting on a tiled floor. There is a small round object on the top of the piano.](https://raw.githubusercontent.com/gbaptista/assets/main/gemini-ai/piano.jpg)
 
@@ -345,7 +454,7 @@ Switch to the `gemini-pro-vision` model:
 ```ruby
 client = Gemini.new(
   credentials: { service: 'vertex-ai-api', region: 'us-east4' },
-  options: { model: 'gemini-pro-vision', stream: true }
+  options: { model: 'gemini-pro-vision', server_sent_events: true }
 )
 ```
 
@@ -391,7 +500,7 @@ The result:
    'usageMetadata' => { 'promptTokenCount' => 263, 'candidatesTokenCount' => 50, 'totalTokenCount' => 313 } }]
 ```
 
-##### Video
+#### Video
 
 https://gist.github.com/assets/29520/f82bccbf-02d2-4899-9c48-eb8a0a5ef741
 
@@ -404,7 +513,7 @@ Switch to the `gemini-pro-vision` model:
 ```ruby
 client = Gemini.new(
   credentials: { service: 'vertex-ai-api', region: 'us-east4' },
-  options: { model: 'gemini-pro-vision', stream: true }
+  options: { model: 'gemini-pro-vision', server_sent_events: true }
 )
 ```
 
@@ -451,41 +560,15 @@ The result:
   "usageMetadata"=>{"promptTokenCount"=>1037, "candidatesTokenCount"=>32, "totalTokenCount"=>1069}}]
 ```
 
-#### Synchronous
-
-```ruby
-result = client.stream_generate_content({
-  contents: { role: 'user', parts: { text: 'hi!' } }
-})
-```
-
-Result:
-```ruby
-[{ 'candidates' =>
-   [{ 'content' => {
-        'role' => 'model',
-        'parts' => [{ 'text' => 'Hello! How may I assist you?' }]
-      },
-      'finishReason' => 'STOP',
-      'safetyRatings' =>
-      [{ 'category' => 'HARM_CATEGORY_HARASSMENT', 'probability' => 'NEGLIGIBLE' },
-       { 'category' => 'HARM_CATEGORY_HATE_SPEECH', 'probability' => 'NEGLIGIBLE' },
-       { 'category' => 'HARM_CATEGORY_SEXUALLY_EXPLICIT', 'probability' => 'NEGLIGIBLE' },
-       { 'category' => 'HARM_CATEGORY_DANGEROUS_CONTENT', 'probability' => 'NEGLIGIBLE' }] }],
-   'usageMetadata' => {
-     'promptTokenCount' => 2,
-     'candidatesTokenCount' => 8,
-     'totalTokenCount' => 10
-   } }]
-```
+### Streaming vs. Server-Sent Events (SSE)
 
-#### Streaming
+[Server-Sent Events (SSE)](https://en.wikipedia.org/wiki/Server-sent_events) is a technology that allows certain endpoints to offer streaming capabilities, such as creating the impression that "the model is typing along with you," rather than delivering the entire answer all at once.
 
-You can set up the client to use streaming for all supported endpoints:
+You can set up the client to use Server-Sent Events (SSE) for all supported endpoints:
 ```ruby
 client = Gemini.new(
   credentials: { ... },
-  options: { model: 'gemini-pro', stream: true }
+  options: { model: 'gemini-pro', server_sent_events: true }
 )
 ```
 
@@ -493,11 +576,11 @@ Or, you can decide on a request basis:
 ```ruby
 client.stream_generate_content(
   { contents: { role: 'user', parts: { text: 'hi!' } } },
-  stream: true
+  server_sent_events: true
 )
 ```
 
-With streaming enabled, you can use a block to receive the results:
+With Server-Sent Events (SSE) enabled, you can use a block to receive partial results via events. This feature is particularly useful for methods that offer streaming capabilities, such as `stream_generate_content`:
 
 ```ruby
 client.stream_generate_content(
@@ -527,14 +610,16 @@ Event:
   } }
 ```
 
-#### Streaming Hang
+Even though streaming methods utilize Server-Sent Events (SSE), using this feature doesn't necessarily mean streaming data. For example, when `generate_content` is called with SSE enabled, you will receive all the data at once in a single event, rather than through multiple partial events. This occurs because `generate_content` isn't designed for streaming, even though it is capable of utilizing Server-Sent Events.
+
+#### Server-Sent Events (SSE) Hang
 
-Method calls will _hang_ until the stream finishes, so even without providing a block, you can get the final results of the stream events:
+Method calls will _hang_ until the server-sent events finish, so even without providing a block, you can obtain the final results of the received events:
 
 ```ruby
 result = client.stream_generate_content(
   { contents: { role: 'user', parts: { text: 'hi!' } } },
-  stream: true
+  server_sent_events: true
 )
 ```
 
@@ -558,7 +643,40 @@ Result:
    } }]
 ```
 
-#### Back-and-Forth Conversations
+#### Non-Streaming
+
+Depending on the service, you can use the [`generate_content`](#generate_content) method, which does not stream the answer.
+
+You can also use methods designed for streaming without necessarily processing partial events; instead, you can wait for the result of all received events:
+
+```ruby
+result = client.stream_generate_content({
+  contents: { role: 'user', parts: { text: 'hi!' } },
+  server_sent_events: false
+})
+```
+
+Result:
+```ruby
+[{ 'candidates' =>
+   [{ 'content' => {
+        'role' => 'model',
+        'parts' => [{ 'text' => 'Hello! How may I assist you?' }]
+      },
+      'finishReason' => 'STOP',
+      'safetyRatings' =>
+      [{ 'category' => 'HARM_CATEGORY_HARASSMENT', 'probability' => 'NEGLIGIBLE' },
+       { 'category' => 'HARM_CATEGORY_HATE_SPEECH', 'probability' => 'NEGLIGIBLE' },
+       { 'category' => 'HARM_CATEGORY_SEXUALLY_EXPLICIT', 'probability' => 'NEGLIGIBLE' },
+       { 'category' => 'HARM_CATEGORY_DANGEROUS_CONTENT', 'probability' => 'NEGLIGIBLE' }] }],
+   'usageMetadata' => {
+     'promptTokenCount' => 2,
+     'candidatesTokenCount' => 8,
+     'totalTokenCount' => 10
+   } }]
+```
+
+### Back-and-Forth Conversations
 
 To maintain a back-and-forth conversation, you need to append the received responses and build a history for your requests:
 
@@ -600,7 +718,7 @@ Result:
    } }]
 ```
 
-#### Tools (Functions) Calling
+### Tools (Functions) Calling
 
 > As of the writing of this README, only the `vertex-ai-api` service and the `gemini-pro` model [supports](https://cloud.google.com/vertex-ai/docs/generative-ai/multimodal/function-calling#supported_models) tools (functions) calls.
 
@@ -756,6 +874,42 @@ result = client.request(
 )
 ```
 
+### Request Options
+
+#### Timeout
+
+You can set the maximum number of seconds to wait for the request to complete with the `timeout` option:
+
+```ruby
+client = Gemini.new(
+  credentials: { service: 'vertex-ai-api', region: 'us-east4' },
+  options: {
+    model: 'gemini-pro',
+    connection: { request: { timeout: 5 } }
+  }
+)
+```
+
+You can also have more fine-grained control over [Faraday's Request Options](https://lostisland.github.io/faraday/#/customization/request-options?id=request-options) if you prefer:
+
+```ruby
+client = Gemini.new(
+  credentials: { service: 'vertex-ai-api', region: 'us-east4' },
+  options: {
+    model: 'gemini-pro',
+    connection: {
+      request: {
+        timeout: 5,
+        open_timeout: 5,
+        read_timeout: 5,
+        write_timeout: 5
+      }
+    }
+  }
+)
+```
+
+
 ### Error Handling
 
 #### Rescuing
@@ -803,7 +957,7 @@ GeminiError
 
 MissingProjectIdError
 UnsupportedServiceError
-BlockWithoutStreamError
+BlockWithoutServerSentEventsError
 
 RequestError
 ```
@@ -826,7 +980,7 @@ gem build gemini-ai.gemspec
 
 gem signin
 
-gem push gemini-ai-2.2.0.gem
+gem push gemini-ai-3.1.0.gem
 ```
 
 ### Updating the README

data/components/errors.rb

@@ -10,7 +10,7 @@ module Gemini
 
     class MissingProjectIdError < GeminiError; end
     class UnsupportedServiceError < GeminiError; end
-    class BlockWithoutStreamError < GeminiError; end
+    class BlockWithoutServerSentEventsError < GeminiError; end
 
     class RequestError < GeminiError
       attr_reader :request, :payload

data/controllers/client.rb

@@ -5,11 +5,13 @@ require 'faraday'
 require 'json'
 require 'googleauth'
 
-require_relative '../components/errors'
+require_relative '../ports/dsl/gemini-ai/errors'
 
 module Gemini
   module Controllers
     class Client
+      ALLOWED_REQUEST_OPTIONS = %i[timeout open_timeout read_timeout write_timeout].freeze
+
       def initialize(config)
         if config[:credentials][:api_key]
           @authentication = :api_key
@@ -26,49 +28,67 @@ module Gemini
         end
 
         if @authentication == :service_account || @authentication == :default_credentials
-          @project_id = if config[:credentials][:project_id].nil?
-                          @authorizer.project_id || @authorizer.quota_project_id
-                        else
-                          config[:credentials][:project_id]
-                        end
+          @project_id = config[:credentials][:project_id] || @authorizer.project_id || @authorizer.quota_project_id
 
           raise MissingProjectIdError, 'Could not determine project_id, which is required.' if @project_id.nil?
         end
 
-        @address = case config[:credentials][:service]
+        @service = config[:credentials][:service]
+
+        @address = case @service
                    when 'vertex-ai-api'
                      "https://#{config[:credentials][:region]}-aiplatform.googleapis.com/v1/projects/#{@project_id}/locations/#{config[:credentials][:region]}/publishers/google/models/#{config[:options][:model]}"
                    when 'generative-language-api'
                      "https://generativelanguage.googleapis.com/v1/models/#{config[:options][:model]}"
                    else
-                     raise UnsupportedServiceError, "Unsupported service: #{config[:credentials][:service]}"
+                     raise UnsupportedServiceError, "Unsupported service: #{@service}"
                    end
 
-        @stream = config[:options][:stream]
+        @server_sent_events = config[:options][:server_sent_events]
+
+        @request_options = config.dig(:options, :connection, :request)
+
+        @request_options = if @request_options.is_a?(Hash)
+                             @request_options.select do |key, _|
+                               ALLOWED_REQUEST_OPTIONS.include?(key)
+                             end
+                           else
+                             {}
+                           end
       end
 
-      def stream_generate_content(payload, stream: nil, &callback)
-        request('streamGenerateContent', payload, stream:, &callback)
+      def stream_generate_content(payload, server_sent_events: nil, &callback)
+        request('streamGenerateContent', payload, server_sent_events:, &callback)
+      end
+
+      def generate_content(payload, server_sent_events: nil, &callback)
+        result = request('generateContent', payload, server_sent_events:, &callback)
+
+        return result.first if result.is_a?(Array) && result.size == 1
+
+        result
       end
 
-      def request(path, payload, stream: nil, &callback)
-        stream_enabled = stream.nil? ? @stream : stream
+      def request(path, payload, server_sent_events: nil, &callback)
+        server_sent_events_enabled = server_sent_events.nil? ? @server_sent_events : server_sent_events
         url = "#{@address}:#{path}"
         params = []
 
-        params << 'alt=sse' if stream_enabled
+        params << 'alt=sse' if server_sent_events_enabled
         params << "key=#{@api_key}" if @authentication == :api_key
 
         url += "?#{params.join('&')}" if params.size.positive?
 
-        if !callback.nil? && !stream_enabled
-          raise BlockWithoutStreamError, 'You are trying to use a block without stream enabled.'
+        if !callback.nil? && !server_sent_events_enabled
+          raise BlockWithoutServerSentEventsError,
+                'You are trying to use a block without Server Sent Events (SSE) enabled.'
         end
 
         results = []
 
-        response = Faraday.new do |faraday|
+        response = Faraday.new(request: @request_options) do |faraday|
           faraday.response :raise_error
+          faraday.options.timeout = @timeout if @timeout
         end.post do |request|
           request.url url
           request.headers['Content-Type'] = 'application/json'
@@ -78,7 +98,7 @@ module Gemini
 
           request.body = payload.to_json
 
-          if stream_enabled
+          if server_sent_events_enabled
             parser = EventStreamParser::Parser.new
 
             request.options.on_data = proc do |chunk, bytes, env|
@@ -107,7 +127,7 @@ module Gemini
           end
         end
 
-        return safe_parse_json(response.body) unless stream_enabled
+        return safe_parse_json(response.body) unless server_sent_events_enabled
 
         results.map { |result| result[:event] }
       rescue Faraday::ServerError => e

data/gemini-ai.gemspec

@@ -30,7 +30,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ['ports/dsl']
 
   spec.add_dependency 'event_stream_parser', '~> 1.0'
-  spec.add_dependency 'faraday', '~> 2.7', '>= 2.7.12'
+  spec.add_dependency 'faraday', '~> 2.8', '>= 2.8.1'
   spec.add_dependency 'googleauth', '~> 1.9', '>= 1.9.1'
 
   spec.metadata['rubygems_mfa_required'] = 'true'

data/static/gem.rb

@@ -3,7 +3,7 @@
 module Gemini
   GEM = {
     name: 'gemini-ai',
-    version: '2.2.0',
+    version: '3.1.0',
     author: 'gbaptista',
     summary: "Interact with Google's Gemini AI.",
     description: "A Ruby Gem for interacting with Gemini through Vertex AI, Generative Language API, or AI Studio, Google's generative AI services.",

data/tasks/generate-readme.clj

@@ -4,7 +4,7 @@
   (-> text
       (clojure.string/lower-case)
       (clojure.string/replace " " "-")
-      (clojure.string/replace #"[^a-z0-9\-]" "")))
+      (clojure.string/replace #"[^a-z0-9\-_]" "")))
 
 (defn remove-code-blocks [content]
   (let [code-block-regex #"(?s)```.*?```"]

data/template.md

@@ -9,7 +9,7 @@ A Ruby Gem for interacting with [Gemini](https://deepmind.google/technologies/ge
 ## TL;DR and Quick Start
 
 ```ruby
-gem 'gemini-ai', '~> 2.2.0'
+gem 'gemini-ai', '~> 3.1.0'
 ```
 
 ```ruby
@@ -21,7 +21,7 @@ client = Gemini.new(
     service: 'generative-language-api',
     api_key: ENV['GOOGLE_API_KEY']
   },
-  options: { model: 'gemini-pro', stream: false }
+  options: { model: 'gemini-pro', server_sent_events: true }
 )
 
 # With a Service Account Credentials File
@@ -31,7 +31,7 @@ client = Gemini.new(
     file_path: 'google-credentials.json',
     region: 'us-east4'
   },
-  options: { model: 'gemini-pro', stream: false }
+  options: { model: 'gemini-pro', server_sent_events: true }
 )
 
 # With Application Default Credentials
@@ -40,7 +40,7 @@ client = Gemini.new(
     service: 'vertex-ai-api',
     region: 'us-east4'
   },
-  options: { model: 'gemini-pro', stream: false }
+  options: { model: 'gemini-pro', server_sent_events: true }
 )
 
 result = client.stream_generate_content({
@@ -77,11 +77,11 @@ Result:
 ### Installing
 
 ```sh
-gem install gemini-ai -v 2.2.0
+gem install gemini-ai -v 3.1.0
 ```
 
 ```sh
-gem 'gemini-ai', '~> 2.2.0'
+gem 'gemini-ai', '~> 3.1.0'
 ```
 
 ### Credentials
@@ -248,7 +248,7 @@ client = Gemini.new(
     service: 'generative-language-api',
     api_key: ENV['GOOGLE_API_KEY']
   },
-  options: { model: 'gemini-pro', stream: false }
+  options: { model: 'gemini-pro', server_sent_events: true }
 )
 
 # With a Service Account Credentials File
@@ -258,7 +258,7 @@ client = Gemini.new(
     file_path: 'google-credentials.json',
     region: 'us-east4'
   },
-  options: { model: 'gemini-pro', stream: false }
+  options: { model: 'gemini-pro', server_sent_events: true }
 )
 
 # With Application Default Credentials
@@ -267,15 +267,118 @@ client = Gemini.new(
     service: 'vertex-ai-api',
     region: 'us-east4'
   },
-  options: { model: 'gemini-pro', stream: false }
+  options: { model: 'gemini-pro', server_sent_events: true }
 )
 ```
 
-### Generate Content
+### Methods
 
-#### Modes
+#### stream_generate_content
 
-##### Text
+##### Receiving Stream Events
+
+Ensure that you have enabled [Server-Sent Events](#streaming-vs-server-sent-events-sse) before using blocks for streaming:
+
+```ruby
+client.stream_generate_content(
+  { contents: { role: 'user', parts: { text: 'hi!' } } }
+) do |event, parsed, raw|
+  puts event
+end
+```
+
+Event:
+```ruby
+{ 'candidates' =>
+  [{ 'content' => {
+       'role' => 'model',
+       'parts' => [{ 'text' => 'Hello! How may I assist you?' }]
+     },
+     'finishReason' => 'STOP',
+     'safetyRatings' =>
+     [{ 'category' => 'HARM_CATEGORY_HARASSMENT', 'probability' => 'NEGLIGIBLE' },
+      { 'category' => 'HARM_CATEGORY_HATE_SPEECH', 'probability' => 'NEGLIGIBLE' },
+      { 'category' => 'HARM_CATEGORY_SEXUALLY_EXPLICIT', 'probability' => 'NEGLIGIBLE' },
+      { 'category' => 'HARM_CATEGORY_DANGEROUS_CONTENT', 'probability' => 'NEGLIGIBLE' }] }],
+  'usageMetadata' => {
+    'promptTokenCount' => 2,
+    'candidatesTokenCount' => 8,
+    'totalTokenCount' => 10
+  } }
+```
+
+##### Without Events
+
+You can use `stream_generate_content` without events:
+
+```ruby
+result = client.stream_generate_content(
+  { contents: { role: 'user', parts: { text: 'hi!' } } }
+)
+```
+
+In this case, the result will be an array with all the received events:
+
+```ruby
+[{ 'candidates' =>
+   [{ 'content' => {
+        'role' => 'model',
+        'parts' => [{ 'text' => 'Hello! How may I assist you?' }]
+      },
+      'finishReason' => 'STOP',
+      'safetyRatings' =>
+      [{ 'category' => 'HARM_CATEGORY_HARASSMENT', 'probability' => 'NEGLIGIBLE' },
+       { 'category' => 'HARM_CATEGORY_HATE_SPEECH', 'probability' => 'NEGLIGIBLE' },
+       { 'category' => 'HARM_CATEGORY_SEXUALLY_EXPLICIT', 'probability' => 'NEGLIGIBLE' },
+       { 'category' => 'HARM_CATEGORY_DANGEROUS_CONTENT', 'probability' => 'NEGLIGIBLE' }] }],
+   'usageMetadata' => {
+     'promptTokenCount' => 2,
+     'candidatesTokenCount' => 8,
+     'totalTokenCount' => 10
+   } }]
+```
+
+You can mix both as well:
+```ruby
+result = client.stream_generate_content(
+  { contents: { role: 'user', parts: { text: 'hi!' } } }
+) do |event, parsed, raw|
+  puts event
+end
+```
+
+#### generate_content
+
+```ruby
+result = client.generate_content(
+  { contents: { role: 'user', parts: { text: 'hi!' } } }
+)
+```
+
+Result:
+```ruby
+{ 'candidates' =>
+  [{ 'content' => { 'parts' => [{ 'text' => 'Hello! How can I assist you today?' }], 'role' => 'model' },
+     'finishReason' => 'STOP',
+     'index' => 0,
+     'safetyRatings' =>
+     [{ 'category' => 'HARM_CATEGORY_SEXUALLY_EXPLICIT', 'probability' => 'NEGLIGIBLE' },
+      { 'category' => 'HARM_CATEGORY_HATE_SPEECH', 'probability' => 'NEGLIGIBLE' },
+      { 'category' => 'HARM_CATEGORY_HARASSMENT', 'probability' => 'NEGLIGIBLE' },
+      { 'category' => 'HARM_CATEGORY_DANGEROUS_CONTENT', 'probability' => 'NEGLIGIBLE' }] }],
+  'promptFeedback' =>
+  { 'safetyRatings' =>
+    [{ 'category' => 'HARM_CATEGORY_SEXUALLY_EXPLICIT', 'probability' => 'NEGLIGIBLE' },
+     { 'category' => 'HARM_CATEGORY_HATE_SPEECH', 'probability' => 'NEGLIGIBLE' },
+     { 'category' => 'HARM_CATEGORY_HARASSMENT', 'probability' => 'NEGLIGIBLE' },
+     { 'category' => 'HARM_CATEGORY_DANGEROUS_CONTENT', 'probability' => 'NEGLIGIBLE' }] } }
+```
+
+As of the writing of this README, only the `generative-language-api` service supports the `generate_content` method; `vertex-ai-api` does not.
+
+### Modes
+
+#### Text
 
 ```ruby
 result = client.stream_generate_content({
@@ -303,7 +406,7 @@ Result:
    } }]
 ```
 
-##### Image
+#### Image
 
 ![A black and white image of an old piano. The piano is an upright model, with the keys on the right side of the image. The piano is sitting on a tiled floor. There is a small round object on the top of the piano.](https://raw.githubusercontent.com/gbaptista/assets/main/gemini-ai/piano.jpg)
 
@@ -314,7 +417,7 @@ Switch to the `gemini-pro-vision` model:
 ```ruby
 client = Gemini.new(
   credentials: { service: 'vertex-ai-api', region: 'us-east4' },
-  options: { model: 'gemini-pro-vision', stream: true }
+  options: { model: 'gemini-pro-vision', server_sent_events: true }
 )
 ```
 
@@ -360,7 +463,7 @@ The result:
    'usageMetadata' => { 'promptTokenCount' => 263, 'candidatesTokenCount' => 50, 'totalTokenCount' => 313 } }]
 ```
 
-##### Video
+#### Video
 
 https://gist.github.com/assets/29520/f82bccbf-02d2-4899-9c48-eb8a0a5ef741
 
@@ -373,7 +476,7 @@ Switch to the `gemini-pro-vision` model:
 ```ruby
 client = Gemini.new(
   credentials: { service: 'vertex-ai-api', region: 'us-east4' },
-  options: { model: 'gemini-pro-vision', stream: true }
+  options: { model: 'gemini-pro-vision', server_sent_events: true }
 )
 ```
 
@@ -420,41 +523,15 @@ The result:
   "usageMetadata"=>{"promptTokenCount"=>1037, "candidatesTokenCount"=>32, "totalTokenCount"=>1069}}]
 ```
 
-#### Synchronous
-
-```ruby
-result = client.stream_generate_content({
-  contents: { role: 'user', parts: { text: 'hi!' } }
-})
-```
-
-Result:
-```ruby
-[{ 'candidates' =>
-   [{ 'content' => {
-        'role' => 'model',
-        'parts' => [{ 'text' => 'Hello! How may I assist you?' }]
-      },
-      'finishReason' => 'STOP',
-      'safetyRatings' =>
-      [{ 'category' => 'HARM_CATEGORY_HARASSMENT', 'probability' => 'NEGLIGIBLE' },
-       { 'category' => 'HARM_CATEGORY_HATE_SPEECH', 'probability' => 'NEGLIGIBLE' },
-       { 'category' => 'HARM_CATEGORY_SEXUALLY_EXPLICIT', 'probability' => 'NEGLIGIBLE' },
-       { 'category' => 'HARM_CATEGORY_DANGEROUS_CONTENT', 'probability' => 'NEGLIGIBLE' }] }],
-   'usageMetadata' => {
-     'promptTokenCount' => 2,
-     'candidatesTokenCount' => 8,
-     'totalTokenCount' => 10
-   } }]
-```
+### Streaming vs. Server-Sent Events (SSE)
 
-#### Streaming
+[Server-Sent Events (SSE)](https://en.wikipedia.org/wiki/Server-sent_events) is a technology that allows certain endpoints to offer streaming capabilities, such as creating the impression that "the model is typing along with you," rather than delivering the entire answer all at once.
 
-You can set up the client to use streaming for all supported endpoints:
+You can set up the client to use Server-Sent Events (SSE) for all supported endpoints:
 ```ruby
 client = Gemini.new(
   credentials: { ... },
-  options: { model: 'gemini-pro', stream: true }
+  options: { model: 'gemini-pro', server_sent_events: true }
 )
 ```
 
@@ -462,11 +539,11 @@ Or, you can decide on a request basis:
 ```ruby
 client.stream_generate_content(
   { contents: { role: 'user', parts: { text: 'hi!' } } },
-  stream: true
+  server_sent_events: true
 )
 ```
 
-With streaming enabled, you can use a block to receive the results:
+With Server-Sent Events (SSE) enabled, you can use a block to receive partial results via events. This feature is particularly useful for methods that offer streaming capabilities, such as `stream_generate_content`:
 
 ```ruby
 client.stream_generate_content(
@@ -496,14 +573,16 @@ Event:
   } }
 ```
 
-#### Streaming Hang
+Even though streaming methods utilize Server-Sent Events (SSE), using this feature doesn't necessarily mean streaming data. For example, when `generate_content` is called with SSE enabled, you will receive all the data at once in a single event, rather than through multiple partial events. This occurs because `generate_content` isn't designed for streaming, even though it is capable of utilizing Server-Sent Events.
+
+#### Server-Sent Events (SSE) Hang
 
-Method calls will _hang_ until the stream finishes, so even without providing a block, you can get the final results of the stream events:
+Method calls will _hang_ until the server-sent events finish, so even without providing a block, you can obtain the final results of the received events:
 
 ```ruby
 result = client.stream_generate_content(
   { contents: { role: 'user', parts: { text: 'hi!' } } },
-  stream: true
+  server_sent_events: true
 )
 ```
 
@@ -527,7 +606,40 @@ Result:
    } }]
 ```
 
-#### Back-and-Forth Conversations
+#### Non-Streaming
+
+Depending on the service, you can use the [`generate_content`](#generate_content) method, which does not stream the answer.
+
+You can also use methods designed for streaming without necessarily processing partial events; instead, you can wait for the result of all received events:
+
+```ruby
+result = client.stream_generate_content({
+  contents: { role: 'user', parts: { text: 'hi!' } },
+  server_sent_events: false
+})
+```
+
+Result:
+```ruby
+[{ 'candidates' =>
+   [{ 'content' => {
+        'role' => 'model',
+        'parts' => [{ 'text' => 'Hello! How may I assist you?' }]
+      },
+      'finishReason' => 'STOP',
+      'safetyRatings' =>
+      [{ 'category' => 'HARM_CATEGORY_HARASSMENT', 'probability' => 'NEGLIGIBLE' },
+       { 'category' => 'HARM_CATEGORY_HATE_SPEECH', 'probability' => 'NEGLIGIBLE' },
+       { 'category' => 'HARM_CATEGORY_SEXUALLY_EXPLICIT', 'probability' => 'NEGLIGIBLE' },
+       { 'category' => 'HARM_CATEGORY_DANGEROUS_CONTENT', 'probability' => 'NEGLIGIBLE' }] }],
+   'usageMetadata' => {
+     'promptTokenCount' => 2,
+     'candidatesTokenCount' => 8,
+     'totalTokenCount' => 10
+   } }]
+```
+
+### Back-and-Forth Conversations
 
 To maintain a back-and-forth conversation, you need to append the received responses and build a history for your requests:
 
@@ -569,7 +681,7 @@ Result:
    } }]
 ```
 
-#### Tools (Functions) Calling
+### Tools (Functions) Calling
 
 > As of the writing of this README, only the `vertex-ai-api` service and the `gemini-pro` model [supports](https://cloud.google.com/vertex-ai/docs/generative-ai/multimodal/function-calling#supported_models) tools (functions) calls.
 
@@ -725,6 +837,42 @@ result = client.request(
 )
 ```
 
+### Request Options
+
+#### Timeout
+
+You can set the maximum number of seconds to wait for the request to complete with the `timeout` option:
+
+```ruby
+client = Gemini.new(
+  credentials: { service: 'vertex-ai-api', region: 'us-east4' },
+  options: {
+    model: 'gemini-pro',
+    connection: { request: { timeout: 5 } }
+  }
+)
+```
+
+You can also have more fine-grained control over [Faraday's Request Options](https://lostisland.github.io/faraday/#/customization/request-options?id=request-options) if you prefer:
+
+```ruby
+client = Gemini.new(
+  credentials: { service: 'vertex-ai-api', region: 'us-east4' },
+  options: {
+    model: 'gemini-pro',
+    connection: {
+      request: {
+        timeout: 5,
+        open_timeout: 5,
+        read_timeout: 5,
+        write_timeout: 5
+      }
+    }
+  }
+)
+```
+
+
 ### Error Handling
 
 #### Rescuing
@@ -772,7 +920,7 @@ GeminiError
 
 MissingProjectIdError
 UnsupportedServiceError
-BlockWithoutStreamError
+BlockWithoutServerSentEventsError
 
 RequestError
 ```
@@ -795,7 +943,7 @@ gem build gemini-ai.gemspec
 
 gem signin
 
-gem push gemini-ai-2.2.0.gem
+gem push gemini-ai-3.1.0.gem
 ```
 
 ### Updating the README

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gemini-ai
 version: !ruby/object:Gem::Version
-  version: 2.2.0
+  version: 3.1.0
 platform: ruby
 authors:
 - gbaptista
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-12-16 00:00:00.000000000 Z
+date: 2023-12-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: event_stream_parser
@@ -30,20 +30,20 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.7'
+        version: '2.8'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.7.12
+        version: 2.8.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.7'
+        version: '2.8'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.7.12
+        version: 2.8.1
 - !ruby/object:Gem::Dependency
   name: googleauth
   requirement: !ruby/object:Gem::Requirement