BRAID-DSPy Integration Guide

Overview

BRAID-DSPy integrates seamlessly with the DSPy framework, providing structured reasoning capabilities through Guided Reasoning Diagrams (GRD).

Installation

pip install braid-dspy

Basic Integration

1. Configure DSPy

First, configure DSPy with your language model:

import dspy

# For OpenAI
lm = dspy.OpenAI(model="gpt-4", api_key="your-api-key")
dspy.configure(lm=lm)

# For other providers, use appropriate DSPy LM class

2. Use BRAID Module

from braid import BraidReasoning

braid = BraidReasoning()
result = braid(problem="Your problem here")

Advanced Integration

Using with DSPy Optimizers

BRAID works with DSPy’s optimization framework:

from braid import BraidReasoning, BraidOptimizer
from dspy.teleprompt import MIPROv2

# Create base optimizer
base_optimizer = MIPROv2()

# Create BRAID optimizer
braid_optimizer = BraidOptimizer(base_optimizer=base_optimizer)

# Optimize
optimized_braid = braid_optimizer.optimize(braid, trainset)

Custom Signatures

You can use BRAID signatures in your own DSPy modules:

from braid.signatures import BraidPlanSignature
import dspy

class MyModule(dspy.Module):
    def __init__(self):
        super().__init__()
        self.plan = dspy.Predict(BraidPlanSignature)
    
    def forward(self, problem):
        result = self.plan(problem=problem)
        return result.grd

Combining with Other DSPy Modules

BRAID modules can be combined with other DSPy modules:

import dspy
from braid import BraidReasoning

class ComplexPipeline(dspy.Module):
    def __init__(self):
        super().__init__()
        self.braid = BraidReasoning()
        self.validator = dspy.Predict("answer -> validated_answer")
        self.formatter = dspy.Predict("answer -> formatted_output")
    
    def forward(self, problem):
        # Use BRAID for reasoning
        braid_result = self.braid(problem=problem)
        
        # Validate answer
        validated = self.validator(answer=braid_result.answer)
        
        # Format output
        formatted = self.formatter(answer=validated.validated_answer)
        
        return formatted

Best Practices

1. GRD Generation

Use use_generator=True for better GRD quality
Provide problem_type hints when possible
Use pre-generated GRDs for consistent results

2. Validation

Always enable validate_grd=True in production
Check result.valid before using results
Handle errors gracefully

3. Optimization

Use BRAID optimizer with base optimizer for best results
Provide diverse training examples
Monitor GRD quality metrics

4. Error Handling

from braid import BraidReasoning

braid = BraidReasoning()

try:
    result = braid(problem="Your problem")
    if result.valid:
        # Use result
        print(result.answer)
    else:
        # Handle invalid result
        print(f"Error: {result.error}")
except Exception as e:
    # Handle exception
    print(f"Exception: {e}")

Performance Considerations

GRD Generation: First call may be slower due to GRD generation
Caching: Consider caching GRDs for repeated problems
Execution Steps: Limit max_execution_steps for faster execution
Parallel Processing: Use num_threads in optimizer for parallel optimization

Troubleshooting

Common Issues

LM Not Configured: Ensure DSPy is configured with dspy.configure(lm=...)
Invalid GRD: Check GRD syntax, enable validation
Execution Errors: Check execution_trace for step-by-step errors
Import Errors: Ensure all dependencies are installed

Debugging

Enable verbose output:

import logging
logging.basicConfig(level=logging.DEBUG)

# Your BRAID code here

Check execution trace:

result = braid(problem="Your problem")
for trace in result.execution_trace:
    print(trace)

Migration Guide

From Standard DSPy

If you’re using standard DSPy modules:

Replace dspy.ChainOfThought with BraidReasoning
Update result handling to use BraidResult
Add GRD validation where needed

Example Migration

Before:

import dspy

class MyModule(dspy.Module):
    def __init__(self):
        super().__init__()
        self.reasoning = dspy.ChainOfThought("problem -> answer")
    
    def forward(self, problem):
        return self.reasoning(problem=problem)

After:

from braid import BraidReasoning

class MyModule(dspy.Module):
    def __init__(self):
        super().__init__()
        self.reasoning = BraidReasoning()
    
    def forward(self, problem):
        result = self.reasoning(problem=problem)
        return result.answer