PromptContent

from elsai_prompts.prompt_manager import PromptContent

Returned by every PromptManager fetch method. Unifies access to the four prompt kinds through one class. Kind-specific accessors raise AttributeError if used on the wrong kind — surfacing bugs at the call site instead of returning empty values.

Construction

You don't construct PromptContent directly — it's produced by the SDK from server responses. The constructor signature is documented for completeness:

PromptContent(
    kind: str,
    content: dict,
    *,
    sha: str | None = None,
    version_label: str | None = None,
    prompt_id: str | None = None,
    prompt_name: str | None = None,
    environments: list[str] | None = None,
)

There's also a class method that mirrors how the SDK builds it from the wire payload:

PromptContent.from_response(payload: dict) -> PromptContent

Common attributes (all kinds)

Attribute	Type	Description
kind	str	One of "instruction", "f_string", "chat", "structured"
sha	str | None	First 12 hex chars of the version's content hash
version_label	str | None	Human-readable label, e.g. "v1.0"
prompt_id	str | None	UUID of the prompt
prompt_name	str | None	Name of the prompt
environments	list[str]	Environments the version is released to

Kind-specific accessors

Accessors raise AttributeError with a clear message if used on the wrong kind:

prompt.template
# AttributeError: '.template' is only available for 'f_string' prompts (this prompt is 'instruction')

Instruction

text — str — The main prompt text. Returns "" if missing.

system_prompt — str — Optional system prompt. Returns "" if not set.

prompt = pm.get_active_prompt_version("system_intro")
assert prompt.kind == "instruction"

prompt.text             # → "You are a polite customer support agent..."
prompt.system_prompt    # → "" (or the configured system text)

F-string

template — str — Raw template string with {{variable}} placeholders. Returns "" if missing.

variables — list[dict] — Declared variable specs — list of {name, type, description} dicts.

prompt = pm.get_active_prompt_version("translator")
assert prompt.kind == "f_string"

prompt.template     # → "Translate {{text}} from {{from}} to {{to}}"
prompt.variables    # → [{"name": "text", "type": "string", ...}, ...]

Chat

messages — list[dict] — List of {role, content} message dicts with {{variables}} allowed in any body.

variables — list[dict] — Declared variable specs.

prompt = pm.get_active_prompt_version("interview_bot")
assert prompt.kind == "chat"

prompt.messages    # → [{"role": "system", "content": "..."}, ...]
prompt.variables   # → [{"name": "topic", ...}, ...]

Structured

base — PromptContent — The wrapped base prompt — itself a PromptContent of kind instruction, f_string, or chat.

response_schema — dict — The JSON response schema. Empty dict if missing.

prompt = pm.get_active_prompt_version("entity_extractor")
assert prompt.kind == "structured"

prompt.base                # → PromptContent (kind: "f_string", say)
prompt.base.template       # → "Extract from: {{text}}"
prompt.base.variables      # → [{"name": "text", ...}]
prompt.response_schema     # → {"type": "object", ...}

render(variables)

PromptContent.render(variables: dict | None = None) -> str | list[dict] | dict

Substitute {{variables}} and return the rendered content. Polymorphic by kind:

Kind	Returns	Variables required?
instruction	str	No (ignored if passed)
f_string	str	Yes (missing → empty string)
chat	list[{role, content}]	Yes (missing → empty string)
structured	dict {base: <rendered>, response_schema: dict}	Yes (passed to the base)

variables — dict | None (default: None) — Variable values keyed by name. Values are stringified via str(). Extra keys are ignored. Missing variables substitute as empty string.

Examples:

# Instruction
prompt.render()
# → "You are a polite customer support agent..."

# F-string
prompt.render({"text": "Hello", "from": "English", "to": "Spanish"})
# → "Translate Hello from English to Spanish"

# Chat
prompt.render({"topic": "Python"})
# → [
#     {"role": "system",  "content": "You are interviewing about Python."},
#     {"role": "user",    "content": "Start the interview."}
#   ]

# Structured
prompt.render({"text": "Apple released..."})
# → {
#     "base": "Extract from: Apple released...",
#     "response_schema": {"type": "object", ...}
#   }

See Rendering variables( for substitution rules.

__repr__

>>> repr(prompt)
"PromptContent(kind='f_string', variables=['text', 'from', 'to'])"

Edge cases and gotchas

Variables are case-sensitive

{{name}} matches the key "name" only, not "Name" or "NAME". If you pass {"Name": ...} and the template expects {{name}}, you get an empty substitution.

Missing variables render as empty string, not as a literal

render({}) on a template with {{x}} produces "" for that span, not {{x}}. This is forgiving by design — wrap with a validator if you want strictness.

render() values are stringified

Numbers, booleans, None all pass through str(). None becomes the literal string "None", which is rarely what you want — normalize before calling.

response_schema is not rendered

Even on a structured prompt, the JSON schema is never substituted. Only the wrapped base prompt is rendered with your variables.

Kind can't be discovered from accessors safely

Don't try: prompt.template; except AttributeError: ... to discover the kind — use prompt.kind directly. The accessor AttributeError is a programming-bug signal, not a discovery API.

See also