ai_client 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b12bef21b23a46a47cc409042afd5eaae36d6cf1cdd2fae47f12fd0b958ed961
-  data.tar.gz: 0c70c7f7e562da50876ee65c1f1de81f6ee7d37e97a2a7c114bb692ce5d6155d
+  metadata.gz: c938cc076640fa6952b1140252b0c234a44e7dfd6ee24d2485c344d3b2c98880
+  data.tar.gz: 1dc5cb21b49c2a731689e7ab7d4f6cce56392b06ecb83e2d54b535ec0d0b3d27
 SHA512:
-  metadata.gz: 56d14adae8ab29719083dc7bb63edf33fa625237274edef043b3738f39757fa0c15983232c9aab0a2afbf8db33cbcafc89ed0cb39d0180d045e3c2f6f467a5fe
-  data.tar.gz: 5c3d314a10a6aa6f10a51b6f8eaf574dea6d108feb5b5ec64f47fb0e494cc1ebe865a7b2fbc9401aada23c692cae2346a48dbcf062e84a202e080f25f0790d9d
+  metadata.gz: d2d81aa7bc979a8c75856965261ce54470ef3df1586eb65e809c2e4d32f8a4771a22a85640e026260826ab691e54742666ce0b9d71f2ba992b60db3d5c689cc8
+  data.tar.gz: 7347641ccb974d62c0393a364cb09b214019c0e99a2514478632a9b0c4736bf530c0ba415bae316b0438230691418265b21aed46ef32ca122935d73e30085f41

data/.irbrc

@@ -0,0 +1,3 @@
+# .irbrc
+
+require_relative 'lib/ai_client'

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 ## [Unreleased]
 
-## [0.1.0] - 2024-10-02
+## Released
+### [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.
+
+### [0.1.0] - 2024-10-02
 
 - Initial working release

data/README.md

@@ -2,7 +2,11 @@
 
 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.
 
-**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.
+**This is a work in progress**  I could use your help extending its capability.
+
+AiClien` is working.  I've used early versions of it in several projects.
+
+See the  [change log](CHANGELOG.md) for recent modifications.
 
 ## Summary
 
@@ -41,6 +45,73 @@ c1 = AiClient.new('nomic-embeddings-text')
 c2 = AiClient.new('gpt-4o-mini')
 ```
 
+### Configuration
+
+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.configuration do |config|
+  config.some_item = some_value
+  ...
+end
+```
+
+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
+```
+
+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.
@@ -53,7 +124,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
 
@@ -65,6 +136,15 @@ TODO: list all providers supported and their envar
 
 TODO: document the options like `provider: :ollama`
 
+## 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
+
 ## 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/lib/ai_client/config.yml

@@ -0,0 +1,33 @@
+---
+: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|davinci|curie|babbage|ada|whisper|tts|dall-e)/i
+  :google: !ruby/regexp /^(gemini|palm)/i
+  :mistral: !ruby/regexp /^(mistral|codestral)/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

data/lib/ai_client/configuration.rb

@@ -1,84 +1,148 @@
 # ai_client/configuration.rb
+#
+# 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')
 
+
+require 'hashie'
 require 'logger'
+require 'yaml'
+require 'pathname'
 
 class AiClient
-  # TODO: Need a centralized service where
-  #       metadata about LLMs are available
-  #       via and API call.  Would hope that
-  #       the providers would add a "list"
-  #       endpoint to their API which would
-  #       return the metadata for all of their
-  #       models.
+  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
+  
 
-  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
-  }
+    # I'm not sure about this ...
+    # def provider(name, &block)
+    #   if block_given?
+    #     providers[name] = block.call
+    #   else
+    #     providers[name] || {}
+    #   end
+    # end
 
-  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 << 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
-      yield(configuration)
+    def configure(&block)
+      yield(class_config)
     end
 
-    def configuration
-      @configuration ||= Configuration.new
-    end
+    private
 
+    def initialize_defaults
+      @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
+    end
   end
 
+  initialize_defaults
+end
 
 
+AiClient.default_config = AiClient::Config.load
+AiClient.class_config   = AiClient.default_config.dup
 
-  # Usage example:
-  # Configure general settings
-  #   AiClient.configure do |config|
-  #     config.logger = Logger.new('ai_client.log')
-  #     config.return_raw = true
-  #   end
-  #
-  # Configure provider-specific settings
-  #   AiClient.configure do |config|
-  #     config.configure_provider(:openai) do
-  #       {
-  #         organization: 'org-123',
-  #         api_version: 'v1'
-  #       }
-  #     end
-  #   end
-  #
-
-  class Configuration
-    attr_accessor :logger, :timeout, :return_raw
-    attr_reader :providers, :provider_patterns, :model_types
-
-    def initialize
-      @logger             = Logger.new(STDOUT)
-      @timeout            = nil
-      @return_raw         = false
-      @providers          = {}
-      @provider_patterns  = AiClient::PROVIDER_PATTERNS.dup
-      @model_types        = AiClient::MODEL_TYPES.dup
-    end
-
-    def provider(name, &block)
-      if block_given?
-        @providers[name] = block
-      else
-        @providers[name]&.call || {}
-      end
-    end
-  end
-end
+if config_file = ENV.fetch('AI_CLIENT_CONFIG_FILE', nil)
+  AiClient.class_config.merge!(AiClient::Config.load(config_file))
+end

data/lib/ai_client/middleware.rb

@@ -0,0 +1,37 @@
+# lib/ai_client/middleware.rb
+
+# TODO: As concurrently designed the middleware must
+#       be set before an instance of AiClient is created.
+#       Any `use` commands for middleware made after
+#       the instance is created will not be available
+#       to that instance.
+#       Change this so that middleware can be added
+#       and removed from an existing client.
+
+
+class AiClient
+
+  def call_with_middlewares(method, *args, **kwargs, &block)
+    stack = self.class.middlewares.reverse.reduce(-> { send(method, *args, **kwargs, &block) }) do |next_middleware, middleware|
+      -> { middleware.call(self, next_middleware, *args, **kwargs) }
+    end
+    stack.call
+  end
+
+
+  class << self
+
+    def middlewares
+      @middlewares ||= []
+    end
+
+    def use(middleware)
+      middlewares << middleware
+    end
+
+    def clear_middlewares
+      @middlewares = []
+    end
+  end
+
+end

data/lib/ai_client/version.rb

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

data/lib/ai_client.rb

@@ -17,6 +17,7 @@ require_relative 'extensions/omniai-ollama'
 require_relative 'extensions/omniai-localai'
 
 require_relative 'ai_client/configuration'
+require_relative 'ai_client/middleware'
 require_relative 'ai_client/version'
 
 # Create a generic client instance using only model name
@@ -26,25 +27,53 @@ require_relative 'ai_client/version'
 #   AiClient.use(RetryMiddleware.new(max_retries: 5, base_delay: 2, max_delay: 30))
 #   AiClient.use(LoggingMiddleware.new(AiClient.configuration.logger))
 #
-# TODO: As concurrently designed the middleware must
-#       be set before an instance of AiClient is created.
-#       Any `use` commands for middleware made after
-#       the instance is created will not be available
-#       to that instance.
-#       Change this so that middleware can be added
-#       and removed from an existing client.
+
 
 class AiClient
 
-  attr_reader :client, :provider, :model, :model_type, :logger, :last_response, :config
+  attr_reader :client,        # OmniAI's client instance
+              :provider,      # [Symbol]
+              :model,         # [String]
+              :model_type,    # [Symbol]
+              :logger, 
+              :last_response,
+              :timeout,
+              :config         # Instance configuration
+
+  # You can over-ride the class config by providing a block like this
+  #   c = AiClient.new(...) do |config|
+  #         config.logger = nil
+  #       end
+  #
+  # You can also load an instance's config from a YAML file.
+  #   c = AiClient.new('model_name'. cpmfog: 'path/to/file.yml', ...)
+  #
+  # ... and you can do both = load from a file and
+  #     over-ride with a config block
+  #
+  # The options object is basically those things that the
+  # OmniAI clients want to see.
+  #
+  def initialize(model, **options, &block)
+    # Assign the instance variable @config from the class variable @@config
+    @config = self.class.class_config.dup  
+    
+    # Yield the @config to a block if given
+    yield(@config) if block_given?
+
+    # Merge in an instance-specific YAML file
+    if options.has_key?(:config)
+      @config.merge! Config.load(options[:config])
+      options.delete(:config) # Lconfig not supported by OmniAI
+    end
+
+    @model            = model
+    explicit_provider = options.fetch(:provider, config.provider)
 
-  def initialize(model, config: Configuration.new, **options)
-    @model      = model
-    @config     = config
-    @provider   = validate_provider(options[:provider]) || determine_provider(model)
+    @provider   = validate_provider(explicit_provider) || determine_provider(model)
     @model_type = determine_model_type(model)
 
-    provider_config = @config.provider(@provider)
+    provider_config = @config.providers[@provider] || {}
 
     @logger   = options[:logger]    || @config.logger
     @timeout  = options[:timeout]   || @config.timeout
@@ -58,6 +87,7 @@ class AiClient
   end
 
 
+
   def response  = last_response
   def raw?      = config.return_raw
   
@@ -71,7 +101,6 @@ class AiClient
   def chat(messages, **params)
     result = call_with_middlewares(:chat_without_middlewares, messages, **params)
     @last_response = result
-    # debug_me print " (raw: #{raw?}) "
     raw? ? result : content
   end
 
@@ -114,14 +143,6 @@ class AiClient
   ######################################
   ## Utilities
   
-  def call_with_middlewares(method, *args, **kwargs, &block)
-    stack = self.class.middlewares.reverse.reduce(-> { send(method, *args, **kwargs, &block) }) do |next_middleware, middleware|
-      -> { middleware.call(self, next_middleware, *args, **kwargs) }
-    end
-    stack.call
-  end
-
-
   def content
     case @provider
     when :openai, :localai, :ollama
@@ -141,21 +162,6 @@ class AiClient
   ##############################################
   ## Public Class Methods
 
-  class << self
-
-    def middlewares
-      @middlewares ||= []
-    end
-
-    def use(middleware)
-      middlewares << middleware
-    end
-
-    def clear_middlewares
-      @middlewares = []
-    end
-  end
-
   def method_missing(method_name, *args, &block)
     if @client.respond_to?(method_name)
       result = @client.send(method_name, *args, &block)

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: ai_client
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Dewayne VanHoozer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-10-03 00:00:00.000000000 Z
+date: 2024-10-05 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: hashie
+  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: omniai
   requirement: !ruby/object:Gem::Requirement
@@ -108,6 +122,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
@@ -141,19 +169,23 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".envrc"
+- ".irbrc"
 - CHANGELOG.md
 - LICENSE
 - 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/config.yml
 - lib/ai_client/configuration.rb
 - lib/ai_client/logger_middleware.rb
+- lib/ai_client/middleware.rb
 - lib/ai_client/retry_middleware.rb
 - lib/ai_client/version.rb
 - lib/extensions/omniai-localai.rb