Prompt Templates¶

This guide shows you how to optimize your Pydantic models and prompts using prompt templates with placeholders. After optimization, you'll achieve efficient extraction with dynamic, context-aware prompts.

When to Use Template Optimization¶

Data Type	Best For	Optimization Focus	Extraction Outcome
Text	Documents, emails, reports	Field descriptions + prompts	Structured text data
Images	Classification, OCR	Image-specific prompts	Labels, classifications
PDFs	Forms, invoices, reports	Multi-page optimization	Document data
Templates	Dynamic contexts	Placeholder optimization	Context-aware data

Use template optimization when you need dynamic prompts that change based on input data.

Optimization Workflow¶

flowchart TD
    A[Define Model] --> B[Create Examples with Dicts]
    B --> C[Define Templates with Placeholders]
    C --> D[Run Optimization]
    D --> E[Optimize Descriptions]
    D --> F[Optimize Template Prompts]
    E --> G[Test Variations]
    F --> G
    G --> H[Evaluate Performance]
    H --> I[Select Best]
    I --> J[Optimized Prompter]
    J --> K[Extract with Dynamic Prompts]

Problem¶

You need dynamic prompts that change based on input data, such as including context-specific information in each prompt. You want to optimize these templates for better extraction accuracy.

Solution¶

Use dictionary-based text input with prompt templates containing {placeholders}. DSPydantic optimizes both the template structure and field descriptions.

Steps¶

1. Define Your Model¶

from pydantic import BaseModel, Field
from typing import Literal

class ProductReview(BaseModel):
    sentiment: Literal["positive", "negative", "neutral"] = Field(
        description="Review sentiment"
    )
    rating: int = Field(description="Rating 1-5")
    aspects: list[Literal["camera", "performance", "battery"]] = Field(
        description="Product aspects"
    )

2. Create Examples with Dictionary Text¶

Use dictionaries for the text field:

from dspydantic import Example

examples = [
    Example(
        text={
            "review": "Amazing camera quality and fast performance!",
            "product": "iPhone 15 Pro",
            "category": "smartphone"
        },
        expected_output={
            "sentiment": "positive",
            "rating": 4,
            "aspects": ["camera", "performance"]
        }
    ),
    Example(
        text={
            "review": "Poor battery life and overpriced.",
            "product": "Samsung Galaxy S24",
            "category": "smartphone"
        },
        expected_output={
            "sentiment": "negative",
            "rating": 2,
            "aspects": ["battery"]
        }
    ),
]

3. Use Prompt Templates and Optimize¶

Create prompts with {placeholders} that match dictionary keys:

from dspydantic import Prompter

prompter = Prompter(
    model=ProductReview,
    model_id="gpt-4o",
)

result = prompter.optimize(
    examples=examples,
    system_prompt="You are an expert analyst specializing in {category} reviews.",
    instruction_prompt="Analyze the {category} review about {product}: {review}",
)

The placeholders {category}, {product}, and {review} will be automatically filled from each example's text dictionary during optimization.

The optimization process tests variations of field descriptions and template prompts to find what works best.

4. Use Optimized Prompter (Outcome)¶

After optimization, extract data efficiently with dynamic prompts:

# Extract with prompt templates
data = prompter.run(
    text={
        "category": "smartphone",
        "product": "iPhone 15 Pro",
        "review": "Great camera!"
    }
)
print(data)

The prompter fills the placeholders automatically from the dictionary you provide.

How Template Optimization Works¶

Step	What Happens
1. Dictionary Input	Dictionary keys in `text` become available as placeholders
2. Template Filling	Placeholders in prompts are filled automatically during optimization
3. Optimization	Each example gets its own filled prompt for evaluation
4. Result	Optimized prompts retain placeholders for reuse
5. Extraction	When using `run()`, placeholders are filled from the dictionary you provide

What Gets Optimized¶

Parameter	What Gets Optimized	Impact
Field Descriptions	Individual field descriptions	High - direct extraction accuracy
System Prompt Template	Template structure and wording	Medium - context understanding
Instruction Prompt Template	Template structure and wording	Medium - extraction guidance

Tips¶

Use descriptive dictionary keys that match placeholder names
Ensure all examples have the same dictionary keys
Placeholders are case-sensitive
See Reference: Example for more details