File Coverage

blib/lib/Sim/AgentSoar/Engine.pm
Criterion Covered Total %
statement 6 21 28.5
branch 0 14 0.0
condition 0 3 0.0
subroutine 2 6 33.3
pod 4 4 100.0
total 12 48 25.0


line stmt bran cond sub pod time code
1             package Sim::AgentSoar::Engine;
2              
3 1     1   6 use strict;
  1         2  
  1         42  
4 1     1   5 use warnings;
  1         19  
  1         422  
5              
6             our $VERSION = '0.06';
7              
8             our @ALLOWED_OPERATORS = qw(
9             add_1
10             sub_1
11             add_3
12             sub_3
13             mul_2
14             div_2_if_even
15             );
16              
17             our $MIN_VALUE = -100;
18             our $MAX_VALUE = 100;
19              
20             sub allowed_operators
21             {
22 0     0 1   return @ALLOWED_OPERATORS;
23             }
24              
25             sub apply_operator
26             {
27 0     0 1   my ($class, $value, $op) = @_;
28              
29 0 0         return $value + 1 if $op eq 'add_1';
30 0 0         return $value - 1 if $op eq 'sub_1';
31 0 0         return $value + 3 if $op eq 'add_3';
32 0 0         return $value - 3 if $op eq 'sub_3';
33 0 0         return $value * 2 if $op eq 'mul_2';
34              
35 0 0         if ($op eq 'div_2_if_even')
36             {
37 0 0         return undef unless $value % 2 == 0;
38 0           return int($value / 2);
39             }
40              
41 0           return undef;
42             }
43              
44             sub valid_value
45             {
46 0     0 1   my ($class, $value) = @_;
47              
48 0   0       return defined($value)
49             && $value >= $MIN_VALUE
50             && $value <= $MAX_VALUE;
51             }
52              
53             sub metric
54             {
55 0     0 1   my ($class, $value, $target) = @_;
56 0           return abs($value - $target);
57             }
58              
59             1;
60              
61              
62             =pod
63              
64             =head1 NAME
65              
66             Sim::AgentSoar::Engine - Deterministic calibration environment for heuristic AgentSoar
67              
68             =head1 DESCRIPTION
69              
70             Sim::AgentSoar::Engine defines a minimal deterministic environment used to
71             calibrate and evaluate the Sim::AgentSoar architecture.
72              
73             The domain consists of integer reachability under a fixed set of operators.
74             Although simple, it is intentionally chosen to expose core AgentSoar dynamics:
75              
76             =over 4
77              
78             =item * Local vs. global improvement tension
79              
80             =item * Reversible and irreversible operations
81              
82             =item * Potential regression
83              
84             =item * Cycles and repetition
85              
86             =item * Heuristic bias evaluation
87              
88             =back
89              
90             This module contains no probabilistic logic and no LLM interaction.
91             All state transitions and evaluations are deterministic.
92              
93             =head2 Domain Definition
94              
95             State:
96              
97             value => integer
98              
99             Operators:
100              
101             add_1
102             sub_1
103             add_3
104             sub_3
105             mul_2
106             div_2_if_even
107              
108             Evaluation metric:
109              
110             abs(value - target)
111              
112             Domain bounds:
113              
114             -100 <= value <= 100
115              
116             =head2 Purpose
117              
118             The integer domain serves as:
119              
120             =over 4
121              
122             =item * A calibration environment for testing heuristic quality
123              
124             =item * A controlled benchmark for branching and correction logic
125              
126             =item * A deterministic substrate for measuring LLM efficiency
127              
128             =item * A regression testing environment for architectural changes
129              
130             =back
131              
132             Because the environment is fully observable and inexpensive to evaluate,
133             it allows clear separation between structural AgentSoar performance and
134             heuristic proposal behavior.
135              
136             =head2 ReAgentSoar Role
137              
138             In the broader reAgentSoar program, this module acts as:
139              
140             =over 4
141              
142             =item * A wind-tunnel model for cognitive architecture experiments
143              
144             =item * A baseline for comparing deterministic and LLM-guided AgentSoar
145              
146             =item * A controlled testbed for future memory-layer extensions
147              
148             =back
149              
150             The simplicity of the domain is intentional: it isolates architectural
151             effects from domain complexity.
152              
153             =head1 METHODS
154              
155             =head2 allowed_operators
156              
157             Returns the list of valid operators.
158              
159             =head2 apply_operator
160              
161             Applies an operator to a state value.
162              
163             =head2 valid_value
164              
165             Ensures state remains within domain bounds.
166              
167             =head2 metric
168              
169             Computes distance to target.
170              
171             =head1 AUTHOR
172              
173             Gian Luca Brunetti (2026), gianluca.brunetti@gmail.com
174              
175             =cut
176