ZerdaZerda

Quickstart

On this page

1. Build your first prompt

Python · 14 lines
from zerda.prompt import PromptEngine

engine = PromptEngine()

prompt = engine.build(
    query="What caused the 2008 financial crisis?",
    documents=[
        {"content": "The 2008 crisis was triggered by the collapse of the US "
                     "subprime mortgage market...", "source": "wiki", "score": 0.92},
    ],
)

print(prompt.system_prompt)
print(prompt.user_prompt)

PromptEngine.build() (see api/prompt_engine.md) is the single public entry point. Everything else — context assembly, guardrail selection, strategy dispatch, token optimization — happens internally.

2. Feed it to a real LLM client

BuiltPrompt (see api/types.md) exposes two convenience converters:

Python · 9 lines
# OpenAI-style messages list
response = openai_client.chat.completions.create(
    model="gpt-4o",
    messages=prompt.to_messages(),
)

# Anthropic-style {system, messages} payload
payload = prompt.to_anthropic()
response = anthropic_client.messages.create(**payload, model="claude-opus-4-20250514")

3. Pick a reasoning strategy

The strategy argument selects one of seven prompt shapes documented in api/strategies.md:

Python · 6 lines
prompt = engine.build(
    query="Compare the causes of the 2008 crisis and the 1929 crash.",
    documents=docs,
    strategy="multi_hop",       # decompose -> sub-answer -> synthesize
    output_format="json",
)

If you omit strategy, PromptEngine can auto-detect a reasonable prompt_type and complexity from the query text (see _auto_detect), and PromptBuilder maps prompt_type → a default strategy (see api/builder.md).

4. Control safety and output shape

Python · 8 lines
prompt = engine.build(
    query="Summarize the vendor contract's termination clause.",
    documents=docs,
    output_format="citation",     # inline [1], [2] citations + Sources section
    enable_guardrails=True,       # anti-hallucination + grounding instructions
    enable_citations=True,
    enable_uncertainty=True,      # model is told to admit when it doesn't know
)

See api/guardrails.md for exactly which instructions get injected and when.

5. Inspect what happened

Python · 7 lines
print(prompt.estimated_tokens)
print(prompt.guardrails_applied)     # ['safe_output', 'concise', 'grounding', ...]
print(prompt.documents_included, prompt.documents_truncated)
print(prompt.tokens_saved, prompt.optimization_notes)

print(engine.metrics)                # aggregate PromptMetrics.to_dict()
print(engine.get_trace_log(last_n=5))

6. Bilingual output (English / Arabic)

Python · 5 lines
prompt = engine.build(
    query="ما هي سياسة الإجازات؟",
    documents=docs,
    language="ar",
)

language resolved via resolve_lang() (see api/templates.md) selects natively-authored Arabic system personas and section labels rather than an English prompt with a "respond in Arabic" note bolted on. Any other language code (e.g. "fr") falls back to the English scaffold plus a literal "Respond in fr." instruction line.

Next steps

  • Architecture — how the pieces fit together and the request/response lifecycle
  • Configuration — every constructor/keyword option across the library
  • API Reference — full per-module reference

Related pages