durable-llm 0.1.5 → 0.1.6

data/lib/durable/llm/providers.rb

@@ -83,6 +83,16 @@ module Durable
         end
       end
 
+      # Returns a list of all available provider names as strings.
+      #
+      # Alias for providers that returns strings instead of symbols, useful for
+      # display purposes in error messages and documentation.
+      #
+      # @return [Array<String>] Array of provider names
+      def self.available_providers
+        providers.map(&:to_s).sort
+      end
+
       # Returns a flat list of all model IDs across all providers.
       #
       # This method aggregates model IDs from all available providers by calling

data/lib/durable/llm/response_helpers.rb

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

data/lib/durable/llm/version.rb

@@ -4,7 +4,7 @@
 
 module Durable
   module Llm
-    VERSION = '0.1.5'
+    VERSION = '0.1.6'
   end
 end
 

data/lib/durable/llm.rb

@@ -21,7 +21,7 @@
 #
 # # Create a client and make a request
 # client = Durable::Llm.new(:openai, model: 'gpt-4')
-# response = client.quick_complete('Hello, world!')
+# response = client.complete('Hello, world!')
 # puts response # => "Hello! How can I help you today?"
 # ```
 #
@@ -91,7 +91,7 @@ module Durable
   #   end
   #
   #   client = Durable::Llm.new(:openai)
-  #   response = client.quick_complete('Hello!')
+  #   response = client.complete('Hello!')
   #
   # @see Durable::Llm::Client
   # @see Durable::Llm::Configuration
@@ -155,6 +155,73 @@ module Durable
       self.configuration ||= Configuration.new
       yield(configuration)
     end
+
+    # Creates a quick completion with minimal setup.
+    #
+    # This is a convenience method for one-off completions that automatically
+    # creates a client, performs the completion, and returns the text result.
+    #
+    # @param text [String] The input text to complete
+    # @param provider [Symbol] The provider to use (default: :openai)
+    # @param model [String] The model to use (required)
+    # @param options [Hash] Additional options for the client
+    # @return [String] The completion text
+    # @raise [ArgumentError] If required parameters are missing
+    # @example Quick completion with OpenAI
+    #   result = Durable::Llm.complete('What is Ruby?', model: 'gpt-4')
+    #   puts result
+    # @example Quick completion with Anthropic
+    #   result = Durable::Llm.complete('Explain AI', provider: :anthropic, model: 'claude-3-opus-20240229')
+    #   puts result
+    def self.complete(text, provider: :openai, model: nil, **options)
+      raise ArgumentError, 'text is required' if text.nil? || text.to_s.strip.empty?
+      raise ArgumentError, 'model is required' if model.nil? || model.to_s.strip.empty?
+
+      client = new(provider, options.merge(model: model))
+      client.complete(text)
+    end
+
+    # Creates a chat completion with minimal setup.
+    #
+    # This is a convenience method for quick chat interactions that automatically
+    # creates a client and performs the chat completion.
+    #
+    # @param messages [Array<Hash>] Array of message hashes with :role and :content
+    # @param provider [Symbol] The provider to use (default: :openai)
+    # @param model [String] The model to use (required)
+    # @param options [Hash] Additional options for the client and request
+    # @return [Object] The chat response object
+    # @raise [ArgumentError] If required parameters are missing
+    # @example Simple chat
+    #   response = Durable::Llm.chat(
+    #     [{ role: 'user', content: 'Hello!' }],
+    #     model: 'gpt-4'
+    #   )
+    #   puts response.choices.first.message.content
+    def self.chat(messages, provider: :openai, model: nil, **options)
+      raise ArgumentError, 'messages are required' if messages.nil? || messages.empty?
+      raise ArgumentError, 'model is required' if model.nil? || model.to_s.strip.empty?
+
+      request_keys = %i[temperature max_tokens top_p frequency_penalty presence_penalty]
+      request_params = options.select { |k, _| request_keys.include?(k) }
+      client_options = options.reject { |k, _| request_keys.include?(k) }
+
+      client = new(provider, client_options.merge(model: model))
+      client.chat(messages: messages, **request_params)
+    end
+
+    # Lists available models for a provider.
+    #
+    # @param provider [Symbol] The provider name (default: :openai)
+    # @param options [Hash] Provider options (e.g., api_key)
+    # @return [Array<String>] List of available model IDs
+    # @example List OpenAI models
+    #   models = Durable::Llm.models(:openai)
+    #   puts models.inspect
+    def self.models(provider = :openai, **options)
+      client = new(provider, options)
+      client.provider.models
+    end
   end
 end
 
@@ -163,5 +230,11 @@ end
 
 require 'durable/llm/providers'
 require 'durable/llm/client'
+require 'durable/llm/response_helpers'
+require 'durable/llm/provider_utilities'
+
+# Load global convenience functions for easier access
+# Users can skip this by requiring 'durable/llm/core' instead of 'durable/llm'
+require 'durable/llm/convenience' unless ENV['DLLM_NO_CONVENIENCE']
 
 # Copyright (c) 2025 Durable Programming, LLC. All rights reserved.

data/lib/durable.rb

@@ -16,7 +16,7 @@
 #   end
 #
 #   client = Durable::Llm.new(:openai)
-#   response = client.quick_complete('Hello!')
+#   response = client.complete('Hello!')
 #
 # @see Durable::Llm
 

data/sig/durable/llm.rbs

@@ -69,7 +69,8 @@ module Durable
 
       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 complete: (String text, ?Hash[Symbol, untyped] _opts) -> String
+      alias quick_complete complete
       def completion: (?Hash[Symbol, untyped] params) -> untyped
       def chat: (?Hash[Symbol, untyped] params) -> untyped
       def embed: (?Hash[Symbol, untyped] params) -> untyped

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: durable-llm
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.1.6
 platform: ruby
 authors:
 - Durable Programming Team
 bindir: exe
 cert_chain: []
-date: 1980-01-01 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: event_stream_parser
@@ -16,6 +16,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -23,20 +26,29 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.0
 - !ruby/object:Gem::Dependency
   name: faraday
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: highline
   requirement: !ruby/object:Gem::Requirement
@@ -44,6 +56,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.1.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -51,6 +66,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.1.0
 - !ruby/object:Gem::Dependency
   name: json
   requirement: !ruby/object:Gem::Requirement
@@ -58,6 +76,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.6'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.6.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -65,6 +86,23 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.6'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.6.0
+- !ruby/object:Gem::Dependency
+  name: ostruct
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.6.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.6.0
 - !ruby/object:Gem::Dependency
   name: thor
   requirement: !ruby/object:Gem::Requirement
@@ -72,6 +110,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.3'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.3.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -79,6 +120,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.3'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.3.0
 - !ruby/object:Gem::Dependency
   name: zeitwerk
   requirement: !ruby/object:Gem::Requirement
@@ -86,6 +130,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.6'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.6.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -93,6 +140,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.6'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.6.0
 - !ruby/object:Gem::Dependency
   name: dotenv
   requirement: !ruby/object:Gem::Requirement
@@ -163,6 +213,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
 description: Durable-LLM is a unified interface for interacting with multiple Large
   Language Model APIs, simplifying integration of AI capabilities into Ruby applications.
 email:
@@ -176,7 +240,6 @@ files:
 - CLI.md
 - CONFIGURE.md
 - Gemfile
-- Gemfile.lock
 - LICENSE.txt
 - README.md
 - Rakefile
@@ -193,7 +256,9 @@ files:
 - lib/durable/llm/cli.rb
 - lib/durable/llm/client.rb
 - lib/durable/llm/configuration.rb
+- lib/durable/llm/convenience.rb
 - lib/durable/llm/errors.rb
+- lib/durable/llm/provider_utilities.rb
 - lib/durable/llm/providers.rb
 - lib/durable/llm/providers/anthropic.rb
 - lib/durable/llm/providers/azure_openai.rb
@@ -211,6 +276,7 @@ files:
 - lib/durable/llm/providers/perplexity.rb
 - lib/durable/llm/providers/together.rb
 - lib/durable/llm/providers/xai.rb
+- lib/durable/llm/response_helpers.rb
 - lib/durable/llm/version.rb
 - sig/durable/llm.rbs
 homepage: https://github.com/durableprogramming/durable-llm

data/Gemfile.lock

@@ -1,103 +0,0 @@
-PATH
-  remote: .
-  specs:
-    durable-llm (0.1.5)
-      event_stream_parser (~> 1.0)
-      faraday (> 1.0)
-      highline (~> 3.1)
-      json (~> 2.6)
-      thor (~> 1.3)
-      zeitwerk (~> 2.6)
-
-GEM
-  remote: https://rubygems.org/
-  specs:
-    addressable (2.8.7)
-      public_suffix (>= 2.0.2, < 7.0)
-    ast (2.4.2)
-    base64 (0.2.0)
-    bigdecimal (3.1.8)
-    crack (1.0.0)
-      bigdecimal
-      rexml
-    dotenv (2.8.1)
-    event_stream_parser (1.0.0)
-    faraday (2.12.0)
-      faraday-net_http (>= 2.0, < 3.4)
-      json
-      logger
-    faraday-multipart (1.0.4)
-      multipart-post (~> 2)
-    faraday-net_http (3.3.0)
-      net-http
-    hashdiff (1.1.1)
-    highline (3.1.1)
-      reline
-    io-console (0.7.2)
-    json (2.7.2)
-    language_server-protocol (3.17.0.3)
-    logger (1.6.1)
-    minitest (5.25.1)
-    mocha (2.4.5)
-      ruby2_keywords (>= 0.0.5)
-    multipart-post (2.4.1)
-    net-http (0.4.1)
-      uri
-    parallel (1.26.3)
-    parser (3.3.5.0)
-      ast (~> 2.4.1)
-      racc
-    public_suffix (6.0.1)
-    racc (1.8.1)
-    rainbow (3.1.1)
-    rake (13.2.1)
-    regexp_parser (2.9.2)
-    reline (0.5.10)
-      io-console (~> 0.5)
-    rexml (3.3.8)
-    rubocop (1.66.1)
-      json (~> 2.3)
-      language_server-protocol (>= 3.17.0)
-      parallel (~> 1.10)
-      parser (>= 3.3.0.2)
-      rainbow (>= 2.2.2, < 4.0)
-      regexp_parser (>= 2.4, < 3.0)
-      rubocop-ast (>= 1.32.2, < 2.0)
-      ruby-progressbar (~> 1.7)
-      unicode-display_width (>= 2.4.0, < 3.0)
-    rubocop-ast (1.32.3)
-      parser (>= 3.3.1.0)
-    ruby-openai (7.1.0)
-      event_stream_parser (>= 0.3.0, < 2.0.0)
-      faraday (>= 1)
-      faraday-multipart (>= 1)
-    ruby-progressbar (1.13.0)
-    ruby2_keywords (0.0.5)
-    thor (1.3.2)
-    unicode-display_width (2.6.0)
-    uri (0.13.1)
-    vcr (6.3.1)
-      base64
-    webmock (3.24.0)
-      addressable (>= 2.8.0)
-      crack (>= 0.3.2)
-      hashdiff (>= 0.4.0, < 2.0.0)
-    zeitwerk (2.6.18)
-
-PLATFORMS
-  x86_64-linux
-
-DEPENDENCIES
-  dotenv (~> 2.8)
-  durable-llm!
-  minitest (~> 5.0)
-  mocha (~> 2.1)
-  rake (~> 13.0)
-  rubocop (~> 1.21, ~> 1.0)
-  ruby-openai (~> 7.1)
-  thor (~> 1.3)
-  vcr (~> 6.0)
-  webmock (~> 3.24)
-
-BUNDLED WITH
-   2.7.1