Welcome to Promplate#

Promplate is a templating framework and agent orchestrator that progressively enhances your prompt engineering workflow with minimal dependencies.


pip install promplate

Promplate runs well on python 3.8 - 3.14, and is well-tested on CPython and PyPy.

A simple example#

Let's say I need to greet in foreign language. Let's compose two simple prompts that just work.

main.pyreply.j2translate.j2


from promplate.llm.openai import ChatComplete 
from promplate import Node

reply = Node.read("reply.j2")
translate = Node.read("translate.j2")

translate.run_config["temperature"] = 0

chain = reply + translate 

complete = ChatComplete().bind(model="gpt-3.5-turbo")
context = {"lang": "chinese"}


{# import time #}

<|system|>
current time: {{ time.localtime() }}

<|user|>
Say happy new year to me in no more than 5 words.
Note that you must include the year in the message.

Note

This shows some special markup syntax in promplate:

Inside {# ... #} are python codes to run in the context. In this case, we want to use time.localtime() to get the current time. So we import it in the template.
<|user|> and <|assistant|> are chat markups. It will be formatted into a list[Message] object before being passed to the LLM.
Inside {{ ... }} can be any python expressions.


Translate the following message into `{{ lang }}`:
"""
{{ __result__ }}
"""

You may ask, what is {{ __result__ }}?

In fact, promplate will automatically inject some variables into the context. Among them, __result__ is the LLM response of the previous node.

Then call chain.invoke({"lang": "chinese"}, complete).result to get a Chinese greeting relating with the time now.

Why `promplate`?#

I am a prompt engineer who suffered from the following problems:

Problems#

Writing prompts inside scripts is not elegant#

There is no syntax highlighting, no auto completion, no linting, etc.
the indenting is ugly, or you have to bare with lots of spaces/tabs in your prompts
Some characters must be escaped, like """ inside a python string, or ` inside a JavaScript string.

So in promplate, we support writing prompts in separate files. Of course, you can still write prompts inside scripts too.

details

writing prompts in separate files

read from filefetch from http urls


from promplate import Template

foo = Template.read("path/to/some-template.j2")  // synchronous
bar = await Template.aread("path/to/some-prompt.md")  // asynchronous


from promplate import Template

foo = Template.fetch("https://your-domain.com/path/to/some-template.j2")  // synchronous
bar = await Template.afetch("https://your-domain.com/path/to/some-prompt.md")  // asynchronous

The template name will be their filenames.


>>> print(foo)
<Template some-template>
>>> print(bar)
<Template some-prompt>

writing short prompt through literals


from promplate import Template

foo = Template('Translate this into {{ lang }}: \n"""{{ text }}"""')

The template name will be the variable name.


>>> print(foo) 
<Template foo>

(new in v0.3) writing chat prompts through magic

user / assistant / systemU / A / S


>>> from promplate.prompt.chat import user, assistant, system
>>> user > "hello"
{'role': 'user', 'content': 'hello'}
>>> assistant > "hi"
{'role': 'assistant', 'content': 'hi'}


>>> from promplate.prompt.chat import user, assistant, system
>>> [system > "...", user @ "example_user" > "hi"]
[
    {'role': 'system', 'content': '...'},
    {'role': 'user', 'content': 'hi', 'name': 'example_user'}
]


>>> from promplate.prompt.chat import U, A, S
>>> U > "hello"
{'role': 'user', 'content': 'hello'}
>>> A > "hi"
{'role': 'assistant', 'content': 'hi'}


>>> from promplate.prompt.chat import U, A, S
>>> [S > "...", U @ "example_user" > "hi"]
[
    {'role': 'system', 'content': '...'},
    {'role': 'user', 'content': 'hi', 'name': 'example_user'}
]

Chaining prompts is somehow difficult#

Often we need several LLM calls in a process. LCEL is langchain's solution.

Ours is like that, but everything unit is a promplate.Node instance. Router are implemented with 2-3 lines in callback functions through raise Jump(...) statements.

Promplate Nodes are just state machines.

Chat templates are hard to read#

Usually you need to manually construct the message list if you are using a chat model. In promplate, you can write chat templates in separate files, and use a render it as a list.

Identical prompts are hard to reuse & maintain#

Promplate has a component system (same meaning as in frontend ecosystem), which enable you to reuse prompt template fragments in different prompts.

Callbacks and output parsers are hard to bind#

In langchain, you can bind callback to a variety of event types. Promplate has a flexible callback system similarly, but you can bind simple callbacks through decorators like the callback registration decorators on Node.

Features#

more than templating: components, chat markup
more than LLM: callbacks, state machines
developer experience: full typing, good printing ...
flexibility: underlying ecosystem power