ruby_llm 2.0.0 → 2.1.0

data/lib/ruby_llm/judge.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  # Defines reusable probability, choice, and score questions over application data.
+  #
+  #   class TicketTriage < RubyLLM::Judge
+  #     probability :urgent, "Does this need attention today?"
+  #     choice :department, "Which team should handle this?" do
+  #       billing "Payments and refunds"
+  #       technical "Bugs and integrations"
+  #     end
+  #   end
+  #
+  #   TicketTriage.judge("Please refund my duplicate charge today.").urgent.probability
+  #
+  # Uses Configuration#default_judgment_model unless a model is declared or
+  # supplied for the call. An isolated context supplies its own default.
+  #
+  # Blocks and procs resolve once per judgment, with declared inputs available
+  # as methods. Hashes and arrays preserve structured instructions and criteria.
+  class Judge
+    class << self
+      def inherited(subclass) # :nodoc:
+        super
+        subclass.instance_variable_set(:@model_options, model.dup)
+        subclass.instance_variable_set(:@input_names, inputs.dup)
+        subclass.instance_variable_set(:@question_definitions, question_definitions.dup)
+        subclass.instance_variable_set(:@provider_options, provider_options)
+      end
+
+      # Sets the model and provider used by this judge. A block or proc resolves
+      # the model using runtime inputs. With no arguments, returns the settings.
+      # Without a declaration, uses Configuration#default_judgment_model.
+      def model(value = nil, **options, &block)
+        return @model_options || {} if value.nil? && options.empty? && !block
+
+        raise ArgumentError, 'Pass a model or a block, not both' if !value.nil? && block
+
+        @model_options = options.merge(model: block || value).freeze
+      end
+
+      # Declares required runtime inputs available in question and data blocks.
+      # With no arguments, returns the declared names.
+      #
+      #   inputs :teams
+      #   choice :department, "Which team?", -> { teams.to_h { |team| [team.slug, team.description] } }
+      def inputs(*names)
+        return @input_names || [] if names.empty?
+
+        @input_names = names.flatten.map(&:to_sym).freeze
+      end
+
+      # Sets provider-specific request options as a Hash, proc, or block.
+      # With no arguments, returns the declared options.
+      def provider_options(value = nil, &block)
+        return @provider_options || {} if value.nil? && !block
+
+        raise ArgumentError, 'Pass provider options or a block, not both' if !value.nil? && block
+
+        @provider_options = Data.copy(block || value)
+      end
+
+      # Declares a yes/no question whose answer is the probability of yes.
+      # Optional criteria describe +yes+ and +no+ in a Hash, proc, or block.
+      #
+      #   probability :urgent, "Does this need attention today?" do
+      #     yes "An explicit deadline today"
+      #     no "No deadline or a later deadline"
+      #   end
+      def probability(name, instructions = nil, criteria = nil, &)
+        declare_question(name, :probability, instructions, criteria, &)
+      end
+
+      # Declares a question selecting one named option. Options are a Hash,
+      # a proc returning a Hash, or a block declaring named descriptions.
+      #
+      #   choice :department, "Which team?" do
+      #     billing "Payments and refunds"
+      #     other nil
+      #   end
+      def choice(name, instructions = nil, options = nil, &)
+        declare_question(name, :choice, instructions, options, &)
+      end
+
+      # Declares a question scored against ordered levels. Levels are an Array
+      # or a proc or block returning one. Scores can fall between level indexes.
+      #
+      #   score :frustration, "How frustrated is the customer?", ["Calm", "Frustrated", "Angry"]
+      def score(name, instructions = nil, levels = nil, &)
+        declare_question(name, :score, instructions, levels, &)
+      end
+
+      # Judges text, a Hash, an Array, or images passed as +with:+ and returns
+      # a Judgment. A block or proc can supply the input. Declared inputs are
+      # accepted as keyword arguments; remaining options are forwarded to #judge.
+      #
+      #   TicketTriage.judge do
+      #     message "Please refund the duplicate charge today."
+      #   end
+      def judge(input = nil, **options, &)
+        values = options.slice(*inputs)
+        new(**values).judge(input, **options.except(*inputs), &)
+      end
+
+      def question_definitions # :nodoc:
+        @question_definitions ||= {}
+      end
+
+      private
+
+      def declare_question(name, type, instructions, criteria, &)
+        question = Question.new(name, type:, instructions:, criteria:, &)
+        @declared_names ||= []
+        raise ArgumentError, "Duplicate question: #{name}" if @declared_names.include?(name.to_s)
+
+        @declared_names << name.to_s
+        question_definitions[name.to_s] = question
+        self
+      end
+    end
+
+    # Creates a judge with the runtime inputs declared by its class.
+    def initialize(**inputs)
+      missing = self.class.inputs - inputs.keys
+      extra = inputs.keys - self.class.inputs
+      raise ArgumentError, "Missing judge inputs: #{missing.join(', ')}" unless missing.empty?
+      raise ArgumentError, "Unknown judge inputs: #{extra.join(', ')}" unless extra.empty?
+
+      inputs.each do |name, value|
+        raise ArgumentError, "Judge input conflicts with a method: #{name}" if respond_to?(name, true)
+
+        define_singleton_method(name) { value }
+      end
+    end
+
+    # Judges the supplied input and returns a Judgment. Accepts model and
+    # provider overrides, images as +with:+, an isolated +context:+,
+    # +provider_options:+, instrumentation +metadata:+, and a usage +owner:+,
+    # as RubyLLM.with_usage_owner describes. Additional
+    # +questions:+ are a Hash keyed by question name, with +type:+,
+    # +instructions:+, and +criteria:+ (probability), +options:+ (choice), or
+    # +levels:+ (score). The block supplies input only. Input may be omitted
+    # when images are supplied.
+    #
+    #   RubyLLM.judge("Please help today",
+    #     questions: { urgent: { type: :probability, instructions: "Is this urgent?" } })
+    #   Receipt.judge(with: "receipt.png")
+    def judge(input = nil, questions: {}, with: nil, context: nil, metadata: nil, owner: nil, **options, &block)
+      raise ArgumentError, 'Pass judgment input or a block, not both' if !input.nil? && block
+
+      data = resolve_data(block || input)
+      definitions = resolve_questions(questions)
+      settings = self.class.model.merge(provider_options: self.class.provider_options).merge(options)
+      settings = settings.transform_values { |value| resolve_data(value) }
+      Judgment.judge(data, questions: definitions, with:, context:, metadata:, owner:, **settings)
+    end
+
+    private
+
+    def resolve_data(value)
+      Data.copy(value) { |callable| Builder.resolve(callable, scope: self) }
+    end
+
+    def resolve_questions(questions)
+      questions = resolve_data(questions)
+      raise ArgumentError, 'Questions must be a Hash' unless questions.is_a?(Hash)
+
+      definitions = self.class.question_definitions.dup
+      questions.each do |name, definition|
+        raise ArgumentError, "Duplicate question: #{name}" if definitions.key?(name.to_s)
+
+        definitions[name.to_s] = Question.from_h(name, definition)
+      end
+      raise ArgumentError, 'A judgment needs at least one question' if definitions.empty?
+
+      definitions.transform_values { |definition| definition.resolve(self) }
+    end
+  end
+end

data/lib/ruby_llm/judgment.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  # The typed answers to a set of questions, with model identity and accounting.
+  # Obtain one through RubyLLM.judge or Judge.judge.
+  #
+  #   judgment.urgent.probability
+  #   judgment.department.choice
+  #   judgment.frustration.score
+  #
+  # Named answers are available as readers. Use #[] or #fetch for dynamic
+  # names or names that conflict with existing methods, such as #model.
+  class Judgment
+    include Enumerable
+    include Support::Inspectable
+    include Accounting::Usage::Result
+
+    # Returns the answers keyed by their declared String or Symbol names.
+    attr_reader :answers
+
+    # Returns the actual model ID reported by the provider.
+    attr_reader :model
+
+    # Returns the original provider response.
+    attr_reader :raw
+
+    def initialize(answers:, model:, tokens: Tokens.new, raw: nil, model_info: nil) # :nodoc:
+      @answers = answers.dup.freeze
+      @answer_keys = answers.keys.to_h { |key| [key.to_s, key] }.freeze
+      @model = model
+      @tokens = tokens
+      @raw = raw
+      @model_info = model_info
+    end
+
+    # Returns the named answer, accepting a String or Symbol, or nil if absent.
+    def [](name)
+      answers[@answer_keys[name.to_s]]
+    end
+
+    # Returns the named answer or raises KeyError if it is absent.
+    def fetch(name)
+      answers.fetch(@answer_keys.fetch(name.to_s))
+    end
+
+    # Yields each question name and answer, or returns an Enumerator.
+    def each(&)
+      answers.each(&)
+    end
+
+    # Returns token usage across all provider attempts.
+    def tokens
+      ruby_llm_usage_entries.empty? ? @tokens : ruby_llm_usage_tokens
+    end
+
+    # Returns cost across all provider attempts, preserving unknown amounts.
+    def cost
+      return ruby_llm_usage_cost unless ruby_llm_usage_entries.empty?
+
+      Cost.new(tokens:, model: @model_info)
+    end
+
+    # Returns the model, typed answers, token usage, and cost as a Hash.
+    def to_h
+      { model:, answers: answers.transform_values(&:to_h), tokens: tokens.to_h, cost: cost.to_h }
+    end
+
+    def inspect_attributes # :nodoc:
+      { model:, answers: answers.keys }
+    end
+
+    def self.judge(input, questions:, with: nil, model: nil, provider: nil, context: nil, # :nodoc:
+                   assume_model_exists: false, provider_options: {}, metadata: nil, owner: nil)
+      config = context&.config || RubyLLM.config
+      attachments = Attachment.wrap(with, config:)
+      validate_input!(input, attachments)
+      raise ArgumentError, 'A judgment requires a model' unless model || config.default_judgment_model
+
+      model, provider_instance = Models.resolve(model, provider:, assume_model_exists:, config:, operation: :judge,
+                                                       default_model: config.default_judgment_model)
+      empty_tokens = Tokens.new
+      payload = {
+        provider: provider_instance.slug,
+        provider_class: provider_instance.name,
+        model: model.id,
+        model_info: model,
+        question_count: questions.size,
+        attachment_count: attachments.size,
+        provider_options:,
+        metadata:,
+        tokens: empty_tokens,
+        cost: Cost.new(tokens: empty_tokens, model:)
+      }
+
+      RubyLLM.instrument('judgment.ruby_llm', payload, config:) do |event|
+        result = Accounting::Usage.owned_by(owner) do
+          provider_instance.judge(input, questions:, model:, with: attachments, provider_options:)
+        end
+        event[:result] = result
+        event[:tokens] = result.tokens
+        event[:cost] = result.cost
+        result
+      end
+    end
+
+    def self.validate_input!(input, attachments)
+      return if input.is_a?(String) || input.is_a?(Hash) || input.is_a?(Array) || (input.nil? && attachments.any?)
+
+      raise ArgumentError, 'Judgment input must be text, a Hash, or an Array'
+    end
+    private_class_method :validate_input!
+
+    private
+
+    def method_missing(name, *args, &block)
+      return super unless args.empty? && !block && @answer_keys&.key?(name.to_s)
+
+      self[name]
+    end
+
+    def respond_to_missing?(name, include_private = nil)
+      @answer_keys&.key?(name.to_s) || super
+    end
+  end
+end

data/lib/ruby_llm/mcp/apps.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  class MCP
+    # Reads what the MCP Apps extension keeps in a tool's _meta: the UI that
+    # renders the tool's results, and who may call the tool. Servers on
+    # older SDKs name the UI with the flat ui/resourceUri key the spec
+    # deprecated.
+    module Apps # :nodoc:
+      EXTENSION = 'io.modelcontextprotocol/ui'
+      MIME_TYPE = 'text/html;profile=mcp-app'
+      VISIBILITY = %w[model app].freeze
+
+      module_function
+
+      def uri(meta)
+        meta.dig('ui', 'resourceUri') || meta['ui/resourceUri']
+      end
+
+      def visibility(meta)
+        Array(meta.dig('ui', 'visibility') || VISIBILITY).map(&:to_sym)
+      end
+    end
+  end
+end

data/lib/ruby_llm/mcp/client.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  class MCP
+    # Speaks JSON-RPC to one MCP server over a transport. It speaks the
+    # 2026-07-28 revision and falls back to the initialize handshake for
+    # servers that predate it, declaring only its extensions so those
+    # servers never call back. A server that rejects 2026-07-28 while
+    # listing it gets the request once more; one that answers the handshake
+    # with a revision missing from LEGACY_VERSIONS is disconnected.
+    #
+    # Servers that predate 2026-07-28 may announce that their tools,
+    # prompts, or resources changed on the stream of any request. Those
+    # notifications reach the block given to ::new once the request is
+    # answered, so the block can make requests of its own. #listen opens a
+    # subscription for them instead: subscriptions/listen on newer servers,
+    # resources/subscribe and the session's own stream on older ones, which
+    # never announce the status of tasks. Their subscription counts as
+    # acknowledged once a ping confirms the session, starting a new one if
+    # it ended.
+    class Client # :nodoc:
+      VERSION = '2026-07-28'
+      LEGACY_VERSIONS = %w[2025-11-25 2025-06-18 2025-03-26 2024-11-05].freeze
+      UNSUPPORTED_VERSION = -32_022
+      MODERN_ERRORS = [-32_020, -32_021, UNSUPPORTED_VERSION].freeze
+      METHOD_NOT_FOUND = -32_601
+      DISCOVERY_TIMEOUT = 10
+      ACKNOWLEDGED = 'notifications/subscriptions/acknowledged'
+      CHANGES = %w[
+        notifications/tools/list_changed notifications/prompts/list_changed
+        notifications/resources/list_changed notifications/resources/updated
+      ].freeze
+
+      # The answer to a request the server sends: RubyLLM only answers pings.
+      def self.reply(request)
+        if request['method'] == 'ping'
+          { jsonrpc: '2.0', id: request['id'], result: {} }
+        else
+          { jsonrpc: '2.0', id: request['id'], error: { code: METHOD_NOT_FOUND, message: 'Method not found' } }
+        end
+      end
+
+      attr_reader :version
+
+      def initialize(transport, capabilities: {}, &on_change)
+        @transport = transport
+        @capabilities = capabilities
+        @on_change = on_change
+        @connecting = Mutex.new
+        @subscribed = []
+      end
+
+      def server
+        @connecting.synchronize { @server ||= discover || handshake }
+      end
+
+      def request(method, params = {}, headers: {}, &)
+        server
+        call(method, params, headers:, &)
+      rescue SessionExpired
+        @connecting.synchronize { @server = handshake }
+        call(method, params, headers:, &)
+      end
+
+      def list(method, key)
+        page = request(method)
+        items = page.fetch(key, [])
+        while (cursor = page['nextCursor'])
+          page = request(method, { cursor: })
+          items += page.fetch(key, [])
+        end
+        items
+      end
+
+      # Subscribes to +changes+, a subscriptions/listen filter, and yields
+      # each notification of the subscription, starting with the server's
+      # acknowledgment. Returns when the server ends the subscription and
+      # raises Error when it refuses one or the stream breaks.
+      def listen(changes, &)
+        server
+        raise ConfigurationError, 'The MCP transport does not respond to listen' unless @transport.respond_to?(:listen)
+
+        modern? ? subscribe(changes, &) : listen_to_session(changes, &)
+      end
+
+      def modern?
+        version == VERSION
+      end
+
+      def close
+        @connecting.synchronize do
+          @transport.close
+          @server = nil
+          @version = nil
+          @subscribed = []
+        end
+      end
+
+      private
+
+      def discover
+        @version = VERSION
+        result = call('server/discover', timeout: DISCOVERY_TIMEOUT)
+        result if Array(result['supportedVersions']).include?(VERSION)
+      rescue Error => e
+        raise if MODERN_ERRORS.include?(e.code)
+      end
+
+      def handshake
+        @version = nil
+        params = { protocolVersion: LEGACY_VERSIONS.first, capabilities: @capabilities.slice(:extensions),
+                   clientInfo: client_info }
+        result = call('initialize', params)
+        unless LEGACY_VERSIONS.include?(result['protocolVersion'])
+          @transport.close
+          raise Error, "The server answered with protocol version #{result['protocolVersion']}, " \
+                       'which RubyLLM does not speak'
+        end
+
+        @version = result['protocolVersion']
+        @subscribed = []
+        @transport.notify(message('notifications/initialized'), version:)
+        result
+      end
+
+      def call(method, params = {}, timeout: nil, headers: {}, retried: false, &on_notification)
+        request = message(method, params, id: SecureRandom.uuid)
+        answer(exchange(request, timeout:, headers:, &on_notification))
+      rescue Error => e
+        raise if retried || !offers_version?(e)
+
+        call(method, params, timeout:, headers:, retried: true, &on_notification)
+      end
+
+      def exchange(request, timeout:, headers:, &on_notification)
+        changes = []
+        @transport.request(request, version:, timeout:, headers:) do |notification|
+          CHANGES.include?(notification['method']) ? changes << notification : on_notification&.call(notification)
+        end
+      rescue CancelledError
+        cancel(request)
+        raise
+      ensure
+        changes.each { |change| @on_change&.call(change) }
+      end
+
+      def subscribe(changes)
+        request = message('subscriptions/listen', { notifications: changes }, id: SecureRandom.uuid)
+        ending = catch(request) do
+          @transport.listen(request, version:) do |notification|
+            throw request, notification if cancels?(notification, request)
+            yield notification
+          end
+        end
+        answer(ending)
+      rescue CancelledError
+        cancel(request)
+        raise
+      end
+
+      def listen_to_session(changes, &)
+        uris = Array(changes[:resourceSubscriptions])
+        (@subscribed - uris).each { |uri| request('resources/unsubscribe', { uri: }) }
+        uris.each { |uri| request('resources/subscribe', { uri: }) }
+        @subscribed = uris
+        request('ping')
+        listened = changes.except(:taskIds).transform_keys(&:to_s)
+        yield({ 'method' => ACKNOWLEDGED, 'params' => { 'notifications' => listened } })
+        @transport.listen(nil, version:, &)
+      rescue SessionExpired
+        @connecting.synchronize { @server = handshake }
+        raise
+      end
+
+      def cancels?(notification, request)
+        notification['method'] == 'notifications/cancelled' && notification.dig('params', 'requestId') == request[:id]
+      end
+
+      def cancel(request)
+        @transport.cancel(message('notifications/cancelled', { requestId: request[:id] }), version:)
+      end
+
+      def answer(response)
+        error = response['error']
+        raise Error.new(error['message'], code: error['code'], data: error['data']) if error
+
+        response['result']
+      end
+
+      def offers_version?(error)
+        supported = error.data['supported'] if error.data.is_a?(Hash)
+        modern? && error.code == UNSUPPORTED_VERSION && Array(supported).include?(VERSION)
+      end
+
+      def message(method, params = {}, id: nil)
+        params = params.merge(_meta: meta.merge(params.fetch(:_meta, {}))) if modern?
+        { jsonrpc: '2.0', id:, method:, params: }.compact
+      end
+
+      def meta
+        {
+          'io.modelcontextprotocol/protocolVersion' => VERSION,
+          'io.modelcontextprotocol/clientInfo' => client_info,
+          'io.modelcontextprotocol/clientCapabilities' => @capabilities
+        }
+      end
+
+      def client_info
+        { name: 'ruby_llm', version: RubyLLM::VERSION }
+      end
+    end
+  end
+end

data/lib/ruby_llm/mcp/collection.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  class MCP
+    # The MCP servers connected to a chat, readable by name.
+    #
+    #   chat.with_mcp(Linear.new(user: current_user))
+    #   chat.mcp.linear     # => #<Linear ...>
+    #   chat.mcp[:linear]   # => #<Linear ...>
+    #   chat.mcp.map(&:name) # => ["linear"]
+    #
+    class Collection
+      include Enumerable
+
+      def initialize # :nodoc:
+        @servers = {}
+      end
+
+      def <<(server) # :nodoc:
+        @servers[server.name.to_sym] = server
+        self
+      end
+
+      # Returns the server named +name+, or +nil+.
+      def [](name)
+        @servers[name.to_sym]
+      end
+
+      # Yields each server.
+      def each(&)
+        @servers.each_value(&)
+      end
+
+      # Returns whether no servers are connected.
+      def empty?
+        @servers.empty?
+      end
+
+      def inspect # :nodoc:
+        "#<#{self.class.name} #{@servers.keys.join(', ')}>"
+      end
+
+      private
+
+      def method_missing(name, *arguments)
+        return super unless arguments.empty? && @servers.key?(name)
+
+        @servers[name]
+      end
+
+      def respond_to_missing?(name, include_private = nil)
+        @servers.key?(name) || super
+      end
+    end
+  end
+end

data/lib/ruby_llm/mcp/content.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  class MCP
+    # Reads MCP content blocks into text and attachments. Tool results and
+    # prompt messages share the format.
+    module Content # :nodoc:
+      module_function
+
+      def read(blocks)
+        texts, attachments = Array(blocks).filter_map { |block| part(block) }.partition { |part| part.is_a?(String) }
+        [texts.join("\n\n"), attachments]
+      end
+
+      def part(block)
+        case block['type']
+        when 'text' then block['text']
+        when 'image', 'audio' then attachment(block['data'], block['mimeType'], block['type'])
+        when 'resource' then embedded(block['resource'] || {})
+        when 'resource_link' then [block['title'] || block['name'], block['uri']].compact.join(': ')
+        end
+      end
+
+      def embedded(resource)
+        return resource['text'] if resource['text']
+        return unless resource['blob']
+
+        attachment(resource['blob'], resource['mimeType'], filename(resource['uri']))
+      end
+
+      def attachment(data, mime_type, name)
+        extension = Marcel::TYPE_EXTS[mime_type]&.first
+        name = "#{name}.#{extension}" unless name.to_s.include?('.') || extension.nil?
+        Attachment.new(StringIO.new(Base64.decode64(data.to_s)), filename: name.to_s)
+      end
+
+      def filename(uri)
+        File.basename(URI(uri.to_s).path.to_s)
+      rescue URI::InvalidURIError
+        'resource'
+      end
+    end
+  end
+end

data/lib/ruby_llm/mcp/error.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  class MCP
+    # Raised when an MCP server answers with a JSON-RPC error, an unexpected
+    # HTTP status, or not at all.
+    #
+    #   begin
+    #     github.search_issues(query: "flaky")
+    #   rescue RubyLLM::MCP::Error => e
+    #     e.code  # => -32602
+    #   end
+    class Error < RubyLLM::Error
+      # The JSON-RPC error code, or +nil+ when the failure had none.
+      attr_reader :code
+
+      # Additional information the server attached to the error, or +nil+.
+      attr_reader :data
+
+      def initialize(message = nil, code: nil, data: nil, response: nil) # :nodoc:
+        @code = code
+        @data = data
+        super(message, response:)
+      end
+    end
+  end
+end