omniai 2.5.0 → 2.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 89f3eb0b1c62e35bc437833ad64c2c48504ead7bab049b1fc13cbdde30f5c6fe
-  data.tar.gz: bd8f3e7692996e622e245bd82f4fccc86df703836062d9542d59ec8119e09fe7
+  metadata.gz: 488be723c0a59ca0095eb3a1f64081cceff14ae982208e598da5058ee0ea0c4b
+  data.tar.gz: 47805f82344429912eaa2e0f00299cc95868d35d04a6d424f698b719bf9d0fe8
 SHA512:
-  metadata.gz: eb4748a2dc375e1e36dc096605adacd9822e9f7217ffb5a5c0516bbd21f18228dfdcc329346308ccc9b7a114bc24ee2a5abf04e3c09e06ee50cceac72f8f6d09
-  data.tar.gz: 6c814845c8fed1e20a042abe94c9ba74227f671a00b9551c79b1b12faedac2a7a998e9a325c942e8b07bdc1ebe55f62ef13563eb982b07ef27b9046695b00295
+  metadata.gz: 1c0d66e74c7a0e1eb0296e371b0339d44cedbb7a747c2beeb7cb0547303140d0a6550fd8d7fc6629c09804c57cfcf780dec38f01f6c8aac49004ab28e9968872
+  data.tar.gz: aeb129f452a6ea0a9c2e33a25afbe5f8be1e7b27445fb58399556e7bdd0475b0840b36465c6b33edbdf857c6d943c10824b0cc21b7e6a917d161829e4ca033a6

data/README.md

@@ -88,40 +88,70 @@ require 'omniai/google'
 
 client = OmniAI::Google::Client.new
 
-class Weather < OmniAI::Tool
-  description "Lookup the weather for a location"
+class WeatherTool < OmniAI::Tool
+  description "Lookup the weather for a lat / lng."
 
-  parameter :location, :string, description: "A location (e.g. 'Toronto, Canada')."
+  parameter :lat, :number, description: "The latitude of the location."
+  parameter :lng, :number, description: "The longitude of the location."
   parameter :unit, :string, enum: %w[Celsius Fahrenheit], description: "The unit of measurement."
+  required %i[lat lng]
+
+  # @param lat [Float]
+  # @param lng [Float]
+  # @param unit [String] "Celsius" or "Fahrenheit"
+  #
+  # @return [String] e.g. "20° Celsius at lat=43.7 lng=-79.4"
+  def execute(lat:, lng:, unit: "Celsius")
+    puts "[weather] lat=#{lat} lng=#{lng} unit=#{unit}"
+    "#{rand(20..50)}° #{unit} at lat=#{lat} lng=#{lng}"
+  end
+end
+
+class GeocodeTool < OmniAI::Tool
+  description "Lookup the latitude and longitude of a location."
+
+  parameter :location, :string, description: "The location to geocode."
   required %i[location]
 
-  # @param location [String] required
-  # @param unit [String] optional - "Celsius" or "Fahrenheit"
-  # @return [String]
-  def execute(location:, unit: "Celsius")
-    puts "[weather] location=#{location} unit=#{unit}"
-    "#{rand(20..50)}° #{unit} at #{location}"
+  # @param location [String] "Toronto, Canada"
+  #
+  # @return [Hash] { lat: Float, lng: Float, location: String }
+  def execute(location:)
+    puts "[geocode] location=#{location}"
+
+    {
+      lat: rand(-90.0..+90.0),
+      lng: rand(-180.0..+180.0),
+      location:,
+    }
   end
 end
 
-client.chat(stream: $stdout, tools: [Weather.new]) do |prompt|
+tools = [
+  WeatherTool.new,
+  GeocodeTool.new,
+]
+
+client.chat(stream: $stdout, tools:) 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
 ```
 
 ```
-[weather] location=London unit=Celsius
-[weather] location=Madrid unit=Fahrenheit
-```
+[geocode] location=London
+[weather] lat=... lng=... unit=Celsius
+[geocode] location=Madrid
+[weather] lat=... lng=... unit=Fahrenheit
 
-```
 The weather is 24° Celsius in London and 42° Fahrenheit in Madrid.
 ```
 
+_For a set of pre-built tools for interacting with browsers, databases, docker, and more try the [OmniAI::Tools](https://omniai-tools.ksylvest.com/) project._
+
 ### Example #5: [Chat w/ History](https://github.com/ksylvest/omniai/blob/main/examples/chat_with_history)
 
-Tracking a prompt history over multiple user and assistant messages is especially helpful when building an agent like conversation experience. A prompt can be used to track this back and forth conversation:
+Tracking a prompt history over multiple user and assistant messages is especially helpful when building an agent like conversation experience. A prompt can be used to track this back-and-forth conversation:
 
 ```ruby
 require "omniai/openai"
@@ -146,19 +176,59 @@ loop do
 end
 ```
 
-```
-Type 'exit' or 'quit' to leave.
+### Example #6 [Chat w/ Schema](https://github.com/ksylvest/omniai/blob/main/examples/chat_with_schema)
 
-> What is the capital of France?
-The capital of France is Paris.
-La capitale de la France est Paris.
+Requesting structured data back from an LLM is possible by defining a schema, then passing the schema into the chat. The following example defines a structured schema using `OmniAI::Schema` to model a `Contact`. The results of the LLM call are then parsed using the schema to ensure all types are correct.
 
-> How many people live there?
-The population of Paris is approximately 2.1 million.
-La population de Paris est d’environ 2,1 million.
+```ruby
+format = OmniAI::Schema.format(name: "Contact", schema: OmniAI::Schema.object(
+  description: "A contact with a name, relationship, and addresses.",
+  properties: {
+    name: OmniAI::Schema.string,
+    relationship: OmniAI::Schema.string(enum: %w[friend family]),
+    addresses: OmniAI::Schema.array(
+      items: OmniAI::Schema.object(
+        title: "Address",
+        description: "An address with street, city, state, and zip code.",
+        properties: {
+          street: OmniAI::Schema.string,
+          city: OmniAI::Schema.string,
+          state: OmniAI::Schema.string,
+          zip: OmniAI::Schema.string,
+        },
+        required: %i[street city state zip]
+      )
+    ),
+  },
+  required: %i[name]
+))
+
+response = client.chat(format:) do |prompt|
+  prompt.user <<~TEXT
+    Parse the following contact:
+
+    NAME: George Harrison
+    RELATIONSHIP: friend
+    HOME: 123 Main St, Springfield, IL, 12345
+    WORK: 456 Elm St, Springfield, IL, 12345
+  TEXT
+end
+
+puts format.parse(response.text)
 ```
 
-### Example #6: [Chat w/ CLI](https://github.com/ksylvest/omniai/blob/main/examples/chat_with_cli)
+```
+{
+  name: "George Harrison",
+  relationship: "friend",
+  addresses: [
+    { street: "123 Main St", city: "Springfield", state: "IL", zip: "12345" },
+    { street: "456 Elm St", city: "Springfield", state: "IL", zip: "12345" },
+  ]
+}
+```
+
+### Example #7: [Chat w/ CLI](https://github.com/ksylvest/omniai/blob/main/examples/chat_with_cli)
 
 The `OmniAI` gem also ships with a CLI to simplify quick tests.
 
@@ -178,7 +248,7 @@ omniai chat --provider="google" --model="gemini-2.0-flash" "Who are you?"
 I am a large language model, trained by Google.
 ```
 
-### Example #7: [Text-to-Speech](https://github.com/ksylvest/omniai/blob/main/examples/text_to_speech)
+### Example #8: [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.
 
@@ -194,7 +264,7 @@ File.open(File.join(__dir__, 'audio.wav'), 'wb') do |file|
 end
 ```
 
-### Example #8: [Speech-to-Text](https://github.com/ksylvest/omniai/blob/main/examples/speech_to_text)
+### Example #9: [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.
 
@@ -209,7 +279,7 @@ File.open(File.join(__dir__, 'audio.wav'), 'rb') do |file|
 end
 ```
 
-### Example #9: [Embeddings](https://github.com/ksylvest/omniai/blob/main/examples/embeddings)
+### Example #10: [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.
 
@@ -355,10 +425,10 @@ require 'omniai/openai'
 require 'logger'
 
 logger = Logger.new(STDOUT)
-client = OmniAI::OpenAI::Client.new(timeout: 8) # i.e. 8 seconds
+client = OmniAI::OpenAI::Client.new(timeout: 8) # 8 seconds
 ```
 
-Timeouts are also 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'
@@ -415,7 +485,7 @@ client.chat('Tell me a joke.', stream:)
 
 #### Completion using Streaming via IO
 
-The above code can also be supplied any IO (e.g. `File`, `$stdout`, `$stdin`, etc):
+The above code can also be supplied with any IO object (e.g., `File`, `$stdout`, `$stdin`, etc.):
 
 ```ruby
 client.chat('Tell me a story', stream: $stdout)
@@ -423,22 +493,31 @@ client.chat('Tell me a story', stream: $stdout)
 
 #### Completion with Tools
 
-A chat can also be initialized with tools:
+A chat can also be initialized using tools:
 
 ```ruby
-tool = OmniAI::Tool.new(
-  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[Celsius Fahrenheit]),
-    },
-    required: %i[location]
-  )
-)
-client.chat('What is the weather in "London" in Celsius and "Paris" in Fahrenheit?', tools: [tool])
+class WeatherTool
+  description "Lookup the weather at a location in either Celsius or Fahrenheit."
+
+  parameter :location, :string, description: "The location to find the weather."
+  parameter :unit, :string, enum: %w[Celsius Fahrenheit], description: "The unit of measurement."
+  required %i[location]
+
+  # @param location [String]
+  # @param unit [String] "Celsius" or "Fahrenheit"
+  #
+  # @return [Hash]
+  def execute(location:, unit: "Celsius")
+    puts "[weather] location=#{location} unit=#{unit}"
+
+    {
+      temperature: "#{rand(20..50)}°",
+      humidity: rand(0..100),
+    }
+  end
+end
+
+client.chat('What is the weather in "London" in Celsius and "Paris" in Fahrenheit?', tools: [WeatherTool.new])
 ```
 
 ### Transcribe
@@ -463,7 +542,7 @@ end
 
 ### Speak
 
-Clients that support speak (e.g. OpenAI w/ "Whisper") convert text to recordings via the following calls:
+Clients that support speak (e.g. OpenAI w/ "Whisper") convert text to speech via the following calls:
 
 #### Speech with Stream
 
@@ -493,12 +572,12 @@ response.usage # <OmniAI::Embed::Usage prompt_tokens=5 total_tokens=5>
 response.embedding # [0.1, 0.2, ...] >
 ```
 
-Batches of text can also be converted to embeddings via the following:
+Theese APIs support generating embeddings in batches using the following code:
 
 ```ruby
 response = client.embed([
-  '',
-  '',
+  'The quick brown fox jumps over a lazy dog',
+  'Pack my box with five dozen liquor jugs',
 ])
 response.usage # <OmniAI::Embed::Usage prompt_tokens=5 total_tokens=5>
 response.embeddings.each do |embedding|
@@ -508,7 +587,7 @@ end
 
 ## CLI
 
-OmniAI packages a basic command line interface (CLI) to allow for exploration of various APIs. A detailed CLI documentation can be found via help:
+OmniAI packages a basic command line interface (CLI) to allow for exploration of various APIs. CLI documentation is available with the `--help` flag:
 
 ```bash
 omniai --help

data/lib/omniai/chat/message.rb

@@ -103,7 +103,13 @@ module OmniAI
         serializer = context&.serializer(:message)
         return serializer.call(self, context:) if serializer
 
-        content = @content.is_a?(Array) ? @content.map { |content| content.serialize(context:) } : @content
+        content =
+          case @content
+          when Array then @content.map { |content| content.serialize(context:) }
+          when Content then @content.serialize(context:)
+          else @content
+          end
+
         tool_calls = @tool_call_list&.serialize(context:)
 
         { role: @role, content:, tool_calls: }.compact

data/lib/omniai/chat/response.rb

@@ -29,6 +29,8 @@ module OmniAI
 
       # @param data [Hash]
       # @param context [OmniAI::Context] optional
+      #
+      # @return [OmniAI::Chat::Response]
       def self.deserialize(data, context: nil)
         deserialize = context&.deserializer(:response)
         return deserialize.call(data, context:) if deserialize

data/lib/omniai/chat.rb

@@ -65,7 +65,7 @@ module OmniAI
     # @param temperature [Float, nil] optional
     # @param stream [Proc, IO, nil] optional
     # @param tools [Array<OmniAI::Tool>] optional
-    # @param format [Symbol, nil] optional - :json
+    # @param format [:json, :text, OmniAI::Schema::Object, nil] optional
     #
     # @yield [prompt] optional
     # @yieldparam prompt [OmniAI::Chat::Prompt]

data/lib/omniai/client.rb

@@ -34,69 +34,93 @@ module OmniAI
 
     # Initialize a client for Anthropic. This method requires the provider if it is undefined.
     #
-    # @raise [OmniAI::Error] if the provider is not defined and the gem is not installed
+    # @raise [OmniAI::LoadError] if the provider is not defined and the gem is not installed
     #
     # @return [Class<OmniAI::Client>]
     def self.anthropic
       require "omniai/anthropic" unless defined?(OmniAI::Anthropic::Client)
       OmniAI::Anthropic::Client
     rescue ::LoadError
-      raise Error, "requires 'omniai-anthropic': `gem install omniai-anthropic`"
+      raise LoadError, "requires 'omniai-anthropic': `gem install omniai-anthropic`"
     end
 
     # Initialize a client for DeepSeek. This method requires the provider if it is undefined.
     #
-    # @raise [OmniAI::Error] if the provider is not defined and the gem is not installed
+    # @raise [OmniAI::LoadError] if the provider is not defined and the gem is not installed
     #
     # @return [Class<OmniAI::Client>]
     def self.deepseek
       require "omniai/deepseek" unless defined?(OmniAI::DeepSeek::Client)
       OmniAI::DeepSeek::Client
     rescue ::LoadError
-      raise Error, "requires 'omniai-deepseek': `gem install omniai-deepseek`"
+      raise LoadError, "requires 'omniai-deepseek': `gem install omniai-deepseek`"
     end
 
     # Lookup the `OmniAI::Google::Client``. This method requires the provider if it is undefined.
     #
-    # @raise [OmniAI::Error] if the provider is not defined and the gem is not installed
+    # @raise [OmniAI::LoadError] if the provider is not defined and the gem is not installed
     #
     # @return [Class<OmniAI::Client>]
     def self.google
       require "omniai/google" unless defined?(OmniAI::Google::Client)
       OmniAI::Google::Client
     rescue ::LoadError
-      raise Error, "requires 'omniai-google': `gem install omniai-google`"
+      raise LoadError, "requires 'omniai-google': `gem install omniai-google`"
     end
 
     # Initialize a client for Mistral. This method requires the provider if it is undefined.
     #
-    # @raise [OmniAI::Error] if the provider is not defined and the gem is not installed
+    # @raise [OmniAI::LoadError] if the provider is not defined and the gem is not installed
     #
     # @return [Class<OmniAI::Client>]
     def self.mistral
       require "omniai/mistral" unless defined?(OmniAI::Mistral::Client)
       OmniAI::Mistral::Client
     rescue ::LoadError
-      raise Error, "requires 'omniai-mistral': `gem install omniai-mistral`"
+      raise LoadError, "requires 'omniai-mistral': `gem install omniai-mistral`"
     end
 
     # Initialize a client for OpenAI. This method requires the provider if it is undefined.
     #
-    # @raise [OmniAI::Error] if the provider is not defined and the gem is not installed
+    # @raise [OmniAI::LoadError] if the provider is not defined and the gem is not installed
     #
     # @return [Class<OmniAI::Client>]
     def self.openai
       require "omniai/openai" unless defined?(OmniAI::OpenAI::Client)
       OmniAI::OpenAI::Client
     rescue ::LoadError
-      raise Error, "requires 'omniai-openai': `gem install omniai-openai`"
+      raise LoadError, "requires 'omniai-openai': `gem install omniai-openai`"
+    end
+
+    # Discover a client by provider ('openai' then 'anthropic' then 'google' then 'mistral' then 'deepseek').
+    #
+    # @raise [OmniAI::LoadError] if no providers are installed
+    #
+    # @return [OmniAI::Client]
+    def self.discover(**)
+      %i[openai anthropic google mistral deepseek].each do |provider|
+        return find(provider:, **)
+      rescue LoadError
+        next
+      end
+
+      raise LoadError, <<~TEXT
+        requires 'omniai-openai' or 'omniai-anthropic' or 'openai-deepseek' or 'omniai-google' or 'omniai-mistral':
+
+          `gem install omniai-openai`
+          `gem install omniai-anthropic`
+          `gem install omniai-deepseek`
+          `gem install omniai-google`
+          `gem install omniai-mistral`
+      TEXT
     end
 
     # Initialize a client by provider (e.g. 'openai'). This method attempts to require the provider.
     #
-    # @param provider [String, Symbol] required (e.g. 'anthropic', 'deepsek', 'google', 'mistral', 'openai', etc)
     #
-    # @raise [OmniAI::Error] if the provider is not defined and the gem is not installed
+    # @param provider [String, Symbol] required (e.g. 'anthropic', 'deepseek', 'google', 'mistral', 'openai', etc)
+    #
+    # @raise [OmniAI::LoadError] if the provider is not defined and the gem is not installed
     #
     # @return [OmniAI::Client]
     def self.find(provider:, **)

data/lib/omniai/load_error.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module OmniAI
+  # An error that wraps a ::LoadError for a missing library.
+  class LoadError < Error
+  end
+end

data/lib/omniai/schema/array.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module OmniAI
+  module Schema
+    # @example
+    #    array = OmniAI::Tool::Array.deserialize({
+    #      description: "A list of people.",
+    #      items: {
+    #        properties: {
+    #          name: { type: "string" },
+    #        },
+    #        required: ["name"],
+    #      },
+    #      min_items: 1,
+    #      max_items: 5,
+    #    })
+    #    array.serialize # => { type: "array", items: { ... }, minItems: 1, maxItems: 5 }
+    #    array.parse([{ "name" => "Ringo Starr" }]) # => [{ name: "Ringo Star" }]
+    class Array
+      TYPE = "array"
+
+      # @!attribute [rw] items
+      #   @return [OmniAI::Schema::Object, OmniAI::Schema::Array, OmniAI::Schema::Scalar]
+      attr_accessor :items
+
+      # @!attribute [rw] max_items
+      #   @return [Integer, nil]
+      attr_accessor :max_items
+
+      # @!attribute [rw] min_items
+      #   @return [Integer, nil]
+      attr_accessor :min_items
+
+      # @!attribute [rw] description
+      #   @return [String, nil]
+      attr_accessor :description
+
+      # @example
+      #   array = OmniAI::Schema::Array.deserialize({
+      #     type: "array",
+      #     items: { type: "string" },
+      #     minItems: 1,
+      #     maxItems: 5,
+      #     description: "A list of strings."
+      #   }) # => OmniAI::Schema::Array
+      #
+      # @param data [Hash]
+      #
+      # @return [OmniAI::Schema::Array]
+      def self.deserialize(data)
+        new(
+          items: OmniAI::Schema.deserialize(data["items"] || data[:items]),
+          max_items: data[:maxItems] || data["maxItems"],
+          min_items: data[:minItems] || data["minItems"],
+          description: data[:description] || data["description"]
+        )
+      end
+
+      # @param items [OmniAI::Schema::Object, OmniAI::Schema::Array, OmniAI::Schema::Scalar] required
+      # @param min_items [Integer] optional
+      # @param max_items [Integer] optional
+      # @param description [String] optional
+      def initialize(items:, min_items: nil, max_items: nil, description: nil)
+        super()
+        @items = items
+        @min_items = min_items
+        @max_items = max_items
+        @description = description
+      end
+
+      # @example
+      #   array.serialize # => { type: "array", items: { type: "string" } }
+      #
+      # @return [Hash]
+      def serialize
+        {
+          type: TYPE,
+          description: @description,
+          items: @items.serialize,
+          maxItems: @max_items,
+          minItems: @min_items,
+        }.compact
+      end
+
+      # @example
+      #   array.parse(["1", "2", "3"]) # => [1, 2, 3]
+      #
+      # @param data [Array]
+      #
+      # @return [Array]
+      def parse(data)
+        data.map { |arg| @items.parse(arg) }
+      end
+    end
+  end
+end

data/lib/omniai/schema/format.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module OmniAI
+  module Schema
+    # @example
+    #   format = OmniAI::Schema::Format.deserialize({
+    #     name: "example",
+    #     schema: {
+    #       type: "object",
+    #       properties: {
+    #         name: { type: "string" },
+    #       },
+    #       required: ["name"],
+    #     }
+    #   })
+    #   format.serialize # => { name: "example", schema: { ... } }
+    class Format
+      # @!attribute [rw] name
+      #   @return [String]
+      attr_accessor :name
+
+      # @!attribute [rw] schema
+      #   @return [OmniAI::Schema::Object]
+      attr_accessor :schema
+
+      # @example
+      #   array = OmniAI::Schema::Format.deserialize({
+      #     name: "Contact",
+      #     schema: { ... },
+      #   }) # => OmniAI::Schema::Format
+      #
+      # @param data [Hash]
+      #
+      # @return [OmniAI::Schema::Format]
+      def self.deserialize(data)
+        name = data["name"] || data[:name]
+        schema = OmniAI::Schema.deserialize(data["schema"] || data[:schema])
+
+        new(name:, schema:)
+      end
+
+      # @param name [String]
+      # @param schema [OmniAI::Schema::Object]
+      def initialize(name:, schema:)
+        @name = name
+        @schema = schema
+      end
+
+      # @example
+      #   format.serialize # => { name: "...", schema: { ... } }
+      #
+      # @return [Hash]
+      def serialize
+        {
+          name:,
+          schema: schema.serialize,
+        }
+      end
+
+      # @example
+      #   format.parse("{ "name": "Ringo Starr" }"") # => { name: "Ringo Starr" }
+      #
+      # @param text [String]
+      #
+      # @return [Hash]
+      def parse(text)
+        schema.parse(JSON.parse(text))
+      end
+    end
+  end
+end