NAME
Sim::AgentSoar::AgentSoar - Explicit SOAR-inspired search controller with LLM-guided operator selection
SYNOPSIS
use Sim::AgentSoar::AgentSoar;
use Sim::AgentSoar::Worker;
my $worker = Sim::AgentSoar::Worker->new(
model => 'llama3.2:1b',
);
my $search = Sim::AgentSoar::AgentSoar->new(
worker => $worker,
branching_factor => 2,
regression_tolerance => 2,
max_depth => 20,
);
my $path = $search->run(
start => 4,
target => 19,
);DESCRIPTION
Sim::AgentSoar::AgentSoar implements an explicit state-space search architecture inspired by the classical SOAR cognitive model, but reinterpreted with modern LLM-assisted heuristic control. Indeed, the model substitute the flat, uplfront planning mode of LLMs with a Soar-like Subgoalling approach. The last Lisp implementation, Soar 5.0, has been taken as a reference.
The architecture strictly separates:
Structural recursion (search tree expansion)
Deterministic evaluation (Engine)
Heuristic proposal (Worker / LLM)
Optional bounded local correction
Unlike purely LLM-driven agents, this module preserves deterministic control over state validation, search ordering, and termination criteria. The LLM is never allowed to:
Evaluate goal satisfaction
Modify search ordering
Override state validity
Introduce nondeterministic structural changes
This guarantees that heuristic instability cannot corrupt the search backbone.
AgentSoar Model
The search procedure maintains:
An OPEN list ordered by (metric, depth)
A VISITED set preventing state repetition
A bounded branching factor
Optional regression tolerance logic
Each node expansion proceeds as follows:
- 1. The Worker proposes an operator.
- 2. The Engine deterministically applies and evaluates the operator.
- 3. If regression exceeds tolerance, a single correction pass is allowed.
- 4. Valid child nodes are inserted into OPEN.
The recursion is structural (tree-based), not narrative.
Instrumentation
The module records runtime statistics accessible via stats():
{
nodes_expanded => ...,
children_created => ...,
llm_calls => ...,
corrections => ...,
}This supports empirical evaluation of heuristic efficiency.
CONSTRUCTOR
new
my $search = Sim::AgentSoar::AgentSoar->new(
worker => $worker, # required
branching_factor => 2, # default 1
regression_tolerance => 2, # optional
max_depth => 20, # default 20
);METHODS
run
my $path = $search->run(
start => $start,
target => $target,
);Executes the search and returns an array reference describing the solution path, or undef if no solution is found within constraints.
stats
Returns a hash reference of runtime statistics.
RESEARCH NOTES
This implementation explores a hybrid model:
Explicit symbolic search
LLM-guided operator selection
Bounded internal recursion (correction stage)
Deterministic invariants
The design intentionally avoids letting the LLM control topology. All structural evolution must occur through explicit, measurable mechanisms.
AUTHOR
Gian Luca Brunetti (2026), gianluca.brunetti@gmail.com
AI tools were used to accelerate drafting and refactoring. No changes were merged without human review; the maintainer remains the sole accountable party for correctness, security, and licensing compliance.