llm-shell 0.9.2 → 0.10.0

data/lib/llm/shell/internal/llm.rb/lib/llm/providers/ollama.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module LLM
+  ##
+  # The Ollama class implements a provider for [Ollama](https://ollama.ai/) –
+  # and the provider supports a wide range of models. It is straight forward
+  # to run on your own hardware, and there are a number of multi-modal models
+  # that can process both images and text.
+  #
+  # @example
+  #   #!/usr/bin/env ruby
+  #   require "llm"
+  #
+  #   llm = LLM.ollama(key: nil)
+  #   bot = LLM::Bot.new(llm, model: "llava")
+  #   bot.chat ["Tell me about this image", File.open("/images/parrot.png", "rb")]
+  #   bot.messages.select(&:assistant?).each { print "[#{_1.role}]", _1.content, "\n" }
+  class Ollama < Provider
+    require_relative "ollama/response/embedding"
+    require_relative "ollama/response/completion"
+    require_relative "ollama/error_handler"
+    require_relative "ollama/format"
+    require_relative "ollama/stream_parser"
+    require_relative "ollama/models"
+
+    include Format
+
+    HOST = "localhost"
+
+    ##
+    # @param key (see LLM::Provider#initialize)
+    def initialize(**)
+      super(host: HOST, port: 11434, ssl: false, **)
+    end
+
+    ##
+    # Provides an embedding
+    # @param input (see LLM::Provider#embed)
+    # @param model (see LLM::Provider#embed)
+    # @param params (see LLM::Provider#embed)
+    # @raise (see LLM::Provider#request)
+    # @return [LLM::Response]
+    def embed(input, model: default_model, **params)
+      params   = {model:}.merge!(params)
+      req      = Net::HTTP::Post.new("/v1/embeddings", headers)
+      req.body = JSON.dump({input:}.merge!(params))
+      res      = execute(request: req)
+      LLM::Response.new(res).extend(LLM::Ollama::Response::Embedding)
+    end
+
+    ##
+    # Provides an interface to the chat completions API
+    # @see https://github.com/ollama/ollama/blob/main/docs/api.md#generate-a-chat-completion Ollama docs
+    # @param prompt (see LLM::Provider#complete)
+    # @param params (see LLM::Provider#complete)
+    # @example (see LLM::Provider#complete)
+    # @raise (see LLM::Provider#request)
+    # @raise [LLM::PromptError]
+    #  When given an object a provider does not understand
+    # @return [LLM::Response]
+    def complete(prompt, params = {})
+      params = {role: :user, model: default_model, stream: true}.merge!(params)
+      tools  = resolve_tools(params.delete(:tools))
+      params = [params, {format: params[:schema]}, format_tools(tools)].inject({}, &:merge!).compact
+      role, stream = params.delete(:role), params.delete(:stream)
+      params[:stream] = true if stream.respond_to?(:<<) || stream == true
+      req = Net::HTTP::Post.new("/api/chat", headers)
+      messages = [*(params.delete(:messages) || []), LLM::Message.new(role, prompt)]
+      body = JSON.dump({messages: [format(messages)].flatten}.merge!(params))
+      set_body_stream(req, StringIO.new(body))
+      res = execute(request: req, stream:)
+      LLM::Response.new(res)
+        .extend(LLM::Ollama::Response::Completion)
+        .extend(Module.new { define_method(:__tools__) { tools } })
+    end
+
+    ##
+    # Provides an interface to Ollama's models API
+    # @see https://github.com/ollama/ollama/blob/main/docs/api.md#list-local-models Ollama docs
+    # @return [LLM::Ollama::Models]
+    def models
+      LLM::Ollama::Models.new(self)
+    end
+
+    ##
+    # @return (see LLM::Provider#assistant_role)
+    def assistant_role
+      "assistant"
+    end
+
+    ##
+    # Returns the default model for chat completions
+    # @see https://ollama.com/library/qwen3 qwen3
+    # @return [String]
+    def default_model
+      "qwen3:latest"
+    end
+
+    private
+
+    def headers
+      (@headers || {}).merge(
+        "Content-Type" => "application/json",
+        "Authorization" => "Bearer #{@key}"
+      )
+    end
+
+    def stream_parser
+      LLM::Ollama::StreamParser
+    end
+
+    def error_handler
+      LLM::Ollama::ErrorHandler
+    end
+  end
+end

data/lib/llm/shell/internal/llm.rb/lib/llm/providers/openai/audio.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+class LLM::OpenAI
+  ##
+  # The {LLM::OpenAI::Audio LLM::OpenAI::Audio} class provides an audio
+  # object for interacting with [OpenAI's audio API](https://platform.openai.com/docs/api-reference/audio/createSpeech).
+  # @example
+  #   llm = LLM.openai(key: ENV["KEY"])
+  #   res = llm.audio.create_speech(input: "A dog on a rocket to the moon")
+  #   IO.copy_stream res.audio, "rocket.mp3"
+  class Audio
+    ##
+    # Returns a new Audio object
+    # @param provider [LLM::Provider]
+    # @return [LLM::OpenAI::Responses]
+    def initialize(provider)
+      @provider = provider
+    end
+
+    ##
+    # Create an audio track
+    # @example
+    #   llm = LLM.openai(key: ENV["KEY"])
+    #   res = llm.images.create_speech(input: "A dog on a rocket to the moon")
+    #   File.binwrite("rocket.mp3", res.audio.string)
+    # @see https://platform.openai.com/docs/api-reference/audio/createSpeech OpenAI docs
+    # @param [String] input The text input
+    # @param [String] voice The voice to use
+    # @param [String] model The model to use
+    # @param [String] response_format The response format
+    # @param [Hash] params Other parameters (see OpenAI docs)
+    # @raise (see LLM::Provider#request)
+    # @return [LLM::Response]
+    def create_speech(input:, voice: "alloy", model: "gpt-4o-mini-tts", response_format: "mp3", **params)
+      req = Net::HTTP::Post.new("/v1/audio/speech", headers)
+      req.body = JSON.dump({input:, voice:, model:, response_format:}.merge!(params))
+      io = StringIO.new("".b)
+      res = execute(request: req) { _1.read_body { |chunk| io << chunk } }
+      LLM::Response.new(res).tap { _1.define_singleton_method(:audio) { io } }
+    end
+
+    ##
+    # Create an audio transcription
+    # @example
+    #   llm = LLM.openai(key: ENV["KEY"])
+    #   res = llm.audio.create_transcription(file: "/audio/rocket.mp3")
+    #   res.text # => "A dog on a rocket to the moon"
+    # @see https://platform.openai.com/docs/api-reference/audio/createTranscription OpenAI docs
+    # @param [String, LLM::File] file The input audio
+    # @param [String] model The model to use
+    # @param [Hash] params Other parameters (see OpenAI docs)
+    # @raise (see LLM::Provider#request)
+    # @return [LLM::Response]
+    def create_transcription(file:, model: "whisper-1", **params)
+      multi = LLM::Multipart.new(params.merge!(file: LLM.File(file), model:))
+      req = Net::HTTP::Post.new("/v1/audio/transcriptions", headers)
+      req["content-type"] = multi.content_type
+      set_body_stream(req, multi.body)
+      res = execute(request: req)
+      LLM::Response.new(res)
+    end
+
+    ##
+    # Create an audio translation (in English)
+    # @example
+    #   # Arabic => English
+    #   llm = LLM.openai(key: ENV["KEY"])
+    #   res = llm.audio.create_translation(file: "/audio/bismillah.mp3")
+    #   res.text # => "In the name of Allah, the Beneficent, the Merciful."
+    # @see https://platform.openai.com/docs/api-reference/audio/createTranslation OpenAI docs
+    # @param [LLM::File] file The input audio
+    # @param [String] model The model to use
+    # @param [Hash] params Other parameters (see OpenAI docs)
+    # @raise (see LLM::Provider#request)
+    # @return [LLM::Response]
+    def create_translation(file:, model: "whisper-1", **params)
+      multi = LLM::Multipart.new(params.merge!(file: LLM.File(file), model:))
+      req = Net::HTTP::Post.new("/v1/audio/translations", headers)
+      req["content-type"] = multi.content_type
+      set_body_stream(req, multi.body)
+      res = execute(request: req)
+      LLM::Response.new(res)
+    end
+
+    private
+
+    [:headers, :execute, :set_body_stream].each do |m|
+      define_method(m) { |*args, **kwargs, &b| @provider.send(m, *args, **kwargs, &b) }
+    end
+  end
+end

data/lib/llm/shell/internal/llm.rb/lib/llm/providers/openai/error_handler.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+class LLM::OpenAI
+  ##
+  # @private
+  class ErrorHandler
+    ##
+    # @return [Net::HTTPResponse]
+    #  Non-2XX response from the server
+    attr_reader :res
+
+    ##
+    # @param [Net::HTTPResponse] res
+    #  The response from the server
+    # @return [LLM::OpenAI::ErrorHandler]
+    def initialize(res)
+      @res = res
+    end
+
+    ##
+    # @raise [LLM::Error]
+    #  Raises a subclass of {LLM::Error LLM::Error}
+    def raise_error!
+      case res
+      when Net::HTTPServerError
+        raise LLM::ServerError.new { _1.response = res }, "Server error"
+      when Net::HTTPUnauthorized
+        raise LLM::UnauthorizedError.new { _1.response = res }, "Authentication error"
+      when Net::HTTPTooManyRequests
+        raise LLM::RateLimitError.new { _1.response = res }, "Too many requests"
+      else
+        error = body["error"] || {}
+        case error["type"]
+        when "server_error" then raise LLM::ServerError.new { _1.response = res }, error["message"]
+        else raise LLM::ResponseError.new { _1.response = res }, error["message"] || "Unexpected response"
+        end
+      end
+    end
+
+    private
+
+    def body
+      @body ||= JSON.parse(res.body)
+    end
+  end
+end

data/lib/llm/shell/internal/llm.rb/lib/llm/providers/openai/files.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+class LLM::OpenAI
+  ##
+  # The {LLM::OpenAI::Files LLM::OpenAI::Files} class provides a files
+  # object for interacting with [OpenAI's Files API](https://platform.openai.com/docs/api-reference/files/create).
+  # The files API allows a client to upload files for use with OpenAI's models
+  # and API endpoints. OpenAI supports multiple file formats, including text
+  # files, CSV files, JSON files, and more.
+  #
+  # @example example #1
+  #   #!/usr/bin/env ruby
+  #   require "llm"
+  #
+  #   llm = LLM.openai(key: ENV["KEY"])
+  #   bot = LLM::Bot.new(llm)
+  #   file = llm.files.create file: "/books/goodread.pdf"
+  #   bot.chat ["Tell me about this PDF", file]
+  #   bot.messages.select(&:assistant?).each { print "[#{_1.role}]", _1.content, "\n" }
+  class Files
+    require_relative "response/enumerable"
+    require_relative "response/file"
+
+    ##
+    # Returns a new Files object
+    # @param provider [LLM::Provider]
+    # @return [LLM::OpenAI::Files]
+    def initialize(provider)
+      @provider = provider
+    end
+
+    ##
+    # List all files
+    # @example
+    #   llm = LLM.openai(key: ENV["KEY"])
+    #   res = llm.files.all
+    #   res.each do |file|
+    #     print "id: ", file.id, "\n"
+    #   end
+    # @see https://platform.openai.com/docs/api-reference/files/list OpenAI docs
+    # @param [Hash] params Other parameters (see OpenAI docs)
+    # @raise (see LLM::Provider#request)
+    # @return [LLM::Response]
+    def all(**params)
+      query = URI.encode_www_form(params)
+      req = Net::HTTP::Get.new("/v1/files?#{query}", headers)
+      res = execute(request: req)
+      LLM::Response.new(res).extend(LLM::OpenAI::Response::Enumerable)
+    end
+
+    ##
+    # Create a file
+    # @example
+    #   llm = LLM.openai(key: ENV["KEY"])
+    #   res = llm.files.create file: "/documents/haiku.txt"
+    # @see https://platform.openai.com/docs/api-reference/files/create OpenAI docs
+    # @param [File, LLM::File, String] file The file
+    # @param [String] purpose The purpose of the file (see OpenAI docs)
+    # @param [Hash] params Other parameters (see OpenAI docs)
+    # @raise (see LLM::Provider#request)
+    # @return [LLM::Response]
+    def create(file:, purpose: "assistants", **params)
+      multi = LLM::Multipart.new(params.merge!(file: LLM.File(file), purpose:))
+      req = Net::HTTP::Post.new("/v1/files", headers)
+      req["content-type"] = multi.content_type
+      set_body_stream(req, multi.body)
+      res = execute(request: req)
+      LLM::Response.new(res).extend(LLM::OpenAI::Response::File)
+    end
+
+    ##
+    # Get a file
+    # @example
+    #   llm = LLM.openai(key: ENV["KEY"])
+    #   res = llm.files.get(file: "file-1234567890")
+    #   print "id: ", res.id, "\n"
+    # @see https://platform.openai.com/docs/api-reference/files/get OpenAI docs
+    # @param [#id, #to_s] file The file ID
+    # @param [Hash] params Other parameters (see OpenAI docs)
+    # @raise (see LLM::Provider#request)
+    # @return [LLM::Response]
+    def get(file:, **params)
+      file_id = file.respond_to?(:id) ? file.id : file
+      query = URI.encode_www_form(params)
+      req = Net::HTTP::Get.new("/v1/files/#{file_id}?#{query}", headers)
+      res = execute(request: req)
+      LLM::Response.new(res).extend(LLM::OpenAI::Response::File)
+    end
+
+    ##
+    # Download the content of a file
+    # @example
+    #   llm = LLM.openai(key: ENV["KEY"])
+    #   res = llm.files.download(file: "file-1234567890")
+    #   File.binwrite "haiku1.txt", res.file.read
+    #   print res.file.read, "\n"
+    # @see https://platform.openai.com/docs/api-reference/files/content OpenAI docs
+    # @param [#id, #to_s] file The file ID
+    # @param [Hash] params Other parameters (see OpenAI docs)
+    # @raise (see LLM::Provider#request)
+    # @return [LLM::Response]
+    def download(file:, **params)
+      query = URI.encode_www_form(params)
+      file_id = file.respond_to?(:id) ? file.id : file
+      req = Net::HTTP::Get.new("/v1/files/#{file_id}/content?#{query}", headers)
+      io = StringIO.new("".b)
+      res = execute(request: req) { |res| res.read_body { |chunk| io << chunk } }
+      LLM::Response.new(res).tap { _1.define_singleton_method(:file) { io } }
+    end
+
+    ##
+    # Delete a file
+    # @example
+    #   llm = LLM.openai(key: ENV["KEY"])
+    #   res = llm.files.delete(file: "file-1234567890")
+    #   print res.deleted, "\n"
+    # @see https://platform.openai.com/docs/api-reference/files/delete OpenAI docs
+    # @param [#id, #to_s] file The file ID
+    # @raise (see LLM::Provider#request)
+    # @return [LLM::Response]
+    def delete(file:)
+      file_id = file.respond_to?(:id) ? file.id : file
+      req = Net::HTTP::Delete.new("/v1/files/#{file_id}", headers)
+      res = execute(request: req)
+      LLM::Response.new(res)
+    end
+
+    private
+
+    [:headers, :execute, :set_body_stream].each do |m|
+      define_method(m) { |*args, **kwargs, &b| @provider.send(m, *args, **kwargs, &b) }
+    end
+  end
+end

data/lib/llm/shell/internal/llm.rb/lib/llm/providers/openai/format/completion_format.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module LLM::OpenAI::Format
+  ##
+  # @private
+  class CompletionFormat
+    ##
+    # @param [LLM::Message, Hash] message
+    #  The message to format
+    def initialize(message)
+      @message = message
+    end
+
+    ##
+    # Formats the message for the OpenAI chat completions API
+    # @return [Hash]
+    def format
+      catch(:abort) do
+        if Hash === message
+          {role: message[:role], content: format_content(message[:content])}
+        elsif message.tool_call?
+          {role: message.role, content: nil, tool_calls: message.extra[:original_tool_calls]}
+        else
+          format_message
+        end
+      end
+    end
+
+    private
+
+    def format_content(content)
+      case content
+      when URI
+        [{type: :image_url, image_url: {url: content.to_s}}]
+      when File
+        content.close unless content.closed?
+        format_content(LLM.File(content.path))
+      when LLM::File
+        format_file(content)
+      when LLM::Response
+        content.file? ? [{type: :file, file: {file_id: content.id}}] : prompt_error!(content)
+      when String
+        [{type: :text, text: content.to_s}]
+      when LLM::Message
+        format_content(content.content)
+      when LLM::Function::Return
+        throw(:abort, {role: "tool", tool_call_id: content.id, content: JSON.dump(content.value)})
+      else
+        prompt_error!(content)
+      end
+    end
+
+    def format_file(content)
+      file = content
+      if file.image?
+        [{type: :image_url, image_url: {url: file.to_data_uri}}]
+      else
+        [{type: :file, file: {filename: file.basename, file_data: file.to_data_uri}}]
+      end
+    end
+
+    def format_message
+      case content
+      when Array
+        format_array
+      else
+        {role: message.role, content: format_content(content)}
+      end
+    end
+
+    def format_array
+      if content.empty?
+        nil
+      elsif returns.any?
+        returns.map { {role: "tool", tool_call_id: _1.id, content: JSON.dump(_1.value)} }
+      else
+        {role: message.role, content: content.flat_map { format_content(_1) }}
+      end
+    end
+
+    def prompt_error!(content)
+      raise LLM::PromptError, "The given object (an instance of #{content.class}) " \
+                              "is not supported by the OpenAI chat completions API"
+    end
+
+    def message = @message
+    def content = message.content
+    def returns = content.grep(LLM::Function::Return)
+  end
+end

data/lib/llm/shell/internal/llm.rb/lib/llm/providers/openai/format/moderation_format.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module LLM::OpenAI::Format
+  ##
+  # @private
+  class ModerationFormat
+    ##
+    # @param [String, URI, Array<String, URI>] inputs
+    #  The inputs to format
+    # @return [LLM::OpenAI::Format::ModerationFormat]
+    def initialize(inputs)
+      @inputs = inputs
+    end
+
+    ##
+    # Formats the inputs for the OpenAI moderations API
+    # @return [Array<Hash>]
+    def format
+      [*inputs].flat_map do |input|
+        if String === input
+          {type: :text, text: input}
+        elsif URI === input
+          {type: :image_url, url: input.to_s}
+        else
+          raise LLM::FormatError, "The given object (an instance of #{input.class}) " \
+                                  "is not supported by OpenAI moderations API"
+        end
+      end
+    end
+
+    private
+
+    attr_reader :inputs
+  end
+end

data/lib/llm/shell/internal/llm.rb/lib/llm/providers/openai/format/respond_format.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module LLM::OpenAI::Format
+  ##
+  # @private
+  class RespondFormat
+    def initialize(message)
+      @message = message
+    end
+
+    def format
+      catch(:abort) do
+        if Hash === message
+          {role: message[:role], content: format_content(message[:content])}
+        else
+          format_message
+        end
+      end
+    end
+
+    private
+
+    def format_content(content)
+      case content
+      when LLM::Response
+        content.file? ? format_file(content) : prompt_error!(content)
+      when String
+        [{type: :input_text, text: content.to_s}]
+      when LLM::Message
+        format_content(content.content)
+      else
+        prompt_error!(content)
+      end
+    end
+
+    def format_message
+      case content
+      when Array
+        format_array
+      else
+        {role: message.role, content: format_content(content)}
+      end
+    end
+
+    def format_array
+      if content.empty?
+        nil
+      elsif returns.any?
+        returns.map { {type: "function_call_output", call_id: _1.id, output: JSON.dump(_1.value)} }
+      else
+        {role: message.role, content: content.flat_map { format_content(_1) }}
+      end
+    end
+
+    def format_file(content)
+      file = LLM::File(content.filename)
+      if file.image?
+        [{type: :input_image, file_id: content.id}]
+      else
+        [{type: :input_file, file_id: content.id}]
+      end
+    end
+
+    def prompt_error!(content)
+      raise LLM::PromptError, "The given object (an instance of #{content.class}) " \
+                              "is not supported by the OpenAI responses API"
+    end
+    def message = @message
+    def content = message.content
+    def returns = content.grep(LLM::Function::Return)
+  end
+end

data/lib/llm/shell/internal/llm.rb/lib/llm/providers/openai/format.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+class LLM::OpenAI
+  ##
+  # @private
+  module Format
+    require_relative "format/completion_format"
+    require_relative "format/respond_format"
+    require_relative "format/moderation_format"
+
+    ##
+    # @param [Array<LLM::Message>] messages
+    #  The messages to format
+    # @param [Symbol] mode
+    #  The mode to format the messages for
+    # @return [Array<Hash>]
+    def format(messages, mode)
+      messages.filter_map do |message|
+        if mode == :complete
+          CompletionFormat.new(message).format
+        else
+          RespondFormat.new(message).format
+        end
+      end
+    end
+
+    private
+
+    ##
+    # @param [Hash] params
+    # @return [Hash]
+    def format_schema(params)
+      return {} unless params and params[:schema]
+      schema = params.delete(:schema)
+      {
+        response_format: {
+          type: "json_schema",
+          json_schema: {name: "JSONSchema", schema:}
+        }
+      }
+    end
+
+    ##
+    # @param [Hash] params
+    # @return [Hash]
+    def format_tools(tools)
+      if tools.nil? || tools.empty?
+        {}
+      else
+        {tools: tools.map { _1.respond_to?(:format) ? _1.format(self) : _1 }}
+      end
+    end
+  end
+end