Introduction

pip install vizpy dspy-ai
export VIZPY_API_KEY="..."
export OPENAI_API_KEY="sk-..."   # or your provider's key — see Supported Models below

import dspy
import vizpy
 
dspy.configure(lm=dspy.LM("openai/gpt-4o-mini"))  # use any model you have access to
 
# 1. Define your task
class Sentiment(dspy.Signature):
    """Classify the sentiment of a product review."""
    review: str = dspy.InputField()
    label: str = dspy.OutputField(desc="One of: POSITIVE, NEGATIVE, NEUTRAL")
 
module = dspy.ChainOfThought(Sentiment)
 
# 2. Define a metric — feedback is what the optimizer learns from
def metric(example, pred):
    expected = example["label"]
    actual = pred.label.strip().upper()
    return vizpy.Score(
        value=1.0 if expected == actual else 0.0,
        is_success=expected == actual,
        feedback="" if expected == actual else f"Expected {expected}, got {actual}.",
    )
 
# 3. A handful of labelled examples
train = [
    {"review": "Broke after one week.", "label": "NEGATIVE"},
    {"review": "Exceeded my expectations, very happy.", "label": "POSITIVE"},
    {"review": "Works as described, nothing special.", "label": "NEUTRAL"},
    {"review": "Stopped working on day two.", "label": "NEGATIVE"},
    {"review": "Solid build quality, does exactly what it promises.", "label": "POSITIVE"},
]
 
# 4. Optimize
optimizer = vizpy.ContraPromptOptimizer(metric=metric)
optimized = optimizer.optimize(module, train_examples=train)
 
# 5. Use the result — same interface, better instructions
print(optimized(review="Feels cheap and the buttons stick.").label)  # NEGATIVE

# Hosted API
dspy.configure(lm=dspy.LM("openai/gpt-4o-mini"))
dspy.configure(lm=dspy.LM("anthropic/claude-haiku-4-5-20251001"))
 
# Self-hosted via Ollama
dspy.configure(lm=dspy.LM("ollama/llama3", api_base="http://localhost:11434"))
 
# Any OpenAI-compatible endpoint (vLLM, LM Studio, internal proxy, etc.)
dspy.configure(lm=dspy.LM("openai/your-model", api_base="http://your-host/v1", api_key="..."))

import dspy
import vizpy
 
dspy.configure(lm=dspy.LM("openai/gpt-4o-mini"))
 
class EmailUrgency(dspy.Signature):
    """Classify the urgency level of an email."""
    email: str = dspy.InputField()
    urgency: str = dspy.OutputField(desc="One of: CRITICAL, HIGH, MEDIUM, LOW")
 
module = dspy.ChainOfThought(EmailUrgency)
 
# Before optimization
test = "Blocking our sprint. Tests failing, can't merge. Need help ASAP."
print(module(email=test).urgency)   # CRITICAL  ← wrong, this is HIGH
 
# Metric feedback tells the optimizer *why* it's wrong
def metric(example, prediction):
    expected, actual = example["gold_urgency"], prediction.urgency.strip().upper()
    is_correct = expected == actual
    feedback = (
        "CRITICAL = customer-facing outage/breach. Workflow blockers = HIGH."
        if not is_correct and expected == "HIGH" and actual == "CRITICAL" else
        f"Expected {expected}, got {actual}." if not is_correct else ""
    )
    return vizpy.Score(value=1.0 if is_correct else 0.0, is_success=is_correct, feedback=feedback)
 
optimizer = vizpy.PromptGradOptimizer(metric=metric)
optimized = optimizer.optimize(module, train_examples, val_examples)
 
# After optimization
print(optimized(email=test).urgency)  # HIGH  ← correct