Prompt Deck Laravel Package

## Getting Started

### Minimal Setup
1. **Installation**:
   ```bash
   composer require promptphp/deck
   php artisan vendor:publish --provider="PromptPHP\Deck\Providers\DeckServiceProvider"
   php artisan migrate

• Publishes config (config/deck.php) and migrations for tracking prompt executions.

2. First Prompt:

   php artisan make:prompt order-summary
   

   • Creates resources/prompts/order-summary/ with versioned files (v1/system.md, v1/user.md).
   • Edit files with {{ $variable }} syntax for dynamic values.

3. First Usage:

   use PromptPHP\Deck\Facades\Deck;
   
   $prompt = Deck::get('order-summary');
   $messages = $prompt->toMessages(['tone' => 'friendly', 'order' => $order]);
   

   • Loads the active version and renders variables into API-ready messages.

Where to Look First

• Artisan Commands:
  • make:prompt – Scaffold new prompts.
  • prompt:list – View all prompts and versions.
  • prompt:activate – Switch active versions (e.g., php artisan prompt:activate order-summary v2).
• Config: config/deck.php – Toggle features like auto-scaffolding for Laravel AI agents.
• Docs: deck.promptphp.com – API reference, tracking, and A/B testing guides.

Implementation Patterns

Core Workflow: Prompt Lifecycle

1. Design:
   • Use make:prompt to create structured directories (system.md, user.md).
   • Example:

     # v1/system.md
     You are a {{ $role }} assistant. Respond in {{ $tone }}.
     

2. Develop:
   • Inject variables dynamically:

     $prompt->system(['role' => 'customer support', 'tone' => 'professional']);
     

3. Test:
   • Activate versions via CLI or config:

     config(['deck.activated' => ['order-summary' => 'v2']]);
     

   • Use Deck::get('prompt')->diff('v1') to compare versions.
4. Deploy:
   • Track executions with prompt:track or auto-track via middleware:

     Deck::track('order-summary', ['user_id' => 123]);
     

Integration with Laravel AI SDK

• Agents: Add HasPromptTemplate to agents to auto-generate instructions():

  class OrderAgent extends Agent {
      use HasPromptTemplate;
      // No manual instructions() needed.
  }
  

• Auto-Scaffolding: Enable in config/deck.php:

  'auto_scaffold_agents' => true,
  

  Now make:agent creates matching prompt directories.

Performance Tracking

• Manual Tracking:

  Deck::track('prompt_name', [
      'variables' => ['tone' => 'friendly'],
      'metadata' => ['user_id' => 1, 'response_time' => 120],
  ]);
  

• Middleware: Use PromptExecutionMiddleware to auto-track API calls:

  protected $middleware = [\PromptPHP\Deck\Http\Middleware\TrackPromptExecutions::class];
  

A/B Testing

1. Activate Versions:

   php artisan prompt:activate order-summary v1 --env=staging
   php artisan prompt:activate order-summary v2 --env=production
   

2. Analyze: Query prompt_executions table:

   $executions = \PromptPHP\Deck\Models\PromptExecution::where('prompt_name', 'order-summary')
       ->where('version', 'v1')
       ->get();
   

Gotchas and Tips

Pitfalls

1. Version Confusion:

   • v1 and 1 are equivalent, but mixing formats (e.g., Deck::get('prompt', 1) vs. Deck::get('prompt', 'v1')) may cause issues.
   • Fix: Use consistent formatting (prefer v1 for clarity).

2. Variable Interpolation:

   • Undefined variables ({{ $missing }}) render as literal text.
   • Fix: Validate variables before rendering or use default values:

     $prompt->system(['tone' => 'friendly', 'order' => $order ?? 'N/A']);
     

3. File Permissions:

   • Prompts are stored in resources/prompts/. Ensure Laravel’s storage permissions allow writes:

     chmod -R 755 resources/prompts/
     

4. Laravel AI SDK Quirks:

   • If HasPromptTemplate doesn’t auto-generate instructions(), verify:
     • The prompt directory exists (e.g., resources/prompts/order-agent/).
     • The agent’s prompt_name matches the directory name (case-sensitive).

5. Tracking Overhead:

   • Every Deck::track() inserts a row into prompt_executions. For high-volume apps, batch writes:

     \PromptPHP\Deck\Facades\Deck::batchTrack([
         ['prompt_name' => 'order-summary', 'data' => [...]],
         ['prompt_name' => 'support-agent', 'data' => [...]],
     ]);
     

Debugging Tips

1. Prompt Not Found:

   • Check config/deck.php for prompt_paths (default: resources/prompts).
   • Verify the directory name matches the prompt name (e.g., Deck::get('order-summary') → resources/prompts/order-summary/).

2. Version Activation:

   • Use php artisan prompt:list to confirm active versions.
   • For programmatic checks:

     $activeVersion = Deck::getActiveVersion('order-summary');
     

3. Variable Rendering:

   • Test interpolation manually:

     $rendered = Deck::render('order-summary', ['tone' => 'friendly']);
     

Extension Points

1. Custom Storage:

   • Override PromptManager to use a database or cloud storage:

     // app/Providers/DeckServiceProvider.php
     $this->app->singleton(\PromptPHP\Deck\Contracts\PromptManager::class, CustomPromptManager::class);
     

2. Variable Parsers:

   • Extend interpolation with custom syntax (e.g., {{{ $json }}} for JSON variables):

     // app/Providers/DeckServiceProvider.php
     Deck::extend('custom_parser', function ($value) {
         return json_decode($value);
     });
     

     Usage:

     # v1/system.md
     Process this JSON: {{{ $data }}}
     

3. Tracking Events:

   • Listen for prompt.executed events to add custom logic:

     \PromptPHP\Deck\Events\PromptExecuted::dispatch($execution);
     

4. CLI Customization:

   • Extend Artisan commands (e.g., add --diff flag to prompt:list):

     // app/Console/Commands/CustomPromptList.php
     use PromptPHP\Deck\Console\PromptListCommand;
     class CustomPromptList extends PromptListCommand {
         protected $signature = 'prompt:list {--diff}';
         // ...
     }
     

Performance Optimizations

1. Caching:

   • Cache rendered prompts for repeated calls:

     $cached = Cache::remember("prompt_{$promptName}", now()->addHours(1), function () use ($promptName) {
         return Deck::get($promptName)->toMessages($variables);
     });
     

2. Bulk Operations:

   • Use Deck::getMultiple(['prompt1', 'prompt2']) to load multiple prompts in one query.

3. Database Indexes:

   • Add indexes to prompt_executions for high-traffic prompts:

     Schema::table('prompt_executions', function (Blueprint $table) {
         $table->index(['prompt_name', 'version']);
     });
     

Configuration Quirks

1. Auto-Scaffolding:

   • If make:agent doesn’t create prompts, ensure:

     'auto_scaffold_agents' => true, // config/deck.php
     

   • Manually trigger scaffolding:

     php artisan deck:scaffold-agent OrderAgent
     

2. Environment-Specific Versions:

   • Use .env to override active versions:

     DECK_ACTIVATED_ORDER_SUMMARY=v2
     

   • Parse in DeckServiceProvider:

     $this->app->singleton(PromptManager::class, function () {
         $manager = new PromptManager();
         $manager->setActivatedVersions(config('deck.activated', []));
         return $manager;