durable-llm 0.1.5 → 0.1.6

data/devenv.lock

@@ -3,10 +3,10 @@
     "devenv": {
       "locked": {
         "dir": "src/modules",
-        "lastModified": 1760162706,
+        "lastModified": 1761922975,
         "owner": "cachix",
         "repo": "devenv",
-        "rev": "0d5ad578728fe4bce66eb4398b8b1e66deceb4e4",
+        "rev": "c9f0b47815a4895fadac87812de8a4de27e0ace1",
         "type": "github"
       },
       "original": {
@@ -19,10 +19,10 @@
     "flake-compat": {
       "flake": false,
       "locked": {
-        "lastModified": 1747046372,
+        "lastModified": 1761588595,
         "owner": "edolstra",
         "repo": "flake-compat",
-        "rev": "9100a0f413b0c601e0533d1d94ffd501ce2e7885",
+        "rev": "f387cd2afec9419c8ee37694406ca490c3f34ee5",
         "type": "github"
       },
       "original": {
@@ -31,6 +31,38 @@
         "type": "github"
       }
     },
+    "flake-compat_2": {
+      "flake": false,
+      "locked": {
+        "lastModified": 1761588595,
+        "owner": "edolstra",
+        "repo": "flake-compat",
+        "rev": "f387cd2afec9419c8ee37694406ca490c3f34ee5",
+        "type": "github"
+      },
+      "original": {
+        "owner": "edolstra",
+        "repo": "flake-compat",
+        "type": "github"
+      }
+    },
+    "flake-utils": {
+      "inputs": {
+        "systems": "systems"
+      },
+      "locked": {
+        "lastModified": 1731533236,
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "rev": "11707dc2f618dd54ca8739b309ec4fc024de578b",
+        "type": "github"
+      },
+      "original": {
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "type": "github"
+      }
+    },
     "git-hooks": {
       "inputs": {
         "flake-compat": "flake-compat",
@@ -40,10 +72,10 @@
         ]
       },
       "locked": {
-        "lastModified": 1759523803,
+        "lastModified": 1760663237,
         "owner": "cachix",
         "repo": "git-hooks.nix",
-        "rev": "cfc9f7bb163ad8542029d303e599c0f7eee09835",
+        "rev": "ca5b894d3e3e151ffc1db040b6ce4dcc75d31c37",
         "type": "github"
       },
       "original": {
@@ -74,10 +106,10 @@
     },
     "nixpkgs": {
       "locked": {
-        "lastModified": 1758532697,
+        "lastModified": 1761313199,
         "owner": "cachix",
         "repo": "devenv-nixpkgs",
-        "rev": "207a4cb0e1253c7658c6736becc6eb9cace1f25f",
+        "rev": "d1c30452ebecfc55185ae6d1c983c09da0c274ff",
         "type": "github"
       },
       "original": {
@@ -87,15 +119,51 @@
         "type": "github"
       }
     },
+    "nixpkgs-ruby": {
+      "inputs": {
+        "flake-compat": "flake-compat_2",
+        "flake-utils": "flake-utils",
+        "nixpkgs": [
+          "nixpkgs"
+        ]
+      },
+      "locked": {
+        "lastModified": 1759902829,
+        "owner": "bobvanderlinden",
+        "repo": "nixpkgs-ruby",
+        "rev": "5fba6c022a63f1e76dee4da71edddad8959f088a",
+        "type": "github"
+      },
+      "original": {
+        "owner": "bobvanderlinden",
+        "repo": "nixpkgs-ruby",
+        "type": "github"
+      }
+    },
     "root": {
       "inputs": {
         "devenv": "devenv",
         "git-hooks": "git-hooks",
         "nixpkgs": "nixpkgs",
+        "nixpkgs-ruby": "nixpkgs-ruby",
         "pre-commit-hooks": [
           "git-hooks"
         ]
       }
+    },
+    "systems": {
+      "locked": {
+        "lastModified": 1681028828,
+        "owner": "nix-systems",
+        "repo": "default",
+        "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nix-systems",
+        "repo": "default",
+        "type": "github"
+      }
     }
   },
   "root": "root",

data/devenv.nix

@@ -4,6 +4,9 @@
 
   packages = [ pkgs.git ];
 
-  languages.ruby.enable = true;
+  languages.ruby = {
+    enable = true;
+    version = "3.4.7";
+  };
 
 }

data/devenv.yaml

@@ -1,15 +1,8 @@
-# yaml-language-server: $schema=https://devenv.sh/devenv.schema.json
 inputs:
   nixpkgs:
     url: github:cachix/devenv-nixpkgs/rolling
-
-# If you're using non-OSS software, you can set allowUnfree to true.
-# allowUnfree: true
-
-# If you're willing to use a package that's vulnerable
-# permittedInsecurePackages:
-#  - "openssl-1.1.1w"
-
-# If you have more than one devenv you can merge them
-#imports:
-# - ./backend
+  nixpkgs-ruby:
+    url: github:bobvanderlinden/nixpkgs-ruby
+    inputs:
+      nixpkgs:
+        follows: nixpkgs

data/durable-llm.gemspec

@@ -21,24 +21,32 @@ Gem::Specification.new do |spec|
   spec.metadata['changelog_uri'] = 'https://github.com/durableprogramming/durable-llm/blob/main/CHANGELOG.md'
 
   spec.files = Dir.chdir(__dir__) do
-    `git ls-files -z`.split("\x0").reject do |f|
-      (File.expand_path(f) == __FILE__) || f.start_with?(*%w[bin/ test/ spec/ features/ .git .circleci appveyor])
+    if system('git rev-parse --git-dir > /dev/null 2>&1')
+      `git ls-files -z`.split("\x0").reject do |f|
+        (File.expand_path(f) == __FILE__) || f.start_with?(*%w[bin/ test/ spec/ features/ .git .circleci appveyor])
+      end
+    else
+      Dir.glob('**/*', File::FNM_DOTMATCH).reject do |f|
+        File.directory?(f) || (File.expand_path(f) == __FILE__) || f.start_with?(*%w[bin/ test/ spec/ features/ .git .circleci appveyor])
+      end
     end
   end
   spec.bindir = 'exe'
   spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.add_dependency 'event_stream_parser', '~> 1.0'
-  spec.add_dependency 'faraday', '> 1.0'
-  spec.add_dependency 'highline', '~> 3.1'
-  spec.add_dependency 'json', '~> 2.6'
-  spec.add_dependency 'thor', '~> 1.3'
-  spec.add_dependency 'zeitwerk', '~> 2.6'
+  spec.add_dependency 'event_stream_parser', '~> 1.0', '>= 1.0.0'
+  spec.add_dependency 'faraday', '>= 1.0', '< 3.0'
+  spec.add_dependency 'highline', '~> 3.1', '>= 3.1.0'
+  spec.add_dependency 'json', '~> 2.6', '>= 2.6.0'
+  spec.add_dependency 'ostruct', '~> 0.6.0'
+  spec.add_dependency 'thor', '~> 1.3', '>= 1.3.0'
+  spec.add_dependency 'zeitwerk', '~> 2.6', '>= 2.6.0'
 
   spec.add_development_dependency 'dotenv', '~> 2.8'
   spec.add_development_dependency 'minitest', '~> 5.0'
   spec.add_development_dependency 'mocha', '~> 2.1'
   spec.add_development_dependency 'rubocop', '~> 1.0'
   spec.add_development_dependency 'vcr', '~> 6.0'
+  spec.add_development_dependency 'yard', '~> 0.9'
 end

data/examples/openai_quick_complete.rb

@@ -5,6 +5,6 @@ require 'durable/llm/client'
 
 client = Durable::Llm::Client.new(:openai, model: 'gpt-4')
 
-response = client.quick_complete("What's the capital of California?")
+response = client.complete("What's the capital of California?")
 
 puts response

data/lib/durable/llm/cli.rb

@@ -13,6 +13,9 @@ require 'durable/llm/providers'
 
 module Durable
   module Llm
+    # Command-line interface for Durable LLM gem.
+    #
+    # Provides Thor-based CLI commands for interacting with LLM providers.
     class CLI < Thor
       def self.exit_on_failure?
         true
@@ -21,35 +24,35 @@ module Durable
       CONVERSATIONS_DIR = File.expand_path('~/.durable_llm/conversations')
       LAST_CONVERSATION_FILE = File.join(CONVERSATIONS_DIR, 'last_conversation.txt')
 
-      def conversation_file_path(id)
-        File.join(CONVERSATIONS_DIR, "#{id}.json")
-      end
+      no_commands do
+        def conversation_file_path(id)
+          File.join(CONVERSATIONS_DIR, "#{id}.json")
+        end
 
-      def load_conversation(id)
-        path = conversation_file_path(id)
-        return nil unless File.exist?(path)
+        def load_conversation(id)
+          path = conversation_file_path(id)
+          return nil unless File.exist?(path)
 
-        JSON.parse(File.read(path))
-      end
+          JSON.parse(File.read(path))
+        end
 
-      def save_conversation(conversation)
-        FileUtils.mkdir_p(CONVERSATIONS_DIR) unless Dir.exist?(CONVERSATIONS_DIR)
-        id = conversation['id'] || SecureRandom.uuid
-        conversation['id'] = id
-        conversation['updated_at'] = Time.now.iso8601
-        File.write(conversation_file_path(id), JSON.generate(conversation))
-        File.write(LAST_CONVERSATION_FILE, id)
-        id
-      end
+        def save_conversation(conversation)
+          FileUtils.mkdir_p(CONVERSATIONS_DIR) unless Dir.exist?(CONVERSATIONS_DIR)
+          id = conversation['id'] || SecureRandom.uuid
+          conversation['id'] = id
+          conversation['updated_at'] = Time.now.iso8601
+          File.write(conversation_file_path(id), JSON.generate(conversation))
+          File.write(LAST_CONVERSATION_FILE, id)
+          id
+        end
 
-      def last_conversation_id
-        return nil unless File.exist?(LAST_CONVERSATION_FILE)
+        def last_conversation_id
+          return nil unless File.exist?(LAST_CONVERSATION_FILE)
 
-        File.read(LAST_CONVERSATION_FILE).strip
+          File.read(LAST_CONVERSATION_FILE).strip
+        end
       end
 
-      private :load_conversation, :save_conversation
-
       # Run a single prompt and get a response
       #
       # @param prompt [Array<String>] The prompt text to send to the model

data/lib/durable/llm/client.rb

@@ -33,8 +33,19 @@ module Durable
       # @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 = {})
+        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.provider_class_for(provider_name)
@@ -49,70 +60,143 @@ module Durable
         @model ? { model: @model } : {}
       end
 
-      # Performs a quick text completion with minimal configuration
+      # 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
-      def quick_complete(text, _opts = {})
+      # @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 }]))
 
         choice = response.choices.first
-        raise IndexError, 'No completion choices returned' unless choice
+        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
-        raise NoMethodError, 'Response choice has no message' unless 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
-        raise NoMethodError, 'Response message has no content' unless 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 = {})
+        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 = {})
+        raise ArgumentError, 'params must be a Hash' unless params.is_a?(Hash)
+
         @provider.embedding(**process_params(params))
       rescue NotImplementedError
-        raise NotImplementedError, "#{@provider.class.name} does not support embeddings"
+        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
-        raise NotImplementedError, "#{@provider.class.name} does not support streaming"
+        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
@@ -122,10 +206,67 @@ module Durable
         @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

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.