durable-llm 0.1.4 → 0.1.6

data/Rakefile

@@ -1,16 +1,26 @@
 # frozen_string_literal: true
 
-require "bundler/gem_tasks"
-require "rake/testtask"
+require 'bundler/gem_tasks'
+require 'rake/testtask'
 
 Rake::TestTask.new(:test) do |t|
-  t.libs << "test"
-  t.libs << "lib"
-  t.test_files = FileList["test/**/test_*.rb"]
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.test_files = FileList['test/**/test_*.rb']
 end
 
-require "rubocop/rake_task"
+require 'rubocop/rake_task'
 
 RuboCop::RakeTask.new
 
+begin
+  require 'yard'
+  YARD::Rake::YardocTask.new(:doc) do |t|
+    t.files = ['lib/**/*.rb']
+    t.options = ['--markup', 'markdown', '--output-dir', 'doc']
+  end
+rescue LoadError
+  # YARD not available
+end
+
 task default: %i[test rubocop]

data/devenv.lock

@@ -0,0 +1,171 @@
+{
+  "nodes": {
+    "devenv": {
+      "locked": {
+        "dir": "src/modules",
+        "lastModified": 1761922975,
+        "owner": "cachix",
+        "repo": "devenv",
+        "rev": "c9f0b47815a4895fadac87812de8a4de27e0ace1",
+        "type": "github"
+      },
+      "original": {
+        "dir": "src/modules",
+        "owner": "cachix",
+        "repo": "devenv",
+        "type": "github"
+      }
+    },
+    "flake-compat": {
+      "flake": false,
+      "locked": {
+        "lastModified": 1761588595,
+        "owner": "edolstra",
+        "repo": "flake-compat",
+        "rev": "f387cd2afec9419c8ee37694406ca490c3f34ee5",
+        "type": "github"
+      },
+      "original": {
+        "owner": "edolstra",
+        "repo": "flake-compat",
+        "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",
+        "gitignore": "gitignore",
+        "nixpkgs": [
+          "nixpkgs"
+        ]
+      },
+      "locked": {
+        "lastModified": 1760663237,
+        "owner": "cachix",
+        "repo": "git-hooks.nix",
+        "rev": "ca5b894d3e3e151ffc1db040b6ce4dcc75d31c37",
+        "type": "github"
+      },
+      "original": {
+        "owner": "cachix",
+        "repo": "git-hooks.nix",
+        "type": "github"
+      }
+    },
+    "gitignore": {
+      "inputs": {
+        "nixpkgs": [
+          "git-hooks",
+          "nixpkgs"
+        ]
+      },
+      "locked": {
+        "lastModified": 1709087332,
+        "owner": "hercules-ci",
+        "repo": "gitignore.nix",
+        "rev": "637db329424fd7e46cf4185293b9cc8c88c95394",
+        "type": "github"
+      },
+      "original": {
+        "owner": "hercules-ci",
+        "repo": "gitignore.nix",
+        "type": "github"
+      }
+    },
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1761313199,
+        "owner": "cachix",
+        "repo": "devenv-nixpkgs",
+        "rev": "d1c30452ebecfc55185ae6d1c983c09da0c274ff",
+        "type": "github"
+      },
+      "original": {
+        "owner": "cachix",
+        "ref": "rolling",
+        "repo": "devenv-nixpkgs",
+        "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",
+  "version": 7
+}

data/devenv.nix

@@ -0,0 +1,12 @@
+{ pkgs, lib, config, inputs, ... }:
+
+{
+
+  packages = [ pkgs.git ];
+
+  languages.ruby = {
+    enable = true;
+    version = "3.4.7";
+  };
+
+}

data/devenv.yaml

@@ -0,0 +1,8 @@
+inputs:
+  nixpkgs:
+    url: github:cachix/devenv-nixpkgs/rolling
+  nixpkgs-ruby:
+    url: github:bobvanderlinden/nixpkgs-ruby
+    inputs:
+      nixpkgs:
+        follows: nixpkgs

data/durable-llm.gemspec

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative 'lib/durable/llm/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'durable-llm'
+  spec.version = Durable::Llm::VERSION
+  spec.authors = ['Durable Programming Team']
+  spec.email = ['djberube@durableprogramming.com']
+
+  spec.summary = 'A Ruby gem providing access to LLM APIs from various vendors'
+  spec.description = 'Durable-LLM is a unified interface for interacting with multiple Large Language Model APIs, simplifying integration of AI capabilities into Ruby applications.'
+  spec.homepage = 'https://github.com/durableprogramming/durable-llm'
+  spec.license = 'MIT'
+  spec.required_ruby_version = '>= 2.6.0'
+
+  spec.metadata['allowed_push_host'] = 'https://rubygems.org'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/durableprogramming/durable-llm'
+  spec.metadata['changelog_uri'] = 'https://github.com/durableprogramming/durable-llm/blob/main/CHANGELOG.md'
+
+  spec.files = Dir.chdir(__dir__) do
+    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', '>= 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

@@ -1,8 +1,10 @@
+# frozen_string_literal: true
+
 require 'durable/llm'
 require 'durable/llm/client'
 
-client = Durable::Llm::Client.new(:openai, :model=> 'gpt-4')
+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

@@ -1,15 +1,69 @@
+# 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
+    # 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
       end
 
+      CONVERSATIONS_DIR = File.expand_path('~/.durable_llm/conversations')
+      LAST_CONVERSATION_FILE = File.join(CONVERSATIONS_DIR, 'last_conversation.txt')
+
+      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)
+
+          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
+      end
+
+      # 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'
@@ -27,8 +81,11 @@ module Durable
         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
         messages << { role: 'user', content: prompt.join(' ') }
 
         params = {
@@ -37,22 +94,55 @@ module Durable
         }
         params.merge!(options[:option]) if options[:option]
 
-        if options[:no_stream] || !client.stream?
-          response = client.completion(params)
-          puts response.choices.first
-        else
-          client.stream(params) do |chunk|
-            print chunk
-            $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
 
+      # 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
         model = options[:model] || 'gpt-3.5-turbo'
@@ -63,8 +153,11 @@ module Durable
         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
 
@@ -89,28 +182,131 @@ module Durable
           }
           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
 
+      # 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.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'
 
-          cli.say("#{provider_name.to_s.capitalize}:")
-          provider_models.each do |model|
-            cli.say("  #{model}")
+            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.