Petk 🏸

Professional CLI toolkit for prompt engineering that enables systematic creation, management, and optimization of prompts for Large Language Models with advanced templating capabilities.

🚀 Get Started • https://petk.dev/docs 📖 Documentation • 🎯 Examples • 🏗️ Architecture

• 🚀 Installation
• ⚡ Quick Start
• ⭐ Core Features
• 📖 CLI Commands
• 💡 Example: Building a Modular Prompt System
• 🛠️ Advanced Template Syntax
• 📚 Documentation
• 🎯 Why Petk for Prompt Engineering?
• 🏗️ Project Structure
• 🤝 Contributing
• 📄 License

Install Petk using your preferred package manager:

# Using npm
npm install -g petk

# Using pnpm (recommended)
pnpm add -g petk

# Using yarn
yarn global add petk

Create your first template and process it in minutes:

# Create your first template
echo '# Hello {{name}}!

```{petk:include}
path: examples/greeting.md
```

Welcome to prompt engineering!' > greeting.md

petk process greeting.md --name "World"

petk convert greeting.md --to yaml

• Conditional Logic: Dynamic content with intelligent processing
• Variable Substitution: {{variable}} syntax with nested object support
• File Inclusion: Powerful file embedding with {petk:include} directive blocks
• Glob Patterns: Advanced file matching with sorting and filtering capabilities
• Recursive Resolution: Templates can include other templates seamlessly

• Smart Sorting: Alphabetical, chronological, and file-size based ordering
• Deterministic Sampling: Reproducible random content selection with seed control
• Cycle Detection: Prevents infinite recursion in template dependencies
• Content Filtering: Include/exclude files based on patterns and criteria

• Markdown to YAML: Convert templates to LLM-ready configuration files
• Multimodal Support: Handle text, code blocks, and structured content
• AST Processing: Advanced Markdown parsing and transformation
• Schema Validation: Ensure output meets API requirements

• Watch Mode: Real-time template processing during development
• Template Validation: Syntax checking and error reporting
• Configuration Management: Project-wide settings and path aliases
• Performance Optimized: Fast processing of large template collections

1. Create a base template (base-prompt.md):

# AI Assistant Instructions

You are a helpful AI assistant specialized in {{domain}}.

## Available Tools

```{petk:include}
glob: tools/**/*.md
order_by: alphabetical_asc
```

## Context Guidelines

```{petk:include}
path: shared/guidelines.md
```

## Examples

```{petk:include}
glob: examples/{{domain}}/*.md
limit: 3
order_by: last_updated_desc
```

2. Process with variables:

petk process base-prompt.md \
  --domain "software-engineering" \
  --output final-prompt.md

3. Convert for API usage:

petk convert final-prompt.md --to yaml --output prompt-config.yaml

Variables are enclosed in double curly braces and support nested objects:

# Welcome to {{site.title}}

This project is maintained by {{author.name}} ({{author.email}}).
Current version: {{version}}

Directives use fenced code blocks with YAML syntax:

```{petk:include}
path: shared/header.md
```

Include multiple files using glob patterns with sorting and filtering:

```{petk:include}
glob: posts/**/*.md
order_by: alphabetical_asc
```

```{petk:include}
glob: blog/**/*.md
order_by: last_updated_desc
limit: 5
```

```{petk:include}
glob: examples/**/*.md
order_by: random
seed: 12345
limit: 3
```

• Getting Started Guide - Installation and first steps
• Template Syntax Reference - Complete syntax documentation
• CLI Reference - All commands and options
• Use Cases & Examples - Real-world prompt engineering scenarios
• Architecture Overview - System design and components

Traditional Challenges:

• ❌ Manual copy-paste of prompt components
• ❌ No version control for prompt variations
• ❌ Difficult to maintain consistency across projects
• ❌ Hard to test different prompt combinations
• ❌ No systematic approach to prompt optimization

Petk Solutions:

• ✅ Modular Design: Reusable components and systematic organization
• ✅ Version Control Friendly: Git-ready Markdown format
• ✅ Systematic Testing: Deterministic template generation for A/B testing
• ✅ Professional Workflows: Watch mode, validation, and automation
• ✅ Team Collaboration: Shared patterns and standardized approaches

Petk is built as a modern TypeScript monorepo:

petk/
├── apps/
│   ├── cli/           # Main CLI application
│   └── docs/          # Documentation site
├── packages/
│   ├── engine/        # Template processing engine
│   ├── converter/     # Markdown-to-YAML converter
│   └── utils/         # Shared utilities
└── docs/              # Documentation source

Contributions are welcome! Please read our CONTRIBUTING.md guide for details on the development process, coding conventions, and how to submit pull requests. This project follows the Conventional Commits specification.

Ready to contribute? 📖 Read our Contributing Guide and 🚀 Get started with development.

This project is licensed under the MIT License. See the LICENSE file for details.