types — Shared Contracts

All enumerations and dataclasses used across the package. No logic beyond three convenience methods/properties on BuiltPrompt.

Table of contents

• Enumerations: PromptType, PromptStrategy, OutputFormat, QueryComplexity, UserProfile
• Dataclasses: Document, Message, PromptRequest, BuiltPrompt

Enumerations

All enums subclass (str, Enum), so instances are interchangeable with their string .value almost everywhere in the API — e.g. strategy="multi_hop" and strategy=PromptStrategy.MULTI_HOP are both accepted by PromptEngine.build().

PromptType

Canonical prompt archetypes.

Used by: PromptBuilder._resolve_strategy (maps type → default strategy), PromptEngine._auto_detect (infers type from query keywords), GuardrailEngine._select (skips STAY_ON_TOPIC for AGENT/TOOL_USE).

PromptStrategy

Building strategy layered on top of the prompt type.

Each member has a concrete BaseStrategy implementation registered in STRATEGY_REGISTRY.

OutputFormat

Desired output format enforced by format-specific guardrail instructions (see GuardrailEngine._FORMAT_INSTRUCTIONS).

STRUCTURED combined with a non-None PromptRequest.output_schema causes GuardrailEngine._render to append a json.dumps-formatted schema block to the format instruction.

QueryComplexity

PromptEngine._auto_detect sets this from query word count and document count. PromptBuilder._COMPLEXITY_UPGRADE maps "complex" → CHAIN_OF_THOUGHT and "expert" → MULTI_HOP (only applied when the type's default strategy is SIMPLE). GuardrailEngine._select adds SELF_CHECK for COMPLEX/EXPERT.

UserProfile

Drives the localized persona line returned by persona_line().

Dataclasses

Document

A retrieved passage/chunk used as context.

@dataclass
class Document:
    content:   str
    source:    str            = ""
    score:     float          = 1.0
    metadata:  Dict[str, Any] = field(default_factory=dict)
    chunk_id:  Optional[str]  = None
    language:  str            = "en"

Example

from zerda.prompt import Document

doc = Document(content="Paris is the capital of France.", source="wiki/paris", score=0.87)

Message

A single conversation turn.

@dataclass
class Message:
    role:    Literal["system", "user", "assistant"]
    content: str

Used in PromptRequest.memory, BuiltPrompt.messages, and as the element type consumed by ContextManager.format_memory().

PromptRequest

Everything PromptEngine.build() needs, bundled for internal passing (also accepted directly via PromptEngine.build_from_request).

@dataclass
class PromptRequest:
    query:      str
    documents:  List[Document]      = field(default_factory=list)
    memory:     List[Message]       = field(default_factory=list)
    prompt_type:    PromptType      = PromptType.QA
    strategy:       PromptStrategy  = PromptStrategy.SIMPLE
    output_format:  OutputFormat    = OutputFormat.TEXT
    complexity:     QueryComplexity = QueryComplexity.SIMPLE
    user_profile:   UserProfile     = UserProfile.GENERAL
    max_context_tokens: int         = 3000
    max_answer_tokens:  int         = 512
    output_schema:  Optional[Dict]  = None
    language:       str             = "en"
    enable_guardrails:   bool       = True
    enable_cot:          bool       = False
    enable_citations:    bool       = True
    enable_uncertainty:  bool       = True
    session_id:  str  = ""
    user_id:     str  = ""
    trace_id:    str  = ""
    extra:       Dict[str, Any] = field(default_factory=dict)

[!NOTE] enable_cot is unused enable_cot is declared with the comment "auto-set by strategy" but no code in the provided source reads or sets request.enable_cot. Chain-of-thought behavior is actually driven entirely by strategy/prompt_type, not this flag.

extra is read in one place: ReActStrategy._build_user looks up req.extra.get("tools") to render an "Available Tools" section (see strategies).

BuiltPrompt

The result of PromptEngine.build() / strategy.build().

@dataclass
class BuiltPrompt:
    system_prompt: str
    user_prompt:   str
    messages:      List[Message] = field(default_factory=list)
    prompt_type:   PromptType    = PromptType.QA
    strategy:      PromptStrategy = PromptStrategy.SIMPLE
    output_format: OutputFormat  = OutputFormat.TEXT
    estimated_tokens:    int = 0
    context_tokens_used: int = 0
    documents_included:  int = 0
    documents_truncated: int = 0
    guardrails_applied:  List[str] = field(default_factory=list)
    tokens_saved:        int = 0
    optimization_notes:  List[str] = field(default_factory=list)
    session_id: str = ""
    trace_id:   str = ""

to_messages() -> List[Dict[str, str]]

Returns [{"role": m.role, "content": m.content} for m in self.messages] — directly usable as the messages= argument to OpenAI-compatible chat completion APIs.

to_anthropic() -> Dict[str, Any]

{
    "system":   self.system_prompt,
    "messages": [{"role": m.role, "content": m.content} for m in self.messages if m.role != "system"],
}

Filters out the system message from messages (Anthropic's Messages API takes system as a separate top-level parameter). Splat this into client.messages.create(**payload, model=...).

full_text (property)

f"[SYSTEM]\n{self.system_prompt}\n\n[USER]\n{self.user_prompt}"

Convenience string for debugging/logging; not used elsewhere internally.

Example: inspecting a built prompt

prompt = engine.build(query="What is RAG?")
print(prompt.full_text)
print(prompt.to_messages())
print(prompt.to_anthropic())

Related pages

• prompt_engine — consumes and produces these types
• guardrails — reads OutputFormat, PromptType, QueryComplexity
• templates — reads UserProfile, PromptStrategy, OutputFormat