ai_client 0.2.4 → 0.2.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7b12150b0f3f29804d520aa319a99cc71adc96f023ec99bccc0a9a6682bdba6e
-  data.tar.gz: 59d811a6b9de974f76672a9a1386d6efd3e4547d53ae7b4d24c532a250c00c86
+  metadata.gz: f2b330f59ff7f380306ec354ce5f7197adce8dd101a4b506ab137568f098242a
+  data.tar.gz: f169296b9f20479b1c608f2202d9ab8a8eb416aa80b07f4308ec4648b9c86fcc
 SHA512:
-  metadata.gz: 0beacebae38d5c2101498a59245c5112469ff8fddda2723b5d916ae6d5f731fa6e9e55de46422a6daf463242356e1575c0bbdf77612f9edf9fd05d6b4f885407
-  data.tar.gz: 36b2b5f5fd3d51577b31ac8cbcd57980cb7d0a912428f37e8f345764620aa02198a65b905505136ea40ea2866e274b1f8d6b9b1c9390ccd3608eaad138c37ebb
+  metadata.gz: ce0e2cddd8ec6935a5bea24125358fbcc8fda902340d7767972142505af41eaeef7d7f6f5791bd7d26469fd45e59020237fd0061e75d6a987d8a4181597cdbe9
+  data.tar.gz: 4b2513fba82802eda13cf26c1af0e73f0903a2140765401ed686540d80480d887f2152e342a5fe3546c89482320f61cc6bd04b4e41b8851668bbda31b2496fc9

data/CHANGELOG.md

@@ -1,6 +1,10 @@
 ## [Unreleased]
 
 ## Released
+
+### [0.2.5] - 2024-10-11
+- Added examples/tool.rb to demonstrate use of function callbacks to provide information to the LLM when it needs it.
+
 ### [0.2.4] - 2024-10-10
 - constrained gem omniai-openai to version 1.8.3+ for access to open_router.ai
 - caching models database from open_router.ai

data/README.md

@@ -284,8 +284,7 @@ One of the latest innovations in LLMs is the ability to use functions (aka tools
 
 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
+Take a look at the [examples/tools.rb](examples/tools.rb) file to see different ways in which these callable processes can be defined.
 
 
 ## Best ?? Practices

data/examples/README.md

@@ -7,6 +7,7 @@
 | 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" |
+| tools.rb | Demonstrates usage of functional callbacks (i.e. tools) |
 | 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

data/examples/tools.rb

@@ -0,0 +1,90 @@
+#!/usr/bin/env ruby
+# examples/tools.rb
+# See: https://ksylvest.com/posts/2024-08-16/using-omniai-to-leverage-tools-with-llms
+
+require_relative 'common'
+
+AI = AiClient.new('gpt-4o')
+
+box "omniai-openai's random temp example"
+
+my_weather_function = Proc.new do |location:, unit: 'Celsius'| 
+  "#{rand(20..50)}° #{unit} in #{location}"
+end
+
+weather = AiClient::Tool.new(
+  my_weather_function,
+  name: 'weather',
+  description: 'Lookup the weather in a location',
+  parameters: AiClient::Tool::Parameters.new(
+    properties: {
+      location: AiClient::Tool::Property.string(description: 'e.g. Toronto'),
+      unit: AiClient::Tool::Property.string(enum: %w[Celsius Fahrenheit]),
+    },
+    required: %i[location]
+  )
+)
+
+simple_prompt = <<~TEXT
+  What is the weather in "London" in Celsius and "Paris" in Fahrenheit?
+  Also what are some ideas for activities in both cities given the weather?
+TEXT
+
+response = AI.chat(simple_prompt, tools: [weather])
+puts response
+
+##########################################
+box "Accessing a database to get information"
+
+llm_db_function = Proc.new do |params|
+  records = AiClient::LLM.where(id: /#{params[:model_name]}/i)
+  records.inspect
+end
+
+
+llm_db = AiClient::Tool.new(
+  llm_db_function,
+  name: 'llm_db',
+  description: 'lookup details about an LLM model name',
+  parameters: AiClient::Tool::Parameters.new(
+    properties: {
+      model_name: AiClient::Tool::Property.string
+    },
+    required: %i[model_name]
+  )
+)
+
+response = AI.chat("Get details on an LLM model named bison.  Which one is the cheapest per prompt token.", tools: [llm_db])
+puts response
+
+##########################################
+
+# TODO: Look at creating a better function
+#       process such that the tools parameter
+#       is an Array of Symbols which is
+#       maintained as a class variable.
+#       The symboles are looked up and the
+#       proper instance is inserted in its
+#       place.
+
+box "Using a function class and multiple tools"
+
+class FunctionClass
+  def self.call
+    "April 25th its not to hot nor too cold."
+  end
+
+  def function(my_name)
+    AiClient::Tool.new(
+      self.class, # with a self.call method
+      name: my_name,
+      description: 'what is the perfect date'
+    )
+  end
+end
+
+perfect_date = FunctionClass.new.function('perfect_date')
+
+response = AI.chat("what is the perfect date for paris weather?", tools: [weather, perfect_date])
+puts response
+puts

data/lib/ai_client/configuration.rb

@@ -92,7 +92,11 @@ class AiClient
     include Hashie::Extensions::Mash::SymbolizeKeys
     include Hashie::Extensions::Mash::DefineAccessors
 
-
+    # Saves the current configuration to the specified file.
+    #
+    # @param filepath [String] The path to the file where the configuration will be saved.
+    #   Defaults to '~/aiclient_config.yml' if not provided.
+    #
     def save(filepath=ENV['HOME']+'/aiclient_config.yml')
       filepath = Pathname.new(filepath) unless filepath.is_a? Pathname
 
@@ -101,6 +105,13 @@ class AiClient
 
 
     class << self
+      # Loads configuration from the specified YAML file.
+      #
+      # @param filepath [String] The path to the configuration file.
+      #   Defaults to 'config.yml' if not provided.
+      # @return [AiClient::Config] The loaded configuration.
+      # @raise [ArgumentError] If the specified file does not exist.
+      #
       def load(filepath=DEFAULT_CONFIG_FILEPATH)
         filepath = Pathname.new(filepath) unless Pathname == filepath.class
         if filepath.exist?
@@ -115,17 +126,30 @@ class AiClient
   class << self
     attr_accessor :class_config, :default_config
 
+    # Configures the AiClient with a given block.
+    #
+    # @yieldparam config [AiClient::Config] The configuration instance.
+    # @return [void]
+    #
     def configure(&block)
       yield(class_config)
     end
 
+    # Resets the default configuration to the value defined in the class.
+    #
+    # @return [void]
+    #
     def reset_default_config
       initialize_defaults
         .save(Config::DEFAULT_CONFIG_FILEPATH)      
     end
 
     private
-
+    
+    # Initializes the default configuration.
+    #
+    # @return [void]
+    #
     def initialize_defaults
       @default_config = Config.new(
         logger: Logger.new(STDOUT),

data/lib/ai_client/llm.rb

@@ -9,11 +9,26 @@ class AiClient
     DATA_PATH = Pathname.new( __dir__ + '/models.yml')
     self.data = YAML.parse(DATA_PATH.read).to_ruby 
 
+    # Extracts the model name from the LLM ID.
+    #
+    # @return [String] the model name.
+    #
     def model     = id.split('/')[1]
+
+    # Extracts the provider name from the LLM ID.
+    #
+    # @return [String] the provider name.
+    #
     def provider  = id.split('/')[0]
   end
 
   class << self
+    
+    # Resets the LLM data by fetching models from the Orc client
+    # and writing it to the models.yml file.
+    #
+    # @return [void] 
+    #
     def reset_llm_data
       orc_models = AiClient.orc_client.models
       AiClient::LLM.data = orc_models

data/lib/ai_client/logger_middleware.rb

@@ -16,10 +16,23 @@ class AiClient
   # )
 
   class LoggingMiddleware
+    
+    # Initializes the LoggingMiddleware with a logger.
+    #
+    # @param logger [Logger] The logger used for logging middleware actions.
+    #
     def initialize(logger)
       @logger = logger
     end
 
+    # Calls the next middleware in the stack while logging the start and finish times.
+    #
+    # @param client [Object] The client instance.
+    # @param next_middleware [Proc] The next middleware to call.
+    # @param args [Array] The arguments passed to the middleware call, with the first being the method name.
+    #
+    # @return [Object] The result of the next middleware call.
+    #
     def call(client, next_middleware, *args)
       method_name = args.first.is_a?(Symbol) ? args.first : 'unknown method'
       @logger.info("Starting #{method_name} call")

data/lib/ai_client/middleware.rb

@@ -8,9 +8,19 @@
 #       Change this so that middleware can be added
 #       and removed from an existing client.
 
-
+# AiClient class that handles middleware functionality
+# for API calls.
 class AiClient
 
+  # Calls the specified method with middlewares applied.
+  #
+  # @param method [Symbol] the name of the method to be called
+  # @param args [Array] additional arguments for the method
+  # @param kwargs [Hash] named parameters for the method
+  # @param block [Proc] optional block to be passed to the method
+  #
+  # @return [Object] result of the method call after applying middlewares
+  #
   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) }
@@ -21,17 +31,30 @@ class AiClient
 
   class << self
 
+    # Returns the list of middlewares applied to the client.
+    #
+    # @return [Array] list of middlewares
+    #
     def middlewares
       @middlewares ||= []
     end
 
+    # Adds a middleware to the stack.
+    #
+    # @param middleware [Proc] the middleware to be added
+    #
+    # @return [void]
+    #
     def use(middleware)
       middlewares << middleware
     end
 
+    # Clears all middlewares from the client.
+    #
+    # @return [void]
+    #
     def clear_middlewares
       @middlewares = []
     end
   end
-
 end

data/lib/ai_client/open_router_extensions.rb

@@ -8,14 +8,53 @@ require 'open_router'
 require 'yaml'
 
 class AiClient
+  
+  # Retrieves the available models.
+  #
+  # @return [Array<String>] List of model IDs.
+  #
+  def models
+    self.class.models
+  end
+
+  # Retrieves the available providers.
+  #
+  # @return [Array<String>] List of provider names.
+  def providers
+    self.class.providers
+  end
+
+  # Retrieves model names, optionally filtered by provider.
+  #
+  # @param provider [String, nil] The provider to filter models by.
+  # @return [Array<String>] List of model names.
+  def model_names(provider = nil)
+    self.class.model_names(provider)
+  end
+
+  # Retrieves details for a specific model.
+  #
+  # @param a_model [String] The model ID to retrieve details for.
+  # @return [Hash, nil] Details of the model or nil if not found.
+  def model_details(a_model)
+    self.class.model_details(a_model)
+  end
+
+  # Finds models matching a given substring.
+  #
+  # @param a_model_substring [String] The substring to search for.
+  # @return [Array<String>] List of matching model names.
+  def find_model(a_model_substring)
+    self.class.find_model(a_model_substring)
+  end
 
-  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
+    
+    # Adds OpenRouter extensions to AiClient.
+    #
+    # @return [void]
+    #
     def add_open_router_extensions
       access_token = fetch_access_token
 
@@ -25,10 +64,18 @@ class AiClient
       initialize_orc_client
     end
 
+    # Retrieves ORC client instance.
+    #
+    # @return [OpenRouter::Client] Instance of the OpenRouter client.
+    #
     def orc_client
       @orc_client ||= add_open_router_extensions || raise("OpenRouter extensions are not available")
     end
 
+    # Retrieves models from the ORC client.
+    #
+    # @return [Array<Hash>] List of models.
+    #
     def orc_models
       @orc_models ||= orc_client.models
     end
@@ -36,6 +83,11 @@ class AiClient
     # TODO: Refactor these DB like methods to take
     #       advantage of AiClient::LLM
 
+    # Retrieves model names associated with a provider.
+    #
+    # @param provider [String, nil] The provider to filter models by.
+    # @return [Array<String>] List of model names.
+    #
     def model_names(provider=nil)
       model_ids = models.map { _1['id'] }
 
@@ -44,18 +96,36 @@ class AiClient
       model_ids.filter_map { _1.split('/')[1] if _1.start_with?(provider.to_s.downcase) }
     end
 
+    # Retrieves details of a specific model.
+    #
+    # @param model [String] The model ID to retrieve details for.
+    # @return [Hash, nil] Details of the model or nil if not found.
+    #
     def model_details(model)
       orc_models.find { _1['id'].include?(model) }
     end
 
+    # Retrieves the available providers.
+    #
+    # @return [Array<String>] List of unique provider names.
+    #
     def providers
       @providers ||= models.map{ _1['id'].split('/')[0] }.sort.uniq      
     end
 
+    # Finds models matching a given substring.
+    #
+    # @param a_model_substring [String] The substring to search for.
+    # @return [Array<String>] List of matching model names.
+    #
     def find_model(a_model_substring)
       model_names.select{ _1.include?(a_model_substring) }
     end
   
+    # Resets LLM data with the available ORC models.
+    #
+    # @return [void]
+    #
     def reset_llm_data
       LLM.data = orc_models
       LLM::DATA_PATH.write(orc_models.to_yaml)
@@ -64,23 +134,34 @@ class AiClient
 
     private
 
-    # Similar to fetch_api_key but for the class_config
+    # Fetches the access token from environment variables.
+    #
+    # @return [String, nil] The access token or nil if not found.
+    #
     def fetch_access_token
       class_config.envar_api_key_names.open_router
                   .map { |key| ENV[key] }
                   .compact
                   .first
     end
-    
+
+    # Configures the OpenRouter client with the access token.
+    #
+    # @param access_token [String] The access token to configure.
+    # @return [void]
+    #
     def configure_open_router(access_token)
       OpenRouter.configure { |config| config.access_token = access_token }
     end
 
+    # Initializes the ORC client.
+    #
+    # @return [void]
+    #
     def initialize_orc_client
       @orc_client ||= OpenRouter::Client.new
     end
   end
 end
 
-
 AiClient.add_open_router_extensions

data/lib/ai_client/retry_middleware.rb

@@ -11,12 +11,27 @@ class AiClient
   # )
   #
   class RetryMiddleware
+
+    # Initializes a new instance of RetryMiddleware.
+    #
+    # @param max_retries [Integer] The maximum number of retries to attempt (default: 3).
+    # @param base_delay [Integer] The base delay in seconds before retrying (default: 2).
+    # @param max_delay [Integer] The maximum delay in seconds between retries (default: 16).
+    #
     def initialize(max_retries: 3, base_delay: 2, max_delay: 16)
       @max_retries  = max_retries
       @base_delay   = base_delay
       @max_delay    = max_delay
     end
 
+    # Calls the next middleware, retrying on specific errors.
+    #
+    # @param client [AiClient] The client instance that invokes the middleware.
+    # @param next_middleware [Proc] The next middleware in the chain to call.
+    # @param args [Array] Any additional arguments to pass to the next middleware.
+    #
+    # @raise [StandardError] Reraise the error if max retries are exceeded.
+    #
     def call(client, next_middleware, *args)
       retries = 0
       begin

data/lib/ai_client/tool.rb

@@ -0,0 +1,18 @@
+# lib/ai_client/tool.rb
+
+# TODO: Turn this into a Function class using the pattern
+#       in examples/tools.rb
+#       put the function names as symbols into a class Array
+#       In the AiClient class transform the tools: []
+#       parameter from an Array of Symbols into an Array
+#       of FUnction instances.
+
+class AiClient::Tool < OmniAI::Tool
+  
+  def xyzzy = self.class.xyzzy
+
+  class << self
+    def xyzzy = puts "Magic"
+  end
+end
+

data/lib/ai_client/version.rb

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

data/lib/ai_client.rb

@@ -16,6 +16,8 @@ require 'omniai/openai'
 
 require 'open_router'
 
+require_relative 'ai_client/version'
+
 require_relative 'ai_client/chat'
 require_relative 'ai_client/embed'
 require_relative 'ai_client/speak'
@@ -23,10 +25,10 @@ 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
+require_relative 'ai_client/tool'
 
 # Create a generic client instance using only model name
 #   client = AiClient.new('gpt-3.5-turbo')
@@ -76,6 +78,8 @@ class AiClient
               :timeout,
               :config         # Instance configuration
 
+  # Initializes a new AiClient instance.
+  #
   # You can over-ride the class config by providing a block like this
   #   c = AiClient.new(...) do |config|
   #         config.logger = nil
@@ -90,6 +94,14 @@ class AiClient
   # The options object is basically those things that the
   # OmniAI clients want to see.
   #
+  # @param model [String] The model name to use for the client.
+  # @param options [Hash] Optional named parameters:
+  #   - :provider [Symbol] Specify the provider.
+  #   - :config [String] Path to a YAML configuration file.
+  #   - :logger [Logger] Logger instance for the client.
+  #   - :timeout [Integer] Timeout value for requests.
+  # @yield [config] An optional block to configure the instance.
+  #
   def initialize(model, **options, &block)
     # Assign the instance variable @config from the class variable @@config
     @config = self.class.class_config.dup  
@@ -121,13 +133,34 @@ class AiClient
     @last_response  = nil
   end
 
+  # TODO: Review these raw-ish methods are they really needed?
+  #       raw? should be a private method ??
+
+  # Returns the last response received from the client.
+  #
+  # @return [OmniAI::Response] The last response.
+  #
   def response  = last_response
+  
+  # Checks if the client is set to return raw responses.
+  #
+  # @return [Boolean] True if raw responses are to be returned.
   def raw?      = config.return_raw
   
+
+  # Sets whether to return raw responses.
+  #
+  # @param value [Boolean] The value to set for raw responses return.
+  #
   def raw=(value)
     config.return_raw = value
   end
 
+  # Extracts the content from the last response based on the provider.
+  #
+  # @return [String] The extracted content.
+  # @raise [NotImplementedError] If content extraction is not implemented for the provider.
+  #
   def content
     case @provider
     when :localai, :mistral, :ollama, :open_router, :openai
@@ -142,6 +175,13 @@ class AiClient
   end
   alias_method :text, :content
 
+  # Handles calls to methods that are missing on the AiClient instance.
+  #
+  # @param method_name [Symbol] The name of the method called.
+  # @param args [Array] Arguments passed to the method.
+  # @param block [Proc] Optional block associated with the method call.
+  # @return [Object] The result from the underlying client or raises NoMethodError.
+  #
   def method_missing(method_name, *args, &block)
     if @client.respond_to?(method_name)
       result = @client.send(method_name, *args, &block)
@@ -152,6 +192,12 @@ class AiClient
     end
   end
 
+  # Checks if the instance responds to the missing method.
+  #
+  # @param method_name [Symbol] The name of the method to check.
+  # @param include_private [Boolean] Whether to include private methods in the check.
+  # @return [Boolean] True if the method is supported by the client, false otherwise.
+  #
   def respond_to_missing?(method_name, include_private = false)
     @client.respond_to?(method_name) || super
   end
@@ -160,6 +206,12 @@ class AiClient
   ##############################################
   private
 
+  # Validates the specified provider.
+  #
+  # @param provider [Symbol] The provider to validate.
+  # @return [Symbol, nil] Returns the validated provider or nil.
+  # @raise [ArgumentError] If the provider is unsupported.
+  #
   def validate_provider(provider)
     return nil if provider.nil?
 
@@ -171,7 +223,11 @@ class AiClient
     provider
   end
 
-
+  # Creates an instance of the appropriate OmniAI client based on the provider.
+  #
+  # @return [OmniAI::Client] An instance of the configured OmniAI client.
+  # @raise [ArgumentError] If the provider is unsupported.
+  #
   def create_client
     client_options = {
       api_key:  fetch_api_key,
@@ -209,7 +265,10 @@ class AiClient
   end
 
 
-  # Similar to fetch_access_tokne but for the instance config
+  # Similar to fetch_access_token but for the instance config
+  #
+  # @return [String, nil] The retrieved API key or nil if not found.
+  #
   def fetch_api_key
     config.envar_api_key_names[@provider]
       &.map { |key| ENV[key] }
@@ -217,6 +276,12 @@ class AiClient
       &.first
   end
 
+  # Determines the provider based on the provided model.
+  #
+  # @param model [String] The model name.
+  # @return [Symbol] The corresponding provider.
+  # @raise [ArgumentError] If the model is unsupported.
+  #
   def determine_provider(model)
     config.provider_patterns.find { |provider, pattern| model.match?(pattern) }&.first ||
       raise(ArgumentError, "Unsupported model: #{model}")

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ai_client
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.2.5
 platform: ruby
 authors:
 - Dewayne VanHoozer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-10-10 00:00:00.000000000 Z
+date: 2024-10-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: active_hash
@@ -219,6 +219,7 @@ files:
 - examples/embed.rb
 - examples/speak.rb
 - examples/text.rb
+- examples/tools.rb
 - examples/transcribe.rb
 - lib/ai_client.rb
 - lib/ai_client/chat.rb
@@ -232,6 +233,7 @@ files:
 - lib/ai_client/open_router_extensions.rb
 - lib/ai_client/retry_middleware.rb
 - lib/ai_client/speak.rb
+- lib/ai_client/tool.rb
 - lib/ai_client/transcribe.rb
 - lib/ai_client/version.rb
 - sig/ai_client.rbs