Implementation:Helicone Helicone Prompt State Types

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

Overview

TypeScript type definitions for prompt versioning, editing state, and message formats used throughout the prompt management and playground features.

Description

This module defines the core type contracts for the Helicone prompt management system. It covers several key areas:

PromptState Interface: The primary state object for prompt editing, containing:

• Prompt and version identifiers (promptId, versionId, masterVersion, version)
• Message array using the Message type from @helicone-package/llm-mapper
• Model parameters via StateParameters (provider, model, temperature, reasoning_effort, max_tokens, tools, stop sequences, response_format)
• Optional inputs array (StateInputs) for template variable values
• Dirty flag (isDirty) for tracking unsaved changes
• Optional response and improvement objects for LLM output and suggestions

StateParameters Interface: Model configuration including provider (from @helicone-package/cost), model string, temperature, reasoning effort levels (minimal, low, medium, high), max tokens, tools, stop sequences, and JSON schema response format.

StateInputs Interface: Template variable bindings with name, value, validity flag, and index.

PromptVersionReference Interface: Database representation of a prompt version with ID, version numbers, prompt content, model, Helicone template, timestamps, metadata, parent version reference, and experiment ID.

HeliconeMessage Type (Legacy): A union type supporting three message formats:

• OpenAI ChatCompletionMessageParam for standard chat completions
• { type: "text"; text: string } for Assistants API content
• Template literal <helicone-auto-prompt-input idx=${number} /> for auto-prompt input markers

Usage

Use these types when building prompt editing UI components, managing prompt state in stores, interfacing with the prompt versioning API, or handling prompt message formats across different LLM providers.

Code Reference

Source Location

• Repository: Helicone
• File: web/types/prompt-state.ts

Signature

export interface PromptState {
  promptId?: string;
  masterVersion?: number;
  versionId?: string;
  version?: number;
  messages: Message[];
  parameters: StateParameters;
  inputs?: StateInputs[];
  evals?: any[];
  structure?: any;
  isDirty: boolean;
  response?: { content: string; reasoning: string; calls: string };
  improvement?: { reasoning: string; content: string };
}

export interface StateParameters {
  provider: Provider;
  model: string;
  temperature?: number;
  reasoning_effort?: "minimal" | "low" | "medium" | "high";
  max_tokens?: number;
  tools?: Tool[];
  stop?: string[];
  response_format?: { type: "json_schema"; json_schema?: object };
}

export interface StateInputs {
  name: string;
  value: string;
  isValid?: boolean;
  idx?: number;
}

export interface StateEval {}

export interface PromptVersionReference {
  id: string;
  minor_version: number;
  major_version: number;
  prompt_v2: string;
  model: string;
  helicone_template: string;
  created_at: string;
  metadata: Record<string, any>;
  parent_prompt_version?: string | null;
  experiment_id?: string | null;
  updated_at?: string;
}

export type HeliconeMessage =
  | ChatCompletionMessageParam
  | { type: "text"; text: string }
  | `<helicone-auto-prompt-input idx=${number} />`;

Import

import {
  PromptState,
  StateParameters,
  StateInputs,
  PromptVersionReference,
  HeliconeMessage,
} from "@/types/prompt-state";

I/O Contract

PromptState Fields

Field	Type	Required	Description
promptId	string	No	UUID of the prompt
masterVersion	number	No	Master prompt version number
versionId	string	No	UUID of the specific prompt version
version	number	No	Version number being edited
messages	Message[]	Yes	Array of chat messages
parameters	StateParameters	Yes	Model configuration parameters
inputs	StateInputs[]	No	Template variable values
evals	any[]	No	Evaluator configurations (TODO)
structure	any	No	Structured output schema (TODO)
isDirty	boolean	Yes	Whether the state has unsaved changes
response	{ content, reasoning, calls }	No	LLM response output
improvement	{ reasoning, content }	No	AI-suggested improvements

StateParameters Fields

Field	Type	Required	Description
provider	Provider	Yes	LLM provider (from cost package types)
model	string	Yes	Model identifier string
temperature	number	No	Sampling temperature
reasoning_effort	"low" | "medium" | "high"	No	Reasoning effort level
max_tokens	number	No	Maximum output tokens
tools	Tool[]	No	Tool definitions for function calling
stop	string[]	No	Stop sequences
response_format	{ type: "json_schema"; json_schema?: object }	No	Structured response format

Usage Examples

import { PromptState, StateParameters } from "@/types/prompt-state";

const initialState: PromptState = {
  messages: [{ role: "system", content: "You are a helpful assistant." }],
  parameters: {
    provider: "OPENAI",
    model: "gpt-4",
    temperature: 0.7,
    max_tokens: 1024,
  },
  isDirty: false,
};

Related Pages

• Principle:Helicone_Helicone_Prompt_Management
• Helicone_Helicone_Perform_Edit_Prompt