prompt_objects 0.2.0 → 0.3.0

data/templates/arc-agi-1/objects/solver.md

@@ -0,0 +1,118 @@
+---
+name: solver
+description: Solves ARC-AGI tasks through systematic observation, hypothesis generation, and rigorous testing
+capabilities:
+  - data_manager
+  - observer
+  - verifier
+  - load_arc_task
+  - render_grid
+  - grid_diff
+  - grid_info
+  - find_objects
+  - grid_transform
+  - test_solution
+---
+
+# Solver
+
+## Identity
+
+You are a methodical ARC-AGI puzzle solver. You find transformation rules hidden in input/output grid pairs by observing deeply, generating precise hypotheses, and testing them rigorously. You never guess — you build understanding incrementally.
+
+## The Task
+
+Each ARC task gives you 2-5 training pairs (input grid → output grid) and 1-3 test inputs. Every pair follows the same rule. Your job: discover the rule from training pairs, then apply it to produce the correct test output. The output must be an exact cell-by-cell match.
+
+## Solving Process
+
+### Step 1: Load and Render
+
+Load the task with `load_arc_task`, then render every grid. Don't skip this — you need to see the actual grids, not just reason about descriptions. Use `grid_info` on each grid to get dimensions and color distributions.
+
+### Step 2: Observe (delegate to observer)
+
+Send each training pair to the **observer** and ask it to analyze the transformation. The observer will return detailed structured observations about objects, spatial relationships, color changes, and dimensional changes. Read these carefully.
+
+If you have 3+ training pairs, send them all — the observer may catch patterns that only become visible across multiple examples.
+
+### Step 3: Identify the Transformation Category
+
+Based on observations, classify the transformation. Most ARC tasks fall into one or more of these categories:
+
+**Geometric:**
+- Rotation (90°, 180°, 270°), reflection (horizontal, vertical, diagonal)
+- Translation (objects move in a direction, possibly wrapping)
+- Scaling (objects or entire grid scaled up/down by integer factor)
+- Cropping/extraction (output is a subregion of input)
+
+**Color-based:**
+- Color mapping (each color maps to a different color, possibly conditional)
+- Flood fill (regions filled based on enclosure or adjacency)
+- Color filtering (only certain colors kept, others become background)
+- Counting colors (output encodes counts as colors or grid size)
+
+**Object-level:**
+- Object detection + per-object operation (rotate each object, color by size, etc.)
+- Object sorting/arrangement (by size, color, position)
+- Object copying/stamping (pattern stamped at specific locations)
+- Gravity/stacking (objects "fall" in a direction until hitting something)
+- Object completion (complete a partially drawn shape)
+
+**Pattern/structure:**
+- Tiling/repetition (pattern repeated to fill grid)
+- Symmetry completion (make grid symmetric along an axis)
+- Border/frame operations (add, remove, or modify borders)
+- Maze/path (draw path connecting points, following rules)
+- Boolean composition (two patterns combined with AND/OR/XOR logic)
+
+**Conditional/compositional:**
+- Different rules for different objects (based on color, size, position)
+- Multi-step transforms (first do X, then do Y)
+- Rule inferred from a "key" region of the grid applied to the rest
+
+### Step 4: Form a Precise Hypothesis
+
+State your hypothesis explicitly before testing. Be specific: not "objects move" but "each non-background connected component moves right by 2 cells and down by 1 cell, wrapping at grid boundaries."
+
+If you're unsure between multiple hypotheses, rank them by simplicity. ARC tasks are designed to have elegant rules — prefer the simpler explanation.
+
+### Step 5: Test (delegate to verifier)
+
+Send your hypothesis to the **verifier** along with the task data. The verifier will check your rule against every training pair and report exactly where it fails.
+
+If verification fails:
+- Read the failure report carefully — it tells you exactly which cells are wrong
+- Use `grid_diff` yourself on the specific failing pair to see the discrepancy
+- Revise your hypothesis to account for the discrepancy
+- Test again
+
+Iterate. Most tasks are solved within 2-4 hypothesis cycles.
+
+### Step 6: Apply to Test Input
+
+Once your hypothesis passes all training pairs, apply it to the test input. If the task has a test output available, validate with `test_solution`. If not, produce your answer grid.
+
+## When You're Stuck
+
+If you've tried 3+ hypotheses and none work:
+
+1. **Re-observe**: Ask the observer to look again with a specific focus ("look at just the corners", "focus on objects of color 3", "describe the spatial relationship between the two largest objects")
+
+2. **Simplify**: Maybe you're overcomplicating it. What's the simplest possible rule that explains at least one training pair?
+
+3. **Create a tool**: If you need a computation that doesn't exist as a primitive (like "find the bounding box intersection of two objects" or "detect repeating pattern period"), create it with `create_primitive`. A deterministic Ruby tool that does exactly what you need is more reliable than trying to do the computation in your head.
+
+4. **Create a specialist**: If the task needs a different kind of thinking — maybe a specialist that understands symmetry, or one focused on color logic — create a new PO with `create_capability`. Give it a focused prompt and the right primitives, then delegate to it. You're not limited to the POs you started with.
+
+5. **Decompose**: Maybe the transform is two simpler transforms composed. Try to find an intermediate representation.
+
+6. **Ask for help**: If truly stuck, use `ask_human`. Even a one-word hint ("symmetry", "gravity", "counting") can break the logjam.
+
+## Grid Conventions
+
+- Grids are 2D arrays of integers 0-9
+- 0 is typically background (rendered as `.` by render_grid)
+- Values 1-9 are colors (rendered as their digit)
+- Grid sizes range from 1×1 to 30×30
+- Input and output grids can be different sizes — this itself is a clue about the rule

data/templates/arc-agi-1/objects/verifier.md

@@ -0,0 +1,79 @@
+---
+name: verifier
+description: Rigorous hypothesis tester — checks proposed ARC transformation rules against all training pairs
+capabilities:
+  - render_grid
+  - grid_diff
+  - grid_info
+  - find_objects
+  - grid_transform
+  - test_solution
+---
+
+# Verifier
+
+## Identity
+
+You are a rigorous verification specialist for ARC-AGI puzzle solving. When given a proposed transformation rule and a set of training pairs, your job is to check whether the rule actually works — not approximately, not mostly, but exactly. You are skeptical by nature. You look for where rules break.
+
+## How You Work
+
+When the solver sends you a hypothesis to verify:
+
+### 1. Understand the Hypothesis
+
+Restate the proposed rule in your own words to confirm understanding. If the rule is ambiguous, identify the ambiguity and test the most likely interpretation, noting the alternatives.
+
+### 2. Test Each Training Pair
+
+For each training pair:
+1. Start with the input grid
+2. Mentally (or programmatically) apply the proposed rule step by step
+3. Compare your result with the expected output using `grid_diff`
+4. If using `test_solution` with a grid, provide the grid directly
+
+### 3. Report Results
+
+For each pair, report:
+- **PASS** or **FAIL**
+- If FAIL: exactly which cells are wrong (coordinates, expected value, got value)
+- If FAIL: whether the failure is systematic (same type of error across cells) or isolated
+- If FAIL: what the wrong cells suggest about the rule (e.g., "the rule works for objects of color 1 but not color 3" or "the rule works except at grid boundaries" or "the rule gets the shape right but the position is offset by 1")
+
+### 4. Overall Assessment
+
+After testing all pairs:
+- If all PASS: confirm the rule holds across all training pairs
+- If some FAIL: summarize the pattern of failures. This is the most valuable part — the failure pattern is a clue to the correct rule
+- If all FAIL: suggest what category of rule might work better based on what you observed
+
+## Verification Strategies
+
+### For geometric rules (rotation, reflection, translation):
+- Use `grid_transform` to apply the transform and then `grid_diff` to compare
+- Check edge handling — does the rule wrap, clip, or pad?
+
+### For object-level rules:
+- Use `find_objects` on both input and expected output
+- Check object-by-object: does each input object map to the right output object?
+- Pay attention to object ordering — is it by position, size, or color?
+
+### For color-mapping rules:
+- Check every cell, not just a sample
+- Look for cells where the mapping is inconsistent — these reveal conditional rules
+
+### For compositional rules:
+- Verify each step independently
+- The error might be in step 2 while step 1 is correct
+
+## Important Principles
+
+- **Never round up.** If 95% of cells match, the rule is WRONG. One wrong cell means the hypothesis needs refinement.
+- **Failures are information.** A rule that's almost right is more valuable than no rule at all. Your failure analysis helps the solver converge.
+- **Check assumptions.** If the rule says "all objects move right by 2," verify there isn't one object that moves by 3. Check every instance.
+- **Dimensional awareness.** If the rule should produce a grid of different size than the input, verify the output dimensions match expectations.
+- **Don't fix the rule.** Your job is to test, not to propose corrections. Report what's wrong and let the solver revise. (But if the fix is obvious — like "off by one in the x-direction" — you can note that.)
+
+## Self-Improvement
+
+You have universal capabilities available to you. If you find yourself repeatedly needing a verification operation that doesn't exist — like checking rotational equivalence, or testing whether a grid matches a pattern with tolerance for specific positions — create it with `create_primitive`. A purpose-built verification tool is faster and more reliable than manual cell-by-cell checking. If a category of rules needs a dedicated testing approach, you can create a specialist PO with `create_capability`.

data/templates/arc-agi-1/primitives/check_arc_data.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module PromptObjects
+  module Primitives
+    class CheckArcData < Primitive
+      DATA_DIR = File.expand_path("~/.prompt_objects/data/arc-agi-1")
+      TRAINING_DIR = File.join(DATA_DIR, "data", "training")
+      EVALUATION_DIR = File.join(DATA_DIR, "data", "evaluation")
+      REPO_URL = "https://github.com/fchollet/ARC-AGI.git"
+
+      def name
+        "check_arc_data"
+      end
+
+      def description
+        "Check if ARC-AGI-1 dataset is available locally. Returns status, paths, and setup instructions if missing."
+      end
+
+      def parameters
+        {
+          type: "object",
+          properties: {},
+          required: []
+        }
+      end
+
+      def receive(message, context:)
+        exists = Dir.exist?(TRAINING_DIR)
+
+        if exists
+          training_count = Dir.glob(File.join(TRAINING_DIR, "*.json")).length
+          eval_count = Dir.glob(File.join(EVALUATION_DIR, "*.json")).length
+
+          JSON.pretty_generate({
+            status: "available",
+            path: DATA_DIR,
+            training_tasks: training_count,
+            evaluation_tasks: eval_count,
+            training_dir: TRAINING_DIR,
+            evaluation_dir: EVALUATION_DIR
+          })
+        else
+          JSON.pretty_generate({
+            status: "missing",
+            expected_path: DATA_DIR,
+            setup_command: "git clone #{REPO_URL} #{DATA_DIR}",
+            message: "ARC-AGI-1 dataset not found. Run the setup command to download it, or ask the human to do so."
+          })
+        end
+      end
+    end
+  end
+end

data/templates/arc-agi-1/primitives/find_objects.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module PromptObjects
+  module Primitives
+    class FindObjects < Primitive
+      def name
+        "find_objects"
+      end
+
+      def description
+        "Find connected objects (same-color adjacent cells) in a grid. Returns objects with color, cell count, and bounding box."
+      end
+
+      def parameters
+        {
+          type: "object",
+          properties: {
+            grid: { type: "array", description: "2D array of integers" },
+            background: { type: "integer", description: "Background color to ignore (default: 0)" }
+          },
+          required: ["grid"]
+        }
+      end
+
+      def receive(message, context:)
+        grid = message[:grid] || message["grid"]
+        bg = message[:background] || message["background"] || 0
+
+        return "Error: grid is required" unless grid.is_a?(Array)
+        return "Error: grid is empty" if grid.empty?
+
+        rows = grid.length
+        cols = grid[0]&.length || 0
+        visited = Array.new(rows) { Array.new(cols, false) }
+        objects = []
+
+        rows.times do |r|
+          cols.times do |c|
+            next if visited[r][c] || grid[r][c] == bg
+
+            color = grid[r][c]
+            cells = []
+            queue = [[r, c]]
+            visited[r][c] = true
+
+            while (pos = queue.shift)
+              cr, cc = pos
+              cells << [cr, cc]
+              [[-1, 0], [1, 0], [0, -1], [0, 1]].each do |dr, dc|
+                nr, nc = cr + dr, cc + dc
+                next if nr < 0 || nr >= rows || nc < 0 || nc >= cols
+                next if visited[nr][nc] || grid[nr][nc] != color
+                visited[nr][nc] = true
+                queue << [nr, nc]
+              end
+            end
+
+            rs = cells.map(&:first)
+            cs = cells.map(&:last)
+            objects << {
+              color: color,
+              cells: cells.length,
+              bounds: { top: rs.min, left: cs.min, bottom: rs.max, right: cs.max }
+            }
+          end
+        end
+
+        JSON.pretty_generate({ total_objects: objects.length, objects: objects })
+      end
+    end
+  end
+end

data/templates/arc-agi-1/primitives/grid_diff.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module PromptObjects
+  module Primitives
+    class GridDiff < Primitive
+      def name
+        "grid_diff"
+      end
+
+      def description
+        "Compare two ARC grids cell by cell. Shows which cells differ with coordinates and values."
+      end
+
+      def parameters
+        {
+          type: "object",
+          properties: {
+            grid_a: { type: "array", description: "First grid (2D array)" },
+            grid_b: { type: "array", description: "Second grid (2D array)" }
+          },
+          required: ["grid_a", "grid_b"]
+        }
+      end
+
+      def receive(message, context:)
+        a = message[:grid_a] || message["grid_a"]
+        b = message[:grid_b] || message["grid_b"]
+
+        return "Error: grid_a and grid_b are required" unless a.is_a?(Array) && b.is_a?(Array)
+
+        rows_a, cols_a = a.length, a[0]&.length || 0
+        rows_b, cols_b = b.length, 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
+
+        compare_rows.times do |r|
+          compare_cols.times do |c|
+            if a[r][c] == b[r][c]
+              matching += 1
+            else
+              diffs << "(#{r},#{c}): #{a[r][c]} -> #{b[r][c]}"
+            end
+          end
+        end
+
+        total = compare_rows * compare_cols
+        lines << "#{matching}/#{total} cells match (#{diffs.length} differ)"
+
+        if diffs.empty? && rows_a == rows_b && cols_a == cols_b
+          lines << "IDENTICAL"
+        else
+          diffs.first(30).each { |d| lines << "  #{d}" }
+          lines << "  ... and #{diffs.length - 30} more" if diffs.length > 30
+        end
+
+        lines.join("\n")
+      end
+    end
+  end
+end

data/templates/arc-agi-1/primitives/grid_info.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module PromptObjects
+  module Primitives
+    class GridInfo < Primitive
+      def name
+        "grid_info"
+      end
+
+      def description
+        "Get grid dimensions, color frequencies, and density."
+      end
+
+      def parameters
+        {
+          type: "object",
+          properties: {
+            grid: { type: "array", description: "2D array of integers" }
+          },
+          required: ["grid"]
+        }
+      end
+
+      def receive(message, context:)
+        grid = message[:grid] || message["grid"]
+        return "Error: grid is required" unless grid.is_a?(Array)
+        return "Error: grid is empty" if grid.empty?
+
+        flat = grid.flatten
+        colors = flat.tally.sort.to_h
+
+        JSON.pretty_generate({
+          rows: grid.length,
+          cols: grid[0]&.length || 0,
+          total_cells: flat.length,
+          colors: colors,
+          non_background: flat.count { |c| c != 0 }
+        })
+      end
+    end
+  end
+end

data/templates/arc-agi-1/primitives/grid_transform.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module PromptObjects
+  module Primitives
+    class GridTransform < Primitive
+      def name
+        "grid_transform"
+      end
+
+      def description
+        "Apply geometric transforms to a grid: rotate_90, rotate_180, rotate_270, flip_h, flip_v, transpose."
+      end
+
+      def parameters
+        {
+          type: "object",
+          properties: {
+            grid: { type: "array", description: "2D array of integers" },
+            operation: {
+              type: "string",
+              enum: %w[rotate_90 rotate_180 rotate_270 flip_h flip_v transpose],
+              description: "Transformation to apply"
+            }
+          },
+          required: ["grid", "operation"]
+        }
+      end
+
+      def receive(message, context:)
+        grid = message[:grid] || message["grid"]
+        op = message[:operation] || message["operation"]
+
+        return "Error: grid is required" unless grid.is_a?(Array)
+        return "Error: operation is required" unless op
+
+        result = case op
+                 when "rotate_90"  then grid.transpose.map(&:reverse)
+                 when "rotate_180" then grid.reverse.map(&:reverse)
+                 when "rotate_270" then grid.transpose.reverse
+                 when "flip_h"     then grid.map(&:reverse)
+                 when "flip_v"     then grid.reverse
+                 when "transpose"  then grid.transpose
+                 else return "Error: Unknown operation '#{op}'"
+                 end
+
+        JSON.generate(result)
+      end
+    end
+  end
+end

data/templates/arc-agi-1/primitives/load_arc_task.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module PromptObjects
+  module Primitives
+    class LoadArcTask < Primitive
+      def name
+        "load_arc_task"
+      end
+
+      def description
+        "Load an ARC-AGI task from a JSON file. Returns training pairs and test inputs with grid dimensions."
+      end
+
+      def parameters
+        {
+          type: "object",
+          properties: {
+            path: {
+              type: "string",
+              description: "Path to the ARC task JSON file"
+            }
+          },
+          required: ["path"]
+        }
+      end
+
+      def receive(message, context:)
+        path = message[:path] || message["path"]
+        return "Error: path is required" unless path
+
+        expanded = File.expand_path(path)
+        return "Error: File not found: #{path}" unless File.exist?(expanded)
+
+        data = JSON.parse(File.read(expanded, encoding: "UTF-8"))
+        train = data["train"] || []
+        test = data["test"] || []
+
+        result = {
+          task_id: File.basename(expanded, ".json"),
+          training_pairs: train.length,
+          test_inputs: test.length,
+          train: train.map.with_index { |pair, i|
+            {
+              pair: i,
+              input: pair["input"],
+              output: pair["output"],
+              input_size: "#{pair["input"].length}x#{pair["input"][0].length}",
+              output_size: "#{pair["output"].length}x#{pair["output"][0].length}"
+            }
+          },
+          test: test.map.with_index { |t, i|
+            {
+              test: i,
+              input: t["input"],
+              input_size: "#{t["input"].length}x#{t["input"][0].length}"
+            }
+          }
+        }
+
+        JSON.pretty_generate(result)
+      rescue JSON::ParserError => e
+        "Error: Invalid JSON - #{e.message}"
+      rescue StandardError => e
+        "Error loading task: #{e.message}"
+      end
+    end
+  end
+end

data/templates/arc-agi-1/primitives/render_grid.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module PromptObjects
+  module Primitives
+    class RenderGrid < Primitive
+      SYMBOLS = {
+        0 => ".", 1 => "1", 2 => "2", 3 => "3", 4 => "4",
+        5 => "5", 6 => "6", 7 => "7", 8 => "8", 9 => "9"
+      }.freeze
+
+      COLOR_NAMES = {
+        0 => "black", 1 => "blue", 2 => "red", 3 => "green", 4 => "yellow",
+        5 => "grey", 6 => "magenta", 7 => "orange", 8 => "cyan", 9 => "maroon"
+      }.freeze
+
+      def name
+        "render_grid"
+      end
+
+      def description
+        "Render an ARC grid as readable text with coordinates. Background (0) shown as dots, colors 1-9 as digits."
+      end
+
+      def parameters
+        {
+          type: "object",
+          properties: {
+            grid: {
+              type: "array",
+              description: "2D array of integers 0-9"
+            },
+            label: {
+              type: "string",
+              description: "Optional label to display above the grid"
+            }
+          },
+          required: ["grid"]
+        }
+      end
+
+      def receive(message, context:)
+        grid = message[:grid] || message["grid"]
+        label = message[:label] || message["label"]
+
+        return "Error: grid is required" unless grid.is_a?(Array)
+        return "Error: grid is empty" if grid.empty?
+
+        rows = grid.length
+        cols = grid[0]&.length || 0
+        lines = []
+
+        lines << label if label
+        lines << "#{rows}x#{cols}"
+
+        # Column headers
+        col_header = "   " + (0...cols).map { |c| c.to_s.rjust(2) }.join
+        lines << col_header
+        lines << "   " + "--" * cols
+
+        # Rows with line numbers
+        grid.each_with_index do |row, r|
+          cells = row.map { |v| (SYMBOLS[v] || "?").rjust(2) }.join
+          lines << "#{r.to_s.rjust(2)}|#{cells}"
+        end
+
+        # Color legend for non-background colors present
+        present = grid.flatten.uniq.sort - [0]
+        unless present.empty?
+          legend = present.map { |c| "#{c}=#{COLOR_NAMES[c]}" }.join(", ")
+          lines << ""
+          lines << "Colors: #{legend}"
+        end
+
+        lines.join("\n")
+      end
+    end
+  end
+end