Promptel

Declarative prompt engineering. Write once, run anywhere.

---

What is Promptel?

Promptel is a declarative framework for building production-grade LLM prompts. Define your prompts in a clean DSL or YAML, use built-in techniques like Chain-of-Thought, and deploy across OpenAI, Anthropic, or Groq without changing code.

const { executePrompt } = require('promptel');

const result = await executePrompt(`
prompt CodeReviewer {
  params { code: string }

  body {
    text\`Review this code for bugs and security issues:
    \${params.code}\`
  }

  technique {
    chainOfThought {
      step("Security") { text\`Check for vulnerabilities\` }
      step("Logic") { text\`Identify bugs\` }
      step("Quality") { text\`Suggest improvements\` }
    }
  }
}
`, { code: userCode });

Install

npm install promptel

Quick Start

1. Set your API key:

export PROMPTEL_API_KEY=sk-your-key

2. Create a prompt:

// app.js
const { executePrompt } = require('promptel');

async function main() {
  const result = await executePrompt(`
  prompt Summarizer {
    params { text: string }
    body { text\`Summarize in 2 sentences: \${params.text}\` }
    constraints { maxTokens: 100 }
  }
  `, { text: "Your long article here..." });

  console.log(result);
}

main();

3. Run it:

node app.js

Features

Feature	Description
Dual Format	Write prompts in .prompt DSL or YAML
Multi-Provider	OpenAI, Anthropic, Groq with consistent API
Techniques	Built-in Chain-of-Thought, Few-Shot, Tree-of-Thoughts
Harmony Protocol	Native multi-channel responses (OpenAI)
Type-Safe Params	Typed parameters with defaults and validation
CLI Included	Execute and convert prompts from terminal

Formats

Promptel supports two equivalent formats:

.prompt (DSL)	YAML
prompt Greeter { params { name: string lang?: string = "en" } body { text`Hello ${params.name}!` } }	name: Greeter params: name: type: string required: true lang: type: string default: "en" body: text: "Hello ${params.name}!"

Convert between them:

promptel --convert yaml -f prompt.prompt -o prompt.yml

Providers

Switch providers without changing prompts:

// OpenAI (default)
await executePrompt(prompt, params, { provider: 'openai' });

// Anthropic Claude
await executePrompt(prompt, params, { provider: 'claude' });

// Groq
await executePrompt(prompt, params, { provider: 'groq' });

Techniques

Built-in prompting techniques:

prompt Analyzer {
  technique {
    // Step-by-step reasoning
    chainOfThought {
      step("Understand") { text`Parse the input` }
      step("Analyze") { text`Find patterns` }
      step("Conclude") { text`Form conclusions` }
    }
  }
}

Available techniques:

• chainOfThought - Step-by-step reasoning
• fewShot - Learning from examples
• zeroShot - Direct instruction
• treeOfThoughts - Multiple solution paths
• reAct - Reasoning + Actions
• selfConsistency - Multi-sample consensus

Harmony Protocol

Multi-channel responses for advanced reasoning:

prompt HarmonyExample {
  harmony {
    reasoning: "high"
    channels: ["final", "analysis", "commentary"]
  }

  body { text`Solve: ${params.problem}` }
}

const result = await executePrompt(harmonyPrompt, { problem: "..." });

console.log(result.channels.final);      // Clean answer
console.log(result.channels.analysis);   // Reasoning steps
console.log(result.channels.commentary); // Additional context

CLI

# Execute prompt
promptel -f prompt.prompt -p openai -k $KEY --params '{"x":"value"}'

# Convert formats
promptel --convert yaml -f prompt.prompt

# Output to file
promptel -f prompt.yml -p claude -k $KEY -o result.json

API

const {
  parsePrompt,      // Parse .prompt or YAML to AST
  executePrompt,    // Execute prompt end-to-end
  FormatConverter,  // Convert between formats
  PromptelExecutor, // Low-level executor
  createProvider,   // Create provider instance
} = require('promptel');

// Parse without executing
const ast = parsePrompt(promptContent);

// Execute with options
const result = await executePrompt(content, params, {
  provider: 'openai',
  apiKey: process.env.OPENAI_API_KEY
});

// Convert formats programmatically
const converter = new FormatConverter();
const yaml = converter.promptToYaml(promptContent);

Project Structure

promptel/
├── src/
│   ├── index.js          # Main exports
│   ├── parser.js         # .prompt parser (Chevrotain)
│   ├── yaml-parser.js    # YAML parser
│   ├── executor.js       # Execution engine
│   ├── provider.js       # LLM providers
│   ├── format-converter.js
│   └── cli.js
├── tests/
├── examples/
└── documentation/        # MkDocs site

Development

git clone https://github.com/skelf-research/promptel.git
cd promptel
npm install

# Run tests
npm test

# Run linter
npm run lint

# Run integration tests
npm run test:integration

Documentation

Full documentation available at promptel.dev or in the documentation/ folder:

• Getting Started
• Format Guide
• Techniques
• Providers
• Harmony Protocol
• API Reference
• CLI Reference

Requirements

• Node.js 18+
• API key from OpenAI, Anthropic, or Groq

Contributing

Contributions welcome! Please read our contributing guidelines and submit PRs.

npm run lint      # Check code style
npm test          # Run tests
npm run validate  # Full validation

License

MIT License - see LICENSE for details.

---

Built for developers who ship AI to production.