activeagent 1.9.6 → 1.9.8

data/lib/active_agent/evals/catalog.rb

@@ -6,8 +6,9 @@ module ActiveAgent
   module Evals
     # A catalog of evaluation scenarios: the products an app evaluates, each
     # with the named sets of scenarios it is tested with. One YAML document,
-    # or several layered like Suite's: a later document's product, set or
-    # scenario with a key already present replaces it, a new key is appended.
+    # or several layered like Suite's: a later document's product, set,
+    # scenario or criterion with a key already present replaces it, a new key
+    # is appended.
     #
     #   catalog: support_desk
     #   name: Support Desk
@@ -16,11 +17,14 @@ module ActiveAgent
     #     - key: triage
     #       name: Triage agent
     #       agent: TriageAgent            # the agent class, or a dashboard agent's name
+    #       criteria: { shared: [] }      # optional; named criteria lists, as a Suite's
+    #       pass: { min_pass_rate: 0.8 }  # optional; the product's bars (PassThresholds)
     #       sets:
     #         - key: smoke
     #           name: Smoke
     #           judge: { kind: rules }    # optional; an evaluation's judge_kind and judge_model
     #           criteria: []              # optional; an evaluation's criteria
+    #           pass: { gated: false }    # optional; the set's own bars
     #           scenarios:
     #             - key: refund_request
     #               prompt: A customer asks for a refund on order 1042.
@@ -47,12 +51,12 @@ module ActiveAgent
 
       # The keys a product, set or scenario may carry. Anything else is kept
       # under `metadata` so a document round-trips.
-      PRODUCT_KEYS = %w[key name description agent sets].freeze
-      SET_KEYS = %w[key name description judge criteria scenarios].freeze
-      SCENARIO_KEYS = %w[key prompt expect expectations tools contains not_contains notes tags params production_only position].freeze
+      PRODUCT_KEYS = %w[key name description agent criteria pass sets].freeze
+      SET_KEYS = %w[key name description judge criteria pass scenarios].freeze
+      SCENARIO_KEYS = Scenario::DOCUMENT_KEYS
       CATALOG_KEYS = %w[catalog name description products suite groups].freeze
 
-      Product = Struct.new(:key, :name, :description, :agent, :metadata, :sets, :position, keyword_init: true) do
+      Product = Struct.new(:key, :name, :description, :agent, :criteria, :pass, :metadata, :sets, :position, keyword_init: true) do
         def set(key)
           sets.find { |set| set.key == key.to_s }
         end
@@ -62,7 +66,7 @@ module ActiveAgent
         end
       end
 
-      Set = Struct.new(:key, :name, :description, :judge, :criteria, :metadata, :scenarios, :position, keyword_init: true)
+      Set = Struct.new(:key, :name, :description, :judge, :criteria, :pass, :metadata, :scenarios, :position, keyword_init: true)
 
       attr_reader :key, :name, :description, :metadata, :products
 
@@ -114,14 +118,21 @@ module ActiveAgent
       # Scenarios across the catalog, narrowed by product key, set key,
       # scenario keys, or any of them; `production_only` scenarios are
       # dropped unless `include_production_only` is true. Each scenario's
-      # group is its set's key and its group_name the set's name.
-      def scenarios(product: nil, set: nil, keys: nil, include_production_only: true)
+      # group is its set's key and its group_name the set's name. With
+      # `strict`, every key in `keys` must name a scenario of the catalog (see
+      # Suite.select), and a key outside the chosen product or set selects
+      # nothing.
+      def scenarios(product: nil, set: nil, keys: nil, include_production_only: true, strict: false)
         selected = products
         selected = selected.select { |entry| entry.key == product.to_s } if product.present?
         selected = selected.flat_map(&:sets)
         selected = selected.select { |entry| entry.key == set.to_s } if set.present?
         selected = selected.flat_map(&:scenarios)
-        selected = selected.select { |scenario| Array(keys).map(&:to_s).include?(scenario.key) } if keys.present?
+        if strict
+          selected = Suite.select(selected, keys: keys, known: all_scenarios, name: key)
+        elsif keys.present?
+          selected = selected.select { |scenario| Array(keys).map(&:to_s).include?(scenario.key) }
+        end
         selected = selected.reject(&:production_only?) unless include_production_only
         selected
       end
@@ -136,16 +147,24 @@ module ActiveAgent
 
       # One product's sets as a Suite (every set a group), or one set alone,
       # for code that takes a suite: `Runner.new(scenarios: catalog.suite_for(:triage).scenarios, ...)`.
+      # The product's `pass` is the suite's and each set's its group's.
       def suite_for(product_key, set_key = nil)
         found = product(product_key)
         sets = set_key ? [ set(product_key, set_key) ] : found.sets
         Suite.new([ {
           "suite" => [ key, found.key, set_key ].compact.join("/"),
           "description" => found.description || description,
+          "criteria" => found.criteria,
+          "pass" => found.pass,
           "groups" => sets.map { |entry| set_document(entry) }
         } ])
       end
 
+      # The bars a product, or one of its sets, declares (PassThresholds).
+      def pass_thresholds(product_key, set_key = nil)
+        suite_for(product_key, set_key).pass_thresholds
+      end
+
       # The canonical document: keys in a fixed order, nothing empty, so the
       # same content always reads the same.
       def to_h
@@ -182,8 +201,10 @@ module ActiveAgent
             "key" => product_key,
             "name" => document["name"].presence || product_key,
             "description" => document["description"],
+            "criteria" => document["criteria"],
+            "pass" => document["pass"],
             "sets" => Array(document["groups"])
-          } ]
+          }.compact ]
         }.compact
       end
 
@@ -196,16 +217,70 @@ module ActiveAgent
             existing = products.find { |product| product["key"] == incoming["key"].to_s }
             if existing
               %w[name description agent].each { |field| existing[field] = incoming[field] if incoming[field].present? }
+              merge_pass(existing, incoming["pass"], "product #{existing['key'].inspect}")
               existing.merge!(incoming.except(*PRODUCT_KEYS))
+              merge_criteria_lists(existing, incoming)
               merge_sets(existing, Array(incoming["sets"]))
             else
-              products << incoming.merge("key" => incoming["key"].to_s, "sets" => [])
+              products << incoming.merge("key" => incoming["key"].to_s, "criteria" => {}, "sets" => [])
+                .tap { |product| merge_criteria_lists(product, incoming) }
                 .tap { |product| merge_sets(product, Array(incoming["sets"])) }
             end
           end
         end
       end
 
+      # Layers a product document's named criteria lists over the product's:
+      # by name, and within a name by criterion key.
+      def merge_criteria_lists(product, incoming)
+        criteria_lists(incoming).each do |list_name, list|
+          merge_criteria(product["criteria"][list_name] ||= [], list, "list #{list_name.inspect} of product #{product['key'].inspect}")
+        end
+      end
+
+      # A product document's `criteria` as `name => list`; a bare list is the
+      # one list named "default", and an empty one declares no list.
+      def criteria_lists(product)
+        value = product["criteria"]
+        return {} if value.nil? || value == []
+
+        value = { "default" => value } if value.is_a?(Array)
+        unless value.is_a?(Hash)
+          raise InvalidDocument, "the criteria of product #{product['key'].inspect} are not a list or a mapping of lists"
+        end
+
+        value.to_h do |list_name, list|
+          raise InvalidDocument, "criteria list #{list_name.inspect} of product #{product['key'].inspect} is not a list" unless list.is_a?(Array)
+
+          [ list_name.to_s, list ]
+        end
+      end
+
+      # Layers `incoming` criteria over `existing` by key: a criterion with a
+      # key already present replaces it in place and a new key is appended;
+      # an empty or missing `incoming` declares none. A criterion without a
+      # key is appended once, when `allow_keyless` is true, and refused
+      # otherwise.
+      def merge_criteria(existing, incoming, owner, allow_keyless: false)
+        return if incoming.blank?
+        raise InvalidDocument, "the criteria of #{owner} are not a list" unless incoming.is_a?(Array)
+
+        incoming.each do |criterion|
+          raise InvalidDocument, "a criterion in #{owner} is not a mapping" unless criterion.is_a?(Hash)
+
+          criterion = criterion.deep_stringify_keys
+          if criterion["key"].present?
+            criterion["key"] = criterion["key"].to_s
+            index = existing.index { |entry| entry["key"] == criterion["key"] }
+            index ? existing[index] = criterion : existing << criterion
+          elsif allow_keyless
+            existing << criterion unless existing.include?(criterion)
+          else
+            raise InvalidDocument, "a criterion in #{owner} has no key"
+          end
+        end
+      end
+
       def merge_sets(product, incoming_sets)
         incoming_sets.each do |incoming|
           incoming = incoming.to_h.deep_stringify_keys
@@ -213,16 +288,31 @@ module ActiveAgent
 
           existing = product["sets"].find { |set| set["key"] == incoming["key"].to_s }
           if existing
-            %w[name description judge criteria].each { |field| existing[field] = incoming[field] if incoming[field].present? }
+            %w[name description judge].each { |field| existing[field] = incoming[field] if incoming[field].present? }
+            merge_pass(existing, incoming["pass"], "set #{existing['key'].inspect} of product #{product['key'].inspect}")
             existing.merge!(incoming.except(*SET_KEYS))
+            merge_set_criteria(existing, incoming, product)
             merge_scenarios(existing, Array(incoming["scenarios"]))
           else
-            product["sets"] << incoming.merge("key" => incoming["key"].to_s, "scenarios" => [])
+            product["sets"] << incoming.merge("key" => incoming["key"].to_s, "criteria" => [], "scenarios" => [])
+              .tap { |set| merge_set_criteria(set, incoming, product) }
               .tap { |set| merge_scenarios(set, Array(incoming["scenarios"])) }
           end
         end
       end
 
+      # A later document's `pass` layers over the existing one key by key.
+      def merge_pass(existing, incoming, place)
+        incoming = pass_block(incoming, place)
+        existing["pass"] = pass_block(existing["pass"], place).merge(incoming) if incoming.any?
+      end
+
+      # Layers a set document's `criteria` over the set's by key; a set keeps
+      # a criterion without a key.
+      def merge_set_criteria(set, incoming, product)
+        merge_criteria(set["criteria"], incoming["criteria"], "set #{set['key'].inspect} of product #{product['key'].inspect}", allow_keyless: true)
+      end
+
       def merge_scenarios(set, incoming_scenarios)
         incoming_scenarios.each do |scenario|
           scenario = scenario.to_h.deep_stringify_keys
@@ -237,39 +327,67 @@ module ActiveAgent
 
       def build_products(documents)
         documents.each_with_index.map do |product, position|
+          sets = product["sets"].each_with_index.map { |set, set_position| build_set(set, set_position, product["key"]) }
           Product.new(
             key: product["key"],
             name: product["name"].presence || product["key"],
             description: product["description"].presence,
             agent: product["agent"].presence&.to_s,
+            criteria: product["criteria"],
+            pass: validated_pass(product["pass"], PassThresholds::SUITE_KEYS, "product #{product['key'].inspect}"),
             metadata: product.except(*PRODUCT_KEYS),
             position: position,
-            sets: product["sets"].each_with_index.map { |set, set_position| build_set(set, set_position) }
+            sets: sets
           )
         end
       end
 
-      def build_set(set, position)
+      def build_set(set, position, product_key)
         Set.new(
           key: set["key"],
           name: set["name"].presence || set["key"],
           description: set["description"].presence,
           judge: (set["judge"] || {}).to_h.stringify_keys,
-          criteria: Array(set["criteria"]).map { |criterion| criterion.to_h.deep_stringify_keys },
+          criteria: set["criteria"],
+          pass: validated_pass(set["pass"], PassThresholds::GROUP_KEYS, "set #{set['key'].inspect} of product #{product_key.inspect}"),
           metadata: set.except(*SET_KEYS),
           position: position,
           scenarios: set["scenarios"].each_with_index.map do |entry, index|
-            Scenario.from_hash(entry.merge("position" => index), group: set["key"], group_name: set["name"].presence || set["key"])
+            Scenario.from_hash(entry.merge("position" => index), group: set["key"], group_name: set["name"].presence || set["key"],
+              metadata: entry.except(*SCENARIO_KEYS))
           end
         )
       end
 
+      # A `pass` block as a string-keyed Hash, {} when absent, checked the
+      # way PassThresholds reads it (`allowed` is SUITE_KEYS for a product,
+      # GROUP_KEYS for a set) so a block the suite would refuse fails the
+      # catalog as it loads rather than the first run that asks for it; a
+      # refusal names the product or set the block sits on.
+      def validated_pass(value, allowed, place)
+        pass = pass_block(value, place)
+        PassThresholds.validate(pass, allowed, place)
+        pass
+      rescue ArgumentError => e
+        raise InvalidDocument, e.message
+      end
+
+      # A `pass` block as a string-keyed Hash, {} when absent; anything but
+      # a mapping is refused naming the product or set it sits on.
+      def pass_block(value, place)
+        PassThresholds.pass_block(value, place)
+      rescue ArgumentError => e
+        raise InvalidDocument, e.message
+      end
+
       def product_document(product)
         compact({
           "key" => product.key,
           "name" => product.name,
           "description" => product.description,
           "agent" => product.agent,
+          "criteria" => product.criteria,
+          "pass" => product.pass,
           "sets" => product.sets.map { |set| set_document(set) }
         }.merge(product.metadata))
       end
@@ -281,6 +399,7 @@ module ActiveAgent
           "description" => set.description,
           "judge" => set.judge,
           "criteria" => set.criteria,
+          "pass" => set.pass,
           "scenarios" => set.scenarios.map { |scenario| scenario_document(scenario) }
         }.merge(set.metadata))
       end
@@ -294,7 +413,19 @@ module ActiveAgent
           "tags" => scenario.tags,
           "params" => scenario.params,
           "production_only" => (true if scenario.production_only?)
-        })
+        }).merge(canonical_metadata(scenario.metadata.to_h.deep_stringify_keys.except(*SCENARIO_KEYS)))
+      end
+
+      # JSON object storage may reorder keys; array order remains meaningful.
+      def canonical_metadata(value)
+        case value
+        when Hash
+          value.keys.sort.to_h { |key| [ key, canonical_metadata(value[key]) ] }
+        when Array
+          value.map { |entry| canonical_metadata(entry) }
+        else
+          value
+        end
       end
 
       def compact(hash)

data/lib/active_agent/evals/gate_check.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module ActiveAgent
+  module Evals
+    # A report's pass gates as one check with the message a failing
+    # assertion prints, so TestHelper#assert_meets_pass_gates and the RSpec
+    # matcher (`active_agent/evals/rspec`) fail with the same text: how many
+    # gates are not met, each of them as a sentence, then the failures to
+    # read under a heading per group.
+    #
+    #   check = ActiveAgent::Evals::GateCheck.new(report)
+    #   check.met?   # => false
+    #   puts check.message
+    #   # 2 of 5 pass gates not met
+    #   # - Order support · gpt-5-mini: 1/2 (50%) passed, below 100%
+    #   # - All · gpt-5-mini: 3/4 (75%) passed, below 80%
+    #   #
+    #   # Order support failures:
+    #   # - `order_status` on `gpt-5-mini`: low quality — Scored 50% against a pass threshold of 70%, weakest on response_present (100%).
+    class GateCheck
+      # @param report [Report] the report whose gates are checked
+      # @param thresholds [PassThresholds, nil] the bars to hold the report
+      #   to; without them Report#gates decides, taking the report's own,
+      #   else the defaults. Only their `min_pass_rate` and `gated` apply:
+      #   whether an answer passed was settled at the threshold the Runner
+      #   scored it at, so a different `threshold` here changes nothing.
+      def initialize(report, thresholds = nil)
+        @report = report
+        @bars = [ thresholds ].compact
+      end
+
+      # Whether every gate is met.
+      def met?
+        @report.passed?(*@bars)
+      end
+
+      # Every gate, in Report#gates order.
+      def gates
+        @report.gates(*@bars)
+      end
+
+      # The gates that are not met, in gates order.
+      def unmet
+        gates.reject(&:met?)
+      end
+
+      # The text a failing assertion prints. The first line counts the gates
+      # not met, or is the one line "every pass gate met" when none is; then
+      # each unmet gate as Gate#to_s; then, after a blank line, the failures
+      # to read: for each group with an unmet gate, in gates order, "<group>
+      # failures:" over Report#failures_markdown for that group. An unmet All
+      # row adds the failures it counts, those in gated groups or in no
+      # group: under "Failures:" when no group row is unmet, else the ones
+      # outside the groups already listed under "Other failures:", when there
+      # are any. An ungated group's failures count toward no gate and are
+      # never listed.
+      def message
+        all = gates
+        return "no result reached a pass gate; the run evaluated nothing" if all.empty?
+
+        unmet = all.reject(&:met?)
+        return "every pass gate met" if unmet.empty?
+
+        lines = [ "#{unmet.size} of #{all.size} pass gates not met", *unmet.map { |gate| "- #{gate}" } ]
+        grouped = unmet.reject { |gate| gate.group.nil? }.uniq(&:group)
+        grouped.each { |gate| lines << "" << "#{gate.name} failures:" << @report.failures_markdown(group: gate.group) }
+        if unmet.any? { |gate| gate.group.nil? }
+          ungated = all.reject(&:gated).map(&:group)
+          listed = grouped.map(&:group)
+          others = @report.failures.reject { |result| (ungated + listed).include?(result.scenario.group) }
+          heading = listed.empty? ? "Failures:" : "Other failures:"
+          lines << "" << heading << others.map { |result| @report.failure_markdown(result) }.join("\n") if others.any?
+        end
+        lines.join("\n")
+      end
+      alias to_s message
+    end
+  end
+end

data/lib/active_agent/evals/pass_thresholds.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module ActiveAgent
+  module Evals
+    # The bars a suite declares for a run: the score every answer must reach
+    # (the Runner's and the Report's threshold), the share of a model's
+    # answers that must pass, and the groups whose results are reported but
+    # not gated. Report#gates compares each group's pass rate against them.
+    #
+    #   suite: support_desk
+    #   pass:
+    #     threshold: 0.7
+    #     min_pass_rate: 0.8
+    #   groups:
+    #     - key: orders
+    #       pass: { min_pass_rate: 1.0 }
+    #     - key: experimental
+    #       pass: { gated: false }
+    #
+    # A group's `min_pass_rate` falls back to the suite's, and the suite's to
+    # DEFAULT_MIN_PASS_RATE; a group is gated unless it says `gated: false`.
+    # Layered documents override key by key at both levels, so a document
+    # that sets one group's bar leaves the suite's threshold and the other
+    # groups alone.
+    class PassThresholds
+      DEFAULT_MIN_PASS_RATE = 1.0
+      SUITE_KEYS = %w[threshold min_pass_rate].freeze
+      GROUP_KEYS = %w[min_pass_rate gated].freeze
+
+      # Layers each document's top-level `pass` and each group's `pass`
+      # (groups under `groups`, keyed by their `key`), later documents
+      # winning key by key. A group without a key has no scenarios to gate,
+      # so a `pass` block on one is refused.
+      #
+      # @param documents [Array<Hash>] parsed YAML documents, base first
+      def self.from_documents(documents)
+        suite = {}
+        groups = {}
+        Array(documents).each do |document|
+          document = document.to_h.deep_stringify_keys
+          suite.merge!(pass_block(document["pass"], "the suite"))
+          Array(document["groups"]).each do |group|
+            group = group.to_h.deep_stringify_keys
+            key = group["key"].to_s
+            raise ArgumentError, "\"pass\" of a group without a key gates nothing" if key.empty? && !group["pass"].nil?
+
+            groups[key] = groups.fetch(key, {}).merge(pass_block(group["pass"], "group #{key}"))
+          end
+        end
+        new(suite: suite, groups: groups)
+      end
+
+      def self.default
+        new
+      end
+
+      # A `pass` block as a string-keyed Hash; nothing declared reads as {},
+      # and anything but a mapping raises ArgumentError naming `place`.
+      def self.pass_block(value, place)
+        return {} if value.nil?
+        raise ArgumentError, "\"pass\" of #{place} must be a mapping, got #{value.inspect}" unless value.is_a?(Hash)
+
+        value.deep_stringify_keys
+      end
+
+      # `pass` as a string-keyed Hash of the `allowed` keys (SUITE_KEYS or
+      # GROUP_KEYS), each refusal naming `place` — the suite, a group, or
+      # whatever a caller holds a block for: a bar is a number from 0 to 1,
+      # kept as a Float so `1` and `1.0` read, serialize and hash the same,
+      # and `gated` is true or false.
+      def self.validate(pass, allowed, place)
+        pass_block(pass, place).to_h do |key, value|
+          raise ArgumentError, "unknown key #{key.inspect} in \"pass\" of #{place}; expected one of #{allowed.join(', ')}" unless allowed.include?(key)
+
+          if key == "gated"
+            raise ArgumentError, "\"gated\" in \"pass\" of #{place} must be true or false, got #{value.inspect}" unless [ true, false ].include?(value)
+
+            [ key, value ]
+          elsif value.is_a?(Numeric) && value.finite? && value.between?(0, 1)
+            [ key, value.to_f ]
+          else
+            raise ArgumentError, "#{key.inspect} in \"pass\" of #{place} must be a number from 0 to 1, got #{value.inspect}"
+          end
+        end
+      end
+
+      # @param suite [Hash] the suite's bars, `threshold` and `min_pass_rate`
+      # @param groups [Hash{String=>Hash}] each group's bars by group key,
+      #   `min_pass_rate` and `gated`
+      def initialize(suite: {}, groups: {})
+        @suite = self.class.validate(suite, SUITE_KEYS, "the suite")
+        @groups = groups.to_h.deep_stringify_keys.filter_map do |key, pass|
+          declared = self.class.validate(pass, GROUP_KEYS, "group #{key}")
+          [ key.to_s, declared ] if declared.any?
+        end.to_h
+      end
+
+      # The score every answer must reach, 0..1.
+      def threshold
+        (@suite["threshold"] || PASS_THRESHOLD).to_f
+      end
+
+      # The share of a model's answers that must pass, 0..1: the group's own
+      # bar when it declared one, else the suite's, else DEFAULT_MIN_PASS_RATE.
+      def min_pass_rate(group = nil)
+        own = @groups.dig(group.to_s, "min_pass_rate") unless group.nil?
+        (own || @suite["min_pass_rate"] || DEFAULT_MIN_PASS_RATE).to_f
+      end
+
+      # False only for a group that declared `gated: false`; nil and unknown
+      # groups are gated.
+      def gated?(group)
+        return true if group.nil?
+
+        @groups.dig(group.to_s, "gated") != false
+      end
+
+      # The bars in effect, with each group's declared keys only.
+      def to_h
+        {
+          "threshold" => threshold,
+          "min_pass_rate" => min_pass_rate,
+          "groups" => @groups.transform_values(&:dup)
+        }
+      end
+
+      def ==(other)
+        other.is_a?(PassThresholds) && to_h == other.to_h
+      end
+      alias eql? ==
+
+      def hash
+        to_h.hash
+      end
+    end
+  end
+end

data/lib/active_agent/evals/patterns.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module ActiveAgent
+  module Evals
+    # Regexes for a figure an answer is expected to state, built from the data
+    # the scenario was seeded with: a count ("3 of 4 tickets") or a share of
+    # a total ("75%"). Each is a String that drops into a suite's
+    # `expect.contains` / `not_contains` or a `contains` criterion, which
+    # Scorer.matches_pattern? tries as a substring and then as a regex:
+    #
+    #   "expect" => { "contains" => [ Patterns.number(3), Patterns.share(3, 4) ] }
+    module Patterns
+      MONTHS = %w[january february march april may june july august september october november december].freeze
+
+      # `text` as a pattern that matches it in any case, each letter a
+      # character class: any_case("Oct.") is "[Oo][Cc][Tt]\\.".
+      def self.any_case(text)
+        text.chars.map { |char| char.match?(/[a-z]/i) ? "[#{char.upcase}#{char.downcase}]" : Regexp.escape(char) }.join
+      end
+      private_class_method :any_case
+
+      # A day of the month written beside its month, in any case: "Oct 12",
+      # "Sept. 12" and "October 12" before the figure, "12 Oct" and "12th of
+      # October" after it. A lookbehind takes alternatives of one length only,
+      # so the spellings before the figure are one lookbehind per length, and
+      # each letter in it is a character class rather than `(?i:...)`: the
+      # dashes make the pattern UTF-8, where case folding lets "st" match the
+      # one-character ligature "st", and Ruby 3.2 refuses a lookbehind whose
+      # length that leaves open. "may" is left out after the figure, where it
+      # is usually the verb.
+      MONTH_BEFORE = MONTHS.flat_map { |month| [ month, month[0, 3], "#{month[0, 3]}." ] }.push("sept", "sept.").uniq
+        .group_by(&:length).sort.map { |_length, spellings| "(?<!#{spellings.map { |spelling| "\\b#{any_case("#{spelling} ")}" }.join('|')})" }
+        .join.freeze
+      MONTH_AFTER = (MONTHS - %w[may]).map { |month| "#{month[0, 3]}(?:#{Regexp.escape(month[3..])})?" }.push("sept").join("|").freeze
+
+      module_function
+
+      # The integer `count` as a figure on its own: number(10) matches
+      # "10 sessions", "(10)" and "10." at a sentence end, not "2026-10-01",
+      # "10/1", "10:00", "1-10" or "1–10", "110", "10.5", "10,000", "10%",
+      # "Oct 10" or "10 October". A ratio such as "10/22" does not match
+      # either, because "10/12" reads as a date as often as a count; expect
+      # "10 of 22". `count` is read as a whole number from its text, so 3 and
+      # "3" work and 1.5, 10.0, "a" or a negative count raise ArgumentError.
+      def number(count)
+        count = whole_number(count, "count")
+        "(?<![\\d/:.,\\-\u2013\u2014])#{MONTH_BEFORE}\\b#{count}\\b(?![/:\\-\u2013\u2014])(?![.,]\\d)(?! ?%)" \
+          "(?!(?i:(?:st|nd|rd|th)?,? (?:of )?(?:#{MONTH_AFTER})\\b))"
+      end
+
+      # `count` of `total` as a percentage, whole or to one or two decimals,
+      # with an optional space before the sign: share(3, 4) matches "75%",
+      # "75 %", "75.0%" and "75.00%", not "175%", "7.5%", "75.5%" or "0.75".
+      # The whole percent rounds half up like Format.whole and the decimals
+      # like Float#round, so share(1, 8) matches "13%", "12.5%" and "12.50%",
+      # and share(12, 22) matches "55%", "54.5%" and "54.55%". Both arguments are read like
+      # `number`'s; a total below one and a count above the total raise
+      # ArgumentError.
+      def share(count, total)
+        count = whole_number(count, "count")
+        total = whole_number(total, "total", minimum: 1)
+        raise ArgumentError, "count must not exceed total" if count > total
+
+        percent = count * 100.0 / total
+        decimals = [ 2, 1 ].map { |places| Regexp.escape(format("%.#{places}f", percent.round(places))) }
+        "(?<![\\d.,])\\b(?:#{decimals.join('|')}|#{Format.whole(percent)}) ?%"
+      end
+
+      # `value` as an Integer of at least `minimum`, read from its text so
+      # that 1.5 is rejected rather than truncated: 3 and "3" → 3; 1.5, "a"
+      # and a value below `minimum` raise ArgumentError.
+      def whole_number(value, name, minimum: 0)
+        number = Integer(value.to_s, 10)
+        raise ArgumentError, "#{name} must be #{minimum.positive? ? 'positive' : 'zero or positive'}" if number < minimum
+
+        number
+      end
+    end
+  end
+end