Immutable. This exact content is served forever at /api/v1/blob/d4bdafcba948fd91.
---
name: dspy
description: >-
Expert skill for programming—not prompting—language models with Stanford's
DSPy framework. Signatures, modules (Predict, ChainOfThought, ReAct),
optimizer/teleprompter selection, compilation, caching, evaluation. Use when
doing programmatic prompt optimization or building compiled prompt programs.
license: MIT
metadata:
author: Magnus Hedemark
version: 1.0.3
source: https://dspy.ai
---
# DSPy Expert Skill
DSPy is a **compiler for prompt programs**, not a chain or RAG framework. You write Python programs with typed signatures and DSPy optimizes the prompts automatically.
> **⚠️ DSPy is NOT a chain framework.** It does not use `prompt | model | parser`. It does not have LCEL. DSPy operates at a different layer: you define a program with Python control flow and typed signatures, then the *compiler* optimizes the prompts against a metric. If you reach for DSPy expecting LangChain-style composition, you are reaching for the wrong tool.
Think of it as PyTorch for LMs — you define the architecture, the compiler tunes the weights (prompts).
## Core Paradigm
> Read this first. It is the most important thing to understand about DSPy.
```python
import dspy
# 1. Configure the LM
lm = dspy.LM("openai/gpt-4o-mini")
dspy.configure(lm=lm)
# 2. Define a signature (input/output schema)
class QASignature(dspy.Signature):
"""Answer questions concisely."""
question: str = dspy.InputField()
answer: str = dspy.OutputField()
# 3. Build a program using modules
qa = dspy.ChainOfThought(QASignature)
# 4. Compile against a metric
optimizer = dspy.MIPROv2(metric=dspy.answer_exact_match)
compiled_qa = optimizer.compile(qa, trainset=trainset, num_trials=25)
# 5. Use the compiled program (portable artifact)
answer = compiled_qa(question="What is DSPy?").answer
```
## Core Principles
1. **DSPy is a compiler, not a chain framework.** You define the program structure with Python control flow and typed signatures. The compiler optimizes the prompts. This is fundamentally different from LangChain's explicit prompt composition.
2. **Signatures define the task.** Input/output field pairs with optional descriptions are the task definition. The syntax is `input1, input2 -> output1, output2`.
3. **Modules are program components.** `dspy.Predict` (direct), `dspy.ChainOfThought` (reasoning), `dspy.ReAct` (tool-use), and custom `dspy.Module` subclasses. Compose them with Python control flow (if/for/while).
4. **Optimizers tune prompts, not weights.** A dozen optimizers (teleprompters) tune instructions, few-shot demos, or both. Selection depends on bottleneck and budget. See the optimizer cheat sheet.
5. **Compile once, serve many.** Compilation is expensive ($3-$300+). The output is a portable artifact via `program.save(path)`. Inference is cheap.
6. **Cache aggressively.** DSPy caches all LM calls by default. Set `DSPY_CACHEDIR` for the current client. Disable with `dspy.LM(..., cache=False)`.
## Where to Start
| You already have... | Start here |
|---|---|
| Nothing — exploring DSPy | Understand the paradigm (read this page first), then build a simple Predict program |
| A working prompt you want to optimize | Port to a DSPy Signature, add ChainOfThought, compile with BootstrapFewShot |
| A multi-step pipeline | Build as a custom dspy.Module with Python control flow, compile with MIPROv2 |
| An agent/tool-use task | Use dspy.ReAct with tools, compile with GEPA or AvatarOptimizer |
| Comparing frameworks | See the Framework Routing Guide |
## Quick Reference
| Task | Approach | Reference |
|------|----------|-----------|
| Basic prediction | `dspy.Predict(signature)` | `references/core-modules.md` |
| With reasoning | `dspy.ChainOfThought(signature)` | `references/core-modules.md` |
| With tools | `dspy.ReAct(tools=tools)` | `references/agent-patterns.md` |
| Custom program | `class MyProgram(dspy.Module)` | `references/program-patterns.md` |
| Quick optimization | `dspy.BootstrapFewShot(metric)` | `references/optimizer-guide.md` |
| Full optimization | `dspy.MIPROv2(metric, auto="medium")` | `references/optimizer-guide.md` |
| Evaluation | `dspy.Evaluate(metric=fn, devset=examples)` | `references/evaluation.md` |
| Save/load | `program.save(path)` / `program.load(path)` | `references/compilation-guide.md` |
| Retrieval | `dspy.Retrieve(k=5)` | `references/program-patterns.md` |
## Framework Routing Guide
| Scenario | Reach for | Why |
|----------|-----------|-----|
| Prompt optimization / compiled programs | **DSPy** | Only framework that auto-optimizes prompts against a metric |
| Documents to query / RAG | **LlamaIndex** | Data ingestion and retrieval are first-class primitives |
| Chain/agent composition | **LangChain** | LCEL is the cleanest pipe-based composition model |
| State-machine multi-agent | **LangGraph** | Graph topology, subgraphs, human-in-the-loop |
| Search pipelines | **Haystack** | Pipeline model is more mature for search workloads |
| Role-based teams | **CrewAI** | Higher-level agent abstraction |
## Reference Files
| Reference | Load when | File |
|-----------|-----------|------|
| Core Modules | Building with Predict, ChainOfThought, ReAct | `references/core-modules.md` |
| Optimizer Guide | Choosing and configuring an optimizer | `references/optimizer-guide.md` |
| Program Patterns | RAG, classification, multi-step, tool-use | `references/program-patterns.md` |
| Evaluation | Metrics, evaluation loop, dataset creation | `references/evaluation.md` |
| Compilation Guide | Caching, cost management, save/load | `references/compilation-guide.md` |
| Agent Patterns | ReAct agent, tool-use, AvatarOptimizer | `references/agent-patterns.md` |
| FAQ & Troubleshooting | Common errors and fixes | `references/faq-and-troubleshooting.md` |
## Template Files
| Template | When to use | File |
|----------|-------------|------|
| Classification | Text classification with BootstrapFewShot | `templates/classification.py` |
| RAG Program | RAG with ColBERT retrieval and ChainOfThought | `templates/rag-program.py` |
| Multi-Step Reasoning | Multi-step program with tool-use | `templates/multi-step.py` |
## Scripts
| Script | Purpose | File |
|--------|---------|------|
| check-setup | Verify DSPy installation and configuration | `scripts/check-setup.py` |
## Troubleshooting
| Symptom | Likely cause | Fix | Reference |
|---------|-------------|-----|-----------|
| Compilation too slow | Too many candidates/threads | Reduce `num_candidates` or use `auto="light"` | `references/optimizer-guide.md` |
| Compilation too expensive | No caching | Enable DSPY_CACHEDIR | `references/compilation-guide.md` |
| Context too long | Too many demos | Reduce `max_bootstrapped_demos` and `max_labeled_demos` | `references/faq-and-troubleshooting.md` |
| Low quality after compile | Wrong optimizer for bottleneck | Check cheat sheet: instructions vs demos vs weights | `references/optimizer-guide.md` |
| Program is not improving | Metric not discriminating | Use a metric that returns float, not bool | `references/evaluation.md` |
| Sub-module not updating | _compiled flag set | Set `module._compiled = False` before recompiling | `references/compilation-guide.md` |
## When NOT to Use DSPy
- Simple single-prompt application — raw API calls are simpler
- Need pre-built application modules (PDF Q&A, text-to-SQL) — use LlamaIndex or LangChain
- One-shot task with no optimization budget — DSPy's compiler overhead won't amortize
- Real-time latency-critical — compilation happens at development time but adds no inference overhead