Implementation:Helicone Helicone Prompt Types

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

Overview

Central type definitions for the Helicone prompt management system, extending OpenAI chat completion types with support for prompt templates, provider-specific features, and cache control.

Description

types.ts in the prompts package defines the complete type surface for the Helicone prompt system. These types are used across the entire prompts package, the AI Gateway, and client SDKs. The file is organized into several logical groupings:

Template and Variable Types:

• TemplateVariable -- Represents a variable extracted from a prompt template (name, type, raw template string).
• PromptPartialVariable -- Represents a prompt partial reference (prompt_id, index, optional environment).
• ValidationError -- Error reported when a variable substitution fails (variable name, expected type, actual value).
• SubstitutionResult -- Result of a variable substitution operation (success flag, result, errors).

Prompt Version Types:

• Prompt2025Version -- A specific version of a prompt including id, model, major/minor version numbers, commit message, environments, S3 URL, and optional prompt body.
• Prompt2025VersionPromptBody -- The full prompt body structure (messages, model, temperature, tools, etc.).
• Prompt2025 -- Top-level prompt entity (id, name, tags).
• Prompt2025Input -- Input record linking a request to a version with its input values.

Provider-Specific Extensions:

• CacheControl -- Anthropic ephemeral caching configuration with TTL support ("5m" or "1h").
• ChatCompletionContentPartDocument -- Anthropic-specific document content part for extended context with citations.
• ReasoningDetail -- Anthropic thinking blocks with signatures for multi-turn conversations.
• HeliconeContentPartImage -- Image output content part for models that generate images.
• HeliconeReasoningOptions -- Reasoning configuration with budget_tokens and thinking_level.
• ContextEditingConfig -- Anthropic context editing strategies for managing conversation context (clear_tool_uses, clear_thinking).

Extended Chat Completion Types:

• HeliconeChatCompletionContentPart -- OpenAI content part extended with cache control and document support.
• HeliconeChatCompletionMessageParam -- Union of all message types with optional cache_control, reasoning, and images.
• HeliconeChatCompletionExtraConfig -- Additional config options (top_k, image_generation).
• HeliconeChatCreateParams -- Non-streaming completion params with Helicone prompt, reasoning, and context editing support.
• HeliconeChatCreateParamsStreaming -- Streaming variant of the extended params.
• HeliconePromptParams -- Parameters for identifying and configuring a prompt template (prompt_id, version_id, environment, inputs).

Usage

Import these types when building components or services that interact with the Helicone prompt system. They provide type safety for prompt template operations, variable substitution, and provider-specific features like Anthropic caching and reasoning.

Code Reference

Source Location

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

Signature

// Template Types
export type ALLOWED_VARIABLE_TYPE = "string" | "boolean" | "number";
export interface TemplateVariable { name: string; type: string; raw: string; from_prompt_partial?: boolean; }
export interface PromptPartialVariable { prompt_id: string; index: number; environment?: string; raw: string; }
export interface ValidationError { variable: string; expected: string; value: any; }
export interface SubstitutionResult { success: boolean; result?: any; errors?: ValidationError[]; }

// Prompt Version Types
export interface Prompt2025Version {
  id: string; model: string; prompt_id: string;
  major_version: number; minor_version: number;
  commit_message: string; environments?: string[];
  created_at: string; s3_url?: string;
  prompt_body?: Prompt2025VersionPromptBody;
}
export interface Prompt2025 { id: string; name: string; tags: string[]; created_at: string; }
export interface Prompt2025Input { request_id: string; version_id: string; inputs: Record<string, any>; }

// Provider-Specific Types
export interface CacheControl { type: "ephemeral"; ttl?: "5m" | "1h"; }
export interface ContextEditingConfig { enabled: boolean; clear_tool_uses?: {...}; clear_thinking?: {...}; }
export interface HeliconeReasoningOptions { reasoning_options?: { budget_tokens?: number; thinking_level?: "low" | "high"; }; }

// Extended Chat Completion Types
export type HeliconeChatCreateParams = ChatCompletionCreateParamsNonStreamingPartialMessages
  & HeliconePromptParams & HeliconeReasoningOptions & HeliconeContextEditingOptions;
export type HeliconeChatCreateParamsStreaming = ChatCompletionCreateParamsStreamingPartialMessages
  & HeliconePromptParams;
export type HeliconePromptParams = {
  prompt_id?: string; environment?: string; version_id?: string; inputs?: Record<string, any>;
};

Import

import {
  HeliconeChatCreateParams,
  HeliconeChatCreateParamsStreaming,
  HeliconePromptParams,
  Prompt2025Version,
  ValidationError,
  TemplateVariable,
  CacheControl,
} from "@helicone-package/prompts/types";

I/O Contract

Key Types

Type	Purpose	Key Fields
HeliconePromptParams	Identify and configure a prompt template	prompt_id, version_id, environment, inputs
HeliconeChatCreateParams	Non-streaming chat completion with Helicone extensions	All OpenAI params + prompt_id, inputs, reasoning_options, context_editing
Prompt2025Version	A specific version of a prompt	id, model, prompt_id, major_version, minor_version, s3_url
ValidationError	Report a substitution failure	variable, expected, value
CacheControl	Anthropic ephemeral caching	type ("ephemeral"), ttl ("5m" or "1h")
ContextEditingConfig	Anthropic context editing	enabled, clear_tool_uses, clear_thinking

Usage Examples

import type {
  HeliconeChatCreateParams,
  HeliconePromptParams,
  CacheControl,
} from "@helicone-package/prompts/types";

// Using HeliconeChatCreateParams with prompt template
const params: HeliconeChatCreateParams = {
  prompt_id: "my-prompt",
  model: "gpt-4o",
  inputs: { name: "Alice", topic: "AI" },
  messages: [
    {
      role: "user",
      content: "Tell me about {{topic}}",
      cache_control: { type: "ephemeral", ttl: "5m" },
    },
  ],
  reasoning_options: {
    budget_tokens: 1000,
  },
};

// Using prompt params independently
const promptParams: HeliconePromptParams = {
  prompt_id: "summarizer",
  environment: "production",
  inputs: { document: "..." },
};

Related Pages

• Principle:Helicone_Helicone_Prompt_Management
• Implementation:Helicone_Helicone_HeliconePromptManager