ruby_llm-modes 0.1.0

data/lib/ruby_llm/modes/classifiers/judge.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Modes
+    module Classifiers
+      # The +:judge+ backend: one RubyLLM.judge call with a single +choice+
+      # question over the available modes.
+      #
+      # The state is the routing input as data (instructions, conversation,
+      # latest message); the mode descriptions are the choice options. The
+      # answer carries a probability per mode and a +confidence+ reported
+      # by the judgment model with it: how concentrated the distribution
+      # is on one mode, not a self-report, and a different scale from the
+      # chat backend's. It is passed through as is. There is no free text,
+      # so +reason+ is always nil.
+      #
+      # +model+ is passed to RubyLLM.judge as given (nil selects RubyLLM's
+      # default judgment model); +provider+ only when given. +judge:+ replaces
+      # RubyLLM.judge; it is called with the same arguments and must return
+      # a Judgment.
+      #
+      # RubyLLM.judge is not in every RubyLLM release. Without it the
+      # backend cannot run, and the router says so when it is built.
+      class Judge
+        QUESTION = <<~TEXT.strip
+          Which mode should answer the latest user message? Use the conversation
+          only to understand what the latest message refers to.
+        TEXT
+
+        attr_reader :model, :provider
+
+        def self.available?
+          RubyLLM.respond_to?(:judge)
+        end
+
+        def initialize(model: nil, provider: nil, judge: nil)
+          @model = model
+          @provider = provider
+          @judge = judge
+        end
+
+        def call(message:, history:, modes:, instructions:, inputs:)
+          @resolved_model = nil
+          state = self.class.state(message:, history:, instructions:)
+          judgment = judge.call(state, questions: self.class.questions(modes), **model_options)
+          decision_from(judgment)
+        end
+
+        # What ran, for Route#classifier: the model the provider reported
+        # once a judgment came back, else the declared model.
+        def trace
+          { with: "judge", model: @resolved_model || model }
+        end
+
+        # The judgment state: +instructions+ when present, the normalised
+        # +history+ as a conversation, and the latest +message+.
+        def self.state(message:, history:, instructions: nil)
+          state = {}
+          state["instructions"] = instructions unless instructions.nil? || instructions.empty?
+          state["conversation"] = history.map { |entry| transcript_entry(entry) } if history.any?
+          state["latest_message"] = message.to_s
+          state
+        end
+
+        # One choice question whose options are the modes (Registration
+        # values), name to description.
+        def self.questions(modes)
+          { mode: { type: :choice, instructions: QUESTION, options: modes.to_h { |mode| [ mode.name.to_s, mode.description.to_s ] } } }
+        end
+
+        def self.transcript_entry(entry)
+          entry[:role] ? { "role" => entry[:role].to_s, "content" => entry[:content].to_s } : entry[:content].to_s
+        end
+
+        private_class_method :transcript_entry
+
+        private
+
+        def judge
+          return @judge if @judge
+          raise DeclarationError, "RubyLLM.judge is not available in ruby_llm #{RubyLLM::VERSION}" unless self.class.available?
+
+          RubyLLM.method(:judge)
+        end
+
+        def model_options
+          options = { model: model }
+          options[:provider] = provider if provider
+          options
+        end
+
+        def decision_from(judgment)
+          answer = judgment[:mode] if judgment.respond_to?(:[])
+          unless answer.respond_to?(:choice) && answer.respond_to?(:probabilities) && answer.respond_to?(:confidence)
+            raise ContractError, "judge backend returned #{answer.class} for the mode question, expected a choice answer"
+          end
+
+          resolved = judgment.model if judgment.respond_to?(:model)
+          @resolved_model = resolved if resolved.is_a?(String)
+
+          confidence = answer.confidence
+          Decision.new(
+            mode_name: answer.choice&.to_s,
+            confidence: confidence.is_a?(Numeric) ? confidence.to_f : confidence,
+            reason: nil,
+            probabilities: answer.probabilities&.to_h&.transform_keys(&:to_s)
+          )
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/modes/decision.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Modes
+    # What the classifier said, untouched.
+    #
+    # mode_name:     String or nil
+    # confidence:    Float 0..1, or nil for "not scored"
+    # reason:        String or nil
+    # probabilities: { name => Float } or nil
+    Decision = Data.define(:mode_name, :confidence, :reason, :probabilities) do
+      def initialize(mode_name: nil, confidence: nil, reason: nil, probabilities: nil)
+        super
+      end
+
+      # The fields with string keys, for logs and serialisation.
+      # "probabilities" is present only when the classifier set them.
+      def to_h
+        hash = super.transform_keys(&:to_s)
+        probabilities ? hash.merge("probabilities" => probabilities.transform_keys(&:to_s)) : hash.except("probabilities")
+      end
+    end
+  end
+end

data/lib/ruby_llm/modes/errors.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Modes
+    # Base class for the gem's own errors.
+    class Error < StandardError; end
+
+    # A router declaration is invalid. Raised by Router.new.
+    class DeclarationError < Error; end
+
+    # Router#force was asked for a name that is not registered or not
+    # available for this call.
+    class UnknownMode < KeyError; end
+
+    # A classifier returned something outside the classifier contract: not a
+    # Decision, a mode_name or reason that is not a String, a confidence
+    # that is NaN or outside 0..1, probabilities that are not a Hash of
+    # numbers, or a chat response that is not a JSON object.
+    class ContractError < Error; end
+  end
+end

data/lib/ruby_llm/modes/mode.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Modes
+    # Extend into an Agent class to make it routable.
+    #
+    #   class TutorAgent < RubyLLM::Agent
+    #     extend RubyLLM::Modes::Mode
+    #     description "Explains words and grammar."
+    #     mode_name "tutor"   # optional
+    #   end
+    #
+    # Neither value is inherited. A subclass declares its own description,
+    # and its name is derived from its own class name unless overridden.
+    #
+    # Both texts follow Agent's prompt convention. A class that declares no
+    # +description+ reads <tt>app/prompts/<agent path>/description.txt.erb</tt>
+    # when the file exists, rendered without locals; a class that declares
+    # no +instructions+ reads <tt>instructions.txt.erb</tt> next to it, as
+    # any Agent does.
+    #
+    # A mode takes one turn of a chat that already has its own system
+    # prompt, so its +instructions+ default to <tt>append: true</tt> (added
+    # after the chat's prompt) and <tt>persist: false</tt> (kept out of a
+    # Rails record's history), for the template as well as for an explicit
+    # declaration. Declare either option to override.
+    module Mode
+      # Agent's +instructions+ with mode defaults: <tt>append: true</tt> and
+      # <tt>persist: false</tt>. Everything else, including the getter form
+      # and prompt locals, is Agent's.
+      def instructions(text = nil, append: true, persist: false, **options, &block)
+        super
+      end
+
+      # Tells the router what the mode does and when to pick it, as a
+      # Tool's +description+ tells the model when to call the tool. Sets
+      # the text, or returns this class's own one: the declaration, else
+      # the +description+ prompt file when it exists. Multi-line text is
+      # fine; surrounding whitespace is removed.
+      def description(text = nil)
+        return @description || description_from_prompt if text.nil?
+
+        @description = text.to_s.strip
+      end
+
+      # Sets the registration name, or returns it: the override declared on
+      # this class, else the name derived from the class name (see
+      # Mode.derive_name).
+      def mode_name(name = nil)
+        return @mode_name || Mode.derive_name(self) if name.nil?
+
+        @mode_name = name.to_s
+      end
+
+      # Derives a registration name from a class name: the trailing "Agent"
+      # removed (a segment that is only "Agent" stays), namespaces kept as
+      # path segments, the rest underscored.
+      #
+      #   TutorAgent       -> "tutor"
+      #   Chat::TutorAgent -> "chat/tutor"
+      #   TutorModeAgent   -> "tutor_mode"
+      #
+      # Returns nil for an anonymous class.
+      def self.derive_name(klass)
+        return if klass.name.nil?
+
+        base = klass.name.sub(/(?<=\w)Agent\z/, "")
+        RubyLLM::Support::Utils.underscore(base.gsub("::", "/"))
+      end
+
+      private
+
+      # Agent's conventional +instructions+ template with the mode defaults
+      # instead of Agent's. Explicit declarations are returned as they are.
+      def instructions_config
+        config = super
+        return config if instruction_declarations.any?
+
+        config.map { |declaration| declaration.merge(append: true, persist: false) }
+      end
+
+      def description_from_prompt
+        return if name.nil?
+
+        prompt = RubyLLM::Prompt.new("#{prompt_agent_path}/description")
+        return unless File.exist?(prompt.path)
+
+        prompt.render.strip
+      end
+    end
+  end
+end

data/lib/ruby_llm/modes/registration.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Modes
+    # One +mode+ declaration of a router, resolved. +klass+ is the agent
+    # class, +name+ the registration name, +description+ the routing
+    # description, and +condition+ the +if:+ lambda or nil.
+    #
+    # Router#modes returns the registrations available for a call, and a
+    # classifier receives the same objects as +modes:+.
+    Registration = Data.define(:klass, :name, :description, :condition) do
+      def available_on?(router)
+        condition.nil? || !!router.instance_exec(&condition)
+      end
+    end
+  end
+end

data/lib/ruby_llm/modes/route.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Modes
+    # What the router decided for one chat, with the classifier's
+    # decision attached.
+    #
+    # mode_class:  the agent class
+    # mode_name:   its registration name
+    # decided_by:  :caller, :classifier, or :fallback
+    # reason:      why this mode
+    # decision:    Decision, or nil when no classifier ran
+    # duration_ms: Integer, nil on caller-decided routes
+    # classifier:  { with: "chat" | "judge" | "custom", model: String | nil },
+    #              or nil when no backend was called
+    # error:       the exception a failed classifier raised, or nil
+    # chat:        the chat the route was decided for
+    # inputs:      the router's inputs, handed to the mode's agent
+    Route = Data.define(:mode_class, :mode_name, :decided_by, :reason, :decision, :duration_ms, :classifier, :error,
+                        :chat, :inputs) do
+      def initialize(mode_class:, mode_name:, decided_by:, reason:, decision: nil, duration_ms: nil, classifier: nil,
+                     error: nil, chat: nil, inputs: {})
+        super
+      end
+
+      # The mode as an agent on the route's chat: Agent.new applies the
+      # mode's configuration to the chat and returns the agent wrapping
+      # it, so call this once per turn. The router's inputs are the
+      # agent's +inputs:+; the agent takes the names it declared and
+      # ignores the rest. Extra keywords go to Agent.new as given, except
+      # +chat:+: the route was decided for its own chat.
+      def mode(**options)
+        raise ArgumentError, "the route is bound to its chat; mode takes no chat:" if options.key?(:chat)
+
+        mode_class.new(chat:, inputs:, **options)
+      end
+
+      # The fields with string keys, for logs. Drops the mode class, the
+      # error, the chat, and the inputs; the nested decision and classifier
+      # trace get string keys too. Serializes decided_by as a string.
+      def to_h
+        super.except(:mode_class, :error, :chat, :inputs).transform_keys(&:to_s).tap do |hash|
+          hash["decided_by"] = decided_by.to_s
+          hash["decision"] = decision&.to_h
+          hash["classifier"] = classifier&.transform_keys(&:to_s)
+        end
+      end
+    end
+  end
+end