ai_client 0.2.4 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7b12150b0f3f29804d520aa319a99cc71adc96f023ec99bccc0a9a6682bdba6e
-  data.tar.gz: 59d811a6b9de974f76672a9a1386d6efd3e4547d53ae7b4d24c532a250c00c86
+  metadata.gz: 2453f748447f37e755f0087615c845570fe3ea3c4bd06a687947dceedee3e89b
+  data.tar.gz: 79359bcd209448add248514d9a8ee5dc4e0fa69833666df0e779715b574d450a
 SHA512:
-  metadata.gz: 0beacebae38d5c2101498a59245c5112469ff8fddda2723b5d916ae6d5f731fa6e9e55de46422a6daf463242356e1575c0bbdf77612f9edf9fd05d6b4f885407
-  data.tar.gz: 36b2b5f5fd3d51577b31ac8cbcd57980cb7d0a912428f37e8f345764620aa02198a65b905505136ea40ea2866e274b1f8d6b9b1c9390ccd3608eaad138c37ebb
+  metadata.gz: 28007804ea1e223b22846cc199c4bd14d7349f5e051bbc7007ced3641e7174c3fac59b7a225bc4926ffc68d5018a35ed96a8809bf959c8007e978bc831770b9a
+  data.tar.gz: 18ce04f9f83d0c12caadab051b81c48f7dbafa73ff0b2a34df28e3ddfb5ff3c088dcec019a15bc2f2dfc909bb6db0a308b512b6711baaab058629705a1448040

data/CHANGELOG.md

@@ -1,6 +1,15 @@
 ## [Unreleased]
 
 ## Released
+
+### [0.3.0] - 2024-10-13
+- Breaking Change
+- Added new class AiClient::Function to encapsulate the callback functions used as tools in chats.
+- Updated the examples/tools.rb file to use the new function class
+
+### [0.2.5] - 2024-10-11
+- Added examples/tools.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

@@ -2,6 +2,8 @@
 
 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.
 
+Version 0.3.0 has a breaking change w/r/t how [Callback Functions (aka Tools)](#callback-functions-aka-tools) are defined and used.
+
 See the  [change log](CHANGELOG.md) for recent modifications.
 
 
@@ -33,7 +35,8 @@ See the  [change log](CHANGELOG.md) for recent modifications.
         - [transcribe](#transcribe)
     - [Options](#options)
     - [Advanced Prompts](#advanced-prompts)
-    - [Advanced Prompts with Tools](#advanced-prompts-with-tools)
+    - [Callback Functions (aka Tools)](#callback-functions-aka-tools)
+        - [Defining a Callback Function](#defining-a-callback-function)
   - [Best ?? Practices](#best--practices)
   - [OmniAI and OpenRouter](#omniai-and-openrouter)
   - [Contributing](#contributing)
@@ -278,14 +281,55 @@ 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.
+### Callback Functions (aka Tools)
+
+With the release of version 0.3.0, the way callback functions (also referred to as tools) are defined in the `ai_client` gem has undergone significant changes. This section outlines the new approach in detail.  These changes are designed to create a clearer and more robust interface for developers when working with callback functions. If you encounter any issues while updating your functions, please consult the official documentation or raise an issue in the repository.
+
+##### Defining a Callback Function
+
+To define a callback function, you need to create a subclass of `AiClient::Function`. In this subclass, both the `call` and `details` methods must be implemented.
 
-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.
+**Example**
 
+Here's an example illustrating how to define a callback function using the new convention:
 
-TODO: Need to create an example RAG that does not need another access token to a service
+```ruby
+class WeatherFunction < AiClient::Function
+  # The call class method returns a String to be used by the LLM
+  def self.call(location:, unit: 'Celsius')
+    "#{rand(20..50)}° #{unit} in #{location}"
+  end
+
+  # The details method must return a hash with metadata about the function.
+  def self.details
+    {
+      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: [:location]
+      )
+    }
+  end
+end
+
+# Register the WeatherFunction for use.
+WeatherFunction.register
+
+# Use the *.details[:name] value to reference the tools available for
+# the LLM to use in processing the prompt.
+response = AI.chat("what is the weather in London", tools: ['weather'])
+```
+
+In this example:
+- The `call` method is defined to accept named parameters: `location` and `unit`. The default value for `unit` is set to `'Celsius'`.
+- The `details` method provides metadata about the function, ensuring that the parameters section clearly indicates which parameters are required.
+
+See the [examples/tools.rb file](examples/tools.rb) for additional examples.
 
 
 ## Best ?? Practices
@@ -303,6 +347,7 @@ 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
 
 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.

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,123 @@
+#!/usr/bin/env ruby
+# examples/tools.rb
+#
+# Uses the AiClient::Function class to encapsulate the
+# tools used as callback functions when specified in a
+# chat prompt.
+
+
+require_relative 'common'
+
+AI = AiClient.new('gpt-4o')
+
+box "Random Weather (temperature) Example"
+title "Uses two named parameters to the callback function"
+
+# Example subclass implementation
+class WeatherFunction < AiClient::Function
+  def self.call(location:, unit: 'Celsius')
+    "#{rand(20..50)}° #{unit} in #{location}"
+  end
+
+  # Encapsulates registration details for the function
+  def self.details
+    # SMELL:  reconcile regester_tool and details
+    {
+      name:         'weather', # Must be a String
+      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: [:location]
+      )
+    }
+  end
+end
+
+# Register the tool for MyFunction
+WeatherFunction.register
+
+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'] # must match the details[:name] value
+                  )
+
+puts response
+
+
+##########################################
+box "Accessing a database to get information"
+title "Uses one named parameter to the callback function"
+
+class LLMDetailedFunction < AiClient::Function
+  def self.call(model_name:)
+    records = AiClient::LLM.where(id: /#{model_name}/i)&.first
+    records.inspect
+  end
+
+  def self.details
+    {
+      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]
+      )
+    }  
+  end
+end
+
+# Registering the LLM detail function
+LLMDetailedFunction.register
+
+simple_prompt = <<~PROMPT
+  Get the details on an LLM model named 'bison' from the models database 
+  of #{AiClient::LLM.count} models. Format the details for the model
+  using markdown.  Format pricing information in terms of number of
+  tokens per US dollar.
+PROMPT
+
+response = AI.chat(simple_prompt, tools: ['llm_db'])
+puts response
+
+
+
+##########################################
+
+box "Using a function class and multiple tools"
+title "Callback function has no parameters; but uses two functions"
+
+class PerfectDateFunction < AiClient::Function
+  def self.call
+    "April 25th, it's not too hot nor too cold."
+  end
+
+  def self.details
+    {
+      name:         'perfect_date',
+      description:  'what is the perfect date'
+    }
+  end
+end
+
+# Registering the perfect date function
+PerfectDateFunction.register
+
+response = AI.chat("what is the perfect date for current weather in Paris?", 
+                   tools: %w[weather perfect_date])
+puts response
+puts
+
+debug_me{[
+  #'AiClient::Function.registry',
+  'AiClient::Function.functions'
+]}

data/lib/ai_client/chat.rb

@@ -10,7 +10,19 @@ class AiClient
   #   tools:        @tools    [Array<OmniAI::Tool>] optional
   #   temperature:  @temperature  [Float, nil] optional
 
-  def chat(messages, **params)
+  def chat(messages, **params)    
+    if params.has_key? :tools
+      tools = params[:tools]
+      if tools.is_a? Array
+        tools.map!{|function_name| AiClient::Function.registry[function_name]}
+      elsif true == tools
+        tools = AiClient::Function.registry.values
+      else
+        raise 'what is this'
+      end
+      params[:tools] = tools
+    end
+
     result = call_with_middlewares(:chat_without_middlewares, messages, **params)
     @last_response = result
     raw? ? result : content

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/function.rb

@@ -0,0 +1,100 @@
+# lib/ai_client/function.rb
+
+class AiClient
+
+  # The Function class serves as a base class for creating functions
+  # that can be registered and managed within the AiClient.
+  #
+  # Subclasses must implement the `call` and `details` methods
+  # to define their specific behavior and properties.
+  #
+  class Function
+    @@registry = {} # key is known by name (from details) and value is the AiClient::Tool
+
+    class << self
+
+      # Calls the function with the provided parameters.
+      #
+      # @param params [Hash] Named parameters required by the function.
+      # @raise [NotImplementedError] if not implemented in the subclass.
+      #
+      def call(**params)
+        raise NotImplementedError, "You must implement the call method"
+      end
+
+      # Provides the details about the function including its metadata.
+      #
+      # @return [Hash] Metadata containing details about the function.
+      # @raise [NotImplementedError] if not implemented in the subclass.
+      #
+      def details
+        raise NotImplementedError, "You must implement the details method"
+      end
+
+
+      # Registers a tool with the specified properties and parameters.
+      #
+      # This method creates an instance of AiClient::Tool with the
+      # function class and its details and adds it to the registry.
+      #
+      def register
+        this_tool = AiClient::Tool.new(
+                      self, # This is the sub-class
+                      **details
+                    )
+
+        registry[known_by] = this_tool
+      end
+      alias_method :enable, :register
+
+
+      # Disables the function by removing its name from the registry.
+      #
+      # @return [void]
+      #
+      def disable
+        registry.delete(known_by)
+      end
+
+
+      # Returns a list of enabled functions.
+      #
+      # @return [Array<Symbol>] Sorted list of function names.
+      #
+      def functions
+        registry.keys.sort
+      end
+
+
+      # Returns the registry of currently registered functions.
+      # This method is private to limit access to the registry's state.
+      #
+      # @return [Hash] The registry of registered functions.
+      #
+      def registry
+        @@registry
+      end
+
+
+      # Returns the name under which the function is known.
+      #
+      # @return [Symbol] The symbol representation of the function's name.
+      #
+      def known_by
+        details[:name]
+      end
+
+
+      private
+
+      # Converts the class name to a symbol (e.g., MyFunction -> :my_function).
+      #
+      # @return [Symbol] The function name derived from the class name.
+      #
+      def function_name
+        name.split('::').last.gsub(/([a-z])([A-Z])/, '\1_\2').downcase
+      end
+    end
+  end
+end
+

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.3.0"
 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,11 @@ 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'
+require_relative 'ai_client/function'
 
 # Create a generic client instance using only model name
 #   client = AiClient.new('gpt-3.5-turbo')
@@ -76,6 +79,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 +95,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 +134,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 +176,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 +193,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 +207,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 +224,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 +266,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 +277,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.3.0
 platform: ruby
 authors:
 - Dewayne VanHoozer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-10-10 00:00:00.000000000 Z
+date: 2024-10-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: active_hash
@@ -219,12 +219,14 @@ 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
 - lib/ai_client/config.yml
 - lib/ai_client/configuration.rb
 - lib/ai_client/embed.rb
+- lib/ai_client/function.rb
 - lib/ai_client/llm.rb
 - lib/ai_client/logger_middleware.rb
 - lib/ai_client/middleware.rb
@@ -232,6 +234,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