Don't Panic

You're holding this book because somewhere along the way, you realized that prompt engineering is not engineering. It's archaeology — carefully brushing away layers of vague instruction, hoping you don't accidentally collapse the whole structure because you removed "Be concise" from line 47.

You've probably written something like this:

prompt = f"""You are a helpful AI assistant specialized in analyzing startup ideas.
Given the following startup pitch, provide a detailed analysis.
Please respond in JSON format with the following fields:
- "viability_score": a number from 1-10
- "strengths": a list of strengths
- "weaknesses": a list of weaknesses
- "verdict": a one-sentence summary

IMPORTANT: Only respond with valid JSON. Do not include any other text.
SERIOUSLY: Just the JSON. Nothing else. I mean it.

Startup pitch: {pitch}
"""

If that code gave you a visceral reaction — a twitch, perhaps, or a faint sense of existential dread — congratulations. You're ready for DSPy.

What Is DSPy, and Why Should You Care?

DSPy is a framework for programming language models instead of prompting them. That single word swap changes everything.

When you prompt an LLM, you're writing instructions in natural language and hoping the model interprets them the way you intended. When you program with DSPy, you declare what you want (inputs, outputs, types, constraints) and let the framework figure out how to ask for it. You write Python. DSPy writes the prompts.

Here's what that looks like in practice:

import dspy

# Declare what you want
class AnalyzeStartup(dspy.Signature):
    """Analyze a startup pitch and provide a structured evaluation."""
    pitch: str = dspy.InputField(desc="The startup pitch to analyze")
    viability_score: int = dspy.OutputField(desc="Score from 1-10")
    strengths: list[str] = dspy.OutputField(desc="Key strengths of the idea")
    weaknesses: list[str] = dspy.OutputField(desc="Key weaknesses or risks")
    verdict: str = dspy.OutputField(desc="One-sentence overall verdict")

That's it. No "IMPORTANT: respond in JSON." No "SERIOUSLY: I mean it." Just a Python class that declares your intent. DSPy handles the rest — formatting the prompt, parsing the response, retrying on failures, and even optimizing the instructions based on what actually works.

If you're thinking "that seems too good to be true," you're right to be skeptical. By the end of this chapter, you'll have written, run, and inspected a working DSPy program. You'll see exactly what it sends to the LLM, exactly what comes back, and you'll understand why this approach is fundamentally better than prompt wrangling.

Setting Up Your Towel (Environment)

Every hitchhiker needs a towel. Every DSPy developer needs three things: Python, Poetry, and an API key.

Python 3.10+

DSPy 3.x requires Python 3.10 or higher. Check your version:

$ python --version
Python 3.10.12  # 3.10+ is fine

Poetry

We use Poetry for dependency management throughout this book because reproducible environments matter. If you're working through these examples six months from now, poetry install should still give you a working setup.

$ pip install poetry

Project Setup

Let's create our workspace:

$ mkdir ch01_dont_panic && cd ch01_dont_panic
$ poetry init --name "ch01-dont-panic" \
    --description "Chapter 1: Don't Panic" \
    --author "Your Name <you@example.com>" \
    --python ">=3.10,<3.15" \
    --no-interaction
$ poetry add dspy python-dotenv

After a minute of dependency resolution (Poetry is thorough, not fast), you'll have DSPy 3.1.3 installed in an isolated virtual environment. You'll notice we didn't install anthropic or openai separately — DSPy uses LiteLLM under the hood, which handles all provider communication for you. One less thing to manage.

Your API Key

We use Anthropic's Claude as our primary LLM throughout this book. You'll need an API key from console.anthropic.com.

Create a .env file in your project root:

# .env
ANTHROPIC_API_KEY=sk-ant-your-key-here

And a quick utility to load it:

# config.py
import os
from dotenv import load_dotenv

load_dotenv()

ANTHROPIC_API_KEY = os.getenv("ANTHROPIC_API_KEY")
if not ANTHROPIC_API_KEY:
    raise ValueError(
        "ANTHROPIC_API_KEY not found. "
        "Create a .env file with your key. "
        "Don't Panic — just visit console.anthropic.com"
    )

🚨 Gotcha: Never commit your .env file. Add it to .gitignore immediately. This seems obvious, but GitHub's secret scanning service catches thousands of leaked API keys every week. Don't be a statistic.

Your First DSPy Program

Enough setup. Let's write something that actually does something.

We're going to build a Startup Idea Roaster — you feed it a startup pitch, and it gives you a brutally honest (but constructive) analysis. It's a fun first project that demonstrates all the core DSPy concepts without any complex infrastructure.

Step 1: Configure the LM

Every DSPy program starts by telling the framework which language model to use. This is done with dspy.LM and dspy.configure:

import dspy

# Create a language model instance
lm = dspy.LM(
    "anthropic/claude-sonnet-4-6",
    temperature=0.7,
    max_tokens=1000
)

# Set it as the global default
dspy.configure(lm=lm)

Let's unpack this:

dspy.LM("anthropic/claude-sonnet-4-6") — The model string follows the format provider/model-name. DSPy uses LiteLLM under the hood, which means you can swap in any provider with a one-line change:

# Anthropic (our primary)
lm = dspy.LM("anthropic/claude-sonnet-4-6")

# OpenAI
lm = dspy.LM("openai/gpt-5.4-mini")

# Local via Ollama
lm = dspy.LM("ollama_chat/llama3.2", api_base="http://localhost:11434")

This provider-agnostic design is one of DSPy's quiet superpowers. Your program logic doesn't change when you switch models. Your Signatures, Modules, and Optimizers remain the same. Only the LM config changes.

temperature=0.7 — Controls randomness. Lower values (0.0-0.3) give more deterministic outputs; higher values (0.7-1.0) give more creative ones. For analysis tasks, 0.7 is a reasonable starting point.

max_tokens=1000 — Caps the response length. Set this thoughtfully — too low and your outputs get truncated, too high and you're paying for tokens you don't need.

dspy.configure(lm=lm) — Sets the LM as the global default for all DSPy modules. Think of it like setting up a database connection pool — you do it once at startup, and everything uses it.

🧪 Lab Notes: In production, I always set temperature=0.0 for classification tasks and temperature=0.7 for generation tasks. Determinism matters when you're scoring leads — you don't want the same input producing different scores on different runs. But when you're generating outreach emails, a little variety keeps things from sounding robotic.

Step 2: Define a Signature

A Signature is DSPy's way of declaring what a task does — its inputs and outputs — without specifying how to do it. It's a contract between you and the LLM.

The simplest form is an inline string:

# Inline signature: inputs -> outputs
predict = dspy.Predict("pitch: str -> verdict: str")

But for anything beyond a toy example, class-based Signatures are the way to go:

class RoastStartup(dspy.Signature):
    """You are a sharp, witty startup analyst known for cutting through
    hype with humor. Analyze the given startup pitch and provide an
    honest, entertaining evaluation. Be constructive but don't pull punches."""

    pitch: str = dspy.InputField(
        desc="The startup pitch or idea to analyze"
    )
    roast: str = dspy.OutputField(
        desc="A witty, honest roast of the startup idea (2-3 sentences)"
    )
    viability_score: int = dspy.OutputField(
        desc="Viability score from 1 (terrible) to 10 (brilliant)"
    )
    strengths: list[str] = dspy.OutputField(
        desc="List of genuine strengths (be specific)"
    )
    weaknesses: list[str] = dspy.OutputField(
        desc="List of weaknesses and risks (be specific)"
    )
    verdict: str = dspy.OutputField(
        desc="One-sentence final verdict: invest or run?"
    )

Let's break down what matters here:

The docstring is your instruction. That triple-quoted string at the top becomes the system prompt. It tells the LLM how to approach the task. Write it like you're briefing a capable colleague, not like you're trying to jailbreak a chatbot.

Field names are semantically meaningful. Naming your output roast instead of output1 genuinely affects quality. DSPy uses these names as part of the prompt, and LLMs respond to semantic cues. viability_score produces better scores than score or s.

desc parameters guide the LLM. These descriptions become part of the formatted prompt. "Viability score from 1 (terrible) to 10 (brilliant)" is much more useful than "A score."

Type hints drive parsing. When you declare viability_score: int, DSPy knows to parse the output as an integer. list[str] gets parsed as a list. This isn't just documentation — it's functional.

🚨 Gotcha: Field names in Signatures are more important than most people realize. They're not just variable names — they're part of the prompt that DSPy constructs. Renaming detailed_analysis to x will measurably degrade your output quality. Treat field names like you'd treat function names in a public API: make them descriptive and intentional. Inspired by GitHub Issue #164

Step 3: Use a Predict Module

Now we connect the Signature to a prediction module. dspy.Predict is the simplest — it takes a Signature and calls the LLM:

# Create a predictor from our Signature
roaster = dspy.Predict(RoastStartup)

# Call it with input values
result = roaster(
    pitch="An AI-powered toothbrush that writes poetry while you brush. "
          "It uses GPT-4 to generate haikus about your dental hygiene "
          "and posts them to Twitter automatically. $50/month subscription."
)

# Access the outputs
print(result.roast)
print(f"Viability: {result.viability_score}/10")
print(f"Strengths: {result.strengths}")
print(f"Weaknesses: {result.weaknesses}")
print(f"Verdict: {result.verdict}")

That's a complete DSPy program. Signature defines the contract. Predict executes it. The result object gives you typed access to every output field.

Step 4: See What's Actually Happening

Here's where DSPy earns trust. You can inspect exactly what it sent to the LLM:

# Inspect the last LM call
dspy.inspect_history(n=1)

This prints the full conversation — system message, user message, and assistant response — so you can see exactly how DSPy formatted your Signature into a prompt. No black boxes. No mystery. Just a well-structured prompt that you didn't have to write by hand.

The first time you run inspect_history, you'll have an "aha" moment. You'll see that DSPy constructed a prompt far more structured and effective than what most of us write manually. It includes the task description, field descriptions, type constraints, and formatting instructions — all generated from that clean Python class you wrote.

Putting It All Together: The Complete Startup Roaster

Here's the full, runnable program:

"""
startup_roaster.py - Chapter 1: Don't Panic
DSPy: The Mostly Harmless Guide

Your first DSPy program: a startup pitch analyzer that's
honest, structured, and doesn't require a single prompt template.
"""

import dspy


# --- Step 1: Define the Signature ---

class RoastStartup(dspy.Signature):
    """You are a sharp, witty startup analyst known for cutting through
    hype with humor. Analyze the given startup pitch and provide an
    honest, entertaining evaluation. Be constructive but don't pull punches."""

    pitch: str = dspy.InputField(
        desc="The startup pitch or idea to analyze"
    )
    roast: str = dspy.OutputField(
        desc="A witty, honest roast of the startup idea (2-3 sentences)"
    )
    viability_score: int = dspy.OutputField(
        desc="Viability score from 1 (terrible) to 10 (brilliant)"
    )
    strengths: list[str] = dspy.OutputField(
        desc="List of genuine strengths (be specific)"
    )
    weaknesses: list[str] = dspy.OutputField(
        desc="List of weaknesses and risks (be specific)"
    )
    verdict: str = dspy.OutputField(
        desc="One-sentence final verdict: invest or run?"
    )


# --- Step 2: Build the Module ---

class StartupRoaster(dspy.Module):
    """A module that roasts startup pitches with structured analysis.

    Why a Module instead of bare Predict? Modules are composable,
    optimizable, and testable. Even for simple programs, wrapping
    your Predict in a Module is a habit worth building early.
    """

    def __init__(self):
        super().__init__()
        self.analyze = dspy.Predict(RoastStartup)

    def forward(self, pitch: str) -> dspy.Prediction:
        return self.analyze(pitch=pitch)


# --- Step 3: Configure and Run ---

def main():
    # Configure the LM
    lm = dspy.LM(
        "anthropic/claude-sonnet-4-6",
        temperature=0.7,
        max_tokens=1000
    )
    dspy.configure(lm=lm)

    # Create the roaster
    roaster = StartupRoaster()

    # Some pitches to analyze
    pitches = [
        (
            "An AI-powered toothbrush that writes poetry while you brush. "
            "Uses GPT-4 to generate haikus about dental hygiene and posts "
            "them to Twitter automatically. $50/month subscription."
        ),
        (
            "A platform that connects freelance developers with nonprofits "
            "who need technical help but can't afford market rates. "
            "Developers get tax deductions and portfolio pieces. "
            "Nonprofits get quality software. Revenue from premium matching "
            "and enterprise volunteer programs."
        ),
        (
            "Uber for dogs. Not dog walking — actual rideshare for dogs. "
            "Your dog needs to get to the vet but you're at work? "
            "Book a DogUber. We handle pickup, transport, and drop-off. "
            "GPS tracking and live video feed included."
        ),
    ]

    for i, pitch in enumerate(pitches, 1):
        print(f"\n{'='*60}")
        print(f"PITCH #{i}")
        print(f"{'='*60}")
        print(f"{pitch[:80]}...")
        print()

        result = roaster(pitch=pitch)

        print(f"🔥 ROAST: {result.roast}")
        print(f"📊 VIABILITY: {result.viability_score}/10")
        print(f"💪 STRENGTHS: {result.strengths}")
        print(f"⚠️  WEAKNESSES: {result.weaknesses}")
        print(f"🎯 VERDICT: {result.verdict}")

    # Show what DSPy actually sent to the LLM
    print(f"\n{'='*60}")
    print("BEHIND THE CURTAIN: What DSPy sent to the LLM")
    print(f"{'='*60}")
    dspy.inspect_history(n=1)


if __name__ == "__main__":
    main()

Save that as startup_roaster.py and run it:

$ poetry run python startup_roaster.py

What Just Happened? (A Guided Tour)

When you ran that program, DSPy did several things you didn't have to think about:

1. Prompt Construction. DSPy took your Signature class — the docstring, field names, descriptions, and type hints — and assembled a structured prompt. It didn't just dump your instructions into a string. It created a formatted template with clear field delimiters that make it easy for the LLM to produce parseable output.

2. Type-Safe Parsing. When the LLM responded, DSPy parsed viability_score as an integer and strengths as a list of strings. If the LLM returned "7/10" instead of just "7" for the score, DSPy handled it. If the response was malformed, DSPy retried automatically.

3. Caching. By default, DSPy caches LM responses. Run the program again with the same inputs and it returns instantly — no API call, no cost. This is a godsend during development.

4. History Tracking. Every LM call was logged. You can inspect exactly what was sent and received, making debugging straightforward rather than mystical.

Signatures: A Deeper Look

Now that you've seen a Signature in action, let's explore the edges.

Inline vs. Class-Based

Inline Signatures are great for quick experiments:

# Simple inline signature
qa = dspy.Predict("question -> answer")
result = qa(question="What is the capital of France?")
print(result.answer)  # "Paris"

# With type hints
scorer = dspy.Predict("review: str -> sentiment: str, confidence: float")
result = scorer(review="This product changed my life!")
print(result.sentiment, result.confidence)

Class-based Signatures are better for anything you'll maintain:

class ExtractContact(dspy.Signature):
    """Extract structured contact information from unstructured text."""

    text: str = dspy.InputField(desc="Raw text containing contact info")
    name: str = dspy.OutputField(desc="Full name of the person")
    email: str = dspy.OutputField(desc="Email address, or 'not found'")
    phone: str = dspy.OutputField(desc="Phone number, or 'not found'")
    company: str = dspy.OutputField(desc="Company name, or 'not found'")

Use inline for prototyping. Use class-based for anything that goes in a Git repo.

The Power of Good Descriptions

Field descriptions aren't optional decoration — they're the single biggest lever you have over output quality (short of optimization, which we'll cover in Chapter 4).

Compare these two approaches:

# Weak descriptions (or none at all)
class WeakAnalysis(dspy.Signature):
    """Analyze this."""
    text: str = dspy.InputField()
    result: str = dspy.OutputField()

# Strong descriptions
class StrongAnalysis(dspy.Signature):
    """Perform a competitive analysis of the given product, identifying
    its market position relative to top 3 competitors."""
    product_description: str = dspy.InputField(
        desc="Detailed description of the product including features and pricing"
    )
    market_position: str = dspy.OutputField(
        desc="Where this product sits in the market (leader, challenger, niche, or newcomer)"
    )
    competitive_advantages: list[str] = dspy.OutputField(
        desc="Specific features or qualities that differentiate from competitors"
    )
    vulnerabilities: list[str] = dspy.OutputField(
        desc="Areas where competitors have a clear advantage"
    )

The second version will produce dramatically better results. Every piece of context you add to field names and descriptions gives the LLM more signal to work with.

🧪 Lab Notes: When I was building a lead scoring system, I spent an entire afternoon experimenting with field descriptions. Changing score: int = dspy.OutputField() to lead_quality_score: int = dspy.OutputField(desc="Score from 1-100 based on buying intent signals, company fit, and engagement recency") improved accuracy by 15% — without changing a single line of program logic. Field descriptions are free performance.

ChainOfThought: Making the LLM Show Its Work

dspy.Predict asks the LLM to produce outputs directly. dspy.ChainOfThought asks it to reason first, then answer. This simple change often produces better results, especially for tasks that require analysis, comparison, or judgment.

class DebateStartup(dspy.Signature):
    """Evaluate whether a startup idea is worth pursuing.
    Consider market size, feasibility, competition, and timing."""

    pitch: str = dspy.InputField(desc="The startup pitch to evaluate")
    recommendation: str = dspy.OutputField(
        desc="Final recommendation: 'pursue', 'pivot', or 'pass'"
    )
    confidence: float = dspy.OutputField(
        desc="Confidence in recommendation from 0.0 to 1.0"
    )

# Without reasoning (direct answer)
direct = dspy.Predict(DebateStartup)

# With reasoning (thinks step-by-step first)
reasoned = dspy.ChainOfThought(DebateStartup)

When you use ChainOfThought, DSPy automatically adds a reasoning field to the output. The LLM fills this with its step-by-step thinking before producing the final answer:

result = reasoned(
    pitch="A marketplace for renting out your backyard pool by the hour"
)

# The reasoning field shows the LLM's thought process
print(result.reasoning)
# "Let me evaluate this idea step by step. Market size: The sharing
#  economy for homes (Airbnb) is proven, and pools are underutilized
#  assets... Feasibility: Liability and insurance are major challenges..."

print(result.recommendation)  # "pivot"
print(result.confidence)       # 0.6

The reasoning isn't just for show — it genuinely improves output quality. By forcing the model to articulate its thinking, you get more considered, more consistent results. This is the programmatic version of writing "think step by step" in a prompt, but DSPy handles the structure automatically.

🚨 Gotcha: ChainOfThought uses more tokens than Predict because it generates the reasoning text in addition to the actual outputs. For high-volume production workloads where cost matters, benchmark both. Sometimes Predict with great field descriptions performs just as well as ChainOfThought — and at lower cost. We'll cover this trade-off in detail in Chapter 4 when we talk about optimization.

The Module Pattern: Why Bother?

You might be wondering: "Why did we wrap dspy.Predict in a dspy.Module? Can't we just use Predict directly?"

You can. For quick scripts, predict = dspy.Predict(MySignature) is perfectly fine. But Modules give you three things that matter as your programs grow:

1. Composition. Modules can contain other Modules:

class StartupAnalyzer(dspy.Module):
    def __init__(self):
        super().__init__()
        self.roast = dspy.Predict(RoastStartup)
        self.debate = dspy.ChainOfThought(DebateStartup)

    def forward(self, pitch: str):
        roast_result = self.roast(pitch=pitch)
        debate_result = self.debate(pitch=pitch)
        return dspy.Prediction(
            roast=roast_result.roast,
            viability_score=roast_result.viability_score,
            recommendation=debate_result.recommendation,
            reasoning=debate_result.reasoning,
        )

2. Optimization. When we get to Chapter 4, you'll learn that DSPy's optimizers work by examining the Predict instances inside your Module and tuning them. If your Predicts aren't inside a Module, the optimizer can't find them.

3. State Management. Modules can be saved, loaded, and versioned:

# Save an optimized module
roaster.save("roaster_v1.json")

# Load it later
loaded_roaster = StartupRoaster()
loaded_roaster.load("roaster_v1.json")

The habit of always wrapping Predicts in Modules is like the habit of always writing functions instead of top-level scripts. It costs you nothing now and saves you everything later.

Trying Different Models

One of DSPy's most practical features is how easy it makes model switching. Want to compare Claude's analysis against GPT-5.4-mini? It's a one-line change:

# Use Claude (our primary)
claude = dspy.LM("anthropic/claude-sonnet-4-6", temperature=0.7, max_tokens=1000)

# Use GPT-5.4-mini (cheaper, faster)
gpt4mini = dspy.LM("openai/gpt-5.4-mini", temperature=0.7, max_tokens=1000)

# Run with Claude
dspy.configure(lm=claude)
roaster = StartupRoaster()
claude_result = roaster(pitch="An AI that writes AI books")

# Run with GPT-5.4-mini
dspy.configure(lm=gpt4mini)
gpt_result = roaster(pitch="An AI that writes AI books")

Or use dspy.context() for temporary model switches without touching the global config:

dspy.configure(lm=claude)  # Global default

with dspy.context(lm=gpt4mini):
    # This call uses GPT-5.4-mini
    cheap_result = roaster(pitch="Budget analysis time")

# Back to Claude
premium_result = roaster(pitch="Full analysis please")

This is enormously useful in production. You might use a powerful model for complex analyses and a cheaper one for simple classifications, all within the same program. We'll build exactly this pattern in Chapter 6.

Your Turn: Exercises

Before moving on, try these. They'll cement the concepts and give you confidence with the API.

Exercise 1: The Email Subject Line Generator Create a Signature and Module that takes an email body and generates three subject line options with an estimated open rate for each. Use list[str] for the subject lines and list[float] for the open rates.

Exercise 2: The Code Reviewer Build a Signature that takes a code snippet and a programming language, then produces a review with: a quality score (1-10), a list of issues found, and a suggested improved version. Use ChainOfThought so the reviewer reasons about the code before scoring it.

Exercise 3: Model Comparison Run your StartupRoaster against at least two different models (e.g., Claude and GPT-5.4-mini). Compare the outputs. Which model gives more specific strengths and weaknesses? Which gives funnier roasts? Use inspect_history to compare the raw prompts and responses.

🪂 Don't Panic: Chapter 1 Quick Reference

Setup

import dspy

lm = dspy.LM("anthropic/claude-sonnet-4-6", temperature=0.7, max_tokens=1000)
dspy.configure(lm=lm)

Signature (class-based)

class MyTask(dspy.Signature):
    """Instructions for the LLM go in the docstring."""
    input_field: str = dspy.InputField(desc="What this input is")
    output_field: str = dspy.OutputField(desc="What you want back")

Predict vs. ChainOfThought

direct = dspy.Predict(MyTask)           # Direct: input → output
reasoned = dspy.ChainOfThought(MyTask)  # Reasons first, then outputs

Module Pattern

class MyProgram(dspy.Module):
    def __init__(self):
        super().__init__()
        self.step = dspy.Predict(MyTask)

    def forward(self, **kwargs):
        return self.step(**kwargs)

Debugging

dspy.inspect_history(n=1)  # See last LM call
result.keys()              # See all output fields

Common Errors and Fixes

In the next chapter, we'll take this foundation and build something real — a multi-step Lead Intelligence Engine that chains modules together into a pipeline. We'll learn about module composition, conditional logic, and why DSPy's adapter system matters more than you think.

So long, and thanks for all the prompts.