durable-llm 0.1.4 → 0.1.5

data/lib/durable/llm/client.rb

@@ -1,46 +1,123 @@
+# frozen_string_literal: true
+
+# This file implements the main Client class that provides a unified interface for interacting
+# with different LLM providers. It acts as a facade that delegates operations like completion,
+# chat, embedding, and streaming to the appropriate provider instance while handling parameter
+# processing, model configuration, and providing convenience methods for quick text completion.
+# The client automatically resolves provider classes based on the provider name and manages
+# default parameters including model selection.
+
 require 'zeitwerk'
 require 'durable/llm/providers'
 
 module Durable
   module Llm
+    # Unified interface for interacting with different LLM providers
+    #
+    # The Client class provides a facade that delegates operations like completion, chat,
+    # embedding, and streaming to the appropriate provider instance while handling parameter
+    # processing, model configuration, and providing convenience methods for quick text completion.
+    # The client automatically resolves provider classes based on the provider name and manages
+    # default parameters including model selection.
     class Client
+      # @return [Object] The underlying provider instance
       attr_reader :provider
+
+      # @return [String, nil] The default model to use for requests
       attr_accessor :model
 
+      # Initializes a new LLM client for the specified provider
+      #
+      # @param provider_name [Symbol, String] The name of the LLM provider (e.g., :openai, :anthropic)
+      # @param options [Hash] Configuration options for the provider and client
+      # @option options [String] :model The default model to use for requests
+      # @option options [String] 'model' Alternative string key for model
+      # @option options [String] :api_key API key for authentication (provider-specific)
+      # @raise [NameError] If the provider class cannot be found
       def initialize(provider_name, options = {})
-        @model = options.delete('model') || options.delete(:model) if options['model'] || options[:model]
+        @model = options.delete('model') || options.delete(:model) if options.key?('model') || options.key?(:model)
 
-        provider_class = Durable::Llm::Providers.const_get(provider_name.to_s.capitalize)
+        provider_class = Durable::Llm::Providers.provider_class_for(provider_name)
 
         @provider = provider_class.new(**options)
       end
 
+      # Returns the default parameters to merge with request options
+      #
+      # @return [Hash] Default parameters including model if set
       def default_params
-        { model: @model }
+        @model ? { model: @model } : {}
       end
 
+      # Performs a quick text completion with minimal configuration
+      #
+      # @param text [String] The input text to complete
+      # @param opts [Hash] Additional options (currently unused, reserved for future use)
+      # @return [String] The generated completion text
+      # @raise [Durable::Llm::APIError] If the API request fails
+      # @raise [IndexError] If the response contains no choices
+      # @raise [NoMethodError] If the response structure is unexpected
       def quick_complete(text, _opts = {})
         response = completion(process_params(messages: [{ role: 'user', content: text }]))
 
-        response.choices.first.message.content
+        choice = response.choices.first
+        raise IndexError, 'No completion choices returned' unless choice
+
+        message = choice.message
+        raise NoMethodError, 'Response choice has no message' unless message
+
+        content = message.content
+        raise NoMethodError, 'Response message has no content' unless content
+
+        content
       end
 
+      # Performs a completion request
+      #
+      # @param params [Hash] The completion parameters
+      # @return [Object] The completion response object
+      # @raise [Durable::Llm::APIError] If the API request fails
       def completion(params = {})
         @provider.completion(process_params(params))
       end
 
+      # Performs a chat completion request (alias for completion)
+      #
+      # @param params [Hash] The chat parameters
+      # @return [Object] The chat response object
+      # @raise [Durable::Llm::APIError] If the API request fails
       def chat(params = {})
-        @provider.chat(process_params(params))
+        @provider.completion(process_params(params))
       end
 
+      # Performs an embedding request
+      #
+      # @param params [Hash] The embedding parameters including model and input
+      # @return [Object] The embedding response object
+      # @raise [NotImplementedError] If the provider doesn't support embeddings
+      # @raise [Durable::Llm::APIError] If the API request fails
       def embed(params = {})
-        @provider.embed(process_params(params))
+        @provider.embedding(**process_params(params))
+      rescue NotImplementedError
+        raise NotImplementedError, "#{@provider.class.name} does not support embeddings"
       end
 
+      # Performs a streaming completion request
+      #
+      # @param params [Hash] The streaming parameters
+      # @yield [Object] Yields stream response chunks as they arrive
+      # @return [Object] The final response object
+      # @raise [NotImplementedError] If the provider doesn't support streaming
+      # @raise [Durable::Llm::APIError] If the API request fails
       def stream(params = {}, &block)
         @provider.stream(process_params(params), &block)
+      rescue NotImplementedError
+        raise NotImplementedError, "#{@provider.class.name} does not support streaming"
       end
 
+      # Checks if the provider supports streaming
+      #
+      # @return [Boolean] True if streaming is supported, false otherwise
       def stream?
         @provider.stream?
       end
@@ -53,3 +130,5 @@ module Durable
     end
   end
 end
+
+# Copyright (c) 2025 Durable Programming, LLC. All rights reserved.

data/lib/durable/llm/configuration.rb

@@ -1,43 +1,150 @@
+# frozen_string_literal: true
+
+# frozen_string_literal: true
+
 require 'ostruct'
 
 module Durable
   module Llm
+    # Configuration class for managing LLM provider settings and API keys.
+    #
+    # This class provides a centralized configuration management system for the Durable LLM gem.
+    # It supports dynamic provider configuration through method_missing, automatic loading from
+    # environment variables using the `DLLM__` prefix pattern, and optional integration with
+    # Datasette LLM configuration files.
+    #
+    # ## Basic Usage
+    #
+    # ```ruby
+    # config = Durable::Llm::Configuration.new
+    #
+    # # Configure providers dynamically
+    # config.openai = { api_key: 'sk-...', model: 'gpt-4' }
+    # config.anthropic.api_key = 'sk-ant-...'
+    #
+    # # Set default provider
+    # config.default_provider = 'anthropic'
+    # ```
+    #
+    # ## Environment Variable Configuration
+    #
+    # Configuration can be loaded from environment variables using the `DLLM__` prefix:
+    #
+    # ```bash
+    # export DLLM__OPENAI__API_KEY=sk-your-key
+    # export DLLM__ANTHROPIC__API_KEY=sk-ant-your-key
+    # export DLLM__OPENAI__MODEL=gpt-4
+    # ```
+    #
+    # ## Datasette LLM Integration
+    #
+    # The configuration automatically loads API keys from Datasette LLM's configuration file
+    # at `~/.config/io.datasette.llm/keys.json` when `load_from_datasette` is called.
+    #
+    # @example Dynamic provider configuration
+    #   config = Durable::Llm::Configuration.new
+    #   config.openai.api_key = 'sk-...'
+    #   config.anthropic = { api_key: 'sk-ant-...', model: 'claude-3' }
+    #
+    # @example Environment variable loading
+    #   ENV['DLLM__OPENAI__API_KEY'] = 'sk-...'
+    #   config = Durable::Llm::Configuration.new # Automatically loads from env
+    #
+    # @example Datasette integration
+    #   config.load_from_datasette # Loads from ~/.config/io.datasette.llm/keys.json
+    #
+    # @see Durable::Llm::Client
+    # @see Durable::Llm::Providers
     class Configuration
+      # @return [String] The default provider name to use when none is specified
       attr_accessor :default_provider
+
+      # @return [Hash<Symbol, OpenStruct>] Hash of provider configurations keyed by provider name
       attr_reader :providers
 
+      # Initializes a new Configuration instance.
+      #
+      # Creates an empty providers hash, sets the default provider to 'openai',
+      # and automatically loads configuration from environment variables.
+      #
+      # @return [Configuration] A new configuration instance
       def initialize
         @providers = {}
         @default_provider = 'openai'
         load_from_env
       end
 
+      # Clears all provider configurations and resets to defaults.
+      #
+      # This method removes all configured providers, resets the default provider
+      # to 'openai', and reloads configuration from environment variables.
+      #
+      # @return [void]
       def clear
         @providers.clear
         @default_provider = 'openai'
+        load_from_env
       end
 
+      # Loads API keys from Datasette LLM configuration file.
+      #
+      # This method attempts to load API keys from the Datasette LLM configuration
+      # file located at `~/.config/io.datasette.llm/keys.json`. If the file exists
+      # and contains valid JSON, it will populate the API keys for any configured
+      # providers that have matching entries in the file.
+      #
+      # The method gracefully handles missing files, invalid JSON, and other
+      # file system errors by issuing warnings and continuing execution.
+      #
+      # @return [void]
+      # @example Load Datasette configuration
+      #   config = Durable::Llm::Configuration.new
+      #   config.load_from_datasette # Loads keys from ~/.config/io.datasette.llm/keys.json
       def load_from_datasette
         config_file = File.expand_path('~/.config/io.datasette.llm/keys.json')
 
-        if File.exist?(config_file)
+        return unless File.exist?(config_file)
+
+        begin
           config_data = JSON.parse(File.read(config_file))
 
           Durable::Llm::Providers.providers.each do |provider|
-            @providers[provider.to_sym] ||= OpenStruct.new
+            next unless config_data[provider.to_s]
 
-            @providers[provider.to_sym][:api_key] = config_data[provider.to_s] if config_data[provider.to_s]
+            @providers[provider.to_sym] ||= OpenStruct.new
+            @providers[provider.to_sym].api_key = config_data[provider.to_s]
           end
+        rescue JSON::ParserError => e
+          warn "Error parsing Datasette LLM configuration file: #{e.message}"
+        rescue StandardError => e
+          warn "Error loading Datasette LLM configuration: #{e.message}"
         end
-      rescue JSON::ParserError => e
-        puts "Error parsing JSON file: #{e.message}"
       end
 
+      # Loads configuration from environment variables.
+      #
+      # This method scans all environment variables for those starting with the
+      # `DLLM__` prefix and automatically configures provider settings based on
+      # the variable names. The format is `DLLM__PROVIDER__SETTING=value`.
+      #
+      # For example:
+      # - `DLLM__OPENAI__API_KEY=sk-...` sets the API key for OpenAI
+      # - `DLLM__ANTHROPIC__MODEL=claude-3` sets the default model for Anthropic
+      #
+      # Provider and setting names are converted to lowercase symbols for consistency.
+      #
+      # @return [void]
+      # @example Environment variable configuration
+      #   ENV['DLLM__OPENAI__API_KEY'] = 'sk-...'
+      #   ENV['DLLM__ANTHROPIC__MODEL'] = 'claude-3'
+      #   config = Durable::Llm::Configuration.new # Automatically loads these values
       def load_from_env
         ENV.each do |key, value|
           next unless key.start_with?('DLLM__')
 
           parts = key.split('__')
+          next unless parts.length >= 3 # Must have DLLM__PROVIDER__SETTING
+
           provider = parts[1].downcase.to_sym
           setting = parts[2].downcase.to_sym
           @providers[provider] ||= OpenStruct.new
@@ -45,18 +152,64 @@ module Durable
         end
       end
 
+      # Provides dynamic access to provider configurations.
+      #
+      # This method implements dynamic method dispatch for provider configuration.
+      # It allows accessing and setting provider configurations using method calls
+      # like `config.openai` or `config.openai = { api_key: '...' }`.
+      #
+      # ## Getter Methods
+      #
+      # When called without an assignment (e.g., `config.openai`), it returns
+      # an OpenStruct for the specified provider, creating one if it doesn't exist.
+      #
+      # ## Setter Methods
+      #
+      # When called with an assignment (e.g., `config.openai = ...`), it sets
+      # the configuration for the provider:
+      #
+      # - If passed a Hash, merges the hash values into the provider's OpenStruct
+      # - If passed any other object, replaces the provider's configuration entirely
+      #
+      # @param method_name [Symbol] The method name being called
+      # @param args [Array] Arguments passed to the method
+      # @return [OpenStruct] For getter calls, returns the provider configuration
+      # @return [Object] For setter calls, returns the assigned value
+      # @example Dynamic getter
+      #   config.openai # => #<OpenStruct>
+      # @example Hash setter (merges values)
+      #   config.openai = { api_key: 'sk-...', model: 'gpt-4' }
+      # @example Object setter (replaces configuration)
+      #   config.openai = OpenStruct.new(api_key: 'sk-...')
       def method_missing(method_name, *args)
+        provider_name = method_name.to_s.chomp('=').to_sym
+
         if method_name.to_s.end_with?('=')
-          provider = method_name.to_s.chomp('=').to_sym
-          @providers[provider] = args.first
+          @providers[provider_name] ||= OpenStruct.new
+          if args.first.is_a?(Hash)
+            args.first.each { |k, v| @providers[provider_name][k] = v }
+          else
+            @providers[provider_name] = args.first
+          end
         else
-          @providers[method_name]
+          @providers[provider_name] ||= OpenStruct.new
         end
       end
 
-      def respond_to_missing?(method_name, include_private = false)
-        method_name.to_s.end_with?('=') || @providers.key?(method_name) || super
+      # Indicates whether the configuration responds to the given method.
+      #
+      # This method always returns true to support dynamic provider configuration
+      # methods. Any method call on the configuration object is considered valid
+      # since providers are created dynamically as needed.
+      #
+      # @param method_name [Symbol] The method name to check
+      # @param include_private [Boolean] Whether to include private methods
+      # @return [Boolean] Always returns true
+      def respond_to_missing?(_method_name, _include_private = false)
+        true
       end
     end
   end
 end
+
+# Copyright (c) 2025 Durable Programming, LLC. All rights reserved.

data/lib/durable/llm/errors.rb

@@ -1,33 +1,218 @@
+# frozen_string_literal: true
+
+# This file defines a comprehensive hierarchy of custom exception classes for the Durable LLM gem,
+# providing specific error types for different failure scenarios including API errors, rate limiting,
+# authentication issues, network problems, and configuration errors. The error hierarchy extends
+# from a base Error class and allows for precise error handling and user feedback throughout the
+# gem's LLM provider interactions and operations.
+
 module Durable
   module Llm
+    # Base error class for all Durable LLM exceptions.
+    #
+    # All custom errors in the Durable LLM gem inherit from this class,
+    # allowing users to rescue all LLM-related errors with a single catch block.
+    #
+    # @example Rescuing all Durable LLM errors
+    #   begin
+    #     # LLM operation
+    #   rescue Durable::Llm::Error => e
+    #     puts "LLM operation failed: #{e.message}"
+    #   end
     class Error < StandardError; end
 
+    # Error raised when an API request fails with an unexpected error.
+    #
+    # This error is raised for API errors that don't fit into more specific categories
+    # like authentication, rate limiting, or server errors.
+    #
+    # @example Handling API errors
+    #   begin
+    #     client.complete("Hello")
+    #   rescue Durable::Llm::APIError => e
+    #     puts "API request failed: #{e.message}"
+    #   end
     class APIError < Error; end
 
+    # Error raised when the API rate limit has been exceeded.
+    #
+    # This typically occurs when too many requests are made within a short time period.
+    # Users should implement retry logic with exponential backoff when encountering this error.
+    #
+    # @example Handling rate limit errors with retry
+    #   retries = 0
+    #   begin
+    #     client.complete("Hello")
+    #   rescue Durable::Llm::RateLimitError => e
+    #     if retries < 3
+    #       sleep(2 ** retries)
+    #       retries += 1
+    #       retry
+    #     else
+    #       puts "Rate limit exceeded after retries: #{e.message}"
+    #     end
+    #   end
     class RateLimitError < Error; end
 
+    # Error raised when authentication with the LLM provider fails.
+    #
+    # This typically occurs when API keys are invalid, expired, or not provided.
+    # Users should check their API key configuration when encountering this error.
+    #
+    # @example Handling authentication errors
+    #   begin
+    #     client.complete("Hello")
+    #   rescue Durable::Llm::AuthenticationError => e
+    #     puts "Authentication failed. Please check your API key: #{e.message}"
+    #   end
     class AuthenticationError < Error; end
 
+    # Error raised when the request parameters are invalid.
+    #
+    # This occurs when the request contains malformed data, invalid parameters,
+    # or violates the API's constraints.
+    #
+    # @example Handling invalid request errors
+    #   begin
+    #     client.complete("Hello", model: "invalid-model")
+    #   rescue Durable::Llm::InvalidRequestError => e
+    #     puts "Invalid request parameters: #{e.message}"
+    #   end
     class InvalidRequestError < Error; end
 
+    # Error raised when a requested resource cannot be found.
+    #
+    # This typically occurs when requesting a model or resource that doesn't exist
+    # or is not available to the user.
+    #
+    # @example Handling resource not found errors
+    #   begin
+    #     client.complete("Hello", model: "nonexistent-model")
+    #   rescue Durable::Llm::ResourceNotFoundError => e
+    #     puts "Requested resource not found: #{e.message}"
+    #   end
     class ResourceNotFoundError < Error; end
 
+    # Error raised when a request times out.
+    #
+    # This occurs when the API request takes longer than the configured timeout period.
+    # Users may want to increase timeout settings or retry the request.
+    #
+    # @example Handling timeout errors
+    #   begin
+    #     client.complete("Hello")
+    #   rescue Durable::Llm::TimeoutError => e
+    #     puts "Request timed out: #{e.message}"
+    #   end
     class TimeoutError < Error; end
 
+    # Error raised when the LLM provider's server encounters an internal error.
+    #
+    # This indicates a problem on the provider's side, not with the user's request.
+    # Users should retry the request after a short delay.
+    #
+    # @example Handling server errors
+    #   begin
+    #     client.complete("Hello")
+    #   rescue Durable::Llm::ServerError => e
+    #     puts "Server error occurred: #{e.message}"
+    #     # Consider retrying after a delay
+    #   end
     class ServerError < Error; end
 
+    # Error raised when attempting to use an unsupported LLM provider.
+    #
+    # This occurs when the requested provider is not implemented or configured
+    # in the Durable LLM gem.
+    #
+    # @example Handling unsupported provider errors
+    #   begin
+    #     client = Durable::Llm::Client.new(provider: "unsupported-provider")
+    #   rescue Durable::Llm::UnsupportedProviderError => e
+    #     puts "Unsupported provider: #{e.message}"
+    #   end
     class UnsupportedProviderError < Error; end
 
+    # Error raised when there is a configuration problem.
+    #
+    # This occurs when required configuration is missing, invalid, or inconsistent.
+    # Users should check their configuration settings.
+    #
+    # @example Handling configuration errors
+    #   begin
+    #     client = Durable::Llm::Client.new(api_key: nil)
+    #   rescue Durable::Llm::ConfigurationError => e
+    #     puts "Configuration error: #{e.message}"
+    #   end
     class ConfigurationError < Error; end
 
+    # Error raised when the requested model is not found or not available.
+    #
+    # This is similar to ResourceNotFoundError but specifically for models.
+    # It occurs when the specified model doesn't exist or isn't accessible.
+    #
+    # @example Handling model not found errors
+    #   begin
+    #     client.complete("Hello", model: "unknown-model")
+    #   rescue Durable::Llm::ModelNotFoundError => e
+    #     puts "Model not found: #{e.message}"
+    #   end
     class ModelNotFoundError < Error; end
 
+    # Error raised when the account has insufficient quota or credits.
+    #
+    # This occurs when the user's account has exhausted its usage limits
+    # or doesn't have enough credits for the requested operation.
+    #
+    # @example Handling insufficient quota errors
+    #   begin
+    #     client.complete("Hello")
+    #   rescue Durable::Llm::InsufficientQuotaError => e
+    #     puts "Insufficient quota: #{e.message}"
+    #   end
     class InsufficientQuotaError < Error; end
 
+    # Error raised when the API response is invalid or malformed.
+    #
+    # This occurs when the provider returns a response that cannot be parsed
+    # or doesn't match the expected format.
+    #
+    # @example Handling invalid response errors
+    #   begin
+    #     client.complete("Hello")
+    #   rescue Durable::Llm::InvalidResponseError => e
+    #     puts "Invalid response received: #{e.message}"
+    #   end
     class InvalidResponseError < Error; end
 
+    # Error raised when there is a network connectivity problem.
+    #
+    # This occurs when the request cannot reach the LLM provider due to
+    # network issues, DNS problems, or connectivity failures.
+    #
+    # @example Handling network errors
+    #   begin
+    #     client.complete("Hello")
+    #   rescue Durable::Llm::NetworkError => e
+    #     puts "Network error: #{e.message}"
+    #   end
     class NetworkError < Error; end
 
+    # Error raised when there is a problem with streaming responses.
+    #
+    # This occurs during streaming operations when the connection is interrupted,
+    # the stream format is invalid, or other streaming-specific issues arise.
+    #
+    # @example Handling streaming errors
+    #   begin
+    #     client.stream("Hello") do |chunk|
+    #       puts chunk
+    #     end
+    #   rescue Durable::Llm::StreamingError => e
+    #     puts "Streaming error: #{e.message}"
+    #   end
     class StreamingError < Error; end
   end
 end
+
+# Copyright (c) 2025 Durable Programming, LLC. All rights reserved.