Deck Laravel Package

Technical Evaluation

Architecture Fit

• Laravel-Native Integration: Designed specifically for Laravel, leveraging its service providers, facades, and Artisan ecosystem. Fits seamlessly into Laravel’s modular architecture (e.g., DeckServiceProvider, Deck facade).
• AI Prompt Management: Addresses a critical gap in Laravel’s AI ecosystem by providing versioned, structured prompt storage—ideal for teams using Laravel AI SDK or custom LLM integrations.
• Separation of Concerns: Prompts are stored as files (Markdown) in resources/prompts/, decoupling logic from runtime execution. Metadata (e.g., descriptions, variables) is stored in metadata.json, enabling structured data access.
• Extensibility: Supports custom roles (e.g., system, user, assistant) and integrates with Laravel AI SDK via HasPromptTemplate trait, reducing boilerplate for AI agents.

Integration Feasibility

• Low Friction: Requires minimal setup (publish config/migrations, run migrate). No complex dependencies beyond Laravel core.
• Artisan-Driven Workflow: CLI commands (make:prompt, prompt:activate) align with Laravel’s developer experience, reducing cognitive load.
• Database vs. File-Based: Optional database tracking (via prompt_versions table) for A/B testing or performance metrics, but file-based fallback ensures zero-downtime adoption.
• Variable Interpolation: Uses Laravel’s native string replacement ({{ $variable }}), compatible with existing templating logic.

Technical Risk

• Versioning Complexity: File-based versioning (e.g., v1/, v2/) could conflict with CI/CD pipelines if not managed carefully (e.g., accidental overwrites). Mitigated by --force flag and interactive prompts.
• Performance Tracking: Database tracking adds overhead for high-frequency prompt activations. Requires monitoring to balance features with latency.
• LLM Provider Agnosticism: While designed for Laravel AI SDK, custom integrations (e.g., OpenAI, Anthropic) may need adapter layers for toMessages() output.
• Migration Path: Upgrade from veeqtoh/prompt-deck (v0.3.x) requires namespace changes (Veeqtoh\PromptDeck → PromptPHP\Deck). Test thoroughly in staging.

Key Questions

1. Use Case Alignment:
   • Is prompt versioning/A/B testing a priority, or is this primarily for structured storage?
   • Will prompts be used across multiple Laravel services (monorepo) or isolated apps?
2. Scaling Needs:
   • How many prompts/versions will be managed? File-based systems may slow with >10K prompts.
   • Is database tracking for performance metrics critical, or can analytics be added later?
3. CI/CD Impact:
   • How will prompt files be version-controlled (e.g., Git LFS for Markdown)? Will CI pipelines need to handle make:prompt?
4. Security:
   • Are prompts sensitive (e.g., containing PII)? If so, access controls (e.g., middleware) may be needed beyond the package’s scope.
5. LLM Integration:
   • Will prompts be used with Laravel AI SDK exclusively, or will custom LLM clients require additional adapters?

Integration Approach

Stack Fit

• Laravel Core: Fully compatible with Laravel 10/11 (PHP 8.1+). Leverages facades, service providers, and Artisan.
• AI Ecosystem:
  • Laravel AI SDK: Native integration via HasPromptTemplate trait (auto-generates instructions() for agents).
  • Custom LLM Clients: toMessages() output is flexible but may need wrapping for non-Laravel AI SDK providers.
• Database: Optional prompt_versions table for tracking (uses Laravel migrations). No hard dependency.
• File System: Prompts stored in resources/prompts/ (convention over configuration). Custom paths possible via config.

Migration Path

1. Evaluation Phase:
   • Install in a staging environment: composer require promptphp/deck.
   • Publish config: php artisan vendor:publish --provider="PromptPHP\Deck\Providers\DeckServiceProvider".
   • Test with a single prompt: php artisan make:prompt test-prompt.
2. Pilot Phase:
   • Migrate 1–2 critical prompts to Deck, compare with existing storage (e.g., hardcoded strings, external files).
   • Validate variable interpolation and toMessages() output for target LLM providers.
3. Full Adoption:
   • Run migrations: php artisan migrate (if using database tracking).
   • Update CI/CD pipelines to handle resources/prompts/ (e.g., Git ignore rules, artifact storage).
   • Replace hardcoded prompts with Deck::get() calls.
4. Legacy Sunset:
   • Deprecate old prompt storage mechanisms (e.g., config files) via deprecation warnings.
   • Use prompt:list to audit adoption.

Compatibility

• Laravel Versions: Tested on Laravel 10/11. May require adjustments for older versions (e.g., PHP 8.0).
• PHP Extensions: None beyond Laravel’s requirements (e.g., fileinfo, mbstring).
• LLM Providers: Agnostic but optimized for Laravel AI SDK. Custom adapters needed for:
  • Non-JSON message formats (e.g., Anthropic’s messages vs. OpenAI’s content).
  • Async/streaming responses (Deck focuses on prompt construction, not execution).
• Monorepos: File-based storage works across services, but database tracking (if used) must be shared via a central DB.

Sequencing

1. Foundational Setup:
   • Install package, publish config, run migrations.
   • Configure deck.php (e.g., active_version_strategy, storage_path).
2. Prompt Creation:
   • Scaffold prompts via make:prompt (e.g., php artisan make:prompt order-summary --user).
   • Define variables in Markdown (e.g., {{ $tone }}).
3. Integration:
   • Replace hardcoded prompts with Deck::get('prompt-name')->toMessages($variables).
   • For Laravel AI SDK: Add HasPromptTemplate to agents.
4. Advanced Features:
   • Enable database tracking for A/B testing.
   • Use prompt:diff to compare versions pre-deployment.
5. Monitoring:
   • Log prompt usage (e.g., Deck::get() calls) for analytics.
   • Set up alerts for failed prompt loads (e.g., missing files).

Operational Impact

Maintenance

• Prompt Updates:
  • New versions created via make:prompt (interactive or CLI). No manual file management.
  • Rollbacks: Activate previous versions via prompt:activate or Deck::get('name', 'v1').
• Dependency Management:
  • Package updates: Monitor promptphp/deck for breaking changes (e.g., v0.4.0 namespace shift).
  • Laravel upgrades: Test compatibility with new Laravel releases (e.g., facades, Artisan changes).
• Backup/Recovery:
  • Prompts are files → backed up with resources/. Database tracking (if used) requires standard DB backups.
  • Disaster recovery: Restore resources/prompts/ from Git or artifacts.

Support

• Troubleshooting:
  • Missing Prompts: Verify resources/prompts/ exists and files are readable.
  • Variable Errors: Check metadata.json for valid variable names (e.g., {{ $invalid }} → error).
  • Database Issues: Ensure prompt_versions table is migrated and writable.
  • CLI Errors: Use --force cautiously; prefer interactive prompts for safety.
• Documentation:
  • Comprehensive docs.deck.promptphp.com covers CLI, API, and Laravel AI SDK integration.
  • GitHub issues are responsive (MIT license, active maintainer).
• Community:
  • Laravel News feature suggests strong adoption. Leverage Laravel Discord/Forums for peer support.

Scaling

• Performance:
  • File I/O: Reading Markdown files is lightweight but could bottleneck with >10K prompts. Monitor Deck::get() latency.
  • Database Tracking: Queries to prompt_versions are minimal (e.g., WHERE prompt_name = ? AND is_active = 1). Index prompt_name and is_active.
  • Caching: Cache active prompt versions in memory (e.g., Laravel’s cache) to reduce disk I/O.
• Horizontal Scaling:
  • File-based storage is stateless → scales with Laravel’s deployment (e.g., shared storage for multi-server setups).
  • Database tracking requires a shared DB (e.g., PostgreSQL read replicas for read-heavy workloads).
• Cost:
  • No additional infrastructure costs beyond Laravel’s existing stack.
  • Database tracking adds minimal storage (~KB per prompt version).

Failure Modes