cribbage_game 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f082325ee2fa9bad9eb816d32295d2c7efd3e2fee83698184d48f2e966308263
-  data.tar.gz: 8781e57a759011c7ecbc55e76b0965f2de5e076d0d2ffb7e571afe48364a107f
+  metadata.gz: 28b316ae4a4a4e446b114ea4f9615199078ead5aa27dcee342a7d75e53cdb5d1
+  data.tar.gz: a178f8da7d001822da9f8bcb13f5d9e291c63a91c53ba30b11d991dc7a93e5f9
 SHA512:
-  metadata.gz: 4f0aabf20f150a33c422a5670209fedda21a51a275f1a7114eaa07eaac7a786fd6d206f31a44ebdb6b11827fe4f98950cdcde18ede6c3e0086f381cac1f15593
-  data.tar.gz: c501dd8c015ab55f95ca9bf536042616a52b18c0718f7f135c6920c5917fbcf05df5afee1f619bc140e98271d4ae4817cfeb240b4583df97b7c94107ce438e50
+  metadata.gz: 7ca57a72414bd5652bbb4d0e86e20cbc22fff89f17ed508c949785adaa17a83c0fec9c3c81ef04817fd7c10e3917c5b13cb55ecb34ca96917ac4da1eb9190011
+  data.tar.gz: c70f594049fa96113247949d3491c222f5200fe86328ae4e0583bb405737c04412a65c2d17733ff955b5ddc1db30397e49b15096e88d28e588704cfd4103d300

data/CHANGELOG.md

@@ -1,5 +1,13 @@
-## [Unreleased]
+# Changelog
 
-## [0.1.0] - 2022-11-20
+## 1.0.0 - 2026-09-07
 
-- Initial release
+- Added support for three-player games.
+- Added interactive AI gameplay.
+- Ruby 3.0.0 is now the minimum supported version.
+- Preserved the existing two-player API and behavior.
+
+## 0.1.0 - 2023-12-07
+
+- Initial release.
+- Added support for two-player games.

data/Gemfile

@@ -4,8 +4,3 @@ source "https://rubygems.org"
 
 # Specify your gem's dependencies in cribbage_game.gemspec
 gemspec
-
-gem "rake", "~> 13.0"
-
-
-gem "standard", "~> 1.3"

data/Gemfile.lock

@@ -1,73 +1,120 @@
 PATH
   remote: .
   specs:
-    cribbage_game (0.1.0)
+    cribbage_game (1.0.0)
       aasm (~> 5.0, >= 5.0.6)
-      card_deck
+      card_deck (~> 4.02)
+      logger (>= 1.7)
+      ostruct (~> 0.6.0)
       sum_all_number_combinations (~> 0.1.2)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    aasm (5.4.0)
+    aasm (5.5.2)
       concurrent-ruby (~> 1.0)
-    ast (2.4.2)
+    ast (2.4.3)
     card_deck (4.02)
-    concurrent-ruby (1.1.10)
-    diff-lcs (1.3)
-    json (2.6.2)
-    parallel (1.22.1)
-    parser (3.1.2.1)
+    cgi (0.5.2)
+    concurrent-ruby (1.3.8)
+    date (3.5.1)
+    diff-lcs (1.6.2)
+    erb (4.0.4.1)
+      cgi (>= 0.3.3)
+    io-console (0.9.2)
+    irb (1.18.0)
+      pp (>= 0.6.0)
+      prism (>= 1.3.0)
+      rdoc (>= 4.0.0)
+      reline (>= 0.4.2)
+    json (2.21.2)
+    language_server-protocol (3.17.0.6)
+    lint_roller (1.1.0)
+    logger (1.7.0)
+    ostruct (0.6.3)
+    parallel (1.28.0)
+    parser (3.3.12.0)
       ast (~> 2.4.1)
+      racc
+    pp (0.6.4)
+      prettyprint
+    prettyprint (0.2.0)
+    prism (1.9.0)
+    psych (5.5.0)
+      date
+      stringio
+    racc (1.8.1)
     rainbow (3.1.1)
-    rake (13.0.6)
-    regexp_parser (2.6.1)
-    rexml (3.2.5)
-    rspec (3.9.0)
-      rspec-core (~> 3.9.0)
-      rspec-expectations (~> 3.9.0)
-      rspec-mocks (~> 3.9.0)
-    rspec-core (3.9.0)
-      rspec-support (~> 3.9.0)
-    rspec-expectations (3.9.0)
+    rake (13.4.2)
+    rdoc (7.2.0)
+      erb
+      psych (>= 4.0.0)
+      tsort
+    regexp_parser (2.12.0)
+    reline (0.7.0)
+      io-console (~> 0.5)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.9.0)
-    rspec-mocks (3.9.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.8)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.9.0)
-    rspec-support (3.9.0)
-    rubocop (1.39.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.7)
+    rubocop (1.88.2)
       json (~> 2.3)
-      parallel (~> 1.10)
-      parser (>= 3.1.2.1)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (>= 1.10)
+      parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
-      regexp_parser (>= 1.8, < 3.0)
-      rexml (>= 3.2.5, < 4.0)
-      rubocop-ast (>= 1.23.0, < 2.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
-      unicode-display_width (>= 1.4.0, < 3.0)
-    rubocop-ast (1.23.0)
-      parser (>= 3.1.1.0)
-    rubocop-performance (1.15.0)
-      rubocop (>= 1.7.0, < 2.0)
-      rubocop-ast (>= 0.4.0)
-    ruby-progressbar (1.11.0)
-    standard (1.18.0)
-      rubocop (= 1.39.0)
-      rubocop-performance (= 1.15.0)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.50.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    rubocop-performance (1.26.1)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.75.0, < 2.0)
+      rubocop-ast (>= 1.47.1, < 2.0)
+    ruby-progressbar (1.13.0)
+    standard (1.56.0)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.0)
+      rubocop (~> 1.88.0)
+      standard-custom (~> 1.0.0)
+      standard-performance (~> 1.8)
+    standard-custom (1.0.2)
+      lint_roller (~> 1.0)
+      rubocop (~> 1.50)
+    standard-performance (1.9.0)
+      lint_roller (~> 1.1)
+      rubocop-performance (~> 1.26.0)
+    stringio (3.2.0)
     sum_all_number_combinations (0.1.2)
-    unicode-display_width (2.3.0)
+    tsort (0.2.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
 
 PLATFORMS
   ruby
-  x64-mingw32
+  x64-unknown
   x86-mingw32
 
 DEPENDENCIES
   cribbage_game!
+  irb
   rake (~> 13.0)
   rspec (~> 3.0)
-  standard (~> 1.3)
+  standard (~> 1.56)
 
 BUNDLED WITH
    2.3.6

data/README.md

@@ -1,27 +1,17 @@
 # CribbageGame
 
-Two player cribbage game. https://bicyclecards.com/how-to-play/cribbage/
+Ruby [cribbage](https://bicyclecards.com/how-to-play/cribbage/) game engine. Includes a `play_with_ai` game runner for play against AI players using OpenAI models
 
 ## Installation
 
-Add this line to your application's Gemfile:
-
-```ruby
-gem 'cribbage_game'
+```sh
+gem install cribbage_game
 ```
 
-And then execute:
-
-    $ bundle install
-
-Or install it yourself as:
-
-    $ gem install cribbage_game
-
 ## Usage
 
 ```ruby
-game = Game.new
+game = CribbageGame::Game.new({ number_of_players: 2 })
 game.cut_for_deal # randomly determines dealer
 game.deal # deals 6 cards to game.dealer.hand & game.opponent.hand
 game.dealer.discard ["7d", "qc"] # takes cards from hand and puts in crib
@@ -35,19 +25,31 @@ game.submit_hand_scores(game.dealer)
 game.submit_crib_scores  # adds the crib's score to game.dealer.total_score
 game.deal # begin next round
 ```
-### Initialization options
-```ruby
-game = Game.new ({
-  points_to_win: 35, # overrides default of 121
-  game_over_cb: lambda { puts "game over" } # function called on game_over
-})
-```
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+```sh
+bundle install
+bundle exec rake spec # tests
+bundle exec rake standard # linting
+./bin/console # shell script to start an interactive console
+```
+
+### Play against AI
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+## Dependencies
+```sh
+bundle install
+gem install ruby-openai
+export OPENAI_API_KEY=your-api-key
+```
+
+## Playing the game
+```sh
+bin/play_with_ai --help # print command line options
+bin/play_with_ai --players 3 --name Kevin --points-to-win 32 # initialize game
+rdbg -O --port 12345 bin/play_with_ai # run with debugger
+```
 
 ## Contributing
 

data/bin/play_with_ai

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "cribbage_game/play_with_ai"
+
+begin
+  HumanVsAiRunner.from_argv(ARGV).run
+rescue ArgumentError => error
+  warn error.message
+  exit 1
+end

data/cribbage_game.gemspec

@@ -11,7 +11,7 @@ Gem::Specification.new do |spec|
   spec.summary = "Two player cribbage card game"
   spec.homepage = "https://github.com/buchowski/ruby-cribbage"
   spec.license = "MIT"
-  spec.required_ruby_version = ">= 2.6.0"
+  spec.required_ruby_version = ">= 3.0.0"
 
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = "https://github.com/buchowski/ruby-cribbage"
@@ -20,18 +20,25 @@ Gem::Specification.new do |spec|
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
   spec.files = Dir.chdir(File.expand_path(__dir__)) do
-    `git ls-files -z`.split("\x0").reject do |f|
-      (f == __FILE__) || f.match(%r{\A(?:(?:bin|test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
+    files = `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.end_with?(".gem") || f.match(%r{\A(?:(?:bin|test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
     end
+    (files + ["bin/play_with_ai"]).uniq
   end
-  spec.bindir = "exe"
-  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.bindir = "bin"
+  spec.executables = ["play_with_ai"]
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "card_deck"
+  spec.add_dependency "card_deck", "~> 4.02"
   spec.add_dependency "aasm", "~> 5.0", ">= 5.0.6"
   spec.add_dependency "sum_all_number_combinations", "~> 0.1.2"
+  spec.add_dependency "ostruct", "~> 0.6.0"
+  spec.add_dependency "logger", ">= 1.7"
+
   spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "standard", "~> 1.56"
+  spec.add_development_dependency "irb"
 
   # For more information and examples about making a new gem, check out our
   # guide at: https://bundler.io/guides/creating_gem.html

data/lib/cribbage_game/fsm.rb

@@ -4,11 +4,25 @@ module CribbageGame
   class Fsm
     include AASM
 
+    attr_accessor :game
+
+    def initialize(game = nil)
+      @game = game
+    end
+
+    def three_player?
+      game&.players&.size == 3
+    end
+
+    def two_player?
+      !three_player?
+    end
+
     aasm do
       state :cutting_for_deal, initial: true
       state :flipping_top_card
       state :discarding, :dealing, :playing
-      state :scoring_opponent_hand, :scoring_dealer_hand, :scoring_dealer_crib
+      state :scoring_opponent_hand, :scoring_opponent_2_hand, :scoring_dealer_hand, :scoring_dealer_crib
       state :game_over
 
       event :deal do
@@ -30,7 +44,9 @@ module CribbageGame
 
       event :score do
         transitions from: :playing, to: :scoring_opponent_hand
-        transitions from: :scoring_opponent_hand, to: :scoring_dealer_hand
+        transitions from: :scoring_opponent_hand, to: :scoring_dealer_hand, if: :two_player?
+        transitions from: :scoring_opponent_hand, to: :scoring_opponent_2_hand, if: :three_player?
+        transitions from: :scoring_opponent_2_hand, to: :scoring_dealer_hand
         transitions from: :scoring_dealer_hand, to: :scoring_dealer_crib
       end
 

data/lib/cribbage_game/game.rb

@@ -1,7 +1,7 @@
-require "cribbage_game/card"
-require "cribbage_game/score"
-require "cribbage_game/player"
-require "cribbage_game/fsm"
+require_relative "card"
+require_relative "score"
+require_relative "player"
+require_relative "fsm"
 
 module CribbageGame
   class NotYourTurnError < RuntimeError; end
@@ -20,9 +20,15 @@ module CribbageGame
       @points_to_win = args[:points_to_win] || 121
       @auto_score = args[:is_auto_score] || true
       @game_over_cb = args[:game_over_cb] || lambda {}
-      @players = 2.times.map { |id| Player.new self, id.to_s }
+
+      @number_of_players = args.fetch(:number_of_players, 2)
+      unless [2, 3].include?(@number_of_players)
+        raise ArgumentError, ":number_of_players must be either 2 or 3"
+      end
+
+      @players = @number_of_players.times.map { |id| Player.new self, id.to_s }
       @score_client = Score.new self
-      @fsm = Fsm.new
+      @fsm = Fsm.new(self)
       @deck = self.class.get_cards_hash CardDeck::Deck.new.cards
       @round = 0
       @winner = nil
@@ -30,6 +36,10 @@ module CribbageGame
       reset_cards
     end
 
+    def scorecards
+      @score_client.scorecards
+    end
+
     def self.get_cards_hash cards
       cards.each_with_object({}) do |card, card_map|
         card_map[card.id] = card
@@ -40,16 +50,33 @@ module CribbageGame
       card_ids.to_h { |id| [id, true] }
     end
 
+    def is_three_player_game?
+      @number_of_players == 3
+    end
+
+    def player_index(player)
+      @players.index(player)
+    end
+
+    def next_player(player)
+      current_index = player_index(player)
+      @players[(current_index + 1) % @players.size]
+    end
+
     def undealt_card_ids
-      @deck.keys.difference(@dealer.hand.keys, opponent.hand.keys)
+      dealt_cards = @players.flat_map { |player| player.hand.keys }
+      dealt_cards += @crib if @crib
+      dealt_cards << @cut_card if @cut_card
+
+      @deck.keys.difference(dealt_cards)
     end
 
     def opponent
-      @players.difference([@dealer]).first
+      next_player(@dealer)
     end
 
-    def not_whose_turn
-      @players.difference([@whose_turn]).first
+    def opponent_2
+      is_three_player_game? ? next_player(opponent) : nil
     end
 
     def can_play_card? card_id
@@ -65,16 +92,12 @@ module CribbageGame
       card_ids.map { |card_id| can_play_card?(card_id) }.any?
     end
 
-    def can_whose_turn_play?
-      has_playable_card? @whose_turn.hand
-    end
-
-    def can_not_whose_turn_play?
-      has_playable_card? not_whose_turn.hand
+    def can_player_play? player
+      player.nil? ? false : has_playable_card?(player.hand)
     end
 
-    def can_either_player_play?
-      can_whose_turn_play? || can_not_whose_turn_play?
+    def can_any_player_play?
+      @players.any? { |player| can_player_play? player }
     end
 
     def pile_score
@@ -105,16 +128,24 @@ module CribbageGame
       raise WrongStateError if !@fsm.cutting_for_deal?
 
       @dealer = @players.sample
-      @whose_turn = opponent
+      @whose_turn = next_player(@dealer)
       @fsm.deal
     end
 
     def deal
       raise WrongStateError if !@fsm.dealing?
 
-      random_card_ids = @deck.keys.sample 12
-      @dealer.hand = self.class.get_hand_hash random_card_ids.slice!(0, 6)
-      opponent.hand = self.class.get_hand_hash random_card_ids.slice!(0, 6)
+      cards_per_player = is_three_player_game? ? 5 : 6
+      cards_to_draw = @players.size * cards_per_player
+      # draw an extra card for the crib in three player game
+      cards_to_draw += 1 if is_three_player_game?
+
+      random_card_ids = @deck.keys.sample cards_to_draw
+      @players.each do |player|
+        player.hand = self.class.get_hand_hash random_card_ids.slice!(0, cards_per_player)
+      end
+
+      @crib << random_card_ids.shift if is_three_player_game?
 
       @fsm.discard
     end
@@ -124,13 +155,22 @@ module CribbageGame
 
       player.hand[card_id] = false
       @pile << card_id
-      is_last_card = !can_either_player_play?
+      is_last_card = !can_any_player_play?
       @score_client.score_play(@pile, is_last_card, player)
       @score_client.submit_play_score player
       return if we_have_a_winner?
 
       @pile = [] if is_last_card
-      @whose_turn = not_whose_turn if can_not_whose_turn_play?
+      next_player = next_player(player)
+      next_next_player = is_three_player_game? ? next_player(next_player) : nil
+      @whose_turn =
+        if can_player_play? next_player
+          next_player
+        elsif can_player_play? next_next_player
+          next_next_player
+        else
+          player
+        end
       @fsm.score if player_hands_empty?
     end
 
@@ -138,7 +178,7 @@ module CribbageGame
       raise WrongStateError if !@fsm.flipping_top_card?
 
       @cut_card = top_card || undealt_card_ids.sample
-      @whose_turn = opponent
+      @whose_turn = next_player(@dealer)
       @score_client.score_crib
       @score_client.score_hands
       @fsm.play
@@ -157,9 +197,11 @@ module CribbageGame
     def submit_hand_scores player
       raise NotYourTurnError if player == @dealer && !@fsm.scoring_dealer_hand?
       raise NotYourTurnError if player == opponent && !@fsm.scoring_opponent_hand?
+      raise NotYourTurnError if player == opponent_2 && !@fsm.scoring_opponent_2_hand?
 
       @score_client.submit_scores player, :hand
       return if we_have_a_winner?
+
       @fsm.score
     end
 
@@ -169,7 +211,7 @@ module CribbageGame
       @score_client.submit_scores @dealer, :crib
       return if we_have_a_winner?
       reset_cards
-      @dealer = opponent
+      @dealer = next_player(@dealer)
       @fsm.deal
     end
 

data/lib/cribbage_game/play_with_ai.rb

@@ -0,0 +1,305 @@
+require "json"
+require "optparse"
+require_relative "game"
+
+class HumanVsAiRunner
+  MODEL = "gpt-5-nano"
+  USAGE = "Usage: play_with_ai [--name NAME] [--players 2|3] [--points-to-win POINTS] [--all-ai] [--log-ai-inputs]"
+
+  DISCARD_TOOL = {
+    "type" => "function",
+    "name" => "discard",
+    "description" => "Discard the required number of cards from the player's hand",
+    "parameters" => {
+      "type" => "object",
+      "properties" => {
+        "card_ids" => {
+          "type" => "array",
+          "items" => {"type" => "string"},
+          "description" => "The card identifiers to discard"
+        }
+      },
+      "required" => ["card_ids"],
+      "additionalProperties" => false
+    }
+  }.freeze
+
+  PLAY_CARD_TOOL = {
+    "type" => "function",
+    "name" => "play_card",
+    "description" => "Play one legal card from the player's hand",
+    "parameters" => {
+      "type" => "object",
+      "properties" => {
+        "card_id" => {
+          "type" => "string",
+          "description" => "A card identifier such as 5h, kd, or 10s"
+        }
+      },
+      "required" => ["card_id"],
+      "additionalProperties" => false
+    }
+  }.freeze
+
+  def initialize(number_of_players: 2, points_to_win: 121, name: nil, all_ai: false, log_ai_inputs: false, client: nil, input: $stdin, output: $stdout)
+    unless [2, 3].include?(number_of_players)
+      raise ArgumentError, "number_of_players must be either 2 or 3"
+    end
+
+    @number_of_players = number_of_players
+    @points_to_win = points_to_win
+    @all_ai = all_ai
+    @human_name = name.to_s.strip
+    @human_name = "Human Player" if @human_name.empty?
+    @log_ai_inputs = log_ai_inputs
+    @client = client || default_client
+    @input = input
+    @output = output
+  end
+
+  def self.from_argv(arguments)
+    options = {name: nil, number_of_players: 2, points_to_win: 121, all_ai: false, log_ai_inputs: false}
+    parser = OptionParser.new do |opts|
+      opts.banner = USAGE
+      opts.on_tail("-h", "--help", "Show available options") do
+        puts opts
+        exit
+      end
+      opts.on("--name NAME", String, "Human player's name (default: Human Player)") { |name| options[:name] = name }
+      opts.on("--players COUNT", Integer, "Number of players (2 or 3; default: 2)") do |count|
+        options[:number_of_players] = count
+      end
+      opts.on("--number-of-players COUNT", Integer, "Alias for --players (default: 2)") do |count|
+        options[:number_of_players] = count
+      end
+      opts.on("--points-to-win POINTS", Integer, "Points needed to win (default: 121)") do |points|
+        options[:points_to_win] = points
+      end
+      opts.on("--log-ai-inputs", "Log AI inputs and failed tool attempts") do
+        options[:log_ai_inputs] = true
+      end
+      opts.on("--all-ai", "Watch all players play by AI") do
+        options[:all_ai] = true
+      end
+    end
+
+    remaining_arguments = parser.parse!(arguments.dup)
+    raise ArgumentError, "Unexpected arguments: #{remaining_arguments.join(" ")}" unless remaining_arguments.empty?
+
+    new(**options)
+  rescue OptionParser::ParseError, ArgumentError => error
+    raise ArgumentError, "#{error.message}\n#{USAGE}"
+  end
+
+  def run
+    game = CribbageGame::Game.new(number_of_players: @number_of_players, points_to_win: @points_to_win)
+    human = @all_ai ? nil : game.players.first
+    human.name = @human_name unless human.nil?
+    @human_player = human
+
+    game.cut_for_deal
+    until game.fsm.game_over?
+      announce_round(game, human)
+      game.deal
+      discard_hands(game, human)
+      game.flip_top_card
+      log("Cut card: #{game.cut_card}")
+      play_cards(game, human)
+      break if game.fsm.game_over?
+
+      log("")
+      score_round(game)
+      log("")
+    end
+
+    log("Winner: #{player_label(game.winner)} with #{game.winner.total_score} points.")
+    game
+  end
+
+  private
+
+  def default_client
+    require "openai"
+    OpenAI::Client.new(
+      access_token: ENV.fetch("OPENAI_API_KEY"),
+      log_errors: true
+    )
+  rescue LoadError
+    raise LoadError, "The AI runner requires the ruby-openai gem"
+  end
+
+  def discard_hands(game, human)
+    game.players.each do |player|
+      count = game.is_three_player_game? ? 1 : 2
+      if player == human
+        human_discard(player, count)
+      else
+        ai_discard(player, count)
+      end
+    end
+  end
+
+  def human_discard(player, count)
+    loop do
+      ids = prompt("Your hand: #{available_cards(player).join(", ")}\nDiscard #{count} card#{"s" if count > 1}: ")
+        .split(/[\s,]+/)
+        .reject(&:empty?)
+
+      if ids.size == count && ids.uniq.size == count && ids.all? { |id| player.hand[id] }
+        player.discard(ids)
+        return
+      end
+
+      log("Please enter exactly #{count} card IDs from your hand.")
+    end
+  end
+
+  def ai_discard(player, count)
+    arguments = ai_tool_arguments(
+      player,
+      DISCARD_TOOL,
+      "Choose #{count} cards to discard from your hand: #{available_cards(player).join(", ")} ."
+    ) do |data|
+      ids = data["card_ids"]
+      ids.is_a?(Array) && ids.size == count && ids.uniq.size == count && ids.all? { |id| player.hand[id] }
+    end
+
+    ids = arguments.fetch("card_ids")
+    log("#{player_label(player)} discards: #{ids.join(", ")}")
+    player.discard(ids)
+  end
+
+  def play_cards(game, human)
+    while game.fsm.playing? && !game.player_hands_empty?
+      player = game.whose_turn
+      playable = available_cards(player).select { |id| game.can_play_card?(id) }
+
+      card_id = if player == human
+        prompt_for_play(game, player, playable)
+      else
+        ai_play(game, player, playable)
+      end
+
+      pile_was_active = !game.pile.empty?
+      pile_total_after_play = game.pile_score + game.deck.fetch(card_id).value
+      game.play_card(player, card_id)
+      play_score = game.scorecards.fetch(game.round).fetch(:play).last
+      log("#{player_label(player)} played #{card_id}; pile total #{pile_total_after_play}")
+      if play_score[:points] > 0
+        log("#{player_label(player)} scored #{play_score[:points]} point#{"s" if play_score[:points] != 1} during play: #{format_score_reasons(play_score[:reasons])}.")
+      end
+      if pile_was_active && game.pile.empty?
+        log("")
+      end
+    end
+  end
+
+  def prompt_for_play(game, player, playable)
+    loop do
+      card_id = prompt(
+        "Your cards: #{available_cards(player).join(", ")} " \
+        "(playable: #{playable.join(", ")}; pile: #{game.pile_score})\nPlay card: "
+      ).strip.downcase
+      return card_id if playable.include?(card_id)
+
+      log("Choose one of the playable cards: #{playable.join(", ")}.")
+    end
+  end
+
+  def ai_play(game, player, playable)
+    arguments = ai_tool_arguments(
+      player,
+      PLAY_CARD_TOOL,
+      "Choose one card to play. Playable cards: #{playable.join(", ")}. " \
+      "Current pile total: #{game.pile_score}."
+    ) { |data| playable.include?(data["card_id"]) }
+
+    arguments.fetch("card_id")
+  end
+
+  def score_round(game)
+    round_scorecard = game.scorecards.fetch(game.round)
+    pegging_scores = round_scorecard.fetch(:play, []).group_by { |play| play.fetch(:player_id) }
+    scoring_players = [game.opponent]
+    scoring_players << game.opponent_2 if game.is_three_player_game?
+    scoring_players << game.dealer
+
+    scoring_players.each do |player|
+      pegging_points = pegging_scores.fetch(player.id, []).sum { |play| play.fetch(:points) }
+      log("#{player_label(player)} pegging score: #{pegging_points} point#{"s" if pegging_points != 1}.")
+      hand_score = round_scorecard.fetch(player.id).fetch(:hand).fetch(:total_score)
+      log("#{player_label(player)} hand score: #{hand_score} point#{"s" if hand_score != 1}.")
+      game.submit_hand_scores(player)
+      break if game.fsm.game_over?
+    end
+    return if game.fsm.game_over?
+
+    crib_owner = game.dealer
+    crib_score = round_scorecard.fetch(crib_owner.id).fetch(:crib).fetch(:total_score)
+    game.submit_crib_scores
+    log("#{player_label(crib_owner)} crib score: #{crib_score} point#{"s" if crib_score != 1}.")
+    log("Player totals: #{game.players.map { |player| "#{player_label(player)}: #{player.total_score}" }.join(", ")}")
+  end
+
+  def ai_tool_arguments(player, tool, input)
+    3.times do |attempt|
+      log("#{player_label(player)} input: #{input}") if @log_ai_inputs
+      response = @client.responses.create(
+        parameters: {
+          model: MODEL,
+          input: input,
+          tools: [tool],
+          tool_choice: "required"
+        }
+      )
+      function_call = response.dig("output")&.find { |item| item["type"] == "function_call" }
+      tool_name = function_call&.fetch("name", tool["name"])
+      raw_arguments = function_call&.fetch("arguments", nil)
+      arguments = raw_arguments && JSON.parse(raw_arguments)
+      return arguments if arguments && yield(arguments)
+
+      if @log_ai_inputs
+        log("#{player_label(player)} failed tool #{tool_name} with arguments #{arguments.inspect} (attempt #{attempt + 1}).")
+      end
+    rescue JSON::ParserError, KeyError, TypeError
+      if @log_ai_inputs
+        log("#{player_label(player)} failed tool #{tool_name || tool["name"]} with raw arguments #{raw_arguments.inspect} (attempt #{attempt + 1}).")
+      end
+    end
+
+    raise "#{player_label(player)} failed to provide a legal action"
+  end
+
+  def announce_round(game, human)
+    dealer = (game.dealer == human) ? @human_name : player_label(game.dealer)
+    log("Round #{game.round}: dealer is #{dealer}.")
+  end
+
+  def player_label(player)
+    return @human_name if player == @human_player
+
+    ai_names = @all_ai ? {"0" => "One", "1" => "Two", "2" => "Three"} : {"1" => "One", "2" => "Two", "0" => "Three"}
+    ai_name = ai_names.fetch(player.id, player.id)
+    "AI Player #{ai_name}"
+  end
+
+  def format_score_reasons(reasons)
+    reasons.map { |reason| "#{reason[:type].tr("_", " ")} (#{reason[:points]})" }.join(", ")
+  end
+
+  def available_cards(player)
+    player.hand.select { |_id, available| available }.keys
+  end
+
+  def prompt(message)
+    @output.print(message)
+    line = @input.gets
+    raise "Input ended before the game finished" if line.nil?
+
+    line
+  end
+
+  def log(message)
+    @output.puts(message)
+  end
+end

data/lib/cribbage_game/score.rb

@@ -1,4 +1,4 @@
-require "cribbage_game/score_utils"
+require_relative "score_utils"
 
 module CribbageGame
   class Score
@@ -9,6 +9,8 @@ module CribbageGame
       @scorecards = {}
     end
 
+    attr_reader :scorecards
+
     def get_cards card_ids
       card_ids.map { |id| @game.deck[id] }
     end
@@ -47,9 +49,10 @@ module CribbageGame
     def score_play pile_ids, is_last_card, player
       @scorecards[@game.round] = @scorecards[@game.round] || {play: []}
       pile_cards = get_cards pile_ids
-      points = get_pile_points(pile_cards, is_last_card) # pass pile cards not ids
+      score = get_pile_points(pile_cards, is_last_card) # pass pile cards not ids
       @scorecards[@game.round][:play] << {
-        points: points,
+        points: score[:points],
+        reasons: score[:reasons],
         player_id: player.id,
         pile: pile_ids,
         card_id: pile_ids.last

data/lib/cribbage_game/score_utils.rb

@@ -112,15 +112,26 @@ module CribbageGame
 
       throw "31 should always be is_last_card" if pile_score == 31 && !is_last_card
 
-      points = 0
-      points = 1 if pile_score == 31
-      points = 2 if pile_score == 15
+      reasons = []
+      if pile_score == 31
+        reasons << {type: "thirty_one", points: 2}
+      elsif pile_score == 15
+        reasons << {type: "fifteen", points: 2}
+      end
+      if is_last_card && pile_score != 31
+        reasons << {type: "last_card", points: 1}
+      end
+
+      consecutive_points = score_consecutive pile_cards
+      if consecutive_points > 0
+        consecutive_type = {2 => "pair", 6 => "three_of_a_kind", 12 => "four_of_a_kind"}.fetch(consecutive_points)
+        reasons << {type: consecutive_type, points: consecutive_points}
+      end
 
-      points += 1 if is_last_card
-      points += score_consecutive pile_cards
-      points += score_pile_runs pile_cards
+      run_points = score_pile_runs pile_cards
+      reasons << {type: "run", points: run_points} if run_points > 0
 
-      points
+      {points: reasons.sum { |reason| reason[:points] }, reasons: reasons}
     end
   end
 end

data/lib/cribbage_game/version.rb

@@ -1,3 +1,3 @@
 module CribbageGame
-  VERSION = "0.1.0"
+  VERSION = "1.0.0"
 end

metadata

@@ -1,29 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: cribbage_game
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.0.0
 platform: ruby
 authors:
 - buchowski
 autorequire: 
-bindir: exe
+bindir: bin
 cert_chain: []
-date: 2023-12-07 00:00:00.000000000 Z
+date: 2026-09-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: card_deck
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '4.02'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '4.02'
 - !ruby/object:Gem::Dependency
   name: aasm
   requirement: !ruby/object:Gem::Requirement
@@ -58,6 +58,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 0.1.2
+- !ruby/object:Gem::Dependency
+  name: ostruct
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.6.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.6.0
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.7'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -72,10 +100,53 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.56'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.56'
+- !ruby/object:Gem::Dependency
+  name: irb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: 
 email:
 - bucholz.adam@gmail.com
-executables: []
+executables:
+- play_with_ai
 extensions: []
 extra_rdoc_files: []
 files:
@@ -86,11 +157,13 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- bin/play_with_ai
 - cribbage_game.gemspec
 - lib/cribbage_game.rb
 - lib/cribbage_game/card.rb
 - lib/cribbage_game/fsm.rb
 - lib/cribbage_game/game.rb
+- lib/cribbage_game/play_with_ai.rb
 - lib/cribbage_game/player.rb
 - lib/cribbage_game/score.rb
 - lib/cribbage_game/score_utils.rb
@@ -110,7 +183,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.6.0
+      version: 3.0.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="