ai_client 0.2.1 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c938cc076640fa6952b1140252b0c234a44e7dfd6ee24d2485c344d3b2c98880
-  data.tar.gz: 1dc5cb21b49c2a731689e7ab7d4f6cce56392b06ecb83e2d54b535ec0d0b3d27
+  metadata.gz: a4128ef9024e8bc84820346570886aa9b3e25a4e8e442556591d45e0900cf9ea
+  data.tar.gz: 64d339534320c27eb060b02ae927f39a829f3792319dc1cd71e3e0920d6aa0ed
 SHA512:
-  metadata.gz: d2d81aa7bc979a8c75856965261ce54470ef3df1586eb65e809c2e4d32f8a4771a22a85640e026260826ab691e54742666ce0b9d71f2ba992b60db3d5c689cc8
-  data.tar.gz: 7347641ccb974d62c0393a364cb09b214019c0e99a2514478632a9b0c4736bf530c0ba415bae316b0438230691418265b21aed46ef32ca122935d73e30085f41
+  metadata.gz: ef72dd20224bd2f887686c1c75881e8bd9195c60ac2a416c9acee3a93cf09335b852381ce3bf314cab72e9b2a7136b4d2bf3f0f622f39f55f1555500796fca17
+  data.tar.gz: 33cc0e5fcf58ebadb5269138342f4e6c49d42604e2ee2fd22630764c1d288bfafdc3c7999467d2dfe890cd9daae573165f497bd1044d807f80d3a89e97f3de33

data/CHANGELOG.md

@@ -1,6 +1,16 @@
 ## [Unreleased]
 
 ## Released
+### [0.2.3] - 2024-10-08
+- refactored the OmniAI extensions for Ollama, LocalAI and OpenRouter
+- added a file for OpenRouter extensions
+- Added the LLM class
+
+### [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
 

data/README.md

@@ -1,20 +1,58 @@
 # 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**  I could use your help extending its capability.
+See the  [change log](CHANGELOG.md) for recent modifications.
 
-AiClien` is working.  I've used early versions of it in several projects.
 
-See the  [change log](CHANGELOG.md) for recent modifications.
+<!-- Tocer[start]: Auto-generated, don't remove. -->
+
+## Table of Contents
+
+  - [Summary](#summary)
+  - [Installation](#installation)
+  - [Environment Variables for Provider Access](#environment-variables-for-provider-access)
+    - [Changing Envar API Key Names](#changing-envar-api-key-names)
+    - [api_key: Parameter](#api_key-parameter)
+    - [provider: Parameter](#provider-parameter)
+  - [Usage](#usage)
+    - [Configuration](#configuration)
+      - [Default Configuration](#default-configuration)
+      - [Class Configuration](#class-configuration)
+        - [1. Class Configuration Block](#1-class-configuration-block)
+        - [2. Set by a Config File](#2-set-by-a-config-file)
+        - [3. Supplemented by a Config File](#3-supplemented-by-a-config-file)
+      - [Instance Configuration](#instance-configuration)
+        - [1. Supplement from a Constructor Block](#1-supplement-from-a-constructor-block)
+        - [2. Supplement from a YAML File](#2-supplement-from-a-yaml-file)
+        - [3. Load Complete Configuration from a YAML File](#3-load-complete-configuration-from-a-yaml-file)
+    - [Top-level Client Methods](#top-level-client-methods)
+        - [chat](#chat)
+        - [embed](#embed)
+        - [speak](#speak)
+        - [transcribe](#transcribe)
+    - [Options](#options)
+    - [Advanced Prompts](#advanced-prompts)
+    - [Advanced Prompts with Tools](#advanced-prompts-with-tools)
+  - [Best ?? Practices](#best--practices)
+  - [OmniAI and OpenRouter](#omniai-and-openrouter)
+  - [Contributing](#contributing)
+  - [License](#license)
+
+<!-- Tocer[finish]: Auto-generated, don't remove. -->
+
 
 ## 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 `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.
 
-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.
+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.
 
-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.
+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!
 
 ## Installation
 
@@ -30,6 +68,53 @@ If bundler is not being used to manage dependencies, install the gem by executin
 gem install ai_client
 ```
 
+## Environment Variables for Provider Access
+
+For fee providers require an account and provide an access token to allow the use of their LLM models.  The value of these access tokens is typically saved in system environment variables or some other secure data store.  AiClient has a default set of system environment variable names for these access tokens based upon the pattern of `provider_api_key` which can be over-ridden.
+
+| 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 |
+
+
+### Changing Envar API Key Names
+
+You can also configure the system environment variable names to match your on standards at the class level.
+
+```ruby
+AiClient.class_config.envar_api_key_bames = {
+  anthropic:    'your_envar_name',
+  google:       'your_envar_name',
+  mistral:      'your_envar_name',
+  open_router:  'your_envar_name',
+  opena:        'your_envar_name'
+}
+
+AiClient.class_config.save('path/to/file.yml')
+```
+
+### api_key: Parameter
+
+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.
+
+
+### provider: Parameter
+
+To explicitly 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.
+
+
 ## Usage
 
 Basic usage:
@@ -45,24 +130,26 @@ 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 are three levels of configuration, each inherenting from the level above. The following sections
-describe those configuration levels.
+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.
+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.
+The class configuration is derived initially from the default configuration.  It can be changed in three ways.
 
-1. Class Configuration Block
+##### 1. Class Configuration Block
 
 ```ruby
 AiClient.configuration do |config|
@@ -71,13 +158,13 @@ AiClient.configuration do |config|
 end
 ```
 
-2. Set by a Config File
+##### 2. Set by a Config File
 
 ```ruby
 AiClient.class_config = AiClient::Config.load('path/to/file.yml')
 ```
 
-3. Supplemented by a Config File
+##### 3. Supplemented by a Config File
 
 ```ruby
 AiClient.class_config.merge! AiClient::Config.load('path/to/file.yml')
@@ -85,12 +172,9 @@ 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.
+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
+##### 1. Supplement from a Constructor Block
 
 ```ruby
 client = AiClient.new('super-ai-overlord-model') do |config|
@@ -99,51 +183,131 @@ client = AiClient.new('super-ai-overlord-model') do |config|
 end
 ```
 
-2. Suppliment from a YAML File
+##### 2. Supplement from a YAML File
 
 ```ruby
 client = AiClient.new('baby-model', config: 'path/to/file.yml')
 ```
 
-3. Load Complete Configuration from a YAML File
+##### 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?
+### Top-level Client Methods
 
-TODO: Document the methods and their options.
+See the [examples directory](examples/README.md) for some ideas on how to use AiClient.
+
+The following examples are based upon the same client configuration.
+
+```ruby
+AI = AiClient.new(...) do ... end
+```
+
+##### chat
+
+Typically `chat(...)` is the most used top-level.  Sometimes refered to as completion.  You are giving a prompt to an LLM and expecting the LLM to respond (ie. complete its transformation).  If you consider the prompt to be a question, the response would be the answer.  If the prompt were a task, the response would be the completion of that task.
+
+```ruby
+response = AI.chat(...)
+```
+
+The simplest form is a string prompt.  The prompt can come from anywher - a litteral, variable, or get if from a database or a file.
+
+```ruby
+response = AI.chat("Is there anything simpler than this?")
+```
+
+The response will be a simple string or a response object based upon the setting of your `config.return_raw` item.  If `true` then you get the whole shebang.  If `false` you get just the string.
+
+See the [Advanced Prompts] section to learn how to configure a complex prompt message.
+
+
+##### embed
+
+Embeddings (as in 'embed additional information') is how retrial augmented generation (RAG) works - which is a deeper subject for another place.  Basically when using an LLM that supports the vectorization of stuff to create embeddings you can use `embed(stuff)` to return the vector associated with the stuff you gave the model.  This vector (an Array of Floating Points Numbers) is a mathematical representation of the stuff that can be used to compare, mathematically, one piece of stuff to a collection of stuff to find other stuff in that collection that closely resembles the stuff for which you are looking.  Q: What is stuff?  A: You know; its just stuff.
 
 ```ruby
-AI.chat(...)
-AI.transcribe(...)
-AI.speak(...)
 AI.embed(...)
-AI.batch_embed(...)
+response = AI.batch_embed(...)
 ```
 
-See the [examples directory](examples/README.md) for some ideas on how to use AiClient.
+Recommendation: Use PostgreSQL, pg_vector and the neighbor gem.
 
-### System Environment Variables
+##### speak
+
+```ruby
+res[pmse = AI.speak("Isn't it nice to have a computer that will talk to you?")
+```
+
+The response will contain audio data that can be played, manipulated or saved to a file.
+
+##### transcribe
+
+```ruby
+response = AI.transcribe(...)
+```
 
-The API keys used with each LLM provider have the pattern `XXX_API_KEY` where XXX is the name of the provided.  For example `OPENAI_API_KEY1` and `ANTROPIC_API_KEY` etc.
 
-TODO: list all providers supported and their envar
 
 ### Options
 
 TODO: document the options like `provider: :ollama`
 
-## Extensions for OmniAI
+### Advanced Prompts
+
+In more complex application providing a simple string as your prompt is not sufficient.  AiClient can take advantage of OmniAI's complex message builder.
+
+```ruby
+client = AiClient.new 'some_model_bane'
+
+completion = client.chat do |prompt|
+  prompt.system('You are an expert biologist with an expertise in animals.')
+  prompt.user do |message|
+    message.text 'What species are in the attached photos?'
+    message.url('https://.../cat.jpeg', "image/jpeg")
+    message.url('https://.../dog.jpeg', "image/jpeg")
+    message.file('./hamster.jpeg', "image/jpeg")
+  end
+end
+
+completion #=> 'The photos are of a cat, a dog, and a hamster.'
+```
+
+Of course if `client.config.return_raw` is true, the completion value will be the complete response object.
+
+### Advanced Prompts with Tools
+
+One of the latest innovations in LLMs is the ability to use functions (aka tools) as `callbacks` to gather more information or to execute a task at the direction of the LLM prompt processing.
+
+See [blog post](https://ksylvest.com/posts/2024-08-16/using-omniai-to-leverage-tools-with-llms) by Kevin Sylvestre, author of the OmniAI gem.
+
+
+TODO: Need to create an example RAG that does not need another access token to a service
+
+
+## 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.
+
+## OmniAI and OpenRouter
 
-The AiClient makes use of extensions to the OmniAI gem that define
-additional providers and protocols.
+Both OmniAI and OpenRouter have similar goals - to provide a common interface to multiple providers and LLMs.  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.
 
-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
+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
 

data/Rakefile

@@ -3,6 +3,14 @@
 require "bundler/gem_tasks"
 require "minitest/test_task"
 
+begin
+  require "tocer/rake/register"
+rescue LoadError => error
+  puts error.message
+end
+
+Tocer::Rake::Register.call
+
 Minitest::TestTask.create
 
 task default: :test

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

@@ -14,20 +14,28 @@
     binmode: false
     reraise_write_errors: []
     mon_data: !ruby/object:Monitor {}
-    mon_data_owner_object_id: 920
+    mon_data_owner_object_id: 700
   level_override: {}
 :timeout:
 :return_raw: false
 :providers: {}
+:envar_api_key_names:
+  :anthropic:
+  - ANTHROPIC_API_KEY
+  :google:
+  - GOOGLE_API_KEY
+  :mistral:
+  - MISTRAL_API_KEY
+  :open_router:
+  - OPEN_ROUTER_API_KEY
+  - OPENROUTER_API_KEY
+  :openai:
+  - OPENAI_API_KEY
 :provider_patterns:
   :anthropic: !ruby/regexp /^claude/i
-  :openai: !ruby/regexp /^(gpt|davinci|curie|babbage|ada|whisper|tts|dall-e)/i
-  :google: !ruby/regexp /^(gemini|palm)/i
-  :mistral: !ruby/regexp /^(mistral|codestral)/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
-:model_types:
-  :text_to_text: !ruby/regexp /^(nomic|gpt|davinci|curie|babbage|ada|claude|gemini|palm|command|generate|j2-|mistral|codestral)/i
-  :speech_to_text: !ruby/regexp /^whisper/i
-  :text_to_speech: !ruby/regexp /^tts/i
-  :text_to_image: !ruby/regexp /^dall-e/i
+  :open_router: !ruby/regexp /\//

data/lib/ai_client/configuration.rb

@@ -65,6 +65,18 @@
 #       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 = { ... }
+#
+
 
 
 require 'hashie'
@@ -79,16 +91,14 @@ class AiClient
     include Hashie::Extensions::Mash::PermissiveRespondTo
     include Hashie::Extensions::Mash::SymbolizeKeys
     include Hashie::Extensions::Mash::DefineAccessors
-  
 
-    # I'm not sure about this ...
-    # def provider(name, &block)
-    #   if block_given?
-    #     providers[name] = block.call
-    #   else
-    #     providers[name] || {}
-    #   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 << self
       def load(filepath=DEFAULT_CONFIG_FILEPATH)
@@ -117,21 +127,24 @@ class AiClient
         timeout: nil,
         return_raw: false,
         providers: {},
+        envar_api_key_names: {
+          anthropic: ['ANTHROPIC_API_KEY'],
+          google: ['GOOGLE_API_KEY'],
+          mistral: ['MISTRAL_API_KEY'],
+          open_router: ['OPEN_ROUTER_API_KEY', 'OPENROUTER_API_KEY'],
+          openai: ['OPENAI_API_KEY']
+        },
         provider_patterns: {
           anthropic: /^claude/i,
-          openai: /^(gpt|davinci|curie|babbage|ada|whisper|tts|dall-e)/i,
-          google: /^(gemini|palm)/i,
-          mistral: /^(mistral|codestral)/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
-        },
-        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
+          ollama: /(llama|nomic)/i,
+          open_router: /\//
         }
       )
+
       @class_config = @default_config.dup
     end
   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/llm.rb

@@ -0,0 +1,26 @@
+# lib/ai_client/llm.rb
+
+require 'active_hash'
+
+class AiClient
+
+  # TODO: Think about this for the OpenRouter modesl DB
+  #       Might cahnge this to ActiveYaml
+
+  class LLM < ActiveHash::Base
+    self.data = AiClient.models
+
+    def model     = id.split('/')[1]
+    def provider  = id.split('/')[0]
+
+    class << self
+      def import(path_to_uml_file) # TODO: load
+        raise "TODO: Not Implemented: #{path_to_yml_file}"
+      end
+
+      def export(path_to_uml_file) # TODO: Dump
+        raise "TODO: Not Implemented: #{path_to_yml_file}"
+      end
+    end
+  end
+end

data/lib/ai_client/open_router_extensions.rb

@@ -0,0 +1,79 @@
+# lib/ai_client/open_router_extensions.rb
+# frozen_string_literal: true
+
+# These extensions to AiClient are only available with
+# a valid API Key for the open_router.ai web-service
+
+require 'open_router'
+
+class AiClient
+
+  def models                        = self.class.models
+  def providers                     = self.class.providers
+  def model_names(a_provider=nil)   = self.class.model_names(a_provider)
+  def model_details(a_model)        = self.class.model_details(a_model)
+  def find_model(a_model_substring) = self.class.find_model(a_model_substring)
+
+  class << self
+    def add_open_router_extensions
+      access_token = fetch_access_token
+
+      return unless access_token
+
+      configure_open_router(access_token)
+      initialize_orc_client
+    end
+
+    def orc_client
+      @orc_client ||= add_open_router_extensions || raise("OpenRouter extensions are not available")
+    end
+
+    def models
+      @models ||= orc_client.models
+    end
+
+    # TODO: Refactor these DB like methods to take
+    #       advantage of AiClient::LLM
+
+    def model_names(provider=nil)
+      model_ids = models.map { _1['id'] }
+
+      return model_ids unless provider
+
+      model_ids.filter_map { _1.split('/')[1] if _1.start_with?(provider.to_s.downcase) }
+    end
+
+    def model_details(model)
+      orc_models.find { _1['id'].include?(model) }
+    end
+
+    def providers
+      @providers ||= models.map{ _1['id'].split('/')[0] }.sort.uniq      
+    end
+
+    def find_model(a_model_substring)
+      model_names.select{ _1.include?(a_model_substring) }
+    end
+  
+    private
+
+    # Similar to fetch_api_key but for the class_config
+    def fetch_access_token
+      class_config.envar_api_key_names.open_router
+                  .map { |key| ENV[key] }
+                  .compact
+                  .first
+    end
+    
+    def configure_open_router(access_token)
+      OpenRouter.configure { |config| config.access_token = access_token }
+    end
+
+    def initialize_orc_client
+      @orc_client ||= OpenRouter::Client.new
+    end
+  end
+end
+
+
+AiClient.add_open_router_extensions

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.1"
+  VERSION = "0.2.3"
 end

data/lib/ai_client.rb

@@ -13,13 +13,21 @@ require 'omniai/anthropic'
 require 'omniai/google'
 require 'omniai/mistral'
 require 'omniai/openai'
-require_relative 'extensions/omniai-ollama'
-require_relative 'extensions/omniai-localai'
+
+require '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'
 require_relative 'ai_client/version'
 
+require_relative 'ai_client/open_router_extensions'
+require_relative 'ai_client/llm' # SMELL: must come after the open router stuff
+
 # Create a generic client instance using only model name
 #   client = AiClient.new('gpt-3.5-turbo')
 #
@@ -28,13 +36,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 +107,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 +121,6 @@ class AiClient
     @last_response  = nil
   end
 
-
-
   def response  = last_response
   def raw?      = config.return_raw
   
@@ -95,73 +128,20 @@ 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')
-    when :anthropic
-      last_response.data.dig('content',0,'text')
-    when :google
-      last_response.data.dig('candidates', 0, 'content', 'parts', 0, 'text')
-    when :mistral
-      last_response.data.dig('choices', 0, 'message', 'content')
+    when :localai, :mistral, :ollama, :open_router, :openai
+      last_response.data.tunnel 'content'
+      
+    when :anthropic, :google
+      last_response.data.tunnel 'text'
+
     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)
@@ -193,9 +173,8 @@ class AiClient
 
 
   def create_client
-    api_key = fetch_api_key  # Fetching the API key should only happen for valid providers
     client_options = {
-      api_key:  api_key,
+      api_key:  fetch_api_key,
       logger:   @logger,
       timeout:  @timeout
     }
@@ -205,46 +184,43 @@ 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)
+      OmniAI::OpenAI::Client.new(host: 'http://localhost:11434', api_key: nil, **client_options)
+
     when :localai
-      OmniAI::LocalAI::Client.new(**client_options)
+      OmniAI::OpenAI::Client.new(host: 'http://localhost:8080', api_key: nil, **client_options)
+
+    when :open_router
+      OmniAI::OpenAI::Client.new(host: 'https://openrouter.ai', api_prefix: 'api', **client_options)
+
     else
       raise ArgumentError, "Unsupported provider: #{@provider}"
     end
   end
 
 
+  # Similar to fetch_access_tokne but for the instance config
   def fetch_api_key
-    env_var_name = "#{@provider.upcase}_API_KEY"
-    api_key = ENV[env_var_name]
-
-    if api_key.nil? || api_key.empty?
-      unless [:localai, :ollama].include? provider
-        raise ArgumentError, "API key not found in environment variable #{env_var_name}"
-      end
-    end
-
-    api_key
+    config.envar_api_key_names[@provider]
+      &.map { |key| ENV[key] }
+      &.compact
+      &.first
   end
 
-
   def determine_provider(model)
     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
 
 

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: ai_client
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.3
 platform: ruby
 authors:
 - Dewayne VanHoozer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-10-05 00:00:00.000000000 Z
+date: 2024-10-10 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: active_hash
+  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: hashie
   requirement: !ruby/object:Gem::Requirement
@@ -94,6 +108,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
@@ -150,18 +178,29 @@ 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"
+- !ruby/object:Gem::Dependency
+  name: tocer
+  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'
+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: []
@@ -182,14 +221,18 @@ files:
 - 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/llm.rb
 - lib/ai_client/logger_middleware.rb
 - lib/ai_client/middleware.rb
+- lib/ai_client/open_router_extensions.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
 - sig/ai_client.rbs
 - the_ollama_model_problem.md
 homepage: https://github.com/MadBomber/ai_client
@@ -215,7 +258,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

data/lib/extensions/omniai-localai.rb

@@ -1,31 +0,0 @@
-# extensions/omniai-localai.rb
-# frozen_string_literal: true
-
-require 'omniai'
-require 'omniai/openai'
-
-module OmniAI
-
-  # Create an alias for OmniAI::OpenAI module
-  module LocalAI
-    extend OmniAI::OpenAI
-
-    # Alias classes from OmniAI::OpenAI
-    class Client < OmniAI::OpenAI::Client
-      def initialize(**options)
-        options[:host] = 'http://localhost:8080' unless options.has_key?(:host)
-        super(**options)
-      end
-    end
-
-
-    Config = OmniAI::OpenAI::Config
-
-    # Alias the Thread class and its nested classes
-    Thread      = OmniAI::OpenAI::Thread
-    Annotation  = OmniAI::OpenAI::Thread::Annotation
-    Attachment  = OmniAI::OpenAI::Thread::Attachment
-    Message     = OmniAI::OpenAI::Thread::Message
-    Run         = OmniAI::OpenAI::Thread::Run
-  end
-end

data/lib/extensions/omniai-ollama.rb

@@ -1,30 +0,0 @@
-# extensions/omniai-ollama.rb
-# frozen_string_literal: true
-
-require 'omniai'
-require 'omniai/openai'
-
-module OmniAI
-
-  # Create an alias for OmniAI::OpenAI module
-  module Ollama
-    extend OmniAI::OpenAI
-
-    # Alias classes from OmniAI::OpenAI
-    class Client < OmniAI::OpenAI::Client
-      def initialize(**options)
-        options[:host] = 'http://localhost:11434' unless options.has_key?(:host)
-        super(**options)
-      end
-    end    
-
-    Config = OmniAI::OpenAI::Config
-
-    # Alias the Thread class and its nested classes
-    Thread      = OmniAI::OpenAI::Thread
-    Annotation  = OmniAI::OpenAI::Thread::Annotation
-    Attachment  = OmniAI::OpenAI::Thread::Attachment
-    Message     = OmniAI::OpenAI::Thread::Message
-    Run         = OmniAI::OpenAI::Thread::Run
-  end
-end