durable-llm 0.1.3 → 0.1.5

data/lib/durable/llm/cli.rb

@@ -1,7 +1,15 @@
+# frozen_string_literal: true
+
+# This file implements the command-line interface for the Durable LLM gem using Thor, providing commands for single prompts, interactive chat sessions, and listing available models. It handles provider resolution, streaming responses, model options, system prompts, and conversation management through a user-friendly CLI with support for both one-shot completions and multi-turn conversations.
+
 require 'thor'
-require 'durable/llm'
-require 'durable/llm/client'
 require 'highline'
+require 'json'
+require 'securerandom'
+require 'fileutils'
+require 'time'
+require 'durable/llm/client'
+require 'durable/llm/providers'
 
 module Durable
   module Llm
@@ -10,29 +18,72 @@ module Durable
         true
       end
 
-      desc "prompt PROMPT", "Run a prompt"
-      option :model, aliases: "-m", desc: "Specify the model to use"
-      option :system, aliases: "-s", desc: "Set a system prompt"
-      option :continue, aliases: "-c", type: :boolean, desc: "Continue the previous conversation"
-      option :conversation, aliases: "--cid", desc: "Continue a specific conversation by ID"
-      option :no_stream, type: :boolean, desc: "Disable streaming of tokens"
-      option :option, aliases: "-o", type: :hash, desc: "Set model-specific options"
-
-      def prompt(prompt)
-        config = Durable::Llm.configuration
-        model = options[:model] || "gpt-3.5-turbo"
+      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
+
+      def load_conversation(id)
+        path = conversation_file_path(id)
+        return nil unless File.exist?(path)
+
+        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 last_conversation_id
+        return nil unless File.exist?(LAST_CONVERSATION_FILE)
+
+        File.read(LAST_CONVERSATION_FILE).strip
+      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
+      # @option options :model [String] The model to use (default: gpt-3.5-turbo)
+      # @option options :system [String] System prompt to set context
+      # @option options :continue [Boolean] Continue the last conversation
+      # @option options :conversation [String] Continue a specific conversation by ID
+      # @option options :no_stream [Boolean] Disable streaming responses
+      # @option options :option [Hash] Additional model-specific options
+      # @return [void] Outputs the response to stdout
+      # @raise [RuntimeError] If no provider is found for the specified model
+      desc 'prompt PROMPT', 'Run a prompt'
+      option :model, aliases: '-m', desc: 'Specify the model to use'
+      option :system, aliases: '-s', desc: 'Set a system prompt'
+      option :continue, aliases: '-c', type: :boolean, desc: 'Continue the previous conversation'
+      option :conversation, aliases: '--cid', desc: 'Continue a specific conversation by ID'
+      option :no_stream, type: :boolean, desc: 'Disable streaming of tokens'
+      option :option, aliases: '-o', type: :hash, desc: 'Set model-specific options'
+
+      def prompt(*prompt)
+        model = options[:model] || 'gpt-3.5-turbo'
         provider_class = Durable::Llm::Providers.model_id_to_provider(model)
 
-        if provider_class.nil? 
-          raise "no provider found for model '#{model}'"
-        end
+        raise "no provider found for model '#{model}'" if provider_class.nil?
 
         provider_name = provider_class.name.split('::').last.downcase.to_sym
         client = Durable::Llm::Client.new(provider_name)
-        
-        messages = []
-        messages << { role: "system", content: options[:system] } if options[:system]
-        messages << { role: "user", content: prompt }
+
+        conversation_id = options[:conversation] || (options[:continue] ? last_conversation_id : nil)
+        conversation = conversation_id ? load_conversation(conversation_id) : nil
+
+        messages = conversation ? conversation['messages'].dup : []
+        messages << { role: 'system', content: options[:system] } if options[:system] && !conversation
+        messages << { role: 'user', content: prompt.join(' ') }
 
         params = {
           model: model,
@@ -40,37 +91,70 @@ module Durable
         }
         params.merge!(options[:option]) if options[:option]
 
-        if options[:no_stream] 
-          response = client.completion(params)
-          puts response.choices.first.to_s
-        else
-          client.stream(params) do |chunk|
-            print chunk.to_s
-            $stdout.flush
+        begin
+          if options[:no_stream] || !client.stream?
+            response = client.completion(**params)
+            assistant_message = response.choices.first.to_s
+            puts assistant_message
+            messages << { role: 'assistant', content: assistant_message }
+          else
+            assistant_content = ''
+            client.stream(**params) do |chunk|
+              print chunk
+              assistant_content += chunk
+              $stdout.flush
+            end
+            messages << { role: 'assistant', content: assistant_content }
           end
+
+          # Save conversation
+          conversation_data = {
+            'id' => conversation_id,
+            'model' => model,
+            'messages' => messages,
+            'created_at' => conversation ? conversation['created_at'] : Time.now.iso8601
+          }
+          save_conversation(conversation_data)
+        rescue Durable::Llm::Error => e
+          warn "API Error: #{e.message}"
+          exit 1
+        rescue StandardError => e
+          warn "Unexpected error: #{e.message}"
+          exit 1
         end
       end
 
-      desc "chat", "Start an interactive chat"
-      option :model, aliases: "-m", desc: "Specify the model to use"
-      option :system, aliases: "-s", desc: "Set a system prompt"
-      option :continue, aliases: "-c", type: :boolean, desc: "Continue the previous conversation"
-      option :conversation, aliases: "--cid", desc: "Continue a specific conversation by ID"
-      option :option, aliases: "-o", type: :hash, desc: "Set model-specific options"
+      # Start an interactive chat session with the model
+      #
+      # @option options :model [String] The model to use (default: gpt-3.5-turbo)
+      # @option options :system [String] System prompt to set context
+      # @option options :continue [Boolean] Continue the last conversation
+      # @option options :conversation [String] Continue a specific conversation by ID
+      # @option options :no_stream [Boolean] Disable streaming responses
+      # @option options :option [Hash] Additional model-specific options
+      # @return [void] Starts interactive chat session
+      # @raise [RuntimeError] If no provider is found for the specified model
+      desc 'chat', 'Start an interactive chat'
+      option :model, aliases: '-m', desc: 'Specify the model to use'
+      option :system, aliases: '-s', desc: 'Set a system prompt'
+      option :continue, aliases: '-c', type: :boolean, desc: 'Continue the previous conversation'
+      option :conversation, aliases: '--cid', desc: 'Continue a specific conversation by ID'
+      option :no_stream, type: :boolean, desc: 'Disable streaming of tokens'
+      option :option, aliases: '-o', type: :hash, desc: 'Set model-specific options'
       def chat
-        config = Durable::Llm.configuration
-        model = options[:model] || "gpt-3.5-turbo"
+        model = options[:model] || 'gpt-3.5-turbo'
         provider_class = Durable::Llm::Providers.model_id_to_provider(model)
 
-        if provider_class.nil? || provider_class.name.nil?
-          raise "no provider found for model '#{model}'"
-        end
+        raise "no provider found for model '#{model}'" if provider_class.nil? || provider_class.name.nil?
 
         provider_name = provider_class.name.split('::').last.downcase.to_sym
         client = Durable::Llm::Client.new(provider_name)
-        
-        messages = []
-        messages << { role: "system", content: options[:system] } if options[:system]
+
+        conversation_id = options[:conversation] || (options[:continue] ? last_conversation_id : nil)
+        conversation = conversation_id ? load_conversation(conversation_id) : nil
+
+        messages = conversation ? conversation['messages'].dup : []
+        messages << { role: 'system', content: options[:system] } if options[:system] && !conversation
 
         cli = HighLine.new
 
@@ -79,44 +163,147 @@ module Durable
         cli.say("Type '!multi' to enter multiple lines, then '!end' to finish")
 
         loop do
-          input = cli.ask("> ")
-          break if ['exit', 'quit'].include?(input.downcase)
+          input = cli.ask('> ')
+          break if %w[exit quit].include?(input.downcase)
 
-          if input == "!multi"
+          if input == '!multi'
             input = cli.ask("Enter multiple lines. Type '!end' to finish:") do |q|
-              q.gather = "!end"
+              q.gather = '!end'
             end
           end
 
-          messages << { role: "user", content: input }
+          messages << { role: 'user', content: input }
           params = {
             model: model,
             messages: messages
           }
           params.merge!(options[:option]) if options[:option]
 
-          response = client.completion(params)
-          cli.say(response.choices.first.to_s)
-          messages << { role: "assistant", content: response.choices.first.to_s }
+          begin
+            if options[:no_stream] || !client.stream?
+              response = client.completion(**params)
+              assistant_message = response.choices.first.to_s
+              cli.say(assistant_message)
+              messages << { role: 'assistant', content: assistant_message }
+            else
+              assistant_content = ''
+              client.stream(**params) do |chunk|
+                print chunk
+                assistant_content += chunk
+                $stdout.flush
+              end
+              puts # Add newline after streaming
+              messages << { role: 'assistant', content: assistant_content }
+            end
+
+            # Save conversation after each exchange
+            conversation_data = {
+              'id' => conversation_id,
+              'model' => model,
+              'messages' => messages,
+              'created_at' => conversation ? conversation['created_at'] : Time.now.iso8601
+            }
+            conversation_id = save_conversation(conversation_data)
+          rescue Durable::Llm::Error => e
+            cli.say("API Error: #{e.message}")
+            next
+          rescue StandardError => e
+            cli.say("Unexpected error: #{e.message}")
+            next
+          end
         end
       end
 
-      desc "models", "List available models"
-      option :options, type: :boolean, desc: "Show model options"
+      # List all available models from all providers
+      #
+      # @option options :options [Boolean] Show model-specific options for each model
+      # @return [void] Outputs available models to stdout
+      desc 'models', 'List available models'
+      option :options, type: :boolean, desc: 'Show model options'
       def models
         cli = HighLine.new
-        cli.say("Available models:")
-        
-        Durable::Llm::Providers.providers.each do |provider_name|
-          provider_class = Durable::Llm::Providers.const_get(provider_name.to_s.capitalize)
-          provider_models = provider_class.new.models
-          
-          cli.say("#{provider_name.to_s.capitalize}:")
-          provider_models.each do |model|
-            cli.say("  #{model}")
+        cli.say('Available models:')
+
+        Durable::Llm::Providers.providers.each do |provider_sym|
+          provider_class = Durable::Llm::Providers.provider_class_for(provider_sym)
+          begin
+            provider_models = provider_class.models
+            cli.say("#{provider_sym.to_s.capitalize}:")
+            provider_models.each do |model|
+              cli.say("  #{model}")
+              if options[:options]
+                provider_options = provider_class.options
+                cli.say("    Options: #{provider_options.join(', ')}")
+              end
+            end
+          rescue StandardError => e
+            cli.say("#{provider_sym.to_s.capitalize}: Error loading models - #{e.message}")
           end
         end
       end
+
+      # List all saved conversations
+      #
+      # @return [void] Outputs list of saved conversations to stdout
+      desc 'conversations', 'List saved conversations'
+      def conversations
+        cli = HighLine.new
+
+        unless Dir.exist?(CONVERSATIONS_DIR)
+          cli.say('No conversations found.')
+          return
+        end
+
+        conversation_files = Dir.glob("#{CONVERSATIONS_DIR}/*.json").sort_by { |f| File.mtime(f) }.reverse
+
+        if conversation_files.empty?
+          cli.say('No conversations found.')
+          return
+        end
+
+        cli.say('Saved conversations:')
+        cli.say('')
+
+        conversation_files.each do |file|
+          id = File.basename(file, '.json')
+          begin
+            conversation = JSON.parse(File.read(file))
+            model = conversation['model'] || 'unknown'
+            message_count = conversation['messages']&.length || 0
+            updated_at = conversation['updated_at'] ? Time.parse(conversation['updated_at']).strftime('%Y-%m-%d %H:%M') : 'unknown'
+
+            marker = id == last_conversation_id ? ' *' : ''
+            cli.say("#{id}#{marker} - #{model} (#{message_count} messages, updated #{updated_at})")
+          rescue JSON::ParserError
+            cli.say("#{id} - [corrupted conversation file]")
+          end
+        end
+
+        cli.say('')
+        cli.say('* indicates the last active conversation')
+      end
+
+      # Delete a saved conversation by ID
+      #
+      # @param id [String] The conversation ID to delete
+      # @return [void] Outputs confirmation message to stdout
+      desc 'delete_conversation ID', 'Delete a saved conversation'
+      def delete_conversation(id)
+        cli = HighLine.new
+
+        path = conversation_file_path(id)
+        if File.exist?(path)
+          File.delete(path)
+          cli.say("Deleted conversation #{id}")
+
+          # Remove from last conversation if it was the last one
+          File.delete(LAST_CONVERSATION_FILE) if last_conversation_id == id && File.exist?(LAST_CONVERSATION_FILE)
+        else
+          cli.say("Conversation #{id} not found")
+        end
+      end
     end
   end
 end
+
+# Copyright (c) 2025 Durable Programming, LLC. All rights reserved.

data/lib/durable/llm/client.rb

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