ai_client 0.2.0 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 107e9d57f175adc72178f48365a833a4dab7fbe71088169774429f43624d7d9c
-  data.tar.gz: d308008540c4fbf309235c31d60b1a98b14a608a0f69d7ee1bac6911f34dad47
+  metadata.gz: 07a66886ce84dd916574f7a38e292626124ed1a048da92eec33cfdc0e66435e4
+  data.tar.gz: dc9c6734ae4a6a479ed8f6b76fc8edea31dbb588f67ae801b915a067346c5735
 SHA512:
-  metadata.gz: b001c640758c846f2372354660d4a4f4c7ef4a6c4671bbd743fcc713d543faff1fe54ff2e341285ec57dbaf284db3e3a18a50cbd6b420fd01ac911112a93ae8a
-  data.tar.gz: 0055623e374bb4cf111a234712e9ac1441d6ddb541f2f7ebadc604c255e27bdd6ad14d1b2a81d56cb6e2797e01f3d3398eb4b4b3e6c7d04802dadf620ecb0390
+  metadata.gz: ced4f6a3834132d0c1d127ad3fcd931e9600d748a28d6593fc9e382fb6bb98b9fd31de56d44d5a216c5f0bb8394c360f04779995fd2345ae1043e137cd994091
+  data.tar.gz: be77228ac195d1f3de41f1ec0e82f2d2e2aa0f280e51354156c00b9c40bdb466581c87b4ba73b22c57fa86300df9555b7a2230854ac6ff93e365028b946275ba

data/CHANGELOG.md

@@ -1,6 +1,14 @@
 ## [Unreleased]
 
 ## Released
+### [0.2.2] - 2024-10-07
+- Added support for open_router.ai with extensions/omniai-open_router.rb
+- Removed the `model_type` object
+- Added ability to dump a config to a YAML file
+
+### [0.2.1] - 2024-10-05
+- Added support for YAML configuration files
+
 ### [0.2.0] - 2024-10-04
 - Configuration is more robust.  Still room for improvement.
 

data/README.md

@@ -1,16 +1,35 @@
 # AiClient
 
-First and foremost a big **THANK YOU** to [Kevin Sylvestre](https://ksylvest.com/) for his gem [OmniAI](https://github.com/ksylvest/omniai) upon which this effort depends.
+First and foremost a big **THANK YOU** to [Kevin Sylvestre](https://ksylvest.com/) for his gem [OmniAI](https://github.com/ksylvest/omniai) and [Olympia](https://olympia.chat/) for their [open_router gem](https://github.com/OlympiaAI/open_router) upon which this effort depends.
 
-**This is a work in progress**  Its implemented as a class rather than the typical module for most gems.  The `AiClient::Configuration` class is a little first draft-ish.  I'm looking to bulk it up a lot.  At this point I think some of the current tests are failing; but, over all `AiClien` is working.  I've used early versions of it in several projects.
+See the  [change log](CHANGELOG.md) for recent modifications.
 
 ## Summary
 
-`ai_client` is a versatile Ruby gem that serves as a generic client for interacting with various AI service providers through a unified API provided by Kevin's gem `OmniAI`. The `AiClient` class is designed to simplify the integration of large language models (LLMs) into applications. `AiClient` allows developers to create instances using just the model name, greatly reducing configuration overhead.
+Are you ready to supercharge your applications with cutting-edge AI capabilities? 
+Introducing `ai_client`, the ultimate Ruby gem that provides a seamless interface 
+for interacting with a multitude of AI service providers through a single, 
+unified API. 
 
-With built-in support for popular AI providers—including OpenAI, Anthropic, Google, Mistral, LocalAI and Ollama—the gem abstracts the complexities of API interactions, offering methods for tasks such as chatting, transcription, speech synthesis, and embedding.
+With `ai_client`, you can effortlessly integrate large language models (LLMs) 
+into your projects—simply specify the model name and let the gem handle the 
+rest! Say goodbye to tedious configuration and hello to rapid development.
+
+This gem comes packed with built-in support for leading AI providers, including 
+OpenAI, Anthropic, Google, Mistral, LocalAI, and Ollama. Whether you need to 
+implement chatbots, transcription services, speech synthesis, or embeddings, 
+`ai_client` abstracts the complexities of API interactions, allowing you to focus 
+on what truly matters: building amazing applications.
+
+Plus, with its flexible middleware architecture, you can easily customize request 
+and response processing—implement logging, retry logic, and more with minimal effort. 
+And thanks to its seamless integration with the `OmniAI` framework, you can leverage 
+the latest AI advancements without worrying about vendor lock-in.
+
+Join the growing community of developers who are transforming their applications 
+with `ai_client`. Install it today and unlock the full potential of AI in your 
+projects!
 
-The middleware architecture enables customizable processing of requests and responses, making it easy to implement features like logging and retry logic. Seamlessly integrated with the `OmniAI` framework, `ai_client` empowers developers to leverage cutting-edge AI capabilities without vendor lock-in, making it an essential tool for modern AI-driven applications.
 
 ## Installation
 
@@ -26,6 +45,32 @@ If bundler is not being used to manage dependencies, install the gem by executin
 gem install ai_client
 ```
 
+## Providers Supported
+
+To explicitely designate a provider to use with an AiClient instance
+use the parameter `provider: :your_provider` with the Symbol for the supported
+provider you want to use with the model you specify.  The following providers
+are supported by the OmniAI gem upon which AiClient depends along with a few
+extensions.
+
+| Symbol | Envar API Key | Client Source |
+| --- | --- | --- |
+| :anthropic | [ANTHROPIC_API_KEY](https://www.anthropic.com/) | OmniAI |
+| :google | [GOOGLE_API_KEY](https://cloud.google.com/gemini) | OmniAI |
+| :localai | [LOCALAI_API_KEY](https://localai.io/) | AiClient Extension |
+| :mistral | [MISTRAL_API_KEY](https://mistral.ai/) | OmniAI |
+| :ollama | [OLLAMA_API_KEY](https://ollama.com/) | AiClient Extension |
+| :open_router | [OPEN_ROUTER_API_KEY](https://openrouter.ai/) | AiClient Extension |
+| :openai | [OPENAI_API_KEY](https://www.openai.com/) | OmniAI |
+
+In case you are using a different environment variable for your access token than the ones shown above you can use the `api_key:` parameter.
+
+```ruby
+client = AiClient.new('provider/model_name', api_key: ENV['OPENROUTER_API_KEY'])
+```
+
+This way if you are using `AiClient` inside of a Rails application you can retrieve your access token from a secretes file.
+
 ## Usage
 
 Basic usage:
@@ -41,30 +86,80 @@ c1 = AiClient.new('nomic-embeddings-text')
 c2 = AiClient.new('gpt-4o-mini')
 ```
 
+You can also use the `provider:` parameter in the event that the model you want to use is available through multiple providers or that AiClient can not automatically associate the model name with a provider.
+
+
+```ruby
+AI = AiClient.new('nomic-embed-text', provider: :ollama)
+```
+
 ### Configuration
 
-There is an internal hard-coded configuration default.  That default is duppled into a class-level configuration which can be over-ridden with a class-level config block like this ...
+There are three levels of configuration, each inherenting from the level above. The following sections
+describe those configuration levels.
+
+#### Default Configuration
+
+The file [lib/ai_client/configuration.rb] hard codes the default configuration.  This is used to
+update the [lib/ai_client/config.yml] file during development.  If you have
+some changes for this configuration please send me a pull request so we
+can all benefit from your efforts.
+
+#### Class Configuration
+
+The class configuration is derived initially from the default configuration.  It
+can be changed in three ways.
+
+1. Class Configuration Block
 
 ```ruby
-AiClient.configure do |config|
+AiClient.configuration do |config|
   config.some_item = some_value
+  ...
 end
 ```
 
-Every instance of the AiClient inherents the class-level configuration; however, the instance configuration can also be over-ridden also with a block like this ...
+2. Set by a Config File
+
+```ruby
+AiClient.class_config = AiClient::Config.load('path/to/file.yml')
+```
+
+3. Supplemented by a Config File
+
+```ruby
+AiClient.class_config.merge! AiClient::Config.load('path/to/file.yml')
+```
+
+#### Instance Configuration
+
+All instances have a configuration.  Initially that configuration is the same
+as the class configuration; however, each instance can have its own separate
+configuration.  For an instance the class configuration can either be supplemented 
+or complete over-ridden.
+
+1. Supplement from a Constructor Block
 
 ```ruby
 client = AiClient.new('super-ai-overlord-model') do |config|
   config.some_item = some_value
+  ...
 end
 ```
 
-But wait, there's more.  You can also load a YAML file as a configuration of an instance like this ...
+2. Suppliment from a YAML File
 
 ```ruby
 client = AiClient.new('baby-model', config: 'path/to/file.yml')
 ```
 
+3. Load Complete Configuration from a YAML File
+
+```ruby
+client = AiClient.new('your-model')
+client.config = AiClient::Config.load('path/to/file.yml')
+```
+
 ### What Now?
 
 TODO: Document the methods and their options.
@@ -77,7 +172,7 @@ AI.embed(...)
 AI.batch_embed(...)
 ```
 
-TODO: see the [examples] directory.
+See the [examples directory](examples/README.md) for some ideas on how to use AiClient.
 
 ### System Environment Variables
 
@@ -89,6 +184,36 @@ TODO: list all providers supported and their envar
 
 TODO: document the options like `provider: :ollama`
 
+## Best ?? Practices
+
+If you are going to be using one model for multiple purposes in different parts of your application you can assign the instance of `AiClient` to a constant so that the same client can be used everywhere.
+
+```ruby
+AI = AiClient.new 'gpt-4o'
+...
+AI.chat "do something with this #{stuff}"
+...
+AI.speak "warning  Will Robinson! #{bad_things_happened}"
+...
+```
+
+Using the constant for the instance allows you to reference the same client instance inside any method through out your application.  Of course it does not apply to only one instance.  You could assign multiple instances for different models/providers.  For example you could have `AI` for your primary client and `AIbackup` for a fallback client in case you have a problem on the primary; or, maybe `Vectorizer` as a client name tied to a model specializing in embedding vectorization.
+
+## Extensions for OmniAI
+
+The AiClient makes use of extensions to the OmniAI gem that define
+additional providers and protocols.
+
+1. **OmniAI::Ollama^** which wraps the OmniAI::OpenAI class
+2. **OmniAI::LocalAI** which also wraps the OmniAI::OpenAI class
+3. **OmniAI::OpenRouter**  TODO: Still under development
+
+## OmniAI and OpenRouter
+
+OmniAI is a Ruby gem that supports specific providers directly using a common-ish API.  You incur costs directly from those providers for which you have individual API keys (aka access tokens.) OpenRouter, on the other hand, is a web service that also establishes a common API for many providers and models; however, OpenRouter adds a small fee on top of the fee charged by those providers.  You trade off cost for flexibility.  With OpenRouter you only need one API key (OPEN_ROUTER_API_KEY) to access all of its supported services.
+
+The advantage of AiClient is that you have the added flexibility to choose on a client by client bases where you want your model to be processed.  You get free local processing through Ollama and LocalAI.  You get less costly direct access to some providers via OmniAI.  You get slightly more costly wide-spread access via OpenRouter
+
 ## Contributing
 
 I can sure use your help.  This industry is moving faster than I can keep up with.  If you have a bug fix or new feature idea then have at it.  Send me a pull request so we all can benefit from your efforts.

data/examples/README.md

@@ -0,0 +1,13 @@
+# Examples
+
+| File | Content |
+| --- | --- |
+| Bethany Hamilton.m4a | Audio file used to demonstrate transcribe|
+| common.rb | Stuff used by each example |
+| embed.rb | Demonstrates using Ollama locally to vectorize text for embeddings|
+| speak.rb | Demonstrates using OpenAI's text to speech models |
+| text.rb | Demonstrates text-to-text transformers "chat" |
+| transcribe.rb | Uses OpenAI's audio-to-text model |
+
+Many of these example programs show both the raw response object as well as just the
+content from the response.

data/examples/speak.rb

@@ -24,7 +24,7 @@ end
 title "Default Configuration Text-to-Speech"
 
 clients.each do |c|
-  puts "\nModel: #{c.model} (#{c.model_type})  Provider: #{c.provider}"
+  puts "\nModel: #{c.model}  Provider: #{c.provider}"
   text = "Text to speach example using the #{c.model} by provider #{c.provider} with the default voice."
   result = c.speak(text)
   puts "Audio generated. Tempfile: #{result.path}"

data/examples/text.rb

@@ -48,7 +48,7 @@ end
 title "Default Configuration Response to 'hello'"
 
 clients.each do |c|
-  puts "\nModel: #{c.model} (#{c.model_type})  Provider: #{c.provider}"
+  puts "\nModel: #{c.model}  Provider: #{c.provider}"
   begin
     response = c.chat('hello')
     puts response
@@ -73,7 +73,7 @@ puts
 title "Raw Configuration Response to 'hello'"
 
 raw_clients.each do |c|
-  puts "\nModel: #{c.model} (#{c.model_type})  Provider: #{c.provider}"
+  puts "\nModel: #{c.model}  Provider: #{c.provider}"
   begin
     result = c.chat('hello')
     puts result.pretty_inspect

data/examples/transcribe.rb

@@ -21,7 +21,7 @@ title "Default Configuration Speech-to-Text"
 
 
 clients.each do |c|
-  puts "\nModel: #{c.model} (#{c.model_type})  Provider: #{c.provider}"
+  puts "\nModel: #{c.model}  Provider: #{c.provider}"
   result = c.transcribe(audio_file)
   puts "Transcription: #{result.pretty_inspect}"
 end

data/lib/ai_client/chat.rb

@@ -0,0 +1,24 @@
+# lib/ai_client/chat.rb
+
+class AiClient
+
+  ######################################
+  # OmniAI Params
+  #   model:        @model    [String] optional
+  #   format:       @format   [Symbol] optional :text or :json
+  #   stream:       @stream   [Proc, nil] optional
+  #   tools:        @tools    [Array<OmniAI::Tool>] optional
+  #   temperature:  @temperature  [Float, nil] optional
+
+  def chat(messages, **params)
+    result = call_with_middlewares(:chat_without_middlewares, messages, **params)
+    @last_response = result
+    raw? ? result : content
+  end
+
+
+  def chat_without_middlewares(messages, **params)
+    @client.chat(messages, model: @model, **params)
+  end
+
+end

data/lib/ai_client/config.yml

@@ -0,0 +1,29 @@
+---
+:logger: !ruby/object:Logger
+  level: 0
+  progname:
+  default_formatter: !ruby/object:Logger::Formatter
+    datetime_format:
+  formatter:
+  logdev: !ruby/object:Logger::LogDevice
+    shift_period_suffix:
+    shift_size:
+    shift_age:
+    filename:
+    dev: !ruby/object:IO {}
+    binmode: false
+    reraise_write_errors: []
+    mon_data: !ruby/object:Monitor {}
+    mon_data_owner_object_id: 920
+  level_override: {}
+:timeout:
+:return_raw: false
+:providers: {}
+:provider_patterns:
+  :anthropic: !ruby/regexp /^claude/i
+  :openai: !ruby/regexp /^(gpt|chatgpt|o1|davinci|curie|babbage|ada|whisper|tts|dall-e)/i
+  :google: !ruby/regexp /^(gemini|gemma|palm)/i
+  :mistral: !ruby/regexp /^(mistral|codestral|mixtral)/i
+  :localai: !ruby/regexp /^local-/i
+  :ollama: !ruby/regexp /(llama|nomic)/i
+  :open_router: !ruby/regexp /\//

data/lib/ai_client/configuration.rb

@@ -1,27 +1,93 @@
 # ai_client/configuration.rb
 #
-# Design Objective:
-# AiClient.configure do |config|
-#   # global config items that over-ride the defaults
-# end
+# AiClient and AiClient::Config
+#
+# The AiClient class provides a configurable client for interacting with various AI service providers.
+# It allows users to set global configurations and provider-specific settings via a block.
+#
+# There are three levels of configuration:
+#   * default_config .. the starting point
+#   * class_config .... for all instances
+#   * config .......... for an instance
+# 
+# Class Configuration
+#   starts with the default configuration but can
+#   be changed in three different ways.
+#   1. Use the configuration block
+#       AiClient.configuration do |config|
+#         some_item = some_value
+#         ...
+#       end
+#
+#   2.  Automatic YAML configuration file
+#       Set the system environment variable AI_CLIENT_CONFIG_FILE
+#       to an existing configuration file.  The contents of that
+#       file will be automatically merged on top of the
+#       default configuration.
+#
+#   3.  Manual YAML configuration file
+#       You can completely replace the class configuration
+#         AiClient.class_config = AiClient::Config.load('path/to/file.yml')
+#       You can supplement the existing class config
+#         AiClient.class_config.merge!(AiClient::Config.load('path/to/file.yml'))
+#
+# Instance Configuration
+#   AiClient is setup so that you can have multiple instance
+#   of clients each using a different model / provider and having
+#   a different configuration.  There are several ways you
+#   can manipulate an instance's configuration.
+# 
+#   1.  The default instance configuration inherents from the
+#       the class configuration.
+#         client = AiClient.new('your_model')
+#       You can access the instance configuration using
+#         client.config.some_item
+#         client.config[:some_item]
+#         client.config['some_item']
+#       All three ways returns the value for that configuration item.
+#       To change the value of an item its also that simple.
+#         client.config.some_item     = some_value
+#         client.config[:some_item]   = some_value
+#         client.config['some_item']  = some_value
+#   2.  Instance constructor block
+#         client = AiClient.new('your_model') do |config|
+#           config.some_item = some_value
+#           ...
+#         end
+#
+#   3.  Like the class configuration you can can replace or
+#       supplement an instance's configuration from a YAML file.
+#         client = AiClient.new('your_model', config: 'path/to/file.yml')
+#         client.config.merge!(AiClient::Config.load('path/to/file.yml'))
+#       Both of those example suppliment / over0ride items in
+#       the class configuration to become the instance's
+#       configuration.  To completely replace the instance's
+#       configuration you can do this.
+#         client = AiClient.new('your_model')
+#         client.config = AiClient::Config.load('path/to/file.yml')
+#
+# OmniAI Configuration Items
+# OmniAI::OpenAI
+#   config.api_key = '...'
+#   config.host = 'http://localhost:8080'
+#   config.logger = Logger.new(STDOUT)
+#   config.timeout = 15
+#   config.chat_options = { ... }
+#   config.transcribe_options = { ... }
+#   config.speak_options = { ... }
 #
-# client = AiClient.new(...) do
-#   # client specific config items that over-ride the global config
-# end 
+
+
 
 require 'hashie'
 require 'logger'
+require 'yaml'
+require 'pathname'
 
 class AiClient
-  # TODO: Use system environment varibles
-  #       AI_CLIENT_CONFIG_FILE
-  #
-  # TODO: Config.load('path/to/some_file.yml')
-  #         @@default_config (on require from lib/config.yml)
-  #         @@config (if the envar exists ?? merge with default)
-  #         @config ... done
-
   class Config < Hashie::Mash
+    DEFAULT_CONFIG_FILEPATH = Pathname.new(__dir__) + 'config.yml'
+    
     include Hashie::Extensions::Mash::PermissiveRespondTo
     include Hashie::Extensions::Mash::SymbolizeKeys
     include Hashie::Extensions::Mash::DefineAccessors
@@ -36,48 +102,63 @@ class AiClient
     #   end
     # end
 
-  end
 
+    def save(filepath=ENV['HOME']+'/aiclient_config.yml')
+      filepath = Pathname.new(filepath) unless filepath.is_a? Pathname
+
+      filepath.write(YAML.dump(to_hash))
+    end
 
-  # Class variables to hold default and current config
-  @@default_config = Config.new(
-    logger: Logger.new(STDOUT),
-    timeout: nil,
-    return_raw: false,
-    providers: {},
-    provider_patterns: {
-      anthropic: /^claude/i,
-      openai: /^(gpt|davinci|curie|babbage|ada|whisper|tts|dall-e)/i,
-      google: /^(gemini|palm)/i,
-      mistral: /^(mistral|codestral)/i,
-      localai: /^local-/i,
-      ollama: /(llama|nomic)/i
-    },
-    model_types: {
-      text_to_text: /^(nomic|gpt|davinci|curie|babbage|ada|claude|gemini|palm|command|generate|j2-|mistral|codestral)/i,
-      speech_to_text: /^whisper/i,
-      text_to_speech: /^tts/i,
-      text_to_image: /^dall-e/i
-    }
-  )
-
-  @@class_config = @@default_config.dup
+
+    class << self
+      def load(filepath=DEFAULT_CONFIG_FILEPATH)
+        filepath = Pathname.new(filepath) unless Pathname == filepath.class
+        if filepath.exist?
+          new(YAML.parse(filepath.read).to_ruby)
+        else
+          raise ArgumentError, "#{filepath} does not exist"
+        end
+      end
+    end
+  end
 
   class << self
+    attr_accessor :class_config, :default_config
+
     def configure(&block)
       yield(class_config)
     end
 
-    def class_config
-      @@class_config
-    end
-    
-    def class_config=(value)
-      @@class_config = value
-    end
+    private
 
-    def default_config
-      @@default_config
+    def initialize_defaults
+      @default_config = Config.new(
+        logger: Logger.new(STDOUT),
+        timeout: nil,
+        return_raw: false,
+        providers: {},
+        provider_patterns: {
+          anthropic: /^claude/i,
+          openai: /^(gpt|chatgpt|o1|davinci|curie|babbage|ada|whisper|tts|dall-e)/i,
+          google: /^(gemini|gemma|palm)/i,
+          mistral: /^(mistral|codestral|mixtral)/i,
+          localai: /^local-/i,
+          ollama: /(llama|nomic)/i,
+          open_router: /\//
+        }
+      )
+
+      @class_config = @default_config.dup
     end
   end
+
+  initialize_defaults
+end
+
+
+AiClient.default_config = AiClient::Config.load
+AiClient.class_config   = AiClient.default_config.dup
+
+if config_file = ENV.fetch('AI_CLIENT_CONFIG_FILE', nil)
+  AiClient.class_config.merge!(AiClient::Config.load(config_file))
 end

data/lib/ai_client/embed.rb

@@ -0,0 +1,21 @@
+# lib/ai_client/embed.rb
+
+class AiClient
+
+  ######################################
+  # OmniAI Params
+  #   model [String] required
+  #
+
+  def embed(input, **params)
+    @client.embed(input, model: @model, **params)
+  end
+
+  def batch_embed(inputs, batch_size: 100, **params)
+    inputs.each_slice(batch_size).flat_map do |batch|
+      sleep 1 # DEBUG rate limits being exceeded
+      embed(batch, **params)
+    end
+  end
+
+end

data/lib/ai_client/speak.rb

@@ -0,0 +1,26 @@
+# lib/ai_client/speak.rb
+
+class AiClient
+
+  ######################################
+  # OmniAI Params
+  #   input   [String] required
+  #   model   [String] required
+  #   voice   [String] required
+  #   speed   [Float] optional
+  #   format  [String] optional (default "aac")
+  #     aac mp3 flac opus pcm wav
+  #
+  # @yield [output] optional
+  #
+  # @return [Tempfile``]
+
+  def speak(text, **params)
+    call_with_middlewares(:speak_without_middlewares, text, **params)
+  end
+
+  def speak_without_middlewares(text, **params)
+    @client.speak(text, model: @model, **params)
+  end
+
+end

data/lib/ai_client/transcribe.rb

@@ -0,0 +1,21 @@
+# lib/ai_client/transcribe.rb
+
+class AiClient
+
+  ######################################
+  # OmniAI Params
+  #   model    [String]
+  #   language [String, nil] optional
+  #   prompt   [String, nil] optional
+  #   format   [Symbol] :text, :srt, :vtt, or :json (default)
+  #   temperature [Float, nil] optional
+
+  def transcribe(audio, format: nil, **params)
+    call_with_middlewares(:transcribe_without_middlewares, audio, format: format, **params)
+  end
+
+  def transcribe_without_middlewares(audio, format: nil, **params)
+    @client.transcribe(audio, model: @model, format: format, **params)
+  end
+
+end

data/lib/ai_client/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class AiClient
-  VERSION = "0.2.0"
+  VERSION = "0.2.2"
 end

data/lib/ai_client.rb

@@ -13,8 +13,17 @@ require 'omniai/anthropic'
 require 'omniai/google'
 require 'omniai/mistral'
 require 'omniai/openai'
-require_relative 'extensions/omniai-ollama'
+
+require 'open_router'
+
 require_relative 'extensions/omniai-localai'
+require_relative 'extensions/omniai-ollama'
+require_relative 'extensions/omniai-open_router'
+
+require_relative 'ai_client/chat'
+require_relative 'ai_client/embed'
+require_relative 'ai_client/speak'
+require_relative 'ai_client/transcribe'
 
 require_relative 'ai_client/configuration'
 require_relative 'ai_client/middleware'
@@ -28,13 +37,41 @@ require_relative 'ai_client/version'
 #   AiClient.use(LoggingMiddleware.new(AiClient.configuration.logger))
 #
 
-
 class AiClient
 
+  # Define the refinement for Hash
+  module HashRefinement
+    refine Hash do
+      def tunnel(target_key)
+        queue = [self] # Initialize the queue with the current hash
+
+        until queue.empty?
+          current = queue.shift # Dequeue the front hash
+
+          # Check if the current hash contains the target key
+          return current[target_key] if current.key?(target_key)
+
+          # Enqueue sub-hashes and arrays to the queue for further searching
+          current.each_value do |value|
+            case value
+            when Hash
+              queue << value
+            when Array
+              queue.concat(value.select { |v| v.is_a?(Hash) }) # Add sub-hashes from the array
+            end
+          end
+        end
+
+        nil # Return nil if the key is not found
+      end
+    end
+  end
+
+  using HashRefinement
+
   attr_reader :client,        # OmniAI's client instance
               :provider,      # [Symbol]
               :model,         # [String]
-              :model_type,    # [Symbol]
               :logger, 
               :last_response,
               :timeout,
@@ -71,7 +108,6 @@ class AiClient
     explicit_provider = options.fetch(:provider, config.provider)
 
     @provider   = validate_provider(explicit_provider) || determine_provider(model)
-    @model_type = determine_model_type(model)
 
     provider_config = @config.providers[@provider] || {}
 
@@ -86,8 +122,6 @@ class AiClient
     @last_response  = nil
   end
 
-
-
   def response  = last_response
   def raw?      = config.return_raw
   
@@ -95,73 +129,33 @@ class AiClient
     config.return_raw = value
   end
 
-
-
-  ######################################
-  def chat(messages, **params)
-    result = call_with_middlewares(:chat_without_middlewares, messages, **params)
-    @last_response = result
-    raw? ? result : content
-  end
-
-
-  def chat_without_middlewares(messages, **params)
-    @client.chat(messages, model: @model, **params)
-  end
-
-  ######################################
-  def transcribe(audio, format: nil, **params)
-    call_with_middlewares(:transcribe_without_middlewares, audio, format: format, **params)
-  end
-
-  def transcribe_without_middlewares(audio, format: nil, **params)
-    @client.transcribe(audio, model: @model, format: format, **params)
-  end
-
-  ######################################
-  def speak(text, **params)
-    call_with_middlewares(:speak_without_middlewares, text, **params)
-  end
-
-  def speak_without_middlewares(text, **params)
-    @client.speak(text, model: @model, **params)
-  end
-
-
-  ######################################
-  def embed(input, **params)
-    @client.embed(input, model: @model, **params)
-  end
-
-  def batch_embed(inputs, batch_size: 100, **params)
-    inputs.each_slice(batch_size).flat_map do |batch|
-      sleep 1 # DEBUG rate limits being exceeded
-      embed(batch, **params)
-    end
-  end
-
-  ######################################
-  ## Utilities
-  
   def content
     case @provider
     when :openai, :localai, :ollama
-      last_response.data.dig('choices', 0, 'message', 'content')
+      # last_response.data.dig('choices', 0, 'message', 'content')
+      last_response.data.tunnel 'content'
+      
     when :anthropic
-      last_response.data.dig('content',0,'text')
+      # last_response.data.dig('content',0,'text')
+      last_response.data.tunnel 'text'
+
     when :google
-      last_response.data.dig('candidates', 0, 'content', 'parts', 0, 'text')
+      # last_response.data.dig('candidates', 0, 'content', 'parts', 0, 'text')
+      last_response.data.tunnel 'text'
+
     when :mistral
-      last_response.data.dig('choices', 0, 'message', 'content')
+      # last_response.data.dig('choices', 0, 'message', 'content')
+      last_response.data.tunnel 'content'
+
+    when :open_router
+      last_response.data.tunnel 'content'
+
     else
       raise NotImplementedError, "Content extraction not implemented for provider: #{@provider}"
     end
   end
   alias_method :text, :content
 
-  ##############################################
-  ## Public Class Methods
-
   def method_missing(method_name, *args, &block)
     if @client.respond_to?(method_name)
       result = @client.send(method_name, *args, &block)
@@ -205,16 +199,25 @@ class AiClient
     case provider
     when :openai
       OmniAI::OpenAI::Client.new(**client_options)
+
     when :anthropic
       OmniAI::Anthropic::Client.new(**client_options)
+
     when :google
       OmniAI::Google::Client.new(**client_options)
+
     when :mistral
       OmniAI::Mistral::Client.new(**client_options)
+
     when :ollama
       OmniAI::Ollama::Client.new(**client_options)
+
     when :localai
       OmniAI::LocalAI::Client.new(**client_options)
+
+    when :open_router
+      OmniAI::OpenRouter::Client.new(**client_options)
+
     else
       raise ArgumentError, "Unsupported provider: #{@provider}"
     end
@@ -239,12 +242,6 @@ class AiClient
     config.provider_patterns.find { |provider, pattern| model.match?(pattern) }&.first ||
       raise(ArgumentError, "Unsupported model: #{model}")
   end
-
-
-  def determine_model_type(model)
-    config.model_types.find { |type, pattern| model.match?(pattern) }&.first ||
-      raise(ArgumentError, "Unable to determine model type for: #{model}")
-  end
 end
 
 

data/lib/extensions/omniai-open_router.rb

@@ -0,0 +1,92 @@
+# lib/extensions/omniai-open_router.rb
+# frozen_string_literal: true
+
+require 'omniai'
+require 'omniai/openai'
+
+module OmniAI
+
+  # Create an alias for OmniAI::OpenAI module
+  module OpenRouter
+    extend OmniAI::OpenAI
+
+    # Alias classes from OmniAI::OpenAI
+    class Client < OmniAI::OpenAI::Client
+      def initialize(**options)
+        options[:host] = 'https://openrouter.ai/api/v1' unless options.has_key?(:host)
+        super(**options)
+      end
+
+      def self.openrouter
+        OmniAI::OpenRouter::Client
+      end
+
+      def self.open_router
+        OmniAI::OpenRouter::Client
+      end
+
+      def self.find(provider:, **)
+        return OmniAI.open_router.new(**) if :open_reouter == provider
+
+        super(provider: provider.to_s, **)
+      end
+    end    
+
+    Chat = OmniAI::OpenAI::Chat
+
+    class Chat
+      def path
+        "/api/v1/chat/completions"
+      end
+    end
+
+    Config = OmniAI::OpenAI::Config
+
+    # Alias the Thread class and its nested classes
+    Thread              = OmniAI::OpenAI::Thread
+    Thread::Annotation  = OmniAI::OpenAI::Thread::Annotation
+    Thread::Attachment  = OmniAI::OpenAI::Thread::Attachment
+    Thread::Message     = OmniAI::OpenAI::Thread::Message
+    Thread::Run         = OmniAI::OpenAI::Thread::Run
+  end
+end
+
+######################################################
+## Extend Capabilities Using OpenRouter
+#
+# TODO: catch the models db
+# TODO: consider wrapping the models database in an ActiveModel
+#
+class AiClient
+  class << self
+    def orc_models
+      @orc_models ||= ORC.models if defined?(ORC)
+    end
+
+    def orc_model_names(provider=nil)
+      if provider.nil?
+        orc_models.map{|e| e['id']}
+      else
+        orc_models
+          .map{|e| e['id']}
+          .select{|name| name.start_with? provider.to_s.downcase}
+          .map{|e| e.split('/')[1]}
+      end
+    end
+
+    def orc_model_details(model)
+      orc_models.select{|e| e['id'].include?(model)}
+    end
+  end
+end
+
+if ENV.fetch('OPEN_ROUTER_API_KEY', nil)
+  OpenRouter.configure do |config|
+    config.access_token = ENV.fetch('OPEN_ROUTER_API_KEY', nil)
+  end
+
+  # Use a default provider/model
+  AiClient::ORC = OpenRouter::Client.new
+end
+
+

data/lib/extensions/open_router.md

@@ -0,0 +1,97 @@
+# Notes on OpenRouter
+
+OpenROuter is a web service that has a common API to many
+back-end LLM processors.  Its goal is basically the same as the
+OmniAI gem - provide the flexibility of using multiple models
+processed by myltiple providers.
+
+```ruby
+OpenRouter.configure do |config|
+  config.access_token = ENV.fetch('OPEN_ROUTER_API_KEY', nil)
+end
+
+# Use a default provider/model
+AI = OpenRouter::Client.new
+
+# Returns an Array of Hash for supported 
+# models/providers
+Models = AI.models
+```
+
+models with a "/" are targeted to open router.
+  before the "/" is the provider after it is the model name
+
+Will need to add this entriy to the AiClient::Config `provider_patterns` Hash:
+
+```ruby
+open_router: /\//,  # /(.*)\/(.*)/  provider / model name
+```
+
+models can be an Array of Strings.  The first is the primary while
+the rest are fallbacks in case there is one before fails
+
+```ruby
+{
+  "models": ["anthropic/claude-2.1", "gryphe/mythomax-l2-13b"],
+  "route": "fallback",
+  ... // Other params
+}
+```
+
+You can have OpenRouter send your prompt to the best
+provider/model for the prompt like this:
+
+```ruby
+require "open_router"
+
+OpenRouter.configure do |config|
+  config.access_token = ENV["ACCESS_TOKEN"]
+  config.site_name = "YOUR_APP_NAME"
+  config.site_url = "YOUR_SITE_URL"
+end
+
+OpenRouter::Client.new.complete(
+  model: "openrouter/auto",
+  messages: [
+    {
+      "role": "user",
+      "content": "What is the meaning of life?"
+    }
+  ]
+).then do |response|
+  puts response.dig("choices", 0, "message", "content")
+end
+```
+
+OpenRouter can also support OpenAI's API by using this
+  base_url: "https://openrouter.ai/api/v1",
+
+Request Format Documentation
+  https://openrouter.ai/docs/requests
+
+Simple Quick Start ...
+
+```ruby
+OpenRouter::Client.new.complete(
+  model: "openai/gpt-3.5-turbo",
+  messages: [
+    {
+      "role": "user",
+      "content": "What is the meaning of life?"
+    }
+  ]
+).then do |response|
+  puts response.dig("choices", 0, "message", "content")
+end
+```
+
+## Design Approaches
+
+There are at least two different approaches to
+integrate the OpenRouter capability.  1) Use the open_router gem
+and forget about using the same common-ish
+API established by OmniAI; or 2) Take advantage
+or OpenRouter's OpenAI's API and do for it
+the same thing that was done of Ollama and LocalAI.
+
+

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ai_client
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.2
 platform: ruby
 authors:
 - Dewayne VanHoozer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-10-05 00:00:00.000000000 Z
+date: 2024-10-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hashie
@@ -94,6 +94,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: open_router
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: amazing_print
   requirement: !ruby/object:Gem::Requirement
@@ -122,6 +136,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: hashdiff
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: mocha
   requirement: !ruby/object:Gem::Requirement
@@ -136,18 +164,15 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: "`ai_client` is a versatile Ruby gem that serves as a generic client
-  \nfor interacting with various AI service providers through a unified \nAPI. Designed
-  to simplify the integration of large language models \n(LLMs) into applications,
-  `ai_client` allows developers to create \ninstances using just the model name, greatly
-  reducing configuration \noverhead. With built-in support for popular AI providers—including
-  \nOpenAI, Anthropic, Google, Mistral, LocalAI and Ollama—the gem abstracts the \ncomplexities
-  of API interactions, offering methods for tasks such \nas chatting, transcription,
-  speech synthesis, and embedding. The \nmiddleware architecture enables customizable
-  processing of requests \nand responses, making it easy to implement features like
-  logging and \nretry logic. Seamlessly integrated with the `OmniAI` framework, \n`ai_client`
-  empowers developers to leverage cutting-edge AI capabilities \nwithout vendor lock-in,
-  making it an essential tool for modern AI-driven \napplications.\n"
+description: "`ai_client` is a versatile Ruby gem that offers a seamless interface
+  \nfor integrating a wide range of AI service providers through a single, \nunified
+  API. With `ai_client`, you can simply specify the model name \nand quickly leverage
+  advanced features such as chatting, transcription, \nand speech synthesis. The gem
+  supports prominent providers, including \nOpenAI, Anthropic, Google, Mistral, LocalAI,
+  Ollama, and OpenRouter, \nmaking it easier than ever to build innovative applications.
+  Plus, its \nflexible middleware architecture allows for easy customization of request
+  \nand response handling, ensuring that you can harness the power of AI \nwithout
+  vendor lock-in.\n"
 email:
 - dvanhoozer@gmail.com
 executables: []
@@ -161,19 +186,27 @@ files:
 - README.md
 - Rakefile
 - examples/Bethany Hamilton.m4a
+- examples/README.md
 - examples/common.rb
 - examples/embed.rb
 - examples/speak.rb
 - examples/text.rb
 - examples/transcribe.rb
 - lib/ai_client.rb
+- lib/ai_client/chat.rb
+- lib/ai_client/config.yml
 - lib/ai_client/configuration.rb
+- lib/ai_client/embed.rb
 - lib/ai_client/logger_middleware.rb
 - lib/ai_client/middleware.rb
 - lib/ai_client/retry_middleware.rb
+- lib/ai_client/speak.rb
+- lib/ai_client/transcribe.rb
 - lib/ai_client/version.rb
 - lib/extensions/omniai-localai.rb
 - lib/extensions/omniai-ollama.rb
+- lib/extensions/omniai-open_router.rb
+- lib/extensions/open_router.md
 - sig/ai_client.rbs
 - the_ollama_model_problem.md
 homepage: https://github.com/MadBomber/ai_client
@@ -199,7 +232,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.20
+rubygems_version: 3.5.21
 signing_key:
 specification_version: 4
 summary: A generic AI Client for many providers