ProgramRunOutputObserver

Models & Types · AiDotNet.Evolution.Programs.Outputs

Writes the best program to disk at every checkpoint and once more when the run stops.

Implements: IEvolutionObserver<ProgramGenome>

For Beginners

Hand this to the evolution engine as its observer and your run will leave the winning program on disk instead of only in memory - a copy at every checkpoint under checkpoints/checkpoint_1/, checkpoint_2/ and so on, and the final answer under best/. The one wiring step is registering the archives, which you do inside the archive factory you already pass to the engine so the observer knows where to look for the best program.

How It Works

The reference OpenEvolve controller performs these writes inside the engine: _save_checkpoint is called from the evolution loop and _save_best_program from the end of run. Here the same two writes are driven from outside, through the observer stream the engine already publishes - a Checkpointed event triggers the snapshot and a Stopped event triggers the final write - so run output is a component a caller opts into rather than behaviour welded into the search.

The observer needs the archives to answer “which program is best”, because a checkpoint event carries no candidate. Register them with AddArchive from the archive factory the engine is constructed with, or pass them to the constructor when they already exist. The winner is chosen exactly as Best chooses it: best quality in the archive’s own optimisation direction, ties broken by canonical genome identity, so the answer does not depend on island ordering or timing.

Write failures never stop a run. The engine already isolates observer exceptions, but silently losing the output is worse than losing it loudly, so a failed write is recorded in LastError and the run continues; a caller that cares can assert on it after the run. The observer holds no unbounded state: it keeps one record per write, and records never contain program text.

Constructors

Constructor Summary
ProgramRunOutputObserver(ProgramRunOutputWriter writer, IEnumerable<IEvolutionArchiveView<ProgramGenome>> archives) Initializes an observer.

Properties

Property Summary
IReadOnlyList<ProgramRunOutputRecord> Records { get; } Gets the records of every write this observer has made, in order.
ProgramRunOutputRecord LastRecord { get; } Gets the most recent write, or null when nothing has been written.
long ProgramsWritten { get; } Gets how many per-candidate program files this observer has written.
string LastError { get; set; } Gets a bounded description of the most recent failed write, or null when none has failed.

Methods

Method Summary
EvolutionArchiveEntry<ProgramGenome> SelectBest() Selects the globally best archived program using quality then canonical identity.
ProgramRunOutputRecord WriteNow(string note) Writes the current best program immediately, outside the observer event stream.
ValueTask OnEventAsync(EvolutionEvent<ProgramGenome> evolutionEvent, CancellationToken cancellationToken)
void AddArchive(IEvolutionArchiveView<ProgramGenome> archive) Registers one archive the observer reads the best program from.