llm.rb 11.3.1 → 12.1.0

data/lib/llm/providers/xai/images.rb

@@ -4,30 +4,21 @@ class LLM::XAI
   ##
   # The {LLM::XAI::Images LLM::XAI::Images} class provides an interface
   # for [xAI's images API](https://docs.x.ai/docs/guides/image-generations).
-  # xAI supports multiple response formats: temporary URLs, or binary strings
-  # encoded in base64. The default is to return base64-encoded image data.
+  # xAI returns base64-encoded image data.
   #
-  # @example Temporary URLs
+  # @example
   #   #!/usr/bin/env ruby
   #   require "llm"
-  #   require "open-uri"
-  #   require "fileutils"
   #
   #   llm = LLM.xai(key: ENV["KEY"])
-  #   res = llm.images.create prompt: "A dog on a rocket to the moon",
-  #                        response_format: "url"
-  #   FileUtils.mv OpenURI.open_uri(res.urls[0]).path,
-  #                "rocket.png"
-  #
-  # @example Binary strings
-  #   #!/usr/bin/env ruby
-  #   require "llm"
-  #
-  #   llm = LLM.xai(key: ENV["KEY"])
-  #   res = llm.images.create prompt: "A dog on a rocket to the moon",
-  #                           response_format: "b64_json"
+  #   res = llm.images.create prompt: "A dog on a rocket to the moon"
   #   IO.copy_stream res.images[0], "rocket.png"
   class Images < LLM::OpenAI::Images
+    ##
+    # @api private
+    PATTERN = %r{\A(?:https?://|data:)}
+    private_constant :PATTERN
+
     ##
     # Create an image
     # @example
@@ -40,20 +31,52 @@ class LLM::XAI
     # @param [Hash] params Other parameters (see xAI docs)
     # @raise (see LLM::Provider#request)
     # @return [LLM::Response]
-    def create(prompt:, model: "grok-imagine-image", **params)
-      super
+    def create(prompt:, model: "grok-imagine-image-quality", **params)
+      req = LLM::Transport::Request.post(path("/images/generations"), headers)
+      req.body = LLM.json.dump({prompt:, n: 1, model:, response_format: "b64_json"}.merge!(params))
+      res, span, tracer = execute(request: req, operation: "request")
+      res = LLM::OpenAI::ResponseAdapter.adapt(res, type: :image)
+      tracer.on_request_finish(operation: "request", model:, res:, span:)
+      res
     end
 
     ##
-    # @raise [NotImplementedError]
-    def edit(model: "grok-imagine-image", **)
-      raise NotImplementedError
+    # Edit an image
+    # @example
+    #   llm = LLM.xai(key: ENV["KEY"])
+    #   res = llm.images.edit(image: "/images/book.png", prompt: "The book is floating in the clouds")
+    #   IO.copy_stream res.images[0], "floating-book.png"
+    # @see https://docs.x.ai/docs/guides/image-generations xAI docs
+    # @param [String, LLM::File, File] image The image to edit
+    # @param [String] prompt The prompt
+    # @param [String] model The model to use
+    # @param [Hash] params Other parameters (see xAI docs)
+    # @raise (see LLM::Provider#request)
+    # @return [LLM::Response]
+    def edit(image:, prompt:, model: "grok-imagine-image-quality", **params)
+      req = LLM::Transport::Request.post(path("/images/edits"), headers)
+      req.body = LLM.json.dump({
+        prompt:,
+        model:,
+        image: image_url(image),
+        response_format: "b64_json"
+      }.merge!(params))
+      res, span, tracer = execute(request: req, operation: "request")
+      res = LLM::OpenAI::ResponseAdapter.adapt(res, type: :image)
+      tracer.on_request_finish(operation: "request", model:, res:, span:)
+      res
     end
 
-    ##
-    # @raise [NotImplementedError]
-    def create_variation(model: "grok-imagine-image", **)
-      raise NotImplementedError
+    private
+
+    def image_url(image)
+      case image
+      when String
+        url = image.match?(PATTERN) ? image : LLM.File(image).to_data_uri
+      else
+        url = LLM.File(image).to_data_uri
+      end
+      {url:, type: "image_url"}
     end
   end
 end

data/lib/llm/providers/xai.rb

@@ -70,10 +70,10 @@ module LLM
 
     ##
     # Returns the default model for chat completions
-    # #see https://docs.x.ai/docs/models grok-4-0709
+    # #see https://docs.x.ai/docs/models grok-4.3
     # @return [String]
     def default_model
-      "grok-4-0709"
+      "grok-4.3"
     end
   end
 end

data/lib/llm/repl/input.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+class LLM::Repl
+  ##
+  # The {LLM::Repl::Input LLM::Repl::Input} class manages
+  # the editable input line shown at the bottom of the REPL.
+  # @api private
+  class Input
+    UP        = Curses::Key::UP
+    DOWN      = Curses::Key::DOWN
+    ENTER     = [Curses::Key::ENTER, 10, 13]
+    BACKSPACE = [Curses::Key::BACKSPACE, 127]
+    EOF       = [nil, 4]
+
+    ##
+    # @param [String, Symbol] provider
+    # @return [LLM::Repl::Input]
+    def initialize(provider)
+      @provider = provider
+      @buffer = +""
+    end
+
+    ##
+    # @param [LLM::Repl::Window] window
+    # @return [String, nil]
+    def readline(window)
+      catch(:done) do
+        @buffer.clear
+        loop do
+          on_char(window, window.getch)
+          window.redraw
+        end
+      end
+    end
+
+    ##
+    # @return [String]
+    def to_s
+      "> #{@buffer}"
+    end
+
+    private
+
+    def on_char(window, char)
+      if EOF.include?(char)
+        throw(:done, nil)
+      elsif BACKSPACE.include?(char)
+        @buffer.chop!
+      elsif ENTER.include?(char)
+        buf = @buffer.dup
+        @buffer.clear
+        throw(:done, buf)
+      elsif char == UP
+        window.scroll_up
+      elsif char == DOWN
+        window.scroll_down
+      elsif String === char
+        @buffer << char
+      else
+        # ???
+      end
+    end
+  end
+end

data/lib/llm/repl/status.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+class LLM::Repl
+  ##
+  # The {LLM::Repl::Status LLM::Repl::Status} class stores
+  # the small status line shown at the top of the REPL.
+  # @api private
+  class Status
+    ##
+    # @param [String, Symbol] provider
+    # @return [LLM::Repl::Status]
+    def initialize(provider)
+      @provider = provider
+      @text = "idle"
+    end
+
+    ##
+    # @return [String]
+    attr_reader :provider
+
+    ##
+    # @param [String] value
+    # @return [void]
+    attr_accessor :text
+
+    ##
+    # @return [String]
+    alias_method :to_s, :text
+  end
+end

data/lib/llm/repl/stream.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+class LLM::Repl
+  ##
+  # The {LLM::Repl::Stream LLM::Repl::Stream} class manages
+  # the stream for the {LLM::Repl LLM::Repl} class. This class
+  # has defined hooks that receive text, tool calls, and
+  # tool returns.
+  # @api private
+  class Stream < LLM::Stream
+    ##
+    # @param [LLM::Repl] repl
+    # @return [LLM::Repl::Stream]
+    def initialize(repl)
+      @repl = repl
+    end
+
+    ##
+    # @param [String] chars
+    #  One or more chars
+    # @return [void]
+    def on_content(chars)
+      @repl.write(chars)
+    end
+
+    ##
+    # @param [LLM::Function] tool
+    # @param [LLM::Function::Return, nil] error
+    # @return [void]
+    def on_tool_call(tool, error)
+      if error
+        @repl.status = "tool error: #{tool.name}"
+      else
+        @repl.status = "tool: #{tool.name}"
+      end
+    end
+
+    ##
+    # @param [LLM::Function] _tool
+    # @param [LLM::Function::Return] result
+    # @return [void]
+    def on_tool_return(_tool, result)
+      @repl.status = "tool done: #{result.name}"
+    end
+  end
+end

data/lib/llm/repl/transcript.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+class LLM::Repl
+  ##
+  # The {LLM::Repl::Transcript LLM::Repl::Transcript} class
+  # stores streamed output for the REPL.
+  # @api private
+  class Transcript
+    WIDTH = 80
+
+    ##
+    # @return [LLM::Repl::Transcript]
+    def initialize
+      @lines = [+""]
+      @offset = 0
+    end
+
+    ##
+    # @param [String] chars
+    # @return [void]
+    def write(chars)
+      chars.each_char { write_char(_1) }
+    end
+
+    ##
+    # @return [void]
+    def scroll_up(height)
+      max = [@lines.size - height, 0].max
+      @offset = [@offset + 1, max].min
+    end
+
+    ##
+    # @return [void]
+    def scroll_down
+      @offset = [@offset - 1, 0].max
+    end
+
+    ##
+    # @param [Integer] height
+    # @return [Array<String>]
+    def visible(height)
+      last = @lines.size - 1 - @offset
+      first = [last - height + 1, 0].max
+      @lines[first..last] || []
+    end
+
+    private
+
+    def write_char(char)
+      if char == "\n"
+        @offset += 1 if @offset > 0
+        @lines << +""
+      elsif char == " " and @lines.last.length >= WIDTH
+        @offset += 1 if @offset > 0
+        @lines << +""
+      else
+        @lines.last << char
+      end
+    end
+  end
+end

data/lib/llm/repl/window.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+class LLM::Repl
+  ##
+  # The {LLM::Repl::Window LLM::Repl::Window} class draws the
+  # curses screen for the REPL.
+  # @api private
+  class Window
+    ##
+    # @return [LLM::Repl::Status]
+    attr_reader :status
+
+    ##
+    # @return [LLM::Repl::Transcript]
+    attr_reader :transcript
+
+    ##
+    # @return [LLM::Repl::Input]
+    attr_reader :input
+
+    ##
+    # @param [LLM::Repl::Status] status
+    # @param [LLM::Repl::Transcript] transcript
+    # @param [LLM::Repl::Input] input
+    # @return [LLM::Repl::Window]
+    def initialize(status, transcript, input)
+      @status = status
+      @transcript = transcript
+      @input = input
+    end
+
+    ##
+    # @yield
+    # @return [void]
+    def open
+      Curses.init_screen
+      Curses.cbreak
+      Curses.noecho
+      Curses.stdscr.keypad(true)
+      yield
+    ensure
+      Curses.close_screen
+    end
+
+    ##
+    # @return [void]
+    def redraw
+      Curses.clear
+      draw_status
+      draw_transcript
+      draw_input
+      Curses.refresh
+    end
+
+    ##
+    # @return [Integer]
+    def rows
+      [Curses.lines - 3, 1].max
+    end
+
+    ##
+    # @return [Object]
+    def getch
+      Curses.getch
+    end
+
+    ##
+    # @return [void]
+    def scroll_up
+      transcript.scroll_up(rows)
+    end
+
+    ##
+    # @return [void]
+    def scroll_down
+      transcript.scroll_down
+    end
+
+    private
+
+    def draw_status
+      Curses.setpos(0, 0)
+      Curses.addstr(status.to_s)
+      provider = status.provider.to_s
+      Curses.setpos(0, [columns - provider.length, 0].max)
+      Curses.addstr(provider)
+    end
+
+    def draw_transcript
+      visible = transcript.visible(rows)
+      visible.each_with_index do |row, index|
+        Curses.setpos(index + 2, 0)
+        Curses.addstr(row)
+      end
+    end
+
+    def draw_input
+      Curses.setpos(Curses.lines - 1, 0)
+      Curses.clrtoeol
+      Curses.addstr(input.to_s)
+    end
+
+    def columns
+      Curses.cols
+    end
+  end
+end

data/lib/llm/repl.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+LLM.require "curses"
+
+module LLM
+  ##
+  # The {LLM::Repl LLM::Repl} class provides a small
+  # read-eval-print loop around an instance of
+  # {LLM::Agent LLM::Agent}.
+  #
+  # It can be used to keep talking to an agent after it
+  # has been set up or has performed a task. This can be
+  # useful when you want to confirm the agent handled the
+  # task correctly, or for it to correct course after a
+  # mistake was made.
+  class Repl
+    require_relative "repl/window"
+    require_relative "repl/status"
+    require_relative "repl/transcript"
+    require_relative "repl/input"
+    require_relative "repl/stream"
+
+    ##
+    # @param [LLM::Agent] agent
+    # @return [LLM::Repl]
+    def initialize(agent)
+      @agent = agent
+      @provider = agent.llm.name
+      @status = Status.new(@provider)
+      @transcript = Transcript.new
+      @input = Input.new(@provider)
+      @window = Window.new(@status, @transcript, @input)
+      @stream = Stream.new(self)
+    end
+
+    ##
+    # @return [void]
+    def start
+      window.open do
+        loop do
+          window.redraw
+          text = input.readline(window)
+          break if text.nil?
+          next if text.empty?
+          status.text = "thinking"
+          write("user: #{text}\n")
+          window.redraw
+          write("agent: ")
+          agent.talk(text, stream:)
+          status.text = "idle"
+          write("\n\n")
+        end
+      end
+    end
+
+    ##
+    # @param [String] chars
+    # @return [void]
+    def write(chars)
+      transcript.write(chars)
+      window.redraw
+    end
+
+    ##
+    # @param [String] value
+    # @return [void]
+    def status=(value)
+      status.text = value
+      window.redraw
+    end
+
+    private
+
+    attr_reader :agent, :provider, :stream,
+                :status, :transcript, :input,
+                :window
+  end
+end

data/lib/llm/response.rb

@@ -56,6 +56,16 @@ module LLM
       @res.success?
     end
 
+    ##
+    # Returns the provider response id when present.
+    # @return [String, nil]
+    def id
+      return nil unless LLM::Object === body
+      body.id          ||
+      body.responseId  || body.response_id ||
+      body.requestId   || body.request_id
+    end
+
     ##
     # Returns true if the response is from the Files API
     # @return [Boolean]

data/lib/llm/schema/leaf.rb

@@ -95,7 +95,7 @@ class LLM::Schema
     ##
     # @return [Hash]
     def to_h
-      {description: @description, default: @default, enum: @enum}.compact
+      {description: @description, default: @default, enum: @enum, const: @const}.compact
     end
 
     ##
@@ -104,6 +104,12 @@ class LLM::Schema
       to_h.to_json(options)
     end
 
+    ##
+    # @return [String]
+    def to_s
+      LLM::Schema::Renderer.render(self)
+    end
+
     ##
     # @param [LLM::Schema::Leaf] other
     #  An object to compare

data/lib/llm/schema/renderer.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+class LLM::Schema
+  ##
+  # Internal renderer for prompt-friendly schema output.
+  # @api private
+  module Renderer
+    extend self
+
+    ##
+    # Render a schema node as a human-readable string.
+    # @param [LLM::Schema::Leaf] node
+    #  The schema node to render
+    # @param [Integer] indent
+    #  The indentation level
+    # @param [String, Symbol, nil] name
+    #  The property name for nested nodes
+    # @param [Boolean] root
+    #  Whether the node is the root schema object
+    # @return [String]
+    def render(node, indent: 0, name: nil, root: false)
+      line = (" " * indent).to_s
+      if name
+        line << name.to_s
+        line << "?" unless node.required?
+        line << ": "
+      end
+      line << type_name(node)
+      metadata = metadata_for(node, include_required: !root)
+      line << " (#{metadata.join(", ")})" unless metadata.empty?
+      line << " - #{node.description}" if node.respond_to?(:description) && node.description
+      nested = nested_lines(node, indent: indent + 2)
+      ([line] + nested).join("\n")
+    end
+
+    private
+
+    ##
+    # Render nested lines for compound schema nodes.
+    # @param [LLM::Schema::Leaf] node
+    #  The schema node
+    # @param [Integer] indent
+    #  The indentation level
+    # @return [Array<String>]
+    def nested_lines(node, indent:)
+      case node
+      when LLM::Schema::Object
+        node.properties.map { |key, val| render(val, indent:, name: key) }
+      when LLM::Schema::Array
+        items = node.to_h[:items]
+        items.is_a?(LLM::Schema::Object) ? [render(items, indent:, name: "items")] : []
+      else
+        []
+      end
+    end
+
+    ##
+    # Return the printable type name for a schema node.
+    # @param [LLM::Schema::Leaf] node
+    #  The schema node
+    # @return [String]
+    def type_name(node)
+      h = node.to_h
+      return "array<#{inline_type(h[:items])}>" if node.is_a?(LLM::Schema::Array)
+      return "anyOf<#{inline_types(h[:anyOf])}>" if node.is_a?(LLM::Schema::AnyOf)
+      return "oneOf<#{inline_types(h[:oneOf])}>" if node.is_a?(LLM::Schema::OneOf)
+      return "allOf<#{inline_types(h[:allOf])}>" if node.is_a?(LLM::Schema::AllOf)
+      h[:type] || "unknown"
+    end
+
+    ##
+    # Return the inline type description for a nested node.
+    # @param [LLM::Schema::Leaf, Object] node
+    #  The nested schema node
+    # @return [String]
+    def inline_type(node)
+      return type_name(node) if node.is_a?(LLM::Schema::Leaf)
+      node.inspect
+    end
+
+    ##
+    # Return the inline type description for a list of nodes.
+    # @param [Array<LLM::Schema::Leaf>] values
+    #  The union members
+    # @return [String]
+    def inline_types(values)
+      values.map { inline_type(_1) }.join(", ")
+    end
+
+    ##
+    # Extract printable metadata for a schema node.
+    # @param [LLM::Schema::Leaf] node
+    #  The schema node
+    # @param [Boolean] include_required
+    #  Whether to include the required marker
+    # @return [Array<String>]
+    def metadata_for(node, include_required:)
+      h = node.to_h.dup
+      details = []
+      details << "required" if include_required && node.required?
+      details << "default: #{value(node.default)}" if node.default
+      details << "enum: #{node.enum.map { value(_1) }.join(" | ")}" if node.enum
+      details << "const: #{value(node.const)}" if node.const
+      h.except(:type, :description, :default, :enum, :const, :required, :properties, :items, :anyOf, :oneOf, :allOf)
+        .each { |key, val| details << "#{key}: #{value(val)}" }
+      details
+    end
+
+    ##
+    # Convert a scalar value into its printable representation.
+    # @param [Object] val
+    #  The value to render
+    # @return [String]
+    def value(val)
+      case val
+      when ::String then val.inspect
+      else val.to_s
+      end
+    end
+  end
+end