Module: braid.optimizer

BRAID-aware optimizer for DSPy.

class braid.optimizer.GRDMetrics

Bases: object

Metrics for evaluating GRD quality.

Includes both structural metrics and BRAID protocol compliance metrics: - Structural validity - Completeness - Execution traceability - Atomicity (token density) - Masking compliance - Procedural scaffolding

static structural_validity(grd: str) → float

Evaluate structural validity of a GRD.

Returns:

Score between 0.0 and 1.0 (1.0 = perfectly valid)

static completeness(grd_structure: GRDStructure) → float

Evaluate completeness of a GRD (has start, end, reasonable number of steps).

Returns:

Score between 0.0 and 1.0

static execution_traceability(grd_structure: GRDStructure) → float

Evaluate how traceable/executable the GRD is.

Returns:

Score between 0.0 and 1.0

static atomicity_score(grd_structure: GRDStructure, max_tokens: int = 15) → float

Evaluate node atomicity (token density) compliance.

According to BRAID research, nano-scale models perform best when node labels contain fewer than 15 tokens.

Parameters:

• grd_structure – Parsed GRD structure

• max_tokens – Maximum tokens allowed per node

Returns:

Score between 0.0 and 1.0 (1.0 = all nodes within limit)

static masking_compliance(grd: str) → float

Evaluate compliance with numerical masking protocol.

Detects potential answer leakage where computed values appear in node labels.

Parameters:

grd – Mermaid GRD code

Returns:

Score between 0.0 and 1.0 (1.0 = no leakage detected)

static procedural_scaffolding_score(grd: str) → float

Evaluate adherence to procedural scaffolding rules.

Good GRDs describe HOW to solve, not WHAT the answer is.

Parameters:

grd – Mermaid GRD code

Returns:

Score between 0.0 and 1.0

static overall_quality(grd: str, grd_structure: GRDStructure | None = None) → float

Calculate overall GRD quality score.

Parameters:

• grd – Mermaid code string

• grd_structure – Optional pre-parsed structure

Returns:

Overall quality score between 0.0 and 1.0

static detailed_quality_report(grd: str, grd_structure: GRDStructure | None = None) → Dict[str, float]

Get a detailed breakdown of all quality metrics.

Parameters:

• grd – Mermaid code string

• grd_structure – Optional pre-parsed structure

Returns:

Dictionary with all individual metric scores

class braid.optimizer.BraidOptimizer(*args, **kwargs)

Bases: Module

BRAID-aware optimizer for DSPy.

This optimizer extends DSPy’s optimization capabilities by: 1. Optimizing GRD generation quality 2. Optimizing step-by-step execution 3. Providing GRD-specific metrics

__init__(base_optimizer: Module | None = None, grd_quality_weight: float = 0.5, execution_quality_weight: float = 0.5)

Initialize the BRAID optimizer.

Parameters:

• base_optimizer – Base DSPy optimizer to use (e.g., MIPROv2)

• grd_quality_weight – Weight for GRD quality in optimization

• execution_quality_weight – Weight for execution quality in optimization

optimize(module: BraidReasoning, trainset: List[Dict[str, Any]], metric: Callable | None = None, num_threads: int = 1) → BraidReasoning

Optimize a BraidReasoning module.

Parameters:

• module – The BraidReasoning module to optimize

• trainset – Training examples with ‘problem’ and optionally ‘answer’ keys

• metric – Optional custom metric function

• num_threads – Number of threads for parallel optimization

Returns:

Optimized BraidReasoning module

evaluate(module: BraidReasoning, testset: List[Dict[str, Any]], metric: Callable | None = None) → Dict[str, float]

Evaluate a BraidReasoning module on a test set.

Parameters:

• module – The BraidReasoning module to evaluate

• testset – Test examples with ‘problem’ and optionally ‘answer’ keys

• metric – Optional custom metric function

Returns:

Dictionary of evaluation metrics