Feature — Prompt Management
Ship prompt changes without breaking production.
Version history, production promotion, automatic regression detection after every deploy, and AI-powered optimization suggestions.
Every trace linked to its prompt version. Regression caught before users do.
14 days
regression lookback
10%
regression threshold
SHA-256
content hash
Version History & Trace Linkage
Every prompt change creates an immutable version with a SHA-256 content hash. The hash is stored as promptHash on every trace generated by that prompt — creating a bidirectional link between traces and the exact prompt version that produced them.
- Immutable versions: changes never overwrite, full history always preserved
- promptHash on every trace: click through from any trace to its prompt version
- Labels: tag versions with production, staging, experiment, or custom labels
Automatic Regression Detection
When you promote a version to production, a background job compares eval scores for the new version against the previous 14 days. If any evaluator drops more than 10 percentage points, ZespanPilot notifies you with before/after scores per evaluator.
- Triggers automatically on every production promotion — no manual step
- 14-day lookback window for comparison
- quality_regression notification with per-evaluator before/after scores
AI Prompt Optimization
The optimizer analyzes your traces and suggests specific improvements: model switch, prompt compression, or rewrite. Each suggestion includes projected cost savings and can run as a background job for large prompt sets.
- Model switch suggestions: e.g., GPT-4o → GPT-4o-mini for simple tasks
- Prompt compression: identifies boilerplate that can be removed
- buildDirectPromptSuggestion: immediate improvement for a specific prompt text
Runtime SDK Fetch
PromptClient fetches prompt content at runtime by name + label. Content is cached in Redis and invalidated automatically when a new version is promoted — your app always runs the current production prompt without a redeployment.
- Fetch by name + label: prompts.get('support-reply', 'production')
- Redis cache: invalidated on configVersion bump from every promotion
- No redeployment needed: SDK picks up new prompts automatically
Get started
Set up in under 5 minutes
import { PromptClient } from '@zespan/sdk';
// Fetch the current production prompt at runtime — always fresh
const prompts = new PromptClient({ apiKey: process.env.ZESPAN_API_KEY });
const prompt = await prompts.get('support-reply', 'production');
// prompt.content — cached in Redis, invalidated on next version promotionFrequently asked
How does regression detection work exactly?
When you promote a prompt version to the production label, Zespan runs a background job that queries eval scores for traces using the new version vs. traces from the previous 14 days. If any evaluator score drops more than 10 percentage points, a quality_regression ZespanPilot notification fires with the before/after breakdown.
Can I compare two prompt versions side by side?
Yes. The prompt version view shows per-version metrics (eval scores, usage count, latency, cost). You can compare any two versions. The Simulations feature lets you run both versions against the same dataset and compare results head-to-head.
What's the protected label feature?
Certain labels — like production — require admin permission to assign. This prevents developers from accidentally promoting experimental prompts to production without review. You configure which labels are protected in project settings.
Does the SDK cache prompts locally?
Yes. PromptClient caches prompt content in Redis. When you promote a new version, the configVersion bumps and is returned in the next SDK ingest response — triggering SDK clients to refetch. Cache invalidation is automatic and doesn't require your app to restart.
Start free — 10K traces/month, no card needed
Setup takes under 5 minutes. Works with OpenAI, Anthropic, LangChain, and more.