Skip to main content
Use ze.get_prompt to fetch team-managed prompts by slug, pinned by version or movable tag. You can template variables, specify fallbacks, and associate results with a tuning task for observability.

​
Quick start

import zeroeval as ze

ze.init()  # ensure ZEROEVAL_API_KEY is set

# Fetch by slug using environment-resolved tag ("production" in prod, otherwise "latest")
p = ze.get_prompt("support-triage")

print(p.content)

​
API

p = ze.get_prompt(
    "support-triage",
    version=None,            # default: None (int | None) - if set, overrides tag
    tag=None,                # default: None (str | None) → SDK default tag ("production" in prod else "latest")
    fallback=None,           # default: None (str | None) - local content if fetch fails / 404
    variables=None,          # default: None (dict | None) - {name: value} for {{name}} templating
    task_name=None,          # default: None (str | None) - associate content with a tuning task
    render=True,             # default: True (bool) - render template with variables
    missing="error",        # default: "error" ("error" | "leave") - behavior for missing variables
    use_cache=True,          # default: True (bool) - in-process TTL cache for server results
    timeout=None,            # default: None (float | None) → uses client default timeout (10.0s)
)

# Returned object
# p.content       -> str (prompt text, possibly rendered/decorated)
# p.version       -> int | None
# p.version_id    -> str | None
# p.tag           -> str | None
# p.is_latest     -> bool
# p.metadata      -> dict
# p.source        -> "server" | "fallback"

​
Version vs tag

  • If version is provided, it is used and tag is ignored.
  • If version is omitted, the effective tag is tag or a default resolved from the environment.

​
Default tag resolution

  • Explicit env override: ZEROEVAL_PROMPT_TAG.
  • Else, if ZEROEVAL_ENV == "production" → production; otherwise → latest.

​
Variables and templating

  • Use double braces in prompt content: {{variable_name}}.
  • If variables is provided and render=True, placeholders are replaced with their values.
  • missing="error" raises if a placeholder has no value; missing="leave" leaves it intact.

​
Task association (autotune-friendly)

Pass task_name to decorate p.content so downstream LLM calls are traced to that task. The decoration includes prompt identifiers so spans link to the exact version. 
p = ze.get_prompt(
    "support-triage",
    variables={"customer": "Acme"},
    task_name="support-triage",
)

messages = [
    {"role": "system", "content": p.content},
    {"role": "user", "content": "My issue ..."},
]

​
Fallback content

Provide fallback to ensure resiliency if the prompt is missing or the network fails. The returned Prompt.source will be "fallback" in that case. 
p = ze.get_prompt("support-triage", fallback="You are a helpful assistant.")

​
Namespace helper

ze.prompts.get("slug", **kwargs) is a thin wrapper around ze.get_prompt.

​
Examples

  • Fetch latest (non-prod) or production (prod):
p = ze.get_prompt("support-triage")
  • Pin to a specific version:
ze.get_prompt("support-triage", version=3)
  • Render variables:
p = ze.get_prompt(
    "events-create",
    variables={"event_name": "ZeroEval Launch"},
)
print(p.content)
  • Associate with a task for autotune:
p = ze.get_prompt("support-triage", task_name="support-triage")