As you modify your prompt in code, Helicone automatically tracks the new version and maintains a record of the old prompt. Additionally, a dataset of input/output keys is preserved for each version.
Typescript / Javascript
Python
Packageless (cURL)
1
Install the package
npm install @helicone/prompts
2
Import hpf
import { hpf } from "@helicone/prompts";
3
Add `hpf` and identify input variables
By prefixing your prompt with hpf and enclosing your input variables in an additional {}, it allows Helicone to easily detect your prompt and inputs. We’ve designed for minimum code change to keep it as easy as possible to use Prompts.
const location = "space";const character = "two brothers";const promptInput = hpf`Compose a movie scene involving ${{ character }}, set in ${{ location }}`;
In addition to hpf, Helicone provides hpstatic for creating static prompts that don’t change between requests. This is useful for system prompts or other constant text that you don’t want to be treated as variable input.To use hpstatic, import it along with hpf:
import { hpf, hpstatic } from "@helicone/prompts";
Then, you can use it like this:
const systemPrompt = hpstatic`You are a helpful assistant.`;const userPrompt = hpf`Write a story about ${{ character }}`;
The hpstatic function wraps the entire text in <helicone-prompt-static> tags, indicating to Helicone that this part of the prompt should not be treated as variable input.
To rename your input or have a custom input, change the key-value pair in the passed dictionary to the string formatter function:
content: hpf`Write a story about ${{ "my_magical_input": character }}`,
4
Assign an id to your prompt
Assign a Helicone-Prompt-Id header to your LLM request.Assigning an id allows us to associate your prompt with future versions of your prompt, and automatically manage versions on your behalf.
By prefixing your prompt with hpf and providing your input variables as keyword arguments, it allows Helicone to easily detect your prompt and inputs. We’ve designed for minimum code change to keep it as easy as possible to use Prompts.
location = "space"character = "two brothers"prompt_input = hpf( "Compose a movie scene involving {character}, set in {location}", character=character, location=location)
In addition to hpf, Helicone provides hpstatic for creating static prompts that don’t change between requests. This is useful for system prompts or other constant text that you don’t want to be treated as variable input.To use hpstatic, import it along with hpf:
from helicone_prompts import hpf, hpstatic
Then, you can use it like this:
system_prompt = hpstatic("You are a helpful assistant.")user_prompt = hpf("Write a story about {character}", character=character)
The hpstatic function wraps the entire text in <helicone-prompt-static> tags, indicating to Helicone that this part of the prompt should not be treated as variable input.
To rename your input or have a custom input, use a different keyword argument name:
content = hpf( "Write a story about {my_magical_input}", my_magical_input=character)
4
Assign an id to your prompt
Assign a Helicone-Prompt-Id header to your LLM request.Assigning an id allows us to associate your prompt with future versions of your prompt, and automatically manage versions on your behalf.
headers = { "Helicone-Prompt-Id": "prompt_story"}
Currently, we only support packages for TypeScript and JavaScript for easy integration. For other users, we recommend manually implementing input variables as follows:
1
Identify the input variable, and create a key name.
Given the below string, let’s say a secret agent is our inputted variable. Let’s name our key character.
Write a story about a secret agent
2
Add helicone-prompt-input tags
Add <helicone-prompt-input key="<INPUT_ID>"> before your input variable, and </helicone-prompt-input> after, where INPUT_ID is your key name. In this example, key="character":
Write a story about <helicone-prompt-input key="character" >a secret agent</helicone-prompt-input>
Don’t worry, Helicone will remove these tags for you before your prompt is sent to your LLM.
It is crucial that each key has a unique identifier; otherwise, the same variable will be replaced in multiple places.
For static prompts, you can manually wrap static parts of your prompt in <helicone-prompt-static> tags:
<helicone-prompt-static>You are a helpful assistant.</helicone-prompt-static>Write a story about <helicone-prompt-input key="character">a secret agent</helicone-prompt-input>
This tells Helicone that the first part of the prompt is static and should not be treated as variable input.
3
Tag your prompt
In order to securely ensure that we know when and how to parse and categorize your prompt, please append the following header to your LLM request.
Helicone-Prompt-Id: you_prompt_id
The id must not include any spaces or special characters. Underscores and dashes are acceptable.
4
Make a request
You just created a prompt template! Helicone will now keep track of all of your inputs for you. Rest assured that all of the helicone-prompt-input tags will be removed before your prompt is sent to your LLM.
Let’s say we have an app that generates a short story, where users are able to input their own character. For example, the prompt is “Write a story about a secret agent”, where the character is “a secret agent”.
Typescript / Javascript example
Python example
Packageless (cURL) example
// 1. Add importsimport { hpf, hpstatic } from "@helicone/prompts";const chatCompletion = await openai.chat.completions.create( { messages: [ { role: "system", // 2. Use hpstatic for static prompts content: hpstatic`You are a creative storyteller.`, }, { role: "user", // 3: Add hpf to any string, and nest any variable in additional brackets `{}` content: hpf`Write a story about ${{ character }}`, }, ], model: "gpt-4o-mini", }, { // 4. Add Prompt Id Header headers: { "Helicone-Prompt-Id": "prompt_story", }, });
# 1. Add importsfrom helicone_prompts import hpf, hpstaticresponse = client.chat.completions.create( model="gpt-4o-mini", messages=[ { "role": "system", # 2. Use hpstatic for static prompts "content": hpstatic("You are a creative storyteller.") }, { "role": "user", # 3. Call hpf with a string and provide variables as keyword arguments "content": hpf("Write a story about {character}", character="a secret agent") } ], # 4. Add Prompt Id Header headers={ "Helicone-Prompt-Id": "prompt_story", })
openai.ChatCompletion.create( model="[DEPLOYMENT]", # Manually add starting and ending tags with before and after variables messages=[{"role": "User", "content": f'Write a story about <helicone-prompt-input key="character" >{character} </helicone-prompt-input>'}], headers={ # Add Prompt Id header "Helicone-Prompt-Id": "[my_prompt_id]", })
Many times in development, you may want to test your prompt locally before deploying it to production and you don’t want Helicone to track new prompt versions.
Typescript / Javascript
Python
To do this, you can set the Helicone-Prompt-Mode header to testing in your LLM request. This will prevent Helicone from tracking new prompt versions.
headers: { "Helicone-Prompt-Mode": "testing",},
To do this, you can set the Helicone-Prompt-Mode header to testing in your LLM request. This will prevent Helicone from tracking new prompt versions.
Helicone does not own your prompts. We simply provide a logging and observability platform that captures and securely stores your LLM interaction data. When you use our UI, prompts are temporarily stored in our system, but when using code-based integration, prompts remain exclusively in your codebase. Our commitment is to offer transparent insights into your LLM interactions while ensuring your intellectual property remains completely under your control.
How does the version indexing work?
In Helicone, you may notice that some of your prompt versions are labeled as V2.0, while others are labeled V2.1. Major versions (i.e., V1.0, V2.0, V3.0) are your prompts in production. Minor versions (V1.1, V1.2, V1.3) are experiment versions that are created in Helicone, which were forked off of your production version V1.0 in this example.
