omniai 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 116095cbb73cb4e826fe28a4c644e37ea1ecb887d601b0ca4cbdc3a70e0ca81e
-  data.tar.gz: d17b5078d80e7cf6858b0e77e22d5949c157841672aa5bbe54a2782e8e10df31
+  metadata.gz: c58b1fbebfaaaa7bcd77fe9754d0bf0bddc7b55c07b76ae31cbae0ae24b2024f
+  data.tar.gz: d4462dbf00a04ce81db7f8bf7c4f45018aaab994fd2699483e8b2de324546ab2
 SHA512:
-  metadata.gz: 5b3a610780db624592fab65b2437ac552de7dd9f7d5c4f6ec62aff546720db832a40f4a7e24e68d64f42ce84dff24ed73a3105a08c37c61f00faa83d65fd55ca
-  data.tar.gz: 5000a20feca11ee1e29b03d71885d4e75aa6792a39ac828ae78b3fcae5783430f65fe93b209350aa3399dfc7cce1ccbadc0a844518e0ccb772d0b8704f304cc3
+  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/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 = "2.0.0"
+  VERSION = "2.1.0"
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: omniai
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.1.0
 platform: ruby
 authors:
 - Kevin Sylvestre
 bindir: exe
 cert_chain: []
-date: 2025-03-03 00:00:00.000000000 Z
+date: 2025-03-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: event_stream_parser