Prompts in the SDK

Use the SDK to fetch prompts from your Traccia library by name and deploy label (or exact version). Compiling fills {{variables}} and stamps the active span with prompt identity so traces link back to what ran in production.

Quick start

from traccia import init, load_prompt, prefetch_prompts

init(api_key="...", prompt_cache_ttl_s=60)

# Optional: warm cache at startup (jitter avoids multi-replica stampede)
prefetch_prompts(["support-reply"])

prompt = load_prompt(
    "support-reply",
    label="production",
    fallback={
        "type": "chat",
        "messages": [{"role": "system", "content": "You are a helpful assistant."}],
    },
)
messages = prompt.compile(question="Why was I charged?")
# messages ready for your LLM client; span attrs include traccia.prompt.*

Cache, SWR, and fallback

• TTL cache (default 60s): repeated loads of the same name + label/version hit memory. Configure with prompt_cache_ttl_s / promptCacheTtlS or TRACCIA_PROMPT_CACHE_TTL_S.
• Stale-while-revalidate: after TTL expires, the last good prompt is returned immediately while a background refresh runs. On refresh failure, last good is kept (is_stale / isStale).
• Fallback: if fetch fails and nothing is cached, your explicit fallback body is used and is_fallback is set on the object and on span attributes. Prefer always passing a fallback in production.

Compile rules

Templates use double-brace placeholders only. Missing required variables raise an error. Unexpected extras are ignored with a warning. Mustache conditionals are not supported.

text = load_prompt("greet", label="latest").compile(name="Ada")
# or chat:
messages = load_prompt("support-reply").compile(question=q, context=docs)

Span attributes

Calling compile attaches these attributes to the current span when one is active. Content attributes like llm.prompt are unchanged. Redaction allowlists traccia.prompt.* so identity keys are not wiped by the sensitive substring "prompt".

Agent trace layout

For a clean run trace, keep prompt fetch and model generation as sibling spans under one root run span. Load the prompt before the LLM @observe / observe wrapper so traccia.prompt.* lands on the generation span while HTTP fetch appears alongside it.

from traccia import init, load_prompt, observe, trace

init(api_key="...", auto_start_trace=False)

@observe(name="support_reply", as_type="llm")
def generate(messages):
    return gemini_client.generate(messages)

with trace("prompt-support-run"):
    prompt = load_prompt("support-reply", label="production", fallback={...})
    messages = prompt.compile(question=q)
    answer = generate(messages)

API reference tips

• Python: load_prompt(name, *, label="production", version=None, fallback=None)
• Node: loadPrompt({ name, label, version, fallback })
• Prefetch: prefetch_prompts / prefetchPrompts with optional jitter between names.