maritaca-ai 1.0.1 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 528dad62e33505dbe008d7a4a2829f8d0fb91d7ae621884cf4eb436777785589
-  data.tar.gz: fa2f39f286f091d238aee2ba8da22419c0880867892139a8d2c581f78d10f3f4
+  metadata.gz: afaa9a68f6751d7fdc770f727beb62076789b0a2e1b149e1a15c7973e571f4fb
+  data.tar.gz: 913f22cf572a477d03c2b227a478a67a860e01462f22e8a53cba2d650315823d
 SHA512:
-  metadata.gz: 23cb4d50db7d60142fe05313031c16096200b59ff7d10fb4bc51316b64396085d28a4916f2402bc9ff9ada668beb914e701a0b384297a5fd7b47e68a76112610
-  data.tar.gz: 0b0a0ab8c1d4f3f5d69ac0a95a5e63533419f4fb64ca70ffc882bc9e87d8a3867ae68a4d865b7a2a0546869eb2d479a5404cf8aa01025fd4e7ebe56530cee5fa
+  metadata.gz: 455d565cbf7092b0f2fa72902b78d87e8293a03800755c5020461cc86916724471d2b269d3630822ff433c15258733dcdc93ae3b25f745840306ede7062eb208
+  data.tar.gz: 58f7bd165d66a673110ca317393672ed67fe20aa053f97e83195b8892f63c3c8575494795b1055d774ee616e7dd9964bb3e81af28bc7ede3837a05420948295f

data/Gemfile

@@ -7,5 +7,5 @@ gemspec
 group :test, :development do
   gem 'dotenv', '~> 2.8', '>= 2.8.1'
   gem 'pry-byebug', '~> 3.10', '>= 3.10.1'
-  gem 'rubocop', '~> 1.58'
+  gem 'rubocop', '~> 1.60', '>= 1.60.2'
 end

data/Gemfile.lock

@@ -1,8 +1,10 @@
 PATH
   remote: .
   specs:
-    maritaca-ai (1.0.1)
+    maritaca-ai (1.2.0)
+      event_stream_parser (~> 1.0)
       faraday (~> 2.9)
+      faraday-typhoeus (~> 1.1)
 
 GEM
   remote: https://rubygems.org/
@@ -11,17 +13,24 @@ GEM
     byebug (11.1.3)
     coderay (1.1.3)
     dotenv (2.8.1)
+    ethon (0.16.0)
+      ffi (>= 1.15.0)
+    event_stream_parser (1.0.0)
     faraday (2.9.0)
       faraday-net_http (>= 2.0, < 3.2)
     faraday-net_http (3.1.0)
       net-http
-    json (2.7.1)
+    faraday-typhoeus (1.1.0)
+      faraday (~> 2.0)
+      typhoeus (~> 1.4)
+    ffi (1.16.3)
+    json (2.7.2)
     language_server-protocol (3.17.0.3)
-    method_source (1.0.0)
+    method_source (1.1.0)
     net-http (0.4.1)
       uri
     parallel (1.24.0)
-    parser (3.3.0.3)
+    parser (3.3.1.0)
       ast (~> 2.4.1)
       racc
     pry (0.14.2)
@@ -32,22 +41,26 @@ GEM
       pry (>= 0.13, < 0.15)
     racc (1.7.3)
     rainbow (3.1.1)
-    regexp_parser (2.9.0)
-    rexml (3.2.6)
-    rubocop (1.59.0)
+    regexp_parser (2.9.2)
+    rexml (3.2.8)
+      strscan (>= 3.0.9)
+    rubocop (1.63.5)
       json (~> 2.3)
       language_server-protocol (>= 3.17.0)
       parallel (~> 1.10)
-      parser (>= 3.2.2.4)
+      parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 1.8, < 3.0)
       rexml (>= 3.2.5, < 4.0)
-      rubocop-ast (>= 1.30.0, < 2.0)
+      rubocop-ast (>= 1.31.1, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 3.0)
-    rubocop-ast (1.30.0)
-      parser (>= 3.2.1.0)
+    rubocop-ast (1.31.3)
+      parser (>= 3.3.1.0)
     ruby-progressbar (1.13.0)
+    strscan (3.1.0)
+    typhoeus (1.4.1)
+      ethon (>= 0.9.0)
     unicode-display_width (2.5.0)
     uri (0.13.0)
 
@@ -58,7 +71,7 @@ DEPENDENCIES
   dotenv (~> 2.8, >= 2.8.1)
   maritaca-ai!
   pry-byebug (~> 3.10, >= 3.10.1)
-  rubocop (~> 1.58)
+  rubocop (~> 1.60, >= 1.60.2)
 
 BUNDLED WITH
    2.4.22

data/README.md

@@ -9,18 +9,19 @@ A Ruby gem for interacting with [MariTalk](https://chat.maritaca.ai) from [Marit
 ## TL;DR and Quick Start
 
 ```ruby
-gem 'maritaca-ai', '~> 1.0.1'
+gem 'maritaca-ai', '~> 1.2.0'
 ```
 
 ```ruby
 require 'maritaca-ai'
 
 client = Maritaca.new(
-  credentials: { api_key: ENV['MARITACA_API_KEY'] }
+  credentials: { api_key: ENV['MARITACA_API_KEY'] },
+  options: { server_sent_events: true }
 )
 
 result = client.chat_inference(
-  { model: 'maritalk',
+  { model: 'sabia-2-medium',
     chat_mode: true,
     messages: [ { role: 'user', content: 'Oi!' } ] }
 )
@@ -28,7 +29,13 @@ result = client.chat_inference(
 
 Result:
 ```ruby
-{ 'answer' => 'Oi! Como posso ajudá-lo(a) hoje?' }
+{ 'answer' => ' Oi! Como posso ajudar você hoje?',
+  'usage' => {
+    'completion_tokens' => 15,
+    'prompt_tokens' => 3,
+    'total_tokens' => 18
+  },
+  'model' => 'sabia-2-medium' }
 ```
 
 ## Index
@@ -36,27 +43,32 @@ Result:
 - [TL;DR and Quick Start](#tldr-and-quick-start)
 - [Index](#index)
 - [Setup](#setup)
-    - [Installing](#installing)
-    - [Credentials](#credentials)
+  - [Installing](#installing)
+  - [Credentials](#credentials)
 - [Usage](#usage)
-    - [Client](#client)
-        - [Custom Address](#custom-address)
-    - [Methods](#methods)
-        - [chat_inference](#chat_inference)
-            - [Chat](#chat)
-            - [Back-and-Forth Conversations](#back-and-forth-conversations)
-            - [Without Chat](#without-chat)
-    - [New Functionalities and APIs](#new-functionalities-and-apis)
-    - [Request Options](#request-options)
-        - [Timeout](#timeout)
-    - [Error Handling](#error-handling)
-        - [Rescuing](#rescuing)
-        - [For Short](#for-short)
-        - [Errors](#errors)
+  - [Client](#client)
+    - [Custom Address](#custom-address)
+  - [Methods](#methods)
+    - [chat_inference](#chat_inference)
+      - [Without Streaming Events](#without-streaming-events)
+        - [Chat](#chat)
+        - [Back-and-Forth Conversations](#back-and-forth-conversations)
+        - [Without Chat](#without-chat)
+      - [Receiving Stream Events](#receiving-stream-events)
+  - [Streaming and Server-Sent Events (SSE)](#streaming-and-server-sent-events-sse)
+    - [Server-Sent Events (SSE) Hang](#server-sent-events-sse-hang)
+  - [New Functionalities and APIs](#new-functionalities-and-apis)
+  - [Request Options](#request-options)
+    - [Adapter](#adapter)
+    - [Timeout](#timeout)
+  - [Error Handling](#error-handling)
+    - [Rescuing](#rescuing)
+    - [For Short](#for-short)
+    - [Errors](#errors)
 - [Development](#development)
-    - [Purpose](#purpose)
-    - [Publish to RubyGems](#publish-to-rubygems)
-    - [Updating the README](#updating-the-readme)
+  - [Purpose](#purpose)
+  - [Publish to RubyGems](#publish-to-rubygems)
+  - [Updating the README](#updating-the-readme)
 - [Resources and References](#resources-and-references)
 - [Disclaimer](#disclaimer)
 
@@ -65,11 +77,11 @@ Result:
 ### Installing
 
 ```sh
-gem install maritaca-ai -v 1.0.1
+gem install maritaca-ai -v 1.2.0
 ```
 
 ```sh
-gem 'maritaca-ai', '~> 1.0.1'
+gem 'maritaca-ai', '~> 1.2.0'
 ```
 
 ### Credentials
@@ -93,7 +105,8 @@ Create a new client:
 require 'maritaca-ai'
 
 client = Maritaca.new(
-  credentials: { api_key: ENV['MARITACA_API_KEY'] }
+  credentials: { api_key: ENV['MARITACA_API_KEY'] },
+  options: { server_sent_events: true }
 )
 ```
 
@@ -116,11 +129,13 @@ client = Maritaca.new(
 
 #### chat_inference
 
-##### Chat
+##### Without Streaming Events
+
+###### Chat
 
 ```ruby
 result = client.chat_inference(
-  { model: 'maritalk',
+  { model: 'sabia-2-medium',
     chat_mode: true,
     messages: [ { role: 'user', content: 'Oi!' } ] }
 )
@@ -128,16 +143,22 @@ result = client.chat_inference(
 
 Result:
 ```ruby
-{ 'answer' => 'Oi! Como posso ajudá-lo(a) hoje?' }
+{ 'answer' => ' Oi! Como posso ajudar você hoje?',
+  'usage' => {
+    'completion_tokens' => 15,
+    'prompt_tokens' => 3,
+    'total_tokens' => 18
+  },
+  'model' => 'sabia-2-medium' }
 ```
 
-##### 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:
 
 ```rb
 result = client.chat_inference(
-  { model: 'maritalk',
+  { model: 'sabia-2-medium',
     chat_mode: true,
     messages: [
       { role: 'user', content: 'Oi, meu nome é Tamanduá.' },
@@ -149,28 +170,127 @@ result = client.chat_inference(
 
 Result:
 ```ruby
-{ 'answer' => 'Seu nome é Tamanduá.' }
+{ 'answer' => ' Seu nome é Tamanduá. É um prazer conhecê-lo! Como posso ajudá-lo hoje?',
+  'usage' => {
+    'completion_tokens' => 35,
+    'prompt_tokens' => 39,
+    'total_tokens' => 74
+  },
+  'model' => 'sabia-2-medium' }
 ```
 
-##### Without Chat
+###### Without Chat
 
 You can prompt the model without using chat mode:
 
 ```ruby
 result = client.chat_inference(
-  { model: 'maritalk',
+  { model: 'sabia-2-medium',
     chat_mode: false,
-    messages: "Minha terra tem palmeiras,\nOnde canta o Sabiá;\n" }
+    messages: "Minha terra tem palmeiras,\nOnde canta o Sabiá;\n",
+    stopping_tokens: ['.'] }
 )
 ```
 
 Result:
 ```ruby
 { 'answer' =>
-  "As aves, que aqui gorjeiam,\n" \
-    'Não gorjeiam como lá.' }
+    "As aves, que aqui gorjeiam,\n" \
+    'Não gorjeiam como lá.',
+  'usage' => {
+    'completion_tokens' => 21,
+    'prompt_tokens' => 21,
+    'total_tokens' => 42
+  },
+  'model' => 'sabia-2-medium' }
+```
+
+##### Receiving Stream Events
+
+Ensure that you have enabled [Server-Sent Events](#streaming-and-server-sent-events-sse) before using blocks for streaming. You also need to add `stream: true` in your payload:
+
+```ruby
+client.chat_inference(
+  { model: 'sabia-2-medium',
+    stream: true,
+    chat_mode: true,
+    messages: [ { role: 'user', content: 'Oi!' } ] }
+) do |event, parsed, raw|
+  puts event
+end
+```
+
+Event:
+```ruby
+{ 'text' => ' Oi! Com' }
+```
+
+You can get all the receive events at once as an array:
+
+```ruby
+result = client.chat_inference(
+  { model: 'sabia-2-medium',
+    stream: true,
+    chat_mode: true,
+    messages: [ { role: 'user', content: 'Oi!' } ] }
+)
 ```
 
+Result:
+```ruby
+[{ 'text' => ' Oi! Com' },
+ { 'text' => 'o posso a' },
+ { 'text' => 'judar você' },
+ { 'text' => ' hoje?' },
+ { 'completion_tokens' => 15,
+   'prompt_tokens' => 74,
+   'total_tokens' => 89,
+   'model' => 'sabia-2-medium' }]
+```
+
+You can mix both as well:
+```ruby
+result = client.chat_inference(
+  { model: 'sabia-2-medium',
+    stream: true,
+    chat_mode: true,
+    messages: [ { role: 'user', content: 'Oi!' } ] }
+) do |event, parsed, raw|
+  puts event
+end
+```
+
+### Streaming and Server-Sent Events (SSE)
+
+[Server-Sent Events (SSE)](https://en.wikipedia.org/wiki/Server-sent_events) is a technology that allows certain endpoints to offer streaming capabilities, such as creating the impression that "the model is typing along with you," rather than delivering the entire answer all at once.
+
+You can set up the client to use Server-Sent Events (SSE) for all supported endpoints:
+```ruby
+client = Maritaca.new(
+  credentials: { api_key: ENV['MARITACA_API_KEY'] },
+  options: { server_sent_events: true }
+)
+```
+
+Or, you can decide on a request basis:
+```ruby
+client.chat_inference(
+  { model: 'sabia-2-medium',
+    stream: true,
+    chat_mode: true,
+    messages: [ { role: 'user', content: 'Oi!' } ] },
+  server_sent_events: true
+) do |event, parsed, raw|
+  puts event
+end
+```
+
+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 `chat_inference`: [Receiving Stream Events](#receiving-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: [Receiving Stream Events](#receiving-stream-events)
+
 ### New Functionalities and APIs
 
 Maritaca may launch a new endpoint that we haven't covered in the Gem yet. If that's the case, you may still be able to use it through the `request` method. For example, `chat_inference` is just a wrapper for `api/chat/inference`, which you can call directly like this:
@@ -178,7 +298,7 @@ Maritaca may launch a new endpoint that we haven't covered in the Gem yet. If th
 ```ruby
 result = client.request(
   'api/chat/inference',
-  { model: 'maritalk',
+  { model: 'sabia-2-medium',
     chat_mode: true,
     messages: [{ role: 'user', content: 'Oi!' }] },
   request_method: 'POST'
@@ -187,6 +307,21 @@ result = client.request(
 
 ### Request Options
 
+#### Adapter
+
+The gem uses [Faraday](https://github.com/lostisland/faraday) with the [Typhoeus](https://github.com/typhoeus/typhoeus) adapter by default.
+
+You can use a different adapter if you want:
+
+```ruby
+require 'faraday/net_http'
+
+client = Maritaca.new(
+  credentials: { api_key: ENV['MARITACA_API_KEY'] },
+  options: { connection: { adapter: :net_http } }
+)
+```
+
 #### Timeout
 
 You can set the maximum number of seconds to wait for the request to complete with the `timeout` option:
@@ -225,7 +360,7 @@ require 'maritaca-ai'
 
 begin
   client.chat_inference(
-    { model: 'maritalk',
+    { model: 'sabia-2-medium',
       chat_mode: true,
       messages: [ { role: 'user', content: 'Oi!' } ] }
   )
@@ -234,7 +369,7 @@ rescue Maritaca::Errors::MaritacaError => error
   puts error.message # 'the server responded with status 500'
 
   puts error.payload
-  # { model: 'maritalk',
+  # { model: 'sabia-2-medium',
   #   chat_mode: true,
   #   ...
   # }
@@ -251,7 +386,7 @@ require 'maritaca-ai/errors'
 
 begin
   client.chat_inference(
-    { model: 'maritalk',
+    { model: 'sabia-2-medium',
       chat_mode: true,
       messages: [ { role: 'user', content: 'Oi!' } ] }
   )
@@ -290,7 +425,7 @@ gem build maritaca-ai.gemspec
 
 gem signin
 
-gem push maritaca-ai-1.0.1.gem
+gem push maritaca-ai-1.2.0.gem
 ```
 
 ### Updating the README

data/controllers/client.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
+require 'event_stream_parser'
 require 'faraday'
+require 'faraday/typhoeus'
 require 'json'
 
 require_relative '../components/errors'
@@ -12,6 +14,8 @@ module Maritaca
 
       ALLOWED_REQUEST_OPTIONS = %i[timeout open_timeout read_timeout write_timeout].freeze
 
+      DEFAULT_FARADAY_ADAPTER = :typhoeus
+
       def initialize(config)
         @api_key = config.dig(:credentials, :api_key)
         @server_sent_events = config.dig(:options, :server_sent_events)
@@ -35,6 +39,8 @@ module Maritaca
                            else
                              {}
                            end
+
+        @faraday_adapter = config.dig(:options, :connection, :adapter) || DEFAULT_FARADAY_ADAPTER
       end
 
       def chat_inference(payload, server_sent_events: nil, &callback)
@@ -54,9 +60,8 @@ module Maritaca
 
         method_to_call = request_method.to_s.strip.downcase.to_sym
 
-        partial_json = ''
-
         response = Faraday.new(request: @request_options) do |faraday|
+          faraday.adapter @faraday_adapter
           faraday.response :raise_error
         end.send(method_to_call) do |request|
           request.url url
@@ -67,6 +72,10 @@ module Maritaca
           request.body = payload.to_json unless payload.nil?
 
           if server_sent_events_enabled
+            parser = EventStreamParser::Parser.new
+
+            partial_json = ''
+
             request.options.on_data = proc do |chunk, bytes, env|
               if env && env.status != 200
                 raise_error = Faraday::Response::RaiseError.new
@@ -78,14 +87,33 @@ module Maritaca
               parsed_json = safe_parse_json(partial_json)
 
               if parsed_json
-                result = { event: parsed_json, raw: { chunk:, bytes:, env: } }
+                result = {
+                  event: parsed_json,
+                  raw: { chunk:, bytes:, env: }
+                }
 
-                callback.call(result[:event], result[:raw]) unless callback.nil?
+                callback.call(result[:event], result[:parsed], result[:raw]) unless callback.nil?
 
                 results << result
 
                 partial_json = ''
               end
+
+              parser.feed(chunk) do |type, data, id, reconnection_time|
+                parsed_data = safe_parse_json(data)
+
+                unless parsed_data.nil?
+                  result = {
+                    event: parsed_data,
+                    parsed: { type:, data:, id:, reconnection_time: },
+                    raw: { chunk:, bytes:, env: }
+                  }
+
+                  callback.call(result[:event], result[:parsed], result[:raw]) unless callback.nil?
+
+                  results << result
+                end
+              end
             end
           end
         end

data/maritaca-ai.gemspec

@@ -29,7 +29,9 @@ Gem::Specification.new do |spec|
 
   spec.require_paths = ['ports/dsl']
 
+  spec.add_dependency 'event_stream_parser', '~> 1.0'
   spec.add_dependency 'faraday', '~> 2.9'
+  spec.add_dependency 'faraday-typhoeus', '~> 1.1'
 
   spec.metadata['rubygems_mfa_required'] = 'true'
 end

data/static/gem.rb

@@ -3,7 +3,7 @@
 module Maritaca
   GEM = {
     name: 'maritaca-ai',
-    version: '1.0.1',
+    version: '1.2.0',
     author: 'gbaptista',
     summary: 'Interact with Maritaca AI.',
     description: "A Ruby gem for interacting with Maritaca AI's large language models.",

data/tasks/generate-readme.clj

@@ -23,7 +23,7 @@
                              (remove nil?))]
     (->> processed-lines
          (map (fn [{:keys [level title link]}]
-                (str (apply str (repeat (* 4 (- level 2)) " "))
+                (str (apply str (repeat (* 2 (- level 2)) " "))
                      "- ["
                      title
                      "](#"

data/template.md

@@ -9,18 +9,19 @@ A Ruby gem for interacting with [MariTalk](https://chat.maritaca.ai) from [Marit
 ## TL;DR and Quick Start
 
 ```ruby
-gem 'maritaca-ai', '~> 1.0.1'
+gem 'maritaca-ai', '~> 1.2.0'
 ```
 
 ```ruby
 require 'maritaca-ai'
 
 client = Maritaca.new(
-  credentials: { api_key: ENV['MARITACA_API_KEY'] }
+  credentials: { api_key: ENV['MARITACA_API_KEY'] },
+  options: { server_sent_events: true }
 )
 
 result = client.chat_inference(
-  { model: 'maritalk',
+  { model: 'sabia-2-medium',
     chat_mode: true,
     messages: [ { role: 'user', content: 'Oi!' } ] }
 )
@@ -28,7 +29,13 @@ result = client.chat_inference(
 
 Result:
 ```ruby
-{ 'answer' => 'Oi! Como posso ajudá-lo(a) hoje?' }
+{ 'answer' => ' Oi! Como posso ajudar você hoje?',
+  'usage' => {
+    'completion_tokens' => 15,
+    'prompt_tokens' => 3,
+    'total_tokens' => 18
+  },
+  'model' => 'sabia-2-medium' }
 ```
 
 ## Index
@@ -40,11 +47,11 @@ Result:
 ### Installing
 
 ```sh
-gem install maritaca-ai -v 1.0.1
+gem install maritaca-ai -v 1.2.0
 ```
 
 ```sh
-gem 'maritaca-ai', '~> 1.0.1'
+gem 'maritaca-ai', '~> 1.2.0'
 ```
 
 ### Credentials
@@ -68,7 +75,8 @@ Create a new client:
 require 'maritaca-ai'
 
 client = Maritaca.new(
-  credentials: { api_key: ENV['MARITACA_API_KEY'] }
+  credentials: { api_key: ENV['MARITACA_API_KEY'] },
+  options: { server_sent_events: true }
 )
 ```
 
@@ -91,11 +99,13 @@ client = Maritaca.new(
 
 #### chat_inference
 
-##### Chat
+##### Without Streaming Events
+
+###### Chat
 
 ```ruby
 result = client.chat_inference(
-  { model: 'maritalk',
+  { model: 'sabia-2-medium',
     chat_mode: true,
     messages: [ { role: 'user', content: 'Oi!' } ] }
 )
@@ -103,16 +113,22 @@ result = client.chat_inference(
 
 Result:
 ```ruby
-{ 'answer' => 'Oi! Como posso ajudá-lo(a) hoje?' }
+{ 'answer' => ' Oi! Como posso ajudar você hoje?',
+  'usage' => {
+    'completion_tokens' => 15,
+    'prompt_tokens' => 3,
+    'total_tokens' => 18
+  },
+  'model' => 'sabia-2-medium' }
 ```
 
-##### 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:
 
 ```rb
 result = client.chat_inference(
-  { model: 'maritalk',
+  { model: 'sabia-2-medium',
     chat_mode: true,
     messages: [
       { role: 'user', content: 'Oi, meu nome é Tamanduá.' },
@@ -124,28 +140,127 @@ result = client.chat_inference(
 
 Result:
 ```ruby
-{ 'answer' => 'Seu nome é Tamanduá.' }
+{ 'answer' => ' Seu nome é Tamanduá. É um prazer conhecê-lo! Como posso ajudá-lo hoje?',
+  'usage' => {
+    'completion_tokens' => 35,
+    'prompt_tokens' => 39,
+    'total_tokens' => 74
+  },
+  'model' => 'sabia-2-medium' }
 ```
 
-##### Without Chat
+###### Without Chat
 
 You can prompt the model without using chat mode:
 
 ```ruby
 result = client.chat_inference(
-  { model: 'maritalk',
+  { model: 'sabia-2-medium',
     chat_mode: false,
-    messages: "Minha terra tem palmeiras,\nOnde canta o Sabiá;\n" }
+    messages: "Minha terra tem palmeiras,\nOnde canta o Sabiá;\n",
+    stopping_tokens: ['.'] }
 )
 ```
 
 Result:
 ```ruby
 { 'answer' =>
-  "As aves, que aqui gorjeiam,\n" \
-    'Não gorjeiam como lá.' }
+    "As aves, que aqui gorjeiam,\n" \
+    'Não gorjeiam como lá.',
+  'usage' => {
+    'completion_tokens' => 21,
+    'prompt_tokens' => 21,
+    'total_tokens' => 42
+  },
+  'model' => 'sabia-2-medium' }
+```
+
+##### Receiving Stream Events
+
+Ensure that you have enabled [Server-Sent Events](#streaming-and-server-sent-events-sse) before using blocks for streaming. You also need to add `stream: true` in your payload:
+
+```ruby
+client.chat_inference(
+  { model: 'sabia-2-medium',
+    stream: true,
+    chat_mode: true,
+    messages: [ { role: 'user', content: 'Oi!' } ] }
+) do |event, parsed, raw|
+  puts event
+end
+```
+
+Event:
+```ruby
+{ 'text' => ' Oi! Com' }
+```
+
+You can get all the receive events at once as an array:
+
+```ruby
+result = client.chat_inference(
+  { model: 'sabia-2-medium',
+    stream: true,
+    chat_mode: true,
+    messages: [ { role: 'user', content: 'Oi!' } ] }
+)
 ```
 
+Result:
+```ruby
+[{ 'text' => ' Oi! Com' },
+ { 'text' => 'o posso a' },
+ { 'text' => 'judar você' },
+ { 'text' => ' hoje?' },
+ { 'completion_tokens' => 15,
+   'prompt_tokens' => 74,
+   'total_tokens' => 89,
+   'model' => 'sabia-2-medium' }]
+```
+
+You can mix both as well:
+```ruby
+result = client.chat_inference(
+  { model: 'sabia-2-medium',
+    stream: true,
+    chat_mode: true,
+    messages: [ { role: 'user', content: 'Oi!' } ] }
+) do |event, parsed, raw|
+  puts event
+end
+```
+
+### Streaming and Server-Sent Events (SSE)
+
+[Server-Sent Events (SSE)](https://en.wikipedia.org/wiki/Server-sent_events) is a technology that allows certain endpoints to offer streaming capabilities, such as creating the impression that "the model is typing along with you," rather than delivering the entire answer all at once.
+
+You can set up the client to use Server-Sent Events (SSE) for all supported endpoints:
+```ruby
+client = Maritaca.new(
+  credentials: { api_key: ENV['MARITACA_API_KEY'] },
+  options: { server_sent_events: true }
+)
+```
+
+Or, you can decide on a request basis:
+```ruby
+client.chat_inference(
+  { model: 'sabia-2-medium',
+    stream: true,
+    chat_mode: true,
+    messages: [ { role: 'user', content: 'Oi!' } ] },
+  server_sent_events: true
+) do |event, parsed, raw|
+  puts event
+end
+```
+
+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 `chat_inference`: [Receiving Stream Events](#receiving-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: [Receiving Stream Events](#receiving-stream-events)
+
 ### New Functionalities and APIs
 
 Maritaca may launch a new endpoint that we haven't covered in the Gem yet. If that's the case, you may still be able to use it through the `request` method. For example, `chat_inference` is just a wrapper for `api/chat/inference`, which you can call directly like this:
@@ -153,7 +268,7 @@ Maritaca may launch a new endpoint that we haven't covered in the Gem yet. If th
 ```ruby
 result = client.request(
   'api/chat/inference',
-  { model: 'maritalk',
+  { model: 'sabia-2-medium',
     chat_mode: true,
     messages: [{ role: 'user', content: 'Oi!' }] },
   request_method: 'POST'
@@ -162,6 +277,21 @@ result = client.request(
 
 ### Request Options
 
+#### Adapter
+
+The gem uses [Faraday](https://github.com/lostisland/faraday) with the [Typhoeus](https://github.com/typhoeus/typhoeus) adapter by default.
+
+You can use a different adapter if you want:
+
+```ruby
+require 'faraday/net_http'
+
+client = Maritaca.new(
+  credentials: { api_key: ENV['MARITACA_API_KEY'] },
+  options: { connection: { adapter: :net_http } }
+)
+```
+
 #### Timeout
 
 You can set the maximum number of seconds to wait for the request to complete with the `timeout` option:
@@ -200,7 +330,7 @@ require 'maritaca-ai'
 
 begin
   client.chat_inference(
-    { model: 'maritalk',
+    { model: 'sabia-2-medium',
       chat_mode: true,
       messages: [ { role: 'user', content: 'Oi!' } ] }
   )
@@ -209,7 +339,7 @@ rescue Maritaca::Errors::MaritacaError => error
   puts error.message # 'the server responded with status 500'
 
   puts error.payload
-  # { model: 'maritalk',
+  # { model: 'sabia-2-medium',
   #   chat_mode: true,
   #   ...
   # }
@@ -226,7 +356,7 @@ require 'maritaca-ai/errors'
 
 begin
   client.chat_inference(
-    { model: 'maritalk',
+    { model: 'sabia-2-medium',
       chat_mode: true,
       messages: [ { role: 'user', content: 'Oi!' } ] }
   )
@@ -265,7 +395,7 @@ gem build maritaca-ai.gemspec
 
 gem signin
 
-gem push maritaca-ai-1.0.1.gem
+gem push maritaca-ai-1.2.0.gem
 ```
 
 ### Updating the README

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: maritaca-ai
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.2.0
 platform: ruby
 authors:
 - gbaptista
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-01-13 00:00:00.000000000 Z
+date: 2024-05-19 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: event_stream_parser
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: faraday
   requirement: !ruby/object:Gem::Requirement
@@ -24,8 +38,22 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.9'
+- !ruby/object:Gem::Dependency
+  name: faraday-typhoeus
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
 description: A Ruby gem for interacting with Maritaca AI's large language models.
-email: 
+email:
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -53,7 +81,7 @@ metadata:
   homepage_uri: https://github.com/gbaptista/maritaca-ai
   source_code_uri: https://github.com/gbaptista/maritaca-ai
   rubygems_mfa_required: 'true'
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - ports/dsl
@@ -69,7 +97,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubygems_version: 3.3.3
-signing_key: 
+signing_key:
 specification_version: 4
 summary: Interact with Maritaca AI.
 test_files: []