llm.rb 13.1.0 → 14.0.0

data/lib/llm/guard/loop.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+class LLM::Guard
+  ##
+  # {LLM::Guard::Loop LLM::Guard::Loop} is the built-in loop-detection
+  # guard. It detects when a context is repeating the same tool-call
+  # pattern instead of making progress, and returns an in-band
+  # {LLM::Function::Return LLM::Function::Return} so {LLM::Context
+  # LLM::Context} can block the pending tool work.
+  class Loop < self
+    ##
+    # The default number of repeated tool-call patterns required before
+    # the guard intervenes.
+    # @return [Integer]
+    DEFAULT_THRESHOLD = 3
+
+    ##
+    # Checks the current context for repeated tool-call patterns.
+    #
+    # This method inspects assistant tool calls only. It reduces each call
+    # to a `[tool_name, arguments]` signature and checks whether the tail
+    # of the sequence is repeating.
+    #
+    # @param [LLM::Function] function
+    #  The pending function being decided about. Only its id and name are
+    #  used to build the return.
+    # @param [Integer] threshold
+    #  How many repeated tool-call patterns must appear at the tail of the
+    #  sequence before the guard returns a warning.
+    # @param [Hash] opts
+    #  Additional per-call options (ignored).
+    # @return [LLM::Function::Return, nil]
+    #  Returns a tool return that blocks this function's pending call, or
+    #  nil when execution should continue.
+    def call(function:, threshold: DEFAULT_THRESHOLD, **opts)
+      repetitions = detect(messages.to_a, threshold)
+      return unless repetitions
+      function.return(error: true, type: "guard_error", message: warning(repetitions))
+    end
+
+    private
+
+    def detect(messages, threshold)
+      signatures = extract_signatures(messages)
+      return if signatures.size < threshold
+      check_repeating_pattern(signatures, threshold)
+    end
+
+    def warning(repetitions)
+      <<~MSG
+        SYSTEM NOTICE: Repeated tool-call pattern detected - the same pattern has repeated #{repetitions} times.
+        You are stuck in a loop and not making progress. Stop and try a fundamentally different approach:
+        - Re-read the relevant context before retrying
+        - Try a different tool or strategy
+        - Break the problem into smaller steps
+        - If a tool keeps failing, investigate why before retrying
+      MSG
+    end
+
+    def extract_signatures(messages)
+      messages
+        .select(&:assistant?)
+        .flat_map { |message| message.functions.map { [_1.name.to_s, _1.arguments.to_h] } }
+    end
+
+    def check_repeating_pattern(sequence, threshold)
+      max_pattern_len = sequence.size / threshold
+      (1..max_pattern_len).each do |pattern_len|
+        count = count_tail_repetitions(sequence, pattern_len)
+        return count if count >= threshold
+      end
+      nil
+    end
+
+    def count_tail_repetitions(sequence, length)
+      return 0 if sequence.size < length
+      pattern = sequence.last(length)
+      count = 1
+      pos = sequence.size - length
+      while pos >= length
+        candidate = sequence[(pos - length)...pos]
+        break unless candidate == pattern
+        count += 1
+        pos -= length
+      end
+      count
+    end
+  end
+end

data/lib/llm/guard/null.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+class LLM::Guard
+  ##
+  # {LLM::Guard::Null LLM::Guard::Null} is a no-op guard. It never blocks
+  # pending tool work and is the default guard used by
+  # {LLM::Context LLM::Context}.
+  class Null < self
+    ##
+    # @param [LLM::Function] function
+    #  The pending function (ignored)
+    # @param [Hash] opts
+    #  Per-call options (ignored)
+    # @return [nil]
+    def call(function:, **opts)
+      nil
+    end
+  end
+end

data/lib/llm/guard.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module LLM
+  ##
+  # {LLM::Guard LLM::Guard} is the superclass for context-level
+  # supervisors in llm.rb.
+  #
+  # A guard is bound to a context and decides whether a tool call should
+  # be blocked before it runs. Each subclass implements {#call} and returns
+  # an {LLM::Function::Return LLM::Function::Return} that closes the
+  # pending tool call, or `nil` when execution should continue. The guard
+  # is stamped onto the functions the context binds, so it runs whenever a
+  # task is spawned — including tool calls queued from a stream. The
+  # built-in implementation is {LLM::Guard::Loop LLM::Guard::Loop}, which
+  # detects repeated tool-call patterns. {LLM::Guard::Null LLM::Guard::Null}
+  # is a no-op and the default.
+  #
+  # {LLM::Agent LLM::Agent} enables {LLM::Guard::Loop LLM::Guard::Loop}
+  # by default through its wrapped context.
+  class Guard
+    require_relative "guard/null"
+    require_relative "guard/loop"
+
+    ##
+    # @return [LLM::Context]
+    attr_reader :ctx
+
+    ##
+    # @param ctx [LLM::Context, LLM::Agent]
+    # @return [LLM::Guard]
+    def initialize(ctx)
+      @ctx = LLM::Agent === ctx ? ctx.instance_variable_get(:@ctx) : ctx
+    end
+
+    ##
+    # @abstract
+    # @param [LLM::Function] function
+    #  The pending function the guard is deciding about.
+    # @param opts [Hash] Per-call options
+    # @return [LLM::Function::Return, nil]
+    #  A tool return that closes this function's pending call when it
+    #  should be blocked, or nil when execution should continue.
+    def call(function:, **opts)
+      raise NotImplementedError
+    end
+
+    private
+
+    ##
+    # @return [LLM::Stream]
+    def stream
+      @ctx.params[:stream]
+    end
+
+    ##
+    # @return [LLM::Buffer]
+    def messages
+      @ctx.messages
+    end
+  end
+end

data/lib/llm/provider.rb

@@ -40,6 +40,42 @@ class LLM::Provider
     @monitor = Monitor.new
   end
 
+  ##
+  # Builds the outgoing message array for a turn. Normalizes the
+  # prompt into one or more {LLM::Message} objects and prepends
+  # the existing history.
+  #
+  # The method is idempotent. If the prompt is already an
+  # {LLM::Message} or an array of {LLM::Message}s (ie it was built
+  # by a previous call and possibly transformed), it is returned
+  # as-is without rebuilding.
+  #
+  # @param [String, Array, LLM::Message, LLM::Prompt] prompt
+  # @param [Hash] params
+  #  Turn params. The history is taken from `params[:messages]`.
+  # @param [Symbol] role
+  #  The role to assign to a raw prompt
+  # @param [Symbol] key
+  #  The params key that holds the history (`:messages` for chat
+  #  completions, `:input` for the responses API).
+  # @return [Array<LLM::Message>]
+  def build_messages(prompt, params, role, key: :messages)
+    case prompt
+    when LLM::Message
+      [prompt]
+    when Array
+      if prompt.all? { LLM::Message === _1 }
+        prompt
+      else
+        [*(params.delete(key) || []), LLM::Message.new(role, prompt)]
+      end
+    when LLM::Prompt
+      [*(params.delete(key) || []), *prompt.to_a]
+    else
+      [*(params.delete(key) || []), LLM::Message.new(role, prompt)]
+    end
+  end
+
   ##
   # Returns an inspection of the provider object
   # @return [String]

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

@@ -102,6 +102,7 @@ class LLM::Anthropic
         fn.arguments = LLM::Anthropic.parse_tool_input(tool["input"])
         fn.tracer = @stream.extra[:tracer]
         fn.model = @stream.extra[:model]
+        fn.guard = @stream.extra[:guard]
       end
       [fn, (registered ? nil : fn.unavailable)]
     end

data/lib/llm/providers/anthropic.rb

@@ -167,7 +167,7 @@ module LLM
     end
 
     def build_complete_request(prompt, params, role)
-      messages = build_complete_messages(prompt, params, role)
+      messages = build_messages(prompt, params, role)
       payload = adapt(messages)
       body = LLM.json.dump(payload.merge!(params))
       req = LLM::Transport::Request.post("/v1/messages", headers)
@@ -175,12 +175,5 @@ module LLM
       req
     end
 
-    def build_complete_messages(prompt, params, role)
-      if LLM::Prompt === prompt
-        [*(params.delete(:messages) || []), *prompt.to_a]
-      else
-        [*(params.delete(:messages) || []), Message.new(role, prompt)]
-      end
-    end
   end
 end

data/lib/llm/providers/bedrock/stream_parser.rb

@@ -181,6 +181,7 @@ class LLM::Bedrock
         f.arguments = payload["input"] || {}
         f.tracer = @stream.extra[:tracer]
         f.model = @stream.extra[:model]
+        f.guard = @stream.extra[:guard]
       end
       [fn, registered ? nil : fn.unavailable]
     end

data/lib/llm/providers/bedrock.rb

@@ -210,7 +210,7 @@ module LLM
     end
 
     def build_complete_request(prompt, params, role, stream: nil)
-      messages = build_complete_messages(prompt, params, role)
+      messages = build_messages(prompt, params, role)
       model_id = params.delete(:model) || default_model
       payload = build_converse_payload(messages, params)
       body = LLM.json.dump(payload)
@@ -221,13 +221,6 @@ module LLM
       [req, messages, body]
     end
 
-    def build_complete_messages(prompt, params, role)
-      if LLM::Prompt === prompt
-        [*(params.delete(:messages) || []), *prompt]
-      else
-        [*(params.delete(:messages) || []), Message.new(role, prompt)]
-      end
-    end
 
     def build_converse_payload(messages, params)
       adapted = adapt(messages)

data/lib/llm/providers/google/stream_parser.rb

@@ -150,6 +150,7 @@ class LLM::Google
         fn.arguments = call["args"]
         fn.tracer = @stream.extra[:tracer]
         fn.model = @stream.extra[:model]
+        fn.guard = @stream.extra[:guard]
       end
       [fn, (registered ? nil : fn.unavailable)]
     end

data/lib/llm/providers/google.rb

@@ -217,18 +217,11 @@ module LLM
       model.respond_to?(:id) ? model.id : model
       path = ["/v1beta/models/#{model}", action].join(":")
       req  = LLM::Transport::Request.post(path, headers)
-      messages = build_complete_messages(prompt, params, role)
+      messages = build_messages(prompt, params, role)
       body = LLM.json.dump({contents: adapt(messages)}.merge!(params))
       transport.set_body_stream(req, StringIO.new(body))
       req
     end
 
-    def build_complete_messages(prompt, params, role)
-      if LLM::Prompt === prompt
-        [*(params.delete(:messages) || []), *prompt.to_a]
-      else
-        [*(params.delete(:messages) || []), LLM::Message.new(role, prompt)]
-      end
-    end
   end
 end

data/lib/llm/providers/moonshot.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require_relative "openai" unless defined?(LLM::OpenAI)
+
+module LLM
+  ##
+  # The Moonshot class implements a provider for
+  # [Moonshot AI](https://platform.moonshot.ai) through its
+  # OpenAI-compatible Kimi API.
+  #
+  # @example
+  #   #!/usr/bin/env ruby
+  #   require "llm"
+  #
+  #   llm = LLM.moonshot(key: ENV["KEY"])
+  #   ctx = LLM::Context.new(llm)
+  #   ctx.talk "Hello"
+  class Moonshot < OpenAI
+    HOST = "api.moonshot.ai"
+    BASE_PATH = "/v1"
+
+    ##
+    # @param key (see LLM::Provider#initialize)
+    # @param host (see LLM::Provider#initialize)
+    # @param base_path (see LLM::Provider#initialize)
+    # @return [LLM::Moonshot]
+    def initialize(host: HOST, base_path: BASE_PATH, **)
+      super
+    end
+
+    ##
+    # @return [Symbol]
+    #  Returns the provider's name
+    def name
+      :moonshot
+    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://platform.moonshot.ai/docs/api/models-overview Kimi models
+    # @return [String]
+    def default_model
+      "kimi-k3"
+    end
+  end
+end

data/lib/llm/providers/ollama.rb

@@ -137,19 +137,12 @@ module LLM
     end
 
     def build_complete_request(prompt, params, role)
-      messages = build_complete_messages(prompt, params, role)
+      messages = build_messages(prompt, params, role)
       body = LLM.json.dump({messages: [adapt(messages)].flatten}.merge!(params))
       req = LLM::Transport::Request.post("/api/chat", headers)
       transport.set_body_stream(req, StringIO.new(body))
       req
     end
 
-    def build_complete_messages(prompt, params, role)
-      if LLM::Prompt === prompt
-        [*(params.delete(:messages) || []), *prompt.to_a]
-      else
-        [*(params.delete(:messages) || []), LLM::Message.new(role, prompt)]
-      end
-    end
   end
 end

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

@@ -265,6 +265,7 @@ class LLM::OpenAI
         fn.arguments = arguments
         fn.tracer = @stream.extra[:tracer]
         fn.model = @stream.extra[:model]
+        fn.guard = @stream.extra[:guard]
       end
       [fn, (registered ? nil : fn.unavailable)]
     end

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

@@ -44,8 +44,13 @@ class LLM::OpenAI
         adapt_tools(tools)
       ].inject({}, &:merge!).compact
       req = LLM::Transport::Request.post(path("/responses"), headers)
-      messages = build_complete_messages(prompt, params, role)
+      messages = @provider.build_messages(prompt, params, role, key: :input)
       @provider.tracer.set_request_metadata(user_input: extract_user_input(messages, fallback: prompt))
+      ##
+      # The input is derived from `prompt`/`messages` above; a
+      # stale `:input` passed in params (eg by LLM::Context) must
+      # not overwrite it in the request body.
+      params.delete(:input)
       body = LLM.json.dump({input: [adapt(messages, mode: :response)].flatten}.merge!(params))
       transport.set_body_stream(req, StringIO.new(body))
       res, span, tracer = execute(request: req, stream:, stream_parser:, operation: "chat", model: params[:model])
@@ -102,13 +107,6 @@ class LLM::OpenAI
       define_method(m) { |*args, **kwargs, &b| @provider.send(m, *args, **kwargs, &b) }
     end
 
-    def build_complete_messages(prompt, params, role)
-      if LLM::Prompt === prompt
-        [*(params.delete(:input) || []), *prompt]
-      else
-        [*(params.delete(:input) || []), LLM::Message.new(role, prompt)]
-      end
-    end
 
     def adapt_schema(params)
       return {} unless params && params[:schema]

data/lib/llm/providers/openai/stream_parser.rb

@@ -180,6 +180,7 @@ class LLM::OpenAI
         fn.arguments = arguments
         fn.tracer = @stream.extra[:tracer]
         fn.model = @stream.extra[:model]
+        fn.guard = @stream.extra[:guard]
       end
       [fn, (registered ? nil : fn.unavailable)]
     end

data/lib/llm/providers/openai.rb

@@ -146,10 +146,10 @@ module LLM
 
     ##
     # Returns the default model for chat completions
-    # @see https://platform.openai.com/docs/models/gpt-5.4-mini gpt-5.4-mini
+    # @see https://platform.openai.com/docs/models/gpt-5.6-luna gpt-5.6-luna
     # @return [String]
     def default_model
-      "gpt-5.4-mini"
+      "gpt-5.6-luna"
     end
 
     ##
@@ -230,20 +230,13 @@ module LLM
     end
 
     def build_complete_request(prompt, params, role)
-      messages = build_complete_messages(prompt, params, role)
+      messages = build_messages(prompt, params, role)
       body = LLM.json.dump({messages: adapt(messages, mode: :complete).flatten}.merge!(params))
       req = LLM::Transport::Request.post(completions_path, headers)
       transport.set_body_stream(req, StringIO.new(body))
       [req, messages]
     end
 
-    def build_complete_messages(prompt, params, role)
-      if LLM::Prompt === prompt
-        [*(params.delete(:messages) || []), *prompt]
-      else
-        [*(params.delete(:messages) || []), Message.new(role, prompt)]
-      end
-    end
 
     def extract_user_input(messages, fallback:)
       message = messages.reverse.find(&:user?) || messages.last

data/lib/llm/repl/bar.rb

@@ -17,7 +17,8 @@ class LLM::Repl
     FREE = " "
 
     ##
-    # @param [Integer] used
+    # @param [Integer, nil] used
+    #  The used context, or nil when it is unknown (eg after compaction).
     # @param [Integer] total
     # @param [Integer] width
     # @return [LLM::Repl::Bar]
@@ -36,11 +37,11 @@ class LLM::Repl
     private
 
     ##
-    # @param [Integer] used
+    # @param [Integer, nil] used
     # @param [Integer] total
     # @return [[String, Integer]]
     def remainder(used, total)
-      return ["???", width] if total <= 0
+      return ["???", width] if used.nil? || total <= 0
       diff = total - used
       return ["0%", 0] if diff <= 0
       remaining = (diff.fdiv(total) * 100).round(2)

data/lib/llm/repl/buffer.rb

@@ -20,7 +20,8 @@ class LLM::Repl
     #  An instance of {LLM::Repl LLM::Repl}.
     # @return [LLM::Repl::Buffer]
     def initialize(repl)
-      @repl = repl
+      @repl   = repl
+      @window = repl.window
       @rows = [[]]
       @cursor = nil
       @snapshot = nil
@@ -46,12 +47,12 @@ class LLM::Repl
     # @param [Symbol] method
     # @return [void]
     def write_message(user, content, method: :append)
-      chunks = [Node.new("#{user}: ", Curses::A_BOLD)]
+      chunks = [Node.new("#{user}:\n", Curses::A_BOLD | Color.blue)]
       case content
       when Array then chunks.concat(content)
       else chunks.push(Node.new(content))
       end
-      chunks.push(Node.new("\n"))
+      chunks.push(Node.new("\n\n"))
       write(chunks, method:)
     end
 
@@ -90,6 +91,15 @@ class LLM::Repl
       @offset = 0
     end
 
+    ##
+    # The width of the centered content area -
+    # with 20% on each side. The rest makes up
+    # the width of the buffer.
+    # @return [Integer]
+    def width
+      (Curses.cols * 0.6).floor
+    end
+
     ##
     # @param [Integer] height
     # @return [Array<String>]
@@ -103,8 +113,8 @@ class LLM::Repl
     private
 
     ##
-    # @return [LLM::Repl]
-    attr_reader :repl
+    # @api private
+    attr_reader :repl, :window
 
     ##
     # Appends a new row
@@ -126,20 +136,37 @@ class LLM::Repl
     end
 
     ##
-    # Given a chunk this method wraps text at
-    # around 80 columns: a new row starts when
-    # the current character is " " and the sum
-    # of all characters in that row is greater
-    # than 80 columns.
+    # Given a chunk this method wraps text to the buffer's
+    # width. The text is split into words; a word that does
+    # not fit on the current row moves to the next. Only a
+    # single word longer than the whole width is hard-broken,
+    # so text is never clipped by the window.
     def wrap(chunk, rows)
       attrs = chunk[:attrs]
-      chunk[:text].to_s.each_char do |char|
-        if char == "\n"
-          rows << []
-        elsif char == " " and sum(rows.last) >= repl.width
+      chunk[:text].to_s.scan(/\n|[^\s]+|\s+/) do |token|
+        if token == "\n"
           rows << []
+        elsif token.match?(/\s/)
+          if sum(rows.last) + token.length <= width
+            rows.last << Node.new(token, attrs)
+          end
+        elsif sum(rows.last) + token.length > width
+          if sum(rows.last) == 0
+            ##
+            # A single word wider than the row: break it
+            # every width characters.
+            token.scan(/.{1,#{width}}/).each do |piece|
+              rows.last << Node.new(piece, attrs)
+              if sum(rows.last) >= width
+                rows << []
+              end
+            end
+          else
+            rows << []
+            rows.last << Node.new(token, attrs)
+          end
         else
-          rows.last << Node.new(char, attrs)
+          rows.last << Node.new(token, attrs)
         end
       end
     end