Installation
Basic Setup
Replace hardcoded prompt strings with ze.prompt(). Your existing text becomes the fallback content that’s used until an optimized version is available.
import zeroeval as ze
from openai import OpenAI
ze.init()
client = OpenAI()
system_prompt = ze.prompt(
name="support-bot",
content="You are a helpful customer support agent for {{company}}.",
variables={"company": "TechCorp"}
)
response = client.chat.completions.create(
model="gpt-4",
messages=[
{"role": "system", "content": system_prompt},
{"role": "user", "content": "How do I reset my password?"}
]
)
ze.prompt() is tracked, versioned, and linked to the completions it produces. You’ll see production traces at ZeroEval → Prompts.
When you provide content, ZeroEval automatically uses the latest optimized
version from your dashboard if one exists. The content parameter serves as a
fallback for when no optimized versions are available yet.
Version Control
Auto-optimization (default)
prompt = ze.prompt(
name="customer-support",
content="You are a helpful assistant."
)
Explicit mode
prompt = ze.prompt(
name="customer-support",
from_="explicit",
content="You are a helpful assistant."
)
Latest mode
prompt = ze.prompt(
name="customer-support",
from_="latest"
)
PromptRequestError if none is found.
Pin to a specific version
prompt = ze.prompt(
name="customer-support",
from_="a1b2c3d4..." # 64-char SHA-256 hash
)
Prompt Library
For more control, use ze.get_prompt() to fetch prompts from the Prompt Library with tag-based deployments and caching.
prompt = ze.get_prompt(
"support-triage",
tag="production",
fallback="You are a helpful assistant.",
variables={"product": "Acme"},
)
print(prompt.content)
print(prompt.version)
print(prompt.model)
Parameters
| Parameter | Type | Default | Description |
|---|
slug | str | — | Prompt slug (e.g. "support-triage") |
version | int | None | Fetch a specific version number |
tag | str | "latest" | Tag to fetch ("production", "latest", etc.) |
fallback | str | None | Content to use if the prompt is not found |
variables | dict | None | Template variables for {{var}} tokens |
task_name | str | None | Override the task name for tracing |
render | bool | True | Whether to render template variables |
missing | str | "error" | What to do with missing variables: "error" or "ignore" |
use_cache | bool | True | Use in-memory cache for repeated fetches |
timeout | float | None | Request timeout in seconds |
Return value
Returns a Prompt object with:
| Field | Type | Description |
|---|
content | str | The rendered prompt content |
version | int | Version number |
version_id | str | Version UUID |
tag | str | Tag this version was fetched from |
is_latest | bool | Whether this is the latest version |
model | str | Model bound to this version (if any) |
metadata | dict | Additional metadata |
source | str | "api" or "fallback" |
content_hash | str | SHA-256 hash of the content |
Model Deployments
When you deploy a model to a prompt version in the dashboard, the SDK automatically patches the model parameter in your LLM calls:
system_prompt = ze.prompt(
name="support-bot",
content="You are a helpful customer support agent."
)
response = client.chat.completions.create(
model="gpt-4", # Gets replaced with the deployed model
messages=[
{"role": "system", "content": system_prompt},
{"role": "user", "content": "Hello"}
]
)
Sending Feedback
Attach feedback to completions to power prompt optimization:
ze.send_feedback(
prompt_slug="support-bot",
completion_id=response.id,
thumbs_up=True,
reason="Clear and concise response"
)
| Parameter | Type | Required | Description |
|---|
prompt_slug | str | Yes | Prompt name (same as used in ze.prompt()) |
completion_id | str | Yes | UUID of the completion |
thumbs_up | bool | Yes | Positive or negative feedback |
reason | str | No | Explanation of the feedback |
expected_output | str | No | What the output should have been |
metadata | dict | No | Additional metadata |
