llm-shell 0.9.2 → 0.10.0

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

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+class LLM::OpenAI
+  ##
+  # The {LLM::OpenAI::Images LLM::OpenAI::Images} class provides an interface
+  # for [OpenAI's images API](https://platform.openai.com/docs/api-reference/images).
+  # OpenAI supports multiple response formats: temporary URLs, or binary strings
+  # encoded in base64. The default is to return temporary URLs.
+  #
+  # @example Temporary URLs
+  #   #!/usr/bin/env ruby
+  #   require "llm"
+  #   require "open-uri"
+  #   require "fileutils"
+  #
+  #   llm = LLM.openai(key: ENV["KEY"])
+  #   res = llm.images.create prompt: "A dog on a rocket to the moon"
+  #   FileUtils.mv OpenURI.open_uri(res.urls[0]).path,
+  #                "rocket.png"
+  #
+  # @example Binary strings
+  #   #!/usr/bin/env ruby
+  #   require "llm"
+  #
+  #   llm = LLM.openai(key: ENV["KEY"])
+  #   res = llm.images.create prompt: "A dog on a rocket to the moon",
+  #                           response_format: "b64_json"
+  #   IO.copy_stream res.images[0], "rocket.png"
+  class Images
+    require_relative "response/image"
+    ##
+    # Returns a new Images object
+    # @param provider [LLM::Provider]
+    # @return [LLM::OpenAI::Responses]
+    def initialize(provider)
+      @provider = provider
+    end
+
+    ##
+    # Create an image
+    # @example
+    #   llm = LLM.openai(key: ENV["KEY"])
+    #   res = llm.images.create prompt: "A dog on a rocket to the moon"
+    #   res.urls.each { print _1, "\n" }
+    # @see https://platform.openai.com/docs/api-reference/images/create OpenAI docs
+    # @param [String] prompt The prompt
+    # @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(prompt:, model: "dall-e-3", **params)
+      req = Net::HTTP::Post.new("/v1/images/generations", headers)
+      req.body = JSON.dump({prompt:, n: 1, model:}.merge!(params))
+      res = execute(request: req)
+      LLM::Response.new(res).extend(LLM::OpenAI::Response::Image)
+    end
+
+    ##
+    # Create image variations
+    # @example
+    #   llm = LLM.openai(key: ENV["KEY"])
+    #   res = llm.images.create_variation(image: "/images/hat.png", n: 5)
+    #   p res.urls
+    # @see https://platform.openai.com/docs/api-reference/images/createVariation OpenAI docs
+    # @param [File] image The image to create variations from
+    # @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_variation(image:, model: "dall-e-2", **params)
+      image = LLM.File(image)
+      multi = LLM::Multipart.new(params.merge!(image:, model:))
+      req = Net::HTTP::Post.new("/v1/images/variations", 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::Image)
+    end
+
+    ##
+    # Edit an image
+    # @example
+    #   llm = LLM.openai(key: ENV["KEY"])
+    #   res = llm.images.edit(image: "/images/hat.png", prompt: "A cat wearing this hat")
+    #   p res.urls
+    # @see https://platform.openai.com/docs/api-reference/images/createEdit OpenAI docs
+    # @param [File] image The image to edit
+    # @param [String] prompt The prompt
+    # @param [String] model The model to use
+    # @param [Hash] params Other parameters (see OpenAI docs)
+    # @raise (see LLM::Provider#request)
+    # @return [LLM::Response]
+    def edit(image:, prompt:, model: "dall-e-2", **params)
+      image = LLM.File(image)
+      multi = LLM::Multipart.new(params.merge!(image:, prompt:, model:))
+      req = Net::HTTP::Post.new("/v1/images/edits", 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::Image)
+    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/models.rb

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

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+class LLM::OpenAI
+  ##
+  # The {LLM::OpenAI::Moderations LLM::OpenAI::Moderations} class provides a moderations
+  # object for interacting with [OpenAI's moderations API](https://platform.openai.com/docs/api-reference/moderations).
+  # The moderations API can categorize content into different categories, such as
+  # hate speech, self-harm, and sexual content. It can also provide a confidence score
+  # for each category.
+  #
+  # @example
+  #   #!/usr/bin/env ruby
+  #   require "llm"
+  #
+  #   llm = LLM.openai(key: ENV["KEY"])
+  #   res = llm.moderations.create input: "I hate you"
+  #   mod = res.moderations[0]
+  #   print "categories: #{mod.categories}", "\n"
+  #   print "scores: #{mod.scores}", "\n"
+  #
+  # @example
+  #   #!/usr/bin/env ruby
+  #   require "llm"
+  #
+  #   llm = LLM.openai(key: ENV["KEY"])
+  #   res = llm.moderations.create input: URI.parse("https://example.com/image.png")
+  #   mod = res.moderations[0]
+  #   print "categories: #{mod.categories}", "\n"
+  #   print "scores: #{mod.scores}", "\n"
+  #
+  # @see https://platform.openai.com/docs/api-reference/moderations/create OpenAI docs
+  # @see https://platform.openai.com/docs/models#moderation OpenAI moderation models
+  class Moderations
+    require_relative "response/moderations"
+
+    ##
+    # Returns a new Moderations object
+    # @param [LLM::Provider] provider
+    # @return [LLM::OpenAI::Moderations]
+    def initialize(provider)
+      @provider = provider
+    end
+
+    ##
+    # Create a moderation
+    # @see https://platform.openai.com/docs/api-reference/moderations/create OpenAI docs
+    # @see https://platform.openai.com/docs/models#moderation OpenAI moderation models
+    # @param [String, URI, Array<String, URI>] input
+    # @param [String, LLM::Model] model The model to use
+    # @return [LLM::Response]
+    def create(input:, model: "omni-moderation-latest", **params)
+      req = Net::HTTP::Post.new("/v1/moderations", headers)
+      input = Format::ModerationFormat.new(input).format
+      req.body = JSON.dump({input:, model:}.merge!(params))
+      res = execute(request: req)
+      LLM::Response.new(res).extend(LLM::OpenAI::Response::Moderations)
+    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/openai/response/audio.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module LLM::OpenAI::Response
+  module Audio
+    def audio = body.audio
+  end
+end

data/lib/llm/shell/internal/llm.rb/lib/llm/providers/openai/response/completion.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module LLM::OpenAI::Response
+  module Completion
+    def choices
+      body.choices.map.with_index do |choice, index|
+        choice = LLM::Object.from_hash(choice)
+        message = choice.message
+        extra = {
+          index:, response: self,
+          logprobs: choice.logprobs,
+          tool_calls: format_tool_calls(message.tool_calls),
+          original_tool_calls: message.tool_calls
+        }
+        LLM::Message.new(message.role, message.content, extra)
+      end
+    end
+    alias_method :messages, :choices
+
+    def model = body.model
+    def prompt_tokens = usage["prompt_tokens"]
+    def completion_tokens = usage["completion_tokens"]
+    def total_tokens = usage["total_tokens"]
+    def usage = body.usage || {}
+
+    private
+
+    def format_tool_calls(tools)
+      (tools || []).filter_map do |tool|
+        next unless tool.function
+        tool = {
+          id: tool.id,
+          name: tool.function.name,
+          arguments: JSON.parse(tool.function.arguments)
+        }
+        LLM::Object.new(tool)
+      end
+    end
+  end
+end

data/lib/llm/shell/internal/llm.rb/lib/llm/providers/openai/response/embedding.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module LLM::OpenAI::Response
+  module Embedding
+    def embeddings = data.map { _1["embedding"] }
+    def prompt_tokens = data.dig(0, "usage", "prompt_tokens")
+    def total_tokens = data.dig(0, "usage", "total_tokens")
+  end
+end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module LLM::OpenAI::Response
+  module Enumerable
+    include ::Enumerable
+    def each(&)
+      return enum_for(:each) unless block_given?
+      data.each { yield(_1) }
+    end
+
+    ##
+    # @return [Boolean]
+    def empty?
+      data.empty?
+    end
+
+    ##
+    # @return [Integer]
+    def size
+      data.size
+    end
+  end
+end

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

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module LLM::OpenAI::Response
+  module File
+    def file? = true
+  end
+end

data/lib/llm/shell/internal/llm.rb/lib/llm/providers/openai/response/image.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module LLM::OpenAI::Response
+  module Image
+    def urls
+      data.filter_map { _1["url"] }
+    end
+
+    def images
+      data.filter_map do
+        next unless _1["b64_json"]
+        StringIO.new(_1["b64_json"].unpack1("m0"))
+      end
+    end
+  end
+end

data/lib/llm/shell/internal/llm.rb/lib/llm/providers/openai/response/moderations.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module LLM::OpenAI::Response
+  module Moderations
+    ##
+    # @return [Array<LLM::Response]
+    def moderations
+      @moderations ||= body.results.map { _1.extend(Moderation) }
+    end
+  end
+
+  module Moderation
+    ##
+    # Returns true if the moderation is flagged
+    # @return [Boolean]
+    def flagged?
+      body.flagged
+    end
+
+    ##
+    # Returns the moderation categories
+    # @return [Array<String>]
+    def categories
+      self["categories"].filter_map { _2 ? _1 : nil }
+    end
+
+    ##
+    # Returns the moderation scores
+    # @return [Hash]
+    def scores
+      self["category_scores"].select { |(key, _)| categories.include?(key) }.to_h
+    end
+  end
+end

data/lib/llm/shell/internal/llm.rb/lib/llm/providers/openai/response/responds.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module LLM::OpenAI::Response
+  module Responds
+    def model = body.model
+    def response_id = respond_to?(:response) ? response["id"] : id
+    def choices = [format_message]
+    def annotations = choices[0].annotations
+
+    def prompt_tokens = body.usage&.input_tokens
+    def completion_tokens = body.usage&.output_tokens
+    def total_tokens = body.usage&.total_tokens
+
+    ##
+    # Returns the aggregated text content from the response outputs.
+    # @return [String]
+    def output_text
+      choices.find(&:assistant?).content || ""
+    end
+
+    private
+
+    def format_message
+      message = LLM::Message.new("assistant", +"", {response: self, tool_calls: []})
+      output.each.with_index do |choice, index|
+        if choice.type == "function_call"
+          message.extra[:tool_calls] << format_tool(choice)
+        elsif choice.content
+          choice.content.each do |c|
+            next unless c["type"] == "output_text"
+            message.content << c["text"] << "\n"
+            next unless c["annotations"]
+            message.extra["annotations"] = [*message.extra["annotations"], *c["annotations"]]
+          end
+        end
+      end
+      message
+    end
+
+    def format_tool(tool)
+      LLM::Object.new(
+        id: tool.call_id,
+        name: tool.name,
+        arguments: JSON.parse(tool.arguments)
+      )
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module LLM::OpenAI::Response
+  ##
+  # The {LLM::OpenAI::Response::WebSearch LLM::OpenAI::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(
+        choices[0]
+          .annotations
+          .map { _1.slice(:title, :url) }
+      )
+    end
+  end
+end

data/lib/llm/shell/internal/llm.rb/lib/llm/providers/openai/responses/stream_parser.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+class LLM::OpenAI
+  ##
+  # @private
+  class Responses::StreamParser
+    ##
+    # Returns the fully constructed response body
+    # @return [LLM::Object]
+    attr_reader :body
+
+    ##
+    # @param [#<<] io An IO-like object
+    # @return [LLM::OpenAI::Responses::StreamParser]
+    def initialize(io)
+      @body = LLM::Object.new(output: []) # Initialize with an empty output array
+      @io = io
+    end
+
+    ##
+    # @param [Hash] chunk
+    # @return [LLM::OpenAI::Responses::StreamParser]
+    def parse!(chunk)
+      tap { handle_event(chunk) }
+    end
+
+    private
+
+    def handle_event(chunk)
+      case chunk["type"]
+      when "response.created"
+        chunk.each do |k, v|
+          next if k == "type"
+          @body[k] = v
+        end
+        @body.output ||= []
+      when "response.output_item.added"
+        output_index = chunk["output_index"]
+        item = LLM::Object.from_hash(chunk["item"])
+        @body.output[output_index] = item
+        @body.output[output_index].content ||= []
+      when "response.content_part.added"
+        output_index = chunk["output_index"]
+        content_index = chunk["content_index"]
+        part = LLM::Object.from_hash(chunk["part"])
+        @body.output[output_index] ||= LLM::Object.new(content: [])
+        @body.output[output_index].content ||= []
+        @body.output[output_index].content[content_index] = part
+      when "response.output_text.delta"
+        output_index = chunk["output_index"]
+        content_index = chunk["content_index"]
+        delta_text = chunk["delta"]
+        output_item = @body.output[output_index]
+        if output_item&.content
+          content_part = output_item.content[content_index]
+          if content_part && content_part.type == "output_text"
+            content_part.text ||= ""
+            content_part.text << delta_text
+            @io << delta_text if @io.respond_to?(:<<)
+          end
+        end
+      when "response.output_item.done"
+        output_index = chunk["output_index"]
+        item = LLM::Object.from_hash(chunk["item"])
+        @body.output[output_index] = item
+      when "response.content_part.done"
+        output_index = chunk["output_index"]
+        content_index = chunk["content_index"]
+        part = LLM::Object.from_hash(chunk["part"])
+        @body.output[output_index] ||= LLM::Object.new(content: [])
+        @body.output[output_index].content ||= []
+        @body.output[output_index].content[content_index] = part
+      end
+    end
+  end
+end

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

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+class LLM::OpenAI
+  ##
+  # The {LLM::OpenAI::Responses LLM::OpenAI::Responses} class provides
+  # an interface for [OpenAI's response API](https://platform.openai.com/docs/guides/conversation-state?api-mode=responses).
+  #
+  # @example example #1
+  #   #!/usr/bin/env ruby
+  #   require "llm"
+  #
+  #   llm = LLM.openai(key: ENV["KEY"])
+  #   res1 = llm.responses.create "Your task is to answer the user's questions", role: :developer
+  #   res2 = llm.responses.create "5 + 5 = X ?", role: :user, previous_response_id: res1.id
+  #   [res1, res2].each { llm.responses.delete(_1) }
+  class Responses
+    require_relative "response/responds"
+    require_relative "responses/stream_parser"
+    include Format
+
+    ##
+    # Returns a new Responses object
+    # @param provider [LLM::Provider]
+    # @return [LLM::OpenAI::Responses]
+    def initialize(provider)
+      @provider = provider
+    end
+
+    ##
+    # Create a response
+    # @see https://platform.openai.com/docs/api-reference/responses/create OpenAI docs
+    # @param prompt (see LLM::Provider#complete)
+    # @param params (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 create(prompt, params = {})
+      params = {role: :user, model: @provider.default_model}.merge!(params)
+      tools  = resolve_tools(params.delete(:tools))
+      params = [params, format_schema(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/responses", headers)
+      messages = [*(params.delete(:input) || []), LLM::Message.new(role, prompt)]
+      body = JSON.dump({input: [format(messages, :response)].flatten}.merge!(params))
+      set_body_stream(req, StringIO.new(body))
+      res = execute(request: req, stream:, stream_parser:)
+      LLM::Response.new(res)
+        .extend(LLM::OpenAI::Response::Responds)
+        .extend(Module.new { define_method(:__tools__) { tools } })
+    end
+
+    ##
+    # Get a response
+    # @see https://platform.openai.com/docs/api-reference/responses/get OpenAI docs
+    # @param [#id, #to_s] response Response ID
+    # @raise (see LLM::Provider#request)
+    # @return [LLM::Response]
+    def get(response, **params)
+      response_id = response.respond_to?(:id) ? response.id : response
+      query = URI.encode_www_form(params)
+      req = Net::HTTP::Get.new("/v1/responses/#{response_id}?#{query}", headers)
+      res = execute(request: req)
+      LLM::Response.new(res).extend(LLM::OpenAI::Response::Responds)
+    end
+
+    ##
+    # Deletes a response
+    # @see https://platform.openai.com/docs/api-reference/responses/delete OpenAI docs
+    # @param [#id, #to_s] response Response ID
+    # @raise (see LLM::Provider#request)
+    # @return [LLM::Object] Response body
+    def delete(response)
+      response_id = response.respond_to?(:id) ? response.id : response
+      req = Net::HTTP::Delete.new("/v1/responses/#{response_id}", headers)
+      res = execute(request: req)
+      LLM::Response.new(res)
+    end
+
+    private
+
+    [:headers, :execute, :set_body_stream, :resolve_tools].each do |m|
+      define_method(m) { |*args, **kwargs, &b| @provider.send(m, *args, **kwargs, &b) }
+    end
+
+    def format_schema(params)
+      return {} unless params && params[:schema]
+      schema = params.delete(:schema)
+      schema = schema.to_h.merge(additionalProperties: false)
+      name = "JSONSchema"
+      {text: {format: {type: "json_schema", name:, schema:}}}
+    end
+
+    def stream_parser
+      LLM::OpenAI::Responses::StreamParser
+    end
+  end
+end