llm-shell 0.9.2 → 0.10.0

data/lib/llm/shell/internal/coderay/lib/coderay.rb

@@ -0,0 +1,284 @@
+# encoding: utf-8
+# Encoding.default_internal = 'UTF-8'
+
+# = CodeRay Library
+#
+# CodeRay is a Ruby library for syntax highlighting.
+#
+# I try to make CodeRay easy to use and intuitive, but at the same time fully
+# featured, complete, fast and efficient.
+# 
+# See README.
+# 
+# It consists mainly of
+# * the main engine: CodeRay (Scanners::Scanner, Tokens, Encoders::Encoder)
+# * the plugin system: PluginHost, Plugin
+# * the scanners in CodeRay::Scanners
+# * the encoders in CodeRay::Encoders
+# * the styles in CodeRay::Styles
+# 
+# Here's a fancy graphic to light up this gray docu:
+# 
+# http://cycnus.de/raindark/coderay/scheme.png
+# 
+# == Documentation
+#
+# See CodeRay, Encoders, Scanners, Tokens.
+#
+# == Usage
+#
+# Remember you need RubyGems to use CodeRay, unless you have it in your load
+# path. Run Ruby with -rubygems option if required.
+#
+# === Highlight Ruby code in a string as html
+# 
+#   require 'coderay'
+#   print CodeRay.scan('puts "Hello, world!"', :ruby).html
+#
+#   # prints something like this:
+#   puts <span class="s">&quot;Hello, world!&quot;</span>
+# 
+# 
+# === Highlight C code from a file in a html div
+# 
+#   require 'coderay'
+#   print CodeRay.scan(File.read('ruby.h'), :c).div
+#   print CodeRay.scan_file('ruby.h').html.div
+# 
+# You can include this div in your page. The used CSS styles can be printed with
+# 
+#   % coderay_stylesheet
+# 
+# === Highlight without typing too much
+# 
+# If you are one of the hasty (or lazy, or extremely curious) people, just run this file:
+# 
+#   % ruby -rubygems /path/to/coderay/coderay.rb > example.html
+# 
+# and look at the file it created in your browser.
+# 
+# = CodeRay Module
+#
+# The CodeRay module provides convenience methods for the engine.
+#
+# * The +lang+ and +format+ arguments select Scanner and Encoder to use. These are
+#   simply lower-case symbols, like <tt>:python</tt> or <tt>:html</tt>.
+# * All methods take an optional hash as last parameter, +options+, that is send to
+#   the Encoder / Scanner.
+# * Input and language are always sorted in this order: +code+, +lang+.
+#   (This is in alphabetical order, if you need a mnemonic ;)
+# 
+# You should be able to highlight everything you want just using these methods;
+# so there is no need to dive into CodeRay's deep class hierarchy.
+#
+# The examples in the demo directory demonstrate common cases using this interface.
+#  
+# = Basic Access Ways
+#
+# Read this to get a general view what CodeRay provides.
+# 
+# == Scanning
+# 
+# Scanning means analysing an input string, splitting it up into Tokens.
+# Each Token knows about what type it is: string, comment, class name, etc.
+#
+# Each +lang+ (language) has its own Scanner; for example, <tt>:ruby</tt> code is
+# handled by CodeRay::Scanners::Ruby.
+# 
+# CodeRay.scan:: Scan a string in a given language into Tokens.
+#                This is the most common method to use.
+# CodeRay.scan_file:: Scan a file and guess the language using FileType.
+# 
+# The Tokens object you get from these methods can encode itself; see Tokens.
+# 
+# == Encoding
+#
+# Encoding means compiling Tokens into an output. This can be colored HTML or
+# LaTeX, a textual statistic or just the number of non-whitespace tokens.
+# 
+# Each Encoder provides output in a specific +format+, so you select Encoders via
+# formats like <tt>:html</tt> or <tt>:statistic</tt>.
+# 
+# CodeRay.encode:: Scan and encode a string in a given language.
+# CodeRay.encode_tokens:: Encode the given tokens.
+# CodeRay.encode_file:: Scan a file, guess the language using FileType and encode it.
+#
+# == All-in-One Encoding
+#
+# CodeRay.encode:: Highlight a string with a given input and output format.
+#
+# == Instanciating
+#
+# You can use an Encoder instance to highlight multiple inputs. This way, the setup
+# for this Encoder must only be done once.
+#
+# CodeRay.encoder:: Create an Encoder instance with format and options.
+# CodeRay.scanner:: Create an Scanner instance for lang, with '' as default code.
+#
+# To make use of CodeRay.scanner, use CodeRay::Scanner::code=.
+#
+# The scanning methods provide more flexibility; we recommend to use these.
+# 
+# == Reusing Scanners and Encoders
+# 
+# If you want to re-use scanners and encoders (because that is faster), see
+# CodeRay::Duo for the most convenient (and recommended) interface.
+module CodeRay
+  
+  $CODERAY_DEBUG ||= false
+  
+  CODERAY_PATH = File.expand_path('../coderay', __FILE__)
+  
+  # Assuming the path is a subpath of lib/coderay/
+  def self.coderay_path *path
+    File.join CODERAY_PATH, *path
+  end
+  
+  autoload :VERSION, 'coderay/version'
+  
+  # helpers
+  autoload :FileType,    coderay_path('helpers', 'file_type')
+  
+  # Tokens
+  autoload :Tokens,      coderay_path('tokens')
+  autoload :TokensProxy, coderay_path('tokens_proxy')
+  autoload :TokenKinds,  coderay_path('token_kinds')
+  
+  # Plugin system
+  autoload :PluginHost,  coderay_path('helpers', 'plugin_host')
+  autoload :Plugin,      coderay_path('helpers', 'plugin')
+  
+  # Plugins
+  autoload :Scanners,    coderay_path('scanners')
+  autoload :Encoders,    coderay_path('encoders')
+  autoload :Styles,      coderay_path('styles')
+  
+  # convenience access and reusable Encoder/Scanner pair
+  autoload :Duo,         coderay_path('duo')
+  
+  class << self
+    
+    # Scans the given +code+ (a String) with the Scanner for +lang+.
+    #
+    # This is a simple way to use CodeRay. Example:
+    #  require 'coderay'
+    #  page = CodeRay.scan("puts 'Hello, world!'", :ruby).html
+    #
+    # See also demo/demo_simple.
+    def scan code, lang, options = {}, &block
+      CodeRay::TokensProxy.new code, lang, options, block
+    end
+    
+    # Scans +filename+ (a path to a code file) with the Scanner for +lang+.
+    #
+    # If +lang+ is :auto or omitted, the CodeRay::FileType module is used to
+    # determine it. If it cannot find out what type it is, it uses
+    # CodeRay::Scanners::Text.
+    #
+    # Calls CodeRay.scan.
+    #
+    # Example:
+    #  require 'coderay'
+    #  page = CodeRay.scan_file('some_c_code.c').html
+    def scan_file filename, lang = :auto, options = {}, &block
+      lang = CodeRay::FileType.fetch filename, :text, true if lang == :auto
+      code = File.read filename
+      scan code, lang, options, &block
+    end
+    
+    # Encode a string.
+    #
+    # This scans +code+ with the the Scanner for +lang+ and then
+    # encodes it with the Encoder for +format+.
+    # +options+ will be passed to the Encoder.
+    #
+    # See CodeRay::Encoder.encode.
+    def encode code, lang, format, options = {}
+      encoder(format, options).encode code, lang, options
+    end
+    
+    # Encode pre-scanned Tokens.
+    # Use this together with CodeRay.scan:
+    #
+    #  require 'coderay'
+    #  
+    #  # Highlight a short Ruby code example in a HTML span
+    #  tokens = CodeRay.scan '1 + 2', :ruby
+    #  puts CodeRay.encode_tokens(tokens, :span)
+    #
+    def encode_tokens tokens, format, options = {}
+      encoder(format, options).encode_tokens tokens, options
+    end
+    
+    # Encodes +filename+ (a path to a code file) with the Scanner for +lang+.
+    #
+    # See CodeRay.scan_file.
+    # Notice that the second argument is the output +format+, not the input language.
+    #
+    # Example:
+    #  require 'coderay'
+    #  page = CodeRay.encode_file 'some_c_code.c', :html
+    def encode_file filename, format, options = {}
+      tokens = scan_file filename, :auto, get_scanner_options(options)
+      encode_tokens tokens, format, options
+    end
+    
+    # Highlight a string into a HTML <div>.
+    #
+    # CSS styles use classes, so you have to include a stylesheet
+    # in your output.
+    #
+    # See encode.
+    def highlight code, lang, options = { :css => :class }, format = :div
+      encode code, lang, format, options
+    end
+    
+    # Highlight a file into a HTML <div>.
+    #
+    # CSS styles use classes, so you have to include a stylesheet
+    # in your output.
+    #
+    # See encode.
+    def highlight_file filename, options = { :css => :class }, format = :div
+      encode_file filename, format, options
+    end
+    
+    # Finds the Encoder class for +format+ and creates an instance, passing
+    # +options+ to it.
+    #
+    # Example:
+    #  require 'coderay'
+    #  
+    #  stats = CodeRay.encoder(:statistic)
+    #  stats.encode("puts 17 + 4\n", :ruby)
+    #  
+    #  puts '%d out of %d tokens have the kind :integer.' % [
+    #    stats.type_stats[:integer].count,
+    #    stats.real_token_count
+    #  ]
+    #  #-> 2 out of 4 tokens have the kind :integer.
+    def encoder format, options = {}
+      CodeRay::Encoders[format].new options
+    end
+    
+    # Finds the Scanner class for +lang+ and creates an instance, passing
+    # +options+ to it.
+    #
+    # See Scanner.new.
+    def scanner lang, options = {}, &block
+      CodeRay::Scanners[lang].new '', options, &block
+    end
+    
+    # Extract the options for the scanner from the +options+ hash.
+    #
+    # Returns an empty Hash if <tt>:scanner_options</tt> is not set.
+    #
+    # This is used if a method like CodeRay.encode has to provide options
+    # for Encoder _and_ scanner.
+    def get_scanner_options options
+      options.fetch :scanner_options, {}
+    end
+    
+  end
+  
+end

data/lib/llm/shell/internal/io-line/lib/io/line/multiple.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+class IO::Line::Multiple
+  def initialize(lines, cursor)
+    @lines = lines
+    @cursor = cursor
+  end
+
+  def print(*strs, lineno:)
+    line = @lines[lineno]
+    if lineno > @cursor
+      line.io.cursor_down(lineno - @cursor)
+    elsif lineno < @cursor
+      line.io.cursor_up(lineno + @cursor)
+    end
+    @cursor = lineno
+    line.rewind.print(*strs)
+  end
+end

data/lib/{io → llm/shell/internal/io-line/lib/io}/line.rb

@@ -2,7 +2,9 @@
 
 class IO::Line
   require "io/console"
+  require_relative "line/multiple"
 
+  VERSION = "0.1.0"
   attr_reader :io
 
   def initialize(io)

data/lib/llm/shell/internal/llm.rb/lib/llm/bot/builder.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+class LLM::Bot
+  ##
+  # @private
+  module Builder
+    private
+
+    ##
+    # @param [String] prompt The prompt
+    # @param [Hash] params
+    # @return [LLM::Response]
+    def create_response!(prompt, params)
+      @provider.responses.create(
+        prompt,
+        @params.merge(params.merge(@response ? {previous_response_id: @response.id} : {}))
+      )
+    end
+
+    ##
+    # @param [String] prompt The prompt
+    # @param [Hash] params
+    # @return [LLM::Response]
+    def create_completion!(prompt, params)
+      @provider.complete(
+        prompt,
+        @params.merge(params.merge(messages:))
+      )
+    end
+  end
+end

data/lib/llm/shell/internal/llm.rb/lib/llm/bot/conversable.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+class LLM::Bot
+  ##
+  # @private
+  module Conversable
+    private
+
+    ##
+    # Queues a response to be sent to the provider.
+    # @param [String] prompt The prompt
+    # @param [Hash] params
+    # @return [void]
+    def async_response(prompt, params = {})
+      if Array === prompt and prompt.empty?
+        @messages
+      else
+        role = params.delete(:role)
+        @messages << [LLM::Message.new(role, prompt), @params.merge(params), :respond]
+      end
+    end
+
+    ##
+    # Queues a completion to be sent to the provider.
+    # @param [String] prompt The prompt
+    # @param [Hash] params
+    # @return [void]
+    def async_completion(prompt, params = {})
+      if Array === prompt and prompt.empty?
+        @messages
+      else
+        role = params.delete(:role)
+        @messages << [LLM::Message.new(role, prompt), @params.merge(params), :complete]
+      end
+    end
+  end
+end

data/lib/llm/shell/internal/llm.rb/lib/llm/bot/prompt/completion.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module LLM::Bot::Prompt
+  class Completion < Struct.new(:bot, :defaults)
+    ##
+    # @param [LLM::Bot] bot
+    # @param [Hash] defaults
+    # @return [LLM::Bot::Prompt::Completion]
+    def initialize(bot, defaults)
+      super(bot, defaults || {})
+    end
+
+    ##
+    # @param [String] prompt
+    # @param [Hash] params (see LLM::Provider#complete)
+    # @return [LLM::Bot]
+    def system(prompt, params = {})
+      params = defaults.merge(params)
+      bot.chat prompt, params.merge(role: :system)
+    end
+
+    ##
+    # @param [String] prompt
+    # @param [Hash] params (see LLM::Provider#complete)
+    # @return [LLM::Bot]
+    def user(prompt, params = {})
+      params = defaults.merge(params)
+      bot.chat prompt, params.merge(role: :user)
+    end
+
+    ##
+    # @param [String] prompt
+    # @param [Hash] params (see LLM::Provider#complete)
+    # @return [LLM::Bot]
+    def assistant(prompt, params = {})
+      params = defaults.merge(params)
+      bot.chat prompt, params.merge(role: :assistant)
+    end
+
+    ##
+    # @param [String] prompt
+    # @param [Hash] params (see LLM::Provider#complete)
+    # @return [LLM::Bot]
+    def model(prompt, params = {})
+      params = defaults.merge(params)
+      bot.chat prompt, params.merge(role: :model)
+    end
+  end
+end

data/lib/llm/shell/internal/llm.rb/lib/llm/bot/prompt/respond.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module LLM::Bot::Prompt
+  class Respond < Struct.new(:bot, :defaults)
+    ##
+    # @param [LLM::Bot] bot
+    # @param [Hash] defaults
+    # @return [LLM::Bot::Prompt::Completion]
+    def initialize(bot, defaults)
+      super(bot, defaults || {})
+    end
+
+    ##
+    # @param [String] prompt
+    # @param [Hash] params (see LLM::Provider#complete)
+    # @return [LLM::Bot]
+    def system(prompt, params = {})
+      params = defaults.merge(params)
+      bot.respond prompt, params.merge(role: :system)
+    end
+
+    ##
+    # @param [String] prompt
+    # @param [Hash] params (see LLM::Provider#complete)
+    # @return [LLM::Bot]
+    def developer(prompt, params = {})
+      params = defaults.merge(params)
+      bot.respond prompt, params.merge(role: :developer)
+    end
+
+    ##
+    # @param [String] prompt
+    # @param [Hash] params (see LLM::Provider#complete)
+    # @return [LLM::Bot]
+    def user(prompt, params = {})
+      params = defaults.merge(params)
+      bot.respond prompt, params.merge(role: :user)
+    end
+
+    ##
+    # @param [String] prompt
+    # @param [Hash] params (see LLM::Provider#complete)
+    # @return [LLM::Bot]
+    def assistant(prompt, params = {})
+      params = defaults.merge(params)
+      bot.chat prompt, params.merge(role: :assistant)
+    end
+  end
+end

data/lib/llm/shell/internal/llm.rb/lib/llm/bot.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module LLM
+  ##
+  # {LLM::Bot LLM::Bot} provides an object that can maintain a
+  # conversation. A conversation can use the chat completions API
+  # that all LLM providers support or the responses API that currently
+  # only OpenAI supports.
+  #
+  # @example
+  #   #!/usr/bin/env ruby
+  #   require "llm"
+  #
+  #   llm  = LLM.openai(key: ENV["KEY"])
+  #   bot  = LLM::Bot.new(llm)
+  #   url  = "https://en.wikipedia.org/wiki/Special:FilePath/Cognac_glass.jpg"
+  #   msgs = bot.chat do |prompt|
+  #     prompt.system "Your task is to answer all user queries"
+  #     prompt.user ["Tell me about this URL", URI(url)]
+  #     prompt.user ["Tell me about this PDF", File.open("handbook.pdf", "rb")]
+  #     prompt.user "Are the URL and PDF similar to each other?"
+  #   end
+  #
+  #   # At this point, we execute a single request
+  #   msgs.each { print "[#{_1.role}] ", _1.content, "\n" }
+  class Bot
+    require_relative "bot/prompt/completion"
+    require_relative "bot/prompt/respond"
+    require_relative "bot/conversable"
+    require_relative "bot/builder"
+
+    include Conversable
+    include Builder
+
+    ##
+    # Returns an Enumerable for the messages in a conversation
+    # @return [LLM::Buffer<LLM::Message>]
+    attr_reader :messages
+
+    ##
+    # @param [LLM::Provider] provider
+    #  A provider
+    # @param [Hash] params
+    #  The parameters to maintain throughout the conversation.
+    #  Any parameter the provider supports can be included and
+    #  not only those listed here.
+    # @option params [String] :model Defaults to the provider's default model
+    # @option params [#to_json, nil] :schema Defaults to nil
+    # @option params [Array<LLM::Function>, nil] :tools Defaults to nil
+    def initialize(provider, params = {})
+      @provider = provider
+      @params = {model: provider.default_model, schema: nil}.compact.merge!(params)
+      @messages = LLM::Buffer.new(provider)
+    end
+
+    ##
+    # Maintain a conversation via the chat completions API
+    # @overload def chat(prompt, params = {})
+    #   @param prompt (see LLM::Provider#complete)
+    #   @param params The params
+    #   @return [LLM::Bot]
+    #     Returns self
+    # @overload def chat(prompt, params, &block)
+    #   @param prompt (see LLM::Provider#complete)
+    #   @param params The params
+    #   @yield prompt Yields a prompt
+    #   @return [LLM::Buffer]
+    #     Returns messages
+    def chat(prompt = nil, params = {})
+      if block_given?
+        params = prompt
+        yield Prompt::Completion.new(self, params)
+        messages
+      elsif prompt.nil?
+        raise ArgumentError, "wrong number of arguments (given 0, expected 1)"
+      else
+        params = {role: :user}.merge!(params)
+        tap { async_completion(prompt, params) }
+      end
+    end
+
+    ##
+    # Maintain a conversation via the responses API
+    # @overload def respond(prompt, params = {})
+    #   @param prompt (see LLM::Provider#complete)
+    #   @param params The params
+    #   @return [LLM::Bot]
+    #     Returns self
+    # @overload def respond(prompt, params, &block)
+    #   @note Not all LLM providers support this API
+    #   @param prompt (see LLM::Provider#complete)
+    #   @param params The params
+    #   @yield prompt Yields a prompt
+    #   @return [LLM::Buffer]
+    #     Returns messages
+    def respond(prompt = nil, params = {})
+      if block_given?
+        params = prompt
+        yield Prompt::Respond.new(self, params)
+        messages
+      elsif prompt.nil?
+        raise ArgumentError, "wrong number of arguments (given 0, expected 1)"
+      else
+        params = {role: :user}.merge!(params)
+        tap { async_response(prompt, params) }
+      end
+    end
+
+    ##
+    # @return [String]
+    def inspect
+      "#<#{self.class.name}:0x#{object_id.to_s(16)} " \
+      "@provider=#{@provider.class}, @params=#{@params.inspect}, " \
+      "@messages=#{@messages.inspect}>"
+    end
+
+    ##
+    # Returns an array of functions that can be called
+    # @return [Array<LLM::Function>]
+    def functions
+      messages
+        .select(&:assistant?)
+        .flat_map(&:functions)
+        .select(&:pending?)
+    end
+
+    ##
+    # @example
+    #   llm = LLM.openai(key: ENV["KEY"])
+    #   bot = LLM::Bot.new(llm, stream: $stdout)
+    #   bot.chat("Hello", role: :user).flush
+    # Drains the buffer and returns all messages as an array
+    # @return [Array<LLM::Message>]
+    def drain
+      messages.drain
+    end
+    alias_method :flush, :drain
+
+    ##
+    # Returns token usage for the conversation
+    # @note
+    # This method returns token usage for the latest
+    # assistant message, and it returns an empty object
+    # if there are no assistant messages
+    # @return [LLM::Object]
+    def usage
+      messages.find(&:assistant?)&.usage || LLM::Object.from_hash({})
+    end
+  end
+end