llm.rb 11.2.0 → 11.3.1

data/lib/llm/active_record/acts_as_agent.rb

@@ -1,5 +1,11 @@
 # frozen_string_literal: true
 
+# @!parse
+#   module ::ActiveRecord
+#     class Base
+#     end
+#   end
+
 module LLM::ActiveRecord
   ##
   # ActiveRecord integration for persisting {LLM::Agent LLM::Agent} state.
@@ -134,4 +140,5 @@ module LLM::ActiveRecord
   end
 end
 
+# @!parse ::ActiveRecord::Base.extend(LLM::ActiveRecord::ActsAsAgent)
 ::ActiveRecord::Base.extend(LLM::ActiveRecord::ActsAsAgent)

data/lib/llm/active_record/acts_as_llm.rb

@@ -1,5 +1,11 @@
 # frozen_string_literal: true
 
+# @!parse
+#   module ::ActiveRecord
+#     class Base
+#     end
+#   end
+
 module LLM::ActiveRecord
   ##
   # ActiveRecord integration for persisting {LLM::Context LLM::Context} state.
@@ -222,4 +228,5 @@ module LLM::ActiveRecord
   end
 end
 
+# @!parse ::ActiveRecord::Base.extend(LLM::ActiveRecord::ActsAsLLM)
 ::ActiveRecord::Base.extend(LLM::ActiveRecord::ActsAsLLM)

data/lib/llm/agent.rb

@@ -72,7 +72,11 @@ module LLM
     #  Returns the current skills when no argument is provided
     def self.skills(*skills, &block)
       return @skills if skills.empty? && !block
-      @skills = block || skills.flatten
+      if skills.size == 1 and skills.grep(Symbol).any?
+        @skills = skills.first
+      else
+        @skills = block || skills.flatten
+      end
     end
 
     ##
@@ -160,18 +164,35 @@ module LLM
     ##
     # Set or get the tool names that require confirmation before they can run.
     #
+    # When a single Symbol is given, it is stored as-is and resolved at
+    # initialization time by calling the method with that name on the agent
+    # instance. This allows dynamic tool confirmation lists.
+    #
+    # @example
+    #   class MyAgent < LLM::Agent
+    #     confirm :tools_that_need_confirmation
+    #
+    #     def tools_that_need_confirmation
+    #       some_condition ? %w[delete destroy] : %w[delete]
+    #     end
+    #   end
+    #
     # @param [String, Symbol, Array<String, Symbol>, Proc] tool_names
     #  One or more tool names.
     # @param [Proc] block
     #  An optional, lazy-evaluated Proc
-    # @return [Array<String>, Proc, nil]
+    # @return [Array<String>, Proc, Symbol, nil]
     def self.confirm(*tool_names, &block)
       return @confirm if tool_names.empty? && !block
-      @confirm = block || tool_names.flatten.map(&:to_s)
+      if tool_names.size == 1 && tool_names.grep(Symbol).any?
+        @confirm = tool_names.first
+      else
+        @confirm = block || tool_names.flatten.map(&:to_s)
+      end
     end
 
     ##
-    # @param [LLM::Provider] provider
+    # @param [LLM::Provider] llm
     #  A provider
     # @param [Hash] params
     #  The parameters to maintain throughout the conversation.
@@ -190,7 +211,7 @@ module LLM
       fields_ivar = %i[tracer concurrency instructions confirm]
       fields.each do |field|
         resolvable = params.key?(field) ? params.delete(field) : self.class.public_send(field)
-        resolve_symbol = !%i[concurrency confirm].include?(field)
+        resolve_symbol = !%i[concurrency].include?(field)
         resolved = resolvable != nil ? resolve_option(self, resolvable, resolve_symbol:) : resolvable
         resolved = [*resolved].map(&:to_s) if field == :confirm && resolved
         if field == :model

data/lib/llm/cost.rb

@@ -37,7 +37,7 @@ class LLM::Cost < Struct.new(
 )
   ##
   # Build a cost breakdown from token usage and model pricing.
-  # @param [LLM::Context]
+  # @param [LLM::Context] ctx
   #  Context used to resolve provider, model, and token usage
   # @return [LLM::Cost]
   def self.from(ctx)

data/lib/llm/error.rb

@@ -35,6 +35,10 @@ module LLM
   # HTTPServerError
   ServerError = Class.new(Error)
 
+  ##
+  # HTTPNotFound
+  NotFoundError = Class.new(Error)
+
   ##
   # When an given an input object that is not understood
   FormatError = Class.new(Error)

data/lib/llm/function/fiber_group.rb

@@ -3,7 +3,7 @@
 class LLM::Function
   ##
   # The {LLM::Function::FiberGroup} class wraps an array of
-  # {Fiber} objects that are running {LLM::Function} calls
+  # `Fiber` objects that are running {LLM::Function} calls
   # concurrently using scheduler-backed fibers.
   #
   # This class provides the same interface as {LLM::Function::ThreadGroup}
@@ -26,7 +26,7 @@ class LLM::Function
     # of fiber objects.
     #
     # @param [Array<Fiber>] fibers
-    #   An array of fibers, each running an {LLM::Function#spawn_fiber} call.
+    #   An array of fibers, each running an `LLM::Function#spawn_fiber` call.
     #
     # @return [LLM::Function::FiberGroup]
     #   Returns a new fiber group.

data/lib/llm/function/task_group.rb

@@ -3,7 +3,7 @@
 class LLM::Function
   ##
   # The {LLM::Function::TaskGroup} class wraps an array of
-  # {Async::Task} objects that are running {LLM::Function} calls
+  # `Async::Task` objects that are running {LLM::Function} calls
   # concurrently using the async gem.
   #
   # This class provides the same interface as {LLM::Function::ThreadGroup}
@@ -27,7 +27,7 @@ class LLM::Function
     # of async task objects.
     #
     # @param [Array<Async::Task>] tasks
-    #   An array of async tasks, each running an {LLM::Function#spawn_async} call.
+    #   An array of async tasks, each running an `LLM::Function#spawn_async` call.
     #
     # @return [LLM::Function::TaskGroup]
     #   Returns a new task group.

data/lib/llm/function/thread_group.rb

@@ -3,7 +3,7 @@
 class LLM::Function
   ##
   # The {LLM::Function::ThreadGroup} class wraps an array of
-  # {Thread} objects that are running {LLM::Function} calls
+  # `Thread` objects that are running {LLM::Function} calls
   # concurrently. It provides a single {#wait} method that
   # collects the {LLM::Function::Return} values from those
   # threads.
@@ -27,11 +27,11 @@ class LLM::Function
   class ThreadGroup
     ##
     # Creates a new {LLM::Function::ThreadGroup} from an array
-    # of {Thread} objects.
+    # of `Thread` objects.
     #
     # @param [Array<Thread>] threads
     #   An array of threads, each running an {LLM::Function#spawn}
-    #   call. The thread's {Thread#value} will be an
+    #   call. The thread's `Thread#value` will be an
     #   {LLM::Function::Return}.
     #
     # @return [LLM::Function::ThreadGroup]

data/lib/llm/pipe.rb

@@ -3,7 +3,7 @@
 module LLM
   ##
   # The {LLM::Pipe LLM::Pipe} class wraps a pair of IO objects created by
-  # {IO.pipe}. It is used by llm.rb internals to manage process and stream
+  # `IO.pipe`. It is used by llm.rb internals to manage process and stream
   # communication through one small interface.
   class Pipe
     ##

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

@@ -49,6 +49,8 @@ class LLM::Anthropic
         LLM::UnauthorizedError.new("Authentication error").tap { _1.response = res }
       elsif res.rate_limited?
         LLM::RateLimitError.new("Too many requests").tap { _1.response = res }
+      elsif res.not_found?
+        LLM::NotFoundError.new("Server response: not found (404)").tap { _1.response = res }
       else
         LLM::Error.new("Unexpected response").tap { _1.response = res }
       end

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

@@ -28,7 +28,7 @@ class LLM::Anthropic
     private
 
     ##
-    # @param [Hash] params
+    # @param [Array<LLM::Function>] tools
     # @return [Hash]
     def adapt_tools(tools)
       return {} unless tools&.any?

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

@@ -53,7 +53,7 @@ class LLM::Bedrock
       elsif res.rate_limited?
         LLM::RateLimitError.new(message).tap { _1.response = res }
       elsif res.not_found?
-        LLM::Error.new("Bedrock model not found: #{message}").tap { _1.response = res }
+        LLM::NotFoundError.new("Server response: not found (404)").tap { _1.response = res }
       else
         LLM::Error.new(message).tap { _1.response = res }
       end

data/lib/llm/providers/bedrock/request_adapter/completion.rb

@@ -5,11 +5,11 @@ module LLM::Bedrock::RequestAdapter
   # Adapts a single message to Bedrock Converse content blocks.
   #
   # Bedrock Converse content blocks include:
-  #   - {text: "..."}
-  #   - {image: {format: "png", source: {bytes: "..."}}}
-  #   - {document: {format: "pdf", name: "...", source: {bytes: "..."}}}
-  #   - {toolUse: {toolUseId: "...", name: "...", input: {...}}}
-  #   - {toolResult: {toolUseId: "...", content: [{text: "..."}]}}
+  #   - { text: "..." }
+  #   - { image: { format: "png", source: { bytes: "..." } } }
+  #   - { document: { format: "pdf", name: "...", source: { bytes: "..." } } }
+  #   - { toolUse: { toolUseId: "...", name: "...", input: ... } }
+  #   - {toolResult: {toolUseId: "...", content: [{ text: "..." }]}}
   #
   # @api private
   class Completion

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

@@ -5,10 +5,10 @@ class LLM::Bedrock
   # Adapts llm.rb internal message format to Bedrock Converse API format.
   #
   # Bedrock Converse uses:
-  #   - system: [{text: "..."}]  (top-level, separate from messages)
-  #   - messages: [{role: "user"|"assistant", content: [{...}, ...]}]
+  #   - system: `[ { text: "..." } ]`  (top-level, separate from messages)
+  #   - messages: `[ { role: "user"|"assistant", content: [ ... ] } ]`
   #   - Content blocks: text, image, document, toolUse, toolResult
-  #   - toolConfig: {tools: [{toolSpec: {name:, description:, inputSchema: {json: ...}}}]}
+  #   - toolConfig: `{ tools: [ { toolSpec: { name:, description:, inputSchema: { json: ... } } } ] }`
   #
   # @api private
   module RequestAdapter

data/lib/llm/providers/bedrock/response_adapter/completion.rb

@@ -8,9 +8,9 @@ module LLM::Bedrock::ResponseAdapter
   #   {
   #     "output" => {"message" => {
   #       "role" => "assistant",
-  #       "content" => [{"text" => "..."}, {"toolUse" => {...}}]
+  #       "content" => `[ { "text" => "..." }, { "toolUse" => ... } ]`
   #     }},
-  #     "usage" => {"inputTokens" => N, "outputTokens" => N},
+  #     "usage" => `{ "inputTokens" => N, "outputTokens" => N }`,
   #     "modelId" => "anthropic.claude-sonnet-4-20250514-v1:0",
   #     "stopReason" => "end_turn"
   #   }

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

@@ -6,8 +6,8 @@ class LLM::Bedrock
   #
   # Bedrock Converse returns:
   #   {
-  #     output: {message: {role: "assistant", content: [{...}, ...]}},
-  #     usage: {inputTokens: N, outputTokens: N},
+  #     output: `{ message: { role: "assistant", content: [ ... ] } }`,
+  #     usage: `{ inputTokens: N, outputTokens: N }`,
   #     modelId: "anthropic.claude-...",
   #     stopReason: "end_turn" | "tool_use" | "max_tokens" | ...
   #   }

data/lib/llm/providers/deepseek/request_adapter.rb

@@ -18,7 +18,7 @@ class LLM::DeepSeek
     private
 
     ##
-    # @param [Hash] params
+    # @param [Array<LLM::Function>] tools
     # @return [Hash]
     def adapt_tools(tools)
       (tools.nil? || tools.empty?) ? {} : {tools: tools.map { _1.adapt(self) }}

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

@@ -60,6 +60,8 @@ class LLM::Google
         end
       elsif res.rate_limited?
         LLM::RateLimitError.new("Too many requests").tap { _1.response = res }
+      elsif res.not_found?
+        LLM::NotFoundError.new("Server response: not found (404)").tap { _1.response = res }
       else
         LLM::Error.new("Unexpected response").tap { _1.response = res }
       end

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

@@ -29,7 +29,7 @@ class LLM::Google
     end
 
     ##
-    # @param [Hash] params
+    # @param [Array<LLM::Function>] tools
     # @return [Hash]
     def adapt_tools(tools)
       return {} unless tools&.any?

data/lib/llm/providers/ollama/error_handler.rb

@@ -49,6 +49,8 @@ class LLM::Ollama
         LLM::UnauthorizedError.new("Authentication error").tap { _1.response = res }
       elsif res.rate_limited?
         LLM::RateLimitError.new("Too many requests").tap { _1.response = res }
+      elsif res.not_found?
+        LLM::NotFoundError.new("Server response: not found (404)").tap { _1.response = res }
       else
         LLM::Error.new("Unexpected response").tap { _1.response = res }
       end

data/lib/llm/providers/ollama/request_adapter.rb

@@ -19,7 +19,7 @@ class LLM::Ollama
     private
 
     ##
-    # @param [Hash] params
+    # @param [Array<LLM::Function>] tools
     # @return [Hash]
     def adapt_tools(tools)
       return {} unless tools&.any?

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

@@ -55,6 +55,8 @@ class LLM::OpenAI
         LLM::UnauthorizedError.new("Authentication error").tap { _1.response = res }
       elsif res.rate_limited?
         LLM::RateLimitError.new("Too many requests").tap { _1.response = res }
+      elsif res.not_found?
+        LLM::NotFoundError.new("Server response: not found (404)").tap { _1.response = res }
       else
         error = body["error"] || {}
         case error["type"]

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

@@ -42,7 +42,7 @@ class LLM::OpenAI
     end
 
     ##
-    # @param [Hash] params
+    # @param [Array<LLM::Function>] tools
     # @return [Hash]
     def adapt_tools(tools)
       if tools.nil? || tools.empty?

data/lib/llm/registry.rb

@@ -12,7 +12,7 @@ class LLM::Registry
   ##
   # @raise [LLM::Error]
   #  Might raise an error
-  # @param [Symbol]
+  # @param [Symbol] name
   #  A provider name
   # @return [LLM::Registry]
   def self.for(name)
@@ -71,7 +71,7 @@ class LLM::Registry
   end
 
   ##
-  # Similar to #{find} but returns the block's return value
+  # Similar to `#find` but returns the block's return value
   # @return [Object, nil]
   def find_map(pair)
     result = nil

data/lib/llm/response.rb

@@ -14,7 +14,7 @@ module LLM
   # through {#res}. When the default net/http transport is in use,
   # {LLM::Transport::Response::HTTP
   # LLM::Transport::Response::HTTP} keeps the
-  # original {Net::HTTPResponse Net::HTTPResponse} available through
+  # original `Net::HTTPResponse` available through
   # its own {LLM::Transport::Response::HTTP#res #res}.
   class Response
     require "json"

data/lib/llm/schema/object.rb

@@ -12,7 +12,7 @@ class LLM::Schema
     attr_reader :properties
 
     ##
-    # @param params [Hash]
+    # @param [Hash] properties
     #  A hash of properties
     # @return [LLM::Schema::Object]
     def initialize(properties)

data/lib/llm/stream.rb

@@ -15,7 +15,7 @@ module LLM
   #   therefore block streaming progress and should generally return as
   #   quickly as possible.
   #
-  # The most common callback is {#on_content}, which also maps to {#<<}.
+  # The most common callback is {#on_content}, which also maps to `#<<`.
   # Providers may also call {#on_reasoning_content} and {#on_tool_call} when
   # that data is available. Runtime features such as context compaction may
   # also emit lifecycle callbacks like {#on_transform} or {#on_compaction}.

data/lib/llm/tool.rb

@@ -63,7 +63,7 @@ class LLM::Tool
   ##
   # @param [LLM::A2A] a2a
   #  The A2A client that will execute the tool call
-  # @param [LLM::A2A::Card::Skill]
+  # @param [LLM::A2A::Card::Skill] skill
   #  An A2A tool
   # @return [Class<LLM::Tool>]
   #  Returns a subclass of LLM::Tool
@@ -124,7 +124,7 @@ class LLM::Tool
 
   ##
   # Registers the tool as a function when inherited
-  # @param [Class] klass The subclass
+  # @param [Class] tool The subclass
   # @return [void]
   def self.inherited(tool)
     LLM.lock(:inherited) do

data/lib/llm/transport/http.rb

@@ -5,7 +5,7 @@ require "net/http"
 class LLM::Transport
   ##
   # The {LLM::Transport::HTTP LLM::Transport::HTTP} transport is the
-  # built-in adapter for Ruby's {Net::HTTP Net::HTTP}. It manages
+  # built-in adapter for Ruby's `Net::HTTP`. It manages
   # transient HTTP connections, tracks active requests by owner, and
   # interrupts in-flight requests when needed.
   #
@@ -69,7 +69,7 @@ class LLM::Transport
 
     ##
     # Performs a request on the current HTTP transport.
-    # Accepts both {Net::HTTPRequest} and {LLM::Transport::Request}.
+    # Accepts both `Net::HTTPRequest` and {LLM::Transport::Request}.
     #
     # @param [Net::HTTPRequest, LLM::Transport::Request] request
     # @param [Fiber] owner

data/lib/llm/transport/persistent_http.rb

@@ -81,7 +81,7 @@ class LLM::Transport
 
     ##
     # Performs a request on the current HTTP transport.
-    # Accepts both {Net::HTTPRequest} and {LLM::Transport::Request}.
+    # Accepts both `Net::HTTPRequest` and {LLM::Transport::Request}.
     #
     # @param [Net::HTTPRequest, LLM::Transport::Request] request
     # @param [Fiber] owner

data/lib/llm/transport/response/http.rb

@@ -3,7 +3,7 @@
 class LLM::Transport::Response
   ##
   # {LLM::Transport::Response::HTTP LLM::Transport::Response::HTTP}
-  # adapts a {Net::HTTPResponse Net::HTTPResponse} to the
+  # adapts a `Net::HTTPResponse` to the
   # {LLM::Transport::Response LLM::Transport::Response} interface.
   #
   # This is the default wrapper for responses produced by the built-in

data/lib/llm/utils.rb

@@ -45,7 +45,7 @@ module LLM
     # Returns the Ruby module or class name for an object.
     #
     # This bypasses overridden `#name` implementations by binding
-    # {Module#name} directly.
+    # `Module#name` directly.
     #
     # @param [Module] obj
     # @return [String, nil]

data/lib/llm/version.rb

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

data/lib/llm.rb

@@ -181,16 +181,19 @@ module LLM
   end
 
   ##
-  # @param [Hash, nil] stdio
-  # @option stdio [Array<String>] :argv
+  # @param [Hash] opts
+  #  MCP client options
+  # @option opts [Hash, nil] :stdio
+  #  Standard I/O transport options
+  # @option opts [Array<String>] :stdio/:argv
   #  The command to run for the MCP process
-  # @option stdio [Hash] :env
+  # @option opts [Hash] :stdio/:env
   #  The environment variables to set for the MCP process
-  # @option stdio [String, nil] :cwd
+  # @option opts [String, nil] :stdio/:cwd
   #  The working directory for the MCP process
   # @return [LLM::MCP]
-  def mcp(**)
-    LLM::MCP.new(**)
+  def mcp(**opts)
+    LLM::MCP.new(**opts)
   end
 
   ##
@@ -234,7 +237,7 @@ module LLM
   ##
   # Provides a thread-safe lock
   # @param [Symbol] name The name of the lock
-  # @param [Proc] & The block to execute within the lock
+  # @param [Proc] block The block to execute within the lock
   # @return [void]
-  def lock(name, &) = @monitors[name].synchronize(&)
+  def lock(name, &block) = @monitors[name].synchronize(&block)
 end

data/llm.gemspec

@@ -5,12 +5,12 @@ require_relative "lib/llm/version"
 Gem::Specification.new do |spec|
   spec.name = "llm.rb"
   spec.version = LLM::VERSION
-  spec.authors = ["Antar Azri", "0x1eef", "Christos Maris", "Rodrigo Serrano"]
-  spec.email = ["azantar@proton.me", "0x1eef@hardenedbsd.org"]
+  spec.authors = ["Robert (0x1eef)", "Antar Azri", "Rodrigo Serrano"]
+  spec.email = ["robert@r.uby.dev"]
 
-  spec.summary = "Ruby's most capable AI runtime"
+  spec.summary = "Ruby's capable AI runtime"
   spec.description = <<~DESC
-  llm.rb is Ruby's most capable AI runtime.
+  llm.rb is Ruby's capable AI runtime.
 
   It runs on Ruby's standard library by default. loads optional pieces
   only when needed, and offers a single runtime for providers, agents,
@@ -28,23 +28,24 @@ Gem::Specification.new do |spec|
   spec.license = "0BSD"
   spec.required_ruby_version = ">= 3.3.0"
 
-  spec.homepage = "https://llmrb.github.io"
+  spec.homepage = "https://r.uby.dev/llm/"
   spec.metadata["homepage_uri"] = spec.homepage
-  spec.metadata["source_code_uri"] = "https://github.com/llmrb/llm.rb"
-  spec.metadata["documentation_uri"] = "https://llmrb.github.io/llm.rb"
-  spec.metadata["changelog_uri"] = "https://0x1eef.github.io/x/llm.rb/file.CHANGELOG.html"
+  spec.metadata["source_code_uri"] = "https://github.com/r-uby-dev/llm.rb"
+  spec.metadata["documentation_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "https://r.uby.dev/api-docs/llm.rb/file.CHANGELOG.html"
 
   spec.files = Dir[
     "README.md", "LICENSE",
     "lib/*.rb", "lib/**/*.rb",
     "data/*.json", "CHANGELOG.md",
+    "resources/deepdive.md",
     "llm.gemspec"
   ]
   spec.require_paths = ["lib"]
 
   spec.add_development_dependency "webmock", "~> 3.24.0"
   spec.add_development_dependency "yard", "~> 0.9.37"
-  spec.add_development_dependency "kramdown", "~> 2.4"
+  spec.add_development_dependency "redcarpet", "~> 3.6"
   spec.add_development_dependency "webrick", "~> 1.8"
   spec.add_development_dependency "test-cmd.rb", "~> 0.12.0"
   spec.add_development_dependency "rake", "~> 13.0"
@@ -60,4 +61,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "sqlite3", "~> 2.0"
   spec.add_development_dependency "xchan.rb", "~> 0.20"
   spec.add_development_dependency "pg", "~> 1.5"
+  spec.add_development_dependency "irb", "~> 1.18"
 end