llm.rb 15.0.3 → 15.2.0

data/lib/llm/providers/bedrock.rb

@@ -210,7 +210,7 @@ module LLM
     end
 
     def normalize_complete_params(params)
-      params = {role: :user, model: default_model, max_tokens: 2048}.merge!(params)
+      params = {role: :user, model: params.delete(:model) || default_model, max_tokens: 2048}.merge!(params)
       tools = resolve_tools(params.delete(:tools))
       params = [params, adapt_schema(params), adapt_tools(tools)].inject({}, &:merge!).compact
       role, stream = params.delete(:role), LLM::Stream.try(params.delete(:stream))

data/lib/llm/providers/deepseek.rb

@@ -78,7 +78,7 @@ module LLM
     # @see https://api-docs.deepseek.com/quick_start/pricing deepseek-v4-flash
     # @return [String]
     def default_model
-      "deepseek-v4-flash"
+      "deepseek-flash"
     end
   end
 end

data/lib/llm/providers/google.rb

@@ -202,7 +202,7 @@ module LLM
 
     def normalize_complete_params(params)
       except = %i[role model messages stream]
-      params = {role: :user, model: default_model}.merge!(params)
+      params = {role: :user, model: params.delete(:model) || default_model}.merge!(params)
       tools  = resolve_tools(params.delete(:tools))
       config = adapt_generation_config(params.except(*except))
       params = [params.except(:schema), config, adapt_tools(tools)].inject({}, &:merge!).compact

data/lib/llm/providers/ollama.rb

@@ -129,7 +129,7 @@ module LLM
     end
 
     def normalize_complete_params(params)
-      params = {role: :user, model: default_model, stream: true}.merge!(params)
+      params = {role: :user, model: params.delete(:model) || default_model, stream: true}.merge!(params)
       tools  = resolve_tools(params.delete(:tools))
       params = [params, {format: params[:schema]}, adapt_tools(tools)].inject({}, &:merge!).compact
       role, stream = params.delete(:role), LLM::Stream.try(params.delete(:stream))

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

@@ -35,7 +35,8 @@ class LLM::OpenAI
     #  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)
+      params = {}.merge!(params)
+      params = {role: :user, model: params.delete(:model) || @provider.default_model}.merge!(params)
       role, stream = params.delete(:role), LLM::Stream.try(params.delete(:stream))
       tools  = resolve_tools(params.delete(:tools))
       params = [

data/lib/llm/providers/openai.rb

@@ -219,7 +219,7 @@ module LLM
     end
 
     def normalize_complete_params(params)
-      params = {role: :user, model: default_model}.merge!(params)
+      params = {role: :user, model: params.delete(:model) || default_model}.merge!(params)
       tools = resolve_tools(params.delete(:tools))
       params = [params, adapt_schema(params), adapt_tools(tools)].inject({}, &:merge!).compact
       role, stream = params.delete(:role), LLM::Stream.try(params.delete(:stream))
@@ -231,6 +231,7 @@ module LLM
 
     def build_complete_request(prompt, params, role)
       messages = build_messages(prompt, params, role)
+      messages = [*params.delete(:messages), *messages] if params[:messages]
       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))

data/lib/llm/providers/openrouter.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require_relative "openai" unless defined?(LLM::OpenAI)
+
+module LLM
+  ##
+  # The OpenRouter class implements a provider for
+  # [OpenRouter](https://openrouter.ai) through its OpenAI-compatible API.
+  #
+  # @example
+  #   #!/usr/bin/env ruby
+  #   require "llm"
+  #
+  #   llm = LLM.openrouter(key: ENV["KEY"])
+  #   ctx = LLM::Context.new(llm)
+  #   ctx.talk "Hello"
+  class OpenRouter < OpenAI
+    HOST = "openrouter.ai"
+    BASE_PATH = "/api/v1"
+
+    ##
+    # @param key (see LLM::Provider#initialize)
+    # @param host (see LLM::Provider#initialize)
+    # @param base_path (see LLM::Provider#initialize)
+    # @return [LLM::OpenRouter]
+    def initialize(host: HOST, base_path: BASE_PATH, **)
+      super
+    end
+
+    ##
+    # @return [Symbol]
+    #  Returns the provider's name
+    def name
+      :openrouter
+    end
+
+    ##
+    # Provides an embedding.
+    # @see https://openrouter.ai/docs/api/api-reference/embeddings/create-embeddings OpenRouter docs
+    # @param input (see LLM::Provider#embed)
+    # @param model (see LLM::Provider#embed)
+    # @param params (see LLM::Provider#embed)
+    # @raise (see LLM::Provider#request)
+    # @return (see LLM::Provider#embed)
+    def embed(input, model: "openai/text-embedding-3-small", **params)
+      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 vector_stores
+      raise NotImplementedError
+    end
+
+    ##
+    # Returns the default model for chat completions
+    # @see https://openrouter.ai/docs/guides/routing/routers/auto-router OpenRouter Auto Router
+    # @return [String]
+    def default_model
+      "openrouter/auto"
+    end
+  end
+end

data/lib/llm/schema/leaf.rb

@@ -19,6 +19,26 @@ class LLM::Schema
       @required = nil
       @const = nil
       @index = nil
+      @owner = nil
+    end
+
+    ##
+    # @param [Object] owner
+    #  The owner of a schema, typically an LLM::Tool or LLM::Schema class
+    # @return [void]
+    def owner=(owner)
+      @owner = owner
+    end
+
+    ##
+    # Resolves a configured value against the owner,
+    # following {LLM::Utils#resolve_option}. A Proc runs
+    # against the owner, a Symbol is sent to it, and
+    # everything else passes through unchanged.
+    # @param [Object] value
+    # @return [Object]
+    def resolve(value)
+      LLM::Utils.resolve_option(@owner, value, resolve_symbol: true)
     end
 
     ##
@@ -39,7 +59,7 @@ class LLM::Schema
     # @return [LLM::Schema::Leaf]
     def default(value = nil)
       if value.nil?
-        @default
+        resolve(@default)
       else
         tap { @default = value }
       end
@@ -100,7 +120,7 @@ class LLM::Schema
     ##
     # @return [Hash]
     def to_h
-      {description: @description, default: @default, enum: @enum, const: @const}.compact
+      {description: @description, default:, enum: @enum, const: @const}.compact
     end
 
     ##
@@ -124,5 +144,17 @@ class LLM::Schema
       to_h == other.to_h
     end
     alias_method :eql?, :==
+
+    ##
+    # @return [Integer]
+    def hash
+      to_h.hash
+    end
+
+    private
+
+    def owner
+      @owner
+    end
   end
 end

data/lib/llm/schema.rb

@@ -128,8 +128,10 @@ class LLM::Schema
   def self.defaults(defaults)
     lock do
       object.tap do |schema|
-        defaults.each do |name, val|
-          Utils.fetch(schema.properties, name).default(val)
+        defaults.each do |name, value|
+          leaf = Utils.fetch(schema.properties, name)
+          leaf.owner = self
+          leaf.default(value)
         end
       end
     end

data/lib/llm/sequel/agent.rb

@@ -35,7 +35,10 @@ module LLM::Sequel
       ##
       # @return [Class<LLM::Agent>]
       def agent
-        @agent ||= Class.new(LLM::Agent)
+        return @agent if defined?(@agent)
+        @agent = Class.new(LLM::Agent)
+        @agent.name(self)
+        @agent
       end
 
       ##
@@ -75,11 +78,12 @@ module LLM::Sequel
       #  This method does not persist to the database,
       #  but it can inspect and alter runtime state in
       #  a way that is temporary.
-      # @param (see LLM::Agent#repl)
-      # @return (see LLM::Agent#repl)
-      def repl(**params)
-        ctx.repl(**params)
+      # @param (see LLM::Agent#console)
+      # @return (see LLM::Agent#console)
+      def console(**params)
+        ctx.console(**params)
       end
+      alias_method :repl, :console
 
       private
 

data/lib/llm/skill.rb

@@ -35,6 +35,11 @@ module LLM
     # @return [String]
     attr_reader :description
 
+    ##
+    # Returns the model the skill will use.
+    # @return [String, nil]
+    attr_reader :model
+
     ##
     # Returns the skill instructions.
     # @return [String]
@@ -90,7 +95,7 @@ module LLM
       stream = ctx.stream
       stream.on_skill_call(self)
       agent = self.agent(ctx)
-      res = agent.talk("Solve the user's query.")
+      res = agent.talk("Solve the user's query.", model: model || ctx.model)
       stream.on_skill_return(agent, self, res)
       {content: res.content}
     end
@@ -156,6 +161,7 @@ module LLM
       @frontmatter = LLM::Object.from(YAML.safe_load(match[1]) || {})
       @name = @frontmatter.name || @name
       @description = @frontmatter.description || @description
+      @model = @frontmatter.model || nil
       @instructions = match[2]
       @inherit_tools, @tools = parse_tools(@frontmatter.tools)
     end

data/lib/llm/stream.rb

@@ -185,12 +185,17 @@ module LLM
     end
 
     ##
-    # Called when a request is rate limited and will be retried.
-    # @param [LLM::RateLimitError] error
+    # Called when a request is retried because it was rate limited or
+    # timed out.
+    # @param [Exception] error
+    #  The error that caused the retry
+    # @param [Integer] attempt
+    #  The one-based retry attempt number
     # @return [nil]
-    def on_rate_limit(error)
+    def on_retry(error, attempt)
       nil
     end
+    alias_method :on_rate_limit, :on_retry
 
     ##
     # Called before a skill's subagent runs.

data/lib/llm/tool/param.rb

@@ -63,7 +63,11 @@ class LLM::Tool
     def defaults(defaults)
       lock do
         function.params.tap do |schema|
-          defaults.each { Utils.fetch(schema.properties, _1).default(_2) }
+          defaults.each do |name, value|
+            leaf = Utils.fetch(schema.properties, name)
+            leaf.owner = self
+            leaf.default(value)
+          end
         end
       end
     end

data/lib/llm/tool.rb

@@ -34,6 +34,11 @@
 # @see LLM::Agent Tools are attached to agents
 # @see LLM::Function The function object that Tool wraps
 class LLM::Tool
+  ##
+  # @api private
+  UNDEFINED = Object.new
+  private_constant :UNDEFINED
+
   require_relative "tool/param"
   extend LLM::Tool::Param
   extend LLM::Function::Registry

data/lib/llm/tools/bundle.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+class LLM::Tool
+  ##
+  # The {LLM::Tool::Bundle} class implements
+  # a tool that runs a command through `bundle`.
+  # It inherits the `BUNDLE_GEMFILE` environment
+  # variable when set, or defaults to a `Gemfile`
+  # in the current working directory.
+  class Bundle < self
+    require_relative "exec"
+
+    name "bundle"
+    description "Run the 'bundle' command\n" \
+                "This command (bundle) is spawned without a shell"
+    parameter :arguments, Array[String], "one or more command arguments"
+    parameter :timeout, Integer, "the maximum allowed time for the command to run (in seconds)"
+    parameter :max_bytes, Integer, "max number of bytes to emit"
+    defaults arguments: [], timeout: 60, max_bytes: -> { Exec.max_bytes }
+
+    ##
+    # @return [LLM::Tool::BundleExec]
+    def initialize
+      @env = {"BUNDLE_GEMFILE" => ENV["BUNDLE_GEMFILE"] || File.join(Dir.getwd, "Gemfile")}
+    end
+
+    ##
+    # @param [Array<String>] arguments
+    #  One or more command-line arguments
+    # @param [Integer] timeout
+    #  The maximum allowed time for the command to run (in seconds)
+    # @param [Integer] max_bytes
+    #  Max number of bytes to emit
+    # @return [Hash]
+    def call(arguments: [], timeout: 60, max_bytes: Exec.max_bytes)
+      Exec.new(env:).call(
+        arguments: ["bundle", *arguments],
+        timeout:,
+        max_bytes:
+      )
+    end
+
+    private
+
+    ##
+    # Returns the `Gemfile` used by this tool:
+    # the `BUNDLE_GEMFILE` environment variable
+    #  when set, otherwise a `Gemfile` in the
+    # current working directory.
+    # @return [Hash{String => String}]
+    attr_reader :env
+  end
+end

data/lib/llm/tools/edit-file.rb

@@ -22,9 +22,14 @@ class LLM::Tool
     # @return [Hash]
     def call(path:, before:, after:, expected_count: 1)
       content = File.read(path)
-      count = content.scan(before).length
+      re = Regexp.new(Regexp.escape(before))
+      count = content.scan(re).length
       raise "expected #{expected_count} match(es), found #{count}" unless count == expected_count.to_i
-      File.write(path, content.sub(before, after))
+      ##
+      # Block form keeps the replacement literal:
+      # `sub(re, str)` would expand backreferences
+      # like \1 and \& in the replacement text.
+      File.write(path, content.sub(re) { after })
       {ok: true, replaced: count}
     end
   end

data/lib/llm/tools/exec.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+class LLM::Tool
+  ##
+  # The {LLM::Tool::Exec} class implements a tool that can
+  # spawn a command. That can be dangerous given a low-quality
+  # model, or a high-quality model that simply makes a bad
+  # decision. The risk can be reduced through a confirmation
+  # step such as {LLM::Agent.confirm LLM::Agent.confirm}, or
+  # by managing the tool loop manually through
+  # {LLM::Context LLM::Context}.
+  class Exec < self
+    require_relative "utils"
+    include Utils
+
+    name "exec"
+    description "Run a command without a shell"
+    parameter :arguments, Array[String], "a command and its argument(s)"
+    parameter :timeout, Integer, "the maximum allowed time for the command to run (in seconds)"
+    parameter :max_bytes, Integer, "max number of bytes to emit"
+    required %i[arguments]
+    defaults timeout: 60, max_bytes: :max_bytes
+
+    ##
+    # Returns (or sets) the advisory maximum number of bytes
+    # this tool returns to the model.
+    # @param [Integer, nil] bytes
+    #  When given, sets the maximum
+    # @return [Integer]
+    def self.max_bytes(bytes = UNDEFINED)
+      if bytes.equal?(UNDEFINED)
+        @max_bytes || 75_000
+      else
+        @max_bytes = bytes
+      end
+    end
+
+    ##
+    # @param [Hash] env
+    #  Extra environment variables to set for the command.
+    #  This is configuration for the tool instance, not a
+    #  model-provided parameter.
+    # @return [LLM::Tool::Exec]
+    def initialize(env: {})
+      @env = env
+    end
+
+    ##
+    # @param [String] name
+    #  The name of a command
+    # @param [Array<String>] arguments
+    #  One or more command-line arguments
+    # @param [Integer] timeout
+    #  The maximum allowed time for the command to run (in seconds)
+    # @param [Integer] max_bytes
+    #  the max number of bytes to emit
+    # @return [Hash]
+    def call(arguments: [], timeout: 60, max_bytes: self.class.max_bytes)
+      name = arguments[0]
+      command = spawn(name:, arguments: arguments[1..], env:, max_bytes:)
+      wait(command:, timeout:)
+      if command.not_found?
+        {ok: false, error: "command '#{name}' was not found on this system"}
+      else
+        {ok: command.success?,
+        stdout: truncate(command.stdout, max_bytes:),
+        stderr: truncate(command.stderr, max_bytes:)}
+      end
+    rescue LLM::Interrupt
+      command.kill! if command&.running?
+      raise
+    end
+
+    private
+
+    attr_reader :env
+  end
+end

data/lib/llm/tools/git.rb

@@ -3,45 +3,46 @@
 class LLM::Tool
   ##
   # The {LLM::Tool::Git LLM::Tool::Git} class implements
-  # a tool that can perform a select number of git actions.
-  # The actions it can perform are read-only - at least for
-  # the time being.
+  # a tool that can perform a select number of git subcommands.
   class Git < self
-    require_relative "utils"
-    include Utils
+    require_relative "exec"
 
     name "git"
-    description "perform an action with git"
-    parameter :action, Enum["log", "diff", "commit", "checkout", "branch", "show"], "the git operation to perform"
-    parameter :arguments, Array[String], "one or more arguments for the git action"
-    parameter :timeout, Integer, "the maximum time to allow the command to run"
-    required %i[action]
+    description "Perform a git subcommand\n" \
+                "This command (git) is spawned without a shell"
+    parameter :arguments, Array[String], "one or more arguments forwarded to git"
+    parameter :timeout, Integer, "the maximum time to allow the command to run (in seconds)"
+    required %i[arguments]
     defaults arguments: [], timeout: 5
 
     ##
-    # @param [String] action
+    # @param [String] subcommand
     # @param [Array<String>, nil] arguments
     # @return [Hash]
-    def call(action:, arguments: [], timeout: 5)
-      command = spawn(action:, arguments:)
-      wait(command:, timeout:)
-      {ok: command.success?, stdout: command.stdout, stderr: command.stderr}
-    rescue LLM::Interrupt
-      command.kill! if command&.running?
-      raise
+    def call(arguments: [], timeout: 5)
+      subcommand = arguments[0]
+      validate!(subcommand:, arguments:)
+      Exec.new.call(
+        arguments: ["git", subcommand, *arguments[1..]],
+        timeout:
+      )
     end
 
     private
 
-    def spawn(action:, arguments:)
-      Command
-        .new("git")
-        .argv(action)
-        .argv(*[*arguments])
-        .spawn
+    ##
+    # @return [void]
+    def validate!(subcommand:, arguments:)
+      unless subcommands.include?(subcommand.to_s)
+        raise RuntimeError, "git subcommand must be one of: #{subcommands.join(",")}"
+      end
     end
 
-    LLM.require "test-cmd.rb",  "~> 1.1"
-    Command = Test::Cmd
+    ##
+    # @return [Array<String>]
+    #  The git subcommands that can be performed by this tool.
+    def subcommands
+      ["log", "diff", "commit", "checkout", "branch", "show"]
+    end
   end
 end

data/lib/llm/tools/mkdir.rb

@@ -5,31 +5,24 @@ class LLM::Tool
   # The {LLM::Tool::Mkdir LLM::Tool::Mkdir} class implements
   # a tool that can create a tree of new directories.
   class Mkdir < self
+    require_relative "exec"
+
     name "mkdir"
-    description "create a new directory"
+    description "Create a new directory\n" \
+                "This command (mkdir) is spawned without a shell"
     parameter :path, String, "the path to the directory"
+    parameter :max_bytes, Integer, "max number of bytes to emit"
+    required %i[path]
+    defaults max_bytes: -> { Exec.max_bytes }
 
     ##
     # @param [String] path
     # @return [Hash]
-    def call(path:)
-      command = spawn(path:)
-      {ok: command.success?, stdout: command.stdout, stderr: command.stderr}
-    rescue LLM::Interrupt
-      command.kill! if command&.running?
-      raise
+    def call(path:, max_bytes: Exec.max_bytes)
+      Exec.new.call(
+        arguments: ["mkdir", "-p", path],
+        max_bytes:
+      )
     end
-
-    private
-
-    def spawn(path:)
-      Command
-        .new("mkdir")
-        .argv("-p", path)
-        .spawn
-    end
-
-    LLM.require "test-cmd.rb", "~> 1.1"
-    Command = Test::Cmd
   end
 end