prompt-utils v0.1.0

prompt-utils

A collection of LLM prompt utilities, primarily centered around the promptTemplate module. 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-utils

Usage

promptTemplate with InputVariableName

import { promptTemplate } from 'prompt-utils'

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

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

promptTemplate with InputVariableConfig.onFormat

import { promptTemplate } from 'prompt-utils'

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

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

promptTemplate with InputVariableConfig.schema

import { promptTemplate } from 'prompt-utils'
import { z } from 'zod'

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

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

promptTemplate with InputVariableConfig.default

import { promptTemplate } from 'prompt-utils'

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

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

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

promptTemplate with nested promptTemplate

import { promptTemplate } from 'prompt-utils'

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

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

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

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

promptTemplate with PromptTemplateOptions

import { promptTemplate } from 'prompt-utils'

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

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

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

API

promptTemplate

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

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

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

or

const userPromptTemplate = promptTemplate({ prefix: 'user: ' })

const myUserPromptTemplate = userPromptTemplate`
  My prompt template with ${'inputVariableName'}.
`

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

Note: The above is conventionally inlined:

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

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

PromptTemplate Class

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

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

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

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

const myPrompt = myPromptTemplate.format({
  inputVariableName: 'inputVariableValue' as const,
})
//=> '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 myNestedPromptTemplate = promptTemplate`
  My nested prompt template with ${'nestedInputVariableName'}.
`

const myPromptTemplate = promptTemplate`
  - My prompt template with ${'inputVariableName'}
  - My prompt template with ${{
    name: 'inputVariableConfigName' as const,
    default: 'inputVariableConfigDefault',
  }}
  - ${myNestedPromptTemplate}
`

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

const myPrompt = myPromptTemplate.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 myNestedPromptTemplate = promptTemplate`
  My nested prompt template with ${'nestedInputVariableName'}.
`

const myPromptTemplate = promptTemplate`
  - My prompt template with ${'inputVariableName'}.
  - My prompt template with ${{
    name: 'inputVariableConfigName' as const,
    default: 'inputVariableConfigDefault',
  }}.
  - ${myNestedPromptTemplate}
`

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

getInputVariableNamesRequired()

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

const myNestedPromptTemplate = promptTemplate`
  My nested prompt template with ${'nestedInputVariableName'}.
`

const myPromptTemplate = promptTemplate`
  - My prompt template with ${'inputVariableName'}.
  - My prompt template with ${{
    name: 'inputVariableConfigName' as const,
    default: 'inputVariableConfigDefault',
  }}.
  - ${myNestedPromptTemplate}
`

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

getInputVariableNamesOptional()

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

const myNestedPromptTemplate = promptTemplate`
  My nested prompt template with ${'nestedInputVariableName'}.
`

const myPromptTemplate = promptTemplate`
  - My prompt template with ${'inputVariableName'}.
  - My prompt template with ${{
    name: 'inputVariableConfigName' as const,
    default: 'inputVariableConfigDefault',
  }}.
  - ${myNestedPromptTemplate}
`

myPromptTemplate.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 myPromptTemplate = promptTemplate`
  My duplicate prompt template with ${'duplicateInputVariableName'} and ${{
    name: 'duplicateInputVariableName' as const,
    default: 'duplicateInputVariableNameDefault',
  }}.
`

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

myPromptTemplate.getInputVariableNamesOptional()
//=> []

PromptTemplateOptions

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

const promptTemplateOptions = {
  prefix: 'prefix - ',
  suffix: ' - suffix',
  dedent: true, // Default
}

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

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

InputVariableName

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

const myPromptTemplate = promptTemplate`
  My prompt template with ${'inputVariableName'}
`

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

InputVariableConfig

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

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

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

InputVariableConfig.name

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

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

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

InputVariableConfig.default

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

const myPromptTemplate = promptTemplate`
  My prompt template with ${{
    name: 'inputVariableConfigName' as const,
    default: 'inputVariableConfigDefault',
  }}
`

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

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.

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

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

InputVariableConfig.schema

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

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

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

Text Transforms

The following text transforms are simply a re-export of change-case and title-case with support for ESM and CJS.

• caseCamel
• caseCapital
• caseConstant
• caseDot
• caseKebab
• caseNo
• casePascal
• casePascalSnake
• casePath
• caseSentence
• caseSnake
• caseTrain
• caseTitle

Note: Each transform has been renamed in reverse order to improve autocomplete behavior and discovery.

import { promptTemplate, caseCapital } from 'prompt-utils'

const myPromptTemplate = promptTemplate`
  Brainstorm 3 superhero names for a ${{
    name: 'animal' as const,
    onFormat: caseCapital,
  }}
`

const myPrompt = myPromptTemplate.format({
  inputVariableName: 'cat' as const,
})
//=> 'Brainstorm 3 superhero names for a Cat.'

Additionally, the dedent module is re-exported from prompt-utils.

import { promptTemplate, dedent } from 'prompt-utils'

const chatPromptTemplate = promptTemplate`
  You are a friendly chatbot.

  Conversation:
  ${'history'}
  Human: ${'question'}
  AI:
`

const chatPrompt = chatPromptTemplate.format({
  history: dedent`
    Human: Brainstorm 3 superhero names for a cat.
    AI: Whisker Warrior, Shadow Pounce, and Feline Flash.
  `,
  question: 'What about a dog?',
})
//=> 'You are a friendly chatbot named Chatty.
//
//    Conversation:
//    Human: Brainstorm 3 superhero names for a cat.
//    AI: Whisker Warrior, Shadow Pounce, and Feline Flash.
//    Human: What about a dog?
//    AI:'