llm.rb 13.0.0 → 14.0.0

data/lib/llm/tools/ruby.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+class LLM::Tool
+  ##
+  # The {LLM::Tool::Ruby LLM::Tool::Ruby} class implements
+  # a tool that can execute an arbitrary string of Ruby code
+  # and return the result. It uses `test-cmd.rb` under the
+  # hood for process management.
+  class Ruby < self
+    require_relative "utils"
+    include Utils
+
+    name "ruby"
+    description "runs a string of ruby code"
+    parameter :code, String, "a string of ruby code"
+    parameter :timeout, Integer, "maximum runtime before timeout"
+    required %i[code]
+    defaults timeout: 15
+
+    ##
+    # @param [String] code
+    #  Ruby code
+    # @param [Integer] timeout
+    #  Runtime timeout
+    def call(code:, timeout: 15)
+      command = spawn(code:)
+      wait(command:, timeout:)
+      {ok: command.success?, stdout: command.stdout, stderr: command.stderr}
+    rescue LLM::Interrupt
+      command.kill! if command&.running?
+      raise
+    end
+
+    private
+
+    def spawn(code:)
+      Command
+        .new(RbConfig.ruby)
+        .argv("-e", code)
+    end
+
+    require "rbconfig"
+    LLM.require "test-cmd.rb", "~> 1.1"
+    Command = Test::Cmd
+  end
+end

data/lib/llm/tools/shell.rb

@@ -31,6 +31,9 @@ class LLM::Tool
       command = spawn(name:, arguments:)
       wait(command:, timeout:)
       {ok: command.success?, stdout: command.stdout, stderr: command.stderr}
+    rescue LLM::Interrupt
+      command.kill! if command&.running?
+      raise
     end
 
     private

data/lib/llm/tracer/pretty_logger.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module LLM
+  ##
+  # The {LLM::Tracer::PrettyLogger LLM::Tracer::PrettyLogger} class
+  # writes human-readable request and tool call logs to a console
+  # or file. Each event is a single line with the relevant context
+  # inline, no structured JSON.
+  #
+  # @example
+  #   llm = LLM.openai(key: ENV["KEY"])
+  #   llm.tracer = LLM::Tracer::PrettyLogger.new(llm)
+  #
+  # @example Writing to a file
+  #   llm.tracer = LLM::Tracer::PrettyLogger.new(llm, io: File.open("log.txt", "a"))
+  class Tracer::PrettyLogger < Tracer
+    ##
+    # @param (see LLM::Tracer#initialize)
+    def initialize(provider, options = {})
+      super
+      setup!(**options)
+    end
+
+    ##
+    # @param (see LLM::Tracer#on_request_start)
+    # @return [void]
+    def on_request_start(operation:, model: nil, **)
+      @start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      name = operation == "chat" ? "chat" : operation
+      @io.puts "#{timestamp} #{provider_name} #{name} (#{model || "default"})"
+    end
+
+    ##
+    # @param (see LLM::Tracer#on_request_finish)
+    # @return [void]
+    def on_request_finish(operation:, res:, model: nil, **)
+      elapsed = @start ? (Process.clock_gettime(Process::CLOCK_MONOTONIC) - @start).round(2) : nil
+      tokens = format_tokens(res)
+      name = operation == "chat" ? "chat" : operation
+      parts = ["#{timestamp} #{provider_name} #{name} done"]
+      parts << tokens if tokens
+      parts << "#{elapsed}s" if elapsed
+      @io.puts parts.join(", ")
+    end
+
+    ##
+    # @param (see LLM::Tracer#on_request_error)
+    # @return [void]
+    def on_request_error(ex:, **)
+      @io.puts "#{timestamp} #{provider_name} error #{ex.class}: #{ex.message}"
+    end
+
+    ##
+    # @param (see LLM::Tracer#on_tool_start)
+    # @return [void]
+    def on_tool_start(id:, name:, arguments:, **)
+      @io.puts "#{timestamp} #{name}(#{format_arguments(arguments)})"
+    end
+
+    ##
+    # @param (see LLM::Tracer#on_tool_finish)
+    # @return [void]
+    def on_tool_finish(result:, **)
+      @io.puts "#{timestamp} #{result.name} -> #{format_value(result.value)}"
+    end
+
+    ##
+    # @param (see LLM::Tracer#on_tool_error)
+    # @return [void]
+    def on_tool_error(ex:, **)
+      @io.puts "#{timestamp} tool error #{ex.class}: #{ex.message}"
+    end
+
+    private
+
+    def setup!(io: $stderr)
+      @io = io
+      @start = nil
+    end
+
+    def timestamp
+      Time.now.strftime("%H:%M:%S")
+    end
+
+    def format_tokens(res)
+      usage = res.usage
+      if usage.input_tokens and usage.output_tokens
+        "in=#{usage.input_tokens} out=#{usage.output_tokens}"
+      elsif usage.input_tokens
+        "in=#{usage.input_tokens}"
+      elsif usage.output_tokens
+        "out=#{usage.output_tokens}"
+      end
+    end
+
+    def format_arguments(args, max: 50)
+      return "" unless args
+      case args
+      when Hash, LLM::Object
+        result = args.map { |k, v| "#{k}: #{format_value(v)}" }.join(", ")
+      when Array
+        result = args.map { |v| format_value(v) }.join(", ")
+      else
+        result = args.inspect
+      end
+      result.size > max ? "#{result[0...max - 1]}..." : result
+    end
+
+    def format_value(value, max: 18)
+      case value
+      when String
+        value.size > max ? "#{value[0...max]}...".inspect : value.inspect
+      when Array
+        items = value.take(2).map { format_value(_1, max: 10) }
+        items << "..." if value.size > 2
+        "[#{items.join(", ")}]"
+      when Hash
+        "{...}"
+      when nil
+        "nil"
+      else
+        str = value.inspect
+        str.size > max ? "#{str[0...max]}..." : str
+      end
+    end
+  end
+end

data/lib/llm/tracer.rb

@@ -12,6 +12,7 @@ module LLM
     require_relative "tracer/logger"
     require_relative "tracer/telemetry"
     require_relative "tracer/null"
+    require_relative "tracer/pretty_logger"
 
     ##
     # @return [LLM::Provider]

data/lib/llm/transformer/null.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+class LLM::Transformer
+  ##
+  # An {LLM::Transformer::Null LLM::Transformer::Null} is a
+  # transformer that does nothing. It is used as the default when
+  # no transformer strategy is configured.
+  #
+  # It returns the given message unchanged.
+  class Null < self
+    ##
+    # @param [LLM::Message] message
+    #  The message to transform
+    # @param [Hash] opts
+    #  Ignored
+    # @return [LLM::Message]
+    def call(message:, **opts)
+      message
+    end
+  end
+end

data/lib/llm/transformer.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module LLM
+  ##
+  # {LLM::Transformer LLM::Transformer} is the superclass for
+  # message transformers in llm.rb.
+  #
+  # A transformer is bound to a context and rewrites a single
+  # message before it is sent to the provider. Each subclass
+  # implements a different transformation: it takes a message in
+  # {#call} and returns a message. {LLM::Transformer::Null} is a
+  # no-op (the default).
+  #
+  # A transformer may mutate the message in place or return a new
+  # one. Either way, the returned message is what gets sent.
+  class Transformer
+    require_relative "transformer/null"
+
+    ##
+    # @return [LLM::Context]
+    attr_reader :ctx
+
+    ##
+    # @param ctx [LLM::Context, LLM::Agent]
+    # @return [LLM::Transformer]
+    def initialize(ctx)
+      @ctx = LLM::Agent === ctx ? ctx.instance_variable_get(:@ctx) : ctx
+    end
+
+    ##
+    # @abstract
+    # @param [LLM::Message] message
+    #  The message to transform
+    # @param [Hash] opts
+    #  Per-call options
+    # @return [LLM::Message]
+    def call(message:, **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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module LLM
-  VERSION = "13.0.0"
+  VERSION = "14.0.0"
 end

data/lib/llm.rb

@@ -7,7 +7,7 @@
 #
 # @example The three-step workflow
 #   require "llm"
-#   llm = LLM.deepseek(key: ENV["KEY"])           # 1. pick a provider
+#   llm = LLM.deepseek(key: ENV["KEY"])            # 1. pick a provider
 #   agent = LLM::Agent.new(llm, stream: $stdout)   # 2. create an agent
 #   agent.talk "Hello world"                       # 3. talk to it
 #
@@ -17,6 +17,7 @@ module LLM
   require "stringio"
   require "securerandom"
   require_relative "llm/compactor"
+  require_relative "llm/transformer"
   require_relative "llm/json_adapter"
   require_relative "llm/tracer"
   require_relative "llm/error"
@@ -40,7 +41,7 @@ module LLM
   require_relative "llm/stream"
   require_relative "llm/provider"
   require_relative "llm/context"
-  require_relative "llm/loop_guard"
+  require_relative "llm/guard"
   require_relative "llm/agent"
   require_relative "llm/buffer"
   require_relative "llm/function"
@@ -218,6 +219,15 @@ module LLM
     LLM::ZAI.new(**)
   end
 
+  ##
+  # @param key (see LLM::Moonshot#initialize)
+  # @param host (see LLM::Moonshot#initialize)
+  # @return (see LLM::Moonshot#initialize)
+  def moonshot(**)
+    lock(:require) { require_relative "llm/providers/moonshot" unless defined?(LLM::Moonshot) }
+    LLM::Moonshot.new(**)
+  end
+
   ##
   # @param [Hash] opts
   #  MCP client options

data/llm.gemspec

@@ -12,7 +12,7 @@ Gem::Specification.new do |spec|
   spec.description = <<~DESCRIPTION
 llm.rb is an advanced runtime for building capable AI applications
 on CRuby. By default it has zero runtime dependencies although certain
-functionality &ndash; such as ActiveRecord support &ndash; require
+functionality (such as ActiveRecord support) require
 optional dependencies that are opt-in.
 DESCRIPTION
 
@@ -30,9 +30,16 @@ DESCRIPTION
     "lib/*.rb", "lib/**/*.rb",
     "data/*.json", "CHANGELOG.md",
     "resources/deepdive.md",
-    "llm.gemspec"
+    "resources/deepdive/*/*.md",
+    "llm.gemspec", "bin/llm.rb"
   ]
+  spec.executables = ["llm.rb"]
   spec.require_paths = ["lib"]
+  spec.post_install_message = "\n" \
+                              "Learn more about llm.rb by reading the deepdive:" \
+                              "\n" \
+                              "https://r.uby.dev/llm/deepdive" \
+                              "\n\n"
 
   spec.add_development_dependency "webmock", "~> 3.24.0"
   spec.add_development_dependency "yard", "~> 0.9.37"

data/resources/deepdive/advanced/cancellation.md

@@ -0,0 +1,74 @@
+
+## Cancellation
+
+### Introduction
+
+#### Overview
+
+Cancellation lets you abort a model request mid-stream and interrupt
+any tools that are currently executing. The user changes their mind.
+The model goes off course. A tool hangs. In all three cases,
+cancellation stops the work and reclaims the tokens.
+
+#### How it works
+
+When you want to cancel an active request or tool call, call
+[`LLM::Agent#cancel!`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#cancel!)
+or
+[`LLM::Context#cancel!`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#cancel!)
+from any thread. Two things
+happen at once:
+
+[`LLM::Interrupt`](https://r.uby.dev/api-docs/llm.rb/LLM/Interrupt.html)
+is raised on the thread where
+[`LLM::Agent#talk`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#talk)
+or
+[`LLM::Context#talk`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#talk)
+is running, so the caller
+can rescue it and know the request was cancelled.
+
+At the same time,
+[`LLM::Interrupt`](https://r.uby.dev/api-docs/llm.rb/LLM/Interrupt.html)
+is raised on every active tool.
+A tool running in a thread gets it on that thread. A tool in a
+fiber gets it on that fiber. A tool in a forked process gets it
+via a message over the control channel. Pending tools (not yet
+started) are cancelled through
+[`LLM::Function#cancel`](https://r.uby.dev/api-docs/llm.rb/LLM/Function.html#cancel)
+without ever being executed.
+
+The transport layer also cancels the in-flight HTTP request.
+
+```ruby
+require "llm"
+
+llm = LLM.deepseek(key: ENV["DEEPSEEK_SECRET"])
+agent = LLM::Agent.new(llm)
+queue = Queue.new
+
+Thread.new do
+  queue.push(nil)
+  sleep(2)
+  agent.cancel!
+end
+
+begin
+  queue.pop
+  agent.talk "write me a very long poem", stream: $stdout
+rescue LLM::Interrupt
+  puts "request cancelled!"
+end
+```
+
+#### Why would I use it?
+
+Cancellation prevents wasted time and tokens when the model goes
+off course, the user changes their mind, or a tool hangs. A forked
+tool that enters an infinite loop would run forever without it.
+
+#### Notes
+
+The `:ractor` strategy delivers the interrupt through ractor
+message passing. The `:fork` strategy delivers it via a message
+over the xchan control channel. All other strategies raise the
+exception directly on the executing thread or fiber.

data/resources/deepdive/advanced/compaction.md

@@ -0,0 +1,83 @@
+
+## Compaction
+
+### Introduction
+
+#### Overview
+
+Long-running conversations consume tokens. Without intervention,
+every turn pushes toward the model's context window limit. Compaction
+drops old messages to keep the conversation alive. The runtime runs
+a compactor automatically before each
+[`LLM::Agent#talk`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#talk)
+call, trimming the oldest messages when the conversation exceeds a configured size.
+This keeps the context window healthy without manual intervention.
+
+#### How it works
+
+Compactors run automatically before each
+[`LLM::Agent#talk`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#talk)
+call.
+[`LLM::Compactor::Truncate`](https://r.uby.dev/api-docs/llm.rb/LLM/Compactor/Truncate.html)
+strategy drops the oldest messages, keeping only the N most recent.
+It preserves tool call/return pairs so the conversation never
+contains an orphaned result.
+
+The `keep:` parameter accepts an integer count or a percentage
+string like `"80%"`. The default compactor is
+[`LLM::Compactor::Null`](https://r.uby.dev/api-docs/llm.rb/LLM/Compactor/Null.html),
+which does nothing. A compactor can also be used standalone:
+
+```ruby
+ctx = LLM::Context.new(
+  llm,
+  compactor: LLM::Compactor::Truncate,
+  compactor_options: {keep: 64}
+)
+
+agent = LLM::Agent.new(
+  llm,
+  compactor: LLM::Compactor::Truncate,
+  compactor_options: {keep: 128}
+)
+
+compactor = LLM::Compactor::Truncate.new(agent)
+compactor.call(keep: 200)
+```
+
+##### The `/compact` command
+
+The REPL provides a `/compact` command that accepts a count or
+percentage:
+
+```ruby
+# /compact        # keep last 128 messages
+# /compact 50     # keep last 50 messages
+# /compact 75%    # keep approximately 75% of messages
+```
+
+#### Why would I use it?
+
+Without compaction, the provider eventually rejects requests because
+the context window is full. Compaction keeps the conversation alive
+by discarding old messages before they cause a problem.
+
+Long-running agents that span hundreds of turns need this. A bug
+investigation that bounces back and forth between diagnosis and
+fix cannot fit every exchange in memory. Compaction trims the
+unimportant parts and keeps the conversation alive.
+
+#### Notes
+
+The Truncate strategy is fast and has no dependencies. It operates
+entirely in memory with a single pass over the message list. The
+trade-off is that dropped messages are gone, so information may be
+lost. Set `keep` to a higher number to retain more context.
+
+Both strategies emit
+[`LLM::Stream#on_compaction`](https://r.uby.dev/api-docs/llm.rb/LLM/Stream.html#on_compaction)
+and
+[`LLM::Stream#on_compaction_finish`](https://r.uby.dev/api-docs/llm.rb/LLM/Stream.html#on_compaction_finish)
+stream callbacks so the UI can show progress. The context's
+[`LLM::Context#compacted?`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#compacted?)
+flag is `true` between compaction and the next model response.