FileSystemProgramArtifactStore

Models & Types · AiDotNet.Evolution.Programs.ArtifactStore

An artifact store that keeps small content in a per-genome index and large content in its own file.

Implements: IProgramArtifactStore

For Beginners

Create one with a directory, hand it to whatever scores your candidate programs, and everything they print or write is filed under the program’s fingerprint. After the run, call GetAsync(genomeId) to read the output of any candidate the run recorded, or ListAsync first to see what is there without loading it. Call PurgeAsync(DateTimeOffset.UtcNow) occasionally to delete anything older than the retention period so a long-running search does not fill the disk.

How It Works

Each genome gets one directory under the store root containing index.json and, for artifacts larger than InlineSizeThresholdBytes, one file per artifact. That split is the reference OpenEvolve behaviour (openevolve/database.py``store_artifacts): content at or below the threshold is serialized into the record and anything larger is written to a per-program directory. Both tiers are durable here, so retrieval by genome identifier keeps working after the run that produced them has exited - which is the whole point, because that is when the output is read.

Three things are deliberately stronger than the reference. Writes are atomic: the index is written to a temporary file, flushed to disk, and swapped into place, so a crash leaves the previous index rather than a torn one. Retention operates on the same root the writes go to, whereas upstream writes artifacts under db_path/artifacts - or the working directory when db_path is unset, which is the default - while its cleanup pass looks under <checkpoint>/artifacts, so by default nothing it wrote is ever expired. And every input is bounded: names are sanitized to a safe file name, oversized content is truncated and flagged, and a genome that would exceed its artifact count or byte budget is rejected rather than silently trimmed.

Artifact content is untrusted. Nothing here executes, interprets, or renders it; it is written as opaque bytes under a sanitized name that cannot escape the store root. All operations are serialized through one lock, so a single instance may be shared by concurrent callers, and the asynchronous signatures complete synchronously.

Constructors

Constructor Summary
FileSystemProgramArtifactStore(string rootDirectory, ProgramArtifactStoreOptions options) Initializes a file-backed artifact store, creating the root directory when it does not exist.

Properties

Property Summary
string RootDirectory { get; } Gets the absolute path of the directory that holds one subdirectory per genome.

Methods

Method Summary
ProgramArtifactStoreOptions GetOptions() Gets an independent copy of the limits this store was validated with.
Task<IReadOnlyList<ProgramArtifact>> GetAsync(string genomeId, CancellationToken cancellationToken)
Task<IReadOnlyList<ProgramArtifactDescriptor>> ListAsync(string genomeId, CancellationToken cancellationToken)
Task<IReadOnlyList<ProgramArtifactDescriptor>> StoreAsync(string genomeId, IEnumerable<ProgramArtifact> artifacts, CancellationToken cancellationToken)
Task<ProgramArtifact> GetAsync(string genomeId, string name, CancellationToken cancellationToken)
Task<bool> RemoveAsync(string genomeId, CancellationToken cancellationToken)
Task<int> PurgeAsync(DateTimeOffset utcNow, CancellationToken cancellationToken)
string GetGenomeDirectory(string genomeId) Computes the directory this store uses for one genome, whether or not it exists.

Fields

Field Summary
string IndexFileName The name of the per-genome index document.