Prism Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require prism-php/prism
   

   Publish the config:

   php artisan prism:install
   

2. Configure Providers: Edit .env with your preferred LLM provider (e.g., OpenAI, Anthropic, Mistral) and API keys:

   PRISM_PROVIDERS=openai
   OPENAI_API_KEY=your_key_here
   

3. First Use Case: Generate text via a controller:

   use Prism\Prism;
   
   public function generateText()
   {
       $response = Prism::make('openai')
           ->model('gpt-4')
           ->text('What is Laravel?')
           ->get();
   
       return response()->json($response);
   }
   

Key Starting Points

• Official Docs: https://prismphp.com
• Provider Support: Check config/prism.php for enabled providers and their capabilities.
• Quickstart Guide: Prism Quickstart.

Implementation Patterns

Core Workflows

1. Basic Text Generation

$response = Prism::make('openai')
    ->model('gpt-4')
    ->text('Summarize this: ' . $longText)
    ->temperature(0.7)
    ->get();

2. Conversational Chains

$conversation = Prism::make('anthropic')
    ->model('claude-3')
    ->startConversation();

$conversation->say('Hello!');
$response = $conversation->ask('How are you?');

3. Tool Usage (Multi-Step Workflows)

Define tools in a Tool class:

use Prism\Tool;

class WeatherTool extends Tool
{
    public function handle(string $query): string
    {
        return "Weather for $query: Sunny";
    }
}

Register and use:

$response = Prism::make('openai')
    ->model('gpt-4')
    ->tools([new WeatherTool()])
    ->text('What is the weather in Paris?')
    ->get();

4. Streaming Responses

Prism::make('openai')
    ->model('gpt-4')
    ->text('Explain Laravel')
    ->stream()
    ->each(function ($chunk) {
        echo $chunk->content;
    });

5. Embeddings

$embeddings = Prism::make('openai')
    ->model('text-embedding-ada-002')
    ->embeddings(['Your text here'])
    ->get();

Integration Tips

• Service Providers: Bind Prism to your container for dependency injection:

  $this->app->singleton(PrismManager::class, function ($app) {
      return new PrismManager(config('prism'));
  });
  

• Event Listeners: Listen to ToolCallEvent, StreamEvent, etc., for real-time processing:

  Prism::make('openai')->listen(function ($event) {
      // Handle tool calls or streams
  });
  

• Skills (Modular Logic): Use Prism\Skill for reusable AI logic:

  Prism::skill('summarize')->run($longText);
  

Gotchas and Tips

Pitfalls

1. Provider-Specific Quirks:

   • Anthropic: Structured output now uses native mode (v0.100.0). Citations are incompatible with structured output.
   • OpenRouter: Null-coalesce JSON responses to avoid TypeError (fixed in v0.99.22).
   • Gemini: Streaming with parallel tool calls requires explicit handling (fixed in v0.99.15).

2. Streaming Artifacts:

   • Breaking Change (v0.99.19): Artifact data protocol key changed from artifact to data-artifact:

     - artifacts.set(data.toolCallId, data.artifact);
     + artifacts.set(data.data.toolCallId, data.data.artifact);
     

3. Tool Call Loops:

   • Infinite loops can occur with ToolChoice::Any. Use required mapping to enforce tool selection:

     ->tools([new WeatherTool()])
     ->toolChoiceMap(['required' => [WeatherTool::class]])
     

4. Rate Limits:

   • Anthropic’s rate limits use Unix timestamps. Handle PrismProviderOverloadedException for 503 errors (v0.100.0).

Debugging Tips

• Enable Debugging:

  PRISM_DEBUG=true
  

  Logs raw API responses and errors to storage/logs/prism.log.

• Tool Debugging: Expose raw tool call arguments:

  $response = Prism::make('openai')
      ->tools([new WeatherTool()])
      ->text('...')
      ->withDebug()
      ->get();
  

• Streaming Issues:

  • Ensure StreamEndEvent is emitted when tools reach maxSteps (fixed in v0.99.14).
  • Use ->each() for granular control over chunks.

Extension Points

1. Custom Providers: Extend Prism\Providers\Provider or use PrismManager::extend():

   PrismManager::extend('custom', function () {
       return new CustomProvider();
   });
   

2. Event Customization: Override default events (e.g., ToolCallEvent) in EventServiceProvider:

   Prism::make('openai')->listen(function ($event) {
       // Custom logic
   });
   

3. Skills System: Create modular AI skills in app/Skills/:

   namespace App\Skills;
   
   use Prism\Skill;
   
   class SummarizeSkill extends Skill
   {
       public function handle(string $text): string
       {
           return Prism::make('openai')
               ->model('gpt-4')
               ->text("Summarize: $text")
               ->get()
               ->content;
       }
   }
   

   Register in config/prism.php:

   'skills' => [
       App\Skills\SummarizeSkill::class,
   ],
   

4. Caching: Enable automatic caching for Anthropic (v0.99.21):

   Prism::make('anthropic')->withCache();
   

Performance Tips

• Batch Embeddings: Use ->batch() for bulk embedding generation (supported by OpenAI, Gemini, etc.).
• Concurrent Tools: Execute tools in parallel (v0.99.18):

  ->tools([$tool1, $tool2])
  ->concurrent()