Evolution API Reference

Run a complete skill evolution cycle.

Workflow: load/create baseline -> iterate (Proposer generates candidates -> CandidateEvaluator scores them) -> finalize with best version.

Parameters:

Name	Type	Description	Default
config	EvolutionRunConfig	Evolution run configuration.	required
trajectory_store	Any	TrajectoryStore instance for feedback data.	required
workspace_mgr	Any	WorkspaceManager for creating evaluation workspaces.	required
pes_factory	Callable[[str, WorkspaceHandle], Any]	Factory (pes_name, workspace) -> PES for evaluation.	required
evaluator_fn	Callable[[str, str, str], float]	Scoring function (question, predicted, truth) -> float.	required
source_project_root	Path	Project root containing skills/ directory.	required
llm_client	Any	LLM client for the Proposer.	required
version_store	SkillVersionStore | None	Optional SkillVersionStore (defaults to global path).	None

Returns:

Type	Description
EvolutionRunRecord	EvolutionRunRecord with status, scores, and best version ID.

promote — write an evaluated SkillVersion back to the project's skills/ directory.

Reference: docs/superpowers/specs/2026-04-17-scrivai-m2-design.md §5.5

promote(version_id, source_project_root, version_store=None, backup=True)

Atomically write a skill version's content back to the project.

Parameters:

Name	Type	Description	Default
version_id	str	ID of the version to promote.	required
source_project_root	Path	Project root path.	required
version_store	SkillVersionStore | None	SkillVersionStore instance (defaults to global path).	None
backup	bool	If True, back up current content before overwriting.	True

Returns:

Type	Description
Path	Path to the backup directory (if backup=True) or the new skill
Path	directory (if backup=False).

Pulls feedback from trajectory.feedback, scores with the evaluator, and splits into train/hold_out.

Parameters:

Name	Type	Description	Default
trajectory_store	TrajectoryStore	TrajectoryStore instance providing get_feedback_pairs/get_run.	required
pes_name	str	Target PES name used to filter feedback records.	required
skill_name	str	Skill name (currently an identifier field used by the caller).	required
evaluator_fn	Callable[[str, str, str], float]	Scoring function (question, predicted, ground_truth) -> float in [0, 1].	required
min_confidence	float	Minimum feedback quality threshold; records below this are filtered out.	0.7
failure_threshold	float	baseline_score below this value is treated as a failure sample for train.	0.5

has_enough_data(min_samples=10)

Check whether enough feedback samples have been accumulated.

Parameters:

Name	Type	Description	Default
min_samples	int	Minimum sample count threshold.	10

Returns:

Type	Description
bool	True if the sample count meets the threshold and evolution can be triggered.

collect_failures(hold_out_ratio=0.3, random_seed=42)

Fetch feedback, score samples, and split into train/hold_out.

Steps: 1. Pull feedback pairs from TrajectoryStore that meet min_confidence. 2. Try to load the corresponding trajectory and extract truncated phase summaries (silently skip if get_run fails). 3. Call evaluator_fn to compute baseline_score. 4. Shuffle with a fixed random seed, then split by hold_out_ratio. 5. Keep only samples with baseline_score < failure_threshold in the train set.

Parameters:

Name	Type	Description	Default
hold_out_ratio	float	Fraction of total samples for hold_out in [0.0, 1.0).	0.3
random_seed	int	Random seed to guarantee reproducible results for the same parameters.	42

Returns:

Type	Description
tuple[list[FailureSample], list[FailureSample]]	Tuple (train_failures, hold_out_samples) of two FailureSample lists.

LLM-based candidate SKILL.md generator.

propose(current_skill_snapshot, failures, rejected_proposals, n=3, budget=None) async

Generate N candidate SKILL.md revisions from failure samples.

Parameters:

Name	Type	Description	Default
current_skill_snapshot	dict[str, str]	Current SKILL.md content snapshot {"SKILL.md": ...}.	required
failures	list[FailureSample]	List of failure samples.	required
rejected_proposals	list[EvolutionProposal]	Previously rejected candidates (to avoid repeating directions).	required
n	int	Expected number of candidate proposals.	3
budget	LLMCallBudget | None	LLM call budget guard (optional).	None

Returns:

Type	Description
list[EvolutionProposal]	List of EvolutionProposal with length >= 1.

Raises:

Type	Description
ProposerError	If parsing still fails after retries or no valid candidates remain.
BudgetExceededError	If the budget is exceeded.

Replays the real PES with a candidate SkillVersion on hold-out samples and scores it.

Workflow: 1. Copytree the source project_root to a temp directory, replacing the target skill content. 2. For each hold-out sample: create workspace -> instantiate PES -> run -> score. 3. Each sample consumes 3 LLM budget units. 4. A single-sample failure yields score=0.0 without affecting other samples. 5. The finally block cleans up the temp directory.

__init__(workspace_mgr, pes_factory, evaluator_fn, source_project_root, budget)

Initialise CandidateEvaluator.

Parameters:

Name	Type	Description	Default
workspace_mgr	Any	WorkspaceManager instance.	required
pes_factory	Callable[[str, WorkspaceHandle], Any]	Factory (pes_name, workspace) -> PES instance.	required
evaluator_fn	Callable[[str, str, str], float]	Scoring function (question, predicted, ground_truth) -> float.	required
source_project_root	Path	Source project root directory path.	required
budget	LLMCallBudget	LLM call budget guard.	required

evaluate(version, hold_out) async

Evaluate a candidate SkillVersion on hold-out samples.

Parameters:

Name	Type	Description	Default
version	SkillVersion	Candidate version to evaluate.	required
hold_out	list[FailureSample]	List of hold-out samples.	required

Returns:

Type	Description
EvolutionScore	EvolutionScore with total score, per-sample scores, and budget consumed.

Encapsulates the skill_versions / evolution_runs / evolution_scores tables in evolution.db.

Tracks and enforces the maximum LLM call count for a single run_evolution call.

consume(n=1)

Consume n LLM calls; raises BudgetExceededError if the budget would be exceeded.