gemini-ai 2.1.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3c6743cedf074b42aed890203de2d5db7697b6302c349c66bae9ac538bf2c680
-  data.tar.gz: ad0c8dd1ba69f58c0e37ed170bbd758231adea02245a63eb10fffa9a57fa2400
+  metadata.gz: c7c5bd6e6cd1d2195b7a437fb0664cd553dc0acbf0d293042d93c3d701e6b6e0
+  data.tar.gz: 665458cc152b00efae9f8e2b730fe000ef2caac63f835944c1e76a83b9a0e627
 SHA512:
-  metadata.gz: 558e2a13c12931f6bfbde1d625cb38b7779e08d8eb5bc0a845861902f50fbcbc43b64c67348220f35316b4a37504daa220c334b0479fb5493973bc49ab34e77c
-  data.tar.gz: 2df9f463de540a3d76f86252bd178ca5638caca7e172d59ea244f5f12d04c86d22dcbe2e219049a33ad318ffecc9aaff07c28ffe30aa69ebc109befa08acbcca
+  metadata.gz: 0ca1f3f87c61276902259d937f4d57f324a756d1e63c1e5781680ba970313f3c3c29a2da49c4eb1ec0bf351f984bee378e86b22d1656b2423638e1a70bd5dddf
+  data.tar.gz: 50988d0881d37f561e0c75ac1beea4fc9b34c757d0f16fb2dcb2f63d3e63f867194e0f826800c8429ce9f33500dd74c3fa4c5d747a0975378c81cf3e0ad4a61b

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    gemini-ai (2.1.0)
+    gemini-ai (2.2.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.1.0'
+gem 'gemini-ai', '~> 2.2.0'
 ```
 
 ```ruby
@@ -82,12 +82,20 @@ Result:
 - [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)
+        - [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)
+        - [For Short](#for-short)
+        - [Errors](#errors)
 - [Development](#development)
     - [Purpose](#purpose)
     - [Publish to RubyGems](#publish-to-rubygems)
@@ -100,15 +108,20 @@ Result:
 ### Installing
 
 ```sh
-gem install gemini-ai -v 2.1.0
+gem install gemini-ai -v 2.2.0
 ```
 
 ```sh
-gem 'gemini-ai', '~> 2.1.0'
+gem 'gemini-ai', '~> 2.2.0'
 ```
 
 ### Credentials
 
+- [Option 1: API Key (Generative Language API)](#option-1-api-key-generative-language-api)
+- [Option 2: Service Account Credentials File (Vertex AI API)](#option-2-service-account-credentials-file-vertex-ai-api)
+- [Option 3: Application Default Credentials (Vertex AI API)](#option-3-application-default-credentials-vertex-ai-api)
+- [Required Data](#required-data)
+
 > ⚠️ DISCLAIMER: Be careful with what you are doing, and never trust others' code related to this. These commands and instructions alter the level of access to your Google Cloud Account, and running them naively can lead to security risks as well as financial risks. People with access to your account can use it to steal data or incur charges. Run these commands at your own responsibility and due diligence; expect no warranties from the contributors of this project.
 
 #### Option 1: API Key (Generative Language API)
@@ -291,6 +304,153 @@ client = Gemini.new(
 
 ### Generate Content
 
+#### Modes
+
+##### Text
+
+```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
+   } }]
+```
+
+##### 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)
+
+> _Courtesy of [Unsplash](https://unsplash.com/photos/greyscale-photo-of-grand-piano-czPs0z3-Ggg)_
+
+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 }
+)
+```
+
+Then, encode the image as [Base64](https://en.wikipedia.org/wiki/Base64) and add its [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types):
+
+```ruby
+require 'base64'
+
+result = client.stream_generate_content(
+  { contents: [
+    { role: 'user', parts: [
+      { text: 'Please describe this image.' },
+      { inline_data: {
+        mime_type: 'image/jpeg',
+        data: Base64.strict_encode64(File.read('piano.jpg'))
+      } }
+    ] }
+  ] }
+)
+```
+
+The result:
+```ruby
+[{ 'candidates' =>
+   [{ 'content' =>
+      { 'role' => 'model',
+        'parts' =>
+        [{ 'text' =>
+           ' 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' }] },
+      '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' }] }] },
+ { 'candidates' =>
+   [{ 'content' => { 'role' => 'model', 'parts' => [{ 'text' => ' sitting on a tiled floor. There is a small round object on the top of the piano.' }] },
+      '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' => 263, 'candidatesTokenCount' => 50, 'totalTokenCount' => 313 } }]
+```
+
+##### Video
+
+https://gist.github.com/assets/29520/f82bccbf-02d2-4899-9c48-eb8a0a5ef741
+
+> ALT: A white and gold cup is being filled with coffee. The coffee is dark and rich. The cup is sitting on a black surface. The background is blurred.
+
+> _Courtesy of [Pexels](https://www.pexels.com/video/pouring-of-coffee-855391/)_
+
+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 }
+)
+```
+
+Then, encode the video as [Base64](https://en.wikipedia.org/wiki/Base64) and add its [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types):
+
+```ruby
+require 'base64'
+
+result = client.stream_generate_content(
+  { contents: [
+    { role: 'user', parts: [
+      { text: 'Please describe this video.' },
+      { inline_data: {
+        mime_type: 'video/mp4',
+        data: Base64.strict_encode64(File.read('coffee.mp4'))
+      } }
+    ] }
+  ] }
+)
+```
+
+The result:
+```ruby
+[{"candidates"=>
+   [{"content"=>
+      {"role"=>"model",
+       "parts"=>
+        [{"text"=>
+           " A white and gold cup is being filled with coffee. The coffee is dark and rich. The cup is sitting on a black surface. The background is blurred"}]},
+     "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"=>1037, "candidatesTokenCount"=>31, "totalTokenCount"=>1068}},
+ {"candidates"=>
+   [{"content"=>{"role"=>"model", "parts"=>[{"text"=>"."}]},
+     "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"=>1037, "candidatesTokenCount"=>32, "totalTokenCount"=>1069}}]
+```
+
 #### Synchronous
 
 ```ruby
@@ -398,7 +558,7 @@ Result:
    } }]
 ```
 
-### Back-and-Forth Conversations
+#### 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:
 
@@ -440,7 +600,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.
 
@@ -596,6 +756,58 @@ result = client.request(
 )
 ```
 
+### Error Handling
+
+#### Rescuing
+
+```ruby
+require 'gemini-ai'
+
+begin
+  client.stream_generate_content({
+    contents: { role: 'user', parts: { text: 'hi!' } }
+  })
+rescue Gemini::Errors::GeminiError => error
+  puts error.class # Gemini::Errors::RequestError
+  puts error.message # 'the server responded with status 500'
+
+  puts error.payload
+  # { contents: [{ role: 'user', parts: { text: 'hi!' } }],
+  #   generationConfig: { candidateCount: 1 },
+  #   ...
+  # }
+
+  puts error.request
+  # #<Faraday::ServerError response={:status=>500, :headers...
+end
+```
+
+#### For Short
+
+```ruby
+require 'gemini-ai/errors'
+
+begin
+  client.stream_generate_content({
+    contents: { role: 'user', parts: { text: 'hi!' } }
+  })
+rescue GeminiError => error
+  puts error.class # Gemini::Errors::RequestError
+end
+```
+
+#### Errors
+
+```ruby
+GeminiError
+
+MissingProjectIdError
+UnsupportedServiceError
+BlockWithoutStreamError
+
+RequestError
+```
+
 ## Development
 
 ```bash
@@ -614,7 +826,7 @@ gem build gemini-ai.gemspec
 
 gem signin
 
-gem push gemini-ai-2.1.0.gem
+gem push gemini-ai-2.2.0.gem
 ```
 
 ### Updating the README

data/components/errors.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Gemini
+  module Errors
+    class GeminiError < StandardError
+      def initialize(message = nil)
+        super(message)
+      end
+    end
+
+    class MissingProjectIdError < GeminiError; end
+    class UnsupportedServiceError < GeminiError; end
+    class BlockWithoutStreamError < GeminiError; end
+
+    class RequestError < GeminiError
+      attr_reader :request, :payload
+
+      def initialize(message = nil, request: nil, payload: nil)
+        @request = request
+        @payload = payload
+
+        super(message)
+      end
+    end
+  end
+end

data/controllers/client.rb

@@ -5,6 +5,8 @@ require 'faraday'
 require 'json'
 require 'googleauth'
 
+require_relative '../components/errors'
+
 module Gemini
   module Controllers
     class Client
@@ -30,7 +32,7 @@ module Gemini
                           config[:credentials][:project_id]
                         end
 
-          raise StandardError, 'Could not determine project_id, which is required.' if @project_id.nil?
+          raise MissingProjectIdError, 'Could not determine project_id, which is required.' if @project_id.nil?
         end
 
         @address = case config[:credentials][:service]
@@ -39,7 +41,7 @@ module Gemini
                    when 'generative-language-api'
                      "https://generativelanguage.googleapis.com/v1/models/#{config[:options][:model]}"
                    else
-                     raise StandardError, "Unsupported service: #{config[:credentials][:service]}"
+                     raise UnsupportedServiceError, "Unsupported service: #{config[:credentials][:service]}"
                    end
 
         @stream = config[:options][:stream]
@@ -60,12 +62,14 @@ module Gemini
         url += "?#{params.join('&')}" if params.size.positive?
 
         if !callback.nil? && !stream_enabled
-          raise StandardError, 'You are trying to use a block without stream enabled."'
+          raise BlockWithoutStreamError, 'You are trying to use a block without stream enabled.'
         end
 
         results = []
 
-        response = Faraday.new.post do |request|
+        response = Faraday.new do |faraday|
+          faraday.response :raise_error
+        end.post do |request|
           request.url url
           request.headers['Content-Type'] = 'application/json'
           if @authentication == :service_account || @authentication == :default_credentials
@@ -106,6 +110,8 @@ module Gemini
         return safe_parse_json(response.body) unless stream_enabled
 
         results.map { |result| result[:event] }
+      rescue Faraday::ServerError => e
+        raise RequestError.new(e.message, request: e, payload:)
       end
 
       def safe_parse_json(raw)

data/ports/dsl/gemini-ai/errors.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative '../../../components/errors'
+
+include Gemini::Errors

data/static/gem.rb

@@ -3,7 +3,7 @@
 module Gemini
   GEM = {
     name: 'gemini-ai',
-    version: '2.1.0',
+    version: '2.2.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/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.1.0'
+gem 'gemini-ai', '~> 2.2.0'
 ```
 
 ```ruby
@@ -77,15 +77,20 @@ Result:
 ### Installing
 
 ```sh
-gem install gemini-ai -v 2.1.0
+gem install gemini-ai -v 2.2.0
 ```
 
 ```sh
-gem 'gemini-ai', '~> 2.1.0'
+gem 'gemini-ai', '~> 2.2.0'
 ```
 
 ### Credentials
 
+- [Option 1: API Key (Generative Language API)](#option-1-api-key-generative-language-api)
+- [Option 2: Service Account Credentials File (Vertex AI API)](#option-2-service-account-credentials-file-vertex-ai-api)
+- [Option 3: Application Default Credentials (Vertex AI API)](#option-3-application-default-credentials-vertex-ai-api)
+- [Required Data](#required-data)
+
 > ⚠️ DISCLAIMER: Be careful with what you are doing, and never trust others' code related to this. These commands and instructions alter the level of access to your Google Cloud Account, and running them naively can lead to security risks as well as financial risks. People with access to your account can use it to steal data or incur charges. Run these commands at your own responsibility and due diligence; expect no warranties from the contributors of this project.
 
 #### Option 1: API Key (Generative Language API)
@@ -268,6 +273,153 @@ client = Gemini.new(
 
 ### Generate Content
 
+#### Modes
+
+##### Text
+
+```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
+   } }]
+```
+
+##### 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)
+
+> _Courtesy of [Unsplash](https://unsplash.com/photos/greyscale-photo-of-grand-piano-czPs0z3-Ggg)_
+
+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 }
+)
+```
+
+Then, encode the image as [Base64](https://en.wikipedia.org/wiki/Base64) and add its [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types):
+
+```ruby
+require 'base64'
+
+result = client.stream_generate_content(
+  { contents: [
+    { role: 'user', parts: [
+      { text: 'Please describe this image.' },
+      { inline_data: {
+        mime_type: 'image/jpeg',
+        data: Base64.strict_encode64(File.read('piano.jpg'))
+      } }
+    ] }
+  ] }
+)
+```
+
+The result:
+```ruby
+[{ 'candidates' =>
+   [{ 'content' =>
+      { 'role' => 'model',
+        'parts' =>
+        [{ 'text' =>
+           ' 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' }] },
+      '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' }] }] },
+ { 'candidates' =>
+   [{ 'content' => { 'role' => 'model', 'parts' => [{ 'text' => ' sitting on a tiled floor. There is a small round object on the top of the piano.' }] },
+      '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' => 263, 'candidatesTokenCount' => 50, 'totalTokenCount' => 313 } }]
+```
+
+##### Video
+
+https://gist.github.com/assets/29520/f82bccbf-02d2-4899-9c48-eb8a0a5ef741
+
+> ALT: A white and gold cup is being filled with coffee. The coffee is dark and rich. The cup is sitting on a black surface. The background is blurred.
+
+> _Courtesy of [Pexels](https://www.pexels.com/video/pouring-of-coffee-855391/)_
+
+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 }
+)
+```
+
+Then, encode the video as [Base64](https://en.wikipedia.org/wiki/Base64) and add its [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types):
+
+```ruby
+require 'base64'
+
+result = client.stream_generate_content(
+  { contents: [
+    { role: 'user', parts: [
+      { text: 'Please describe this video.' },
+      { inline_data: {
+        mime_type: 'video/mp4',
+        data: Base64.strict_encode64(File.read('coffee.mp4'))
+      } }
+    ] }
+  ] }
+)
+```
+
+The result:
+```ruby
+[{"candidates"=>
+   [{"content"=>
+      {"role"=>"model",
+       "parts"=>
+        [{"text"=>
+           " A white and gold cup is being filled with coffee. The coffee is dark and rich. The cup is sitting on a black surface. The background is blurred"}]},
+     "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"=>1037, "candidatesTokenCount"=>31, "totalTokenCount"=>1068}},
+ {"candidates"=>
+   [{"content"=>{"role"=>"model", "parts"=>[{"text"=>"."}]},
+     "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"=>1037, "candidatesTokenCount"=>32, "totalTokenCount"=>1069}}]
+```
+
 #### Synchronous
 
 ```ruby
@@ -375,7 +527,7 @@ Result:
    } }]
 ```
 
-### Back-and-Forth Conversations
+#### 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:
 
@@ -417,7 +569,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.
 
@@ -573,6 +725,58 @@ result = client.request(
 )
 ```
 
+### Error Handling
+
+#### Rescuing
+
+```ruby
+require 'gemini-ai'
+
+begin
+  client.stream_generate_content({
+    contents: { role: 'user', parts: { text: 'hi!' } }
+  })
+rescue Gemini::Errors::GeminiError => error
+  puts error.class # Gemini::Errors::RequestError
+  puts error.message # 'the server responded with status 500'
+
+  puts error.payload
+  # { contents: [{ role: 'user', parts: { text: 'hi!' } }],
+  #   generationConfig: { candidateCount: 1 },
+  #   ...
+  # }
+
+  puts error.request
+  # #<Faraday::ServerError response={:status=>500, :headers...
+end
+```
+
+#### For Short
+
+```ruby
+require 'gemini-ai/errors'
+
+begin
+  client.stream_generate_content({
+    contents: { role: 'user', parts: { text: 'hi!' } }
+  })
+rescue GeminiError => error
+  puts error.class # Gemini::Errors::RequestError
+end
+```
+
+#### Errors
+
+```ruby
+GeminiError
+
+MissingProjectIdError
+UnsupportedServiceError
+BlockWithoutStreamError
+
+RequestError
+```
+
 ## Development
 
 ```bash
@@ -591,7 +795,7 @@ gem build gemini-ai.gemspec
 
 gem signin
 
-gem push gemini-ai-2.1.0.gem
+gem push gemini-ai-2.2.0.gem
 ```
 
 ### Updating the README

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gemini-ai
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 2.2.0
 platform: ruby
 authors:
 - gbaptista
@@ -78,9 +78,11 @@ files:
 - Gemfile.lock
 - LICENSE
 - README.md
+- components/errors.rb
 - controllers/client.rb
 - gemini-ai.gemspec
 - ports/dsl/gemini-ai.rb
+- ports/dsl/gemini-ai/errors.rb
 - static/gem.rb
 - tasks/generate-readme.clj
 - template.md