gemini-ai 2.0.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 790a1c353ecc9e3122fc096f674d50fbd0ef36b4b0f9ab56ef66d180b0a5d4de
-  data.tar.gz: 2eac84cb99804362eea89063ea6ed66467af1ffb3a7d4ffd1ab186f7a2842157
+  metadata.gz: c7c5bd6e6cd1d2195b7a437fb0664cd553dc0acbf0d293042d93c3d701e6b6e0
+  data.tar.gz: 665458cc152b00efae9f8e2b730fe000ef2caac63f835944c1e76a83b9a0e627
 SHA512:
-  metadata.gz: d82d466e8272ab1919c153d3f68ffb3ab4ebd5a750a3822daef4394a814b36c08c0f114e691cb52a5c830a74a0e9d208cd3d4407227592812f0534655dc5afc1
-  data.tar.gz: 7141a1bff79ea92aac09105b84fd9c2d5b68efe5184bf1ca0588dc420c0180ea65cd2fcca000ab0ea2cd00c1be188877f3f97ec6c7410f61bea4c8acf52b475c
+  metadata.gz: 0ca1f3f87c61276902259d937f4d57f324a756d1e63c1e5781680ba970313f3c3c29a2da49c4eb1ec0bf351f984bee378e86b22d1656b2423638e1a70bd5dddf
+  data.tar.gz: 50988d0881d37f561e0c75ac1beea4fc9b34c757d0f16fb2dcb2f63d3e63f867194e0f826800c8429ce9f33500dd74c3fa4c5d747a0975378c81cf3e0ad4a61b

data/.gitignore

@@ -1 +1,2 @@
 *.gem
+.devcontainer

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    gemini-ai (2.0.0)
+    gemini-ai (2.2.0)
       event_stream_parser (~> 1.0)
       faraday (~> 2.7, >= 2.7.12)
       googleauth (~> 1.9, >= 1.9.1)
@@ -36,7 +36,7 @@ GEM
     method_source (1.0.0)
     multi_json (1.15.0)
     os (1.1.4)
-    parallel (1.23.0)
+    parallel (1.24.0)
     parser (3.2.2.4)
       ast (~> 2.4.1)
       racc

data/README.md

@@ -1,6 +1,6 @@
 # Gemini AI
 
-A Ruby Gem for interacting with [Gemini](https://deepmind.google/technologies/gemini/) through [Vertex AI](https://cloud.google.com/vertex-ai) or [AI Studio](https://makersuite.google.com), Google's generative AI services.
+A Ruby Gem for interacting with [Gemini](https://deepmind.google/technologies/gemini/) through [Vertex AI](https://cloud.google.com/vertex-ai), [Generative Language API](https://ai.google.dev/api/rest), or [AI Studio](https://makersuite.google.com), Google's generative AI services.
 
 ![The logo shows a gemstone split into red and blue halves, symbolizing Ruby programming and Gemini AI. It's surrounded by a circuit-like design on a dark blue backdrop.](https://raw.githubusercontent.com/gbaptista/assets/main/gemini-ai/ruby-gemini-ai.png)
 
@@ -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.0'
+gem 'gemini-ai', '~> 2.2.0'
 ```
 
 ```ruby
@@ -24,12 +24,20 @@ client = Gemini.new(
   options: { model: 'gemini-pro', stream: false }
 )
 
-# With a Service Account
+# With a Service Account Credentials File
 client = Gemini.new(
   credentials: {
     service: 'vertex-ai-api',
     file_path: 'google-credentials.json',
-    project_id: 'PROJECT_ID',
+    region: 'us-east4'
+  },
+  options: { model: 'gemini-pro', stream: false }
+)
+
+# With Application Default Credentials
+client = Gemini.new(
+  credentials: {
+    service: 'vertex-ai-api',
     region: 'us-east4'
   },
   options: { model: 'gemini-pro', stream: false }
@@ -67,18 +75,27 @@ Result:
 - [Setup](#setup)
     - [Installing](#installing)
     - [Credentials](#credentials)
-        - [Option 1: API Key](#option-1-api-key)
-        - [Option 2: Service Account](#option-2-service-account)
+        - [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)
 - [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)
@@ -91,18 +108,23 @@ Result:
 ### Installing
 
 ```sh
-gem install gemini-ai -v 2.0.0
+gem install gemini-ai -v 2.2.0
 ```
 
 ```sh
-gem 'gemini-ai', '~> 2.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
+#### Option 1: API Key (Generative Language API)
 
 You need a [Google Cloud](https://console.cloud.google.com) [_Project_](https://cloud.google.com/resource-manager/docs/creating-managing-projects), and then you can generate an API Key through the Google Cloud Console [here](https://console.cloud.google.com/apis/credentials).
 
@@ -111,7 +133,7 @@ You also need to enable the _Generative Language API_ service in your Google Clo
 
 Alternatively, you can generate an API Key through _Google AI Studio_ [here](https://makersuite.google.com/app/apikey). However, this approach will automatically create a project for you in your Google Cloud Account.
 
-#### Option 2: Service Account
+#### Option 2: Service Account Credentials File (Vertex AI API)
 
 You need a [Google Cloud](https://console.cloud.google.com) [_Project_](https://cloud.google.com/resource-manager/docs/creating-managing-projects) and a [_Service Account_](https://cloud.google.com/iam/docs/service-account-overview) to use [Vertex AI](https://cloud.google.com/vertex-ai) API.
 
@@ -165,11 +187,24 @@ gcloud projects add-iam-policy-binding PROJECT_ID \
   --role='roles/ml.admin'
 ```
 
+#### Option 3: Application Default Credentials (Vertex AI API)
+
+Similar to [Option 2](#option-2-service-account-credentials-file-vertex-ai-api), but you don't need to download a `google-credentials.json`. [_Application Default Credentials_](https://cloud.google.com/docs/authentication/application-default-credentials) automatically find credentials based on the application environment.
+
+For local development, you can generate your default credentials using the [gcloud CLI](https://cloud.google.com/sdk/gcloud) as follows:
+
+```sh
+gcloud auth application-default login 
+```
+
+For more details about alternative methods and different environments, check the official documentation:
+[Set up Application Default Credentials](https://cloud.google.com/docs/authentication/provide-credentials-adc)
+
 #### Required Data
 
 After choosing an option, you should have all the necessary data and access to use Gemini.
 
-For API Key:
+**Option 1**, for API Key:
 
 ```ruby
 {
@@ -187,13 +222,21 @@ Remember that hardcoding your API key in code is unsafe; it's preferable to use
 }
 ```
 
-Alternativelly, for Service Account, a `google-credentials.json` file, a `PROJECT_ID`, and a `REGION`:
+**Option 2**: For the Service Account, provide a `google-credentials.json` file and a `REGION`:
 
 ```ruby
 {
   service: 'vertex-ai-api',
   file_path: 'google-credentials.json',
-  project_id: 'PROJECT_ID',
+  region: 'us-east4'
+}
+```
+
+**Option 3**: For _Application Default Credentials_, omit both the `api_key` and the `file_path`:
+
+```ruby
+{
+  service: 'vertex-ai-api',
   region: 'us-east4'
 }
 ```
@@ -212,6 +255,15 @@ Tokyo, Japan (asia-northeast1)
 
 You can follow here if new regions are available: [Gemini API](https://cloud.google.com/vertex-ai/docs/generative-ai/model-reference/gemini)
 
+You might want to explicitly set a Google Cloud Project ID, which you can do as follows:
+
+```ruby
+{
+  service: 'vertex-ai-api',
+  project_id: 'PROJECT_ID'
+}
+```
+
 ## Usage
 
 ### Client
@@ -230,12 +282,20 @@ client = Gemini.new(
   options: { model: 'gemini-pro', stream: false }
 )
 
-# With a Service Account
+# With a Service Account Credentials File
 client = Gemini.new(
   credentials: {
     service: 'vertex-ai-api',
     file_path: 'google-credentials.json',
-    project_id: 'PROJECT_ID',
+    region: 'us-east4'
+  },
+  options: { model: 'gemini-pro', stream: false }
+)
+
+# With Application Default Credentials
+client = Gemini.new(
+  credentials: {
+    service: 'vertex-ai-api',
     region: 'us-east4'
   },
   options: { model: 'gemini-pro', stream: false }
@@ -244,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
@@ -351,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:
 
@@ -393,9 +600,9 @@ Result:
    } }]
 ```
 
-### Tools (Functions) Calling
+#### Tools (Functions) Calling
 
-> As of the writing of this README, only the `gemini-pro` model [supports](https://cloud.google.com/vertex-ai/docs/generative-ai/multimodal/function-calling#supported_models) tools (functions) calls.
+> 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.
 
 You can provide specifications for [tools (functions)](https://cloud.google.com/vertex-ai/docs/generative-ai/multimodal/function-calling) using [JSON Schema](https://json-schema.org) to generate potential calls to them:
 
@@ -549,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
@@ -567,7 +826,7 @@ gem build gemini-ai.gemspec
 
 gem signin
 
-gem push gemini-ai-2.0.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
@@ -12,21 +14,34 @@ module Gemini
         if config[:credentials][:api_key]
           @authentication = :api_key
           @api_key = config[:credentials][:api_key]
-        else
+        elsif config[:credentials][:file_path]
           @authentication = :service_account
           @authorizer = ::Google::Auth::ServiceAccountCredentials.make_creds(
             json_key_io: File.open(config[:credentials][:file_path]),
             scope: 'https://www.googleapis.com/auth/cloud-platform'
           )
+        else
+          @authentication = :default_credentials
+          @authorizer = ::Google::Auth.get_application_default
+        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
+
+          raise MissingProjectIdError, 'Could not determine project_id, which is required.' if @project_id.nil?
         end
 
         @address = case config[:credentials][:service]
                    when 'vertex-ai-api'
-                     "https://#{config[:credentials][:region]}-aiplatform.googleapis.com/v1/projects/#{config[:credentials][:project_id]}/locations/#{config[:credentials][:region]}/publishers/google/models/#{config[:options][:model]}"
+                     "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 StandardError, "Unsupported service: #{config[:credentials][:service]}"
+                     raise UnsupportedServiceError, "Unsupported service: #{config[:credentials][:service]}"
                    end
 
         @stream = config[:options][:stream]
@@ -47,15 +62,17 @@ 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
+          if @authentication == :service_account || @authentication == :default_credentials
             request.headers['Authorization'] = "Bearer #{@authorizer.fetch_access_token!['access_token']}"
           end
 
@@ -93,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,10 +3,10 @@
 module Gemini
   GEM = {
     name: 'gemini-ai',
-    version: '2.0.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 or AI Studio, Google's generative AI services.",
+    description: "A Ruby Gem for interacting with Gemini through Vertex AI, Generative Language API, or AI Studio, Google's generative AI services.",
     github: 'https://github.com/gbaptista/gemini-ai',
     gem_server: 'https://rubygems.org',
     license: 'MIT',

data/template.md

@@ -1,6 +1,6 @@
 # Gemini AI
 
-A Ruby Gem for interacting with [Gemini](https://deepmind.google/technologies/gemini/) through [Vertex AI](https://cloud.google.com/vertex-ai) or [AI Studio](https://makersuite.google.com), Google's generative AI services.
+A Ruby Gem for interacting with [Gemini](https://deepmind.google/technologies/gemini/) through [Vertex AI](https://cloud.google.com/vertex-ai), [Generative Language API](https://ai.google.dev/api/rest), or [AI Studio](https://makersuite.google.com), Google's generative AI services.
 
 ![The logo shows a gemstone split into red and blue halves, symbolizing Ruby programming and Gemini AI. It's surrounded by a circuit-like design on a dark blue backdrop.](https://raw.githubusercontent.com/gbaptista/assets/main/gemini-ai/ruby-gemini-ai.png)
 
@@ -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.0'
+gem 'gemini-ai', '~> 2.2.0'
 ```
 
 ```ruby
@@ -24,12 +24,20 @@ client = Gemini.new(
   options: { model: 'gemini-pro', stream: false }
 )
 
-# With a Service Account
+# With a Service Account Credentials File
 client = Gemini.new(
   credentials: {
     service: 'vertex-ai-api',
     file_path: 'google-credentials.json',
-    project_id: 'PROJECT_ID',
+    region: 'us-east4'
+  },
+  options: { model: 'gemini-pro', stream: false }
+)
+
+# With Application Default Credentials
+client = Gemini.new(
+  credentials: {
+    service: 'vertex-ai-api',
     region: 'us-east4'
   },
   options: { model: 'gemini-pro', stream: false }
@@ -69,18 +77,23 @@ Result:
 ### Installing
 
 ```sh
-gem install gemini-ai -v 2.0.0
+gem install gemini-ai -v 2.2.0
 ```
 
 ```sh
-gem 'gemini-ai', '~> 2.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
+#### Option 1: API Key (Generative Language API)
 
 You need a [Google Cloud](https://console.cloud.google.com) [_Project_](https://cloud.google.com/resource-manager/docs/creating-managing-projects), and then you can generate an API Key through the Google Cloud Console [here](https://console.cloud.google.com/apis/credentials).
 
@@ -89,7 +102,7 @@ You also need to enable the _Generative Language API_ service in your Google Clo
 
 Alternatively, you can generate an API Key through _Google AI Studio_ [here](https://makersuite.google.com/app/apikey). However, this approach will automatically create a project for you in your Google Cloud Account.
 
-#### Option 2: Service Account
+#### Option 2: Service Account Credentials File (Vertex AI API)
 
 You need a [Google Cloud](https://console.cloud.google.com) [_Project_](https://cloud.google.com/resource-manager/docs/creating-managing-projects) and a [_Service Account_](https://cloud.google.com/iam/docs/service-account-overview) to use [Vertex AI](https://cloud.google.com/vertex-ai) API.
 
@@ -143,11 +156,24 @@ gcloud projects add-iam-policy-binding PROJECT_ID \
   --role='roles/ml.admin'
 ```
 
+#### Option 3: Application Default Credentials (Vertex AI API)
+
+Similar to [Option 2](#option-2-service-account-credentials-file-vertex-ai-api), but you don't need to download a `google-credentials.json`. [_Application Default Credentials_](https://cloud.google.com/docs/authentication/application-default-credentials) automatically find credentials based on the application environment.
+
+For local development, you can generate your default credentials using the [gcloud CLI](https://cloud.google.com/sdk/gcloud) as follows:
+
+```sh
+gcloud auth application-default login 
+```
+
+For more details about alternative methods and different environments, check the official documentation:
+[Set up Application Default Credentials](https://cloud.google.com/docs/authentication/provide-credentials-adc)
+
 #### Required Data
 
 After choosing an option, you should have all the necessary data and access to use Gemini.
 
-For API Key:
+**Option 1**, for API Key:
 
 ```ruby
 {
@@ -165,13 +191,21 @@ Remember that hardcoding your API key in code is unsafe; it's preferable to use
 }
 ```
 
-Alternativelly, for Service Account, a `google-credentials.json` file, a `PROJECT_ID`, and a `REGION`:
+**Option 2**: For the Service Account, provide a `google-credentials.json` file and a `REGION`:
 
 ```ruby
 {
   service: 'vertex-ai-api',
   file_path: 'google-credentials.json',
-  project_id: 'PROJECT_ID',
+  region: 'us-east4'
+}
+```
+
+**Option 3**: For _Application Default Credentials_, omit both the `api_key` and the `file_path`:
+
+```ruby
+{
+  service: 'vertex-ai-api',
   region: 'us-east4'
 }
 ```
@@ -190,6 +224,15 @@ Tokyo, Japan (asia-northeast1)
 
 You can follow here if new regions are available: [Gemini API](https://cloud.google.com/vertex-ai/docs/generative-ai/model-reference/gemini)
 
+You might want to explicitly set a Google Cloud Project ID, which you can do as follows:
+
+```ruby
+{
+  service: 'vertex-ai-api',
+  project_id: 'PROJECT_ID'
+}
+```
+
 ## Usage
 
 ### Client
@@ -208,12 +251,20 @@ client = Gemini.new(
   options: { model: 'gemini-pro', stream: false }
 )
 
-# With a Service Account
+# With a Service Account Credentials File
 client = Gemini.new(
   credentials: {
     service: 'vertex-ai-api',
     file_path: 'google-credentials.json',
-    project_id: 'PROJECT_ID',
+    region: 'us-east4'
+  },
+  options: { model: 'gemini-pro', stream: false }
+)
+
+# With Application Default Credentials
+client = Gemini.new(
+  credentials: {
+    service: 'vertex-ai-api',
     region: 'us-east4'
   },
   options: { model: 'gemini-pro', stream: false }
@@ -222,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
@@ -329,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:
 
@@ -371,9 +569,9 @@ Result:
    } }]
 ```
 
-### Tools (Functions) Calling
+#### Tools (Functions) Calling
 
-> As of the writing of this README, only the `gemini-pro` model [supports](https://cloud.google.com/vertex-ai/docs/generative-ai/multimodal/function-calling#supported_models) tools (functions) calls.
+> 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.
 
 You can provide specifications for [tools (functions)](https://cloud.google.com/vertex-ai/docs/generative-ai/multimodal/function-calling) using [JSON Schema](https://json-schema.org) to generate potential calls to them:
 
@@ -527,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
@@ -545,7 +795,7 @@ gem build gemini-ai.gemspec
 
 gem signin
 
-gem push gemini-ai-2.0.0.gem
+gem push gemini-ai-2.2.0.gem
 ```
 
 ### Updating the README

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gemini-ai
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.2.0
 platform: ruby
 authors:
 - gbaptista
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-12-15 00:00:00.000000000 Z
+date: 2023-12-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: event_stream_parser
@@ -64,8 +64,8 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 1.9.1
-description: A Ruby Gem for interacting with Gemini through Vertex AI or AI Studio,
-  Google's generative AI services.
+description: A Ruby Gem for interacting with Gemini through Vertex AI, Generative
+  Language API, or AI Studio, Google's generative AI services.
 email: 
 executables: []
 extensions: []
@@ -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