actionagent 1.2.2 → 1.5.0

data/app/models/action_agent/agent.rb

@@ -2,6 +2,8 @@
 
 module ActionAgent
   class Agent < ApplicationRecord
+    class ObservedAgentError < StandardError; end
+
     include Ownable
     owned_by :user, :account
 
@@ -72,7 +74,7 @@ module ActionAgent
 
     # Available tools/MCPs
     AVAILABLE_TOOLS = %w[
-      terminal playwright filesystem code database slack fetch search edit translate memory agents
+      terminal playwright filesystem code database slack fetch search edit translate memory agents ui
     ].freeze
 
     # Available providers
@@ -181,28 +183,34 @@ module ActionAgent
       agent_versions.count
     end
 
-    # Generate Ruby agent class code
+    # Generate Ruby agent class code.
+    #
+    # The class is named by telemetry_agent_class: it parameterizes a name
+    # with spaces ("My Agent" -> MyAgentAgent, not `class My AgentAgent`) and
+    # appends the Agent suffix only when it is missing, so an observed agent
+    # whose reported class already ends in Agent is not doubled. It is also
+    # the key traces are correlated on, so the exported class reports under
+    # the same name this record listens for.
     def to_agent_class_code
       <<~RUBY
-        class #{agent_class_name || name.camelize}Agent < ApplicationAgent
+        class #{telemetry_agent_class} < ApplicationAgent
           generate_with :#{provider}, model: "#{model}"#{model_config_code}
 
           def perform
-            prompt#{instructions_code}
+            #{instructions_code}
           end
         end
       RUBY
     end
 
-    # Execute a run with this agent
-    def execute(input_prompt, action: nil, **params)
-      run = agent_runs.create!(
-        input_prompt: input_prompt,
-        action_name: normalized_action(action),
-        input_params: params,
-        status: :pending,
-        trace_id: SecureRandom.uuid
-      )
+    # Execute a run with this agent. Files in +attachments+ (uploaded files,
+    # {io:, filename:, content_type:} hashes or blobs) are stored on the run
+    # before the job is enqueued, so a worker on another machine finds them
+    # attached. +params+ (provider/model overrides, the context_id of a
+    # conversation to continue) are kept on the run as input_params.
+    def execute(input_prompt, action: nil, attachments: [], **params)
+      ensure_executable!
+      run = create_run(input_prompt, action: action, attachments: attachments, params: params, status: :pending)
 
       # Queue the execution job
       AgentExecutionJob.perform_later(run.id)
@@ -211,14 +219,11 @@ module ActionAgent
     end
 
     # Quick test execution (synchronous)
-    def test_execute(input_prompt, action: nil, **params)
-      run = agent_runs.create!(
-        input_prompt: input_prompt,
-        action_name: normalized_action(action),
-        input_params: params,
-        status: :running,
-        trace_id: SecureRandom.uuid,
-        started_at: Time.current
+    def test_execute(input_prompt, action: nil, attachments: [], **params)
+      ensure_executable!
+      run = create_run(
+        input_prompt, action: action, attachments: attachments, params: params,
+        status: :running, started_at: Time.current
       )
 
       begin
@@ -247,8 +252,52 @@ module ActionAgent
       run
     end
 
+    # An observed agent was reconstructed from telemetry, so it is read-only:
+    # editing it would rewrite a record of what ran. Executing it is a
+    # different question — it carries the instructions, model and MCP servers a
+    # run needs, and evaluating the agent that actually served production is
+    # the case operators ask for. So a run is allowed once the agent names a
+    # server the dashboard can reach, and refused when it would have nothing to
+    # call.
+    def ensure_executable!
+      return unless observed?
+      return if MCPToolDispatcher.new(self).any_reachable_server?
+
+      raise ObservedAgentError,
+            "This agent was observed from telemetry and is read-only: it names no reachable MCP server — duplicate it to create an executable copy"
+    end
+
     private
 
+    # Refuses files before creating anything: a run that exists but lost
+    # its attachments would execute against the wrong prompt.
+    def create_run(input_prompt, action:, attachments:, params:, **attributes)
+      files = Array.wrap(attachments).compact
+      raise AgentRun::AttachmentsUnavailable if files.any? && !AgentRun.attachments_available?
+
+      run = agent_runs.create!(
+        input_prompt: input_prompt,
+        action_name: normalized_action(action),
+        input_params: params,
+        trace_id: SecureRandom.uuid,
+        **attributes
+      )
+
+      if files.any?
+        begin
+          run.attachments.attach(*files)
+        rescue StandardError
+          # An attach that raises (an unwritable service, a value that is not
+          # a file) happens after the row exists, and the caller never reaches
+          # the enqueue: without this the run would sit pending forever.
+          run.destroy
+          raise
+        end
+      end
+
+      run
+    end
+
     def slug_unique_within_owner
       return if slug.blank?
 
@@ -334,10 +383,12 @@ module ActionAgent
       ", #{configs}"
     end
 
+    # Exactly one prompt call: a bare `prompt` without instructions, or a
+    # single `prompt instructions:` heredoc with them.
     def instructions_code
-      return "" if instructions.blank?
+      return "prompt" if instructions.blank?
 
-      "\n    prompt instructions: <<~INSTRUCTIONS\n      #{instructions.gsub("\n", "\n      ")}\n    INSTRUCTIONS"
+      "prompt instructions: <<~INSTRUCTIONS\n      #{instructions.gsub("\n", "\n      ")}\n    INSTRUCTIONS"
     end
   end
 end

data/app/models/action_agent/agent_run.rb

@@ -4,6 +4,49 @@ module ActionAgent
   class AgentRun < ApplicationRecord
     belongs_to :agent
 
+    # Raised when a caller hands a run files to attach in a host app that
+    # has nowhere to keep them.
+    class AttachmentsUnavailable < StandardError
+      def initialize(message = "Attachments need Active Storage in the host app (run `rails active_storage:install`)")
+        super
+      end
+    end
+
+    # Files uploaded with the run. The execution service delivers them to
+    # the model (images and PDFs as data URIs, text inlined) and the
+    # persisted user message keeps a manifest of them.
+    #
+    # Guarded like RecordingSnapshot: a host app created with
+    # --skip-active-storage has no has_many_attached to call.
+    has_many_attached :attachments if defined?(ActiveStorage)
+
+    # Whether runs can carry files in this host app: Active Storage loaded,
+    # the macro applied, and its tables migrated. Never raises — a host
+    # that skipped `rails active_storage:install` still runs agents, it
+    # just can't attach files to them.
+    def self.attachments_available?
+      defined?(ActiveStorage) && method_defined?(:attachments) && ActiveStorage::Blob.table_exists?
+    rescue StandardError
+      false
+    end
+
+    # How an attachment reaches the model, by MIME type with a filename
+    # fallback for the text formats browsers upload as octet-stream:
+    # images and documents ride along as data URIs, text is inlined into
+    # the prompt, anything else is only described.
+    TEXT_CONTENT_TYPES = %w[application/json application/xml application/x-yaml application/csv].freeze
+    TEXT_EXTENSIONS = %w[.csv .md .txt .json .yml .yaml].freeze
+
+    def self.attachment_kind(content_type, filename = nil)
+      type = content_type.to_s.downcase
+      return "image" if type.start_with?("image/")
+      return "document" if type == "application/pdf"
+      return "text" if type.start_with?("text/") || TEXT_CONTENT_TYPES.include?(type)
+      return "text" if TEXT_EXTENSIONS.include?(File.extname(filename.to_s).downcase)
+
+      "file"
+    end
+
     # Status enum
     enum :status, { pending: 0, running: 1, complete: 2, failed: 3, cancelled: 4 }
 
@@ -103,6 +146,37 @@ module ActionAgent
       complete? || failed? || cancelled?
     end
 
+    # The conversation this run belongs to: the one it actually wrote to
+    # once it has executed (output_metadata), else the one the caller asked
+    # to continue. A pinned id the run declined — another agent's context,
+    # or another action's — must not be the id the API reports, or the
+    # runner would open a conversation the turn is not in.
+    def context_id
+      output_metadata&.dig("context_id") || input_params&.dig("context_id")
+    end
+
+    # The run's files as the runner and the persisted user message show
+    # them: one hash per attachment, with the kind the execution service
+    # sorted it into and a blob URL for thumbnails (nil when the host app
+    # didn't draw Active Storage's routes). Empty without Active Storage.
+    def attachment_manifest
+      return [] unless self.class.attachments_available?
+
+      attachment_records.map do |attachment|
+        blob = attachment.blob
+        {
+          "id" => attachment.id,
+          "blob_id" => blob.id,
+          "signed_id" => blob.signed_id,
+          "filename" => blob.filename.to_s,
+          "content_type" => blob.content_type,
+          "byte_size" => blob.byte_size,
+          "kind" => self.class.attachment_kind(blob.content_type, blob.filename.to_s),
+          "url" => blob_path(blob)
+        }
+      end
+    end
+
     # Get a summary for display
     def summary
       {
@@ -118,6 +192,8 @@ module ActionAgent
         instructions_digest: instructions_digest,
         instructions_codename: instructions_codename,
         instructions_preview: output_metadata&.dig("instructions")&.truncate(120),
+        attachments: attachment_manifest,
+        context_id: context_id,
         created_at: created_at,
         error: error_message
       }
@@ -147,5 +223,28 @@ module ActionAgent
     def set_trace_id
       self.trace_id ||= SecureRandom.uuid
     end
+
+    # Reads the association as loaded when a list preloaded it
+    # (with_attachments below), so serializing a page of runs costs two
+    # queries rather than two per run; a single run fetches its own.
+    def attachment_records
+      if attachments_attachments.loaded?
+        attachments_attachments.sort_by(&:id)
+      else
+        attachments_attachments.includes(:blob).order(:id).to_a
+      end
+    end
+
+    # Preloads attachments and blobs for a list of runs — a no-op scope in
+    # a host without Active Storage, so callers need no guard of their own.
+    def self.with_attachments
+      attachments_available? ? with_attached_attachments : all
+    end
+
+    def blob_path(blob)
+      Rails.application.routes.url_helpers.rails_blob_path(blob, only_path: true)
+    rescue StandardError
+      nil
+    end
   end
 end

data/app/models/action_agent/agent_template.rb

@@ -24,10 +24,14 @@ module ActionAgent
       automation
     ].freeze
 
-    # Create an agent from this template for a user
-    def create_agent_for(user, name: nil)
-      agent = user.agents.build(
-        name: name || self.name,
+    # Build (unsaved) an agent from this template inside +relation+: a host
+    # user's agents association, or the engine's owner scope
+    # (Api::BaseController#owner_agents). The relation decides the owner —
+    # including no owner at all in a single-user install, where the old
+    # `user.agents.build` had no user to call it on and raised.
+    def build_agent_in(relation, name: nil)
+      relation.build(
+        name: name.presence || self.name,
         description: description,
         provider: provider,
         model: model,
@@ -40,6 +44,12 @@ module ActionAgent
         model_config: model_config,
         status: :draft
       )
+    end
+
+    # Create an agent from this template for a host user with an `agents`
+    # association.
+    def create_agent_for(user, name: nil)
+      agent = build_agent_in(user.agents, name: name)
 
       if agent.save
         increment!(:usage_count)
@@ -158,12 +168,17 @@ module ActionAgent
           appearance: { hat: "fedora", hatAccessory: "theaterMasks", heldItem: "browser" },
           instruction_sets: [],
           tools: %w[playwright],
-          mcp_servers: {
-            playwright: {
+          # An array of server entries, which is the shape agents.mcp_servers
+          # takes everywhere else (the builder's strong params permit an
+          # array). The old top-level Hash was copied onto agents verbatim and
+          # crashed ToolDiscovery for the whole workspace.
+          mcp_servers: [
+            {
+              name: "playwright",
               command: "npx",
               args: [ "-y", "@anthropic/mcp-server-playwright" ]
             }
-          },
+          ],
           model_config: { temperature: 0.2, max_tokens: 4096 },
           instructions: "You are a browser automation assistant using Playwright MCP.\n\nAvailable actions:\n- browser_navigate: Go to a URL\n- browser_snapshot: Get the accessibility tree\n- browser_click: Click on an element\n- browser_type: Type text into an input\n- browser_take_screenshot: Capture the page\n- browser_wait_for: Wait for text or element\n\nGuidelines:\n1. Always take a snapshot first to understand the page\n2. Use element refs from snapshots for interactions\n3. Wait for page loads before taking actions\n4. Handle errors gracefully\n5. Limit yourself to 10 steps maximum\n\nAlways describe what you see and what actions you're taking.",
           icon: "🎭",

data/app/models/action_agent/evaluation.rb

@@ -13,6 +13,7 @@ module ActionAgent
   class Evaluation < ApplicationRecord
     belongs_to :agent
     has_many :evaluation_runs, dependent: :destroy
+    has_many :scenarios, class_name: "EvaluationScenario", dependent: :destroy
 
     # judge_defined: the judge model authors the KPI criteria itself from the
     # agent's instructions + sample interactions on the first run, then scores
@@ -47,8 +48,66 @@ module ActionAgent
       Array(config["compare_models"]).map(&:to_s).reject(&:blank?)
     end
 
-    def run!
-      EvaluationRunnerService.call(self)
+    # A scenario evaluation replays its own prompts rather than sampling the
+    # agent's recorded generations.
+    def scenario_suite?
+      scenarios.any?
+    end
+
+    def scenario_groups
+      # The index preloads scenarios for a page of evaluations; read the
+      # loaded association there rather than querying once per suite.
+      return scenarios.filter_map { |scenario| scenario.group.presence }.uniq.sort if scenarios.loaded?
+
+      scenarios.where.not(group: [ nil, "" ]).distinct.order(:group).pluck(:group)
+    end
+
+    # Runs the evaluation. `selection` narrows a scenario evaluation to some of
+    # its scenarios (`scenario_ids`, `keys`, `group`) and/or to specific
+    # `models`; it is ignored by a generation-sampling evaluation.
+    def run!(run: nil, **selection)
+      # A run created ahead of time (run_later!) is the scenario runner's even
+      # if the suite has since lost its scenarios: it fails that run with
+      # "No scenarios selected" rather than leaving it pending forever.
+      if run || scenario_suite?
+        ScenarioEvaluationRunner.call(self, selection: selection, run: run)
+      else
+        EvaluationRunnerService.call(self)
+      end
+    end
+
+    # Creates the run now and executes it in the background, so a suite of
+    # many scenarios under several models does not have to finish inside one
+    # request. Returns the pending EvaluationRun.
+    def run_later!(**selection)
+      run = evaluation_runs.create!(status: :pending, selection: selection.deep_stringify_keys)
+      EvaluationRunJob.perform_later(id, run.id, selection.deep_stringify_keys)
+      run
+    end
+
+    # Replaces the suite with the scenarios described by +attributes+ (the
+    # ActiveAgent::Evals::ScenarioParser output). Keys already in the suite keep their records, so
+    # earlier runs' results still resolve to their scenario, and keep their
+    # enabled flag unless the attributes set it (a paste cannot).
+    def replace_scenarios!(attributes)
+      transaction do
+        keep = attributes.map { |attrs| attrs["key"] }
+        scenarios.where.not(key: keep).destroy_all
+
+        attributes.each_with_index do |attrs, index|
+          scenario = scenarios.find_or_initialize_by(key: attrs["key"])
+          scenario.assign_attributes(
+            prompt: attrs["prompt"],
+            group: attrs["group"],
+            notes: attrs["notes"],
+            expectations: attrs["expectations"] || {},
+            position: attrs.fetch("position", index),
+            enabled: attrs.fetch("enabled") { scenario.new_record? || scenario.enabled }
+          )
+          scenario.save!
+        end
+      end
+      scenarios.reload
     end
 
     def llm_criteria
@@ -60,8 +119,9 @@ module ActionAgent
     def validate_criteria
       if criteria.blank?
         # judge_defined evaluations start empty — the judge authors the KPIs
-        # on the first run.
-        errors.add(:criteria, "must include at least one criterion") unless judge_defined?
+        # on the first run — and a scenario suite is scored by its scenarios'
+        # own expectations even with no criteria.
+        errors.add(:criteria, "must include at least one criterion") unless judge_defined? || scenarios.any?
         return
       end
 

data/app/models/action_agent/evaluation_run.rb

@@ -2,19 +2,207 @@
 
 module ActionAgent
   # One execution of an Evaluation over a sample of the agent's generations.
-  # scores: { criterion_key => { "score", "min", "max", "passed", "total" } }
+  # scores: { criterion_key => { "score", "min", "max", "passed", "total" } },
+  # except on a comparison run, where each criterion is a cohort map of
+  # model => stats and "_"-prefixed metadata keys sit alongside the criteria.
+  # See #average_score, which is what has to tolerate both shapes.
   class EvaluationRun < ApplicationRecord
     belongs_to :evaluation
+    has_many :scenario_results, class_name: "EvaluationScenarioResult", dependent: :destroy
 
     enum :status, { pending: 0, running: 1, complete: 2, failed: 3 }
 
     scope :recent, -> { order(created_at: :desc) }
 
+    # Which scenarios and models a scenario run covered; empty for a
+    # generation-sampling run.
+    def selection
+      value = super
+      value.is_a?(Hash) ? value : {}
+    end
+
+    # The candidate models a scenario run compared, in the order they were
+    # requested; empty for a generation-sampling run.
+    def models
+      Array(scores&.dig("_models")&.keys)
+    end
+
+    def report_metadata
+      value = scores&.dig("_metadata")
+      value.is_a?(Hash) ? value : {}
+    end
+
+    # The label ActiveAgent::Evals::Report gives a verdict it ranked by pass
+    # rate itself, for a comparison no judge was available to rule on. Read
+    # from the framework rather than restated: the report reads it back when
+    # it names the judge, so the two have to agree on the string.
+    PASS_RATE_JUDGE = ActiveAgent::Evals::Report::PASS_RATE_JUDGE
+
+    # The verdict a comparison run recorded — the judge's pick and rationale
+    # when a judge wrote it, the framework's pass-rate ranking otherwise —
+    # as `{ "winner", "rationale", "judge" }`; nil for a single-model or
+    # generation-sampling run.
+    def recorded_verdict
+      verdict = scores&.dig("_verdict")
+      verdict.to_h.stringify_keys.presence if verdict.is_a?(Hash)
+    end
+
+    # How the report names the judge, the way the suite panel does: the
+    # judge the recorded verdict names — unless that is only the pass-rate
+    # ranking — else the evaluation's judge model. nil when neither is set,
+    # which the report reads as "rules".
+    def judge_label
+      return scores["_judge_label"] if scores&.key?("_judge_label")
+
+      recorded = recorded_verdict&.dig("judge").to_s
+      return recorded if recorded.present? && recorded != PASS_RATE_JUDGE
+
+      evaluation.judge_model.presence
+    end
+
+    # scores is not uniformly { criterion => stats }: a comparison run also
+    # records "_"-prefixed metadata (EvaluationRunnerService writes
+    # "_missing_models" as an Array and "_verdict"), and each of its criteria
+    # is a cohort map of model => stats rather than a single stats hash.
+    # Only real criterion scores are averaged; anything else is ignored
+    # rather than raising and taking the whole Evaluations page down.
     def average_score
-      values = scores.values.map { |s| s["score"] }.compact
+      values = (scores || {}).reject { |key, _| key.to_s.start_with?("_") }.filter_map do |_key, value|
+        criterion_score(value) if value.is_a?(Hash)
+      end
       return nil if values.empty?
 
       (values.sum.to_f / values.size).round(3)
     end
+
+    # Aggregate usage over the run's scenario results, for display after a
+    # run: estimated cost, token totals, summed model time, and the run's
+    # wall-clock runtime. Returns nil for a generation-sampling run, which
+    # replays nothing itself.
+    def usage
+      totals = scenario_results.pick(
+        Arel.sql("COUNT(*)"), Arel.sql("SUM(cost)"), Arel.sql("SUM(input_tokens)"),
+        Arel.sql("SUM(output_tokens)"), Arel.sql("SUM(duration_ms)")
+      )
+      replays = totals&.first.to_i
+      return nil if replays.zero?
+
+      {
+        replays: replays,
+        cost: totals[1]&.to_f,
+        input_tokens: totals[2].to_i,
+        output_tokens: totals[3].to_i,
+        model_time_ms: totals[4].to_i,
+        runtime_ms: completed_at.present? ? ((completed_at - created_at) * 1000).round : nil
+      }
+    end
+
+    # Route templates for the report's fix item actions, relative to the
+    # dashboard mount: `%{key}` is filled in per MCP server by the report.
+    # The JSON API leaves `mount` empty — the React app resolves paths
+    # against the mount itself (dashboardPath) — while the standalone HTML
+    # report page is served outside the app and needs the absolute path.
+    def report_links(mount: "")
+      base = mount.to_s.chomp("/")
+
+      {
+        "mcp" => "#{base}/mcp/%{key}",
+        "tools" => "#{base}/tools",
+        "instructions" => "#{base}/agents/#{evaluation.agent_id}/edit"
+      }
+    end
+
+    # What to fix, from the framework's Report: one item per fault plus one
+    # per instruction change the judge proposed, each naming the tools
+    # involved, the MCP server that serves them and whether this run's
+    # agent has it enabled (EvaluationToolResolver), and the dashboard
+    # action that addresses it. Empty for a generation-sampling run.
+    def fix_items(links: report_links)
+      to_report(links: links).fix_items
+    end
+
+    # Rebuilds the framework's Report from this run's persisted results, so
+    # the dashboard serves the same self-contained report page a CLI run
+    # writes with Report#to_html. The run's recorded verdict and judge go
+    # with it: the report is not to re-rank the rebuilt results by pass
+    # rate and show a different judge's pick, verdict or `judged by` than
+    # the suite panel does. Raises ActiveRecord::RecordNotFound via the
+    # caller for a run of a generation-sampling evaluation, which has no
+    # scenario results to report on.
+    def to_report(links: report_links)
+      rows = scenario_results.includes(:scenario).sort_by do |row|
+        [ row.evaluated_scenario["position"].to_i, row.evaluation_scenario_id, row.model ]
+      end
+      selected = selected_specs
+      specs = {}
+      results = rows.map do |row|
+        spec = specs[[ row.provider.to_s, row.model ]] ||= selected[[ row.provider.to_s, row.model ]] || ModelSpec.new(
+          label: [ row.provider.presence, row.model ].compact.join("/"), provider: row.provider.to_s, model: row.model
+        )
+        ActiveAgent::Evals::Result.new(
+          scenario: ActiveAgent::Evals::Scenario.from_hash(row.evaluated_scenario),
+          spec: spec,
+          replay: ActiveAgent::Evals::Replay.new(
+            answer: row.output, tool_calls: Array(row.tool_calls), duration_ms: row.duration_ms,
+            input_tokens: row.input_tokens, output_tokens: row.output_tokens,
+            cost: row.cost&.to_f, error: row.error_message, metadata: row.replay_metadata
+          ),
+          scores: row.scores.to_h, score: row.score, status: row.status,
+          diagnosis: row.evaluation_diagnosis.presence
+        )
+      end
+
+      ActiveAgent::Evals::Report.new(
+        results: results,
+        models: (selected.values & specs.values) + (specs.values - selected.values),
+        metadata: {
+          "evaluation" => evaluation.name,
+          "agent" => evaluation.agent&.name,
+          "run" => id,
+          "finished" => completed_at&.iso8601
+        }.compact.merge(report_metadata),
+        verdict: recorded_verdict,
+        judge_label: judge_label,
+        tool_resolver: EvaluationToolResolver.new(evaluation.agent),
+        agent_name: evaluation.agent&.name,
+        links: links
+      )
+    end
+
+    private
+
+    ModelSpec = ActiveAgent::Evals::ModelSpec
+    private_constant :ModelSpec
+
+    # The candidate specs the run was asked to compare, keyed by
+    # [provider, model] in the order requested. ScenarioEvaluationRunner
+    # persists each ModelSpec#to_h in `selection`, and it is that label —
+    # the string the user typed, e.g. "gpt-5-mini" — that keys the run's
+    # `_models` and names the verdict's winner, so the rebuilt report has
+    # to reuse it rather than relabel every model provider/model.
+    def selected_specs
+      Array(selection["models"]).filter_map do |entry|
+        next unless entry.is_a?(Hash)
+
+        entry = entry.stringify_keys
+        next if entry["model"].blank?
+
+        ModelSpec.new(label: entry["label"].presence || entry["model"], provider: entry["provider"].to_s, model: entry["model"])
+      end.index_by { |spec| [ spec.provider, spec.model ] }
+    end
+
+    # A criterion is either scored directly ({ "score" => 0.8, ... }) or, on a
+    # comparison run, a map of model => stats; that cohort's mean is the
+    # criterion's headline score. Skipped criteria carry no score at all.
+    def criterion_score(value)
+      return value["score"] if value["score"].is_a?(Numeric)
+
+      cohort = value.each_value.filter_map do |stats|
+        stats["score"] if stats.is_a?(Hash) && stats["score"].is_a?(Numeric)
+      end
+      return nil if cohort.empty?
+
+      cohort.sum.to_f / cohort.size
+    end
   end
 end