omniai 2.6.0 → 2.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6b8a243fb8313c7c1fe3a483cdac33892f1b764cac19c38465a880e3f8a790f0
-  data.tar.gz: b24f59696a3befee77cde24b8fd25b88331b3664a327e8e207d9f57a08abb524
+  metadata.gz: 488be723c0a59ca0095eb3a1f64081cceff14ae982208e598da5058ee0ea0c4b
+  data.tar.gz: 47805f82344429912eaa2e0f00299cc95868d35d04a6d424f698b719bf9d0fe8
 SHA512:
-  metadata.gz: 985aafb6c64874122c77c172ba7dccc1a371a982855b33add51c3371d872db7008391a28382aa7442d640a2f76df1e3ca95426428fb7cd3b12a177d69ed3605e
-  data.tar.gz: 42edecdd416fdc53562ea82caf09b94886e761ea2858c28db76dc4e909dd4da87835fe152bbebf3cc87a64a72eded21706c60ba13beba2293fa5470f11e822bd
+  metadata.gz: 1c0d66e74c7a0e1eb0296e371b0339d44cedbb7a747c2beeb7cb0547303140d0a6550fd8d7fc6629c09804c57cfcf780dec38f01f6c8aac49004ab28e9968872
+  data.tar.gz: aeb129f452a6ea0a9c2e33a25afbe5f8be1e7b27445fb58399556e7bdd0475b0840b36465c6b33edbdf857c6d943c10824b0cc21b7e6a917d161829e4ca033a6

data/README.md

@@ -147,9 +147,11 @@ end
 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"
@@ -176,6 +178,8 @@ end
 
 ### Example #6 [Chat w/ Schema](https://github.com/ksylvest/omniai/blob/main/examples/chat_with_schema)
 
+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.
+
 ```ruby
 format = OmniAI::Schema.format(name: "Contact", schema: OmniAI::Schema.object(
   description: "A contact with a name, relationship, and addresses.",
@@ -421,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'
@@ -481,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)
@@ -489,11 +493,11 @@ 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
 class WeatherTool
-  description "Lookup the weather at a location in either Celsius for Fahrenheit."
+  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."
@@ -504,11 +508,11 @@ class WeatherTool
   #
   # @return [Hash]
   def execute(location:, unit: "Celsius")
-    puts "[weather] location=#{locaiton} unit=#{unit}"
+    puts "[weather] location=#{location} unit=#{unit}"
 
     {
       temperature: "#{rand(20..50)}°",
-      humidty: rand(0..100),
+      humidity: rand(0..100),
     }
   end
 end
@@ -538,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
 
@@ -568,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|
@@ -583,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/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/version.rb

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

data/lib/omniai.rb

@@ -16,6 +16,68 @@ loader.inflector.inflect "http_error" => "HTTPError"
 loader.inflector.inflect "ssl_error" => "SSLError"
 loader.setup
 
+# @example
+#
+#   OmniAI.chat(...)
+#   OmniAI.transcribe(...)
+#   OmniAI.speak(...)
+#   OmniAI.embed(...)
 module OmniAI
   class Error < StandardError; end
+
+  # Discover a client by provider ('openai' then 'anthropic' then 'google' then 'mistral' then 'deepseek').
+  #
+  # @param provider [Symbol] the provider to use (e.g. :openai, :anthropic, :google, :mistral, :deepseek) - optional
+  #
+  # @raise [OmniAI::LoadError] if no providers are installed
+  #
+  # @return [OmniAI::Client]
+  def self.client(provider: nil, **)
+    provider ? OmniAI::Client.find(provider:, **) : OmniAI::Client.discover(**)
+  end
+
+  # @example
+  #   response = OmniAI.chat("What is the capital of Spain?")
+  #   puts response.text
+  #
+  # @example
+  #   OmniAI.chat(stream: $stdout) do |prompt|
+  #     prompt.system("Answer in both English and French.")
+  #     prompt.user("How many people live in Tokyo?")
+  #   end
+  #
+  # @see OmniAI::Client#chat
+  def self.chat(...)
+    client.chat(...)
+  end
+
+  # @example
+  #   File.open("audio.wav", "rb") do |file|
+  #     puts OmniAI.transcribe(file).text
+  #   end
+  #
+  # @see OmniAI::Client#transcribe
+  def self.transcribe(...)
+    client.transcribe(...)
+  end
+
+  # @example
+  #   File.open("audio.wav", "wb") do |file|
+  #     OmniAI.speak("Sally sells seashells by the seashore.") do |chunk|
+  #       file << chunk
+  #     end
+  #   end
+  #
+  # @see OmniAI::Client#speak
+  def self.speak(...)
+    client.speak(...)
+  end
+
+  # @example
+  #   embedding = OmniAI.embed("The quick brown fox jumps over the lazy dog.").embedding
+  #
+  # @see OmniAI::Client#embed
+  def self.embed(...)
+    client.embed(...)
+  end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: omniai
 version: !ruby/object:Gem::Version
-  version: 2.6.0
+  version: 2.7.0
 platform: ruby
 authors:
 - Kevin Sylvestre
 bindir: exe
 cert_chain: []
-date: 2025-05-08 00:00:00.000000000 Z
+date: 2025-05-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: event_stream_parser
@@ -112,6 +112,7 @@ files:
 - lib/omniai/files.rb
 - lib/omniai/http_error.rb
 - lib/omniai/instrumentation.rb
+- lib/omniai/load_error.rb
 - lib/omniai/mcp/jrpc.rb
 - lib/omniai/mcp/jrpc/error.rb
 - lib/omniai/mcp/jrpc/request.rb