Variables

Variables let you write prompt templates with dynamic slots that get filled in at runtime. VersionR uses {{double_curly_braces}} syntax — the same convention used by Handlebars and Mustache.

Declaring variables

Write a variable directly into your prompt text in the editor:

You are an experienced technical interviewer.
Your candidate is {{candidate_name}}, applying for a {{job_role}} role.
Difficulty level: {{difficulty}}.

VersionR auto-detects all {{variable_name}} slots on save. No manual schema definition needed.

Variable name format

Variable names must:

• Start with a letter
• Contain only letters, numbers, and underscores
• Be snake_case by convention

Valid: candidate_name, job_role, user_id, difficulty_level_2 Invalid: candidate-name, 2name, job role

Substituting variables

Pass a variables object to pd.render():

const rendered = await pd.render('interviewer-system', {
  env: 'production',
  variables: {
    candidate_name: 'Eoin',
    job_role: 'Senior Engineer',
    difficulty: 'hard',
  },
})
 
// rendered.content — all {{variables}} replaced

Variable values are always strings. If you need to pass a number or boolean, convert it before passing:

variables: {
  score: String(userScore),
  is_premium: isPremium ? 'yes' : 'no',
}

Missing variables

If the prompt declares a variable and you don’t provide a value, pd.render() throws a VersionRError:

VersionRError: Missing required variable: candidate_name
  Prompt: interviewer-system (v3)
  Declared variables: candidate_name, job_role, difficulty

This fails loudly and immediately — before the LLM is called. You won’t silently send a prompt with {{candidate_name}} in it.

Extra variables

Providing a variable that the prompt doesn’t declare is silently ignored. This makes it safe to pass a broad context object:

const rendered = await pd.render('interviewer-system', {
  env: 'production',
  variables: {
    candidate_name: 'Eoin',
    job_role: 'Senior Engineer',
    difficulty: 'hard',
    session_id: 'abc123',    // not in prompt — ignored
    timestamp: '2025-01-01', // not in prompt — ignored
  },
})

Inspecting declared variables

Both pd.get() and pd.render() return a variables array listing the names detected in the prompt:

const prompt = await pd.get('interviewer-system', { env: 'production' })
console.log(prompt.variables)
// → ['candidate_name', 'job_role', 'difficulty']

Use this to build dynamic UI or validate your inputs before calling pd.render().