Files
skills/public/dspy-assertions.html
zeekayandHanzo Dev 9e10c1c10e Each llms index points at the other two
hanzoskills.com/llms.txt now opens with the install line, the API
reference index and the company index, so an agent that lands on any
one of the three can find the rest.

robots.txt claimed 537 documents while llms.txt counts 920. The number
is gone from robots.txt; llms.txt derives it.

public/ is regenerated from scripts/site.py, which it had fallen
behind: the copy-prompt menu and agent bar were in the generator and
not in the committed pages. tests/site.mjs passes against the result.

Co-authored-by: Hanzo Dev <[email protected]>
2026-09-11 00:27:59 -07:00

690 lines
30 KiB
HTML

<!doctype html>
<html lang="en"><head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>dspy-assertions</title>
<meta name="color-scheme" content="dark">
<style>
/* Committed to one visual world: a dark instrument panel. No light variant —
the dot field and the hairline rules only read on black, and a naive
inversion would wash both out. Every colour is painted explicitly so the page
never borrows a host background. */
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
:root{
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
--font-zen-pixel-square:'Zen Pixel Square',monospace;
--mono:var(--font-zen-mono);
--sans:var(--font-zen-sans);
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
--r:999px; --r-soft:14px;
}
*{box-sizing:border-box}
html{-webkit-text-size-adjust:100%}
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
/* The dot field. A halftone made of one repeating radial-gradient, faded out
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
/* No overflow clip here: the dot field is inset to the box already, and a clip
would cut off the copy-prompt menu. */
.hero{position:relative;border-bottom:1px solid var(--line)}
.hero::before{content:"";position:absolute;inset:0;
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
background-size:7px 7px;
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
pointer-events:none}
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
nav{border-bottom:1px solid var(--line)}
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
justify-content:space-between;align-items:center;gap:1rem}
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--ink);text-decoration:none;
display:inline-flex;align-items:center;gap:.6rem}
.brand i{font-style:normal;color:var(--faint)}
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--soft);text-decoration:none}
nav a.up:hover{color:var(--ink)}
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
h1 em{font-style:normal;color:var(--faint)}
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
line-height:1.2;font-weight:400}
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
.btn.solid:hover{background:#d8d8d4}
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
/* Copy-prompt selector. Each row copies the prompt for its own target. */
.copy{position:relative;display:inline-flex}
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
padding:.4rem;display:flex;flex-direction:column;
box-shadow:0 12px 32px rgba(0,0,0,.75)}
.menu[hidden]{display:none}
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
white-space:nowrap}
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
.mi:hover .mark{color:var(--ink)}
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
letter-spacing:.1em;text-transform:uppercase}
/* Works-with bar: one scrolling row, name and mark per agent. */
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
display:flex;align-items:center}
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
-webkit-overflow-scrolling:touch;
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
.bar::-webkit-scrollbar{display:none}
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
text-decoration:none;background:var(--ground)}
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
.agent .mark{width:.95rem;height:.95rem}
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
p{margin:0 0 1rem;max-width:70ch}
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
li{margin:.22rem 0}
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
text-decoration-color:var(--line-hi)}
a:hover{text-decoration-color:var(--ink)}
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
display:block;overflow-x:auto}
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
.curl{display:block;background:var(--panel);border:1px solid var(--line);
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
white-space:pre;line-height:1.9}
.curl b{color:var(--ink);font-weight:400}
.curl i{font-style:normal;color:var(--faint)}
/* index */
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
#q:focus{outline:none;border-color:var(--soft)}
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
text-transform:uppercase;margin:0 0 2rem}
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
padding-bottom:.45rem}
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
border-radius:var(--r-soft);text-decoration:none}
.row:hover{background:#0a0a0a}
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
color:var(--faint);font-size:.85rem}
footer a{color:var(--soft)}
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
margin:0 0 2rem;font-size:.85rem}
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
border-bottom:1px solid var(--line);padding-bottom:.4rem}
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
.fmap a:hover{text-decoration:underline}
.fmap div{color:var(--faint);line-height:1.5}
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
@media (max-width:640px){
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
.btns{gap:.5rem}
.btn{padding:.75rem 1.15rem;font-size:.68rem}
.copy,.copy .btn{width:100%;justify-content:center}
.menu{left:0;right:0;min-width:0}
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
.strip b{border-right:0;padding-right:0}
.bar{width:100%}
}
</style>
<link rel="alternate" type="text/markdown" href="/dspy-assertions.md">
<link rel="icon" href="/favicon.svg">
<link rel="canonical" href="https://hanzoskills.com/dspy-assertions">
</head>
<!-- Reading this with a machine? Every page here is also plain markdown.
This one: https://hanzoskills.com/dspy-assertions.md
Index: https://hanzoskills.com/llms.txt
Corpus: https://hanzoskills.com/all.md
Append .md to any path for the markdown twin. -->
<body>
<nav><div class="in">
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
<a class="up" href="/">All skills</a>
</div></nav>
<div class="wrap">
<h1>dspy-assertions</h1><p class="lede">Adding constraints and validation to DSPy programs with assertions and suggestions</p><h1>DSPy Assertions</h1>
<p><strong>Scope</strong>: dspy.Assert, dspy.Suggest, output validation, constraints, retry logic <strong>Lines</strong>: ~380 <strong>Last Updated</strong>: 2025-10-25</p>
<h2>When to Use This Skill</h2>
<p>Activate this skill when:</p>
<ul><li>Validating DSPy module outputs meet specific criteria</li><li>Enforcing constraints on generated content (length, format, values)</li><li>Implementing automatic retry with feedback</li><li>Reducing invalid or low-quality predictions</li><li>Adding guardrails to LM behavior</li><li>Debugging module failures with better error messages</li></ul>
<h2>Core Concepts</h2>
<h3>Assertions in DSPy</h3>
<p><strong>Definition</strong>: Runtime checks that validate module outputs</p>
<p><strong>Purpose</strong>:</p>
<ul><li><strong>Quality control</strong>: Ensure outputs meet requirements</li><li><strong>Constraint enforcement</strong>: Length limits, format requirements, value ranges</li><li><strong>Self-correction</strong>: Automatic retry with feedback</li><li><strong>Debugging</strong>: Clear error messages when validation fails</li></ul>
<p><strong>Key insight</strong>: Assertions make LM programs more reliable by catching and fixing errors</p>
<h3>Assertion Types</h3>
<p><strong>dspy.Assert</strong>: Hard constraint (must pass)</p>
<ul><li>Raises error if validation fails</li><li>Stops execution</li><li>Use for critical requirements</li></ul>
<p><strong>dspy.Suggest</strong>: Soft constraint (should pass)</p>
<ul><li>Logs warning if validation fails</li><li>Continues execution</li><li>Attempts retry with feedback</li><li>Use for quality improvements</li></ul>
<h3>How Assertions Work</h3>
<p><strong>Workflow</strong>:</p>
<ol><li>Module produces output</li><li>Assertion validates output</li><li>If validation fails:</li></ol>
<ul><li><strong>Assert</strong>: Raises error</li><li><strong>Suggest</strong>: Provides feedback and retries</li></ul>
<ol><li>If validation passes: Continue</li></ol>
<p><strong>Retry mechanism</strong>:</p>
<ul><li>Failed suggestion triggers automatic retry</li><li>Feedback message added to prompt</li><li>LM gets chance to self-correct</li><li>Configurable max retries</li></ul>
<hr>
<h2>Patterns</h2>
<h3>Pattern 1: Basic Assertion</h3>
<pre><code class="lang-python">import dspy
class ValidatedQA(dspy.Module):
def __init__(self):
super().__init__()
self.generate = dspy.ChainOfThought(&quot;question -&gt; answer&quot;)
def forward(self, question):
result = self.generate(question=question)
# Assert answer is non-empty
dspy.Assert(
len(result.answer.strip()) &gt; 0,
&quot;Answer cannot be empty&quot;
)
# Assert answer is not too long
dspy.Assert(
len(result.answer.split()) &lt;= 100,
&quot;Answer must be 100 words or less&quot;
)
return result
# Use validated module
qa = ValidatedQA()
try:
result = qa(question=&quot;What is DSPy?&quot;)
print(result.answer)
except AssertionError as e:
print(f&quot;Validation failed: {e}&quot;)</code></pre>
<p><strong>When to use</strong>:</p>
<ul><li>Critical constraints that cannot be violated</li><li>Hard format requirements</li><li>Safety checks</li></ul>
<h3>Pattern 2: Suggestion with Retry</h3>
<pre><code class="lang-python">import dspy
class SuggestedQA(dspy.Module):
def __init__(self):
super().__init__()
self.generate = dspy.ChainOfThought(&quot;question -&gt; answer&quot;)
def forward(self, question):
result = self.generate(question=question)
# Suggest (not require) concise answer
dspy.Suggest(
len(result.answer.split()) &lt;= 50,
&quot;Please provide a more concise answer (50 words or less)&quot;
)
# Suggest answer includes specific keyword (if applicable)
if &quot;framework&quot; in question.lower():
dspy.Suggest(
&quot;framework&quot; in result.answer.lower(),
&quot;Answer should mention &#x27;framework&#x27; since question asks about it&quot;
)
return result
# Use with suggestions
qa = SuggestedQA()
result = qa(question=&quot;What is DSPy?&quot;)
print(result.answer)
# If suggestions fail, DSPy automatically retries with feedback</code></pre>
<p><strong>How it works</strong>:</p>
<ol><li>First attempt produces answer</li><li>Suggestion validates answer</li><li>If validation fails, DSPy retries with feedback message</li><li>LM sees feedback and adjusts output</li><li>Process repeats until validation passes or max retries reached</li></ol>
<h3>Pattern 3: Format Validation</h3>
<pre><code class="lang-python">import dspy
import json
class JSONGenerator(dspy.Module):
&quot;&quot;&quot;Generate valid JSON output.&quot;&quot;&quot;
def __init__(self):
super().__init__()
self.generate = dspy.ChainOfThought(
&quot;description -&gt; json_output: str&quot;
)
def forward(self, description):
result = self.generate(description=description)
# Assert output is valid JSON
try:
parsed = json.loads(result.json_output)
is_valid_json = True
except json.JSONDecodeError:
is_valid_json = False
dspy.Assert(
is_valid_json,
&quot;Output must be valid JSON&quot;
)
# Suggest specific structure
dspy.Suggest(
isinstance(parsed, dict),
&quot;JSON should be an object (not array or primitive)&quot;
)
dspy.Suggest(
&quot;name&quot; in parsed and &quot;value&quot; in parsed,
&quot;JSON should contain &#x27;name&#x27; and &#x27;value&#x27; fields&quot;
)
return dspy.Prediction(
json_output=result.json_output,
parsed=parsed
)
# Use JSON generator
gen = JSONGenerator()
result = gen(description=&quot;Create a person object with name John and age 30&quot;)
print(result.parsed) # {&#x27;name&#x27;: &#x27;John&#x27;, &#x27;value&#x27;: 30}</code></pre>
<p><strong>When to use</strong>:</p>
<ul><li>Generating structured outputs (JSON, XML, CSV)</li><li>Parsing validation</li><li>Schema compliance</li></ul>
<h3>Pattern 4: Value Range Constraints</h3>
<pre><code class="lang-python">import dspy
class ScoringModule(dspy.Module):
&quot;&quot;&quot;Generate scores with validation.&quot;&quot;&quot;
def __init__(self):
super().__init__()
self.score = dspy.ChainOfThought(
&quot;text -&gt; score: float, explanation&quot;
)
def forward(self, text):
result = self.score(text=text)
# Convert score to float
try:
score_value = float(result.score)
except:
score_value = 0.0
# Assert score is in valid range
dspy.Assert(
0.0 &lt;= score_value &lt;= 1.0,
&quot;Score must be between 0.0 and 1.0&quot;
)
# Suggest explanation is provided
dspy.Suggest(
len(result.explanation.split()) &gt;= 5,
&quot;Provide a more detailed explanation (at least 5 words)&quot;
)
return dspy.Prediction(
score=score_value,
explanation=result.explanation
)
# Use scoring module
scorer = ScoringModule()
result = scorer(text=&quot;This is a great product!&quot;)
print(f&quot;Score: {result.score}&quot;)
print(f&quot;Explanation: {result.explanation}&quot;)</code></pre>
<p><strong>When to use</strong>:</p>
<ul><li>Numeric outputs with valid ranges</li><li>Ratings, scores, percentages</li><li>Confidence values</li></ul>
<h3>Pattern 5: Content Validation</h3>
<pre><code class="lang-python">import dspy
class SafeContentGenerator(dspy.Module):
&quot;&quot;&quot;Generate content with safety checks.&quot;&quot;&quot;
def __init__(self):
super().__init__()
self.generate = dspy.ChainOfThought(&quot;topic -&gt; content&quot;)
def forward(self, topic):
result = self.generate(topic=topic)
# List of banned words/topics
banned_words = [&quot;inappropriate&quot;, &quot;offensive&quot;, &quot;harmful&quot;]
# Assert no banned content
contains_banned = any(
word in result.content.lower()
for word in banned_words
)
dspy.Assert(
not contains_banned,
&quot;Content contains inappropriate language&quot;
)
# Suggest minimum quality
dspy.Suggest(
len(result.content.split()) &gt;= 20,
&quot;Content should be at least 20 words for good quality&quot;
)
# Suggest proper punctuation
dspy.Suggest(
result.content.strip().endswith((&#x27;.&#x27;, &#x27;!&#x27;, &#x27;?&#x27;)),
&quot;Content should end with proper punctuation&quot;
)
return result
# Use safe generator
gen = SafeContentGenerator()
result = gen(topic=&quot;artificial intelligence&quot;)
print(result.content)</code></pre>
<p><strong>When to use</strong>:</p>
<ul><li>Content moderation</li><li>Safety filters</li><li>Quality guidelines</li></ul>
<h3>Pattern 6: Multi-Field Validation</h3>
<pre><code class="lang-python">import dspy
class EntityExtractor(dspy.Module):
&quot;&quot;&quot;Extract entities with validation.&quot;&quot;&quot;
def __init__(self):
super().__init__()
self.extract = dspy.ChainOfThought(
&quot;text -&gt; entities: list[str], entity_types: list[str], confidence: float&quot;
)
def forward(self, text):
result = self.extract(text=text)
# Parse list fields (may be comma-separated strings)
if isinstance(result.entities, str):
entities = [e.strip() for e in result.entities.split(&quot;,&quot;)]
else:
entities = result.entities
if isinstance(result.entity_types, str):
entity_types = [t.strip() for t in result.entity_types.split(&quot;,&quot;)]
else:
entity_types = result.entity_types
# Assert lists have same length
dspy.Assert(
len(entities) == len(entity_types),
&quot;Number of entities must match number of entity types&quot;
)
# Suggest at least one entity found
dspy.Suggest(
len(entities) &gt; 0,
&quot;Try to find at least one entity in the text&quot;
)
# Validate confidence
try:
conf = float(result.confidence)
except:
conf = 0.5
dspy.Suggest(
0.0 &lt;= conf &lt;= 1.0,
&quot;Confidence should be between 0 and 1&quot;
)
return dspy.Prediction(
entities=entities,
entity_types=entity_types,
confidence=conf
)
# Use entity extractor
extractor = EntityExtractor()
result = extractor(text=&quot;Apple Inc. was founded by Steve Jobs in California.&quot;)
print(f&quot;Entities: {result.entities}&quot;)
print(f&quot;Types: {result.entity_types}&quot;)</code></pre>
<p><strong>When to use</strong>:</p>
<ul><li>Multi-field outputs with dependencies</li><li>List/array outputs</li><li>Structured extraction tasks</li></ul>
<h3>Pattern 7: Custom Validation Functions</h3>
<pre><code class="lang-python">import dspy
def is_valid_email(email: str) -&gt; bool:
&quot;&quot;&quot;Simple email validation.&quot;&quot;&quot;
return &quot;@&quot; in email and &quot;.&quot; in email.split(&quot;@&quot;)[1]
def is_valid_phone(phone: str) -&gt; bool:
&quot;&quot;&quot;Simple phone validation.&quot;&quot;&quot;
digits = &quot;&quot;.join(c for c in phone if c.isdigit())
return len(digits) &gt;= 10
class ContactExtractor(dspy.Module):
&quot;&quot;&quot;Extract contact information with validation.&quot;&quot;&quot;
def __init__(self):
super().__init__()
self.extract = dspy.ChainOfThought(
&quot;text -&gt; email, phone, name&quot;
)
def forward(self, text):
result = self.extract(text=text)
# Validate email format
dspy.Suggest(
is_valid_email(result.email),
&quot;Email should be in valid format ([email protected])&quot;
)
# Validate phone format
dspy.Suggest(
is_valid_phone(result.phone),
&quot;Phone should contain at least 10 digits&quot;
)
# Validate name is not empty
dspy.Assert(
len(result.name.strip()) &gt; 0,
&quot;Name cannot be empty&quot;
)
return result
# Use contact extractor
extractor = ContactExtractor()
result = extractor(text=&quot;Contact John Doe at [email protected] or (555) 123-4567&quot;)
print(f&quot;Name: {result.name}&quot;)
print(f&quot;Email: {result.email}&quot;)
print(f&quot;Phone: {result.phone}&quot;)</code></pre>
<p><strong>Benefits</strong>:</p>
<ul><li>Reusable validation logic</li><li>Domain-specific checks</li><li>Clear separation of concerns</li></ul>
<h3>Pattern 8: Assertion with Backoff</h3>
<pre><code class="lang-python">import dspy
class RobustGenerator(dspy.Module):
&quot;&quot;&quot;Generator with configurable assertion retries.&quot;&quot;&quot;
def __init__(self, max_retries=3):
super().__init__()
self.max_retries = max_retries
self.generate = dspy.ChainOfThought(&quot;prompt -&gt; response&quot;)
def forward(self, prompt):
for attempt in range(self.max_retries):
try:
result = self.generate(prompt=prompt)
# Validations
dspy.Assert(
len(result.response.strip()) &gt; 0,
&quot;Response cannot be empty&quot;
)
dspy.Suggest(
len(result.response.split()) &gt;= 10,
&quot;Response should be at least 10 words&quot;
)
# If we get here, validation passed
return result
except AssertionError as e:
if attempt == self.max_retries - 1:
# Last attempt failed, re-raise
raise
# Otherwise, retry (DSPy handles this automatically for Suggest)
print(f&quot;Attempt {attempt + 1} failed: {e}&quot;)
# Should not reach here
raise AssertionError(&quot;All retries exhausted&quot;)
# Use robust generator
gen = RobustGenerator(max_retries=3)
result = gen(prompt=&quot;Explain quantum computing&quot;)</code></pre>
<p><strong>When to use</strong>:</p>
<ul><li>Production systems requiring reliability</li><li>Handling transient validation failures</li><li>Custom retry logic</li></ul>
<hr>
<h2>Quick Reference</h2>
<h3>Assertion Syntax</h3>
<pre><code class="lang-python"># Assert (hard requirement)
dspy.Assert(
condition,
&quot;Error message if condition is False&quot;
)
# Suggest (soft requirement with retry)
dspy.Suggest(
condition,
&quot;Feedback message for retry if condition is False&quot;
)</code></pre>
<h3>Common Validations</h3>
<pre><code class="lang-python"># Non-empty
dspy.Assert(len(output.strip()) &gt; 0, &quot;Output cannot be empty&quot;)
# Length constraint
dspy.Suggest(len(output.split()) &lt;= 100, &quot;Keep under 100 words&quot;)
# Numeric range
dspy.Assert(0.0 &lt;= score &lt;= 1.0, &quot;Score must be 0-1&quot;)
# Format check
dspy.Assert(is_valid_json(output), &quot;Must be valid JSON&quot;)
# Content safety
dspy.Assert(is_safe(output), &quot;Contains inappropriate content&quot;)
# List length
dspy.Assert(len(list1) == len(list2), &quot;Lists must match&quot;)</code></pre>
<h3>Best Practices</h3>
<pre><code>✅ DO: Use Assert for critical constraints
✅ DO: Use Suggest for quality improvements
✅ DO: Provide clear, actionable error messages
✅ DO: Validate early (before expensive operations)
✅ DO: Use custom validation functions for reusability
❌ DON&#x27;T: Over-constrain (too many assertions = failures)
❌ DON&#x27;T: Use vague error messages (&quot;invalid output&quot;)
❌ DON&#x27;T: Assert on things LM can&#x27;t control
❌ DON&#x27;T: Forget to handle validation failures in production</code></pre>
<hr>
<h2>Anti-Patterns</h2>
<p>❌ <strong>Too many assertions</strong>: Over-constrained, frequent failures</p>
<pre><code class="lang-python"># Bad - too restrictive
dspy.Assert(len(output) == 42, &quot;Must be exactly 42 characters&quot;)
dspy.Assert(&quot;the&quot; in output, &quot;Must contain &#x27;the&#x27;&quot;)
dspy.Assert(output.startswith(&quot;Answer:&quot;), &quot;Must start with &#x27;Answer:&#x27;&quot;)
# ... 10 more assertions</code></pre>
<p>✅ Use only essential constraints:</p>
<pre><code class="lang-python"># Good - essential constraints only
dspy.Assert(len(output.strip()) &gt; 0, &quot;Output required&quot;)
dspy.Suggest(len(output.split()) &lt;= 100, &quot;Prefer concise answers&quot;)</code></pre>
<p>❌ <strong>Vague error messages</strong>: Don&#x27;t help LM self-correct</p>
<pre><code class="lang-python"># Bad
dspy.Suggest(condition, &quot;Invalid&quot;)</code></pre>
<p>✅ Provide actionable feedback:</p>
<pre><code class="lang-python"># Good
dspy.Suggest(condition, &quot;Answer should be 2-3 sentences with specific examples&quot;)</code></pre>
<p>❌ <strong>No error handling</strong>: Crashes in production</p>
<pre><code class="lang-python"># Bad
result = module(input) # May raise AssertionError
return result.output</code></pre>
<p>✅ Handle validation failures:</p>
<pre><code class="lang-python"># Good
try:
result = module(input)
return result.output
except AssertionError as e:
log_error(e)
return fallback_response()</code></pre>
<hr>
<h2>Related Skills</h2>
<ul><li><code>dspy-modules.md</code> - Adding assertions to modules</li><li><code>dspy-evaluation.md</code> - Validation vs evaluation</li><li><code>dspy-optimizers.md</code> - Optimizing with constraints</li><li><code>api/api-error-handling.md</code> - Error handling patterns</li></ul>
<hr>
<p><strong>Last Updated</strong>: 2025-10-25 <strong>Format Version</strong>: 1.0 (Atomic)</p>
<footer>
<div class="fmap">
<div><b>Build</b>
<a href="https://hanzo.app">hanzo.app</a> app builder
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
<div><b>Run</b>
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
<div><b>Account</b>
<a href="https://hanzo.id">hanzo.id</a> sign in
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
<div><b>Company</b>
<a href="https://hanzo.ai">hanzo.ai</a> canonical
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
</div>
<div class="fend"><a href="/dspy-assertions.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
</footer>
</div></body></html>