omniai 1.9.6 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 23098dd1fbbb9542265f3d32a9c37642a1a554fa4a789c78fb4e25a364213116
-  data.tar.gz: 4885f37cc46af15c1e208a6c9c4f0f06b84d4986c1d0b9361fd2b9e451fb3352
+  metadata.gz: c58b1fbebfaaaa7bcd77fe9754d0bf0bddc7b55c07b76ae31cbae0ae24b2024f
+  data.tar.gz: d4462dbf00a04ce81db7f8bf7c4f45018aaab994fd2699483e8b2de324546ab2
 SHA512:
-  metadata.gz: a63e630e0aeeeb8342cceba0d2505c487e9dacfcd76bcc07e75d8c29c132a9806d3d4fdc4346ebcd6a6eb02534a14de75f9bd5530388eec1652ff19a61b2d008
-  data.tar.gz: a61425c68913a53de2d0300fe3c74ea546491f69fffd53c1c6fbd414924b7204b718c7676de5b604a063532a8149bbaef132032b1cbc49ac0e69d9030bfd456e
+  metadata.gz: b7857bee4ec80f63d8e2a8ae3a6534c36f21ae622ba3a672653ae6aa2017e929baa2d4f89d9bcd783ab645bf17c9e65c6dfa8fa18fc757a38106d59375305bb8
+  data.tar.gz: d0c5f8a0ab434740df1a6abc4f5f9d96590d067fe5d6e4e1a9849edea9647bcfa4c5768fdfe74c14a520ff6a9849e8b51f56b764ca8f28424bdb614a87d47f0e

data/README.md

@@ -16,124 +16,161 @@ OmniAI provides a unified Ruby API for integrating with multiple AI providers, i
 
 ## Examples
 
-### Example #1: [Chat](https://github.com/ksylvest/omniai/blob/main/examples/chat)
+### Example #1: [Chat w/ Text](https://github.com/ksylvest/omniai/blob/main/examples/chat_with_text)
 
-This example demonstrates using `OmniAI` with **Anthropic** to prompt a “biologist” for an analysis of photos, identifying the animals within each one. A system and user message are provided, and the response is streamed in real time.
+This example demonstrates using `OmniAI` with **Anthropic** to ask for a joke. The response is parsed and printed.
 
 ```ruby
 require 'omniai/anthropic'
 
-CLIENT = OmniAI::Anthropic::Client.new
-
-CAT_URL = 'https://images.unsplash.com/photo-1472491235688-bdc81a63246e?q=80&w=1024&h=1024&fit=crop&fm=jpg'
-DOG_URL = 'https://images.unsplash.com/photo-1517849845537-4d257902454a?q=80&w=1024&h=1024&fit=crop&fm=jpg'
+client = OmniAI::Anthropic::Client.new
 
-CLIENT.chat(stream: $stdout) do |prompt|
-  prompt.system('You are a helpful biologist with an expertise in animals that responds with the latin names.')
-  prompt.user do |message|
-    message.text('What animals are in the attached photos?')
-    message.url(CAT_URL, 'image/jpeg')
-    message.url(DOG_URL, 'image/jpeg')
-  end
-end
+puts client.chat("Tell me a joke").text
 ```
 
 ```
-The animals in the photos are:
-
-1. A cat (*Felis catus*).
-2. A dog (*Canis familiaris*).
+Why don't scientists trust atoms? Because they make up everything!
 ```
 
-### Example #2: [Text-to-Speech](https://github.com/ksylvest/omniai/blob/main/examples/text_to_speech)
+### Example #2: [Chat w/ Prompt](https://github.com/ksylvest/omniai/blob/main/examples/chat_with_prompt)
 
-This example demonstrates using `OmniAI` with **OpenAI** to convert text to speech and save it to a file.
+This example demonstrates using `OmniAI` with **Mistral** to ask for the fastest animal. It includes a system and user message in the prompt. The response is streamed in real time.
 
 ```ruby
-require 'omniai/openai'
+require "omniai/mistral"
 
-CLIENT = OmniAI::OpenAI::Client.new
+client = OmniAI::Mistral::Client.new
 
-File.open(File.join(__dir__, 'audio.wav'), 'wb') do |file|
-  CLIENT.speak('Sally sells seashells by the seashore.', format: OmniAI::Speak::Format::WAV) do |chunk|
-    file << chunk
-  end
+client.chat(stream: $stdout) do |prompt|
+  prompt.system "Respond in both English and French."
+  prompt.user "What is the fastest animal?"
 end
 ```
 
-### Example #3: [Speech-to-Text](https://github.com/ksylvest/omniai/blob/main/examples/speech_to_text)
+```
+**English**: The peregrine falcon is generally considered the fastest animal, reaching speeds of over 390 km/h.
+**French**: Le faucon pèlerin est généralement considéré comme l'animal le plus rapide, atteignant des vitesses de plus de 390 km/h.
+```
 
-This example demonstrates using `OmniAI` with **OpenAI** to convert speech to text.
+### Example #3: [Chat w/ Vision](https://github.com/ksylvest/omniai/blob/main/examples/chat_with_vision)
+
+This example demonstrates using `OmniAI` with **OpenAI** to prompt a “biologist” for an analysis of photos, identifying the animals within each one. A system and user message are provided, and the response is streamed in real time.
 
 ```ruby
-require 'omniai/openai'
+require "omniai/openai"
 
-CLIENT = OmniAI::OpenAI::Client.new
+client = OmniAI::OpenAI::Client.new
 
-File.open(File.join(__dir__, 'audio.wav'), 'rb') do |file|
-  transcription = CLIENT.transcribe(file)
-  puts(transcription.text)
+CAT_URL = "https://images.unsplash.com/photo-1472491235688-bdc81a63246e?q=80&w=1024&h=1024&fit=crop&fm=jpg"
+DOG_URL = "https://images.unsplash.com/photo-1517849845537-4d257902454a?q=80&w=1024&h=1024&fit=crop&fm=jpg"
+
+client.chat(stream: $stdout) do |prompt|
+  prompt.system("You are a helpful biologist with expertise in animals who responds with the Latin names.")
+  prompt.user do |message|
+    message.text("What animals are in the attached photos?")
+    message.url(CAT_URL, "image/jpeg")
+    message.url(DOG_URL, "image/jpeg")
+  end
 end
 ```
 
-### Example #4: [Tools](https://github.com/ksylvest/omniai/blob/main/examples/tools)
+```
+The first photo is of a cat, *Felis Catus*.
+The second photo is of a dog, *Canis Familiaris*.
+```
+
+### Example #4: [Chat w/ Tools](https://github.com/ksylvest/omniai/blob/main/examples/chat_with_tools)
 
-This example demonstrates how to use `OmniAI` with **Google** to call a custom tool that generates a weather report. The tool accepts a list of locations (city and country) and returns a temperature — randomly generated for demonstration purposes — based on the provided parameters.
+This example demonstrates using `OmniAI` with **Google** to ask for the weather. A tool “Weather” is provided. The tool accepts a location and unit (Celsius or Fahrenheit) then calculates the weather. The LLM makes multiple tool-call requests and is automatically provided with a tool-call response prior to streaming in real-time the result.
 
 ```ruby
 require 'omniai/google'
 
-CLIENT = OmniAI::Google::Client.new
+client = OmniAI::Google::Client.new
 
-LOCATION = OmniAI::Tool::Property.object(
-  properties: {
-    city: OmniAI::Tool::Property.string(description: 'e.g. "Toronto"'),
-    country: OmniAI::Tool::Property.string(description: 'e.g. "Canada"'),
-  },
-  required: %i[city country]
-)
+class Weather < OmniAI::Tool
+  description "Lookup the weather for a location"
 
-LOCATIONS = OmniAI::Tool::Property.array(
-  min_items: 1,
-  max_items: 5,
-  items: LOCATION
-)
+  parameter :location, :string, description: "A location (e.g. 'Toronto, Canada')."
+  parameter :unit, :string, enum: %w[Celsius Fahrenheit], description: "The unit of measurement."
+  required %i[location]
 
-UNIT = OmniAI::Tool::Property.string(enum: %w[celcius fahrenheit])
+  # @param location [String] required
+  # @param unit [String] optional - "Celcius" or "Fahrenheit"
+  # @return [String]
+  def execute(location:, unit: "Celsius")
+    puts "[weather] location=#{location} unit=#{unit}"
+    "#{rand(20..50)}° #{unit} at #{location}"
+  end
+end
 
-WEATHER = proc do |locations:, unit: 'celsius'|
-  locations.map do |location|
-    "#{rand(20..50)}° #{unit} in #{location[:city]}, #{location[:country]}"
-  end.join("\n")
+client.chat(stream: $stdout, tools: [Weather.new]) do |prompt|
+  prompt.system "You are an expert in weather."
+  prompt.user 'What is the weather in "London" in Celsius and "Madrid" in Fahrenheit?'
 end
+```
 
-TOOL = OmniAI::Tool.new(
-  WEATHER,
-  name: 'Weather',
-  description: 'Lookup the weather in a location',
-  parameters: OmniAI::Tool::Parameters.new(
-    properties: {
-      locations: LOCATIONS,
-      unit: UNIT,
-    },
-    required: %i[locations]
-  )
-)
+```
+[weather] location=London unit=Celsius
+[weather] location=Madrid unit=Fahrenheit
+```
 
-completion = CLIENT.chat(tools: [TOOL]) do |prompt|
-  prompt.user do |message|
-    message.text('What is the weather in "London" in celcius and "Seattle" in fahrenheit?')
-  end
-end
+```
+The weather is 24° Celsius in London and 42° Fahrenheit in Madrid.
+```
+
+### Example #5: Chat w/ CLI
+
+The `OmniAI` gem also ships with a CLI to simplify quick tests.
 
-puts(completion.text)
+```bash
+omniai chat "Who designed the Ruby programming language?"
 ```
 
 ```
-The weather is 24° celcius in London and 42° fahrenheit in Seattle.
+The Ruby programming language was created by Yukihiro Matsumoto, often known as "Matz."
+```
+
+```bash
+omniai chat --provider="google" --model="gemini-2.0-flash" "Who are you?"
+```
+
+```
+I am a large language model, trained by Google.
+```
+
+### Example #6: [Text-to-Speech](https://github.com/ksylvest/omniai/blob/main/examples/text_to_speech)
+
+This example demonstrates using `OmniAI` with **OpenAI** to convert text to speech and save it to a file.
+
+```ruby
+require 'omniai/openai'
+
+client = OmniAI::OpenAI::Client.new
+
+File.open(File.join(__dir__, 'audio.wav'), 'wb') do |file|
+  client.speak('Sally sells seashells by the seashore.', format: OmniAI::Speak::Format::WAV) do |chunk|
+    file << chunk
+  end
+end
+```
+
+### Example #7: [Speech-to-Text](https://github.com/ksylvest/omniai/blob/main/examples/speech_to_text)
+
+This example demonstrates using `OmniAI` with **OpenAI** to convert speech to text.
+
+```ruby
+require 'omniai/openai'
+
+client = OmniAI::OpenAI::Client.new
+
+File.open(File.join(__dir__, 'audio.wav'), 'rb') do |file|
+  transcription = client.transcribe(file)
+  puts(transcription.text)
+end
 ```
 
-### Example #5: [Embeddings](https://github.com/ksylvest/omniai/blob/main/examples/embeddings)
+### Example #8: [Embeddings](https://github.com/ksylvest/omniai/blob/main/examples/embeddings)
 
 This example demonstrates using `OmniAI` with **Mistral** to generate embeddings for a dataset. It defines a set of entries (e.g. "George is a teacher." or "Ringo is a doctor.") and then compares the embeddings generated from a query (e.g. "What does George do?" or "Who is a doctor?") to rank the entries by relevance.
 
@@ -282,7 +319,7 @@ logger = Logger.new(STDOUT)
 client = OmniAI::OpenAI::Client.new(timeout: 8) # i.e. 8 seconds
 ```
 
-Timeouts are also be configurable by passing a `timeout` hash with `timeout` / `read` / `write` / `keys using:
+Timeouts are also configurable by passing a `timeout` hash with `timeout` / `read` / `write` / keys using:
 
 ```ruby
 require 'omniai/openai'
@@ -351,18 +388,18 @@ A chat can also be initialized with tools:
 
 ```ruby
 tool = OmniAI::Tool.new(
-  proc { |location:, unit: 'celsius'| "#{rand(20..50)}° #{unit} in #{location}" },
+  proc { |location:, unit: 'Celsius'| "#{rand(20..50)}° #{unit} in #{location}" },
   name: 'Weather',
   description: 'Lookup the weather in a location',
   parameters: OmniAI::Tool::Parameters.new(
     properties: {
       location: OmniAI::Tool::Property.string(description: 'e.g. Toronto'),
-      unit: OmniAI::Tool::Property.string(enum: %w[celcius fahrenheit]),
+      unit: OmniAI::Tool::Property.string(enum: %w[Celsius Fahrenheit]),
     },
     required: %i[location]
   )
 )
-client.chat('What is the weather in "London" in celcius and "Paris" in fahrenheit?', tools: [tool])
+client.chat('What is the weather in "London" in Celsius and "Paris" in Fahrenheit?', tools: [tool])
 ```
 
 ### Transcribe

data/lib/omniai/chat/choice.rb

@@ -54,13 +54,6 @@ module OmniAI
         }
       end
 
-      # @param other [OmniAI::Chat::Choice]
-      #
-      # @return [OmniAI::Chat::Choice]
-      def merge(other)
-        self.class.new(index: @index, message: @message.merge(other.message))
-      end
-
       # @return [Message]
       def delta
         message

data/lib/omniai/chat/delta.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module OmniAI
+  class Chat
+    # An `OmniAI::Chat::Delta` is used to assist with streaming. It represents a chunk of a conversation that is yielded
+    # back to the caller.
+    class Delta
+      # @!attribute [rw] text
+      #
+      attr_accessor :text
+
+      # @param text [String]
+      def initialize(text:)
+        @text = text
+      end
+
+      # @return [Boolean]
+      def text?
+        !text.empty?
+      end
+    end
+  end
+end

data/lib/omniai/chat/function.rb

@@ -4,10 +4,12 @@ module OmniAI
   class Chat
     # A function that includes a name / arguments.
     class Function
-      # @return [String]
+      # @!attribute [rw] name
+      #   @return [String]
       attr_accessor :name
 
-      # @return [Hash]
+      # @!attribute [rw] arguments
+      #   @return [Hash]
       attr_accessor :arguments
 
       # @param name [String]

data/lib/omniai/chat/message.rb

@@ -47,12 +47,12 @@ module OmniAI
       attr_accessor :role
 
       # @!attribute [rw] tool_call_list
-      #   @return [Array<ToolCall>, nil]
+      #   @return [ToolCallList, nil]
       attr_accessor :tool_call_list
 
       # @param content [String, nil]
       # @param role [String]
-      # @param tool_call_list [Array<ToolCall>, nil]
+      # @param tool_call_list [ToolCallList, nil]
       def initialize(content:, role: Role::USER, tool_call_list: nil)
         @content = content
         @role = role
@@ -86,7 +86,7 @@ module OmniAI
 
         role = data["role"]
         content = Content.deserialize(data["content"], context:)
-        tool_call_list = data["tool_calls"]&.map { |subdata| ToolCall.deserialize(subdata, context:) }
+        tool_call_list = ToolCallList.deserialize(data["tool_calls"], context:)
 
         new(content:, role:, tool_call_list:)
       end
@@ -104,32 +104,11 @@ module OmniAI
         return serializer.call(self, context:) if serializer
 
         content = @content.is_a?(Array) ? @content.map { |content| content.serialize(context:) } : @content
-        tool_calls = @tool_call_list&.map { |tool_call| tool_call.serialize(context:) }
+        tool_calls = @tool_call_list&.serialize(context:)
 
         { role: @role, content:, tool_calls: }.compact
       end
 
-      # @param other [OmniAI::Chat::Message]
-      #
-      # @return [OmniAI::Chat::Message]
-      def merge(other)
-        content =
-          if @content && other.content
-            @content + other.content
-          else
-            @content || other.content
-          end
-
-        tool_call_list =
-          if @tool_call_list && other.tool_call_list
-            @tool_call_list + other.tool_call_list
-          else
-            @tool_call_list || other.tool_call_list
-          end
-
-        self.class.new(content:, role:, tool_call_list:)
-      end
-
       # @return [Boolean]
       def role?(role)
         String(@role).eql?(String(role))

data/lib/omniai/chat/response.rb

@@ -2,68 +2,116 @@
 
 module OmniAI
   class Chat
-    # Used when processing everything at once.
+    # An `OmniAI::Chat::Response` encapsulates the result of generating a chat completion.
     class Response
       # @return [Hash]
       attr_accessor :data
 
+      # @return [Array<Choice>]
+      attr_accessor :choices
+
+      # @return [Usage, nil]
+      attr_accessor :usage
+
       # @param data [Hash]
-      # @param context [Context, nil]
-      def initialize(data:, context: nil)
+      # @param choices [Array<Choice>]
+      # @param usage [Usage, nil]
+      def initialize(data:, choices: [], usage: nil)
         @data = data
-        @context = context
+        @choices = choices
+        @usage = usage
       end
 
-      # @return [Payload]
-      def completion
-        @completion ||= Payload.deserialize(@data, context: @context)
+      # @return [String]
+      def inspect
+        "#<#{self.class.name} choices=#{choices.inspect} usage=#{usage.inspect}>"
       end
 
-      # @return [Usage, nil]
-      def usage
-        completion.usage
-      end
+      # @param data [Hash]
+      # @param context [OmniAI::Context] optional
+      def self.deserialize(data, context: nil)
+        deserialize = context&.deserializer(:response)
+        return deserialize.call(data, context:) if deserialize
 
-      # @return [Array<Choice>]
-      def choices
-        completion.choices
+        choices = data["choices"].map { |choice_data| Choice.deserialize(choice_data, context:) }
+        usage = Usage.deserialize(data["usage"], context:) if data["usage"]
+
+        new(data:, choices:, usage:)
       end
 
-      # @return [Array<Message>]
-      def messages
-        completion.messages
+      # @param context [OmniAI::Context] optional
+      # @return [Hash]
+      def serialize(context:)
+        serialize = context&.serializer(:response)
+        return serialize.call(self, context:) if serialize
+
+        {
+          choices: choices.map { |choice| choice.serialize(context:) },
+          usage: usage&.serialize(context:),
+        }
       end
 
       # @param index [Integer]
-      # @return [Choice]
+      #
+      # @return [Choice, nil]
       def choice(index: 0)
-        completion.choice(index:)
+        @choices[index]
+      end
+
+      # @param index [Integer]
+      #
+      # @return [Boolean]
+      def choice?(index: 0)
+        !choice(index:).nil?
       end
 
       # @param index [Integer]
-      # @return [Message]
+      #
+      # @return [Message, nil]
       def message(index: 0)
-        completion.message(index:)
+        choice(index:)&.message
       end
 
-      # @return [String]
-      def text
-        message.text
+      # @param index [Integer]
+      #
+      # @return [Boolean]
+      def message?
+        !message(index:).nil?
+      end
+
+      # @return [Array<Message>]
+      def messages
+        @choices.map(&:message)
+      end
+
+      # @param index [Integer]
+      #
+      # @return [String, nil]
+      def text(index: 0)
+        message(index:)&.text
       end
 
+      # @param index [Integer]
+      #
       # @return [Boolean]
-      def text?
-        message.text?
+      def text?(index: 0)
+        message = message(index:)
+
+        !message.nil? && message.text?
       end
 
-      # @return [Array<ToolCall>]
-      def tool_call_list
-        choice.tool_call_list
+      # @param index [Integer]
+      #
+      # @return [ToolCallList]
+      def tool_call_list(index: 0)
+        message(index:)&.tool_call_list
       end
 
       # @return [Boolean]
-      def tool_call_list?
-        tool_call_list&.any?
+      def tool_call_list?(index: 0)
+        tool_call_list = tool_call_list(index:)
+
+        !tool_call_list.nil? && tool_call_list.any?
       end
     end
   end

data/lib/omniai/chat/stream.rb

@@ -13,30 +13,32 @@ module OmniAI
     class Stream
       # @param logger [OmniAI::Client]
       # @param chunks [Enumerable<String>]
-      # @param context [Context, nil]
-      def initialize(chunks:, logger: nil, context: nil)
+      def initialize(chunks:, logger: nil)
         @chunks = chunks
         @logger = logger
-        @context = context
       end
 
-      # @yield [payload]
-      # @yieldparam payload [OmniAI::Chat::Payload]
+      # @yield [delta]
+      # @yieldparam delta [OmniAI::Chat::Delta]
       #
-      # @return [OmniAI::Chat::Payload]
+      # @return [Hash]
       def stream!(&block)
-        OmniAI::Chat::Payload.new.tap do |payload|
-          @chunks.map do |chunk|
-            parser.feed(chunk) do |type, data, id|
-              result = process!(type, data, id, &block)
-              payload.merge!(result) if result.is_a?(OmniAI::Chat::Payload)
-            end
+        @data = { "choices" => [] }
+
+        @chunks.map do |chunk|
+          parser.feed(chunk) do |type, data, id|
+            process!(type, data, id, &block)
           end
         end
+
+        @data
       end
 
     protected
 
+      # @yield [delta]
+      # @yieldparam delta [OmniAI::Chat::Delta]
+      #
       # @param type [String]
       # @param data [String]
       # @param id [String]
@@ -50,19 +52,78 @@ module OmniAI
         @logger&.debug("Stream#process! #{arguments.join(' ')}")
       end
 
+      # @yield [delta]
+      # @yieldparam delta [OmniAI::Chat::Delta]
+      #
       # @param type [String]
       # @param data [String]
       # @param id [String]
-      #
-      # @return [OmniAI::Chat::Payload, nil]
-      def process!(type, data, id, &block)
+      def process!(type, data, id, &)
         log(type, data, id)
 
         return if data.eql?("[DONE]")
 
-        payload = Payload.deserialize(JSON.parse(data), context: @context)
-        block&.call(payload)
-        payload
+        process_data!(data: JSON.parse(data), &)
+      end
+
+      # @yield [delta]
+      # @yieldparam delta [OmniAI::Chat::Delta]
+      #
+      # @param data [Hash]
+      def process_data!(data:, &block)
+        data.each do |key, value|
+          @data[key] = value unless key.eql?("choices") || key.eql?("object")
+        end
+
+        data["choices"].each do |choice|
+          merge_choice!(choice:)
+
+          text = choice["delta"]["content"]
+          block&.call(Delta.new(text:)) if text
+        end
+      end
+
+      # @param choice [Hash]
+      def merge_choice!(choice:)
+        index = choice["index"]
+        delta = choice["delta"]
+
+        if @data["choices"][index].nil?
+          @data["choices"][index] = {
+            "index" => index,
+            "message" => delta,
+          }
+        else
+          message = @data["choices"][index]["message"]
+
+          message["content"] += delta["content"] if delta["content"]
+
+          merge_tool_call_list!(tool_call_list: delta["tool_calls"], message:)
+        end
+      end
+
+      # @param tool_call_list [Array<Hash>, nil]
+      # @param message [Hash]
+      def merge_tool_call_list!(tool_call_list:, message:)
+        return unless tool_call_list
+
+        message["tool_calls"] ||= []
+
+        tool_call_list.each do |tool_call|
+          merge_tool_call_data!(tool_call:, message:)
+        end
+      end
+
+      # @param tool_call [Hash]
+      # @param message [Hash]
+      def merge_tool_call_data!(tool_call:, message:)
+        tool_call_index = tool_call["index"]
+
+        if message["tool_calls"][tool_call_index].nil?
+          message["tool_calls"][tool_call_index] = tool_call
+        else
+          message["tool_calls"][tool_call_index]["function"]["arguments"] += tool_call["function"]["arguments"]
+        end
       end
 
       # @return [EventStreamParser::Parser]

data/lib/omniai/chat/tool_call.rb

@@ -4,10 +4,12 @@ module OmniAI
   class Chat
     # A tool-call that includes an ID / function.
     class ToolCall
-      # @return [String]
+      # @!attribute [rw] id
+      #   @return [String]
       attr_accessor :id
 
-      # @return [Function]
+      # @!attribute [rw] function
+      #   @return [Function]
       attr_accessor :function
 
       # @param id [String]
@@ -25,7 +27,7 @@ module OmniAI
       # @param data [Hash]
       # @param context [Context] optional
       #
-      # @return [Function]
+      # @return [ToolCall]
       def self.deserialize(data, context: nil)
         deserialize = context&.deserializer(:tool_call)
         return deserialize.call(data, context:) if deserialize

data/lib/omniai/chat/tool_call_list.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module OmniAI
+  class Chat
+    # An `OmniAI::Chat::ToolCallList` is a collection designed to handle the merging of multiple tool call arrays. LLMs
+    # provide a subset of tool call items when chunking, so merging requires the use of the tool call index to combine.
+    class ToolCallList
+      include Enumerable
+
+      # @param entries [Array<ToolCall>]
+      def initialize(entries: [])
+        @entries = entries
+      end
+
+      # Usage:
+      #
+      #   ToolCallList.deserialize([]) # => #<ToolCallList ...>
+      #
+      # @param data [Array]
+      # @param context [Context] optional
+      #
+      # @return [ToolCallList]
+      def self.deserialize(data, context: nil)
+        return unless data
+
+        new(entries: data.map { |subdata| ToolCall.deserialize(subdata, context:) })
+      end
+
+      # Usage:
+      #
+      #   tool_call_list.serialize # => [...]
+      #
+      # @param context [Context] optional
+      #
+      # @return [Array<Hash>]
+      def serialize(context: nil)
+        @entries.compact.map { |tool_call| tool_call.serialize(context:) }
+      end
+
+      # @return [String]
+      def inspect
+        "#<#{self.class.name} entries=#{@entries.inspect}>"
+      end
+
+      # @yield toolcall
+      # @yieldparam toolcall [ToolCall]
+      def each(&)
+        @entries.each(&)
+      end
+    end
+  end
+end

data/lib/omniai/chat/tool_call_message.rb

@@ -28,7 +28,7 @@ module OmniAI
       #
       # @return [ToolMessage]
       def self.deserialize(data, context: nil)
-        deserialize = context&.deserializer(:tool_message)
+        deserialize = context&.deserializer(:tool_call_message)
         return deserialize.call(data, context:) if deserialize
 
         role = data["role"]
@@ -47,7 +47,7 @@ module OmniAI
       #
       # @return [Hash]
       def serialize(context: nil)
-        serializer = context&.serializer(:tool_message)
+        serializer = context&.serializer(:tool_call_message)
         return serializer.call(self, context:) if serializer
 
         role = @role

data/lib/omniai/chat.rb

@@ -86,12 +86,25 @@ module OmniAI
     end
 
     # @raise [HTTPError]
+    #
+    # @return [OmniAI::Chat::Response]
     def process!
       response = request!
 
       raise HTTPError, response.flush unless response.status.ok?
 
-      parse!(response:)
+      completion = parse!(response:)
+
+      if @tools && completion.tool_call_list?
+        spawn!(
+          @prompt.dup.tap do |prompt|
+            prompt.messages += completion.messages
+            prompt.messages += build_tool_call_messages(completion.tool_call_list)
+          end
+        ).process!
+      else
+        completion
+      end
     end
 
   protected
@@ -135,6 +148,7 @@ module OmniAI
     end
 
     # @param response [HTTP::Response]
+    #
     # @return [OmniAI::Chat::Response]
     def parse!(response:)
       if @stream
@@ -145,32 +159,22 @@ module OmniAI
     end
 
     # @param response [HTTP::Response]
+    #
     # @return [OmniAI::Chat::Response]
     def complete!(response:)
-      completion = self.class::Response.new(data: response.parse, context:)
-
-      if @tools && completion.tool_call_list?
-        spawn!(
-          @prompt.dup.tap do |prompt|
-            prompt.messages += completion.messages
-            prompt.messages += build_tool_call_messages(completion.tool_call_list)
-          end
-        ).process!
-      else
-        completion
-      end
+      OmniAI::Chat::Response.deserialize(response.parse, context:)
     end
 
     # @param response [HTTP::Response]
     #
-    # @return [OmniAI::Chat::Payload]
+    # @return [OmniAI::Chat::Response]
     def stream!(response:)
       raise Error, "#{self.class.name}#stream! unstreamable" unless @stream
 
-      payload = self.class::Stream.new(chunks: response.body, logger:, context:).stream! do |chunk|
+      data = self.class::Stream.new(chunks: response.body, logger:).stream! do |chunk|
         case @stream
         when IO, StringIO
-          if chunk.text
+          if chunk.text?
             @stream << chunk.text
             @stream.flush
           end
@@ -178,9 +182,11 @@ module OmniAI
         end
       end
 
-      @stream.puts if @stream.is_a?(IO) || @stream.is_a?(StringIO)
+      response = OmniAI::Chat::Response.deserialize(data, context:)
+
+      @stream.puts if response.text? && (@stream.is_a?(IO) || @stream.is_a?(StringIO))
 
-      payload
+      response
     end
 
     # @return [HTTP::Response]

data/lib/omniai/client.rb

@@ -134,7 +134,7 @@ module OmniAI
     # @yield [prompt] optional
     # @yieldparam prompt [OmniAI::Chat::Prompt]
     #
-    # @return [OmniAI::Chat::Completion]
+    # @return [OmniAI::Chat::Response]
     def chat(messages = nil, model:, temperature: nil, format: nil, stream: nil, tools: nil, &)
       raise NotImplementedError, "#{self.class.name}#chat undefined"
     end

data/lib/omniai/tool/property.rb

@@ -28,6 +28,19 @@ module OmniAI
       # @return [Array<String>, nil]
       attr_reader :enum
 
+      # @param kind [Symbol]
+      # @return [OmniAI::Tool::Property]
+      def self.build(kind, **args)
+        case kind
+        when :array then array(**args)
+        when :object then object(**args)
+        when :boolean then boolean(**args)
+        when :integer then integer(**args)
+        when :string then string(**args)
+        when :number then number(**args)
+        end
+      end
+
       # @example
       #   property = OmniAI::Tool::Property.array(
       #     items: OmniAI::Tool::Property.string(description: 'The name of the person.'),

data/lib/omniai/tool.rb

@@ -3,40 +3,82 @@
 module OmniAI
   # Usage:
   #
-  #   fibonacci = proc do |n:|
-  #     next(0) if n == 0
-  #     next(1) if n == 1
-  #     fibonacci.call(n: n - 1) + fibonacci.call(n: n - 2)
-  #   end
+  #   class Weather < OmniAI::Tool
+  #     description 'Find the weather for a location'
+  #
+  #     parameter :location, :string, description: 'The location to find the weather for (e.g. "Toronto, Canada").'
+  #     parameter :unit, :string, description: 'The unit of measurement (e.g. "Celcius" or "Fahrenheit").'
+  #     required %i[location]
   #
-  #   tool = OmniAI::Tool.new(fibonacci,
-  #     name: 'Fibonacci',
-  #     description: 'Cacluate the nth Fibonacci',
-  #     parameters: OmniAI::Tool::Parameters.new(
-  #       properties: {
-  #         n: OmniAI::Tool::Property.integer(description: 'The nth Fibonacci number to calculate')
-  #       },
-  #       required: %i[n],
-  #      )
-  #   )
+  #     def execute!(location:)
+  #       # ...
+  #     end
+  #   end
   class Tool
-    # @return [Proc]
+    class << self
+      # @param description [String]
+      def description(description = nil)
+        return @description if description.nil?
+
+        @description = description
+      end
+
+      # @return [OmniAI::Tool::Parameters]
+      def parameters
+        @parameters ||= Parameters.new
+      end
+
+      # @param name [Symbol]
+      # @param kind [Symbol]
+      def parameter(name, kind, **)
+        parameters.properties[name] = Property.build(kind, **)
+      end
+
+      # @param names [Array<Symbol>]
+      def required(names)
+        parameters.required = names
+      end
+
+      # Converts a class name to a tool:
+      #  - e.g. "IBM::Watson::SearchTool" => "ibm_watson_search"
+      #
+      # @return [String]
+      def namify
+        name
+          .gsub("::", "_")
+          .gsub(/(?<prefix>[A-Z+])(?<suffix>[A-Z][a-z])/, '\k<prefix>_\k<suffix>')
+          .gsub(/(?<prefix>[a-z])(?<suffix>[A-Z])/, '\k<prefix>_\k<suffix>')
+          .gsub(/_tool$/i, "")
+          .downcase
+      end
+    end
+
+    # @!attribute [rw] function
+    #   @return [Proc]
     attr_accessor :function
 
-    # @return [String]
+    # @!attribute [rw] name
+    #   @return [String]
     attr_accessor :name
 
-    # @return [String, nil]
+    # @!attribute [description]
+    #   @return [String, nil]
     attr_accessor :description
 
-    # @return [Hash, nil]
+    # @!attribute[parameters]
+    #   @return [Hash, nil]
     attr_accessor :parameters
 
     # @param function [Proc]
     # @param name [String]
     # @param description [String]
     # @param parameters [Hash]
-    def initialize(function, name:, description: nil, parameters: nil)
+    def initialize(
+      function = method(:execute),
+      name: self.class.namify,
+      description: self.class.description,
+      parameters: self.class.parameters
+    )
       @function = function
       @name = name
       @description = description
@@ -79,6 +121,10 @@ module OmniAI
       }
     end
 
+    def execute(...)
+      raise NotImplementedError, "#{self.class}#execute undefined"
+    end
+
     # @example
     #   tool.call({ "n" => 6 })
     #   #=> 8

data/lib/omniai/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OmniAI
-  VERSION = "1.9.6"
+  VERSION = "2.1.0"
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: omniai
 version: !ruby/object:Gem::Version
-  version: 1.9.6
+  version: 2.1.0
 platform: ruby
 authors:
 - Kevin Sylvestre
 bindir: exe
 cert_chain: []
-date: 2025-02-27 00:00:00.000000000 Z
+date: 2025-03-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: event_stream_parser
@@ -83,17 +83,18 @@ files:
 - lib/omniai/chat.rb
 - lib/omniai/chat/choice.rb
 - lib/omniai/chat/content.rb
+- lib/omniai/chat/delta.rb
 - lib/omniai/chat/file.rb
 - lib/omniai/chat/function.rb
 - lib/omniai/chat/media.rb
 - lib/omniai/chat/message.rb
 - lib/omniai/chat/message/builder.rb
-- lib/omniai/chat/payload.rb
 - lib/omniai/chat/prompt.rb
 - lib/omniai/chat/response.rb
 - lib/omniai/chat/stream.rb
 - lib/omniai/chat/text.rb
 - lib/omniai/chat/tool_call.rb
+- lib/omniai/chat/tool_call_list.rb
 - lib/omniai/chat/tool_call_message.rb
 - lib/omniai/chat/tool_call_result.rb
 - lib/omniai/chat/url.rb

data/lib/omniai/chat/payload.rb

@@ -1,107 +0,0 @@
-# frozen_string_literal: true
-
-module OmniAI
-  class Chat
-    # A chunk or completion.
-    class Payload
-      # @return [Array<Choice>]
-      attr_accessor :choices
-
-      # @return [Usage, nil]
-      attr_accessor :usage
-
-      # @param choices [Array<Choice>]
-      # @param usage [Usage, nil]
-      def initialize(choices: [], usage: nil)
-        @id = SecureRandom.alphanumeric
-        @choices = choices
-        @usage = usage
-      end
-
-      # @return [String]
-      def inspect
-        "#<#{self.class.name} choices=#{choices.inspect} usage=#{usage.inspect}>"
-      end
-
-      # @param data [Hash]
-      # @param context [OmniAI::Context] optional
-      def self.deserialize(data, context: nil)
-        deserialize = context&.deserializer(:payload)
-        return deserialize.call(data, context:) if deserialize
-
-        choices = data["choices"].map { |choice_data| Choice.deserialize(choice_data, context:) }
-        usage = Usage.deserialize(data["usage"], context:) if data["usage"]
-
-        new(choices:, usage:)
-      end
-
-      # @param context [OmniAI::Context] optional
-      # @return [Hash]
-      def serialize(context:)
-        serialize = context&.serializer(:payload)
-        return serialize.call(self, context:) if serialize
-
-        {
-          choices: choices.map { |choice| choice.serialize(context:) },
-          usage: usage&.serialize(context:),
-        }
-      end
-
-      # @param other [OmniAI::Chat::Payload]
-      def merge!(other)
-        return unless other
-
-        @usage = other.usage if other.usage
-
-        other.choices.each do |choice|
-          if choice?(index: choice.index)
-            choices[choice.index] = choices[choice.index].merge(choice)
-          else
-            @choices[choice.index] = choice
-          end
-        end
-      end
-
-      # @param index [Integer]
-      # @return [Choice]
-      def choice(index: 0)
-        @choices[index]
-      end
-
-      # @param index [Integer]
-      # @return [Boolean]
-      def choice?(index: 0)
-        !choice(index:).nil?
-      end
-
-      # @param index [Integer]
-      # @return [Message]
-      def message(index: 0)
-        choice(index:).message
-      end
-
-      # @return [Array<Message>]
-      def messages
-        @choices.map(&:message)
-      end
-
-      # @param index [Integer]
-      # @return [String, nil]
-      def text(index: 0)
-        message(index:).text
-      end
-
-      # @param index [Integer]
-      # @return [Boolean]
-      def text?(index: 0)
-        message(index:).text?
-      end
-
-      # @param index [Integer]
-      # @return [Array<ToolCall>]
-      def tool_call_list(index:)
-        message(index:).tool_call_list
-      end
-    end
-  end
-end