llm-shell 0.9.2 → 0.10.0

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

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module LLM::Anthropic::Format
+  ##
+  # @private
+  class CompletionFormat
+    ##
+    # @param [LLM::Message, Hash] message
+    #  The message to format
+    def initialize(message)
+      @message = message
+    end
+
+    ##
+    # Formats the message for the Anthropic chat completions API
+    # @return [Hash]
+    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_message
+      if message.tool_call?
+        {role: message.role, content: message.extra[:original_tool_calls]}
+      else
+        {role: message.role, content: format_content(content)}
+      end
+    end
+
+    ##
+    # @param [String, URI] content
+    #  The content to format
+    # @return [String, Hash]
+    #  The formatted content
+    def format_content(content)
+      case content
+      when Hash
+        content.empty? ? throw(:abort, nil) : [content]
+      when Array
+        content.empty? ? throw(:abort, nil) : content.flat_map { format_content(_1) }
+      when URI
+        [{type: :image, source: {type: "url", url: content.to_s}}]
+      when File
+        content.close unless content.closed?
+        format_content(LLM.File(content.path))
+      when LLM::File
+        if content.image?
+          [{type: :image, source: {type: "base64", media_type: content.mime_type, data: content.to_b64}}]
+        elsif content.pdf?
+          [{type: :document, source: {type: "base64", media_type: content.mime_type, data: content.to_b64}}]
+        else
+          raise LLM::PromptError, "The given object (an instance of #{content.class}) " \
+                                  "is not an image or PDF, and therefore not supported by the " \
+                                  "Anthropic API"
+        end
+      when LLM::Response
+        if content.file?
+          [{type: content.file_type, source: {type: :file, file_id: content.id}}]
+        else
+          prompt_error!(content)
+        end
+      when String
+        [{type: :text, text: content}]
+      when LLM::Message
+        format_content(content.content)
+      when LLM::Function::Return
+        [{type: "tool_result", tool_use_id: content.id, content: [{type: :text, text: JSON.dump(content.value)}]}]
+      else
+        prompt_error!(content)
+      end
+    end
+
+    def prompt_error!(content)
+      raise LLM::PromptError, "The given object (an instance of #{content.class}) " \
+                              "is not supported by the Anthropic API"
+    end
+
+    def message = @message
+    def content = message.content
+  end
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+class LLM::Anthropic
+  ##
+  # @private
+  module Format
+    require_relative "format/completion_format"
+
+    ##
+    # @param [Array<LLM::Message>] messages
+    #  The messages to format
+    # @return [Array<Hash>]
+    def format(messages)
+      messages.filter_map do
+        CompletionFormat.new(_1).format
+      end
+    end
+
+    private
+
+    ##
+    # @param [Hash] params
+    # @return [Hash]
+    def format_tools(tools)
+      return {} unless tools&.any?
+      {tools: tools.map { _1.respond_to?(:format) ? _1.format(self) : _1 }}
+    end
+  end
+end

data/lib/llm/shell/internal/llm.rb/lib/llm/providers/anthropic/models.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+class LLM::Anthropic
+  require_relative "response/enumerable"
+  ##
+  # The {LLM::Anthropic::Models LLM::Anthropic::Models} class provides a model
+  # object for interacting with [Anthropic's models API](https://platform.anthropic.com/docs/api-reference/models/list).
+  # The models API allows a client to query Anthropic for a list of models
+  # that are available for use with the Anthropic API.
+  #
+  # @example
+  #   #!/usr/bin/env ruby
+  #   require "llm"
+  #
+  #   llm = LLM.anthropic(key: ENV["KEY"])
+  #   res = llm.models.all
+  #   res.each do |model|
+  #     print "id: ", model.id, "\n"
+  #   end
+  class Models
+    ##
+    # Returns a new Models object
+    # @param provider [LLM::Provider]
+    # @return [LLM::Anthropic::Files]
+    def initialize(provider)
+      @provider = provider
+    end
+
+    ##
+    # List all models
+    # @example
+    #   llm = LLM.anthropic(key: ENV["KEY"])
+    #   res = llm.models.all
+    #   res.each do |model|
+    #     print "id: ", model.id, "\n"
+    #   end
+    # @see https://docs.anthropic.com/en/api/models-list Anthropic docs
+    # @param [Hash] params Other parameters (see Anthropic docs)
+    # @raise (see LLM::Provider#request)
+    # @return [LLM::Response]
+    def all(**params)
+      query = URI.encode_www_form(params)
+      req = Net::HTTP::Get.new("/v1/models?#{query}", headers)
+      res = execute(request: req)
+      LLM::Response.new(res).extend(LLM::Anthropic::Response::Enumerable)
+    end
+
+    private
+
+    [:headers, :execute].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/anthropic/response/completion.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module LLM::Anthropic::Response
+  module Completion
+    def choices = format_choices
+    def role = body.role
+    def model = body.model
+    def prompt_tokens = body.usage["input_tokens"] || 0
+    def completion_tokens = body.usage["output_tokens"] || 0
+    def total_tokens = prompt_tokens + completion_tokens
+
+    private
+
+    def format_choices
+      texts.map.with_index do |choice, index|
+        extra = {
+          index:, response: self,
+          tool_calls: format_tool_calls(tools), original_tool_calls: tools
+        }
+        LLM::Message.new(role, choice["text"], extra)
+      end
+    end
+
+    def format_tool_calls(tools)
+      (tools || []).filter_map do |tool|
+        tool = {
+          id: tool.id,
+          name: tool.name,
+          arguments: tool.input
+        }
+        LLM::Object.new(tool)
+      end
+    end
+
+    def parts = body.content
+    def texts = @texts ||= LLM::Object.from_hash(parts.select { _1["type"] == "text" })
+    def tools = @tools ||= LLM::Object.from_hash(parts.select { _1["type"] == "tool_use" })
+  end
+end

data/lib/llm/shell/internal/llm.rb/lib/llm/providers/anthropic/response/enumerable.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module LLM::Anthropic::Response
+  module Enumerable
+    include ::Enumerable
+    def each(&)
+      return enum_for(:each) unless block_given?
+      data.each { yield(_1) }
+    end
+  end
+end

data/lib/llm/shell/internal/llm.rb/lib/llm/providers/anthropic/response/file.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module LLM::Anthropic::Response
+  module File
+    ##
+    # Always return true
+    # @return [Boolean]
+    def file? = true
+
+    ##
+    # Returns the file type referenced by a prompt
+    # @return [Symbol]
+    def file_type
+      if mime_type.start_with?("image/")
+        :image
+      elsif mime_type == "text/plain" || mime_type == "application/pdf"
+        :document
+      else
+        :container_upload
+      end
+    end
+  end
+end

data/lib/llm/shell/internal/llm.rb/lib/llm/providers/anthropic/response/web_search.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module LLM::Anthropic::Response
+  ##
+  # The {LLM::Anthropic::Response::WebSearch LLM::Anthropic::Response::WebSearch}
+  # module provides methods for accessing web search results from a web search
+  # tool call made via the {LLM::Provider#web_search LLM::Provider#web_search}
+  # method.
+  module WebSearch
+    ##
+    # Returns one or more search results
+    # @return [Array<LLM::Object>]
+    def search_results
+      LLM::Object.from_hash(
+        content
+          .select { _1["type"] == "web_search_tool_result" }
+          .flat_map { |n| n.content.map { _1.slice(:title, :url) } }
+      )
+    end
+  end
+end

data/lib/llm/shell/internal/llm.rb/lib/llm/providers/anthropic/stream_parser.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+class LLM::Anthropic
+  ##
+  # @private
+  class StreamParser
+    ##
+    # Returns the fully constructed response body
+    # @return [LLM::Object]
+    attr_reader :body
+
+    ##
+    # @param [#<<] io An IO-like object
+    # @return [LLM::Anthropic::StreamParser]
+    def initialize(io)
+      @body = LLM::Object.new(role: "assistant", content: [])
+      @io = io
+    end
+
+    ##
+    # @param [Hash] chunk
+    # @return [LLM::Anthropic::StreamParser]
+    def parse!(chunk)
+      tap { merge!(chunk) }
+    end
+
+    private
+
+    def merge!(chunk)
+      if chunk["type"] == "message_start"
+        merge_message!(chunk["message"])
+      elsif chunk["type"] == "content_block_start"
+        @body["content"][chunk["index"]] = chunk["content_block"]
+      elsif chunk["type"] == "content_block_delta"
+        if chunk["delta"]["type"] == "text_delta"
+          @body.content[chunk["index"]]["text"] << chunk["delta"]["text"]
+          @io << chunk["delta"]["text"] if @io.respond_to?(:<<)
+        elsif chunk["delta"]["type"] == "input_json_delta"
+          content = @body.content[chunk["index"]]
+          if Hash === content["input"]
+            content["input"] = chunk["delta"]["partial_json"]
+          else
+            content["input"] << chunk["delta"]["partial_json"]
+          end
+        end
+      elsif chunk["type"] == "message_delta"
+        merge_message!(chunk["delta"])
+      elsif chunk["type"] == "content_block_stop"
+        content = @body.content[chunk["index"]]
+        if content["input"]
+          content["input"] = JSON.parse(content["input"])
+        end
+      end
+    end
+
+    def merge_message!(message)
+      message.each do |key, value|
+        @body[key] = if value.respond_to?(:each_pair)
+          merge_message!(value)
+        else
+          value
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module LLM
+  ##
+  # The Anthropic class implements a provider for
+  # [Anthropic](https://www.anthropic.com).
+  #
+  # @example
+  #   #!/usr/bin/env ruby
+  #   require "llm"
+  #
+  #   llm = LLM.anthropic(key: ENV["KEY"])
+  #   bot = LLM::Bot.new(llm)
+  #   bot.chat ["Tell me about this photo", File.open("/images/dog.jpg", "rb")]
+  #   bot.messages.select(&:assistant?).each { print "[#{_1.role}]", _1.content, "\n" }
+  class Anthropic < Provider
+    require_relative "anthropic/response/completion"
+    require_relative "anthropic/response/web_search"
+    require_relative "anthropic/format"
+    require_relative "anthropic/error_handler"
+    require_relative "anthropic/stream_parser"
+    require_relative "anthropic/files"
+    require_relative "anthropic/models"
+    include Format
+
+    HOST = "api.anthropic.com"
+
+    ##
+    # @param key (see LLM::Provider#initialize)
+    def initialize(**)
+      super(host: HOST, **)
+    end
+
+    ##
+    # Provides an interface to the chat completions API
+    # @see https://docs.anthropic.com/en/api/messages Anthropic 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 (see LLM::Provider#complete)
+    def complete(prompt, params = {})
+      params = {role: :user, model: default_model, max_tokens: 1024}.merge!(params)
+      tools  = resolve_tools(params.delete(:tools))
+      params = [params, 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("/v1/messages", headers)
+      messages = [*(params.delete(:messages) || []), 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::Anthropic::Response::Completion)
+        .extend(Module.new { define_method(:__tools__) { tools } })
+    end
+
+    ##
+    # Provides an interface to Anthropic's models API
+    # @see https://docs.anthropic.com/en/api/models-list
+    # @return [LLM::Anthropic::Models]
+    def models
+      LLM::Anthropic::Models.new(self)
+    end
+
+    ##
+    # Provides an interface to Anthropic's files API
+    # @see https://docs.anthropic.com/en/docs/build-with-claude/files Anthropic docs
+    # @return [LLM::Anthropic::Files]
+    def files
+      LLM::Anthropic::Files.new(self)
+    end
+
+    ##
+    # @return (see LLM::Provider#assistant_role)
+    def assistant_role
+      "assistant"
+    end
+
+    ##
+    # Returns the default model for chat completions
+    # @see https://docs.anthropic.com/en/docs/about-claude/models/all-models#model-comparison-table claude-sonnet-4-20250514
+    # @return [String]
+    def default_model
+      "claude-sonnet-4-20250514"
+    end
+
+    ##
+    # @note
+    #  This method includes certain tools that require configuration
+    #  through a set of options that are easier to set through the
+    #  {LLM::Provider#server_tool LLM::Provider#server_tool} method.
+    # @see https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/web-search-tool Anthropic docs
+    # @return (see LLM::Provider#server_tools)
+    def server_tools
+      {
+        bash: server_tool(:bash, type: "bash_20250124"),
+        web_search: server_tool(:web_search, type: "web_search_20250305", max_uses: 5),
+        text_editor: server_tool(:str_replace_based_edit_tool, type: "text_editor_20250728", max_characters: 10_000)
+      }
+    end
+
+    ##
+    # A convenience method for performing a web search using the
+    # Anthropic web search tool.
+    # @example
+    #   llm = LLM.anthropic(key: ENV["KEY"])
+    #   res = llm.web_search(query: "summarize today's news")
+    #   res.search_results.each { |item| print item.title, ": ", item.url, "\n" }
+    # @param query [String] The search query.
+    # @return [LLM::Response] The response from the LLM provider.
+    def web_search(query:)
+      complete(query, tools: [server_tools[:web_search]])
+        .extend(LLM::Anthropic::Response::WebSearch)
+    end
+
+    private
+
+    def headers
+      (@headers || {}).merge(
+        "Content-Type" => "application/json",
+        "x-api-key" => @key,
+        "anthropic-version" => "2023-06-01",
+        "anthropic-beta" => "files-api-2025-04-14"
+      )
+    end
+
+    def stream_parser
+      LLM::Anthropic::StreamParser
+    end
+
+    def error_handler
+      LLM::Anthropic::ErrorHandler
+    end
+  end
+end

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

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module LLM::DeepSeek::Format
+  ##
+  # @private
+  class CompletionFormat
+    ##
+    # @param [LLM::Message, Hash] message
+    #  The message to format
+    def initialize(message)
+      @message = message
+    end
+
+    ##
+    # Formats the message for the DeepSeek 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 String
+        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
+        raise LLM::PromptError, "The given object (an instance of #{content.class}) " \
+                                "is not supported by the DeepSeek chat completions API"
+      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 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/deepseek/format.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+class LLM::DeepSeek
+  ##
+  # @private
+  module Format
+    require_relative "format/completion_format"
+    ##
+    # @param [Array<LLM::Message>] messages
+    #  The messages to format
+    # @return [Array<Hash>]
+    def format(messages, ...)
+      messages.filter_map do |message|
+        CompletionFormat.new(message).format
+      end
+    end
+
+    private
+
+    ##
+    # @param [Hash] params
+    # @return [Hash]
+    def format_tools(tools)
+      (tools.nil? || tools.empty?) ? {} : {tools: tools.map { _1.format(self) }}
+    end
+  end
+end

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

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require_relative "openai" unless defined?(LLM::OpenAI)
+
+module LLM
+  ##
+  # The DeepSeek class implements a provider for
+  # [DeepSeek](https://deepseek.com)
+  # through its OpenAI-compatible API available via
+  # their [web platform](https://platform.deepseek.com).
+  #
+  # @example
+  #   #!/usr/bin/env ruby
+  #   require "llm"
+  #
+  #   llm = LLM.deepseek(key: ENV["KEY"])
+  #   bot = LLM::Bot.new(llm)
+  #   bot.chat ["Tell me about this photo", File.open("/images/cat.jpg", "rb")]
+  #   bot.messages.select(&:assistant?).each { print "[#{_1.role}]", _1.content, "\n" }
+  class DeepSeek < OpenAI
+    require_relative "deepseek/format"
+    include DeepSeek::Format
+
+    ##
+    # @param (see LLM::Provider#initialize)
+    # @return [LLM::DeepSeek]
+    def initialize(host: "api.deepseek.com", port: 443, ssl: true, **)
+      super
+    end
+
+    ##
+    # @raise [NotImplementedError]
+    def files
+      raise NotImplementedError
+    end
+
+    ##
+    # @raise [NotImplementedError]
+    def images
+      raise NotImplementedError
+    end
+
+    ##
+    # @raise [NotImplementedError]
+    def audio
+      raise NotImplementedError
+    end
+
+    ##
+    # @raise [NotImplementedError]
+    def moderations
+      raise NotImplementedError
+    end
+
+    ##
+    # @raise [NotImplementedError]
+    def responses
+      raise NotImplementedError
+    end
+
+    ##
+    # @raise [NotImplementedError]
+    def vector_stores
+      raise NotImplementedError
+    end
+
+    ##
+    # Returns the default model for chat completions
+    # @see https://api-docs.deepseek.com/quick_start/pricing deepseek-chat
+    # @return [String]
+    def default_model
+      "deepseek-chat"
+    end
+  end
+end