@prompt-template/core

@prompt-template/core contains the core PromptTemplate module and types for creating and formatting prompts with input variables. Key features include:

• Type Safety: Ensures PromptTemplate input variables are defined and formatted correctly at compile time.
• Modular Design: Supports nested PromptTemplates to promote organization and reusability.
• Intuitive Authoring: Simplifies prompt creation by solely defining input variables in PromptTemplates.
• Community Prompts: Designed with the vision of creating and sharing PromptTemplates with the community (as NPM packages for example).

Installation

npm i @prompt-template/core

Usage

PromptTemplate.create with InputVariableName

import { PromptTemplate } from '@prompt-template/core'

const promptTemplate = PromptTemplate.create`
  Brainstorm 3 names for a superhero ${'animal'}.
`

const prompt = promptTemplate.format({
  animal: 'cat',
})
//=> 'Brainstorm 3 names for a superhero cat.'

PromptTemplate.create with InputVariableConfig.onFormat

import { PromptTemplate } from '@prompt-template/core'

const promptTemplate = PromptTemplate.create`
  Brainstorm 3 names for a superhero ${{
    name: 'animal',
    onFormat: (inputValue) => inputValue.toUpperCase(),
  }}.
`

const prompt = promptTemplate.format({
  animal: 'cat',
})
//=> 'Brainstorm 3 names for a superhero CAT.'

PromptTemplate.create with InputVariableConfig.schema

import { PromptTemplate } from '@prompt-template/core'
import { z } from 'zod'

const promptTemplate = PromptTemplate.create`
  Brainstorm 3 names for a superhero ${{
    name: 'animal',
    schema: z.string().nonempty(),
  }}.
`

const prompt = promptTemplate.format({
  animal: 'cat',
})
//=> 'Brainstorm 3 names for a superhero cat.'

PromptTemplate.create with InputVariableConfig.default

import { PromptTemplate } from '@prompt-template/core'

const promptTemplate = PromptTemplate.create`
  Brainstorm 3 names for a superhero ${{
    name: 'animal',
    default: 'cat',
  }}.
`

const catPrompt = promptTemplate.format({})
//=> 'Brainstorm 3 names for a superhero cat.'

const dogPrompt = promptTemplate.format({
  animal: 'dog',
})
//=> 'Brainstorm 3 names for a superhero dog.'

PromptTemplate.create with nested PromptTemplate.create

import { PromptTemplate } from '@prompt-template/core'

const outputFormatPromptTemplate = PromptTemplate.create`
  Format the output as ${{
    name: 'format',
    default: 'bullet points',
  }}.
`

const promptTemplate = PromptTemplate.create`
  Brainstorm 3 names for a superhero ${'animal'}.
  ${outputFormatPromptTemplate}
`

const bulletPointsPrompt = promptTemplate.format({
  animal: 'cat',
})
//=> 'Brainstorm 3 names for a superhero cat.
//    Format the output as bullet points.'

const numberedListPrompt = promptTemplate.format({
  animal: 'cat',
  format: 'a numbered list',
})
//=> 'Brainstorm 3 names for a superhero cat.
//    Format the output as a numbered list.'

PromptTemplate.create with PromptTemplateOptions

import { PromptTemplate } from '@prompt-template/core'

const promptTemplate = PromptTemplate.create({ prefix: 'user: ' })`
  Brainstorm 3 names for a superhero ${'animal'}.
`

const prompt = promptTemplate.format({
  animal: 'cat',
})
//=> 'user: Brainstorm 3 names for a superhero cat.'

Note: By default, format will dedent the formatted prompt. You can disable this behavior by setting the dedent option to false.

API

PromptTemplate.create

A tagged template literal function that returns a PromptTemplate instance or a new PromptTemplate bound to the provided PromptTemplateOptions overrides.

const promptTemplate = PromptTemplate.create`
  My prompt template with ${'inputVariableName'}.
`

const prompt = promptTemplate.format({
  inputVariableName: 'inputVariableValue',
})
//=> 'My prompt template with inputVariableValue.'

or

const promptTemplate = PromptTemplate.create({ prefix: 'user: ' })`
  My prompt template with ${'inputVariableName'}.
`

const prompt = promptTemplate.format({
  inputVariableName: 'inputVariableValue',
})
//=> 'user: My prompt template with inputVariableValue.'

PromptTemplate.from(string)

A static method that returns a PromptTemplate instance.

const promptTemplate = PromptTemplate.from('My prompt template.')

const prompt = promptTemplate.format()
//=> 'My prompt template.'

PromptTemplate Class

A PromptTemplate instance is returned from a PromptTemplate.create call. It contains a format method for creating the final prompt and additional properties/methods for advanced use cases.

const promptTemplate = PromptTemplate.create`
  My prompt template with ${'inputVariableName'} and default ${{
    name: 'inputVariableConfigName',
    default: 'inputVariableConfigDefault',
  }}.
`

promptTemplate.templateStrings
//=> ['My prompt template with ', ' and default ', '.']

promptTemplate.inputVariables
//=> ['inputVariableName', { name: 'inputVariableConfigName', default: 'inputVariableConfigDefault' }]

const prompt = promptTemplate.format({
  inputVariableName: 'inputVariableValue',
})
//=> 'My prompt template with inputVariableValue and default inputVariableConfigDefault.'

format(inputValues)

A PromptTemplate instance method used to create the final prompt. It accepts an inputValues object where each key corresponds to the InputVariableName, InputVariableConfig.name, and any nested PromptTemplate instance input variable names.

const nestedPromptTemplate = PromptTemplate.create`
  My nested prompt template with ${'nestedInputVariableName'}.
`

const promptTemplate = PromptTemplate.create`
  - My prompt template with ${'inputVariableName'}.
  - My prompt template with ${{
    name: 'inputVariableConfigName',
    default: 'inputVariableConfigDefault',
  }}.
  - ${nestedPromptTemplate}
`

const inputValues = {
  inputVariableName: 'inputVariableValue',
  // inputVariableConfigName: 'inputVariableConfigValue', // Optional
  nestedInputVariableName: 'nestedInputVariableValue',
}

const prompt = promptTemplate.format(inputValues)
//=> '- My prompt template with inputVariableValue
//    - My prompt template with inputVariableConfigDefault
//    - My nested prompt template with nestedInputVariableValue.'

getInputVariableNames()

A PromptTemplate instance method that recursively extracts and deduplicates all input variable names.

const nestedPromptTemplate = PromptTemplate.create`
  My nested prompt template with ${'nestedInputVariableName'}.
`

const promptTemplate = PromptTemplate.create`
  - My prompt template with ${'inputVariableName'}.
  - My prompt template with ${{
    name: 'inputVariableConfigName',
    default: 'inputVariableConfigDefault',
  }}.
  - ${nestedPromptTemplate}
`

promptTemplate.getInputVariableNames()
//=> ['inputVariableName', 'inputVariableConfigName', 'nestedInputVariableName']

getInputVariableNamesRequired()

A PromptTemplate instance method that recursively extracts and deduplicates all required input variable names.

const nestedPromptTemplate = PromptTemplate.create`
  My nested prompt template with ${'nestedInputVariableName'}.
`

const promptTemplate = PromptTemplate.create`
  - My prompt template with ${'inputVariableName'}.
  - My prompt template with ${{
    name: 'inputVariableConfigName',
    default: 'inputVariableConfigDefault',
  }}.
  - ${nestedPromptTemplate}
`

promptTemplate.getInputVariableNamesRequired()
//=> ['inputVariableName', 'nestedInputVariableName']

getInputVariableNamesOptional()

A PromptTemplate instance method that recursively extracts and deduplicates all optional input variable names.

const nestedPromptTemplate = PromptTemplate.create`
  My nested prompt template with ${'nestedInputVariableName'}.
`

const promptTemplate = PromptTemplate.create`
  - My prompt template with ${'inputVariableName'}.
  - My prompt template with ${{
    name: 'inputVariableConfigName',
    default: 'inputVariableConfigDefault',
  }}.
  - ${nestedPromptTemplate}
`

promptTemplate.getInputVariableNamesOptional()
//=> ['inputVariableConfigName']

Important: If input variable names are duplicated and one is required and the other is optional, the input variable name is considered required.

const promptTemplate = PromptTemplate.create`
  My duplicate prompt template with ${'duplicateInputVariableName'} and ${{
    name: 'duplicateInputVariableName',
    default: 'duplicateInputVariableNameDefault',
  }}.
`

promptTemplate.getInputVariableNamesRequired()
//=> ['duplicateInputVariableName']

promptTemplate.getInputVariableNamesOptional()
//=> []

walkInputVariables(options)

A PromptTemplate instance method that recursively walks all input variables.

const nestedPromptTemplate = PromptTemplate.create`
  My nested prompt template with ${'nestedInputVariableName'}.
`

const promptTemplate = PromptTemplate.create`
  - My prompt template with ${'inputVariableName'}.
  - My prompt template with ${{
    name: 'inputVariableConfigName',
    default: 'inputVariableConfigDefault',
  }}.
  - ${nestedPromptTemplate}
`

promptTemplate.walkInputVariables({
  strategy: 'depth-first', // Default
  onInputVariableName(inputVariableName) {
    console.log(inputVariableName)
    //=> 'inputVariableName'
    //=> 'nestedInputVariableName'
  },
  onInputVariableConfig(inputVariableConfig) {
    console.log(inputVariableConfig.name),
    //=> 'inputVariableConfigName'
  },
  onPromptTemplate(promptTemplate) {/* ... */},
})

PromptTemplateOptions

A PromptTemplateOptions object is passed to a PromptTemplate.create call to override the default behavior of a PromptTemplate instance.

const promptTemplateOptions = {
  prefix: 'prefix - ',
  suffix: ' - suffix',
  dedent: true, // Default
  description: 'My prompt template description.',
}

const promptTemplate = PromptTemplate.create(promptTemplateOptions)`
  My prompt template with ${'inputVariableName'}.
`

const prompt = promptTemplate.format({
  inputVariableName: 'inputVariableValue',
})
//=> 'prefix - My prompt template with inputVariableValue. - suffix'

InputVariableName

An InputVariableName is a string used to identify input variables in a PromptTemplate.create and establish a corresponding property in the format inputValues.

const promptTemplate = PromptTemplate.create`
  My prompt template with ${'inputVariableName'}.
`

const prompt = promptTemplate.format({
  inputVariableName: 'inputVariableValue',
})
//=> 'My prompt template with inputVariableValue.'

InputVariableConfig

An InputVariableConfig is an object used to identify input variables in a PromptTemplate.create and establish a corresponding property in the format inputValues. It also allows for additional configuration of the input variable.

const promptTemplate = PromptTemplate.create`
  My prompt template with ${{
    name: 'inputVariableConfigName',
    default: 'inputVariableConfigDefault',
    onFormat: (inputValue) => inputValue.toUpperCase(),
    schema: z.string().nonempty(),
  }}.
`

const prompt = promptTemplate.format({
  inputVariableConfigName: 'inputVariableConfigValue',
})
//=> 'My prompt template with INPUTVARIABLECONFIGVALUE.'

InputVariableConfig.name

An InputVariableConfig.name is a string used to identify input variables in a PromptTemplate.create and establish a corresponding property in the format input values.

const promptTemplate = PromptTemplate.create`
  My prompt template with ${{ name: 'inputVariableConfigName' }}.
`

const prompt = promptTemplate.format({
  inputVariableConfigName: 'inputVariableConfigValue',
})
//=> 'My prompt template with inputVariableConfigValue.'

InputVariableConfig.default

An InputVariableConfig.default is a default value for an input variable in a PromptTemplate.create and allows the corresponding property in the format inputValues to be omitted.

const promptTemplate = PromptTemplate.create`
  My prompt template with ${{
    name: 'inputVariableConfigName',
    default: 'inputVariableConfigDefault',
  }}.
`

const prompt = promptTemplate.format({})
//=> 'My prompt template with inputVariableConfigDefault.'

InputVariableConfig.description

The InputVariableConfig.description property is a string used to describe the input variable.

const promptTemplate = PromptTemplate.create`
  My prompt template with ${{
    name: 'inputVariableConfigName',
    description: 'My input variable description.',
  }}.
`

InputVariableConfig.onFormat

The InputVariableConfig.onFormat function is a callback used to provide custom formatting for inputValues and is called when the format method is called.

Arguments:

• inputValue: The input variable value passed to the format method.
• accumulatedPrompt: The accumulated prompt string up to the current position.

const promptTemplate = PromptTemplate.create`
  My prompt template with ${{
    name: 'inputVariableConfigName',
    onFormat: (inputValue, accumulatedPrompt) => inputValue.toUpperCase(),
  }}.
`

const prompt = promptTemplate.format({
  inputVariableConfigName: 'inputVariableConfigValue',
})
//=> 'My prompt template with INPUTVARIABLECONFIGVALUE.'

InputVariableConfig.schema

The InputVariableConfig.schema property accepts a Zod-like schema and is used to validate format inputValues.

const promptTemplate = PromptTemplate.create`
  My prompt template with ${{
    name: 'inputVariableConfigName',
    schema: z.string().nonempty(),
  }}.
`

const prompt = promptTemplate.format({
  inputVariableConfigName: 'inputVariableConfigValue',
})
//=> 'My prompt template with inputVariableConfigValue.'