Template Evolution
Template Evolution is a self-updating code template feature: when a DAG step completes with a high Critic score, BioCortex saves that code as a stable template for the same (skill, step). On the next run, the Executor reuses the template and only adapts paths and parameters, instead of generating code from scratch. This reduces repeated failures (e.g. API version mismatches) and improves success rates for the same workflow over time.How It Works
- During execution — For each DAG node, the Executor checks whether a stable template exists for the current task’s matched skill and step name. If yes, it injects that template into the prompt and instructs the model to use it and only adapt paths/params.
- After a step passes — If the step completes successfully and the Critic score is ≥ the threshold (default 0.9), the Orchestrator saves:
- The executed code
- The score and timestamp
- An optional environment snapshot (e.g.
scanpy,squidpy,anndata,numpyversions) to the template repository, keyed by(skill_id, step_name).
- Next run — The same analysis type matches the same skill; the same step names come from the Planner. The Executor loads the stored template and prefers it, so that step “does not re-optimize” and reuses the previously validated code.
Configuration
| Option | Default | Description |
|---|---|---|
template_evolution.enabled | true | Turn template evolution on or off. |
template_evolution.score_threshold | 0.9 | Only record and reuse templates when Critic score ≥ this value. |
template_evolution.storage_dir | data/template_evolution | Directory where (skill_id, step_name).json files are stored. |
template_evolution.capture_env | true | Whether to record library versions (scanpy, squidpy, etc.) when saving a template. |
Environment Variables
You can override without changing code:| Variable | Example | Description |
|---|---|---|
BIOCORTEX_TEMPLATE_EVOLUTION | false | Disable template evolution. |
BIOCORTEX_TEMPLATE_THRESHOLD | 0.9 | Score threshold (0.0–1.0). |
BIOCORTEX_TEMPLATE_STORAGE_DIR | data/template_evolution | Storage directory for template JSON files. |
Storage Format
Each template is stored as a JSON file understorage_dir, with a filename derived from skill_id and step_name (e.g. anndata_load_and_qc_spatial_data.json). Contents include:
skill_id,step_namecode— the executed code that passed validationscore— Critic scoreenv_snapshot— optional dict of library versionstimestamp— when it was saved
(skill_id, step_name) is kept; a new run overwrites only if its score is ≥ the existing one.
When to Use It
- Recommended for workflows you run often (e.g. spatial transcriptomics SVG detection, single-cell QC + clustering). After a few successful runs with score ≥ 0.9, those steps will reuse stable code and run faster and more reliably.
- Optional to disable (e.g.
BIOCORTEX_TEMPLATE_EVOLUTION=false) if you want every run to generate fresh code, or while debugging template behavior.
Relation to Other Features
- Self-Correction — Runs first (reflection + retry). Template evolution only records code after a step has passed validation. If a step keeps failing, Self-Correction keeps trying; once it passes with score ≥ 0.9, the template is saved.
- SKILL / workflows — The matched skill comes from the task description (same as Planner/Executor). Step names come from the DAG (Planner output). So the same “analysis type” and “step name” consistently map to the same template key.
docs/CODE_OPTIMIZER_PLAN.md.