pydantic-promptmodel 0.1.0

Convention-first typed prompt models with canonical Markdown and XML

pydantic-promptmodel

Write prompts as typed Python. Render them as clean Markdown or XML.

pydantic-promptmodel turns a natural class hierarchy into a ready-to-send LLM prompt. Define the structure once, validate values with Pydantic, and switch output formats with one method call—useful for comparing models, providers, and prompting strategies without maintaining two templates.

Quick start

uv add pydantic-promptmodel

Or:

pip install pydantic-promptmodel

Define the meaning of your prompt, without specifying heading levels, list markers, or XML tags:

from pydantic_promptmodel import PromptModel, prompt


@prompt
class CodeReviewPrompt(PromptModel):
    _title: str
    _body: str
    focus_areas: list[str]
    output: str


review = CodeReviewPrompt(
    _title="Code Review",
    _body="Review the supplied pull request as a senior engineer.",
    focus_areas=[
        "Correctness and edge cases",
        "Security and data handling",
        "Clear, maintainable design",
    ],
    output="Return prioritized findings with a concrete fix for each one.",
)

markdown_prompt = review.to_markdown()
xml_prompt = review.to_xml()

The Markdown is immediately useful:

# Code Review

Review the supplied pull request as a senior engineer.

## Focus Areas

- Correctness and edge cases
- Security and data handling
- Clear, maintainable design

## Output

Return prioritized findings with a concrete fix for each one.

The same instance also produces equivalent XML:

<code-review-prompt title="Code Review">
  <content>Review the supplied pull request as a senior engineer.</content>
  <focus-areas>
    <focus-area>Correctness and edge cases</focus-area>
    <focus-area>Security and data handling</focus-area>
    <focus-area>Clear, maintainable design</focus-area>
  </focus-areas>
  <output>Return prioritized findings with a concrete fix for each one.</output>
</code-review-prompt>

Why use it?

• One prompt model, multiple formats. Change .to_markdown() to .to_xml() without rewriting or synchronizing templates.
• Natural structure. Nested models become nested sections, list[str] becomes a readable list, and snake_case names become human-friendly labels.
• Pydantic validation. Prompt inputs are typed and validated before they reach the model provider.
• Deterministic output. The same prompt instance always renders the same text, making snapshots, reviews, and A/B tests straightforward.
• Useful defaults first. Most prompts need no formatting metadata. Local overrides are available when a label, XML name, ordering rule, literal block, or runtime slot needs special treatment.

_title names the current prompt or nested section, while _body is prose owned directly by it. Ordinary fields named title and body remain available for your domain.

Design philosophy

The model is the source of truth. The library aims to produce one beautiful, correct, and useful representation for each format—not reproduce every possible hand-written Markdown or XML layout.

Version 0.1.0 is an alpha release for Python 3.11+ and Pydantic 2.

Learn more

• Transformation contract
• Changelog

Development

make format
make lint
make test
make check
make build

Release maintainers should follow the trusted-publishing guide.