omniai 2.6.0 → 2.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6b8a243fb8313c7c1fe3a483cdac33892f1b764cac19c38465a880e3f8a790f0
-  data.tar.gz: b24f59696a3befee77cde24b8fd25b88331b3664a327e8e207d9f57a08abb524
+  metadata.gz: a9cab46e52805a61d08bf4638ef7ed9ab46549c016ada8740abb7471f3ee5d07
+  data.tar.gz: 3a34ea68b515d8759a76d689f2474648c7e55d51b42a93ee022c18df271e049e
 SHA512:
-  metadata.gz: 985aafb6c64874122c77c172ba7dccc1a371a982855b33add51c3371d872db7008391a28382aa7442d640a2f76df1e3ca95426428fb7cd3b12a177d69ed3605e
-  data.tar.gz: 42edecdd416fdc53562ea82caf09b94886e761ea2858c28db76dc4e909dd4da87835fe152bbebf3cc87a64a72eded21706c60ba13beba2293fa5470f11e822bd
+  metadata.gz: b241dca1c95f27efd023c09cb6ed9e8193f94e2487490b376a816e5c50d8a6a42e6cb0bc54e47ec3aeba0b12f23de7b3a258d9ca29d222ce6bf414469e2ad777
+  data.tar.gz: b74ba2a9950c821b7ca6bd5d1348165daab7dea3b7372db702d40cdda8d2669c057b32913cf5713b6d75cf3d97a234acf25c1f11af3357cc465740b18ec5990e

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.",
@@ -224,24 +228,27 @@ puts format.parse(response.text)
 }
 ```
 
-### Example #7: [Chat w/ CLI](https://github.com/ksylvest/omniai/blob/main/examples/chat_with_cli)
+### Example #7: [CLI](https://github.com/ksylvest/omniai/blob/main/examples/cli)
 
 The `OmniAI` gem also ships with a CLI to simplify quick tests.
 
 ```bash
+# Chat
+
 omniai chat "Who designed the Ruby programming language?"
-```
+omniai chat --provider="google" --model="gemini-2.0-flash" "Who are you?"
 
-```
-The Ruby programming language was created by Yukihiro Matsumoto, often known as "Matz."
-```
+## Speech to Text
 
-```bash
-omniai chat --provider="google" --model="gemini-2.0-flash" "Who are you?"
-```
+omniai speak "Salley sells sea shells by the sea shore." > ./files/audio.wav
 
-```
-I am a large language model, trained by Google.
+# Text to Speech
+
+omniai transcribe "./files/audio.wav"
+
+# Embed
+
+omniai embed "What is the capital of France?"
 ```
 
 ### Example #8: [Text-to-Speech](https://github.com/ksylvest/omniai/blob/main/examples/text_to_speech)
@@ -421,10 +428,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 +488,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 +496,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 +511,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 +545,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 +575,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 +590,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
@@ -646,6 +653,18 @@ The capital of Spain is **Madrid**.
 ...
 ```
 
+#### Text-to-Speech
+
+```bash
+omniai speak "Sally sells sea shells on the sea shore." > audio.aac
+```
+
+#### Speech-to-Text
+
+```bash
+omniai transcribe ./audio.aac
+```
+
 ### MCP
 
 [MCP](https://modelcontextprotocol.io/introduction) is an open protocol designed to standardize giving context to LLMs. The OmniAI implementation supports building an MCP server that operates via the [stdio](https://modelcontextprotocol.io/docs/concepts/transports) transport.

data/lib/omniai/cli/base_handler.rb

@@ -31,7 +31,7 @@ module OmniAI
 
       # @return [OmniAI::Client]
       def client
-        @client ||= OmniAI::Client.find(provider: @provider)
+        @client ||= OmniAI.client(provider: @provider)
       end
     end
   end

data/lib/omniai/cli/speak_handler.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module OmniAI
+  class CLI
+    # Used by CLI to process commands like:
+    #
+    #    omniai speak "Sally sells seashells by the seashore." > ./audio.aac
+    class SpeakHandler < BaseHandler
+      # @param argv [Array<String>]
+      def handle!(argv:)
+        parser.parse!(argv)
+
+        speak(argv.join(" "))
+      end
+
+    private
+
+      # @param input [String]
+      def speak(input)
+        client.speak(input, **@args) do |chunk|
+          @stdout.write(chunk)
+        end
+        @stdout.flush
+      end
+
+      # @return [OptionParser]
+      def parser
+        OptionParser.new do |options|
+          options.banner = 'usage: omniai speak [options] "<prompt>"'
+
+          options.on("-h", "--help", "help") do
+            @stdout.puts(options)
+            exit
+          end
+
+          options.on("-p", "--provider=PROVIDER", "provider") do |provider|
+            @provider = provider
+          end
+
+          options.on("-m", "--model=MODEL", "model") do |model|
+            @args[:model] = model
+          end
+
+          options.on("-v", "--voice=VOICE", "voice") do |voice|
+            @args[:voice] = voice
+          end
+
+          options.on("-s", "--speed=SPEED", Float, "speed") do |speed|
+            @args[:speed] = speed
+          end
+
+          options.on("-f", "--format=FORMAT", "format") do |format|
+            @args[:format] = format
+          end
+        end
+      end
+    end
+  end
+end

data/lib/omniai/cli/transcribe_handler.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module OmniAI
+  class CLI
+    # Used by CLI to process commands like:
+    #
+    #    omniai transcribe ./audio.wav
+    class TranscribeHandler < BaseHandler
+      # @param argv [Array<String>]
+      def handle!(argv:)
+        parser.parse!(argv)
+
+        argv.each do |path|
+          transcribe(path)
+        end
+      end
+
+    private
+
+      # @param input [String]
+      def transcribe(input)
+        File.open(input, "rb") do |file|
+          @stdout.puts(client.transcribe(file, **@args).text)
+        end
+      end
+
+      # @return [OptionParser]
+      def parser
+        OptionParser.new do |options|
+          options.banner = 'usage: omniai chat [options] "<prompt>"'
+
+          options.on("-h", "--help", "help") do
+            @stdout.puts(options)
+            exit
+          end
+
+          options.on("-p", "--provider=PROVIDER", "provider") do |provider|
+            @provider = provider
+          end
+
+          options.on("-m", "--model=MODEL", "model") do |model|
+            @args[:model] = model
+          end
+
+          options.on("-l", "--language=LANGUAGE", "language") do |language|
+            @args[:language] = language
+          end
+
+          options.on("-f", "--format=FORMAT", "format") do |format|
+            @args[:format] = format
+          end
+        end
+      end
+    end
+  end
+end

data/lib/omniai/cli.rb

@@ -13,7 +13,7 @@ module OmniAI
     # @param stdin [IO] a stream
     # @param stdout [IO] a stream
     # @param provider [String] a provider
-    def initialize(stdin: $stdin, stdout: $stdout, provider: "openai")
+    def initialize(stdin: $stdin, stdout: $stdout, provider: nil)
       @stdin = stdin
       @stdout = stdout
       @provider = provider
@@ -30,6 +30,8 @@ module OmniAI
         case command
         when "chat" then ChatHandler
         when "embed" then EmbedHandler
+        when "speak" then SpeakHandler
+        when "transcribe" then TranscribeHandler
         else raise Error, "unsupported command=#{command.inspect}"
         end
 
@@ -60,6 +62,9 @@ module OmniAI
         options.separator <<~COMMANDS
           commands:
             chat
+            embed
+            speak
+            transcribe
         COMMANDS
       end
     end

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/speak.rb

@@ -23,7 +23,11 @@ module OmniAI
   #     end
   #   end
   #
-  #   client.transcribe(File.open("..."), model: "...", format: :json)
+  #   File.open('audio.wav', 'wb') do |file|
+  #     client.speak('Sally sells seashells by the seashore.', format: OmniAI::Speak::Format::WAV) do |chunk|
+  #       file << chunk
+  #     end
+  #   end
   class Speak
     module Format
       AAC = "aac"
@@ -34,6 +38,8 @@ module OmniAI
       WAV = "wav"
     end
 
+    DEFAULT_FORMAT = Format::AAC
+
     # @raise [HTTPError]
     #
     # @param client [OmniAI::Client] required
@@ -52,7 +58,7 @@ module OmniAI
     # @yield [chunk]
     #
     # @return [Tempfile]
-    def self.process!(input, client:, model:, voice:, speed: nil, format: nil, &)
+    def self.process!(input, client:, model:, voice:, speed: nil, format: DEFAULT_FORMAT, &)
       new(input, client:, model:, voice:, speed:, format:).process!(&)
     end
 
@@ -68,7 +74,7 @@ module OmniAI
     #   - "opus"
     #   - "pcm"
     #   - "wav"
-    def initialize(input, client:, model:, voice:, speed: nil, format: nil)
+    def initialize(input, client:, model:, voice:, speed: nil, format: DEFAULT_FORMAT)
       @input = input
       @client = client
       @model = model

data/lib/omniai/transcribe.rb

@@ -23,7 +23,9 @@ module OmniAI
   #     end
   #   end
   #
-  #   client.transcribe(File.open("..."), model: "...", format: :json)
+  #   File.open('audio.wav', 'rb') do |file|
+  #     client.transcribe(file, model: "...", format: :json)
+  #   end
   class Transcribe
     module Language
       AFRIKAANS = "af"

data/lib/omniai/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OmniAI
-  VERSION = "2.6.0"
+  VERSION = "2.8.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.8.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
@@ -103,6 +103,8 @@ files:
 - lib/omniai/cli/base_handler.rb
 - lib/omniai/cli/chat_handler.rb
 - lib/omniai/cli/embed_handler.rb
+- lib/omniai/cli/speak_handler.rb
+- lib/omniai/cli/transcribe_handler.rb
 - lib/omniai/client.rb
 - lib/omniai/config.rb
 - lib/omniai/context.rb
@@ -112,6 +114,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