mirror of
https://github.com/hanzoai/skills.git
synced 2026-11-19 00:47:36 +00:00
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]>
690 lines
30 KiB
HTML
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("question -> answer")
|
|
|
|
def forward(self, question):
|
|
result = self.generate(question=question)
|
|
|
|
# Assert answer is non-empty
|
|
dspy.Assert(
|
|
len(result.answer.strip()) > 0,
|
|
"Answer cannot be empty"
|
|
)
|
|
|
|
# Assert answer is not too long
|
|
dspy.Assert(
|
|
len(result.answer.split()) <= 100,
|
|
"Answer must be 100 words or less"
|
|
)
|
|
|
|
return result
|
|
|
|
# Use validated module
|
|
qa = ValidatedQA()
|
|
|
|
try:
|
|
result = qa(question="What is DSPy?")
|
|
print(result.answer)
|
|
except AssertionError as e:
|
|
print(f"Validation failed: {e}")</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("question -> answer")
|
|
|
|
def forward(self, question):
|
|
result = self.generate(question=question)
|
|
|
|
# Suggest (not require) concise answer
|
|
dspy.Suggest(
|
|
len(result.answer.split()) <= 50,
|
|
"Please provide a more concise answer (50 words or less)"
|
|
)
|
|
|
|
# Suggest answer includes specific keyword (if applicable)
|
|
if "framework" in question.lower():
|
|
dspy.Suggest(
|
|
"framework" in result.answer.lower(),
|
|
"Answer should mention 'framework' since question asks about it"
|
|
)
|
|
|
|
return result
|
|
|
|
# Use with suggestions
|
|
qa = SuggestedQA()
|
|
result = qa(question="What is DSPy?")
|
|
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):
|
|
"""Generate valid JSON output."""
|
|
|
|
def __init__(self):
|
|
super().__init__()
|
|
self.generate = dspy.ChainOfThought(
|
|
"description -> json_output: str"
|
|
)
|
|
|
|
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,
|
|
"Output must be valid JSON"
|
|
)
|
|
|
|
# Suggest specific structure
|
|
dspy.Suggest(
|
|
isinstance(parsed, dict),
|
|
"JSON should be an object (not array or primitive)"
|
|
)
|
|
|
|
dspy.Suggest(
|
|
"name" in parsed and "value" in parsed,
|
|
"JSON should contain 'name' and 'value' fields"
|
|
)
|
|
|
|
return dspy.Prediction(
|
|
json_output=result.json_output,
|
|
parsed=parsed
|
|
)
|
|
|
|
# Use JSON generator
|
|
gen = JSONGenerator()
|
|
result = gen(description="Create a person object with name John and age 30")
|
|
print(result.parsed) # {'name': 'John', 'value': 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):
|
|
"""Generate scores with validation."""
|
|
|
|
def __init__(self):
|
|
super().__init__()
|
|
self.score = dspy.ChainOfThought(
|
|
"text -> score: float, explanation"
|
|
)
|
|
|
|
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 <= score_value <= 1.0,
|
|
"Score must be between 0.0 and 1.0"
|
|
)
|
|
|
|
# Suggest explanation is provided
|
|
dspy.Suggest(
|
|
len(result.explanation.split()) >= 5,
|
|
"Provide a more detailed explanation (at least 5 words)"
|
|
)
|
|
|
|
return dspy.Prediction(
|
|
score=score_value,
|
|
explanation=result.explanation
|
|
)
|
|
|
|
# Use scoring module
|
|
scorer = ScoringModule()
|
|
result = scorer(text="This is a great product!")
|
|
print(f"Score: {result.score}")
|
|
print(f"Explanation: {result.explanation}")</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):
|
|
"""Generate content with safety checks."""
|
|
|
|
def __init__(self):
|
|
super().__init__()
|
|
self.generate = dspy.ChainOfThought("topic -> content")
|
|
|
|
def forward(self, topic):
|
|
result = self.generate(topic=topic)
|
|
|
|
# List of banned words/topics
|
|
banned_words = ["inappropriate", "offensive", "harmful"]
|
|
|
|
# Assert no banned content
|
|
contains_banned = any(
|
|
word in result.content.lower()
|
|
for word in banned_words
|
|
)
|
|
|
|
dspy.Assert(
|
|
not contains_banned,
|
|
"Content contains inappropriate language"
|
|
)
|
|
|
|
# Suggest minimum quality
|
|
dspy.Suggest(
|
|
len(result.content.split()) >= 20,
|
|
"Content should be at least 20 words for good quality"
|
|
)
|
|
|
|
# Suggest proper punctuation
|
|
dspy.Suggest(
|
|
result.content.strip().endswith(('.', '!', '?')),
|
|
"Content should end with proper punctuation"
|
|
)
|
|
|
|
return result
|
|
|
|
# Use safe generator
|
|
gen = SafeContentGenerator()
|
|
result = gen(topic="artificial intelligence")
|
|
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):
|
|
"""Extract entities with validation."""
|
|
|
|
def __init__(self):
|
|
super().__init__()
|
|
self.extract = dspy.ChainOfThought(
|
|
"text -> entities: list[str], entity_types: list[str], confidence: float"
|
|
)
|
|
|
|
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(",")]
|
|
else:
|
|
entities = result.entities
|
|
|
|
if isinstance(result.entity_types, str):
|
|
entity_types = [t.strip() for t in result.entity_types.split(",")]
|
|
else:
|
|
entity_types = result.entity_types
|
|
|
|
# Assert lists have same length
|
|
dspy.Assert(
|
|
len(entities) == len(entity_types),
|
|
"Number of entities must match number of entity types"
|
|
)
|
|
|
|
# Suggest at least one entity found
|
|
dspy.Suggest(
|
|
len(entities) > 0,
|
|
"Try to find at least one entity in the text"
|
|
)
|
|
|
|
# Validate confidence
|
|
try:
|
|
conf = float(result.confidence)
|
|
except:
|
|
conf = 0.5
|
|
|
|
dspy.Suggest(
|
|
0.0 <= conf <= 1.0,
|
|
"Confidence should be between 0 and 1"
|
|
)
|
|
|
|
return dspy.Prediction(
|
|
entities=entities,
|
|
entity_types=entity_types,
|
|
confidence=conf
|
|
)
|
|
|
|
# Use entity extractor
|
|
extractor = EntityExtractor()
|
|
result = extractor(text="Apple Inc. was founded by Steve Jobs in California.")
|
|
print(f"Entities: {result.entities}")
|
|
print(f"Types: {result.entity_types}")</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) -> bool:
|
|
"""Simple email validation."""
|
|
return "@" in email and "." in email.split("@")[1]
|
|
|
|
def is_valid_phone(phone: str) -> bool:
|
|
"""Simple phone validation."""
|
|
digits = "".join(c for c in phone if c.isdigit())
|
|
return len(digits) >= 10
|
|
|
|
class ContactExtractor(dspy.Module):
|
|
"""Extract contact information with validation."""
|
|
|
|
def __init__(self):
|
|
super().__init__()
|
|
self.extract = dspy.ChainOfThought(
|
|
"text -> email, phone, name"
|
|
)
|
|
|
|
def forward(self, text):
|
|
result = self.extract(text=text)
|
|
|
|
# Validate email format
|
|
dspy.Suggest(
|
|
is_valid_email(result.email),
|
|
"Email should be in valid format ([email protected])"
|
|
)
|
|
|
|
# Validate phone format
|
|
dspy.Suggest(
|
|
is_valid_phone(result.phone),
|
|
"Phone should contain at least 10 digits"
|
|
)
|
|
|
|
# Validate name is not empty
|
|
dspy.Assert(
|
|
len(result.name.strip()) > 0,
|
|
"Name cannot be empty"
|
|
)
|
|
|
|
return result
|
|
|
|
# Use contact extractor
|
|
extractor = ContactExtractor()
|
|
result = extractor(text="Contact John Doe at [email protected] or (555) 123-4567")
|
|
print(f"Name: {result.name}")
|
|
print(f"Email: {result.email}")
|
|
print(f"Phone: {result.phone}")</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):
|
|
"""Generator with configurable assertion retries."""
|
|
|
|
def __init__(self, max_retries=3):
|
|
super().__init__()
|
|
self.max_retries = max_retries
|
|
self.generate = dspy.ChainOfThought("prompt -> response")
|
|
|
|
def forward(self, prompt):
|
|
for attempt in range(self.max_retries):
|
|
try:
|
|
result = self.generate(prompt=prompt)
|
|
|
|
# Validations
|
|
dspy.Assert(
|
|
len(result.response.strip()) > 0,
|
|
"Response cannot be empty"
|
|
)
|
|
|
|
dspy.Suggest(
|
|
len(result.response.split()) >= 10,
|
|
"Response should be at least 10 words"
|
|
)
|
|
|
|
# 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"Attempt {attempt + 1} failed: {e}")
|
|
|
|
# Should not reach here
|
|
raise AssertionError("All retries exhausted")
|
|
|
|
# Use robust generator
|
|
gen = RobustGenerator(max_retries=3)
|
|
result = gen(prompt="Explain quantum computing")</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,
|
|
"Error message if condition is False"
|
|
)
|
|
|
|
# Suggest (soft requirement with retry)
|
|
dspy.Suggest(
|
|
condition,
|
|
"Feedback message for retry if condition is False"
|
|
)</code></pre>
|
|
<h3>Common Validations</h3>
|
|
<pre><code class="lang-python"># Non-empty
|
|
dspy.Assert(len(output.strip()) > 0, "Output cannot be empty")
|
|
|
|
# Length constraint
|
|
dspy.Suggest(len(output.split()) <= 100, "Keep under 100 words")
|
|
|
|
# Numeric range
|
|
dspy.Assert(0.0 <= score <= 1.0, "Score must be 0-1")
|
|
|
|
# Format check
|
|
dspy.Assert(is_valid_json(output), "Must be valid JSON")
|
|
|
|
# Content safety
|
|
dspy.Assert(is_safe(output), "Contains inappropriate content")
|
|
|
|
# List length
|
|
dspy.Assert(len(list1) == len(list2), "Lists must match")</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'T: Over-constrain (too many assertions = failures)
|
|
❌ DON'T: Use vague error messages ("invalid output")
|
|
❌ DON'T: Assert on things LM can't control
|
|
❌ DON'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, "Must be exactly 42 characters")
|
|
dspy.Assert("the" in output, "Must contain 'the'")
|
|
dspy.Assert(output.startswith("Answer:"), "Must start with 'Answer:'")
|
|
# ... 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()) > 0, "Output required")
|
|
dspy.Suggest(len(output.split()) <= 100, "Prefer concise answers")</code></pre>
|
|
<p>❌ <strong>Vague error messages</strong>: Don't help LM self-correct</p>
|
|
<pre><code class="lang-python"># Bad
|
|
dspy.Suggest(condition, "Invalid")</code></pre>
|
|
<p>✅ Provide actionable feedback:</p>
|
|
<pre><code class="lang-python"># Good
|
|
dspy.Suggest(condition, "Answer should be 2-3 sentences with specific examples")</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> |