plai_testr 0.1.1

data/lib/plai_testr/agents/player_agent.rb

@@ -0,0 +1,216 @@
+module PlaiTestr
+  module Agents
+    class PlayerAgent
+      MAX_PARSE_RETRIES = 2
+
+      def initialize(name:, model:, client:, game_name:, settings: PlaiTestr.config.model_settings, think: false)
+        @name      = name
+        @model     = model
+        @client    = client
+        @game_name = game_name
+        @settings  = settings
+        @think     = think
+      end
+
+      # Response contract for menu turns. Ollama enforces this schema via `format`.
+      MENU_SCHEMA = {
+        'type'       => 'object',
+        'properties' => {
+          'choice'      => { 'type' => 'integer' },
+          'reasoning'   => { 'type' => 'string' },
+          'plan'        => { 'type' => 'string' }
+        },
+        'required' => %w[choice reasoning plan]
+      }.freeze
+
+      PICK_SCHEMA = {
+        'type'       => 'object',
+        'properties' => {
+          'choices'   => { 'type' => 'array', 'items' => { 'type' => 'integer' } },
+          'reasoning' => { 'type' => 'string' },
+          'plan'      => { 'type' => 'string' }
+        },
+        'required' => %w[choices reasoning plan]
+      }.freeze
+
+      # Menu turn: the game supplies the rules text, a human-readable view, and a numbered list
+      # of legal moves; the model only has to return the number of one of them.
+      #
+      # Returns { 'choice' => Integer (1-based, always valid), 'reasoning', 'plan',
+      #           'attempts' => Integer, 'fallback' => Boolean }.
+      # Invalid or out-of-range replies are re-prompted; after MAX_PARSE_RETRIES 'choice' is nil
+      # and 'fallback' is true, and the runner picks the move instead.
+      def choose(rules_text:, view_text:, labels:, plan: nil, recent: [], prompt_note: nil, persona: nil, think: true)
+        messages = menu_messages(rules_text:, view_text:, labels:, plan:, recent:, prompt_note:, persona:)
+
+        ask(messages, MENU_SCHEMA, think, plan) do |parsed|
+          choice = parsed['choice'].to_s =~ /\A\d+\z/ ? parsed['choice'].to_i : nil
+          next { 'choice' => choice } if choice&.between?(1, labels.length)
+
+          "That was not a valid choice. Reply with JSON whose \"choice\" is a number from 1 to #{labels.length}."
+        end
+      end
+
+      def choose_many(rules_text:, view_text:, labels:, min:, max:, plan: nil, recent: [], prompt_note: nil, persona: nil, think: true)
+        rule     = min == max ? "exactly #{min}" : "between #{min} and #{max}"
+        note     = [prompt_note, "Choose #{rule} different options. Reply with JSON: {\"choices\": [<numbers>], \"reasoning\": \"...\", \"plan\": \"...\"}"].compact.join("\n")
+        messages = menu_messages(rules_text:, view_text:, labels:, plan:, recent:, prompt_note: note, persona:)
+
+        ask(messages, PICK_SCHEMA, think, plan) do |parsed|
+          choices = Array(parsed['choices']).map { |c| Integer(c, exception: false) }
+          valid   = choices.none?(&:nil?) && choices.uniq.length == choices.length &&
+                    choices.length.between?(min, max) && choices.all? { |c| c.between?(1, labels.length) }
+          next { 'choices' => choices } if valid
+
+          "That was not valid. \"choices\" must list #{rule} different numbers from 1 to #{labels.length}."
+        end
+      end
+
+      def prompt_tokens(**prompt)
+        @client.chat(model: @model, messages: menu_messages(**prompt), **chat_options(true).merge(num_predict: 1))['prompt_eval_count'].to_i
+      end
+
+      def context_size = @think ? @settings[:long_context_size] : @settings[:context_size]
+
+      # Asked once per player after the game, instead of collecting design notes every turn
+      # (per-turn notes were either filler or, from larger models, always empty).
+      #
+      # Returns [{ 'question' => String, 'answer' => String }] in question order. A missing or
+      # unparseable answer becomes an empty string; the debrief never raises on bad output.
+      def debrief(rules_text:, view_text:, questions:, persona: nil)
+        keys     = questions.each_index.map { |i| "q#{i + 1}" }
+        schema   = { 'type' => 'object', 'properties' => keys.to_h { |k| [k, { 'type' => 'string' }] }, 'required' => keys }
+        messages = [
+          { role: 'system', content: debrief_system_prompt(rules_text, persona) },
+          { role: 'user',   content: debrief_prompt(view_text, questions, keys) }
+        ]
+        options  = { temperature: @settings[:temperature], think: false, num_ctx: @settings[:long_context_size], num_predict: @settings[:debrief_budget] }
+
+        parsed = {}
+        (MAX_PARSE_RETRIES + 1).times do
+          response = @client.chat(model: @model, messages: messages, format: schema, **options)
+          parsed   = parse_menu_response(response.dig('message', 'content').to_s)
+          break if parsed.is_a?(Hash) && keys.any? { |k| !parsed[k].to_s.strip.empty? }
+        end
+        parsed = {} unless parsed.is_a?(Hash)
+
+        questions.zip(keys).map { |q, k| { 'question' => q, 'answer' => parsed[k].to_s.strip } }
+      end
+
+      def menu_messages(rules_text:, view_text:, labels:, plan: nil, recent: [], prompt_note: nil, persona: nil)
+        [
+          { role: 'system', content: menu_system_prompt(rules_text, persona) },
+          { role: 'user',   content: menu_turn_prompt(view_text, labels, plan, recent, prompt_note) }
+        ]
+      end
+
+      private
+
+      def ask(messages, schema, think, plan)
+        context_full = false
+
+        (MAX_PARSE_RETRIES + 1).times do |i|
+          response     = @client.chat(model: @model, messages: messages, format: schema, **chat_options(think))
+          context_full ||= response['context_full'] == true
+          content      = response.dig('message', 'content').to_s
+          parsed       = parse_menu_response(content)
+          verdict      = parsed.is_a?(Hash) ? yield(parsed) : 'That was not valid JSON. Reply with JSON only.'
+          return parsed.slice('reasoning', 'plan').merge(verdict, 'attempts' => i + 1, 'fallback' => false, 'context_full' => context_full) if verdict.is_a?(Hash)
+
+          messages += [
+            { role: 'assistant', content: content[0, 300] },
+            { role: 'user',      content: verdict }
+          ]
+        end
+
+        { 'choice' => nil, 'choices' => nil, 'reasoning' => nil, 'plan' => plan,
+          'attempts' => MAX_PARSE_RETRIES + 1, 'fallback' => true, 'context_full' => context_full }
+      end
+
+      def chat_options(think)
+        base = { temperature: @settings[:temperature], num_ctx: context_size }
+        return base.merge(think: false, num_predict: @settings[:menu_budget]) unless @think && think
+
+        base.merge(think: true, num_predict: @settings[:think_budget])
+      end
+
+      def debrief_system_prompt(rules_text, persona)
+        <<~PROMPT
+          You are #{@name}. You just finished a playtest of the tabletop game #{@game_name}.
+          Now you are a playtester giving the game designer honest feedback.
+
+          #{rules_text}
+          #{"\nTHE STRATEGY YOU PLAYED: #{persona}\n" if persona}
+
+          HOW TO ANSWER:
+          - Be specific: name actual components, rules, and decisions from your game.
+          - Stick to the facts under YOUR FINAL POSITION. Describe a card by the text given there, not from memory,
+            and check the log before saying something did or did not happen.
+          - 1-3 sentences per answer. Criticism is welcome; the designer wants to find problems.
+          - If nothing applies, answer "nothing" rather than inventing a problem.
+
+          Reply with JSON only.
+        PROMPT
+      end
+
+      def debrief_prompt(view_text, questions, keys)
+        list = questions.zip(keys).map { |q, k| "#{k}: #{q}" }.join("\n")
+
+        <<~PROMPT
+          YOUR FINAL POSITION:
+          #{view_text}
+
+          QUESTIONS:
+          #{list}
+
+          Reply with JSON only: {#{keys.map { |k| "\"#{k}\": \"<answer>\"" }.join(', ')}}
+        PROMPT
+      end
+
+      def menu_system_prompt(rules_text, persona)
+        <<~PROMPT
+          You are #{@name}, a player in a playtest of the tabletop game #{@game_name}. Play to win.
+
+          #{rules_text}
+          #{"\nYOUR STRATEGY (follow it in every decision): #{persona}\n" if persona}
+
+          HOW TO PLAY EACH TURN:
+          - You get YOUR VIEW (only what you are allowed to know) and a numbered list of LEGAL MOVES.
+          - Choose ONLY a number from LEGAL MOVES. Never invent cards or moves.
+          - Do not assume anything about hidden cards beyond what YOUR VIEW says.
+          - Keep a one-line plan and update it; your previous plan is shown to you.
+          - RECENT EVENTS lines starting with BOT: or RNG: were moves made for you automatically, not by you.
+
+          Reply with JSON only: {"choice": <number>, "reasoning": "<1-3 sentences>", "plan": "<one line>"}
+        PROMPT
+      end
+
+      def menu_turn_prompt(view_text, labels, plan, recent, prompt_note)
+        moves = labels.each_with_index.map { |label, i| "#{i + 1}. #{label}" }.join("\n")
+
+        <<~PROMPT
+          YOUR VIEW:
+          #{view_text}
+
+          RECENT EVENTS:
+          #{recent.empty? ? '(none yet)' : recent.map { |r| "- #{r}" }.join("\n")}
+
+          YOUR PLAN SO FAR: #{plan.to_s.empty? ? '(none yet)' : plan}
+          #{"\nNOTE: #{prompt_note}\n" if prompt_note}
+          LEGAL MOVES:
+          #{moves}
+
+          Reply with JSON only.
+        PROMPT
+      end
+
+      def parse_menu_response(content)
+        cleaned = content.gsub(/<think>.*?<\/think>/m, '').strip
+        json    = cleaned[/\{.*\}/m]
+        json && JSON.parse(json)
+      rescue JSON::ParserError
+        nil
+      end
+    end
+  end
+end

data/lib/plai_testr/agents/referee_agent.rb

@@ -0,0 +1,56 @@
+module PlaiTestr
+  module Agents
+    class RefereeAgent
+      MAX_PARSE_RETRIES = 2
+      TEMPERATURE       = 0.1
+
+      RULING_SCHEMA = {
+        'type'       => 'object',
+        'properties' => {
+          'met' => { 'type' => 'boolean' },
+          'why' => { 'type' => 'string' }
+        },
+        'required' => %w[met why]
+      }.freeze
+
+      def initialize(model:, client:, game_name:, settings: PlaiTestr.config.model_settings)
+        @model     = model
+        @client    = client
+        @game_name = game_name
+        @options   = { temperature: TEMPERATURE, think: true, num_ctx: settings[:context_size], num_predict: settings[:referee_budget] }
+      end
+
+      def ruling(question:, facts:)
+        messages = [
+          { role: 'system', content: system_prompt },
+          { role: 'user',   content: "QUESTION: #{question}\n\nFACTS:\n#{facts}\n\nReply with JSON only: {\"met\": true|false, \"why\": \"<1 sentence>\"}" }
+        ]
+
+        (MAX_PARSE_RETRIES + 1).times do
+          response = @client.chat(model: @model, messages: messages, format: RULING_SCHEMA, **@options)
+          parsed   = parse(response.dig('message', 'content').to_s)
+          return { 'met' => parsed['met'], 'why' => parsed['why'].to_s, 'fallback' => false } if parsed && [true, false].include?(parsed['met'])
+        end
+
+        { 'met' => false, 'why' => 'fallback: no valid ruling after retries', 'fallback' => true }
+      end
+
+      private
+
+      def system_prompt
+        <<~PROMPT
+          You are the rules referee for #{@game_name}.
+          You answer ONE yes/no question about whether a rule or card condition is met.
+          Use only the FACTS given. Do not assume anything that is not stated.
+        PROMPT
+      end
+
+      def parse(content)
+        json = content.gsub(/<think>.*?<\/think>/m, '')[/\{.*\}/m]
+        json && JSON.parse(json)
+      rescue JSON::ParserError
+        nil
+      end
+    end
+  end
+end

data/lib/plai_testr/botrun.rb

@@ -0,0 +1,60 @@
+module PlaiTestr
+  class Botrun
+    attr_reader :planned
+
+    def initialize(game:, players:, seeds:, personas: nil, out: nil)
+      @game     = game
+      @players  = players
+      @seeds    = seeds
+      @personas = personas
+      @out      = out
+      @planned  = seeds.length
+    end
+
+    def run
+      catalog = @game.personas
+      catalog.check_request(@personas, players: @players.length, all: true)
+      pairings = all_pairings? ? catalog.pairings(@players.length) : []
+      raise PersonaError, "--personas all needs at least #{@players.length} personas to pair up" if all_pairings? && pairings.empty?
+
+      results = []
+      with_signal_traps do
+        @seeds.each_with_index do |seed, i|
+          break if @stopping
+
+          results << play(seed, all_pairings? ? pairings[i % pairings.length] : @personas)
+          yield results.length if block_given?
+        end
+      end
+      results
+    end
+
+    def stopped_early? = @stopping == true
+
+    private
+
+    def all_pairings? = @personas == [Personas::ALL]
+
+    def play(seed, personas)
+      game = @game.runner_class.new(game: @game, players: @players, seed: seed, personas: personas, mode: 'bot', persist: false,
+                                    out: @out || StringIO.new, echo_warnings: false)
+      game.play_out
+      game.botrun_result
+    rescue StandardError => e
+      { 'seed' => seed, 'personas_requested' => personas, 'error' => "#{e.class}: #{e.message}" }
+    end
+
+    def with_signal_traps
+      previous = %w[INT TERM].to_h do |signal|
+        [signal, trap(signal) do
+          exit!(130) if @stopping
+          @stopping = true
+          $stderr.puts "\n\nInterrupted — finishing this game, then reporting. Press Ctrl+C again to quit immediately."
+        end]
+      end
+      yield
+    ensure
+      previous&.each { |signal, handler| trap(signal, handler || 'DEFAULT') }
+    end
+  end
+end

data/lib/plai_testr/cli.rb

@@ -0,0 +1,190 @@
+module PlaiTestr
+  class CLI
+    COMMANDS       = %w[play botrun resume preflight compare list].freeze
+    GAME_COMMANDS  = %w[play botrun resume preflight].freeze
+    PROGRESS_EVERY = 50
+
+    def self.start(argv)
+      $stdout.sync = true
+      PlaiTestr.load_config
+
+      case argv
+      in ['new', dir]
+        Generator.new.app(dir)
+        puts "\nNext:\n  cd #{dir}\n  bundle install\n  bundle exec plai_testr hearts botrun --games 100\n  bundle exec plai_testr hearts play"
+      in ['generate', 'game', name]
+        Generator.new.game(name)
+        puts "\nNext: describe the game in games/#{name}/data/, implement games/#{name}/lib/#{name}/session/runner.rb, then run bundle exec rspec games/#{name}"
+      in [String => name, *rest] unless name.start_with?('-')
+        new(PlaiTestr.load(name)).run(rest)
+      else
+        abort <<~USAGE
+          Usage:
+            #{File.basename($PROGRAM_NAME)} new <directory>              Create a playtesting app with example games
+            #{File.basename($PROGRAM_NAME)} generate game <name>         Add a game skeleton under games/<name>
+            #{File.basename($PROGRAM_NAME)} <game> <command> [options]   Play a game (games: #{PlaiTestr.names.join(', ')})
+        USAGE
+      end
+    rescue Error => e
+      raise if e.is_a?(MoveError) || ENV['PLAI_TESTR_DEBUG']
+
+      abort e.message
+    end
+
+    def initialize(game)
+      @game    = game
+      @options = {
+        player:    PlaiTestr.config.player_model,
+        referee:   PlaiTestr.config.referee_model,
+        think:     false,
+        mode:      'llm',
+        games:     100,
+        seeds:     [],
+        preflight: true
+      }
+
+      PlaiTestr.sessions_dir = game.sessions_dir
+      PlaiTestr.reports_dir  = game.reports_dir
+    end
+
+    def run(argv)
+      args    = parser.parse(argv)
+      command = args.first
+      return puts(parser.help) unless COMMANDS.include?(command)
+
+      @game.check!.each { |note| warn "  [warning] #{note}" } if GAME_COMMANDS.include?(command)
+
+      case command
+      when 'play'      then play
+      when 'botrun'    then botrun
+      when 'resume'    then resume(args[1])
+      when 'preflight' then Preflight.new(game: @game, players: seats, models: models, personas: @options[:personas]).run(@options[:seed] || 1)
+      when 'compare'   then compare
+      when 'list'      then list
+      end
+    rescue OptionParser::ParseError => e
+      raise UsageError, e.message
+    end
+
+    private
+
+    def models = { player: @options[:player], referee: @options[:referee], think: @options[:think] }
+
+    def parser
+      @parser ||= OptionParser.new do |o|
+        o.banner = <<~USAGE
+          #{@game.name}: automated playtesting
+
+          Commands:
+            play    [--seed N] [--model M] [--think] [--mode M] [--players N] [--personas A,B] [--referee M]   Play one game
+            botrun  [--games N | --seeds 1,2,3] [--players N] [--personas all|A,B]   Play many games with bot rules only (no model), then report
+            resume  <session_id>                    Resume an interrupted session
+            preflight                               Check Ollama, pull and warm up the models, measure the prompt, lint with bot games
+            compare [--since ID]                    Compare completed games by model and host
+            list                                    List sessions
+
+          Options:
+        USAGE
+        o.on('--seed N', Integer, 'play: seed for shuffles and dice (default: random 1-100, printed)') { |v| @options[:seed] = v }
+        o.on('--seeds LIST', Array, 'botrun: comma-separated seeds') { |v| @options[:seeds] = v.map { |s| Integer(s) } }
+        o.on('--games N', Integer, 'botrun: number of games, seeds 1..N (default 100)') { |v| @options[:games] = v }
+        o.on('--model M', "Ollama model for the players (default #{PlaiTestr.config.player_model})") { |v| @options[:player] = v }
+        o.on('--mode M', Session::Runner::MODES, 'llm (default): the model decides; hybrid: bot rules play obvious moves; bot: no model') { |v| @options[:mode] = v }
+        o.on('--think', 'Let the player model think before each choice (slower; stronger play)') { @options[:think] = true }
+        o.on('--referee M', 'Ollama model for yes/no rulings (only for games that ask for them)') { |v| @options[:referee] = v }
+        o.on('--players N', Integer, 'Number of players, within the game\'s player_count (default: the game\'s default)') { |v| @options[:player_count] = v }
+        o.on('--personas LIST', Array, 'One persona per player, comma-separated, * for random (default: random); botrun also takes "all"') { |v| @options[:personas] = v }
+        o.on('--skip-preflight', 'Skip the Ollama checks and the lint games') { @options[:preflight] = false }
+        o.on('--since ID', 'compare: only sessions whose id sorts at or after ID (e.g. 20261011-170000)') { |v| @options[:since] = v }
+        o.on('--quiet', 'Show only a progress line and the result') { @options[:quiet] = true }
+        o.on('--verbose', 'Also show the raw model output and timings (play), or every game (botrun)') { @options[:verbose] = true }
+      end
+    end
+
+    def seats
+      range = @game.rules.dig('game', 'player_count')
+      count = @options[:player_count] || range&.dig('default')
+      return @game.players unless count
+      raise UsageError, "#{@game.name}: #{count} players is outside #{range['min']}-#{range['max']}" if range && !count.between?(range['min'], range['max'])
+
+      Array.new(count) { |i| "Player #{i + 1}" }
+    end
+
+    def preflight? = @options[:preflight] && @options[:mode] != 'bot'
+
+    def output = @options[:quiet] ? StringIO.new : $stdout
+
+    def play
+      seed    = @options[:seed] || rand(1..100)
+      players = seats
+      @game.personas.check_request(@options[:personas], players: players.length)
+      Preflight.new(game: @game, players: players, models: models, personas: @options[:personas], out: output).run(seed) if preflight?
+
+      runner = @game.runner_class.new(game: @game, players: players, models: models, seed: seed, mode: @options[:mode],
+                                      personas: @options[:personas], out: output, verbose: @options[:verbose])
+      play_session(runner)
+    end
+
+    def resume(session_id)
+      raise UsageError, "Usage: plai_testr #{@game.name} resume <session_id>" unless session_id
+
+      runner = @game.runner_class.resume(@game, session_id, out: output, verbose: @options[:verbose])
+      session_models = { player: runner.data['player_model'], referee: runner.data['referee_model'] }
+      Preflight.new(game: @game, players: runner.game_state.players, models: session_models, out: output).ollama! if @options[:preflight] && runner.data['mode'] != 'bot'
+      play_session(runner)
+    end
+
+    def play_session(runner)
+      started = clock
+      runner.run { |decisions| progress("decision #{decisions} · #{duration(clock - started)}", decisions) if @options[:quiet] }
+      if @options[:quiet]
+        puts
+        puts runner.status == 'completed' ? "Game complete (seed #{runner.seed}). Report: #{runner.report_path}" : "Saved. Resume with: plai_testr #{@game.name} resume #{runner.session_id}"
+      end
+      exit 130 if runner.status == 'interrupted'
+    end
+
+    def botrun
+      seeds   = @options[:seeds].empty? ? (1..@options[:games]).to_a : @options[:seeds]
+      started = clock
+      botrun  = Botrun.new(game: @game, players: seats, seeds: seeds, personas: @options[:personas], out: (@options[:verbose] ? $stdout : nil))
+      results = botrun.run { |done| progress("#{done}/#{seeds.length} games", done) }
+      rules   = @game.rules
+
+      markdown = @game.botrun_report_class.new(results, game: rules.dig('game', 'name'), version: rules.dig('game', 'version'),
+                                                        seconds: clock - started, personas: @options[:personas], planned: seeds.length).to_markdown
+      FileUtils.mkdir_p(PlaiTestr.reports_dir)
+      path = File.join(PlaiTestr.reports_dir, "botrun-#{Time.now.strftime('%Y%m%d-%H%M%S')}.md")
+      File.write(path, markdown)
+      puts @options[:quiet] ? "\nReport: #{path}" : "\n\n#{markdown}\nSaved: #{path}"
+    end
+
+    def compare
+      markdown = @game.comparison_class.new(PlaiTestr.sessions_dir, since: @options[:since]).to_markdown
+      FileUtils.mkdir_p(PlaiTestr.reports_dir)
+      path = File.join(PlaiTestr.reports_dir, "comparison-#{Time.now.strftime('%Y%m%d-%H%M%S')}.md")
+      File.write(path, markdown)
+      puts markdown, "\nSaved: #{path}"
+    end
+
+    def list
+      sessions = Session::Manager.list
+      return puts 'No sessions found.' if sessions.empty?
+
+      puts format('%-24s  %-12s  %s', 'SESSION_ID', 'STATUS', 'SAVED_AT')
+      sessions.each { |s| puts format('%-24s  %-12s  %s', *s.values_at('session_id', 'status', 'saved_at')) }
+    end
+
+    def progress(text, count)
+      if $stdout.tty?
+        print "\r  #{text}\e[K"
+      elsif (count % PROGRESS_EVERY).zero?
+        puts "  #{text}"
+      end
+    end
+
+    def clock = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+    def duration(seconds) = format('%dm %02ds', seconds / 60, seconds % 60)
+  end
+end

data/lib/plai_testr/config.rb

@@ -0,0 +1,39 @@
+module PlaiTestr
+  class Config
+    MODEL_SETTINGS = {
+      context_size:      8192,
+      long_context_size: 16_384,
+      menu_budget:       512,
+      think_budget:      8192,
+      debrief_budget:    1024,
+      referee_budget:    2048,
+      temperature:       0.6
+    }.freeze
+
+    attr_accessor :max_decisions, :ollama_host, :ollama_port, :player_model, :referee_model
+    attr_reader :model_settings
+
+    def initialize
+      @max_decisions  = 100_000
+      @ollama_host    = ENV.fetch('PLAI_TESTR_OLLAMA_HOST', 'localhost')
+      @ollama_port    = Integer(ENV.fetch('PLAI_TESTR_OLLAMA_PORT', '11434'))
+      @player_model   = ENV.fetch('PLAI_TESTR_PLAYER_MODEL', 'qwen3:8b')
+      @referee_model  = ENV['PLAI_TESTR_REFEREE_MODEL']
+      @model_settings = MODEL_SETTINGS.dup
+    end
+
+    def model_settings=(settings)
+      @model_settings = MODEL_SETTINGS.merge(settings)
+    end
+  end
+
+  def self.config = @config ||= Config.new
+
+  def self.configure = yield(config)
+
+  def self.reset_config! = @config = nil
+
+  def self.load_config(path = File.join(Dir.pwd, 'config', 'plai_testr.rb'))
+    Kernel.load(path) if File.exist?(path)
+  end
+end

data/lib/plai_testr/deck.rb

@@ -0,0 +1,11 @@
+module PlaiTestr
+  module Deck
+    def self.build(rules, component: nil)
+      deck = rules.fetch('components', []).find { |c| c['type'] == 'card_deck' && (component.nil? || c['name'] == component) }
+      return [] unless deck
+
+      deck.fetch('values', []).flat_map { |card| Array.new(card.fetch('copies', 1)) { card.except('copies') } }
+          .each.with_index(1).map { |card, uid| card.merge('uid' => uid) }
+    end
+  end
+end

data/lib/plai_testr/errors.rb

@@ -0,0 +1,9 @@
+module PlaiTestr
+  class Error < StandardError; end
+  class RulesError < Error; end
+  class PersonaError < Error; end
+  class SessionError < Error; end
+  class ModelError < Error; end
+  class UsageError < Error; end
+  class MoveError < Error; end
+end

data/lib/plai_testr/event_log.rb

@@ -0,0 +1,24 @@
+module PlaiTestr
+  class EventLog
+    def initialize(entries)
+      @entries = entries
+    end
+
+    def add(text, turn:, to: nil, actor: nil, tag: nil)
+      entry = { 'turn' => turn, 'text' => text, 'to' => to }
+      entry.merge!('actor' => actor, 'tag' => tag) if tag
+      @entries << entry
+    end
+
+    def visible_to(player)
+      @entries.select { |e| e['to'].nil? || e['to'] == player }
+    end
+
+    def recent_for(player, count)
+      visible_to(player).last(count).map do |e|
+        text = e['to'] ? "(private) #{e['text']}" : e['text']
+        e['tag'] && e['actor'] == player ? "#{e['tag']}: #{text}" : text
+      end
+    end
+  end
+end

data/lib/plai_testr/game.rb

@@ -0,0 +1,50 @@
+module PlaiTestr
+  Game = Data.define(:name, :runner_class, :game_state_class, :players, :comparison_class, :botrun_report_class, :max_decisions, :model_settings) do
+    def root         = File.join(PlaiTestr.games_dir, name)
+    def data_dir     = File.join(root, 'data')
+    def rules_file   = File.join(data_dir, 'rules.json')
+    def sessions_dir = File.join(root, 'sessions')
+    def reports_dir  = File.join(root, 'reports')
+    def rules        = RulesLoader.load(rules_file)
+    def personas     = Personas.load(data_dir)
+
+    def check!
+      Dir.glob('**/*.{yml,yaml}', base: data_dir).each do |file|
+        YAML.safe_load_file(File.join(data_dir, file), aliases: true)
+      rescue Psych::SyntaxError => e
+        raise RulesError, "#{File.join(data_dir, file)}: #{e.message}"
+      end
+      rules
+      personas.lint
+    end
+
+    def fingerprint
+      files = %w[data lib].flat_map { |dir| Dir.glob(File.join(root, dir, '**', '*')) }.select { |path| File.file?(path) }.sort
+      digest = Digest::SHA256.new
+      digest << VERSION
+      files.each { |path| digest << path.delete_prefix(root) << File.binread(path) }
+      digest.hexdigest
+    end
+  end
+
+  def self.register(name, runner_class:, game_state_class:, players: ['Player 1', 'Player 2'], comparison_class: Reporter::ModelComparison,
+                    botrun_report_class: Reporter::BotrunReport, max_decisions: nil, model_settings: {})
+    registry[name] = Game.new(name:, runner_class:, game_state_class:, players:, comparison_class:, botrun_report_class:, max_decisions:, model_settings:)
+  end
+
+  def self.load(name)
+    entry = File.join(games_dir, name, 'lib', "#{name}.rb")
+    raise UsageError, "Unknown game #{name.inspect}. Available: #{names.join(', ')}" unless File.exist?(entry)
+
+    require entry
+    registry.fetch(name)
+  end
+
+  def self.names
+    Dir.glob('*', base: games_dir).select { |name| File.exist?(File.join(games_dir, name, 'lib', "#{name}.rb")) }.sort
+  end
+
+  def self.registry
+    @registry ||= {}
+  end
+end