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

📑 Table of Contents

• 🚀 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

🚀 Installation

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

⚡ Quick Start

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

Process the template

petk process greeting.md --name "World"

Convert to YAML for API usage

petk convert greeting.md --to yaml

⭐ Core Features

🧩 Advanced Template Engine

• 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

📁 Intelligent Content Assembly

• 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

🔄 Multi-Format Conversion

• 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

⚡ Professional Workflow Tools

• 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

📖 CLI Commands

Command	Purpose	Example
process	Build templates with variable substitution	petk process template.md --var value
convert	Transform Markdown to YAML/JSON	petk convert input.md --to yaml
validate	Check template syntax and structure	petk validate templates/
watch	Monitor and rebuild templates automatically	petk watch src/ --output dist/
config	Manage project configuration	petk config set paths.templates ./prompts

💡 Example: Building a Modular Prompt System

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

🛠️ Advanced Template Syntax

Variable Substitution

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}}

Directive Blocks

Directives use fenced code blocks with YAML syntax:

Basic File Inclusion

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

Advanced Glob Patterns

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
```

📚 Documentation

• 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

🎯 Why Petk for Prompt Engineering?

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

🏗️ Project Structure

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

🤝 Contributing

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.

📄 License

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

---

🚀 Get Started • https://petk.dev/docs 📖 View Documentation • 🐛 Report Issues • Contribute

Made with ❤️ for the AI development community