Implementation:Helicone Helicone Prompt Templates

Knowledge Sources	Helicone
Domains	Prompt Management, Template Engine
Last Updated	2026-02-14 06:32 GMT

Overview

The core template engine that powers Helicone's prompt versioning system, providing type-safe variable extraction, validation, and substitution for both string templates and structured JSON objects.

Description

The HeliconeTemplateManager class implements Helicone's prompt templating system using two regex-based pattern syntaxes:

• Template variables -- Patterns of the form {{hc:NAME:type}}, matched by TEMPLATE_REGEX. These support typed substitution where type can be string, number, or boolean.
• Prompt partials -- Patterns of the form {{hcp:prompt_id:index:environment}}, matched by PROMPT_PARTIAL_REGEX. These enable composable prompt references where one prompt template can include content from another versioned prompt.

Key static methods:

• extractVariables -- Parses a template string and returns an array of unique TemplateVariable objects (name, type, raw match).
• extractPromptPartialVariables -- Parses prompt partial references, returning PromptPartialVariable objects (prompt_id, index, optional environment, raw match).
• substituteVariables -- Performs two-phase substitution on a string template: first replaces prompt partials, then replaces template variables. Validates type compatibility before substitution and returns errors if validation fails.
• substituteVariablesJSON -- Deep-traverses a JSON object, replacing template variables in both keys and values. When a string value wholly matches a template pattern, the substituted value preserves the original type (number, boolean, array, or object) rather than coercing to string. This enables type-safe structured fields like response_format and tools.
• getVariableNames -- Convenience method returning just the variable name strings.

Private helpers include isTypeCompatible for type validation, isWholeMatch and getVariableName for pattern detection, performRegexReplacement for string-level replacement, and processObjectKV for recursive JSON traversal.

Usage

Use this class whenever working with Helicone prompt templates: extracting variables to build input forms, validating user inputs before substitution, or performing the actual substitution before sending prompts to LLM providers. The JSON substitution method is particularly important for structured prompt fields.

Code Reference

Source Location

• Repository: Helicone
• File: packages/prompts/templates.ts

Signature

export const TEMPLATE_REGEX: RegExp;
export const PROMPT_PARTIAL_REGEX: RegExp;
export const BOOLEAN_VALUES: string[];

export class HeliconeTemplateManager {
  static extractPromptPartialVariables(template: string): PromptPartialVariable[];
  static extractVariables(template: string): TemplateVariable[];
  static substituteVariables(
    template: string,
    inputs: Record<string, any>,
    promptPartialInputs: Record<string, any>
  ): SubstitutionResult;
  static substituteVariablesJSON(
    json: Record<string, any>,
    inputs: Record<string, any>
  ): SubstitutionResult;
  static getVariableNames(template: string): string[];
}

Import

import {
  HeliconeTemplateManager,
  TEMPLATE_REGEX,
  PROMPT_PARTIAL_REGEX,
} from "@helicone/prompts/templates";

I/O Contract

extractVariables

Parameter	Type	Description
template	string	Template string containing {{hc:NAME:type}} patterns

Returns	Type	Description
(array)	TemplateVariable[]	Unique variables with name, type, and raw match string

substituteVariables

Parameter	Type	Description
template	string	Template string with variable placeholders
inputs	Record<string, any>	Variable name to value mapping
promptPartialInputs	Record<string, any>	Prompt partial raw match to replacement value mapping

Returns	Type	Description
(result)	SubstitutionResult	{ success: true, result: string } or { success: false, errors: ValidationError[] }

substituteVariablesJSON

Parameter	Type	Description
json	Record<string, any>	JSON object containing template patterns in keys and values
inputs	Record<string, any>	Variable name to value mapping

Returns	Type	Description
(result)	SubstitutionResult	{ success: true, result: object } or { success: false, errors: ValidationError[] }

Usage Examples

import { HeliconeTemplateManager } from "@helicone/prompts/templates";

// Extract variables from a template
const template = "Hello {{hc:user_name:string}}, your score is {{hc:score:number}}";
const vars = HeliconeTemplateManager.extractVariables(template);
// vars = [
//   { name: "user_name", type: "string", raw: "{{hc:user_name:string}}" },
//   { name: "score", type: "number", raw: "{{hc:score:number}}" }
// ]

// Substitute variables in a string template
const result = HeliconeTemplateManager.substituteVariables(
  template,
  { user_name: "Alice", score: 95 },
  {}
);
// result = { success: true, result: "Hello Alice, your score is 95" }

// Substitute variables in a JSON object (preserves types)
const jsonTemplate = {
  model: "gpt-4",
  temperature: "{{hc:temp:number}}",
  messages: [{ role: "user", content: "{{hc:prompt:string}}" }]
};
const jsonResult = HeliconeTemplateManager.substituteVariablesJSON(
  jsonTemplate,
  { temp: 0.7, prompt: "Explain quantum computing" }
);
// jsonResult.result.temperature = 0.7 (number, not string)

// Get just variable names
const names = HeliconeTemplateManager.getVariableNames(template);
// names = ["user_name", "score"]

Related Pages

• Principle:Helicone_Helicone_Prompt_Management