llm.rb 4.9.0 → 4.11.0

data/lib/llm/schema/any_of.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+class LLM::Schema
+  ##
+  # The {LLM::Schema::AnyOf LLM::Schema::AnyOf} class represents an
+  # anyOf union in a JSON schema. It is a subclass of
+  # {LLM::Schema::Leaf LLM::Schema::Leaf}.
+  class AnyOf < Leaf
+    ##
+    # Returns an anyOf union for the given types.
+    # @return [LLM::Schema::AnyOf]
+    def self.[](*types)
+      schema = LLM::Schema.new
+      new(types.map { LLM::Schema::Utils.resolve(schema, _1) })
+    end
+
+    ##
+    # @param [Array<LLM::Schema::Leaf>] values
+    #  The values allowed by the union
+    # @return [LLM::Schema::AnyOf]
+    def initialize(values)
+      @values = values
+    end
+
+    ##
+    # @return [Hash]
+    def to_h
+      super.merge!(anyOf: @values)
+    end
+  end
+end

data/lib/llm/schema/one_of.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+class LLM::Schema
+  ##
+  # The {LLM::Schema::OneOf LLM::Schema::OneOf} class represents an
+  # oneOf union in a JSON schema. It is a subclass of
+  # {LLM::Schema::Leaf LLM::Schema::Leaf}.
+  class OneOf < Leaf
+    ##
+    # Returns a oneOf union for the given types.
+    # @return [LLM::Schema::OneOf]
+    def self.[](*types)
+      schema = LLM::Schema.new
+      new(types.map { LLM::Schema::Utils.resolve(schema, _1) })
+    end
+
+    ##
+    # @param [Array<LLM::Schema::Leaf>] values
+    #  The values allowed by the union
+    # @return [LLM::Schema::OneOf]
+    def initialize(values)
+      @values = values
+    end
+
+    ##
+    # @return [Hash]
+    def to_h
+      super.merge!(oneOf: @values)
+    end
+  end
+end

data/lib/llm/schema/parser.rb

@@ -8,6 +8,8 @@ class LLM::Schema
   # external JSON schema definitions into the schema objects used
   # throughout llm.rb.
   module Parser
+    METADATA_KEYS = %w[description default enum const].freeze
+
     ##
     # Parses a JSON schema into an {LLM::Schema::Leaf}.
     # @param [Hash] schema
@@ -27,6 +29,8 @@ class LLM::Schema
       when "number" then apply(parse_number(schema), schema)
       when "boolean" then apply(schema().boolean, schema)
       when "null" then apply(schema().null, schema)
+      when ::Array then apply(schema().any_of(*schema["type"].map { parse(schema.except("type", *METADATA_KEYS).merge("type" => _1), root) }), schema.except("type"))
+      when nil then parse_union(schema, root)
       else raise TypeError, "unsupported schema type #{schema["type"].inspect}"
       end
     end
@@ -50,6 +54,14 @@ class LLM::Schema
       schema().array(items)
     end
 
+    def parse_union(schema, root)
+      return apply(schema().any_of(*schema["anyOf"].map { parse(_1, root) }), schema) if schema.key?("anyOf")
+      return apply(schema().one_of(*schema["oneOf"].map { parse(_1, root) }), schema) if schema.key?("oneOf")
+      return apply(schema().all_of(*schema["allOf"].map { parse(_1, root) }), schema) if schema.key?("allOf")
+      return parse(infer_type(schema), root) if infer_type(schema)
+      raise TypeError, "unsupported schema type #{schema["type"].inspect}"
+    end
+
     def parse_string(schema)
       leaf = schema().string
       leaf.min(schema["minLength"]) if schema.key?("minLength")
@@ -105,5 +117,29 @@ class LLM::Schema
     rescue KeyError
       raise TypeError, "unresolvable schema ref #{ref.inspect}"
     end
+
+    def infer_type(schema)
+      if schema.key?("const")
+        schema.merge("type" => type_of(schema["const"]))
+      elsif schema.key?("enum")
+        type = type_of(schema["enum"].first)
+        return unless type && schema["enum"].all? { type_of(_1) == type }
+        schema.merge("type" => type)
+      elsif schema.key?("default")
+        schema.merge("type" => type_of(schema["default"]))
+      end
+    end
+
+    def type_of(value)
+      case value
+      when ::Hash then "object"
+      when ::Array then "array"
+      when ::String then "string"
+      when ::Integer then "integer"
+      when ::Float then "number"
+      when ::TrueClass, ::FalseClass then "boolean"
+      when ::NilClass then "null"
+      end
+    end
   end
 end

data/lib/llm/schema.rb

@@ -35,6 +35,9 @@ class LLM::Schema
   require_relative "schema/leaf"
   require_relative "schema/object"
   require_relative "schema/array"
+  require_relative "schema/all_of"
+  require_relative "schema/any_of"
+  require_relative "schema/one_of"
   require_relative "schema/string"
   require_relative "schema/enum"
   require_relative "schema/number"
@@ -45,6 +48,23 @@ class LLM::Schema
   @__monitor = Monitor.new
   extend LLM::Schema::Parser
 
+  ##
+  # @api private
+  module Utils
+    extend self
+
+    def resolve(schema, type)
+      if LLM::Schema::Leaf === type
+        type
+      elsif Class === type && type.respond_to?(:object)
+        type.object
+      else
+        target = type.name.split("::").last.downcase
+        schema.public_send(target)
+      end
+    end
+  end
+
   ##
   # Configures a monitor for a subclass
   # @return [void]
@@ -65,14 +85,7 @@ class LLM::Schema
   #  A hash of options
   def self.property(name, type, description, options = {})
     lock do
-      if LLM::Schema::Leaf === type
-        prop = type
-      elsif Class === type && type.respond_to?(:object)
-        prop = type.object
-      else
-        target = type.name.split("::").last.downcase
-        prop = schema.public_send(target)
-      end
+      prop = Utils.resolve(schema, type)
       options = {description:}.merge(options)
       options.each { (_2 == true) ? prop.public_send(_1) : prop.public_send(_1, *_2) }
       object[name] = prop
@@ -120,6 +133,30 @@ class LLM::Schema
     Array.new(*items)
   end
 
+  ##
+  # Returns an anyOf union
+  # @param [Array<LLM::Schema::Leaf>] values The union values
+  # @return [LLM::Schema::AnyOf]
+  def any_of(*values)
+    AnyOf.new(values)
+  end
+
+  ##
+  # Returns an allOf union
+  # @param [Array<LLM::Schema::Leaf>] values The union values
+  # @return [LLM::Schema::AllOf]
+  def all_of(*values)
+    AllOf.new(values)
+  end
+
+  ##
+  # Returns a oneOf union
+  # @param [Array<LLM::Schema::Leaf>] values The union values
+  # @return [LLM::Schema::OneOf]
+  def one_of(*values)
+    OneOf.new(values)
+  end
+
   ##
   # Returns a string
   # @return [LLM::Schema::String]

data/lib/llm/stream/queue.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+class LLM::Stream
+  ##
+  # A small queue for collecting streamed tool work. Values can be immediate
+  # {LLM::Function::Return} objects or concurrent handles returned by
+  # {LLM::Function#spawn}. Calling {#wait(strategy)} resolves queued work and
+  # returns an array of {LLM::Function::Return} values.
+  class Queue
+    ##
+    # @return [LLM::Stream::Queue]
+    def initialize
+      @items = []
+    end
+
+    ##
+    # Enqueue a function return or spawned task.
+    # @param [LLM::Function::Return, Thread, Async::Task, Fiber] item
+    # @return [LLM::Stream::Queue]
+    def <<(item)
+      @items << item
+      self
+    end
+
+    ##
+    # Returns true when the queue is empty.
+    # @return [Boolean]
+    def empty?
+      @items.empty?
+    end
+
+    ##
+    # Waits for queued work to finish and returns function results.
+    # @param [Symbol] strategy
+    #   Controls concurrency strategy:
+    #   - `:thread`: Use threads
+    #   - `:task`: Use async tasks (requires async gem)
+    #   - `:fiber`: Use raw fibers
+    # @return [Array<LLM::Function::Return>]
+    def wait(strategy)
+      returns, tasks = @items.shift(@items.length).partition { LLM::Function::Return === _1 }
+      returns.concat case strategy
+      when :thread then LLM::Function::ThreadGroup.new(tasks).wait
+      when :task then LLM::Function::TaskGroup.new(tasks).wait
+      when :fiber then LLM::Function::FiberGroup.new(tasks).wait
+      else raise ArgumentError, "Unknown strategy: #{strategy.inspect}. Expected :thread, :task, or :fiber"
+      end
+    end
+    alias_method :value, :wait
+  end
+end

data/lib/llm/stream.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module LLM
+  ##
+  # The {LLM::Stream LLM::Stream} class provides the callback interface for
+  # streamed model output in llm.rb.
+  #
+  # A stream object can be an instance of {LLM::Stream LLM::Stream}, a
+  # subclass that overrides the callbacks it needs, or any other object that
+  # implements some or all of the same interface. {#queue} provides a small
+  # helper for collecting asynchronous tool work started from a callback, and
+  # {#tool_not_found} returns an in-band tool error when a streamed tool
+  # cannot be resolved.
+  #
+  # @note The `on_*` callbacks run inline with the streaming parser. They
+  #   therefore block streaming progress and should generally return as
+  #   quickly as possible.
+  #
+  # The most common callback is {#on_content}, which also maps to {#<<} for
+  # compatibility with `StringIO`-style objects. Providers may also call
+  # {#on_reasoning_content} and {#on_tool_call} when that data is available.
+  class Stream
+    require_relative "stream/queue"
+
+    ##
+    # Returns a lazily-initialized queue for tool results or spawned work.
+    # @return [LLM::Stream::Queue]
+    def queue
+      @queue ||= Queue.new
+    end
+
+    ##
+    # Waits for queued tool work to finish and returns function results.
+    # @param [Symbol] strategy
+    #  The concurrency strategy to use
+    # @return [Array<LLM::Function::Return>]
+    def wait(strategy)
+      queue.wait(strategy)
+    end
+
+    # @group Public callbacks
+
+    ##
+    # Called when visible assistant output is streamed.
+    # @param [String] content
+    #  A chunk of assistant-visible text.
+    # @return [nil]
+    def on_content(content)
+      nil
+    end
+    alias_method :<<, :on_content
+
+    ##
+    # Called when reasoning output is streamed separately from visible content.
+    # @param [String] content
+    #  A chunk of reasoning text.
+    # @return [nil]
+    def on_reasoning_content(content)
+      nil
+    end
+
+    ##
+    # Called when a streamed tool call has been fully constructed.
+    # @note A stream implementation may start tool execution here, for
+    #   example by pushing `tool.spawn(:thread)`, `tool.spawn(:fiber)`, or
+    #   `tool.spawn(:task)` onto {#queue}. When a streamed tool cannot be
+    #   resolved, `error` is passed as an {LLM::Function::Return}. It can be
+    #   sent back to the model, allowing the tool-call path to recover and the
+    #   session to continue. Tool resolution depends on
+    #   {LLM::Function.registry}, which includes {LLM::Tool LLM::Tool}
+    #   subclasses, including MCP tools, but not functions defined with
+    #   {LLM.function}.
+    # @param [LLM::Function] tool
+    #  The parsed tool call.
+    # @param [LLM::Function::Return, nil] error
+    #  An in-band tool error for unresolved tool calls.
+    # @return [nil]
+    def on_tool_call(tool, error)
+      nil
+    end
+
+    # @endgroup
+
+    # @group Error handlers
+
+    ##
+    # Returns a function return describing a streamed tool that could not
+    # be resolved.
+    # @note This is mainly useful as a fallback from {#on_tool_call}. It
+    #   should be uncommon in normal use, since streamed tool callbacks only
+    #   run for tools already defined in the context.
+    # @param [LLM::Function] tool
+    # @return [LLM::Function::Return]
+    def tool_not_found(tool)
+      LLM::Function::Return.new(tool.id, tool.name, {
+        error: true, type: LLM::NoSuchToolError.name, message: "tool not found"
+      })
+    end
+
+    # @endgroup
+  end
+end

data/lib/llm/tool.rb

@@ -20,11 +20,13 @@
 class LLM::Tool
   require_relative "tool/param"
   extend LLM::Tool::Param
+  extend LLM::Function::Registry
 
   types = [
-    :Leaf, :String, :Enum, :Array,
+    :Leaf, :String, :Enum,
+    :AllOf, :AnyOf, :OneOf,
     :Object, :Integer, :Number,
-    :Boolean, :Null
+    :Array, :Boolean, :Null
   ]
   types.each do |constant|
     const_set constant, LLM::Schema.const_get(constant)
@@ -38,58 +40,51 @@ class LLM::Tool
   # @return [Class<LLM::Tool>]
   #  Returns a subclass of LLM::Tool
   def self.mcp(mcp, tool)
-    klass = Class.new(LLM::Tool) do
-      name tool["name"]
-      description tool["description"]
-      params { tool["inputSchema"] || {type: "object", properties: {}} }
-
-      define_singleton_method(:inspect) do
-        "<LLM::Tool:0x#{object_id.to_s(16)} name=#{tool["name"]} (mcp)>"
-      end
-      singleton_class.alias_method :to_s, :inspect
-
-      define_singleton_method(:mcp?) do
-        true
-      end
-
-      define_method(:call) do |**args|
-        mcp.call_tool(tool["name"], args)
-      end
-    end
-    unregister(klass)
-  end
-
-  ##
-  # Returns all subclasses of LLM::Tool
-  # @note
-  #  This method excludes tools who haven't defined a name
-  #  as well as tools defined via MCP.
-  # @return [Array<LLM::Tool>]
-  def self.registry
     lock do
-      @registry.select(&:name)
+      @mcp = true
+      klass = Class.new(LLM::Tool) do
+        name tool["name"]
+        description tool["description"]
+        params { tool["inputSchema"] || {type: "object", properties: {}} }
+
+        define_singleton_method(:inspect) do
+          "<LLM::Tool:0x#{object_id.to_s(16)} name=#{tool["name"]} (mcp)>"
+        end
+        singleton_class.alias_method :to_s, :inspect
+
+        define_singleton_method(:mcp?) do
+          true
+        end
+
+        define_method(:call) do |**args|
+          mcp.call_tool(tool["name"], args)
+        end
+      end
+      @mcp = false
+      register(klass)
+      klass
+    ensure
+      @mcp = false
     end
   end
-  @registry = []
 
   ##
   # Clear the registry
   # @return [void]
   def self.clear_registry!
     lock do
-      @registry.clear
-      nil
+      @__registry.each_value { LLM::Function.unregister(_1.function) }
+      super
     end
   end
 
   ##
-  # Register a tool in the registry
+  # Registers a tool and its function.
   # @param [LLM::Tool] tool
   # @api private
   def self.register(tool)
-    lock do
-      @registry << tool
-    end
+    super
+    LLM::Function.register(tool.function)
   end
 
   ##
@@ -98,7 +93,9 @@ class LLM::Tool
   # @api private
   def self.unregister(tool)
     lock do
-      @registry.delete(tool)
+      LLM::Function.unregister(tool.function)
+      super
+      tool
     end
   end
 
@@ -110,7 +107,7 @@ class LLM::Tool
     LLM.lock(:inherited) do
       tool.instance_eval { @__monitor ||= Monitor.new }
       tool.function.register(tool)
-      LLM::Tool.register(tool)
+      LLM::Tool.register(tool) unless lock { @mcp }
     end
   end
 
@@ -124,6 +121,22 @@ class LLM::Tool
     end
   end
 
+  ##
+  # Returns all registered tool classes with definitions.
+  # @return [Array<Class<LLM::Tool>>]
+  def self.registry
+    super.select(&:name)
+  end
+
+  ##
+  # Finds a registered tool by name.
+  # @param [String] name
+  # @return [Class<LLM::Tool>]
+  # @raise [LLM::NoSuchToolError]
+  def self.find_by_name!(name)
+    find_by_name(name) || raise(LLM::NoSuchToolError, "no such tool #{name.inspect}")
+  end
+
   ##
   # Returns (or sets) the tool description
   # @param [String, nil] desc The tool description
@@ -152,13 +165,6 @@ class LLM::Tool
     end
   end
 
-  ##
-  # @api private
-  def self.lock(&)
-    @__monitor.synchronize(&)
-  end
-  @__monitor = Monitor.new
-
   ##
   # Returns true if the tool is an MCP tool
   # @return [Boolean]

data/lib/llm/version.rb

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

data/lib/llm.rb

@@ -20,6 +20,7 @@ module LLM
   require_relative "llm/mime"
   require_relative "llm/multipart"
   require_relative "llm/file"
+  require_relative "llm/stream"
   require_relative "llm/provider"
   require_relative "llm/context"
   require_relative "llm/agent"
@@ -29,10 +30,11 @@ module LLM
   require_relative "llm/eventhandler"
   require_relative "llm/tool"
   require_relative "llm/server_tool"
+  require_relative "llm/mcp"
 
   ##
   # Thread-safe monitors for different contexts
-  @monitors = {require: Monitor.new, clients: Monitor.new, inherited: Monitor.new, registry: Monitor.new}
+  @monitors = {require: Monitor.new, clients: Monitor.new, inherited: Monitor.new, registry: Monitor.new, mcp: Monitor.new}
 
   ##
   # Model registry
@@ -161,7 +163,6 @@ module LLM
   #  The working directory for the MCP process
   # @return [LLM::MCP]
   def mcp(llm = nil, **)
-    lock(:require) { require_relative "llm/mcp" unless defined?(LLM::MCP) }
     LLM::MCP.new(llm, **)
   end
 

data/llm.gemspec

@@ -63,7 +63,7 @@ Gem::Specification.new do |spec|
   spec.files = Dir[
     "README.md", "LICENSE",
     "lib/*.rb", "lib/**/*.rb",
-    "data/*.json",
+    "data/*.json", "CHANGELOG.md",
     "llm.gemspec"
   ]
   spec.require_paths = ["lib"]
@@ -81,4 +81,4 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "net-http-persistent", "~> 4.0"
   spec.add_development_dependency "opentelemetry-sdk", "~> 1.10"
   spec.add_development_dependency "logger", "~> 1.7"
-end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: llm.rb
 version: !ruby/object:Gem::Version
-  version: 4.9.0
+  version: 4.11.0
 platform: ruby
 authors:
 - Antar Azri
@@ -235,6 +235,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - LICENSE
 - README.md
 - data/anthropic.json
@@ -262,6 +263,8 @@ files:
 - lib/llm/function.rb
 - lib/llm/function/array.rb
 - lib/llm/function/fiber_group.rb
+- lib/llm/function/registry.rb
+- lib/llm/function/task.rb
 - lib/llm/function/task_group.rb
 - lib/llm/function/thread_group.rb
 - lib/llm/function/tracing.rb
@@ -271,6 +274,8 @@ files:
 - lib/llm/mcp/error.rb
 - lib/llm/mcp/pipe.rb
 - lib/llm/mcp/rpc.rb
+- lib/llm/mcp/transport/http.rb
+- lib/llm/mcp/transport/http/event_handler.rb
 - lib/llm/mcp/transport/stdio.rb
 - lib/llm/message.rb
 - lib/llm/mime.rb
@@ -315,6 +320,7 @@ files:
 - lib/llm/providers/google/response_adapter/models.rb
 - lib/llm/providers/google/response_adapter/web_search.rb
 - lib/llm/providers/google/stream_parser.rb
+- lib/llm/providers/google/utils.rb
 - lib/llm/providers/llamacpp.rb
 - lib/llm/providers/ollama.rb
 - lib/llm/providers/ollama/error_handler.rb
@@ -358,6 +364,8 @@ files:
 - lib/llm/registry.rb
 - lib/llm/response.rb
 - lib/llm/schema.rb
+- lib/llm/schema/all_of.rb
+- lib/llm/schema/any_of.rb
 - lib/llm/schema/array.rb
 - lib/llm/schema/boolean.rb
 - lib/llm/schema/enum.rb
@@ -366,11 +374,14 @@ files:
 - lib/llm/schema/null.rb
 - lib/llm/schema/number.rb
 - lib/llm/schema/object.rb
+- lib/llm/schema/one_of.rb
 - lib/llm/schema/parser.rb
 - lib/llm/schema/string.rb
 - lib/llm/schema/version.rb
 - lib/llm/server_tool.rb
 - lib/llm/session.rb
+- lib/llm/stream.rb
+- lib/llm/stream/queue.rb
 - lib/llm/tool.rb
 - lib/llm/tool/param.rb
 - lib/llm/tracer.rb