ai_client 0.2.5 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f2b330f59ff7f380306ec354ce5f7197adce8dd101a4b506ab137568f098242a
-  data.tar.gz: f169296b9f20479b1c608f2202d9ab8a8eb416aa80b07f4308ec4648b9c86fcc
+  metadata.gz: 320868a04996fe7ce2b99555b9d5b7c39579eff8be6e73a2ce60534720bd6dbb
+  data.tar.gz: 87b7cf31ba5be1a8acb03a0b56f54ef741e8e1ba0cc03b34045c10768186729d
 SHA512:
-  metadata.gz: ce0e2cddd8ec6935a5bea24125358fbcc8fda902340d7767972142505af41eaeef7d7f6f5791bd7d26469fd45e59020237fd0061e75d6a987d8a4181597cdbe9
-  data.tar.gz: 4b2513fba82802eda13cf26c1af0e73f0903a2140765401ed686540d80480d887f2152e342a5fe3546c89482320f61cc6bd04b4e41b8851668bbda31b2496fc9
+  metadata.gz: c5c96015690e48c578cf88eee643a6b5c4fea551418177b7d2f883114514a469761a502d57846976efac27f2e470b0d7cf37d646e01add5539bc40da3ab50b72
+  data.tar.gz: ab0583961a965fbc7fd51b6159bbde629d19db1ef0105c6d6567f692fc64ca42ac714b488e01aacafa4165345f74a7b9482d1f4107651e591cb337a6a8a79d27

data/CHANGELOG.md

@@ -1,9 +1,19 @@
 ## [Unreleased]
 
+### [0.3.0] - 2024-10-13
+- updated the open_routed_extensions file
+- added simplecov to see code coverage
+- updated README with options doc
+
 ## 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/tool.rb to demonstrate use of function callbacks to provide information to the LLM when it needs it.
+- 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

data/README.md

@@ -2,8 +2,12 @@
 
 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.
 
+You should also checkout the [raix gem](https://github.com/OlympiaAI/raix).  I like the way that Obie's API is setup for callback functions.  `raix-rails` is also available.
+
 
 <!-- Tocer[start]: Auto-generated, don't remove. -->
 
@@ -32,8 +36,23 @@ See the  [change log](CHANGELOG.md) for recent modifications.
         - [speak](#speak)
         - [transcribe](#transcribe)
     - [Options](#options)
+        - [Common Options for All Methods](#common-options-for-all-methods)
+        - [Chat-specific Options](#chat-specific-options)
+        - [Embed-specific Options](#embed-specific-options)
+        - [Speak-specific Options](#speak-specific-options)
+        - [Transcribe-specific Options](#transcribe-specific-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)
+    - [OpenRouter Extensions and AiClient::LLM](#openrouter-extensions-and-aiclientllm)
+        - [Instance Methods](#instance-methods)
+        - [Class Methods](#class-methods)
+    - [AiClient::LLM Data Table](#aiclientllm-data-table)
+        - [Key Features](#key-features)
+        - [Class Methods](#class-methods-1)
+        - [Instance Methods](#instance-methods-1)
+        - [Usage Example](#usage-example)
+        - [Integration with ActiveHash](#integration-with-activehash)
   - [Best ?? Practices](#best--practices)
   - [OmniAI and OpenRouter](#omniai-and-openrouter)
   - [Contributing](#contributing)
@@ -251,10 +270,43 @@ response = AI.transcribe(...)
 ```
 
 
-
 ### Options
 
-TODO: document the options like `provider: :ollama`
+The four major methods (chat, embed, speak, and transcribe) support various options that can be passed to the underlying client code. Here's a breakdown of the common options for each method:
+
+##### Common Options for All Methods
+
+- `provider:` - Specifies the AI provider to use (e.g., `:openai`, `:anthropic`, `:google`, `:mistral`, `:ollama`, `:localai`).
+- `model:` - Specifies the model to use within the chosen provider.
+- `api_key:` - Allows passing a specific API key, overriding the default environment variable.
+- `temperature:` - Controls the randomness of the output (typically a float between 0 and 1).
+- `max_tokens:` - Limits the length of the generated response.
+
+##### Chat-specific Options
+
+- `messages:` - An array of message objects for multi-turn conversations.
+- `functions:` - An array of available functions/tools for the model to use.
+- `function_call:` - Specifies how the model should use functions ("auto", "none", or a specific function name).
+- `stream:` - Boolean to enable streaming responses.
+
+##### Embed-specific Options
+
+- `input:` - The text or array of texts to embed.
+- `dimensions:` - The desired dimensionality of the resulting embeddings (if supported by the model).
+
+##### Speak-specific Options
+
+- `voice:` - Specifies the voice to use for text-to-speech (provider-dependent).
+- `speed:` - Adjusts the speaking rate (typically a float, where 1.0 is normal speed).
+- `format:` - Specifies the audio format of the output (e.g., "mp3", "wav").
+
+##### Transcribe-specific Options
+
+- `file:` - The audio file to transcribe (can be a file path or audio data).
+- `language:` - Specifies the language of the audio (if known).
+- `prompt:` - Provides context or specific words to aid in transcription accuracy.
+
+Note: The availability and exact names of these options may vary depending on the specific provider and model being used. Always refer to the documentation of the chosen provider for the most up-to-date and accurate information on supported options.
 
 ### Advanced Prompts
 
@@ -278,13 +330,179 @@ 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.
+
+**Example**
+
+Here's an example illustrating how to define a callback function using the new convention:
+
+```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.
+
+### OpenRouter Extensions and AiClient::LLM
+
+The `open_router.ai` API provides a service that allows you to download a JSON file containing detailed information about all of the providers and their available models. `AiClient` has saved an old copy of this information in the [`models.yml`](lib/ai_client/models.yml) file. If you want to update this file with the latest information from `open_router.ai`, you must have a valid API key.
+
+You can still use the included `models.yml` file with the `AiClient::LLM` class. The following sections describe the convenient instance and class methods that are available. See the section on `AiClient::LLM` for complete details.
+
+##### Instance Methods
+
+- **`model_details`**: Retrieves details for the current model. Returns a hash containing the model's attributes or `nil` if not found.
+
+```ruby
+client = AiClient.new('gpt-3.5-turbo')
+details = client.model_details
+details #=>
+{
+                    :id => "openai/gpt-3.5-turbo",
+                  :name => "OpenAI: GPT-3.5 Turbo",
+               :created => 1685232000,
+           :description => "GPT-3.5 Turbo is OpenAI's fastest model. It can understand and generate natural language or code, and is optimized for chat and traditional completion tasks.\n\nTraining data up to Sep 2021.",
+        :context_length => 16385,
+          :architecture => {
+             "modality" => "text->text",
+            "tokenizer" => "GPT",
+        "instruct_type" => nil
+    },
+               :pricing => {
+            "prompt" => "0.0000005",
+        "completion" => "0.0000015",
+             "image" => "0",
+           "request" => "0"
+    },
+          :top_provider => {
+               "context_length" => 16385,
+        "max_completion_tokens" => 4096,
+                 "is_moderated" => true
+    },
+    :per_request_limits => {
+            "prompt_tokens" => "40395633",
+        "completion_tokens" => "13465211"
+    }
+}
+```
+
+- **`models`**: Retrieves model names for the current provider. Returns an array of strings with the names of the models.
+
+```ruby
+models = client.models
+```
+
+##### Class Methods
+
+- **`providers`**: Retrieves all available providers. Returns an array of unique symbols representing provider names.
+
+```ruby
+available_providers = AiClient.providers
+```
+
+- **`models(substring = nil)`**: Retrieves model IDs, optionally filtered by a substring.
+
+```ruby
+available_models = AiClient.models('turbo')
+```
+
+- **`model_details(model_id)`**: Retrieves details for a specific model using its ID. Accepts a string representing the model ID. Returns a hash containing the model's attributes or `nil` if not found.
+
+```ruby
+model_info = AiClient.model_details('openai/gpt-3.5-turbo')
+```
+
+- **`reset_llm_data`**: Resets the LLM data with the available ORC models. Returns `void`.
+
+```ruby
+AiClient.reset_llm_data
+```
+
+### AiClient::LLM Data Table
+
+The `AiClient::LLM` class serves as a central point for managing information about large language models (LLMs) available via the `open_router.ai` API service. The YAML file (`models.yml`) contains information about various LLMs and their providers. To update this information to the latest available, you must have an access API key for the `open_router.ai` service.
 
-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.
+`AiClient::LLM` is a subclass of `ActiveHash::Base`, enabling it to act like and interact with `ActiveRecord::Base` defined models. Each entry in this data store is uniquely identified by an `id` in the pattern "provider/model" all lowercase without spaces.
 
-Take a look at the [examples/tools.rb](examples/tools.rb) file to see different ways in which these callable processes can be defined.
+##### Key Features
+
+- **Model and Provider Extraction**:
+  - The class provides methods to extract the model name and provider from the LLM's ID.
+  - The `model` method returns the model ID derived from the ID.
+  - The `provider` method extracts the provider name as a Symbol.
+
+##### Class Methods
+
+- **`reset_llm_data`**:
+  - A class-level method that fetches the latest model data from the open_router.ai service and updates the `models.yml` file accordingly.
+
+##### Instance Methods
+
+- **`model`**:
+  - Returns the name of the model derived from the LLM's ID.
+
+```ruby
+llm_instance = AiClient::LLM.find('openai/gpt-3.5-turbo')
+puts llm_instance.model # Output: gpt-3.5-turbo
+```
+
+- **`provider`**:
+  - Returns the name of the provider associated with the LLM's ID.
+
+```ruby
+llm_instance = AiClient::LLM.find('openai/gpt-3.5-turbo')
+puts llm_instance.provider # Output: :openai
+```
+
+##### Usage Example
+
+The `AiClient::LLM` class is predominantly used to interact with different providers of LLMs. By utilizing the `model` and `provider` methods, users can seamlessly retrieve and utilize models in their applications.
+
+```ruby
+llm_instance = AiClient::LLM.find('google/bard')
+puts "Model: #{llm_instance.model}, Provider: #{llm_instance.provider}"
+```
+
+##### Integration with ActiveHash
+
+The `AiClient::LLM` class inherits from `ActiveHash::Base`, which provides an easy way to define a set of data and allows for lookups and easy manipulation of the data structure. The use of ActiveHash makes it easier to manage the LLM data effectively without needing a full database.
 
 
 ## Best ?? Practices
@@ -302,6 +520,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/tools.rb

@@ -1,90 +1,123 @@
 #!/usr/bin/env ruby
 # examples/tools.rb
-# See: https://ksylvest.com/posts/2024-08-16/using-omniai-to-leverage-tools-with-llms
+#
+# 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 "omniai-openai's random temp example"
+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
 
-my_weather_function = Proc.new do |location:, unit: 'Celsius'| 
-  "#{rand(20..50)}° #{unit} in #{location}"
+  # 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
 
-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]
-  )
-)
+# 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])
+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"
 
-llm_db_function = Proc.new do |params|
-  records = AiClient::LLM.where(id: /#{params[:model_name]}/i)
-  records.inspect
+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
 
-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]
-  )
-)
+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("Get details on an LLM model named bison.  Which one is the cheapest per prompt token.", tools: [llm_db])
+response = AI.chat(simple_prompt, 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"
+title "Callback function has no parameters; but uses two functions"
 
-class FunctionClass
+class PerfectDateFunction < AiClient::Function
   def self.call
-    "April 25th its not to hot nor too cold."
+    "April 25th, it's not too 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'
-    )
+  def self.details
+    {
+      name:         'perfect_date',
+      description:  'what is the perfect date'
+    }
   end
 end
 
-perfect_date = FunctionClass.new.function('perfect_date')
+# Registering the perfect date function
+PerfectDateFunction.register
 
-response = AI.chat("what is the perfect date for paris weather?", tools: [weather, perfect_date])
+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/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,6 +9,13 @@ class AiClient
     DATA_PATH = Pathname.new( __dir__ + '/models.yml')
     self.data = YAML.parse(DATA_PATH.read).to_ruby 
 
+    scope :providers,  -> {all.map(&:provider).uniq.map(&:to_sym)}
+
+    scope :models, ->(substring=nil) do
+      (substring.nil? ? all : all.where(id: /#{substring}/i))
+        .map(&:model).sort.uniq
+    end
+
     # Extracts the model name from the LLM ID.
     #
     # @return [String] the model name.
@@ -17,9 +24,12 @@ class AiClient
 
     # Extracts the provider name from the LLM ID.
     #
-    # @return [String] the provider name.
+    # @return [Symbol] the provider name.
     #
-    def provider  = id.split('/')[0]
+    def provider  = id.split('/')[0].to_sym
+  
+    def to_h = attributes
+
   end
 
   class << self
@@ -34,5 +44,6 @@ class AiClient
       AiClient::LLM.data = orc_models
       AiClient::LLM::DATA_PATH.write(orc_models.to_yaml)
     end
+
   end
 end

data/lib/ai_client/middleware.rb

@@ -1,6 +1,6 @@
 # lib/ai_client/middleware.rb
 
-# TODO: As concurrently designed the middleware must
+# TODO: As currently 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

data/lib/ai_client/open_router_extensions.rb

@@ -1,58 +1,74 @@
 # lib/ai_client/open_router_extensions.rb
-# frozen_string_literal: true
 
-# These extensions to AiClient are only available with
-# a valid API Key for the open_router.ai web-service
+# OpenRouter Extensions for AiClient
+#
+# This file adds several public instance and class methods to the AiClient class
+# to provide information about AI models and providers.
+#
+# Instance Methods:
+# - model_details: Retrieves details for the current model.
+# - models: Retrieves model names for the current provider.
+#
+# Class Methods:
+# - providers: Retrieves all available providers.
+# - models: Retrieves model names, optionally filtered by provider.
+# - model_details: Retrieves details for a specific model.
+#
+# These methods utilize the AiClient::LLM class and the models.yml file
+# for model information.
 
 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.
+  # Retrieves details for the current model.
   #
-  # @return [Array<String>] List of provider names.
-  def providers
-    self.class.providers
+  # @return [Hash, nil] Details of the current model or nil if not found.
+  def model_details
+    id = "#{@provider}/#{@model}"
+    LLM.find(id.downcase)
   end
 
-  # Retrieves model names, optionally filtered by provider.
+  # Retrieves model names for the current 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
+  # @return [Array<String>] List of model names for the current provider.
+  def models = LLM.models(@provider)
 
-  # 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
+  class << self
 
+    # Retrieves all available providers.
+    #
+    # @return [Array<Symbol>] List of all provider names.
+    def providers = LLM.providers
 
-  class << self
-    
-    # Adds OpenRouter extensions to AiClient.
+
+    # Retrieves model names, optionally filtered by provider.
+    #
+    # @param substring [String, nil] Optional substring to filter models by.
+    # @return [Array<String>] List of model names.
+    def models(substring = nil) = LLM.models(substring)
+
+    # Retrieves details for a specific model.
+    #
+    # @param model_id [String] The model ID to retrieve details for,
+    #     in the pattern "provider/model".downcase
+    # @return [AiClient::LLM, nil] Details of the model or nil if not found.
+    def model_details(model_id) = LLM.find(model_id.downcase)
+
+
+    # Resets LLM data with the available ORC models.
+    #
+    # @return [void]
     #
+    def reset_llm_data = LLM.reset_llm_data
+
+
+    # Initializes OpenRouter extensions for AiClient.
+    #
+    # This sets up the access token and initializes the ORC client.
+    # 
     # @return [void]
     #
     def add_open_router_extensions
@@ -64,7 +80,10 @@ class AiClient
       initialize_orc_client
     end
 
-    # Retrieves ORC client instance.
+
+    private
+
+    # Retrieves the ORC client instance.
     #
     # @return [OpenRouter::Client] Instance of the OpenRouter client.
     #
@@ -80,59 +99,7 @@ class AiClient
       @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'] }
-
-      return model_ids unless provider
-
-      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
 
     # Fetches the access token from environment variables.
     #
@@ -154,10 +121,9 @@ class AiClient
       OpenRouter.configure { |config| config.access_token = access_token }
     end
 
-    # Initializes the ORC client.
-    #
-    # @return [void]
+    # Initializes the ORC client instance.
     #
+    # @return [OpenRouter::Client] Instance of the OpenRouter client.
     def initialize_orc_client
       @orc_client ||= OpenRouter::Client.new
     end

data/lib/ai_client/tool.rb

@@ -1,14 +1,11 @@
 # 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
   
+  # TODO: Is there any additional functionality that
+  #       needs to be added to the Rool class that would
+  #       be helpful?
+  
   def xyzzy = self.class.xyzzy
 
   class << self

data/lib/ai_client/version.rb

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

data/lib/ai_client.rb

@@ -1,6 +1,17 @@
 # ai_client.rb
-# WIP:  a generic client to access LLM providers
-#       kinda like the SaaS "open router"
+
+# A generic client to access various LLM providers
+# Inspired by the SaaS "open router" concept
+
+
+# AiClient: A unified interface for interacting with various LLM providers
+#
+# Usage:
+#   client = AiClient.new('gpt-3.5-turbo')
+#
+# Add middlewares:
+#   AiClient.use(RetryMiddleware.new(max_retries: 5, base_delay: 2, max_delay: 30))
+#   AiClient.use(LoggingMiddleware.new(AiClient.configuration.logger))
 #
 
 unless defined?(DebugMe)
@@ -29,6 +40,7 @@ require_relative 'ai_client/middleware'
 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')
@@ -133,29 +145,30 @@ 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
-  
+  def raw?
+    config.return_raw
+  end
+
 
   # 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
 
+
+  # Returns the last response received from the client.
+  #
+  # @return [OmniAI::Response] The last response.
+  #
+  def response  = last_response
+
+
   # Extracts the content from the last response based on the provider.
   #
   # @return [String] The extracted content.
@@ -287,5 +300,3 @@ class AiClient
       raise(ArgumentError, "Unsupported model: #{model}")
   end
 end
-
-

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ai_client
 version: !ruby/object:Gem::Version
-  version: 0.2.5
+  version: 0.3.1
 platform: ruby
 authors:
 - Dewayne VanHoozer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-10-11 00:00:00.000000000 Z
+date: 2024-10-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: active_hash
@@ -226,6 +226,7 @@ files:
 - 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
@@ -261,7 +262,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.21
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
 summary: A generic AI Client for many providers