Chapter 01: DSPy Fundamentals

Key Concepts

1. DSPy Core Philosophy

DSPy (Declarative Self-improving Python) is a framework for programming language models, transforming traditional prompt engineering into a more systematic programming approach.

Core Design Philosophy

• Declarative Programming: Describe “what to do” rather than “how to do it”
• Automatic Optimization: Framework automatically optimizes prompts and reasoning chains
• Modular Design: Composable functional modules
• Type Safety: Strong type system ensures input/output consistency

Comparison with Traditional Methods

Feature	Traditional Prompt Engineering	DSPy Framework
Methodology	Manual prompt debugging	Programmatic construction
Optimization	Manual iteration	Automatic optimization
Maintainability	Difficult to maintain	Highly modular
Scalability	Limited	Easy to extend
Reusability	Low	High

2. DSPy Architecture Components

Core Component Hierarchy

DSPy Framework
├── Signatures - Define input/output specifications
├── Modules - Functional components
├── Predictors - Reasoning engines
├── Optimizers - Automatic tuning
└── Compilers - Program compilation

Workflow

1. Define Signatures: Specify input/output formats
2. Build Modules: Compose functional components
3. Configure Predictors: Choose reasoning methods
4. Compile and Optimize: Automatic performance tuning
5. Execute Program: Run language model programs

3. Environment Setup

Installing DSPy

# Basic installation
pip install dspy-ai

# Full installation (including all dependencies)
pip install "dspy-ai[complete]"

# Development environment installation
pip install "dspy-ai[dev]"

Required Dependencies

# Core dependencies
pip install openai anthropic
pip install pandas numpy
pip install chromadb faiss-cpu

# Optional dependencies (install as needed)
pip install transformers torch  # Local models
pip install pinecone-client     # Pinecone vector database
pip install weaviate-client     # Weaviate vector database

4. Development Environment Configuration

Configuration File Setup

# config.py - Configuration file
import os
from dotenv import load_dotenv

load_dotenv()

# API configuration
OPENAI_API_KEY = os.getenv('OPENAI_API_KEY')
ANTHROPIC_API_KEY = os.getenv('ANTHROPIC_API_KEY')

# Model configuration
DEFAULT_MODEL = "gpt-3.5-turbo"
TEMPERATURE = 0.0
MAX_TOKENS = 1000

# Logging configuration
LOG_LEVEL = "INFO"
LOG_FORMAT = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"

Environment Variables Configuration

# .env file
OPENAI_API_KEY=your_openai_api_key_here
ANTHROPIC_API_KEY=your_anthropic_api_key_here
DSPY_CACHE_DIR=./cache
DSPY_LOG_LEVEL=INFO

Example Code

Your First DSPy Program

import dspy

# 1. Configure language model
lm = dspy.OpenAI(model="gpt-3.5-turbo", max_tokens=100)
dspy.settings.configure(lm=lm)

# 2. Define signature - describe task inputs and outputs
class BasicQA(dspy.Signature):
    """Basic Q&A system for answering user questions"""
    question = dspy.InputField()      # Input: question
    answer = dspy.OutputField()       # Output: answer

# 3. Create predictor module
predict = dspy.Predict(BasicQA)

# 4. Use the program
question = "What is artificial intelligence?"
response = predict(question=question)

print(f"Question: {question}")
print(f"Answer: {response.answer}")

Environment Verification Script

# verify_setup.py - Verify environment configuration
import dspy
import sys
import os

def verify_dspy_installation():
    """Verify DSPy installation"""
    try:
        import dspy
        print("✅ DSPy installed successfully")
        print(f"   Version: {dspy.__version__}")
        return True
    except ImportError as e:
        print("❌ DSPy installation failed")
        print(f"   Error: {e}")
        return False

def verify_api_keys():
    """Verify API key configuration"""
    keys_status = {}

    # Check OpenAI API Key
    openai_key = os.getenv('OPENAI_API_KEY')
    if openai_key:
        keys_status['OpenAI'] = "✅ Configured"
    else:
        keys_status['OpenAI'] = "❌ Not configured"

    # Check Anthropic API Key
    anthropic_key = os.getenv('ANTHROPIC_API_KEY')
    if anthropic_key:
        keys_status['Anthropic'] = "✅ Configured"
    else:
        keys_status['Anthropic'] = "❌ Not configured"

    print("\nAPI Key Status:")
    for provider, status in keys_status.items():
        print(f"   {provider}: {status}")

    return any('✅' in status for status in keys_status.values())

def test_basic_functionality():
    """Test basic functionality"""
    try:
        # Try to create model (without actually calling API)
        if os.getenv('OPENAI_API_KEY'):
            lm = dspy.OpenAI(model="gpt-3.5-turbo", max_tokens=10)
            print("✅ Model configuration successful")
        else:
            print("⚠️  No API key, skipping model test")

        # Test signature creation
        class TestSignature(dspy.Signature):
            input_text = dspy.InputField()
            output_text = dspy.OutputField()

        print("✅ Signature creation successful")

        # Test predictor creation
        predictor = dspy.Predict(TestSignature)
        print("✅ Predictor creation successful")

        return True

    except Exception as e:
        print(f"❌ Functionality test failed: {e}")
        return False

def main():
    """Main verification function"""
    print("DSPy Environment Verification Tool")
    print("=" * 30)

    # Verify installation
    if not verify_dspy_installation():
        sys.exit(1)

    # Verify API keys
    if not verify_api_keys():
        print("⚠️  Warning: No API keys detected, some features will be unavailable")

    # Test basic functionality
    if test_basic_functionality():
        print("\n🎉 Environment configuration verification complete!")
        print("You can now start using DSPy")
    else:
        print("\n❌ Environment configuration has issues")
        sys.exit(1)

if __name__ == "__main__":
    main()

Complete Hello World Example

# hello_dspy.py - Complete DSPy getting started example
import dspy
import os
from dotenv import load_dotenv

# Load environment variables
load_dotenv()

def setup_dspy():
    """Setup DSPy environment"""
    # Configure OpenAI model
    if os.getenv('OPENAI_API_KEY'):
        lm = dspy.OpenAI(
            model="gpt-3.5-turbo",
            max_tokens=150,
            temperature=0.1
        )
        dspy.settings.configure(lm=lm)
        print("✅ DSPy configured with OpenAI model")
    else:
        print("❌ OpenAI API key not found")
        return False
    return True

class Greeting(dspy.Signature):
    """Signature for generating personalized greetings"""
    name = dspy.InputField(desc="User's name")
    language = dspy.InputField(desc="Language for greeting")
    greeting = dspy.OutputField(desc="Personalized greeting")

class Translation(dspy.Signature):
    """Signature for text translation"""
    text = dspy.InputField(desc="Text to translate")
    target_language = dspy.InputField(desc="Target language")
    translation = dspy.OutputField(desc="Translated text")

def main():
    """Main program"""
    print("DSPy Hello World Example")
    print("=" * 25)

    # Setup environment
    if not setup_dspy():
        return

    # Example 1: Basic greeting
    print("\n1. Basic Greeting Example:")
    greeter = dspy.Predict(Greeting)

    result = greeter(
        name="Xiaoming",
        language="Chinese"
    )
    print(f"   Greeting: {result.greeting}")

    # Example 2: English greeting
    print("\n2. English Greeting Example:")
    result = greeter(
        name="Alice",
        language="English"
    )
    print(f"   Greeting: {result.greeting}")

    # Example 3: Translation feature
    print("\n3. Translation Feature Example:")
    translator = dspy.Predict(Translation)

    result = translator(
        text="Hello, how are you?",
        target_language="Chinese"
    )
    print(f"   Original: Hello, how are you?")
    print(f"   Translation: {result.translation}")

    print("\n🎉 DSPy Getting Started Example Complete!")

if __name__ == "__main__":
    main()

Practice Exercises

Exercise 1: Environment Configuration Verification

Run the environment verification script to ensure DSPy is correctly installed and API keys are configured.

python verify_setup.py

Exercise 2: Create Your First DSPy Program

1. Create a simple Q&A system
2. Define your own signature
3. Test different types of questions

# Your exercise code
class MyQA(dspy.Signature):
    """Your Q&A system description"""
    question = dspy.InputField(desc="User question")
    answer = dspy.OutputField(desc="System answer")

# Implement and test your program

Exercise 3: Compare with Traditional Methods

Try implementing the same functionality using traditional prompt engineering methods and compare the differences between the two approaches.

Chapter Summary

Through this chapter, you have:

1. Understood DSPy’s Core Philosophy: Moving from manual prompt engineering to programmatic language model programming
2. Mastered the Basic Architecture: Core components including signatures, modules, predictors
3. Configured the Development Environment: Installed DSPy and set up API keys
4. Run Your First Program: Created and executed a simple DSPy application

In the next chapter, we will dive deeper into DSPy’s core concepts and components, including the signature mechanism, module system, and detailed usage of predictors.