feat: Prompt factories

[tymondesigns]

🚀 Overview

This PR introduces Prompt Factories to Cortex, enabling developers to manage and retrieve prompts from external services like Langfuse. This feature provides a centralized way to store, version, and manage prompts outside of your codebase while maintaining full integration with Cortex's existing functionality.

✨ Key Features

🏭 Prompt Factory System

• Manager-based architecture using Laravel's Manager pattern via PromptFactoryManager
• Multiple provider support with pluggable factory implementations
• Configuration-driven setup through config/cortex.php

🦜 Langfuse Integration (Complete)

• Full Langfuse API integration for prompt retrieval
• Support for both chat and text prompts from Langfuse
• Version and label-based prompt selection
• Automatic metadata parsing including structured output configs
• Message placeholder support for dynamic prompt construction
• Secure credential handling with sensitive parameter protection

🔌 MCP Support (Foundation)

• Model Context Protocol (MCP) foundation laid for future implementation
• Placeholder implementation ready for extension

🛠 Enhanced Developer Experience

Flexible Prompt Creation

The Cortex::prompt() method now supports multiple patterns:

// Get a prompt factory (NEW)
$prompt = Cortex::prompt()->factory('langfuse')->make('my-prompt');

// Get a text prompt builder
$prompt = Cortex::prompt('What is the capital of {country}?');

// Get a chat prompt builder  
$prompt = Cortex::prompt([
    new SystemMessage('You are an expert.'),
    new UserMessage('Answer this: {question}')
]);

// Use builder pattern directly
$prompt = Cortex::prompt()->builder('chat')->messages([...]);

Metadata Support

Enhanced metadata handling for prompts:

$result = Cortex::prompt('What is the capital of {country}?')
    ->metadata(
        provider: 'anthropic',
        model: 'claude-3-5-sonnet-20240620',
        structuredOutput: SchemaFactory::object()->properties(
            SchemaFactory::string('capital')
        )
    )
    ->llm()
    ->invoke(['country' => 'France']);

🏗 Architecture Changes

New Components

• PromptFactoryManager - Central manager for prompt factory drivers
• PromptFactory Contract - Interface for prompt factory implementations
• PromptType Enum - Type-safe prompt type definitions with builder factories
• PromptFactory Facade - Convenient facade access
• Enhanced PromptBuilder Contract - Added metadata() and llm() convenience methods

Configuration

New configuration section in config/cortex.php:

'prompt_factory' => [
    'default' => env('CORTEX_DEFAULT_PROMPT_FACTORY', 'langfuse'),
    
    'langfuse' => [
        'username' => env('LANGFUSE_USERNAME'),
        'password' => env('LANGFUSE_PASSWORD'), 
        'base_uri' => env('LANGFUSE_BASE_URI', 'https://cloud.langfuse.com'),
    ],
    
    'mcp' => [
        'base_uri' => env('MCP_BASE_URI', 'http://localhost:3000'),
    ],
],

🔄 Backward Compatibility

✅ Fully backward compatible - All existing Cortex::prompt() usage continues to work unchanged.

🧪 Technical Details

Langfuse Implementation Highlights

• HTTP client abstraction using PSR-7/18 standards
• Comprehensive type safety with detailed PHPStan annotations
• Error handling with proper exception mapping
• Flexible metadata resolution with customizable resolvers
• Support for complex message types including placeholders

Service Provider Integration

• Singleton registration for PromptFactoryManager
• Contract binding for dependency injection
• Facade registration for convenient access

📋 What's Next

• Complete MCP (Model Context Protocol) implementation
• Add additional prompt factory providers as needed
• Expand metadata resolution capabilities
• Add caching layer for prompt retrieval

[Copilot]

Pull Request Overview

This PR introduces a Prompt Factory system to Cortex, enabling developers to manage and retrieve prompts from external services like Langfuse. The system provides a centralized way to store, version, and manage prompts outside the codebase while maintaining full integration with Cortex's existing functionality.

Key changes include:

• Prompt Factory Architecture: Manager-based system using Laravel's Manager pattern with pluggable factory implementations
• Langfuse Integration: Complete API integration for prompt retrieval with support for chat/text prompts, versioning, and metadata parsing
• Enhanced API: Extended Cortex::prompt() method to support factory access and flexible prompt creation patterns

Reviewed Changes

Copilot reviewed 19 out of 19 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tests/Unit/Prompts/Factories/LangfusePromptFactoryTest.php	Comprehensive test suite for Langfuse prompt factory functionality
src/Support/Utils.php	Updated PHPDoc to include MessagePlaceholder support
src/Support/Traits/DiscoversPsrImplementations.php	Added nullable discovery methods and fail-safe variants
src/Prompts/Templates/ChatPromptTemplate.php	Updated PHPDoc to remove non-empty-array constraint
src/Prompts/PromptFactoryManager.php	Laravel Manager implementation for prompt factory drivers
src/Prompts/Prompt.php	Static helper class for prompt builder and factory access
src/Prompts/Factories/McpPromptFactory.php	Placeholder MCP implementation
src/Prompts/Factories/LangfusePromptFactory.php	Complete Langfuse prompt factory with caching and metadata support
src/Prompts/Enums/PromptType.php	Type-safe prompt type enumeration with builder factories
src/Prompts/Contracts/PromptFactory.php	Interface for prompt factory implementations
src/Prompts/Contracts/PromptBuilder.php	Enhanced contract with metadata and LLM convenience methods
src/Prompts/Builders/Concerns/BuildsPrompts.php	Added setMetadata method for prompt builders
src/Prompts/Builders/ChatPromptBuilder.php	Updated PHPDoc for MessagePlaceholder support
src/LLM/LLMManager.php	Improved PHPDoc type annotations
src/Facades/PromptFactory.php	Facade for convenient prompt factory access
src/CortexServiceProvider.php	Service provider registration for prompt factory services
src/Cortex.php	Enhanced prompt method to support factory access patterns
scratchpad.php	Usage examples for new prompt factory features
config/cortex.php	Configuration section for prompt factory settings

Comments suppressed due to low confidence (1)

tests/Unit/Prompts/Factories/LangfusePromptFactoryTest.php:25

• [nitpick] Global functions in test files should have more specific names to avoid potential naming conflicts. Consider renaming to 'createTestLangfuseFactory' or using a class-based approach.

function createLangfuseFactory(