llm-shell 0.9.2 → 0.10.0

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

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+##
+# The {LLM::Function LLM::Function} class represents a local
+# function that can be called by an LLM.
+#
+# @example example #1
+#   LLM.function(:system) do |fn|
+#     fn.name "system"
+#     fn.description "Runs system commands"
+#     fn.params do |schema|
+#       schema.object(command: schema.string.required)
+#     end
+#     fn.define do |command:|
+#       {success: Kernel.system(command)}
+#     end
+#   end
+#
+# @example example #2
+#   class System < LLM::Tool
+#     name "system"
+#     description "Runs system commands"
+#     params do |schema|
+#       schema.object(command: schema.string.required)
+#     end
+#
+#     def call(command:)
+#       {success: Kernel.system(command)}
+#     end
+#   end
+class LLM::Function
+  class Return < Struct.new(:id, :name, :value)
+  end
+
+  ##
+  # Returns the function ID
+  # @return [String, nil]
+  attr_accessor :id
+
+  ##
+  # Returns function arguments
+  # @return [Array, nil]
+  attr_accessor :arguments
+
+  ##
+  # @param [String] name The function name
+  # @yieldparam [LLM::Function] self The function object
+  def initialize(name, &b)
+    @name = name
+    @schema = LLM::Schema.new
+    @called = false
+    @cancelled = false
+    yield(self) if block_given?
+  end
+
+  ##
+  # Set (or get) the function name
+  # @param [String] name The function name
+  # @return [void]
+  def name(name = nil)
+    if name
+      @name = name.to_s
+    else
+      @name
+    end
+  end
+
+  ##
+  # Set (or get) the function description
+  # @param [String] desc The function description
+  # @return [void]
+  def description(desc = nil)
+    if desc
+      @description = desc
+    else
+      @description
+    end
+  end
+
+  ##
+  # Set (or get) the function parameters
+  # @yieldparam [LLM::Schema] schema The schema object
+  # @return [void]
+  def params
+    if block_given?
+      if @params
+        @params.merge!(yield(@schema))
+      else
+        @params = yield(@schema)
+      end
+    else
+      @params
+    end
+  end
+
+  ##
+  # Set the function implementation
+  # @param [Proc, Class] b The function implementation
+  # @return [void]
+  def define(klass = nil, &b)
+    @runner = klass || b
+  end
+  alias_method :register, :define
+
+  ##
+  # Call the function
+  # @return [LLM::Function::Return] The result of the function call
+  def call
+    runner = ((Class === @runner) ? @runner.new : @runner)
+    Return.new(id, name, runner.call(**arguments))
+  ensure
+    @called = true
+  end
+
+  ##
+  # Returns a value that communicates that the function call was cancelled
+  # @example
+  #   llm = LLM.openai(key: ENV["KEY"])
+  #   bot = LLM::Bot.new(llm, tools: [fn1, fn2])
+  #   bot.chat "I want to run the functions"
+  #   bot.chat bot.functions.map(&:cancel)
+  # @return [LLM::Function::Return]
+  def cancel(reason: "function call cancelled")
+    Return.new(id, name, {cancelled: true, reason:})
+  ensure
+    @cancelled = true
+  end
+
+  ##
+  # Returns true when a function has been called
+  # @return [Boolean]
+  def called?
+    @called
+  end
+
+  ##
+  # Returns true when a function has been cancelled
+  # @return [Boolean]
+  def cancelled?
+    @cancelled
+  end
+
+  ##
+  # Returns true when a function has neither been called nor cancelled
+  # @return [Boolean]
+  def pending?
+    !@called && !@cancelled
+  end
+
+  ##
+  # @return [Hash]
+  def format(provider)
+    case provider.class.to_s
+    when "LLM::Gemini"
+      {name: @name, description: @description, parameters: @params}.compact
+    when "LLM::Anthropic"
+      {name: @name, description: @description, input_schema: @params}.compact
+    else
+      format_openai(provider)
+    end
+  end
+
+  def format_openai(provider)
+    case provider.class.to_s
+    when "LLM::OpenAI::Responses"
+      {
+        type: "function", name: @name, description: @description,
+        parameters: @params.to_h.merge(additionalProperties: false), strict: true
+      }.compact
+    else
+      {
+        type: "function", name: @name,
+        function: {name: @name, description: @description, parameters: @params}
+      }.compact
+    end
+  end
+end

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

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+module LLM
+  class Message
+    ##
+    # Returns the role of the message
+    # @return [Symbol]
+    attr_reader :role
+
+    ##
+    # Returns the content of the message
+    # @return [String]
+    attr_reader :content
+
+    ##
+    # Returns extra context associated with the message
+    # @return [Hash]
+    attr_reader :extra
+
+    ##
+    # Returns a new message
+    # @param [Symbol] role
+    # @param [String] content
+    # @param [Hash] extra
+    # @return [LLM::Message]
+    def initialize(role, content, extra = {})
+      @role = role.to_s
+      @content = content
+      @extra = extra
+    end
+
+    ##
+    # Returns a hash representation of the message
+    # @return [Hash]
+    def to_h
+      {role:, content:}
+    end
+
+    ##
+    # Returns true when two objects have the same role and content
+    # @param [Object] other
+    #  The other object to compare
+    # @return [Boolean]
+    def ==(other)
+      if other.respond_to?(:to_h)
+        to_h == other.to_h
+      else
+        false
+      end
+    end
+    alias_method :eql?, :==
+
+    ##
+    # Try to parse the content as JSON
+    # @return [Hash]
+    def content!
+      JSON.parse(content)
+    end
+
+    ##
+    # @return [Array<LLM::Function>]
+    def functions
+      @functions ||= tool_calls.map do |fn|
+        function = tools.find { _1.name.to_s == fn["name"] }.dup
+        function.tap { _1.id = fn.id }
+        function.tap { _1.arguments = fn.arguments }
+      end
+    end
+
+    ##
+    # Marks the message as read
+    # @return [void]
+    def read!
+      @read = true
+    end
+
+    ##
+    # Returns true when the message has been read
+    # @return [Boolean]
+    def read?
+      @read
+    end
+
+    ##
+    # Returns true when the message is an assistant message
+    # @return [Boolean]
+    def assistant?
+      role == "assistant" || role == "model"
+    end
+
+    ##
+    # Returns true when the message is a system message
+    # @return [Boolean]
+    def system?
+      role == "system"
+    end
+
+    ##
+    # Returns true when the message is a user message
+    # @return [Boolean]
+    def user?
+      role == "user"
+    end
+
+    ##
+    # @return [Boolean]
+    #  Returns true when the message requests a function call
+    def tool_call?
+      tool_calls.any?
+    end
+
+    ##
+    # @return [Boolean]
+    #  Returns true when the message represents a function return
+    def tool_return?
+      LLM::Function::Return === content ||
+        [*content].grep(LLM::Function::Return).any?
+    end
+
+    ##
+    # @note
+    #  This method returns a response for assistant messages,
+    #  and it returns nil for non-assistant messages
+    # @return [LLM::Response, nil]
+    #  Returns the response associated with the message, or nil
+    def response
+      extra[:response]
+    end
+
+    ##
+    # @note
+    #  This method might return annotations for assistant messages,
+    #  and it returns an empty array for non-assistant messages
+    # Returns annotations associated with the message
+    # @return [Array<LLM::Object>]
+    def annotations
+      @annotations ||= LLM::Object.from_hash(extra["annotations"] || [])
+    end
+
+    ##
+    # @note
+    #  This method returns token usage for assistant messages,
+    #  and it returns an empty object for non-assistant messages
+    # Returns token usage statistics
+    # @return [LLM::Object]
+    def usage
+      @usage ||= if response
+        LLM::Object.from_hash({
+          input_tokens: response.prompt_tokens || 0,
+          output_tokens: response.completion_tokens || 0,
+          total_tokens: response.total_tokens || 0
+        })
+      else
+        LLM::Object.from_hash({})
+      end
+    end
+    alias_method :token_usage, :usage
+
+    ##
+    # Returns a string representation of the message
+    # @return [String]
+    def inspect
+      "#<#{self.class.name}:0x#{object_id.to_s(16)} " \
+      "tool_call=#{tool_calls.any?} role=#{role.inspect} " \
+      "content=#{content.inspect}>"
+    end
+
+    private
+
+    def tool_calls
+      @tool_calls ||= LLM::Object.from_hash(@extra[:tool_calls] || [])
+    end
+
+    def tools
+      response&.__tools__ || []
+    end
+  end
+end

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

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+##
+# @private
+class LLM::Mime
+  EXTNAME = /\A\.[a-zA-Z0-9]+\z/
+  private_constant :EXTNAME
+
+  ##
+  # Lookup a mime type
+  # @return [String, nil]
+  def self.[](key)
+    key = key.respond_to?(:path) ? key.path : key
+    extname = (key =~ EXTNAME) ? key : File.extname(key)
+    types[extname] || "application/octet-stream"
+  end
+
+  ##
+  # Returns a Hash of mime types
+  # @return [Hash]
+  def self.types
+    @types ||= {
+      # Images
+      ".png" => "image/png",
+      ".jpg" => "image/jpeg",
+      ".jpeg" => "image/jpeg",
+      ".webp" => "image/webp",
+      ".gif" => "image/gif",
+      ".bmp" => "image/bmp",
+      ".tif" => "image/tiff",
+      ".tiff" => "image/tiff",
+      ".svg" => "image/svg+xml",
+      ".ico" => "image/x-icon",
+      ".apng" => "image/apng",
+      ".jfif" => "image/jpeg",
+      ".heic" => "image/heic",
+
+      # Videos
+      ".flv" => "video/x-flv",
+      ".mov" => "video/quicktime",
+      ".mpeg" => "video/mpeg",
+      ".mpg" => "video/mpeg",
+      ".mp4" => "video/mp4",
+      ".webm" => "video/webm",
+      ".wmv" => "video/x-ms-wmv",
+      ".3gp" => "video/3gpp",
+      ".avi" => "video/x-msvideo",
+      ".mkv" => "video/x-matroska",
+      ".ogv" => "video/ogg",
+      ".m4v" => "video/x-m4v",
+      ".m2ts" => "video/mp2t",
+      ".mts" => "video/mp2t",
+
+      # Audio
+      ".aac" => "audio/aac",
+      ".flac" => "audio/flac",
+      ".mp3" => "audio/mpeg",
+      ".m4a" => "audio/mp4",
+      ".mpga" => "audio/mpeg",
+      ".opus" => "audio/opus",
+      ".pcm" => "audio/L16",
+      ".wav" => "audio/wav",
+      ".weba" => "audio/webm",
+      ".oga" => "audio/ogg",
+      ".ogg" => "audio/ogg",
+      ".mid" => "audio/midi",
+      ".midi" => "audio/midi",
+      ".aiff" => "audio/aiff",
+      ".aif" => "audio/aiff",
+      ".amr" => "audio/amr",
+      ".mka" => "audio/x-matroska",
+      ".caf" => "audio/x-caf",
+
+      # Documents
+      ".pdf" => "application/pdf",
+      ".txt" => "text/plain",
+      ".md" => "text/markdown",
+      ".markdown" => "text/markdown",
+      ".mkd" => "text/markdown",
+      ".doc" => "application/msword",
+      ".docx" => "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+      ".xls" => "application/vnd.ms-excel",
+      ".xlsx" => "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+      ".ppt" => "application/vnd.ms-powerpoint",
+      ".pptx" => "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+      ".csv" => "text/csv",
+      ".json" => "application/json",
+      ".xml" => "application/xml",
+      ".html" => "text/html",
+      ".htm" => "text/html",
+      ".odt" => "application/vnd.oasis.opendocument.text",
+      ".odp" => "application/vnd.oasis.opendocument.presentation",
+      ".ods" => "application/vnd.oasis.opendocument.spreadsheet",
+      ".rtf" => "application/rtf",
+      ".epub" => "application/epub+zip",
+
+      # Code
+      ".js" => "application/javascript",
+      ".jsx" => "text/jsx",
+      ".ts" => "application/typescript",
+      ".tsx" => "text/tsx",
+      ".css" => "text/css",
+      ".c" => "text/x-c",
+      ".cpp" => "text/x-c++",
+      ".h" => "text/x-c",
+      ".rb" => "text/x-ruby",
+      ".py" => "text/x-python",
+      ".java" => "text/x-java-source",
+      ".sh" => "application/x-sh",
+      ".php" => "application/x-httpd-php",
+      ".yml" => "text/yaml",
+      ".yaml" => "text/yaml",
+      ".go" => "text/x-go",
+      ".rs" => "text/rust",
+
+      # Fonts
+      ".woff" => "font/woff",
+      ".woff2" => "font/woff2",
+      ".ttf" => "font/ttf",
+      ".otf" => "font/otf",
+
+      # Archives
+      ".zip" => "application/zip",
+      ".tar" => "application/x-tar",
+      ".gz" => "application/gzip",
+      ".bz2" => "application/x-bzip2",
+      ".xz" => "application/x-xz",
+      ".rar" => "application/vnd.rar",
+      ".7z" => "application/x-7z-compressed",
+      ".tar.gz" => "application/gzip",
+      ".tar.bz2" => "application/x-bzip2",
+      ".apk" => "application/vnd.android.package-archive",
+      ".exe" => "application/x-msdownload",
+
+      # Others
+      ".ics" => "text/calendar",
+      ".vcf" => "text/vcard"
+    }
+  end
+end

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

@@ -0,0 +1,101 @@
+# encoding: ascii-8bit
+# frozen_string_literal: true
+
+##
+# @private
+class LLM::Multipart
+  require "securerandom"
+
+  ##
+  # @return [String]
+  attr_reader :boundary
+
+  ##
+  # @param [Hash] params
+  #  Request parameters
+  # @return [LLM::Multipart]
+  def initialize(params)
+    @boundary = "BOUNDARY__#{SecureRandom.hex(16)}"
+    @params = params
+  end
+
+  ##
+  # Returns the multipart content type
+  # @return [String]
+  def content_type
+    "multipart/form-data; boundary=#{@boundary}"
+  end
+
+  ##
+  # Returns the multipart request body
+  # @return [String]
+  def body
+    io = StringIO.new("".b)
+    [*parts, StringIO.new("--#{@boundary}--\r\n".b)].each { IO.copy_stream(_1.tap(&:rewind), io) }
+    io.tap(&:rewind)
+  end
+
+  private
+
+  attr_reader :params
+
+  def file(locals, file)
+    locals = locals.merge(attributes(file))
+    build_file(locals) do |body|
+      IO.copy_stream(file.path, body)
+      body << "\r\n"
+    end
+  end
+
+  def form(locals, value)
+    locals = locals.merge(value:)
+    build_form(locals) do |body|
+      body << value.to_s
+      body << "\r\n"
+    end
+  end
+
+  def build_file(locals)
+    StringIO.new("".b).tap do |io|
+      io << "--#{locals[:boundary]}" \
+             "\r\n" \
+             "Content-Disposition: form-data; name=\"#{locals[:key]}\";" \
+             "filename=\"#{locals[:filename]}\"" \
+             "\r\n" \
+             "Content-Type: #{locals[:content_type]}" \
+             "\r\n\r\n"
+      yield(io)
+    end
+  end
+
+  def build_form(locals)
+    StringIO.new("".b).tap do |io|
+      io << "--#{locals[:boundary]}" \
+             "\r\n" \
+             "Content-Disposition: form-data; name=\"#{locals[:key]}\"" \
+             "\r\n\r\n"
+      yield(io)
+    end
+  end
+
+  ##
+  # Returns the multipart request body parts
+  # @return [Array<String>]
+  def parts
+    params.map do |key, value|
+      locals = {key: key.to_s.b, boundary: boundary.to_s.b}
+      if value.respond_to?(:path)
+        file(locals, value)
+      else
+        form(locals, value)
+      end
+    end
+  end
+
+  def attributes(file)
+    {
+      filename: File.basename(file.path).b,
+      content_type: LLM::Mime[file].b
+    }
+  end
+end

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+class LLM::Object
+  ##
+  # @private
+  module Builder
+    ##
+    # @example
+    #   obj = LLM::Object.from_hash(person: {name: 'John'})
+    #   obj.person.name  # => 'John'
+    #   obj.person.class # => LLM::Object
+    # @param [Hash, LLM::Object, Array] obj
+    #   A Hash object
+    # @return [LLM::Object]
+    #   An LLM::Object object initialized by visiting `obj` with recursion
+    def from_hash(obj)
+      case obj
+      when self then from_hash(obj.to_h)
+      when Array then obj.map { |v| from_hash(v) }
+      else
+        visited = {}
+        obj.each { visited[_1] = visit(_2) }
+        new(visited)
+      end
+    end
+
+    private
+
+    def visit(value)
+      case value
+      when self then from_hash(value.to_h)
+      when Hash then from_hash(value)
+      when Array then value.map { |v| visit(v) }
+      else value
+      end
+    end
+  end
+end

data/lib/llm/shell/internal/llm.rb/lib/llm/object/kernel.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+class LLM::Object
+  ##
+  # @private
+  module Kernel
+    def tap(...)
+      ::Kernel.instance_method(:tap).bind(self).call(...)
+    end
+
+    def instance_of?(...)
+      ::Kernel.instance_method(:instance_of?).bind(self).call(...)
+    end
+
+    def extend(...)
+      ::Kernel.instance_method(:extend).bind(self).call(...)
+    end
+
+    def method(...)
+      ::Kernel.instance_method(:method).bind(self).call(...)
+    end
+
+    def kind_of?(...)
+      ::Kernel.instance_method(:kind_of?).bind(self).call(...)
+    end
+    alias_method :is_a?, :kind_of?
+
+    def respond_to?(m, include_private = false)
+      @h.key?(m.to_sym) || self.class.instance_methods.include?(m) || super
+    end
+
+    def respond_to_missing?(m, include_private = false)
+      @h.key?(m.to_sym) || super
+    end
+
+    def object_id
+      ::Kernel.instance_method(:object_id).bind(self).call
+    end
+
+    def class
+      ::Kernel.instance_method(:class).bind(self).call
+    end
+
+    def inspect
+      "#<#{self.class}:0x#{object_id.to_s(16)} properties=#{to_h.inspect}>"
+    end
+    alias_method :to_s, :inspect
+
+    def pretty_print(q)
+      q.text(inspect)
+    end
+  end
+end