durable-llm 0.1.4 → 0.1.6

data/lib/durable/llm/providers.rb

@@ -1,34 +1,131 @@
+# frozen_string_literal: true
+
+# This file serves as the main registry and loader for LLM providers in the Durable gem,
+# providing a centralized interface to manage and discover available provider classes. It handles
+# automatic loading of provider modules, maintains a dynamic list of registered providers, offers
+# utility methods for model discovery and provider resolution based on model IDs, and includes
+# provider aliases for backwards compatibility and convenience access.
+
 require 'durable/llm/providers/openai'
 require 'durable/llm/providers/anthropic'
+require 'durable/llm/providers/cohere'
+require 'durable/llm/providers/groq'
+require 'durable/llm/providers/huggingface'
+require 'durable/llm/providers/azure_openai'
+require 'durable/llm/providers/deepseek'
+require 'durable/llm/providers/fireworks'
+require 'durable/llm/providers/google'
+require 'durable/llm/providers/mistral'
+require 'durable/llm/providers/opencode'
+require 'durable/llm/providers/openrouter'
+require 'durable/llm/providers/perplexity'
+require 'durable/llm/providers/together'
+require 'durable/llm/providers/xai'
 
 module Durable
   module Llm
+    # Main module for LLM providers, providing registry and utility methods
     module Providers
+      # Loads all provider files in the providers directory.
+      #
+      # This method dynamically requires all Ruby files in the providers subdirectory,
+      # ensuring that all provider classes are loaded and available for use.
+      #
+      # @return [void]
       def self.load_all
-        Dir[File.join(__dir__, 'providers', '*.rb')].each { |file| require file }
+        Dir[File.join(__dir__, 'providers', '*.rb')].sort.each { |file| require file }
+      end
+
+      # Returns the provider class for a given provider symbol.
+      #
+      # This method handles the mapping from provider symbols to their corresponding
+      # class constants, including special cases where the symbol doesn't directly
+      # map to a capitalized class name.
+      #
+      # @param provider_sym [Symbol] The provider symbol (e.g., :openai, :anthropic)
+      # @return [Class] The provider class
+      # @raise [NameError] If the provider class cannot be found
+      def self.provider_class_for(provider_sym)
+        # Handle special cases where capitalize doesn't match
+        case provider_sym
+        when :deepseek
+          DeepSeek
+        when :openrouter
+          OpenRouter
+        when :azureopenai
+          AzureOpenai
+        when :opencode
+          Opencode
+        else
+          const_get(provider_sym.to_s.capitalize)
+        end
       end
 
+      # Returns a list of all available provider symbols.
+      #
+      # This method dynamically discovers all provider classes by inspecting the
+      # module's constants and filtering for classes that inherit from Base,
+      # excluding the Base class itself.
+      #
+      # @return [Array<Symbol>] Array of provider symbols
       def self.providers
-        @provider_list ||= constants.select do |const_name|
-          const = const_get(const_name)
-          last_component = const.name.split('::').last
-          next if last_component == 'Base'
+        @providers ||= begin
+          provider_classes = constants.select do |const_name|
+            const = const_get(const_name)
+            next if const.name.split('::').last == 'Base'
 
-          const.is_a?(Class) && const.to_s.split('::').last.to_s == const_name.to_s
-        end.map(&:to_s).map(&:downcase).map(&:to_sym)
+            const.is_a?(Class) && const < Durable::Llm::Providers::Base
+          end
+
+          provider_classes.map do |const_name|
+            const_get(const_name).name.split('::').last.downcase.to_sym
+          end.uniq
+        end
       end
 
+      # Returns a list of all available provider names as strings.
+      #
+      # Alias for providers that returns strings instead of symbols, useful for
+      # display purposes in error messages and documentation.
+      #
+      # @return [Array<String>] Array of provider names
+      def self.available_providers
+        providers.map(&:to_s).sort
+      end
+
+      # Returns a flat list of all model IDs across all providers.
+      #
+      # This method aggregates model IDs from all available providers by calling
+      # their models method. If a provider fails to return models (e.g., due to
+      # missing API keys), it gracefully handles the error and continues.
+      #
+      # @return [Array<String>] Array of model IDs
       def self.model_ids
-        providers.flat_map do |provider|
-          provider_class = const_get(provider.to_s.capitalize)
-          provider_class.models
+        providers.flat_map do |provider_sym|
+          provider_class = provider_class_for(provider_sym)
+          begin
+            provider_class.models
+          rescue StandardError
+            []
+          end
         end
       end
 
+      # Finds the provider class that supports a given model ID.
+      #
+      # This method searches through all providers to find which one supports
+      # the specified model ID. Returns nil if no provider supports the model.
+      #
+      # @param model_id [String] The model ID to search for
+      # @return [Class, nil] The provider class that supports the model, or nil
       def self.model_id_to_provider(model_id)
-        providers.each do |provider|
-          provider_class = const_get(provider.to_s.capitalize)
-          return provider_class if provider_class.models.include?(model_id)
+        providers.each do |provider_sym|
+          provider_class = provider_class_for(provider_sym)
+          begin
+            return provider_class if provider_class.models.include?(model_id)
+          rescue StandardError
+            next
+          end
         end
         nil
       end
@@ -36,6 +133,9 @@ module Durable
       Openai = OpenAI
       Claude = Anthropic
       Claude3 = Anthropic
+      AzureOpenAI = AzureOpenai
     end
   end
 end
+
+# Copyright (c) 2025 Durable Programming, LLC. All rights reserved.

data/lib/durable/llm/response_helpers.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+# This module provides helper methods for extracting and formatting responses from
+# LLM API calls. It offers convenient methods to work with response objects from
+# different providers, abstracting away the complexity of response structure variations.
+
+module Durable
+  module Llm
+    # Helper methods for working with LLM responses
+    #
+    # This module provides convenience methods for extracting content, messages,
+    # and metadata from LLM response objects. It handles the common patterns of
+    # response processing across different providers.
+    #
+    # @example Using response helpers
+    #   response = client.chat(messages: [...])
+    #   content = ResponseHelpers.extract_content(response)
+    #   tokens = ResponseHelpers.token_usage(response)
+    module ResponseHelpers
+      module_function
+
+      # Extracts the text content from a completion response
+      #
+      # @param response [Object] The API response object
+      # @return [String, nil] The extracted content or nil if not found
+      # @example Extract content from response
+      #   response = client.completion(messages: [...])
+      #   text = ResponseHelpers.extract_content(response)
+      #   puts text
+      def extract_content(response)
+        return nil unless response
+        return nil unless response.respond_to?(:choices)
+        return nil if response.choices.empty?
+
+        choice = response.choices.first
+        return nil unless choice.respond_to?(:message)
+
+        message = choice.message
+        return nil unless message.respond_to?(:content)
+
+        message.content
+      end
+
+      # Extracts all choice contents from a response
+      #
+      # @param response [Object] The API response object
+      # @return [Array<String>] Array of content strings from all choices
+      # @example Get all alternatives
+      #   response = client.completion(messages: [...], n: 3)
+      #   alternatives = ResponseHelpers.all_contents(response)
+      def all_contents(response)
+        return [] unless response&.respond_to?(:choices)
+
+        response.choices.map do |choice|
+          next unless choice.respond_to?(:message)
+
+          message = choice.message
+          message.content if message.respond_to?(:content)
+        end.compact
+      end
+
+      # Extracts token usage information from a response
+      #
+      # @param response [Object] The API response object
+      # @return [Hash, nil] Hash with :prompt_tokens, :completion_tokens, :total_tokens
+      # @example Get token usage
+      #   response = client.completion(messages: [...])
+      #   usage = ResponseHelpers.token_usage(response)
+      #   puts "Used #{usage[:total_tokens]} tokens"
+      def token_usage(response)
+        return nil unless response&.respond_to?(:usage)
+
+        usage = response.usage
+        return nil unless usage
+
+        {
+          prompt_tokens: usage.prompt_tokens,
+          completion_tokens: usage.completion_tokens,
+          total_tokens: usage.total_tokens
+        }
+      end
+
+      # Extracts the finish reason from a response
+      #
+      # @param response [Object] The API response object
+      # @return [String, nil] The finish reason (e.g., 'stop', 'length', 'content_filter')
+      # @example Check why completion finished
+      #   response = client.completion(messages: [...])
+      #   reason = ResponseHelpers.finish_reason(response)
+      #   puts "Finished because: #{reason}"
+      def finish_reason(response)
+        return nil unless response&.respond_to?(:choices)
+        return nil if response.choices.empty?
+
+        choice = response.choices.first
+        choice.finish_reason if choice.respond_to?(:finish_reason)
+      end
+
+      # Checks if a response was truncated due to length
+      #
+      # @param response [Object] The API response object
+      # @return [Boolean] True if response was truncated
+      # @example Check if truncated
+      #   response = client.completion(messages: [...])
+      #   if ResponseHelpers.truncated?(response)
+      #     puts "Response was cut off. Consider increasing max_tokens."
+      #   end
+      def truncated?(response)
+        finish_reason(response) == 'length'
+      end
+
+      # Formats a response as a simple hash with common fields
+      #
+      # @param response [Object] The API response object
+      # @return [Hash] Simplified response hash
+      # @example Format response
+      #   response = client.completion(messages: [...])
+      #   simple = ResponseHelpers.to_hash(response)
+      #   # => { content: "...", tokens: {...}, finish_reason: "stop" }
+      def to_hash(response)
+        {
+          content: extract_content(response),
+          tokens: token_usage(response),
+          finish_reason: finish_reason(response),
+          all_contents: all_contents(response)
+        }
+      end
+
+      # Extracts model information from response
+      #
+      # @param response [Object] The API response object
+      # @return [String, nil] The model used for the completion
+      # @example Get model name
+      #   response = client.completion(messages: [...])
+      #   model = ResponseHelpers.model_used(response)
+      #   puts "Model: #{model}"
+      def model_used(response)
+        return nil unless response&.respond_to?(:model)
+
+        response.model
+      end
+
+      # Calculates the cost of a response (approximate)
+      #
+      # This is a rough estimate based on common pricing. For accurate costs,
+      # consult your provider's pricing page.
+      #
+      # @param response [Object] The API response object
+      # @param model [String, nil] Optional model name for pricing lookup
+      # @return [Float, nil] Estimated cost in USD
+      # @example Estimate cost
+      #   response = client.completion(messages: [...])
+      #   cost = ResponseHelpers.estimate_cost(response)
+      #   puts "Estimated cost: $#{cost}"
+      def estimate_cost(response, model = nil)
+        usage = token_usage(response)
+        return nil unless usage
+
+        model ||= model_used(response)
+        return nil unless model
+
+        # Rough pricing estimates (as of 2025)
+        pricing = case model
+                  when /gpt-4-turbo/
+                    { prompt: 0.01 / 1000, completion: 0.03 / 1000 }
+                  when /gpt-4/
+                    { prompt: 0.03 / 1000, completion: 0.06 / 1000 }
+                  when /gpt-3.5-turbo/
+                    { prompt: 0.0015 / 1000, completion: 0.002 / 1000 }
+                  when /claude-3-opus/
+                    { prompt: 0.015 / 1000, completion: 0.075 / 1000 }
+                  when /claude-3-sonnet/
+                    { prompt: 0.003 / 1000, completion: 0.015 / 1000 }
+                  else
+                    return nil # Unknown model
+                  end
+
+        (usage[:prompt_tokens] * pricing[:prompt]) +
+          (usage[:completion_tokens] * pricing[:completion])
+      end
+    end
+  end
+end
+
+# Copyright (c) 2025 Durable Programming, LLC. All rights reserved.

data/lib/durable/llm/version.rb

@@ -1,7 +1,11 @@
 # frozen_string_literal: true
 
+# Defines the version constant 
+
 module Durable
   module Llm
-    VERSION = '0.1.4'
+    VERSION = '0.1.6'
   end
 end
+
+# Copyright (c) 2025 Durable Programming, LLC. All rights reserved.

data/lib/durable/llm.rb

@@ -1,27 +1,240 @@
+# frozen_string_literal: true
+
+# Main entry point for the Durable::Llm module.
+#
+# This module provides a unified interface for interacting with multiple Large Language Model (LLM)
+# providers through a consistent API. It handles configuration management, provider instantiation,
+# and offers convenience methods for common LLM operations.
+#
+# The module uses Zeitwerk for efficient autoloading of its components and maintains a global
+# configuration that can be customized through environment variables or programmatic setup.
+#
+# ## Basic Usage
+#
+# ```ruby
+# require 'durable/llm'
+#
+# # Configure API keys
+# Durable::Llm.configure do |config|
+#   config.openai.api_key = 'your-openai-key'
+# end
+#
+# # Create a client and make a request
+# client = Durable::Llm.new(:openai, model: 'gpt-4')
+# response = client.complete('Hello, world!')
+# puts response # => "Hello! How can I help you today?"
+# ```
+#
+# ## Configuration
+#
+# Configuration can be done via environment variables using the `DLLM__` prefix:
+#
+# ```bash
+# export DLLM__OPENAI__API_KEY=your-key-here
+# export DLLM__ANTHROPIC__API_KEY=your-anthropic-key
+# ```
+#
+# Or programmatically:
+#
+# ```ruby
+# Durable::Llm.configure do |config|
+#   config.openai.api_key = 'your-key'
+#   config.anthropic.api_key = 'your-anthropic-key'
+#   config.default_provider = 'anthropic'
+# end
+# ```
+#
+# ## Supported Providers
+#
+# - OpenAI (GPT models)
+# - Anthropic (Claude models)
+# - Google (Gemini models)
+# - Cohere
+# - Mistral AI
+# - Groq
+# - Fireworks AI
+# - Together AI
+# - DeepSeek
+# - OpenRouter
+# - Perplexity
+# - xAI
+# - Azure OpenAI
+#
+# @see Durable::Llm::Client For the main client interface
+# @see Durable::Llm::Configuration For configuration options
+# @see Durable::Llm::Providers For available providers
+
 require 'zeitwerk'
 loader = Zeitwerk::Loader.new
 loader.tag = File.basename(__FILE__, '.rb')
 loader.inflector = Zeitwerk::GemInflector.new(__FILE__)
-loader.push_dir(File.dirname(__FILE__) + '/..')
+loader.push_dir("#{File.dirname(__FILE__)}/..")
 
 require 'durable/llm/configuration'
+require 'durable/llm/version'
 
 module Durable
+  # The Llm module provides a unified interface for Large Language Model operations.
+  #
+  # This module serves as the main entry point for the Durable LLM gem, offering:
+  # - Global configuration management
+  # - Provider-agnostic client creation
+  # - Convenience methods for common operations
+  # - Access to version information
+  #
+  # The module maintains a singleton configuration instance that can be customized
+  # to set API keys, default providers, and other global settings.
+  #
+  # @example Basic setup and usage
+  #   Durable::Llm.configure do |config|
+  #     config.openai.api_key = 'sk-...'
+  #   end
+  #
+  #   client = Durable::Llm.new(:openai)
+  #   response = client.complete('Hello!')
+  #
+  # @see Durable::Llm::Client
+  # @see Durable::Llm::Configuration
   module Llm
     class << self
+      # @return [Configuration] The global configuration instance
       attr_accessor :configuration
 
+      # Returns the current configuration instance.
+      #
+      # This is an alias for the configuration accessor, provided for convenience.
+      #
+      # @return [Configuration] The global configuration instance
+      # @see #configuration
       def config
         configuration
       end
+
+      # Creates a new LLM client for the specified provider.
+      #
+      # This is a convenience method that creates a new Client instance with the
+      # given provider and options. It's equivalent to calling
+      # `Durable::Llm::Client.new(provider, options)`.
+      #
+      # @param provider [Symbol, String] The provider name (e.g., :openai, :anthropic)
+      # @param options [Hash] Configuration options for the client
+      # @option options [String] :model The default model to use
+      # @option options [String] :api_key API key for authentication
+      # @return [Client] A new client instance
+      # @raise [NameError] If the provider is not found
+      # @example Create an OpenAI client
+      #   client = Durable::Llm.new(:openai, api_key: 'sk-...', model: 'gpt-4')
+      # @example Create an Anthropic client
+      #   client = Durable::Llm.new(:anthropic, api_key: 'sk-ant-...')
+      def new(provider, options = {})
+        Client.new(provider, options)
+      end
     end
 
+    # Configures the global LLM settings.
+    #
+    # This method initializes or yields the global configuration instance,
+    # allowing you to set API keys, default providers, and other global options.
+    #
+    # @yield [configuration] The configuration instance to modify
+    # @yieldparam configuration [Configuration] The global configuration object
+    # @return [void]
+    # @example Configure API keys
+    #   Durable::Llm.configure do |config|
+    #     config.openai.api_key = 'sk-...'
+    #     config.anthropic.api_key = 'sk-ant-...'
+    #     config.default_provider = 'openai'
+    #   end
+    # @example Configure from environment
+    #   # Environment variables are automatically loaded
+    #   ENV['DLLM__OPENAI__API_KEY'] = 'sk-...'
+    #   Durable::Llm.configure do |config|
+    #     # Additional programmatic configuration
+    #   end
     def self.configure
       self.configuration ||= Configuration.new
       yield(configuration)
     end
+
+    # Creates a quick completion with minimal setup.
+    #
+    # This is a convenience method for one-off completions that automatically
+    # creates a client, performs the completion, and returns the text result.
+    #
+    # @param text [String] The input text to complete
+    # @param provider [Symbol] The provider to use (default: :openai)
+    # @param model [String] The model to use (required)
+    # @param options [Hash] Additional options for the client
+    # @return [String] The completion text
+    # @raise [ArgumentError] If required parameters are missing
+    # @example Quick completion with OpenAI
+    #   result = Durable::Llm.complete('What is Ruby?', model: 'gpt-4')
+    #   puts result
+    # @example Quick completion with Anthropic
+    #   result = Durable::Llm.complete('Explain AI', provider: :anthropic, model: 'claude-3-opus-20240229')
+    #   puts result
+    def self.complete(text, provider: :openai, model: nil, **options)
+      raise ArgumentError, 'text is required' if text.nil? || text.to_s.strip.empty?
+      raise ArgumentError, 'model is required' if model.nil? || model.to_s.strip.empty?
+
+      client = new(provider, options.merge(model: model))
+      client.complete(text)
+    end
+
+    # Creates a chat completion with minimal setup.
+    #
+    # This is a convenience method for quick chat interactions that automatically
+    # creates a client and performs the chat completion.
+    #
+    # @param messages [Array<Hash>] Array of message hashes with :role and :content
+    # @param provider [Symbol] The provider to use (default: :openai)
+    # @param model [String] The model to use (required)
+    # @param options [Hash] Additional options for the client and request
+    # @return [Object] The chat response object
+    # @raise [ArgumentError] If required parameters are missing
+    # @example Simple chat
+    #   response = Durable::Llm.chat(
+    #     [{ role: 'user', content: 'Hello!' }],
+    #     model: 'gpt-4'
+    #   )
+    #   puts response.choices.first.message.content
+    def self.chat(messages, provider: :openai, model: nil, **options)
+      raise ArgumentError, 'messages are required' if messages.nil? || messages.empty?
+      raise ArgumentError, 'model is required' if model.nil? || model.to_s.strip.empty?
+
+      request_keys = %i[temperature max_tokens top_p frequency_penalty presence_penalty]
+      request_params = options.select { |k, _| request_keys.include?(k) }
+      client_options = options.reject { |k, _| request_keys.include?(k) }
+
+      client = new(provider, client_options.merge(model: model))
+      client.chat(messages: messages, **request_params)
+    end
+
+    # Lists available models for a provider.
+    #
+    # @param provider [Symbol] The provider name (default: :openai)
+    # @param options [Hash] Provider options (e.g., api_key)
+    # @return [Array<String>] List of available model IDs
+    # @example List OpenAI models
+    #   models = Durable::Llm.models(:openai)
+    #   puts models.inspect
+    def self.models(provider = :openai, **options)
+      client = new(provider, options)
+      client.provider.models
+    end
   end
 end
 
 Durable::Llm.configure do
 end
+
+require 'durable/llm/providers'
+require 'durable/llm/client'
+require 'durable/llm/response_helpers'
+require 'durable/llm/provider_utilities'
+
+# Load global convenience functions for easier access
+# Users can skip this by requiring 'durable/llm/core' instead of 'durable/llm'
+require 'durable/llm/convenience' unless ENV['DLLM_NO_CONVENIENCE']
+
+# Copyright (c) 2025 Durable Programming, LLC. All rights reserved.

data/lib/durable.rb

@@ -1,7 +1,32 @@
-require 'durable/llm'
+# frozen_string_literal: true
 
+# Main entry point for the Durable gem.
+#
+# This module provides a namespace for Durable Programming LLC's Ruby gems.
+# It uses autoloading for efficient memory usage and lazy loading of components.
+#
+# Currently, it provides access to the LLM functionality through the Llm submodule.
+#
+# @example Basic usage
+#   require 'durable'
+#
+#   # Access LLM functionality
+#   Durable::Llm.configure do |config|
+#     config.openai.api_key = 'your-key'
+#   end
+#
+#   client = Durable::Llm.new(:openai)
+#   response = client.complete('Hello!')
+#
+# @see Durable::Llm
+
+# Namespace module for Durable Programming LLC's Ruby gems.
+#
+# This module serves as the root namespace for all Durable gems, providing
+# autoloaded access to various components and functionality.
 module Durable
-  # This module serves as a namespace for the Durable gem.
-  # It currently only requires the Llm module, but can be expanded
-  # in the future to include other Durable-related functionality.
+  # Autoload the Llm module for lazy loading
+  autoload :Llm, 'durable/llm'
 end
+
+# Copyright (c) 2025 Durable Programming, LLC. All rights reserved.