durable-llm 0.1.5 → 0.1.6

data/lib/durable/llm/provider_utilities.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+# This module provides utility functions for working with LLM providers, including
+# provider discovery, comparison, and model routing capabilities. It helps developers
+# choose and switch between providers efficiently.
+
+module Durable
+  module Llm
+    # Utility methods for provider management and comparison
+    #
+    # This module offers helper methods for:
+    # - Discovering available providers
+    # - Finding providers that support specific models
+    # - Comparing provider capabilities
+    # - Routing requests to appropriate providers
+    #
+    # @example Find provider for a model
+    #   provider = ProviderUtilities.provider_for_model('gpt-4')
+    #   # => :openai
+    module ProviderUtilities
+      module_function
+
+      # Lists all available providers
+      #
+      # @return [Array<Symbol>] Array of provider names
+      # @example List providers
+      #   providers = ProviderUtilities.available_providers
+      #   # => [:openai, :anthropic, :google, ...]
+      def available_providers
+        Providers.available_providers
+      end
+
+      # Finds the provider that supports a given model
+      #
+      # @param model_id [String] The model identifier
+      # @return [Symbol, nil] The provider name or nil if not found
+      # @example Find provider for GPT-4
+      #   provider = ProviderUtilities.provider_for_model('gpt-4')
+      #   # => :openai
+      # @example Find provider for Claude
+      #   provider = ProviderUtilities.provider_for_model('claude-3-opus-20240229')
+      #   # => :anthropic
+      def provider_for_model(model_id)
+        Providers.model_id_to_provider(model_id)
+      end
+
+      # Gets all models available for a provider
+      #
+      # @param provider_name [Symbol, String] The provider name
+      # @param options [Hash] Provider configuration options
+      # @return [Array<String>] Array of model IDs
+      # @example Get OpenAI models
+      #   models = ProviderUtilities.models_for_provider(:openai)
+      def models_for_provider(provider_name, **options)
+        Durable::Llm.models(provider_name, **options)
+      rescue StandardError
+        []
+      end
+
+      # Checks if a provider supports a specific capability
+      #
+      # @param provider_name [Symbol, String] The provider name
+      # @param capability [Symbol] The capability to check (:streaming, :embeddings, :chat)
+      # @return [Boolean] True if capability is supported
+      # @example Check streaming support
+      #   supports = ProviderUtilities.supports_capability?(:openai, :streaming)
+      #   # => true
+      def supports_capability?(provider_name, capability)
+        provider_class = Providers.provider_class_for(provider_name)
+        instance = provider_class.new
+
+        case capability
+        when :streaming
+          instance.respond_to?(:stream?) && instance.stream?
+        when :embeddings
+          instance.respond_to?(:embedding)
+        when :chat, :completion
+          instance.respond_to?(:completion)
+        else
+          false
+        end
+      rescue StandardError
+        false
+      end
+
+      # Finds all providers that support a specific capability
+      #
+      # @param capability [Symbol] The capability to filter by
+      # @return [Array<Symbol>] Providers supporting the capability
+      # @example Find streaming providers
+      #   providers = ProviderUtilities.providers_with_capability(:streaming)
+      #   # => [:openai, :anthropic, :google, ...]
+      def providers_with_capability(capability)
+        available_providers.select do |provider|
+          supports_capability?(provider, capability)
+        end
+      end
+
+      # Compares models across providers based on common characteristics
+      #
+      # @param model_ids [Array<String>] Models to compare
+      # @return [Hash] Comparison data
+      # @example Compare models
+      #   comparison = ProviderUtilities.compare_models(['gpt-4', 'claude-3-opus-20240229'])
+      def compare_models(model_ids)
+        model_ids.map do |model_id|
+          provider = provider_for_model(model_id)
+          {
+            model: model_id,
+            provider: provider,
+            streaming: provider ? supports_capability?(provider, :streaming) : false
+          }
+        end
+      end
+
+      # Creates a fallback chain of providers for redundancy
+      #
+      # This method helps build resilient systems by providing fallback options
+      # when a primary provider is unavailable.
+      #
+      # @param providers [Array<Symbol>] Ordered list of providers to try
+      # @param options [Hash] Configuration options
+      # @return [Array<Durable::Llm::Client>] Array of clients in fallback order
+      # @example Create fallback chain
+      #   clients = ProviderUtilities.fallback_chain(
+      #     [:openai, :anthropic, :google],
+      #     model_map: {
+      #       openai: 'gpt-4',
+      #       anthropic: 'claude-3-opus-20240229',
+      #       google: 'gemini-pro'
+      #     }
+      #   )
+      def fallback_chain(providers, options = {})
+        model_map = options[:model_map] || {}
+
+        providers.map do |provider|
+          model = model_map[provider]
+          Durable::Llm.new(provider, model: model)
+        rescue StandardError => e
+          warn "Failed to create client for #{provider}: #{e.message}"
+          nil
+        end.compact
+      end
+
+      # Executes a completion with automatic provider fallback
+      #
+      # @param text [String] The input text
+      # @param providers [Array<Symbol>] Ordered providers to try
+      # @param model_map [Hash] Map of provider to model
+      # @return [String, nil] The completion text or nil if all fail
+      # @example Completion with fallback
+      #   result = ProviderUtilities.complete_with_fallback(
+      #     'Hello!',
+      #     providers: [:openai, :anthropic],
+      #     model_map: { openai: 'gpt-4', anthropic: 'claude-3-opus-20240229' }
+      #   )
+      def complete_with_fallback(text, providers:, model_map: {})
+        providers.each do |provider|
+          begin
+            client = Durable::Llm.new(provider, model: model_map[provider])
+            return client.complete(text)
+          rescue StandardError => e
+            warn "Provider #{provider} failed: #{e.message}"
+            next
+          end
+        end
+
+        nil # All providers failed
+      end
+
+      # Gets provider information including capabilities
+      #
+      # @param provider_name [Symbol, String] The provider name
+      # @return [Hash] Provider information
+      # @example Get provider info
+      #   info = ProviderUtilities.provider_info(:openai)
+      #   # => { name: :openai, streaming: true, embeddings: true, ... }
+      def provider_info(provider_name)
+        {
+          name: provider_name,
+          streaming: supports_capability?(provider_name, :streaming),
+          embeddings: supports_capability?(provider_name, :embeddings),
+          chat: supports_capability?(provider_name, :chat)
+        }
+      rescue StandardError => e
+        { name: provider_name, error: e.message }
+      end
+
+      # Lists all providers with their capabilities
+      #
+      # @return [Array<Hash>] Array of provider information hashes
+      # @example List all provider capabilities
+      #   all = ProviderUtilities.all_provider_info
+      def all_provider_info
+        available_providers.map { |p| provider_info(p) }
+      end
+    end
+  end
+end
+
+# Copyright (c) 2025 Durable Programming, LLC. All rights reserved.

data/lib/durable/llm/providers/base.rb

@@ -21,15 +21,40 @@ module Durable
       # implementations for optional features.
       #
       # Subclasses must implement the following methods:
-      # - default_api_key
-      # - completion
-      # - models
-      # - handle_response
+      # - {#default_api_key} - Returns the default API key from configuration
+      # - {#completion} - Performs a completion request
+      # - {#models} - Returns list of available models
+      # - {#handle_response} - Processes API responses
       #
-      # Subclasses may override:
-      # - stream?
-      # - stream
-      # - embedding
+      # Subclasses may optionally override:
+      # - {#stream?} - Check if streaming is supported
+      # - {#stream} - Perform streaming requests
+      # - {#embedding} - Generate embeddings
+      #
+      # @abstract Subclass and implement required methods
+      # @example Implementing a custom provider
+      #   class MyProvider < Durable::Llm::Providers::Base
+      #     def default_api_key
+      #       Durable::Llm.configuration.my_provider&.api_key ||
+      #         ENV['MY_PROVIDER_API_KEY']
+      #     end
+      #
+      #     def completion(options)
+      #       # Make API request
+      #       response = make_request(options)
+      #       handle_response(response)
+      #     end
+      #
+      #     def models
+      #       ['model-1', 'model-2']
+      #     end
+      #
+      #     private
+      #
+      #     def handle_response(response)
+      #       # Process and return response
+      #     end
+      #   end
       class Base
         # @return [String, nil] The default API key for this provider, or nil if not configured
         # @raise [NotImplementedError] Subclasses must implement this method
@@ -44,6 +69,10 @@ module Durable
         # Initializes a new provider instance
         #
         # @param api_key [String, nil] The API key to use for authentication. If nil, uses default_api_key
+        # @example Initialize with explicit API key
+        #   provider = Durable::Llm::Providers::OpenAI.new(api_key: 'sk-...')
+        # @example Initialize with default API key from configuration
+        #   provider = Durable::Llm::Providers::OpenAI.new
         def initialize(api_key: nil)
           @api_key = api_key || default_api_key
         end
@@ -59,25 +88,58 @@ module Durable
 
         # Retrieves the list of available models, with caching
         #
+        # Models are cached in `~/.local/durable-llm/cache/` for 1 hour to reduce
+        # API calls. The cache is automatically refreshed after expiration.
+        #
         # @return [Array<String>] The list of available model names
+        # @example Get available models for OpenAI
+        #   models = Durable::Llm::Providers::OpenAI.models
+        #   # => ["gpt-4", "gpt-3.5-turbo", ...]
         def self.models
-          cache_dir = File.expand_path("#{Dir.home}/.local/durable-llm/cache")
+          cache_file = model_cache_file
+          return cached_models(cache_file) if cache_valid?(cache_file)
 
+          fetch_and_cache_models(cache_file)
+        end
+
+        # Returns the path to the model cache file
+        #
+        # @return [String] The cache file path
+        def self.model_cache_file
+          cache_dir = File.expand_path("#{Dir.home}/.local/durable-llm/cache")
           FileUtils.mkdir_p(cache_dir) unless File.directory?(cache_dir)
-          cache_file = File.join(cache_dir, "#{name.split('::').last}.json")
+          File.join(cache_dir, "#{name.split('::').last}.json")
+        end
 
-          file_exists = File.exist?(cache_file)
-          file_new_enough = file_exists && File.mtime(cache_file) > Time.now - 3600
+        # Checks if the cache file is valid (exists and not expired)
+        #
+        # @param cache_file [String] The cache file path
+        # @return [Boolean] True if cache is valid, false otherwise
+        def self.cache_valid?(cache_file)
+          File.exist?(cache_file) && File.mtime(cache_file) > Time.now - 3600
+        end
 
-          if file_exists && file_new_enough
-            JSON.parse(File.read(cache_file))
-          else
-            models = new.models
-            File.write(cache_file, JSON.generate(models)) if models.length.positive?
-            models
-          end
+        # Reads models from cache file
+        #
+        # @param cache_file [String] The cache file path
+        # @return [Array<String>] The cached model names
+        def self.cached_models(cache_file)
+          JSON.parse(File.read(cache_file))
         end
 
+        # Fetches models from API and caches them
+        #
+        # @param cache_file [String] The cache file path
+        # @return [Array<String>] The fetched model names
+        def self.fetch_and_cache_models(cache_file)
+          models = new.models
+          File.write(cache_file, JSON.generate(models)) if models.length.positive?
+          models
+        end
+
+        private_class_method :model_cache_file, :cache_valid?, :cached_models, :fetch_and_cache_models
+
+
         # Returns the list of supported option names for completions
         #
         # @return [Array<String>] The supported option names
@@ -139,6 +201,71 @@ module Durable
         def handle_response(response)
           raise NotImplementedError, 'Subclasses must implement handle_response'
         end
+
+        # Validates that required parameters are present in the options hash
+        #
+        # @param options [Hash] The options hash to validate
+        # @param required_params [Array<Symbol, String>] List of required parameter names
+        # @raise [ArgumentError] If any required parameters are missing or empty
+        # @return [void]
+        # @example Validate completion parameters
+        #   validate_required_params(options, [:model, :messages])
+        def validate_required_params(options, required_params)
+          missing = required_params.select do |param|
+            value = options[param] || options[param.to_s]
+            value.nil? || (value.respond_to?(:empty?) && value.empty?)
+          end
+
+          return if missing.empty?
+
+          raise ArgumentError, "Missing required parameters: #{missing.join(', ')}. " \
+                               "Please provide these parameters in your request."
+        end
+
+        # Validates that a parameter is within a specified range
+        #
+        # @param value [Numeric] The value to validate
+        # @param param_name [String, Symbol] The parameter name for error messages
+        # @param min [Numeric] The minimum allowed value (inclusive)
+        # @param max [Numeric] The maximum allowed value (inclusive)
+        # @raise [ArgumentError] If the value is outside the allowed range
+        # @return [void]
+        # @example Validate temperature parameter
+        #   validate_range(options[:temperature], :temperature, 0.0, 2.0)
+        def validate_range(value, param_name, min, max)
+          return if value.nil? # Allow nil values (will use provider defaults)
+          return if value >= min && value <= max
+
+          raise ArgumentError, "#{param_name} must be between #{min} and #{max}, got #{value}"
+        end
+
+        # Validates that the API key is configured
+        #
+        # @raise [Durable::Llm::AuthenticationError] If API key is not configured
+        # @return [void]
+        # @example Validate API key before making request
+        #   validate_api_key
+        def validate_api_key
+          return unless @api_key.nil? || @api_key.to_s.strip.empty?
+
+          provider_name = self.class.name.split('::').last
+          raise Durable::Llm::AuthenticationError,
+                "API key not configured for #{provider_name}. " \
+                "Set it via Durable::Llm.configure or environment variable."
+        end
+
+        # Sanitizes and normalizes request options
+        #
+        # @param options [Hash] The raw options hash
+        # @return [Hash] The sanitized options with string keys converted to symbols
+        # @example Sanitize options
+        #   sanitized = sanitize_options({ 'model' => 'gpt-4', 'temperature' => 0.7 })
+        #   # => { model: 'gpt-4', temperature: 0.7 }
+        def sanitize_options(options)
+          return {} if options.nil?
+
+          options.transform_keys(&:to_sym)
+        end
       end
     end
   end

data/lib/durable/llm/providers/cohere.rb

@@ -144,6 +144,10 @@ module Durable
           "#{response.status} Error: #{message}"
         end
 
+        # Response object for Cohere chat API responses.
+        #
+        # Wraps the raw response and provides a consistent interface for accessing
+        # message content and metadata.
         class CohereResponse
           attr_reader :raw_response
 
@@ -160,6 +164,9 @@ module Durable
           end
         end
 
+        # Represents a single choice in a Cohere response.
+        #
+        # Contains the generated text content.
         class CohereChoice
           attr_reader :text
 
@@ -172,6 +179,9 @@ module Durable
           end
         end
 
+        # Response object for Cohere embedding API responses.
+        #
+        # Wraps embedding data and provides array access to the vector representation.
         class CohereEmbeddingResponse
           attr_reader :embedding
 
@@ -184,6 +194,9 @@ module Durable
           end
         end
 
+        # Response object for streaming Cohere chat chunks.
+        #
+        # Wraps individual chunks from the Server-Sent Events stream.
         class CohereStreamResponse
           attr_reader :choices
 
@@ -196,6 +209,9 @@ module Durable
           end
         end
 
+        # Represents a single choice in a streaming Cohere response chunk.
+        #
+        # Contains the delta (incremental content) for the choice.
         class CohereStreamChoice
           attr_reader :delta
 
@@ -208,6 +224,9 @@ module Durable
           end
         end
 
+        # Represents the incremental content delta in a streaming response.
+        #
+        # Contains the text content of the delta.
         class CohereStreamDelta
           attr_reader :text
 

data/lib/durable/llm/providers/fireworks.rb

@@ -11,6 +11,10 @@ require 'durable/llm/providers/base'
 module Durable
   module Llm
     module Providers
+      # Fireworks AI provider for accessing Fireworks AI's language models.
+      #
+      # Provides completion, embedding, and streaming capabilities with proper
+      # error handling and response normalization.
       class Fireworks < Durable::Llm::Providers::Base
         BASE_URL = 'https://api.fireworks.ai/inference/v1'
 
@@ -174,6 +178,10 @@ module Durable
           "#{response.status} Error: #{message}"
         end
 
+        # Response object for Fireworks chat API responses.
+        #
+        # Wraps the raw response and provides a consistent interface for accessing
+        # message content and metadata.
         class FireworksResponse
           attr_reader :raw_response
 
@@ -194,6 +202,9 @@ module Durable
           end
         end
 
+        # Represents a single choice in a Fireworks response.
+        #
+        # Contains the message and finish reason for the choice.
         class FireworksChoice
           attr_reader :message, :finish_reason
 
@@ -207,6 +218,9 @@ module Durable
           end
         end
 
+        # Represents a message in a Fireworks conversation.
+        #
+        # Messages have a role (user, assistant) and text content.
         class FireworksMessage
           attr_reader :role, :content
 
@@ -220,6 +234,9 @@ module Durable
           end
         end
 
+        # Response object for streaming Fireworks chat chunks.
+        #
+        # Wraps individual chunks from the Server-Sent Events stream.
         class FireworksStreamResponse
           attr_reader :choices
 
@@ -232,6 +249,9 @@ module Durable
           end
         end
 
+        # Response object for Fireworks embedding API responses.
+        #
+        # Wraps embedding data and provides array access to the vector representation.
         class FireworksEmbeddingResponse
           attr_reader :embedding
 
@@ -244,6 +264,9 @@ module Durable
           end
         end
 
+        # Represents a single choice in a streaming Fireworks response chunk.
+        #
+        # Contains the delta (incremental content) and finish reason for the choice.
         class FireworksStreamChoice
           attr_reader :delta, :finish_reason
 
@@ -258,6 +281,9 @@ module Durable
           end
         end
 
+        # Represents the incremental content delta in a streaming response.
+        #
+        # Contains the role and text content of the delta.
         class FireworksStreamDelta
           attr_reader :role, :content
 

data/lib/durable/llm/providers/google.rb

@@ -11,6 +11,10 @@ require 'event_stream_parser'
 module Durable
   module Llm
     module Providers
+      # Google Generative AI provider for accessing Gemini language models.
+      #
+      # Provides completion, embedding, and streaming capabilities with proper
+      # error handling and response normalization for Google's Generative Language API.
       class Google < Durable::Llm::Providers::Base
         BASE_URL = 'https://generativelanguage.googleapis.com'
 
@@ -206,6 +210,10 @@ module Durable
           "#{response.status} Error: #{message}"
         end
 
+        # Response object for Google Generative AI API responses.
+        #
+        # Wraps the raw response and provides a consistent interface for accessing
+        # candidate content and metadata.
         class GoogleResponse
           attr_reader :raw_response
 
@@ -222,6 +230,9 @@ module Durable
           end
         end
 
+        # Represents a single candidate choice in a Google response.
+        #
+        # Contains the message content from the candidate.
         class GoogleChoice
           attr_reader :message
 
@@ -234,6 +245,9 @@ module Durable
           end
         end
 
+        # Represents a message in a Google conversation.
+        #
+        # Messages contain text content extracted from parts.
         class GoogleMessage
           attr_reader :content
 
@@ -246,6 +260,9 @@ module Durable
           end
         end
 
+        # Response object for streaming Google Generative AI chunks.
+        #
+        # Wraps individual chunks from the streaming response.
         class GoogleStreamResponse
           attr_reader :choices
 
@@ -258,6 +275,9 @@ module Durable
           end
         end
 
+        # Represents a single choice in a streaming Google response chunk.
+        #
+        # Contains the delta (incremental content) for the choice.
         class GoogleStreamChoice
           attr_reader :delta
 
@@ -270,6 +290,9 @@ module Durable
           end
         end
 
+        # Represents the incremental content delta in a streaming response.
+        #
+        # Contains the text content of the delta.
         class GoogleStreamDelta
           attr_reader :content
 
@@ -282,6 +305,9 @@ module Durable
           end
         end
 
+        # Response object for Google embedding API responses.
+        #
+        # Wraps embedding data and provides array access to the vector representation.
         class GoogleEmbeddingResponse
           attr_reader :embedding
 

data/lib/durable/llm/providers/groq.rb

@@ -11,6 +11,10 @@ require 'event_stream_parser'
 module Durable
   module Llm
     module Providers
+      # Groq provider for accessing language models via OpenAI-compatible API.
+      #
+      # Provides completion, embedding, and streaming capabilities with proper
+      # error handling and response normalization.
       class Groq < Durable::Llm::Providers::Base
         BASE_URL = 'https://api.groq.com/openai/v1'
 
@@ -144,6 +148,10 @@ module Durable
           end
         end
 
+        # Response object for Groq chat API responses.
+        #
+        # Wraps the raw response and provides a consistent interface for accessing
+        # message content, embeddings, and metadata.
         class GroqResponse
           attr_reader :raw_response
 
@@ -172,6 +180,9 @@ module Durable
           end
         end
 
+        # Represents a single choice in a Groq response.
+        #
+        # Contains the message and finish reason for the choice.
         class GroqChoice
           attr_reader :message, :finish_reason
 
@@ -185,6 +196,9 @@ module Durable
           end
         end
 
+        # Represents a message in a Groq conversation.
+        #
+        # Messages have a role (user, assistant, system) and text content.
         class GroqMessage
           attr_reader :role, :content
 
@@ -198,6 +212,9 @@ module Durable
           end
         end
 
+        # Response object for streaming Groq chat chunks.
+        #
+        # Wraps individual chunks from the Server-Sent Events stream.
         class GroqStreamResponse
           attr_reader :choices
 
@@ -210,6 +227,9 @@ module Durable
           end
         end
 
+        # Represents a single choice in a streaming Groq response chunk.
+        #
+        # Contains the delta (incremental content) and finish reason for the choice.
         class GroqStreamChoice
           attr_reader :delta, :finish_reason
 
@@ -224,6 +244,9 @@ module Durable
           end
         end
 
+        # Represents the incremental content delta in a streaming response.
+        #
+        # Contains the role and text content of the delta.
         class GroqStreamDelta
           attr_reader :role, :content
 
@@ -237,6 +260,9 @@ module Durable
           end
         end
 
+        # Response object for Groq embedding API responses.
+        #
+        # Wraps embedding data and provides array access to the vector representation.
         class GroqEmbeddingResponse
           attr_reader :embedding