Prompt API

Filters

Filters are Python functions that are called during the rendering of a certain tag. For example, if a prompt template contains the tag:

{{ 'hello' | upper }}

a Python function named upper (in this case provided by Jinja) will be called passing the string 'hello' as a parameter, and its return value will replace the tag in the final text:

from banks import Prompt

p = Prompt("{{ 'hello' | upper }}")
p.text()  ## outputs 'HELLO'

In addition to all the builtin filters provided by Jinja, Banks supports the following ones, specific for prompt engineering.

tool

tool(function)

Inspect a Python callable and generates a JSON-schema ready for LLM function calling.

Important

This filter only works when used within a {% completion %} block.

cache_control

cache_control(value, cache_type='ephemeral')

Wrap the filtered value into a ContentBlock with the proper cache_control field set.

The resulting ChatMessage will have the field content populated with a list of ContentBlock objects.

Example

{{ "This is a long, long text" | cache_control("ephemeral") }}

This is short and won't be cached.

Important

this filter marks the content to cache by surrounding it with <content_block> and </content_block>, so it's only useful when used within a {% chat %} block.

image

image(value)

Wrap the filtered value into a ContentBlock of type image.

The resulting ChatMessage will have the field content populated with a list of ContentBlock objects.

Example

Describe what you see

{{ "path/to/image/file" | image }}

Important

this filter marks the content to cache by surrounding it with <content_block> and </content_block>, so it's only useful when used within a {% chat %} block.

lemmatize

lemmatize(text)

Compute and return the lemmatization of the input. Language is hardcoded to English.

Example

{{"The dog is running" | lemmatize}}
"the dog be run"

Note

Simplemma must be manually installed to use this filter

Extensions

Extensions are custom functions that can be used to add new tags to the template engine. Banks supports the following ones, specific for prompt engineering.

chat

chat(role)

Text inside chat tags will be rendered as JSON strings representing chat messages. Calling Prompt.chat_messages will return a list of ChatMessage instances.

Example

{% chat role="system" %}
You are a helpful assistant.
{% endchat %}

{% chat role="user" %}
Hello, how are you?
{% endchat %}

completion

completion(model_name)

completion can be used to send to the LLM the content of the block in form of messages.

The rendered value of the block can be assigned to a variable and accessed from another section of the prompt.

Example

{% set response %}
{% completion model="gpt-3.5-turbo-0125" %}
{% chat role="user" %}You are a helpful assistant{% endchat %}
{% endcompletion %}
{% endset %}

{# output the response content #}
{{ response }}

canary_word

Insert into the prompt a canary word that can be checked later with Prompt.canary_leaked() to ensure the original prompt was not leaked.

Example:

from banks import Prompt

p = Prompt("{{canary_word}}Hello, World!")
p.text()  ## outputs 'BANKS[5f0bbba4]Hello, World!'

Macros

Macros are a way to implement complex logic in the template itself, think about defining functions but using Jinja code instead of Python. Banks provides a set of macros out of the box that are useful in prompt engineering, for example to generate a prompt and call OpenAI on-the-fly, during the template rendering. Before using Banks' macros, you have to import them in your templates, see the examples below.