DSPy 0-to-1 Guide

DSPy's architecture is built on three core abstractions that decouple task logic from prompt engineering:

1. Signatures: Declarative task specifications. They define the input/output behavior (the 'what') without specifying the prompt (the 'how'). They act as a contract for modules.
2. Modules: Composable building blocks that encapsulate prompting strategies (e.g., Predict, ChainOfThought, ReAct). Modules are composed like neural network layers to build complex pipelines.
3. Optimizers: Self-improving engines (e.g., BootstrapFewShot). They take a module, a dataset, and a metric, then iteratively refine prompts and few-shot examples to maximize performance.

Beyond basic modules, DSPy supports several advanced patterns for production-grade LLM applications:

• Reflective Prompt Evolution (GEPA): A technique where the model reflects on its own prompts to iteratively improve them.
• Reinforcement Learning optimization: An experimental optimizer that uses RL signals to explore the prompt space.
• Pydantic Integration: Use Pydantic models to enforce strict output schemas and ensure runtime data safety.
• Parallel & Asynchronous Execution: Support for parallel LLM calls and asynchronous pipelines to reduce latency.
• Production Infrastructure: Includes dspy.Cache to reduce costs by caching LM responses, as well as logging and observability modules for debugging intermediate states.

DSPy uses optimizers (also known as teleprompters) to automatically improve your prompts based on data. An optimizer like BootstrapFewShot takes your module and a training set, then automatically generates prompt variations, tests them against a metric, and selects the best performing version (often including few-shot examples).

from dspy.teleprompt import BootstrapFewShot
from dspy import metrics

# Automatic optimization using a teleprompter
teleprompter = BootstrapFewShot(metric=metrics.answer_exact_match)
optimized_analyzer = teleprompter.compile(
    ContractAnalyzer(), 
    trainset=contract_examples
)

To build robust self-improving applications, follow these guidelines:

• Start simple: Begin with a single module (like Predict or ChainOfThought) and add complexity incrementally.
• Collect representative examples: Optimizers require high-quality, representative training data. Label your examples carefully.
• Separate training and evaluation: Always use distinct train and test sets to prevent overfitting prompts to your training examples.
• Manage cost and latency: Optimization involves many LLM calls. Use smaller models and enable caching during the experimentation phase.
• Validate outputs: For structured tasks, integrate Pydantic or explicit parsing to ensure outputs meet your required schema.

Use dspy.configure(lm=...) to set the global language model for your program. You can use cloud providers like OpenAI or local providers via Ollama.

For OpenAI: dspy.configure(lm=dspy.LM('openai/gpt-4o-mini'))

For local Ollama models: dspy.configure(lm=dspy.LM('ollama_chat/llama3'))

import dspy

dspy.configure(lm=dspy.LM('openai/gpt-4o-mini'))

To use DSPy, install the core package via pip. If you prefer to run models locally for privacy or cost reasons, you can use Ollama. After installing Ollama and pulling a model (e.g., llama3), configure DSPy using the ollama_chat/ prefix.

# Install DSPy
pip install dspy-ai

# Optional: Local LLM setup (MacOS example)
brew install ollama
ollama pull llama3
ollama serve

The guide is structured into three progressive learning stages:

Beginner (1-2 hours)

Focus on understanding the motivation, core concepts (Signatures, Modules, Optimizers), and basic installation. Use the examples in examples/basic/.

Intermediate (3-4 hours)

Focus on pipeline composition (RAG, summarization), evaluation metrics, optimization using teleprompters, and building agents with tools.

Advanced (5+ hours)

Deep dive into advanced patterns like GEPA, Pydantic validation, persona-driven use cases, and production infrastructure integration (Prometheus, Grafana, Docker).

To measure performance, follow these steps:

1. Prepare a dataset: Create a list of dspy.Example objects. Use .with_inputs() to specify which fields are inputs.
2. Choose a metric: Use built-in metrics like metrics.answer_exact_match or write a custom function that returns a score in [0, 1].
3. Run evaluation: Use dspy.Evaluate to run your module against the dataset.

from dspy import Example, Evaluate, metrics

# 1. Prepare dataset
train_examples = [
    Example(question="What is the capital of France?", answer="Paris").with_inputs("question"),
    Example(question="Who wrote 1984?", answer="George Orwell").with_inputs("question"),
]

# 2. Evaluate
evaluate = Evaluate(
    trainset=train_examples,
    metric=metrics.answer_exact_match,
)

# Assuming 'rag' is your module
result = evaluate(rag)
print("Accuracy:", result)