gemini-ai 2.2.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c7c5bd6e6cd1d2195b7a437fb0664cd553dc0acbf0d293042d93c3d701e6b6e0
-  data.tar.gz: 665458cc152b00efae9f8e2b730fe000ef2caac63f835944c1e76a83b9a0e627
+  metadata.gz: 80621f6cd2de526141e994a339d645b53492f6ece960955bc56f2e7430be1d0c
+  data.tar.gz: b627386a0dacc899112e0b08806f63b571dd980f2fb749df7681d7c70656d707
 SHA512:
-  metadata.gz: 0ca1f3f87c61276902259d937f4d57f324a756d1e63c1e5781680ba970313f3c3c29a2da49c4eb1ec0bf351f984bee378e86b22d1656b2423638e1a70bd5dddf
-  data.tar.gz: 50988d0881d37f561e0c75ac1beea4fc9b34c757d0f16fb2dcb2f63d3e63f867194e0f826800c8429ce9f33500dd74c3fa4c5d747a0975378c81cf3e0ad4a61b
+  metadata.gz: f5425c3239dac6eca23cccdb2483f90bea23500b0830b865e8acc0fe235cf2ad3cb001d110e7a6ec0cbb59ed5c2f65e74f883edef961cb675b76e7d6117d88fc
+  data.tar.gz: 041122dc5a6d1d596411ea697503aa8d7846b4d2bc6c493b8b7d9102033c9ef3226957340d8caeb443751f9f4f465624a80ef1749e0f5893833e4c72d43ba907

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    gemini-ai (2.2.0)
+    gemini-ai (3.0.0)
       event_stream_parser (~> 1.0)
       faraday (~> 2.7, >= 2.7.12)
       googleauth (~> 1.9, >= 1.9.1)

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.0.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,16 +81,20 @@ 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)
     - [Error Handling](#error-handling)
         - [Rescuing](#rescuing)
@@ -108,11 +112,11 @@ Result:
 ### Installing
 
 ```sh
-gem install gemini-ai -v 2.2.0
+gem install gemini-ai -v 3.0.0
 ```
 
 ```sh
-gem 'gemini-ai', '~> 2.2.0'
+gem 'gemini-ai', '~> 3.0.0'
 ```
 
 ### Credentials
@@ -279,7 +283,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 +293,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 +302,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 +441,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 +452,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 +498,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 +511,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 +558,15 @@ The result:
   "usageMetadata"=>{"promptTokenCount"=>1037, "candidatesTokenCount"=>32, "totalTokenCount"=>1069}}]
 ```
 
-#### Synchronous
+### Streaming vs. Server-Sent Events (SSE)
 
-```ruby
-result = client.stream_generate_content({
-  contents: { role: 'user', parts: { text: 'hi!' } }
-})
-```
+[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.
 
-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
-
-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 +574,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 +608,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.
 
-Method calls will _hang_ until the stream finishes, so even without providing a block, you can get the final results of the stream events:
+#### Server-Sent Events (SSE) Hang
+
+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 +641,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 +716,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.
 
@@ -803,7 +919,7 @@ GeminiError
 
 MissingProjectIdError
 UnsupportedServiceError
-BlockWithoutStreamError
+BlockWithoutServerSentEventsError
 
 RequestError
 ```
@@ -826,7 +942,7 @@ gem build gemini-ai.gemspec
 
 gem signin
 
-gem push gemini-ai-2.2.0.gem
+gem push gemini-ai-3.0.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,7 +5,7 @@ require 'faraday'
 require 'json'
 require 'googleauth'
 
-require_relative '../components/errors'
+require_relative '../ports/dsl/gemini-ai/errors'
 
 module Gemini
   module Controllers
@@ -26,43 +26,50 @@ 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]
+      end
+
+      def stream_generate_content(payload, server_sent_events: nil, &callback)
+        request('streamGenerateContent', payload, server_sent_events:, &callback)
       end
 
-      def stream_generate_content(payload, stream: nil, &callback)
-        request('streamGenerateContent', payload, stream:, &callback)
+      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 = []
@@ -78,7 +85,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 +114,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/static/gem.rb

@@ -3,7 +3,7 @@
 module Gemini
   GEM = {
     name: 'gemini-ai',
-    version: '2.2.0',
+    version: '3.0.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.0.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.0.0
 ```
 
 ```sh
-gem 'gemini-ai', '~> 2.2.0'
+gem 'gemini-ai', '~> 3.0.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
+### Streaming vs. Server-Sent Events (SSE)
 
-```ruby
-result = client.stream_generate_content({
-  contents: { role: 'user', parts: { text: 'hi!' } }
-})
-```
+[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.
 
-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
-
-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.
 
-Method calls will _hang_ until the stream finishes, so even without providing a block, you can get the final results of the stream events:
+#### Server-Sent Events (SSE) Hang
+
+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.
 
@@ -772,7 +884,7 @@ GeminiError
 
 MissingProjectIdError
 UnsupportedServiceError
-BlockWithoutStreamError
+BlockWithoutServerSentEventsError
 
 RequestError
 ```
@@ -795,7 +907,7 @@ gem build gemini-ai.gemspec
 
 gem signin
 
-gem push gemini-ai-2.2.0.gem
+gem push gemini-ai-3.0.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.0.0
 platform: ruby
 authors:
 - gbaptista
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-12-16 00:00:00.000000000 Z
+date: 2023-12-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: event_stream_parser
@@ -109,7 +109,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.3
+rubygems_version: 3.4.22
 signing_key: 
 specification_version: 4
 summary: Interact with Google's Gemini AI.