ai_client 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 107e9d57f175adc72178f48365a833a4dab7fbe71088169774429f43624d7d9c
-  data.tar.gz: d308008540c4fbf309235c31d60b1a98b14a608a0f69d7ee1bac6911f34dad47
+  metadata.gz: c938cc076640fa6952b1140252b0c234a44e7dfd6ee24d2485c344d3b2c98880
+  data.tar.gz: 1dc5cb21b49c2a731689e7ab7d4f6cce56392b06ecb83e2d54b535ec0d0b3d27
 SHA512:
-  metadata.gz: b001c640758c846f2372354660d4a4f4c7ef4a6c4671bbd743fcc713d543faff1fe54ff2e341285ec57dbaf284db3e3a18a50cbd6b420fd01ac911112a93ae8a
-  data.tar.gz: 0055623e374bb4cf111a234712e9ac1441d6ddb541f2f7ebadc604c255e27bdd6ad14d1b2a81d56cb6e2797e01f3d3398eb4b4b3e6c7d04802dadf620ecb0390
+  metadata.gz: d2d81aa7bc979a8c75856965261ce54470ef3df1586eb65e809c2e4d32f8a4771a22a85640e026260826ab691e54742666ce0b9d71f2ba992b60db3d5c689cc8
+  data.tar.gz: 7347641ccb974d62c0393a364cb09b214019c0e99a2514478632a9b0c4736bf530c0ba415bae316b0438230691418265b21aed46ef32ca122935d73e30085f41

data/CHANGELOG.md

@@ -1,6 +1,9 @@
 ## [Unreleased]
 
 ## 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.
 

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
 
@@ -43,28 +47,71 @@ c2 = AiClient.new('gpt-4o-mini')
 
 ### 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 +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
 
@@ -89,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,27 +1,81 @@
 # ai_client/configuration.rb
 #
-# Design Objective:
-# AiClient.configure do |config|
-#   # global config items that over-ride the defaults
-# end
+# AiClient and AiClient::Config
 #
-# client = AiClient.new(...) do
-#   # client specific config items that over-ride the global config
-# end 
+# 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: 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 +90,59 @@ class AiClient
     #   end
     # end
 
+    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 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
+    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|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
+
+if config_file = ENV.fetch('AI_CLIENT_CONFIG_FILE', nil)
+  AiClient.class_config.merge!(AiClient::Config.load(config_file))
 end

data/lib/ai_client/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ai_client
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Dewayne VanHoozer
@@ -122,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
@@ -161,12 +175,14 @@ 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/config.yml
 - lib/ai_client/configuration.rb
 - lib/ai_client/logger_middleware.rb
 - lib/ai_client/middleware.rb