Sim::AgentSoar
Sim::AgentSoar is a SOAR-inspired explicit search architecture with a pluggable Large Language Model (LLM) worker.
It separates deterministic search control from heuristic proposal, allowing a local LLM (via Ollama) to guide operator selection without compromising structural integrity.
Overview
Sim::AgentSoar implements:
- Explicit state-space search
- Best-first ordering (metric, then depth)
- Configurable branching factor
- Optional bounded regression correction
- Deterministic state validation
- Instrumented runtime statistics
- Pluggable LLM proposal layer
The included domain is a simple integer reachability problem used for calibration and experimentation.
Architecture
The system is divided into:
- Engine — deterministic environment logic
- Search — explicit search controller
- Worker — LLM-backed operator proposer
- Node — structured search state
The LLM never evaluates states or controls search order. It only proposes candidate operators.
All correctness guarantees remain deterministic.
Requirements
- Perl 5.14+
- Ollama installed locally
- A local model (default:
llama3.2:1b)
The Ollama daemon must be running:
ollama serve
Example
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,
);
my $path = $search->run(
start => 4,
target => 19,
);
if ($path) {
print "Solution found\n";
}
Design Philosophy
Sim::AgentSoar is built around three principles:
- Structural recursion belongs in the search tree.
- Heuristic reasoning belongs in the LLM.
- Determinism must never depend on the LLM.
This separation prevents heuristic instability from corrupting the search backbone.
License
GPL v3
Author: Gian Luca Brunetti, 2026 - gianluca.brunetti@gmail.com