ai_client 0.2.3 → 0.2.5

data/lib/ai_client/open_router_extensions.rb

@@ -5,16 +5,56 @@
 # a valid API Key for the open_router.ai web-service
 
 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
 
@@ -24,17 +64,30 @@ 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
 
-    def models
-      @models ||= orc_client.models
+    # Retrieves models from the ORC client.
+    #
+    # @return [Array<Hash>] List of models.
+    #
+    def orc_models
+      @orc_models ||= orc_client.models
     end
 
     # 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'] }
 
@@ -43,37 +96,72 @@ 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)
+    end
+
+
     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.3"
+  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.3
+  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
@@ -100,14 +100,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.8.3
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.8.3
 - !ruby/object:Gem::Dependency
   name: open_router
   requirement: !ruby/object:Gem::Requirement
@@ -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
@@ -228,9 +229,11 @@ files:
 - lib/ai_client/llm.rb
 - lib/ai_client/logger_middleware.rb
 - lib/ai_client/middleware.rb
+- lib/ai_client/models.yml
 - 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