@promptt/client

A simple TypeScript library for creating type-safe, structured prompts for Large Language Models (LLMs). Define your prompts in XML, and get fully typed interfaces for your AI interactions.

Features

• 📝 XML-based prompt definition
• 🔒 Type-safe prompt interfaces
• 🚀 Easy integration with any LLM provider
• 📦 Built-in validation and parsing
• 🛠️ CLI tool for code generation

Installation

npm install @promptt/client

# or

yarn add @promptt/client

Quick Start

1. Create a promptt directory in your project root
2. Create a prompt file (e.g., promptt/career-advice.prompt):

<prompt>
  <name>getCareerAdvice</name>
  <version>1.0</version>
  <parameters>
    <temperature>0.7</temperature>
  </parameters>
  <types>
  <input>
    <field name="name" type="String" required="true" />
    <field name="age" type="Int" min="13" max="100" />
    <field name="experience" type="Enum">
      <values>
        <value>BEGINNER</value>
        <value>INTERMEDIATE</value>
        <value>EXPERT</value>
      </values>
    </field>
  </input>
    <output>
      <field name="recommendations" type="String[]" />
      <field name="nextSteps" type="String[]" />
    </output>
  </types>
  <template>
Given a user named {{name}} (age: {{age}})
with {{experience}} experience level,
provide career advice.
  </template>
</prompt>

3. Generate type definitions:

npx promptt generate

4. Use the generated types in your code:

import { Promptt } from '@promptt/client';
import OpenAI from 'openai';

const promptt = new Promptt();
const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

async function getCareerAdvice() {
  // Generate the prompt string with type safety
  const promptString = await promptt.getCareerAdvice.render({
    name: 'John',
    age: 25,
    experience: 'INTERMEDIATE',
  });

  // Send to OpenAI
  const completion = await openai.chat.completions.create({
    messages: [{ role: 'user', content: promptString }],
    model: 'gpt-4o',
  });

  // Parse the response with type safety
  const result = await promptt.getCareerAdvice.parse(
    completion.choices[0].message.content
  );

  // result is now typed as:
  // {
  //   recommendations: string[];
  //   nextSteps: string[];
  // }

  return result;
}

Bonus: Using OpenAI's JSON Mode

You can also use OpenAI's JSON mode with the schema from your prompt definition for guaranteed structured outputs:

import { Promptt } from '@promptt/client';
import OpenAI from 'openai';
import { zodResponseFormat } from 'openai/helpers/zod'; // <- Note this import

const promptt = new Promptt();
const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

async function getCareerAdviceStructured() {
  const promptString = await promptt.getCareerAdvice.render({
    name: 'John',
    age: 25,
    experience: 'INTERMEDIATE',
  });

  // Get the output schema from the prompt definition
  const getCareerAdviceSchema = promptt.getCareerAdvice.outputSchema;

  // Use OpenAI's JSON mode with our schema
  const completion = await openai.beta.chat.completions.parse({
    model: 'gpt-4o',
    messages: [{ role: 'system', content: promptString }],
    response_format: zodResponseFormat(getCareerAdviceSchema, 'careerAdvice'),
  });

  // No need to parse - result is already typed!
  return completion.careerAdvice;
}

Prompt Definition Guide

When you run npx promptt generate, a comprehensive guide will be created at promptt/README.md. This guide contains detailed information about:

• File structure
• Prompt definition format
• Supported field types
• Field attributes
• Best practices

AI Assistant Integration

When using this project with AI assistants (like in Cursor), you can reference the prompt definition guide by including @promptt/README.md in your messages. For example:

"Using @promptt/README.md as context, create a prompt for sentiment analysis. Write a prompt definition that takes a text input and returns a sentiment score between -1 and 1."

The AI will understand the prompt definition format and help you create a properly structured prompt file.

Field Types

The following field types are supported:

• String: Text values
  • pattern: Optional regex pattern
• Int: Integer numbers
  • min: Minimum value
  • max: Maximum value
• Float: Decimal numbers
  • min: Minimum value
  • max: Maximum value
• Boolean: True/false values
• Enum: Fixed set of values
  • values: Array of allowed values
• Arrays: Append [] to any type
  • minItems: Minimum array length
  • maxItems: Maximum array length

For example, to define an array of strings with a minimum length of 1 and a maximum length of 10, you would use:

<field name="recommendations" type="String[]" minItems="1" maxItems="10" />

Field Attributes

Common attributes for all fields:

• name: Field identifier (required)
• type: Data type (required)
• required: Whether the field is required (default: true)
• description: Field description for documentation

Descriptions are useful specially in output schemas when using JSON mode to give the LLM more context about the expected output.

<field name="recommendations" type="String[]" minItems="1" maxItems="10" description="Recommendations for what the user should do next in their career." />

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). This license ensures that:

• The software can be freely used, modified, and distributed
• Any modifications must be released under the same license
• Source code must be made available when the software is used over a network
• Commercial use requires explicit permission and compliance with AGPL-3.0 terms

See the LICENSE file for the full license text.