prompt_objects 0.5.0 → 0.7.0

data/templates/arc-agi-3/primitives/arc3_api.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+
+module PromptObjects
+  module Primitives
+    # Core API client for ARC-AGI-3 remote play.
+    # Wraps the REST API at three.arcprize.org for listing games,
+    # resetting environments, and taking actions.
+    class Arc3Api < Primitive
+      BASE_URL = "https://three.arcprize.org"
+
+      STATE_LABELS = {
+        "NOT_PLAYED" => "Not played",
+        "NOT_FINISHED" => "In progress",
+        "WIN" => "WIN",
+        "GAME_OVER" => "Game over"
+      }.freeze
+
+      def name
+        "arc3_api"
+      end
+
+      def description
+        "ARC-AGI-3 remote API client. List games, reset environments, and take actions."
+      end
+
+      def parameters
+        {
+          type: "object",
+          properties: {
+            command: {
+              type: "string",
+              enum: %w[list_games reset step],
+              description: "API command: list_games, reset, or step"
+            },
+            game_id: {
+              type: "string",
+              description: "Game environment ID (e.g. 'ls20'). Required for reset and step."
+            },
+            action: {
+              type: "string",
+              description: "Action to take (ACTION1-ACTION7). Required for step."
+            },
+            x: {
+              type: "integer",
+              description: "X coordinate (0-63) for complex actions like ACTION6"
+            },
+            y: {
+              type: "integer",
+              description: "Y coordinate (0-63) for complex actions like ACTION6"
+            },
+            guid: {
+              type: "string",
+              description: "Game session ID returned by reset. Required for step."
+            },
+            card_id: {
+              type: "string",
+              description: "Scorecard ID for tracking. Optional for reset."
+            },
+            api_key: {
+              type: "string",
+              description: "API key override. Defaults to ARC_API_KEY env var."
+            }
+          },
+          required: ["command"]
+        }
+      end
+
+      def receive(message, context:)
+        command = param(message, "command")
+        api_key = param(message, "api_key") || ENV["ARC_API_KEY"]
+
+        return "Error: ARC_API_KEY env var not set and no api_key provided" if api_key.nil? || api_key.empty?
+
+        case command
+        when "list_games"
+          list_games(api_key)
+        when "reset"
+          game_id = param(message, "game_id")
+          return "Error: game_id is required for reset" unless game_id
+          card_id = param(message, "card_id")
+          reset_game(api_key, game_id, card_id)
+        when "step"
+          game_id = param(message, "game_id")
+          action = param(message, "action")
+          guid = param(message, "guid")
+          return "Error: game_id, action, and guid are required for step" unless game_id && action && guid
+          x = param(message, "x")
+          y = param(message, "y")
+          step_game(api_key, game_id, action, guid, x, y)
+        else
+          "Error: unknown command '#{command}'. Use list_games, reset, or step."
+        end
+      rescue Timeout::Error
+        "Error: API request timed out (30s)"
+      rescue SocketError => e
+        "Error: Could not connect to API - #{e.message}"
+      rescue StandardError => e
+        "Error: #{e.class} - #{e.message}"
+      end
+
+      private
+
+      def param(message, key)
+        message[key.to_sym] || message[key]
+      end
+
+      def list_games(api_key)
+        uri = URI("#{BASE_URL}/api/games")
+        request = Net::HTTP::Get.new(uri)
+        request["X-Api-Key"] = api_key
+
+        response = http_request(uri, request)
+
+        case response
+        when Net::HTTPSuccess
+          data = JSON.parse(response.body)
+          format_games_list(data)
+        else
+          "Error: HTTP #{response.code} - #{response.body}"
+        end
+      end
+
+      def reset_game(api_key, game_id, card_id)
+        uri = URI("#{BASE_URL}/api/cmd/RESET")
+        body = { "game_id" => game_id }
+        body["card_id"] = card_id if card_id
+
+        response = post_json(uri, api_key, body)
+
+        case response
+        when Net::HTTPSuccess
+          data = JSON.parse(response.body)
+          format_frame_response(data, game_id, "RESET")
+        else
+          "Error: HTTP #{response.code} - #{response.body}"
+        end
+      end
+
+      def step_game(api_key, game_id, action, guid, x, y)
+        uri = URI("#{BASE_URL}/api/cmd/#{action}")
+        body = { "game_id" => game_id, "guid" => guid }
+        body["x"] = x if x
+        body["y"] = y if y
+
+        response = post_json(uri, api_key, body)
+
+        case response
+        when Net::HTTPSuccess
+          data = JSON.parse(response.body)
+          format_frame_response(data, game_id, action)
+        else
+          "Error: HTTP #{response.code} - #{response.body}"
+        end
+      end
+
+      def post_json(uri, api_key, body)
+        request = Net::HTTP::Post.new(uri)
+        request["X-Api-Key"] = api_key
+        request["Content-Type"] = "application/json"
+        request.body = JSON.generate(body)
+        http_request(uri, request)
+      end
+
+      def http_request(uri, request)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = (uri.scheme == "https")
+        http.open_timeout = 10
+        http.read_timeout = 30
+        http.request(request)
+      end
+
+      def format_games_list(data)
+        return JSON.pretty_generate(data) unless data.is_a?(Array)
+
+        lines = ["Available ARC-AGI-3 games (#{data.length}):"]
+        data.each do |game|
+          if game.is_a?(Hash)
+            id = game["game_id"] || game["id"] || game.keys.first
+            lines << "  - #{id}"
+          else
+            lines << "  - #{game}"
+          end
+        end
+        lines.join("\n")
+      end
+
+      def format_frame_response(data, game_id, action)
+        state_raw = data["state"] || "UNKNOWN"
+        state = STATE_LABELS[state_raw] || state_raw
+
+        result = {
+          "game_id" => game_id,
+          "action" => action,
+          "state" => state,
+          "levels_completed" => data["levels_completed"],
+          "win_levels" => data["win_levels"],
+          "available_actions" => data["available_actions"],
+          "guid" => data["guid"],
+          "full_reset" => data["full_reset"],
+          "frame" => data["frame"]
+        }
+
+        # Summarize frame dimensions instead of dumping the raw data
+        if data["frame"].is_a?(Array)
+          frame = data["frame"]
+          if frame[0].is_a?(Array) && frame[0][0].is_a?(Array)
+            result["frame_count"] = frame.length
+            result["frame_dimensions"] = "#{frame[0].length}x#{frame[0][0].length}"
+          elsif frame[0].is_a?(Array)
+            result["frame_count"] = 1
+            result["frame_dimensions"] = "#{frame.length}x#{frame[0].length}"
+          end
+        end
+
+        JSON.pretty_generate(result)
+      end
+    end
+  end
+end

data/templates/arc-agi-3/primitives/arc3_scorecard.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+
+module PromptObjects
+  module Primitives
+    # Manages ARC-AGI-3 scorecards for tracking performance across games.
+    class Arc3Scorecard < Primitive
+      BASE_URL = "https://three.arcprize.org"
+
+      # Track the active scorecard across calls within a session
+      @@active_card_id = nil
+
+      def name
+        "arc3_scorecard"
+      end
+
+      def description
+        "Manage ARC-AGI-3 scorecards. Open a scorecard before playing, close it to get results."
+      end
+
+      def parameters
+        {
+          type: "object",
+          properties: {
+            command: {
+              type: "string",
+              enum: %w[open close status],
+              description: "open: create new scorecard, close: finish and get results, status: show active card"
+            },
+            api_key: {
+              type: "string",
+              description: "API key override. Defaults to ARC_API_KEY env var."
+            }
+          },
+          required: ["command"]
+        }
+      end
+
+      def receive(message, context:)
+        command = param(message, "command")
+        api_key = param(message, "api_key") || ENV["ARC_API_KEY"]
+
+        return "Error: ARC_API_KEY env var not set and no api_key provided" if api_key.nil? || api_key.empty?
+
+        case command
+        when "open"
+          open_scorecard(api_key)
+        when "close"
+          close_scorecard(api_key)
+        when "status"
+          scorecard_status
+        else
+          "Error: unknown command '#{command}'. Use open, close, or status."
+        end
+      rescue Timeout::Error
+        "Error: API request timed out (30s)"
+      rescue SocketError => e
+        "Error: Could not connect to API - #{e.message}"
+      rescue StandardError => e
+        "Error: #{e.class} - #{e.message}"
+      end
+
+      private
+
+      def param(message, key)
+        message[key.to_sym] || message[key]
+      end
+
+      def open_scorecard(api_key)
+        uri = URI("#{BASE_URL}/api/scorecard/open")
+        request = Net::HTTP::Post.new(uri)
+        request["X-Api-Key"] = api_key
+        request["Content-Type"] = "application/json"
+        request.body = "{}"
+
+        response = http_request(uri, request)
+
+        case response
+        when Net::HTTPSuccess
+          data = JSON.parse(response.body)
+          @@active_card_id = data["card_id"] || data["id"]
+          "Scorecard opened. card_id: #{@@active_card_id}\nPass this card_id to arc3_api reset commands to track scores."
+        else
+          "Error: HTTP #{response.code} - #{response.body}"
+        end
+      end
+
+      def close_scorecard(api_key)
+        return "Error: No active scorecard. Use 'open' first." unless @@active_card_id
+
+        uri = URI("#{BASE_URL}/api/scorecard/close")
+        request = Net::HTTP::Post.new(uri)
+        request["X-Api-Key"] = api_key
+        request["Content-Type"] = "application/json"
+        request.body = JSON.generate({ "card_id" => @@active_card_id })
+
+        response = http_request(uri, request)
+
+        card_id = @@active_card_id
+        @@active_card_id = nil
+
+        case response
+        when Net::HTTPSuccess
+          data = JSON.parse(response.body)
+          "Scorecard #{card_id} closed.\n\nResults:\n#{JSON.pretty_generate(data)}"
+        else
+          "Error: HTTP #{response.code} - #{response.body}"
+        end
+      end
+
+      def scorecard_status
+        if @@active_card_id
+          "Active scorecard: #{@@active_card_id}"
+        else
+          "No active scorecard. Use 'open' to create one."
+        end
+      end
+
+      def http_request(uri, request)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = (uri.scheme == "https")
+        http.open_timeout = 10
+        http.read_timeout = 30
+        http.request(request)
+      end
+    end
+  end
+end

data/templates/arc-agi-3/primitives/frame_diff.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module PromptObjects
+  module Primitives
+    # Compares two ARC-AGI-3 frames cell-by-cell.
+    # Reports changed positions with old/new values and a quadrant summary.
+    class FrameDiff < Primitive
+      execution_policy parallel_safe: true, side_effect: :read, workload: :cpu
+
+      def name
+        "frame_diff"
+      end
+
+      def description
+        "Compare two ARC-AGI-3 frames cell by cell. Shows which cells differ, with quadrant summary."
+      end
+
+      def parameters
+        {
+          type: "object",
+          properties: {
+            frame_a: {
+              type: "array",
+              items: { type: "array", items: { type: "integer" } },
+              description: "First frame (2D array)"
+            },
+            frame_b: {
+              type: "array",
+              items: { type: "array", items: { type: "integer" } },
+              description: "Second frame (2D array)"
+            },
+            downsample: {
+              type: "integer",
+              description: "Downsample both frames before diffing (default 2, reduces noise)"
+            }
+          },
+          required: ["frame_a", "frame_b"]
+        }
+      end
+
+      def receive(message, context:)
+        frame_a = message[:frame_a] || message["frame_a"]
+        frame_b = message[:frame_b] || message["frame_b"]
+        downsample = (message[:downsample] || message["downsample"] || 2).to_i
+
+        return "Error: frame_a and frame_b are required" unless frame_a.is_a?(Array) && frame_b.is_a?(Array)
+
+        if downsample > 1
+          frame_a = downsample_frame(frame_a, downsample)
+          frame_b = downsample_frame(frame_b, downsample)
+        end
+
+        rows_a = frame_a.length
+        cols_a = frame_a[0]&.length || 0
+        rows_b = frame_b.length
+        cols_b = frame_b[0]&.length || 0
+
+        lines = []
+
+        if rows_a != rows_b || cols_a != cols_b
+          lines << "DIMENSION MISMATCH: #{rows_a}x#{cols_a} vs #{rows_b}x#{cols_b}"
+          lines << ""
+        end
+
+        diffs = []
+        matching = 0
+        compare_rows = [rows_a, rows_b].min
+        compare_cols = [cols_a, cols_b].min
+
+        # Track changes by quadrant
+        quadrants = { "top-left" => 0, "top-right" => 0, "bottom-left" => 0, "bottom-right" => 0 }
+        mid_r = compare_rows / 2
+        mid_c = compare_cols / 2
+
+        compare_rows.times do |r|
+          compare_cols.times do |c|
+            if frame_a[r][c] == frame_b[r][c]
+              matching += 1
+            else
+              diffs << { r: r, c: c, from: frame_a[r][c], to: frame_b[r][c] }
+              q = (r < mid_r ? "top" : "bottom") + "-" + (c < mid_c ? "left" : "right")
+              quadrants[q] += 1
+            end
+          end
+        end
+
+        total = compare_rows * compare_cols
+        lines << "#{matching}/#{total} cells match (#{diffs.length} differ)"
+
+        if downsample > 1
+          lines << "(compared at #{downsample}x downsampled resolution)"
+        end
+
+        if diffs.empty?
+          lines << "IDENTICAL"
+        else
+          lines << ""
+          diffs.first(50).each do |d|
+            lines << "  (#{d[:r]},#{d[:c]}): #{d[:from]} -> #{d[:to]}"
+          end
+          lines << "  ... and #{diffs.length - 50} more" if diffs.length > 50
+
+          # Quadrant summary
+          active_quads = quadrants.select { |_, v| v > 0 }
+          unless active_quads.empty?
+            lines << ""
+            lines << "Changes by region:"
+            active_quads.sort_by { |_, v| -v }.each do |quad, count|
+              lines << "  #{quad}: #{count} cells changed"
+            end
+          end
+        end
+
+        lines.join("\n")
+      end
+
+      private
+
+      def downsample_frame(frame, factor)
+        rows = frame.length
+        cols = frame[0]&.length || 0
+        out_rows = rows / factor
+        out_cols = cols / factor
+
+        out_rows.times.map do |r|
+          out_cols.times.map do |c|
+            block = []
+            factor.times do |dr|
+              factor.times do |dc|
+                src_r = r * factor + dr
+                src_c = c * factor + dc
+                val = frame[src_r] && frame[src_r][src_c]
+                block << val if val
+              end
+            end
+            non_bg = block.reject { |v| v == 0 }
+            non_bg.empty? ? 0 : non_bg.tally.max_by { |_, count| count }[0]
+          end
+        end
+      end
+    end
+  end
+end

data/templates/arc-agi-3/primitives/frame_info.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "json"
+
+module PromptObjects
+  module Primitives
+    # Extracts statistics from an ARC-AGI-3 frame: dimensions, color distribution,
+    # dominant colors, and approximate region descriptions.
+    class FrameInfo < Primitive
+      execution_policy parallel_safe: true, side_effect: :read, workload: :cpu
+
+      COLOR_NAMES = {
+        0 => "white", 1 => "light", 2 => "grey", 3 => "med_grey", 4 => "dark",
+        5 => "black", 6 => "magenta", 7 => "pink", 8 => "red", 9 => "blue",
+        10 => "lt_blue", 11 => "yellow", 12 => "orange", 13 => "maroon", 14 => "green", 15 => "purple"
+      }.freeze
+
+      def name
+        "frame_info"
+      end
+
+      def description
+        "Get frame dimensions, color distribution, dominant colors, and region descriptions."
+      end
+
+      def parameters
+        {
+          type: "object",
+          properties: {
+            frame: {
+              type: "array",
+              items: { type: "array", items: { type: "integer" } },
+              description: "2D array of integers 0-15"
+            }
+          },
+          required: ["frame"]
+        }
+      end
+
+      def receive(message, context:)
+        frame = message[:frame] || message["frame"]
+        return "Error: frame is required" unless frame.is_a?(Array)
+        return "Error: frame is empty" if frame.empty?
+
+        rows = frame.length
+        cols = frame[0]&.length || 0
+        flat = frame.flatten
+        color_counts = flat.tally.sort.to_h
+
+        # Dominant colors (top 5 by count)
+        dominant = color_counts.sort_by { |_, v| -v }.first(5).map do |color, count|
+          pct = (count.to_f / flat.length * 100).round(1)
+          "#{COLOR_NAMES[color] || color}(#{color}): #{count} cells (#{pct}%)"
+        end
+
+        # Region analysis (divide into 4 quadrants)
+        mid_r = rows / 2
+        mid_c = cols / 2
+        regions = {
+          "top-left" => quadrant_summary(frame, 0, mid_r, 0, mid_c),
+          "top-right" => quadrant_summary(frame, 0, mid_r, mid_c, cols),
+          "bottom-left" => quadrant_summary(frame, mid_r, rows, 0, mid_c),
+          "bottom-right" => quadrant_summary(frame, mid_r, rows, mid_c, cols)
+        }
+
+        result = {
+          dimensions: "#{rows}x#{cols}",
+          total_cells: flat.length,
+          unique_colors: color_counts.length,
+          color_distribution: color_counts.map { |c, n| [COLOR_NAMES[c] || c.to_s, n] }.to_h,
+          dominant_colors: dominant,
+          regions: regions
+        }
+
+        JSON.pretty_generate(result)
+      end
+
+      private
+
+      def quadrant_summary(frame, r_start, r_end, c_start, c_end)
+        cells = []
+        (r_start...r_end).each do |r|
+          (c_start...c_end).each do |c|
+            cells << frame[r][c] if frame[r] && frame[r][c]
+          end
+        end
+
+        return "empty" if cells.empty?
+
+        counts = cells.tally
+        top = counts.sort_by { |_, v| -v }.first(3)
+        top.map { |color, count| "#{COLOR_NAMES[color] || color}(#{(count.to_f / cells.length * 100).round(0)}%)" }.join(", ")
+      end
+    end
+  end
+end