durable-llm 0.1.4 → 0.1.6

data/lib/durable/llm/client.rb

@@ -1,55 +1,275 @@
+# 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 [ArgumentError] If provider_name is nil or empty
+      # @raise [NameError] If the provider class cannot be found
+      # @example Initialize with OpenAI provider
+      #   client = Durable::Llm::Client.new(:openai, model: 'gpt-4', api_key: 'sk-...')
+      # @example Initialize with Anthropic provider
+      #   client = Durable::Llm::Client.new(:anthropic, model: 'claude-3-opus-20240229')
       def initialize(provider_name, options = {})
-        @model = options.delete('model') || options.delete(:model) if options['model'] || options[:model]
+        if provider_name.nil? || provider_name.to_s.strip.empty?
+          raise ArgumentError, 'provider_name cannot be nil or empty. Supported providers: ' \
+                               "#{Durable::Llm::Providers.available_providers.join(', ')}"
+        end
+        raise ArgumentError, 'options must be a Hash' unless options.is_a?(Hash)
+
+        @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
 
-      def quick_complete(text, _opts = {})
+      # Performs a 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 [ArgumentError] If text is nil or empty
+      # @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
+      # @example Text completion with OpenAI
+      #   client = Durable::Llm::Client.new(:openai, model: 'gpt-4')
+      #   response = client.complete('What is the capital of France?')
+      #   puts response # => "The capital of France is Paris."
+      def complete(text, _opts = {})
+        if text.nil? || text.to_s.strip.empty?
+          raise ArgumentError, 'text cannot be nil or empty. Provide a non-empty string for completion.'
+        end
+
         response = completion(process_params(messages: [{ role: 'user', content: text }]))
 
-        response.choices.first.message.content
+        choice = response.choices.first
+        unless choice
+          raise IndexError, 'No completion choices returned from the API. This may indicate an ' \
+                            'API error or invalid request parameters.'
+        end
+
+        message = choice.message
+        unless message
+          raise NoMethodError, 'Response choice has no message. The API response format may be ' \
+                               'unexpected or the provider may have changed their response structure.'
+        end
+
+        content = message.content
+        unless content
+          raise NoMethodError, 'Response message has no content. This may occur if the model ' \
+                               'refused to respond or if content filtering was applied.'
+        end
+
+        content
       end
+      alias quick_complete complete
 
+      # Performs a completion request
+      #
+      # @param params [Hash] The completion parameters
+      # @option params [String] :model The model to use (overrides default)
+      # @option params [Array<Hash>] :messages The conversation messages
+      # @option params [Float] :temperature Sampling temperature (0.0-2.0)
+      # @option params [Integer] :max_tokens Maximum tokens to generate
+      # @return [Object] The completion response object
+      # @raise [ArgumentError] If params is not a Hash
+      # @raise [Durable::Llm::APIError] If the API request fails
+      # @example Perform a completion
+      #   client = Durable::Llm::Client.new(:openai, model: 'gpt-4')
+      #   response = client.completion(
+      #     messages: [
+      #       { role: 'system', content: 'You are a helpful assistant.' },
+      #       { role: 'user', content: 'Hello!' }
+      #     ],
+      #     temperature: 0.7
+      #   )
       def completion(params = {})
+        raise ArgumentError, 'params must be a Hash' unless params.is_a?(Hash)
+
         @provider.completion(process_params(params))
       end
 
+      # Performs a chat completion request (alias for completion)
+      #
+      # @param params [Hash] The chat parameters
+      # @option params [String] :model The model to use (overrides default)
+      # @option params [Array<Hash>] :messages The conversation messages
+      # @option params [Float] :temperature Sampling temperature (0.0-2.0)
+      # @option params [Integer] :max_tokens Maximum tokens to generate
+      # @return [Object] The chat response object
+      # @raise [ArgumentError] If params is not a Hash
+      # @raise [Durable::Llm::APIError] If the API request fails
+      # @see #completion
       def chat(params = {})
-        @provider.chat(process_params(params))
+        raise ArgumentError, 'params must be a Hash' unless params.is_a?(Hash)
+
+        @provider.completion(process_params(params))
       end
 
+      # Performs an embedding request
+      #
+      # @param params [Hash] The embedding parameters including model and input
+      # @option params [String] :model The embedding model to use
+      # @option params [String, Array<String>] :input The text(s) to embed
+      # @return [Object] The embedding response object
+      # @raise [ArgumentError] If params is not a Hash or missing required fields
+      # @raise [NotImplementedError] If the provider doesn't support embeddings
+      # @raise [Durable::Llm::APIError] If the API request fails
+      # @example Generate embeddings
+      #   client = Durable::Llm::Client.new(:openai)
+      #   response = client.embed(
+      #     model: 'text-embedding-ada-002',
+      #     input: 'Hello, world!'
+      #   )
       def embed(params = {})
-        @provider.embed(process_params(params))
+        raise ArgumentError, 'params must be a Hash' unless params.is_a?(Hash)
+
+        @provider.embedding(**process_params(params))
+      rescue NotImplementedError
+        provider_name = @provider.class.name.split('::').last
+        raise NotImplementedError, "#{provider_name} does not support embeddings. " \
+                                    'Try using a provider like OpenAI that offers embedding models.'
       end
 
+      # Performs a streaming completion request
+      #
+      # @param params [Hash] The streaming parameters
+      # @option params [String] :model The model to use (overrides default)
+      # @option params [Array<Hash>] :messages The conversation messages
+      # @option params [Float] :temperature Sampling temperature (0.0-2.0)
+      # @option params [Integer] :max_tokens Maximum tokens to generate
+      # @yield [Object] Yields stream response chunks as they arrive
+      # @return [Object] The final response object
+      # @raise [ArgumentError] If params is not a Hash or no block is given
+      # @raise [NotImplementedError] If the provider doesn't support streaming
+      # @raise [Durable::Llm::APIError] If the API request fails
+      # @example Stream a completion
+      #   client = Durable::Llm::Client.new(:openai, model: 'gpt-4')
+      #   client.stream(messages: [{ role: 'user', content: 'Count to 10' }]) do |chunk|
+      #     print chunk.choices.first.delta.content
+      #   end
       def stream(params = {}, &block)
+        raise ArgumentError, 'params must be a Hash' unless params.is_a?(Hash)
+        unless block_given?
+          raise ArgumentError, 'block required for streaming. Use: client.stream(params) { |chunk| ... }'
+        end
+
         @provider.stream(process_params(params), &block)
+      rescue NotImplementedError
+        provider_name = @provider.class.name.split('::').last
+        raise NotImplementedError, "#{provider_name} does not support streaming. " \
+                                    'Try using completion() or chat() instead.'
       end
 
+      # Checks if the provider supports streaming
+      #
+      # @return [Boolean] True if streaming is supported, false otherwise
       def stream?
         @provider.stream?
       end
 
+      # Sets the model for subsequent requests (fluent interface)
+      #
+      # @param model_name [String] The model to use
+      # @return [Client] Returns self for method chaining
+      # @example Fluent API usage
+      #   client = Durable::Llm::Client.new(:openai)
+      #   client.with_model('gpt-4').complete('Hello!')
+      def with_model(model_name)
+        @model = model_name
+        self
+      end
+
+      # Sets temperature for the next request (fluent interface)
+      #
+      # @param temp [Float] The temperature value (0.0-2.0)
+      # @return [Client] Returns self for method chaining
+      # @example Fluent temperature setting
+      #   client.with_temperature(0.7).complete('Be creative!')
+      def with_temperature(temp)
+        @next_temperature = temp
+        self
+      end
+
+      # Sets max tokens for the next request (fluent interface)
+      #
+      # @param tokens [Integer] Maximum tokens to generate
+      # @return [Client] Returns self for method chaining
+      # @example Fluent max tokens setting
+      #   client.with_max_tokens(500).complete('Write a story')
+      def with_max_tokens(tokens)
+        @next_max_tokens = tokens
+        self
+      end
+
+      # Creates a copy of the client with different configuration
+      #
+      # @param options [Hash] New configuration options
+      # @option options [String] :model Override the model
+      # @return [Client] A new client instance with merged configuration
+      # @example Clone with different model
+      #   gpt4_client = client.clone_with(model: 'gpt-4')
+      #   gpt35_client = client.clone_with(model: 'gpt-3.5-turbo')
+      def clone_with(**options)
+        provider_name = @provider.class.name.split('::').last.downcase.to_sym
+        self.class.new(provider_name, options.merge(model: @model))
+      end
+
       private
 
       def process_params(opts = {})
-        default_params.dup.merge(opts)
+        params = default_params.dup.merge(opts)
+
+        # Apply fluent interface settings if present
+        params[:temperature] = @next_temperature if @next_temperature
+        params[:max_tokens] = @next_max_tokens if @next_max_tokens
+
+        # Clear one-time settings after use
+        @next_temperature = nil
+        @next_max_tokens = nil
+
+        params
       end
     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/convenience.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+# This file provides global convenience functions for quick access to Durable LLM functionality
+# without requiring explicit module qualification. These functions follow Ruby conventions for
+# global helper methods and make the library more approachable for quick usage and scripting.
+# The functions delegate to the main Durable::Llm module methods while providing shorter names.
+
+# Creates a new Durable LLM client with the specified provider and options.
+#
+# This is a global convenience function that provides quick access to client creation
+# without requiring the full Durable::Llm module path. It's equivalent to calling
+# Durable::Llm.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 [Durable::Llm::Client] A new client instance
+# @example Create an OpenAI client
+#   client = DurableLlm(:openai, model: 'gpt-4', api_key: 'sk-...')
+#   response = client.complete('Hello!')
+# @example Create an Anthropic client
+#   client = DurableLlm(:anthropic, model: 'claude-3-opus-20240229')
+def DurableLlm(provider, **options)
+  Durable::Llm.new(provider, options)
+end
+
+# Shorter alias for DurableLlm
+#
+# @param provider [Symbol, String] The provider name
+# @param options [Hash] Configuration options
+# @return [Durable::Llm::Client] A new client instance
+# @see DurableLlm
+def DLLM(provider, **options)
+  Durable::Llm.new(provider, options)
+end
+
+# Performs a quick text completion with minimal setup
+#
+# This global convenience function allows for one-line LLM completions without
+# explicit client creation. Perfect for scripts and REPL usage.
+#
+# @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 client options
+# @return [String] The completion text
+# @example Quick completion
+#   result = LlmComplete('What is Ruby?', model: 'gpt-4')
+#   puts result
+# @example With specific provider
+#   result = LlmComplete('Explain AI', provider: :anthropic, model: 'claude-3-opus-20240229')
+def LlmComplete(text, provider: :openai, model: nil, **options)
+  Durable::Llm.complete(text, provider: provider, model: model, **options)
+end
+
+# Performs a chat completion with minimal setup
+#
+# This global convenience function allows for quick chat interactions without
+# explicit client creation.
+#
+# @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
+# @return [Object] The chat response object
+# @example Simple chat
+#   response = LlmChat([{ role: 'user', content: 'Hello!' }], model: 'gpt-4')
+#   puts response.choices.first.message.content
+def LlmChat(messages, provider: :openai, model: nil, **options)
+  Durable::Llm.chat(messages, provider: provider, model: model, **options)
+end
+
+# Lists available models for a provider
+#
+# @param provider [Symbol] The provider name (default: :openai)
+# @param options [Hash] Provider options
+# @return [Array<String>] List of available model IDs
+# @example List models
+#   models = LlmModels(:openai)
+#   puts models.inspect
+def LlmModels(provider = :openai, **options)
+  Durable::Llm.models(provider, **options)
+end
+
+# Configures Durable LLM with a block
+#
+# This global convenience function provides easy access to configuration.
+#
+# @yield [configuration] The configuration instance to modify
+# @yieldparam configuration [Durable::Llm::Configuration] The config object
+# @return [void]
+# @example Configure API keys
+#   LlmConfigure do |config|
+#     config.openai.api_key = 'sk-...'
+#     config.anthropic.api_key = 'sk-ant-...'
+#   end
+def LlmConfigure(&block)
+  Durable::Llm.configure(&block)
+end
+
+# Copyright (c) 2025 Durable Programming, LLC. All rights reserved.