durable-llm 0.1.3 → 0.1.5

data/lib/durable/llm/providers.rb

@@ -1,36 +1,121 @@
+# 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
+        @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 < Durable::Llm::Providers::Base
+          end
 
-        @provider_list ||= begin
-                             constants.select do |const_name|
-                               const = const_get(const_name)
-                               last_component = const.name.split('::').last
-                               next if last_component == '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)
-                           end
+          provider_classes.map do |const_name|
+            const_get(const_name).name.split('::').last.downcase.to_sym
+          end.uniq
+        end
       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
@@ -38,6 +123,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/version.rb

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

data/lib/durable/llm.rb

@@ -1,20 +1,156 @@
-require "zeitwerk"
+# 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.quick_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.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.quick_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)
@@ -25,3 +161,7 @@ end
 Durable::Llm.configure do
 end
 
+require 'durable/llm/providers'
+require 'durable/llm/client'
+
+# 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.quick_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.

data/sig/durable/llm.rbs

@@ -1,6 +1,307 @@
 module Durable
   module Llm
     VERSION: String
-    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+
+    def self.configure: () { (Configuration) -> void } -> void
+    def self.configuration: () -> Configuration
+    def self.config: () -> Configuration
+
+    class Error < StandardError
+    end
+
+    class APIError < Error
+    end
+
+    class RateLimitError < Error
+    end
+
+    class AuthenticationError < Error
+    end
+
+    class InvalidRequestError < Error
+    end
+
+    class ResourceNotFoundError < Error
+    end
+
+    class TimeoutError < Error
+    end
+
+    class ServerError < Error
+    end
+
+    class UnsupportedProviderError < Error
+    end
+
+    class ConfigurationError < Error
+    end
+
+    class ModelNotFoundError < Error
+    end
+
+    class InsufficientQuotaError < Error
+    end
+
+    class InvalidResponseError < Error
+    end
+
+    class NetworkError < Error
+    end
+
+    class StreamingError < Error
+    end
+
+    class Configuration
+      attr_accessor default_provider: String
+      attr_reader providers: Hash[Symbol, untyped]
+
+      def initialize: () -> void
+      def clear: () -> void
+      def load_from_datasette: () -> void
+      def load_from_env: () -> void
+      def method_missing: (Symbol method_name, *untyped args) -> untyped
+      def respond_to_missing?: (Symbol method_name, ?bool include_private) -> bool
+    end
+
+    class Client
+      attr_reader provider: untyped
+      attr_accessor model: String?
+
+      def initialize: (Symbol | String provider_name, ?Hash[Symbol | String, untyped] options) -> void
+      def default_params: () -> Hash[Symbol, String?]
+      def quick_complete: (String text, ?Hash[Symbol, untyped] _opts) -> String
+      def completion: (?Hash[Symbol, untyped] params) -> untyped
+      def chat: (?Hash[Symbol, untyped] params) -> untyped
+      def embed: (?Hash[Symbol, untyped] params) -> untyped
+      def stream: (?Hash[Symbol, untyped] params) { (untyped) -> void } -> untyped
+      def stream?: () -> bool
+
+      private
+      def process_params: (?Hash[Symbol, untyped] opts) -> Hash[Symbol, untyped]
+    end
+
+    module Providers
+      def self.load_all: () -> void
+      def self.providers: () -> Array[Symbol]
+      def self.model_ids: () -> Array[String]
+      def self.model_id_to_provider: (String model_id) -> Class?
+
+      class Base
+        attr_accessor api_key: String?
+
+        def initialize: (?api_key: String?) -> void
+        def default_api_key: () -> String?
+        def completion: (Hash[Symbol | String, untyped] options) -> untyped
+        def self.models: () -> Array[String]
+        def models: () -> Array[String]
+        def self.stream?: () -> bool
+        def stream?: () -> bool
+        def stream: (Hash[Symbol | String, untyped] options) { (untyped) -> void } -> untyped
+        def embedding: (model: String, input: String | Array[String], **untyped options) -> untyped
+
+        private
+        def handle_response: (untyped response) -> untyped
+      end
+
+      class OpenAI < Base
+        BASE_URL: String
+        attr_accessor organization: String?
+
+        def initialize: (?api_key: String?, ?organization: String?) -> void
+        def completion: (Hash[Symbol | String, untyped] options) -> OpenAIResponse
+        def embedding: (model: String, input: String | Array[String], **untyped options) -> OpenAIEmbeddingResponse
+        def models: () -> Array[String]
+        def self.stream?: () -> true
+        def stream: (Hash[Symbol | String, untyped] options) { (OpenAIStreamResponse) -> void } -> void
+
+        class OpenAIResponse
+          attr_reader raw_response: Hash[String, untyped]
+          def initialize: (Hash[String, untyped] response) -> void
+          def choices: () -> Array[OpenAIChoice]
+          def data: () -> untyped
+          def embedding: () -> untyped
+          def to_s: () -> String
+        end
+
+        class OpenAIChoice
+          attr_reader message: OpenAIMessage
+          attr_reader finish_reason: String?
+          def initialize: (Hash[String, untyped] choice) -> void
+          def to_s: () -> String
+        end
+
+        class OpenAIMessage
+          attr_reader role: String
+          attr_reader content: String
+          def initialize: (Hash[String, untyped] message) -> void
+          def to_s: () -> String
+        end
+
+        class OpenAIStreamResponse
+          attr_reader choices: OpenAIStreamChoice
+          def initialize: (Hash[String, untyped] parsed) -> void
+          def to_s: () -> String
+        end
+
+        class OpenAIStreamChoice
+          attr_reader delta: OpenAIStreamDelta
+          attr_reader finish_reason: String?
+          def initialize: (Array[Hash[String, untyped]] | Hash[String, untyped] choice) -> void
+          def to_s: () -> String
+        end
+
+        class OpenAIStreamDelta
+          attr_reader role: String?
+          attr_reader content: String?
+          def initialize: (Hash[String, untyped] delta) -> void
+          def to_s: () -> String
+        end
+
+        class OpenAIEmbeddingResponse
+          attr_reader embedding: Array[Float]
+          def initialize: (Hash[String, untyped] data) -> void
+          def to_a: () -> Array[Float]
+        end
+      end
+
+      class Anthropic < Base
+        BASE_URL: String
+
+        def initialize: (?api_key: String?) -> void
+        def completion: (Hash[Symbol | String, untyped] options) -> AnthropicResponse
+        def models: () -> Array[String]
+        def self.models: () -> Array[String]
+        def self.stream?: () -> true
+        def stream: (Hash[Symbol | String, untyped] options) { (AnthropicStreamResponse) -> void } -> void
+
+        class AnthropicResponse
+          attr_reader raw_response: Hash[String, untyped]
+          def initialize: (Hash[String, untyped] response) -> void
+          def choices: () -> Array[AnthropicChoice]
+          def to_s: () -> String
+        end
+
+        class AnthropicChoice
+          attr_reader message: AnthropicMessage
+          def initialize: (untyped content) -> void
+          def to_s: () -> String
+        end
+
+        class AnthropicMessage
+          attr_reader role: String
+          attr_reader content: String
+          def initialize: (untyped content) -> void
+          def to_s: () -> String
+        end
+
+        class AnthropicStreamResponse
+          attr_reader choices: Array[AnthropicStreamChoice]
+          def initialize: (String fragment) -> void
+          def to_s: () -> String
+        end
+
+        class AnthropicStreamChoice
+          attr_reader delta: AnthropicStreamDelta
+          def initialize: (Hash[String, untyped] delta) -> void
+          def to_s: () -> String
+        end
+
+        class AnthropicStreamDelta
+          attr_reader type: String?
+          attr_reader text: String?
+          def initialize: (Hash[String, untyped] delta) -> void
+          def to_s: () -> String
+        end
+      end
+
+      class Groq < Base
+        BASE_URL: String
+
+        def self.conn: () -> untyped
+        def conn: () -> untyped
+        def initialize: (?api_key: String?) -> void
+        def completion: (Hash[Symbol | String, untyped] options) -> GroqResponse
+        def embedding: (model: String, input: String | Array[String], **untyped options) -> GroqResponse
+        def models: () -> Array[String]
+        def self.stream?: () -> false
+
+        class GroqResponse
+          attr_reader raw_response: Hash[String, untyped]
+          def initialize: (Hash[String, untyped] response) -> void
+          def choices: () -> Array[GroqChoice]
+          def to_s: () -> String
+          def to_h: () -> Hash[String, untyped]
+        end
+
+        class GroqChoice
+          attr_reader message: GroqMessage
+          attr_reader finish_reason: String?
+          def initialize: (Hash[String, untyped] choice) -> void
+          def to_s: () -> String
+        end
+
+        class GroqMessage
+          attr_reader role: String
+          attr_reader content: String
+          def initialize: (Hash[String, untyped] message) -> void
+          def to_s: () -> String
+        end
+      end
+
+      class Huggingface < Base
+        BASE_URL: String
+
+        def initialize: (?api_key: String?) -> void
+        def completion: (Hash[Symbol | String, untyped] options) -> HuggingfaceResponse
+        def models: () -> Array[String]
+        def self.models: () -> Array[String]
+
+        class HuggingfaceResponse
+          attr_reader raw_response: untyped
+          def initialize: (untyped response) -> void
+          def choices: () -> Array[HuggingfaceChoice]
+          def to_s: () -> String
+        end
+
+        class HuggingfaceChoice
+          attr_reader text: String
+          def initialize: (Hash[String, untyped] choice) -> void
+          def to_s: () -> String
+        end
+      end
+
+      class Cohere < Base
+        BASE_URL: String
+
+        def initialize: (?api_key: String?) -> void
+        def completion: (Hash[Symbol | String, untyped] options) -> CohereResponse
+        def models: () -> Array[String]
+        def self.stream?: () -> false
+
+        class CohereResponse
+          attr_reader raw_response: Hash[String, untyped]
+          def initialize: (Hash[String, untyped] response) -> void
+          def choices: () -> Array[CohereChoice]
+          def to_s: () -> String
+        end
+
+        class CohereChoice
+          attr_reader text: String
+          def initialize: (Hash[String, untyped] generation) -> void
+          def to_s: () -> String
+        end
+      end
+
+      Openai: singleton(OpenAI)
+      Claude: singleton(Anthropic)
+      Claude3: singleton(Anthropic)
+    end
+
+    class CLI < Thor
+      def self.exit_on_failure?: () -> true
+      def prompt: (*String prompt) -> void
+      def chat: () -> void
+      def models: () -> void
+    end
   end
 end