philiprehberger-prompt-builder

Type-safe prompt template builder for LLM APIs.

Installation

pip install philiprehberger-prompt-builder

Usage

from philiprehberger_prompt_builder import Prompt

messages = (
    Prompt()
    .system("You are a helpful assistant.")
    .user("Summarize this article: {article}")
    .render(article="Long article text here...")
)
# [{"role": "system", "content": "You are a helpful assistant."},
#  {"role": "user", "content": "Summarize this article: Long article text here..."}]

Few-Shot Examples

from philiprehberger_prompt_builder import Prompt

messages = (
    Prompt()
    .system("Classify the sentiment.")
    .example(user="I love this!", assistant="positive")
    .example(user="Terrible product.", assistant="negative")
    .user("{text}")
    .render(text="Pretty good actually")
)

Batch Few-Shot Examples

from philiprehberger_prompt_builder import Prompt

messages = (
    Prompt()
    .system("Translate English to French.")
    .with_examples([
        ("Hello", "Bonjour"),
        ("Goodbye", "Au revoir"),
        ("Thank you", "Merci"),
    ])
    .user("{text}")
    .render(text="Good morning")
)

Output Format Instructions

from philiprehberger_prompt_builder import Prompt

# Request JSON output
messages = (
    Prompt()
    .system("Extract structured data.")
    .user("Parse: {text}")
    .expect_json(description='{"name": string, "age": number}')
    .render(text="John is 30 years old")
)

# Request list output
messages = (
    Prompt()
    .system("Generate ideas.")
    .user("List 5 project ideas about {topic}")
    .expect_list()
    .render(topic="machine learning")
)

Conditional Content

from philiprehberger_prompt_builder import Prompt

use_examples = True

messages = (
    Prompt()
    .system("You are a helpful assistant.")
    .conditional(use_examples, "user", "Here are some examples...")
    .conditional(use_examples, "assistant", "I understand the examples.")
    .user("Now answer my question: {question}")
    .render(question="What is Python?")
)

Prompt Composition

from philiprehberger_prompt_builder import Prompt

preamble = Prompt().system("You are a coding assistant.").user("Use Python 3.12+.")
task = Prompt().user("Write a function that {task}")

combined = preamble.merge(task)
messages = combined.render(task="sorts a list")

Reusable Templates

from philiprehberger_prompt_builder import PromptTemplate

summarizer = PromptTemplate(
    system="You are a {tone} summarizer. Output in {format}.",
    user="Summarize: {content}",
    defaults={"tone": "concise", "format": "bullet points"},
)

messages = summarizer.render(content="Article text...")
messages = summarizer.render(content="...", tone="detailed", format="paragraphs")

verbose = summarizer.extend(tone="thorough", format="essay")

Prompt Versioning

from philiprehberger_prompt_builder import Prompt, PromptVersionStore

store = PromptVersionStore()

v1 = Prompt().system("You are helpful.").user("Answer: {question}")
store.save("v1", v1)

v2 = Prompt().system("You are a concise expert.").user("Answer briefly: {question}")
store.save("v2", v2)

prompt = store.load("v1")
messages = prompt.render(question="What is Python?")

store.list_versions()  # ["v1", "v2"]

Token Estimation

from philiprehberger_prompt_builder import Prompt

prompt = Prompt().system("You are helpful.").user("{text}")
estimated = prompt.estimate_tokens(text="Hello world")

Inspecting prompt state

from philiprehberger_prompt_builder import Prompt

p = Prompt()
p.is_empty()  # True
p.role_counts()  # {}

p.system("Be helpful.").user("Hi").user("Still there?").assistant("Yes!")
p.is_empty()  # False
p.role_counts()  # {"system": 1, "user": 2, "assistant": 1}

# Sanity-check a long conversation
counts = p.role_counts()
assert counts.get("user", 0) == counts.get("assistant", 0) + 1

Context-Window Warnings

prompt = Prompt().user("very long input...")

warnings = prompt.warn_if_over(limit=8192)
for w in warnings:
    print("WARN:", w)

Returns warning strings (not exceptions) when the estimated token count is approaching or exceeds the limit, so callers can decide whether to truncate, summarise, or proceed.

API

Development

pip install -e .
python -m pytest tests/ -v

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT