Implementation:Helicone Helicone HeliconePromptManager

Knowledge Sources	Helicone
Domains	Prompts, SDK
Last Updated	2026-02-14 06:32 GMT

Overview

Server-side prompt versioning and management class that pulls, merges, and substitutes Helicone prompt templates with variable interpolation and prompt partial composition.

Description

HeliconePromptManager is the core class in the Helicone prompts package that enables users to manage versioned prompt templates programmatically. It connects to the Helicone API with API key authentication and provides a complete workflow for prompt management:

Version Resolution:

• pullPromptVersion -- Resolves a prompt version by environment, explicit version ID, or defaults to the production version.
• Three private API methods (getPromptVersion, getProductionVersion, getEnvironmentVersion) call the Helicone /v1/prompt-2025/query/* endpoints.

Prompt Body Retrieval:

• pullPromptBody -- Fetches the full prompt body from S3 storage via the version's s3_url.
• pullPromptBodyByVersionId -- Convenience method to pull a prompt body directly by version ID.

Template Variables and Prompt Partials:

• extractPromptPartials -- Scans message content (both string and array content parts) for prompt partial variable references.
• getPromptPartialSubstitutionValue -- Resolves the substitution value for a prompt partial from a source prompt body.

Merging and Substitution:

• mergePromptBody -- Merges source prompt messages with input messages, substitutes template variables and prompt partials using HeliconeTemplateManager, and handles response_format and tools substitution. Returns the compiled ChatCompletionCreateParams along with any ValidationError entries.
• getPromptBody -- High-level convenience method that pulls a prompt and merges it in a single call.

Usage

Use this class in server-side code when you need to dynamically pull and compile Helicone prompt templates. It is particularly useful for production LLM applications that need version-controlled prompts with variable substitution and prompt partial composition.

Code Reference

Source Location

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

Signature

interface HeliconePromptManagerOptions {
  apiKey: string;
  baseUrl?: string;  // defaults to "https://api.helicone.ai"
}

export class HeliconePromptManager {
  constructor(options: HeliconePromptManagerOptions);

  async pullPromptVersion(params: HeliconePromptParams): Promise<Prompt2025Version>;
  async pullPromptBody(params: HeliconePromptParams): Promise<ChatCompletionCreateParams>;
  async pullPromptBodyByVersionId(versionId: string): Promise<ChatCompletionCreateParams>;

  extractPromptPartials(sourcePromptBody: ChatCompletionCreateParams): PromptPartialVariable[];
  getPromptPartialSubstitutionValue(
    promptPartial: PromptPartialVariable,
    sourceBody: ChatCompletionCreateParams
  ): string;

  async mergePromptBody(
    params: HeliconeChatCreateParams | HeliconeChatCreateParamsStreaming,
    sourcePromptBody: ChatCompletionCreateParams,
    promptPartialInputs?: Record<string, any>
  ): Promise<{ body: ChatCompletionCreateParams; errors: ValidationError[] }>;

  async getPromptBody(
    params: HeliconeChatCreateParams | HeliconeChatCreateParamsStreaming
  ): Promise<{ body: ChatCompletionCreateParams; errors: ValidationError[] }>;
}

Import

import { HeliconePromptManager } from "@helicone-package/prompts/HeliconePromptManager";

I/O Contract

Inputs

Name	Type	Required	Description
options.apiKey	string	Yes	Helicone API key for authentication
options.baseUrl	string	No	API base URL (defaults to https://api.helicone.ai)
params.prompt_id	string	Yes	Unique identifier for the prompt template
params.version_id	string	No	Specific version ID to retrieve
params.environment	string	No	Target deployment environment (e.g., "production", "staging")
params.inputs	Record<string, any>	No	Key-value pairs for template variable substitution
params.messages	HeliconeChatCompletionMessageParam[]	No	Additional messages to append to the prompt

Outputs

Name	Type	Description
body	ChatCompletionCreateParams	The fully compiled prompt body with messages, response_format, tools, and model parameters
errors	ValidationError[]	Any variable substitution or validation errors encountered during merging

Usage Examples

import { HeliconePromptManager } from "@helicone-package/prompts/HeliconePromptManager";

const manager = new HeliconePromptManager({
  apiKey: "sk-helicone-...",
  baseUrl: "https://api.helicone.ai",
});

// Pull and compile a prompt with variable substitution
const { body, errors } = await manager.getPromptBody({
  prompt_id: "my-prompt",
  model: "gpt-4o",
  inputs: {
    userName: "Alice",
    topic: "machine learning"
  },
  messages: [
    { role: "user", content: "Tell me more about {{topic}}" }
  ],
});

if (errors.length > 0) {
  console.warn("Substitution errors:", errors);
}

// Use the compiled body with OpenAI
const response = await openai.chat.completions.create(body);

// Pull a specific version
const version = await manager.pullPromptVersion({
  prompt_id: "my-prompt",
  environment: "staging",
});

// Pull the raw prompt body
const promptBody = await manager.pullPromptBody({
  prompt_id: "my-prompt",
  version_id: "abc-123",
});

Related Pages

• Principle:Helicone_Helicone_Prompt_Management
• Implementation:Helicone_Helicone_Prompt_Types