Crate eligo 

eligo — I choose (Latin)

Best-of-N image generation that selects the best candidate by a measurable reward, rather than returning a single one-shot result.

eligo is Latin for “I pick out / I choose” — the root of elect and elite. Choosing is the tool’s one job. Where revelo reveals and viser sees, eligo chooses: given a prompt, it generates n candidate images through a Backend, scores each against the prompt with a Scorer (the reward), and returns the highest-scoring one. An optional bounded re-roll replaces the single worst candidate once. That generate → score → select loop is the smallest honest agentic pattern: a numeric reward drives a decision.

Scope (deliberately bounded)

eligo is a selection library, not a model zoo or an editor. It owns the loop and the contracts (Backend, Scorer); concrete model inference (a Stable Diffusion backend, and CLIP scoring via ONNX Runtime) are pluggable implementations behind those traits. The default build ships a deterministic mock backend/scorer so the loop is testable without model weights.

use eligo::{best_of_n, GenerateConfig};
use eligo::mock::{MockBackend, MockScorer};

let backend = MockBackend::default();
let scorer = MockScorer;
let cfg = GenerateConfig::new("a red bicycle").with_candidates(4);
let selection = best_of_n(&backend, &scorer, &cfg).unwrap();
assert_eq!(selection.all.len(), 4);
// The chosen candidate is the highest-scoring one.
let top = selection.all.iter().map(|c| c.score).fold(f32::MIN, f32::max);
assert!((selection.best().score - top).abs() < f32::EPSILON);

Modules

mock

Deterministic mock Backend and Scorer for tests and demos.

Structs

Candidate

One generated image together with the seed that produced it and its reward.

GenerateConfig

Inputs to crate::best_of_n.

Image

A generated raster image: RGB8, row-major, width * height * 3 bytes.

QualityScorer

A Scorer that rates image quality alone, ignoring the prompt.

QualityWeighted

Wraps a base Scorer (e.g. CLIP alignment) and blends in the no-reference quality score: score = (1 - weight) * base + weight * quality.

Selection

The outcome of crate::best_of_n: every candidate considered, plus the index of the chosen one.

Enums

Error

Errors that can arise while generating or selecting candidates.

RerollPolicy

How to spend a second round of generation, if any.

Traits

Backend

A source of generated images.

Scorer

Scores how well a generated image satisfies the prompt.

Functions

best_of_n

Generate cfg.candidates images, score each against the prompt, and return the highest-scoring one along with the full set considered.

cosine_similarity

Cosine similarity of two equal-length vectors, in [-1, 1].

l2_normalize

L2-normalize a vector in place. A zero vector is left unchanged (its norm is zero, so there is nothing to scale).

quality_score

No-reference quality of an image, in [0, 1] (higher = sharper / cleaner).

Type Aliases

Result

Convenience alias for results in this crate.