overlay
diapason.skills.overlay
¶
SkillOverlay — sidecar storage for optimization output (Plan 2A).
Optimization results from DSPy/GEPA are written to
~/.diapason/learning/skills/<skill-name>/optimized.toml. This module
provides a small loader and writer for that overlay format.
The overlay is a strict TOML file with a single [optimized] section
followed by zero or more [[optimized.few_shot]] array tables.
Example:
[optimized]
skill_name = "research-and-summarize"
optimizer = "dspy"
optimized_at = "2026-04-08T14:30:00Z"
trace_count = 47
description = "Search the web for a topic and produce a structured summary"
[[optimized.few_shot]]
input = "transformer attention mechanisms"
output = "## Recent Advances ..."
SkillOverlay
dataclass
¶
A single optimization overlay for one skill.
SkillOverlayLoader
¶
Read overlay files from a sidecar directory tree.
Layout: <root>/<skill-name>/optimized.toml
load(skill_name)
¶
Load the overlay for skill_name.
Returns None if the overlay file is missing or malformed.
Never raises — bad overlay files should not break skill loading.
write_overlay(overlay, root)
¶
Write overlay to <root>/<skill-name>/optimized.toml.
Creates the directory structure if needed. Returns the path written.