Skip to content

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.