README

Introduction

Deck, formerly Prompt Deck, provides AI prompt management for Laravel and PHP.

Organise your AI agent instructions as versioned files, compare prompt performance, and activate the right version across your app with variable interpolation, tracking, A/B testing, and Laravel AI SDK integration.

Important

Prompt Deck is now Deck by PromptPHP.

From v0.4.0, the package moved from veeqtoh/prompt-deck to promptphp/deck, and the namespace changed from Veeqtoh\PromptDeck to PromptPHP\Deck.

Upgrading from v0.3.x? See the upgrade guide.

Quick Start

Installation

composer require promptphp/deck

Publish the config and migrations

php artisan vendor:publish --provider="PromptPHP\Deck\Providers\DeckServiceProvider"

# Run migrations.
php artisan migrate

Creating a Prompt

Use the Artisan command to create a versioned prompt

php artisan make:prompt order-summary

This creates the following structure

resources/prompts/order-summary/
├── metadata.json          # Prompt-level: name, description, roles, active version
└── v1/
    ├── metadata.json      # This version's own metadata
    └── system.md

Pass --user to add a user prompt, or --role= for any other role

php artisan make:prompt order-summary --user --role=assistant

resources/prompts/order-summary/
├── metadata.json
└── v1/
    ├── metadata.json
    ├── system.md
    ├── user.md
    └── assistant.md

Edit resources/prompts/order-summary/v1/system.md with your prompt content. Use {{ $variable }} syntax for dynamic values:

You are a {{ $tone }} customer service agent.
Summarise the following order for the customer: {{ $order }}.

Using a Prompt

Load and render prompts with the Deck facade

use PromptPHP\Deck\Facades\Deck;

// Load the active version of a prompt.
$prompt = Deck::get('order-summary');

// Render a role with variables.
$prompt->system(['tone' => 'friendly', 'order' => $orderDetails]);
// "You are a friendly customer service agent. Summarise the following order..."

// Build a messages array ready for any chat-completion API.
$messages = $prompt->toMessages(['tone' => 'friendly', 'order' => $orderDetails]);
// [['role' => 'system', 'content' => '...']]

Versioning

Run the command again on an existing prompt and Deck offers to create the next version or overwrite the current one

php artisan make:prompt order-summary

# Prompt [order-summary] already exists at version 1.
# What would you like to do?
#   [version  ] Create a new version (v2)
#   [overwrite] Overwrite version 1

Creating a version never changes which one your application serves, so you can draft freely in production

resources/prompts/order-summary/
├── metadata.json          # "active_version": 1
├── v1/                    # live: what Deck::get('order-summary') returns
│   ├── metadata.json
│   └── system.md
└── v2/                    # drafted, not serving traffic yet
    ├── metadata.json
    └── system.md

Check which version is live at any time

php artisan prompt:list --all

+---------------------+----------------+--------+------------------------------------------------------+
| Prompt              | Active Version | Active | Description                                          |
+---------------------+----------------+--------+------------------------------------------------------+
| order-summary       | v1             | ✅     | Summarises an order for the customer who placed it.  |
| order-summary       | v2             |        | Summarises an order for the customer who placed it.  |
+---------------------+----------------+--------+------------------------------------------------------+

Promote the new version when you are ready

php artisan prompt:activate order-summary v2

# or

php artisan prompt:activate order-summary 2

The active_version key in the prompt's root metadata.json flips to 2, and every Deck::get('order-summary') call starts returning v2. Roll back by activating v1 again.

Both formats work programmatically too

// Load a specific version.
$prompt = Deck::get('order-summary', 'v2');

// Promote a version.
Deck::activate('order-summary', 'v2');
Deck::activate('order-summary', 2);

Laravel AI SDK Integration

If you use the Laravel AI SDK, add the HasPromptTemplate trait to your agents. This way, you do not need to define the instructions() method as it is provided automatically.

use PromptPHP\Deck\Concerns\HasPromptTemplate;

class OrderAgent extends Agent
{
    use HasPromptTemplate;

    // instructions() and promptMessages() are provided automatically.
}

Running make:agent will also auto-scaffold a matching prompt directory.

For the complete guide, see the full documentation below.

Documentation

Full documentation can be found at https://deck.promptphp.com/ or the docs directory on GitHub.

Contributing

Thank you for considering contributing to Deck by PromptPHP. Please open an issue or submit a pull request on GitHub.

Code of Conduct

We follow the Laravel Code of Conduct. We expect you to abide by these guidelines as well.

Security Vulnerabilities

If you discover a security vulnerability within Deck by PromptPHP, please email Victor Ukam at victorjohnukam@gmail.com. All security vulnerabilities will be addressed promptly.

License

Deck by PromptPHP is open-sourced software licensed under the MIT license.

Support

This library is created by Victor Ukam with contributions from the Open Source Community. If you've found this package useful, please consider sponsoring this project. It will go a long way to help with maintenance.

promptphp / deck

Maintainers

Package info

Fund package maintenance!

Statistics

Security