Quickstart

Three steps: define your task, write a metric, call optimize(). That's it.

Installation

pip install vizpy

Set Your API Keys

export VIZPY_API_KEY=your_vizpy_license_key    # from vizpy.vizops.ai/dashboard
export OPENAI_API_KEY=your_openai_key

Example: Customer Support Routing

GPT-4o-mini confuses billing and account tickets — password resets get routed to billing, invoice questions go to account. The optimizer learns the boundary from your labelled examples.

import dspy
import vizpy
 
dspy.configure(lm=dspy.LM("openai/gpt-4o-mini"))
 
 
# 1. Define your task
class SupportRoute(dspy.Signature):
    """Route a customer support message to the correct team."""
    message: str = dspy.InputField()
    team: str = dspy.OutputField(desc="One of: billing, technical, account, general")
 
 
module = dspy.Predict(SupportRoute)
 
 
# 2. Label a small dataset
examples = [
    {"message": "My card was charged twice this month.", "team": "billing"},
    {"message": "The app crashes when I tap checkout.", "team": "technical"},
    {"message": "I need to reset my password.", "team": "account"},
    {"message": "What are your support hours?", "team": "general"},
    {"message": "I was billed after I cancelled my subscription.", "team": "billing"},
    {"message": "Error 500 on the login page.", "team": "technical"},
    {"message": "How do I update my email address?", "team": "account"},
    {"message": "Do you have a phone number I can call?", "team": "general"},
    {"message": "Charged for a plan I never signed up for.", "team": "billing"},
    {"message": "Push notifications stopped working on iOS.", "team": "technical"},
]
 
 
# 3. Write a metric — feedback is what drives optimization
def metric(example, prediction):
    correct = prediction.team.lower() == example["team"].lower()
    return vizpy.Score(
        value=1.0 if correct else 0.0,
        is_success=correct,
        feedback=(
            f"Should route to '{example['team']}', got '{prediction.team}'. "
            f"Billing = charges/invoices. Account = settings/credentials."
        ) if not correct else "",
    )
 
 
# 4. Optimize
optimizer = vizpy.ContraPromptOptimizer(metric=metric)
optimized = optimizer.optimize(module, examples)
 
 
# Use the optimized module
result = optimized(message="Still being invoiced after I cancelled — need a refund.")
print(result.team)  # billing

What Happens

Baseline — the model conflates account management with billing because the instructions don't distinguish them
Contrastive mining — the optimizer finds bad→good pairs (e.g. password reset labelled account, not billing) and extracts rules from the difference
Rule validation — each candidate rule is tested on held-out examples; rules that hurt performance are discarded
Result — the optimized module's instructions now include precise team definitions extracted from your data

Key Concepts

Concept	Description
Module	A DSPy module wrapping your LLM task (Signature + Predict/ChainOfThought)
Metric	Scores each prediction. Returns a `vizpy.Score` with `value`, `is_success`, and `feedback`
Feedback	The most critical field — tells the optimizer why a prediction is wrong. Richer feedback → better rules
Train examples	Input-only dicts the optimizer learns from. Store expected outputs in your metric