DSPy Development

This skill provides comprehensive guidance for working with the DSPy framework, especially within the AgenticFleet context.

Environment Setup

This skill requires uv as the Python package manager. Always ensure a uv virtual environment is active before running any DSPy code.

# Create and activate a uv virtual environment
uv venv
source .venv/bin/activate

# Install dspy
uv pip install dspy

Rule: Never use raw pip or python -m pip. Always use uv pip for package installation and uv run for script execution.

Quick Start

Creating a new signature

import dspy

class MySignature(dspy.Signature):
    """Input and output fields with descriptions."""
    input_field = dspy.InputField(desc="Description of input")
    output_field = dspy.OutputField(desc="Description of output")

Compiling a program

# Use the compile-dspy script for safe compilation
uv run scripts/compile-dspy.py --module my_module --teleprompter teleprompter_name

Optimizing with metrics

# Use the optimize-dspy script for optimization
uv run scripts/optimize-dspy.py --module my_module --metric my_metric --examples examples.jsonl

When to Use This Skill

Use this skill when:

• Creating or modifying DSPy signatures
• Building new DSPy programs or modules
• Running DSPy optimization or compilation
• Debugging DSPy-related issues
• Following AgenticFleet-specific DSPy patterns
• Learning DSPy best practices

Core Concepts

Signatures

DSPy signatures define the input/output contract for your programs. See signatures.md for:

• Signature design patterns
• InputField vs OutputField usage
• Type hints and validation
• Hint and description best practices

Programs & Modules

DSPy programs are composed of modules that process inputs. See programs.md for:

• Building DSPy programs
• Module composition
• Compilation workflows
• Chain-of-thought and other patterns

Optimization

DSPy optimization improves program performance with teleprompters. See optimization.md for:

• Teleprompter selection
• Metric definition
• Optimization strategies
• Evaluation and testing

Patterns & Debugging

AgenticFleet-specific patterns and debugging techniques. See patterns.md for:

• AgenticFleet DSPy architecture
• Common issues and solutions
• Performance optimization
• Testing strategies

Scripts

The scripts/ directory provides reusable tools for DSPy development:

• compile-dspy.py: Compile DSPy modules with proper caching
• optimize-dspy.py: Run optimization with custom metrics
• test-signature.py: Validate signature structure and types
• clear-cache.py: Clear DSPy cache safely

See each script's help (--help) for usage details.

Templates

The assets/templates/ directory provides boilerplate for new DSPy work:

• signature-template.py: Starting point for new signatures
• program-template.py: Starting point for new programs

Examples

The assets/examples/ directory contains real examples from AgenticFleet:

• agentic-fleet-signatures.py: Production signatures from AgenticFleet

Critical Rules for AgenticFleet

1. Always use uv: Use uv venv for environment creation, uv pip for installs, and uv run for script execution
2. Compilation is offline-only: Never compile at runtime in production
3. Clear cache after changes: Run clear-cache.py after modifying DSPy modules
4. Use absolute imports: Always use from agentic_fleet.dspy_modules import ...
5. Set require_compiled: true: Enable in production to fail-fast on missing artifacts
6. JSON logging is default: Set LOG_JSON=0 for human-readable logs during development

Progressive Disclosure

This skill uses progressive disclosure to manage context efficiently:

1. SKILL.md (this file): Quick reference and navigation
2. references/: Detailed technical docs loaded as needed
3. scripts/: Executable tools (can be run without reading)
4. assets/: Templates and examples for new work

Load reference files only when you need detailed information on a specific topic.