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 config/prism.php to add your API keys (OpenAI, Anthropic, Gemini, etc.) under providers.

3. First Use Case: Generate a simple completion:

   use Prism\Prism;
   
   $response = Prism::make('openai')
       ->complete('What is Laravel?')
       ->get();
   

Key Starting Points

• Documentation: https://prismphp.com (official docs)
• Quickstart Guide: /docs/quickstart.md in the repo
• Provider-Specific Examples: /docs/providers/openai.md, /docs/providers/anthropic.md, etc.

Implementation Patterns

Core Workflows

1. Basic Completions

// Simple text generation
$response = Prism::make('openai')
    ->complete('Summarize this: "The quick brown fox..."')
    ->get();

// With parameters
$response = Prism::make('openai')
    ->complete('Explain quantum computing')
    ->temperature(0.7)
    ->maxTokens(100)
    ->get();

2. Conversations (Multi-Turn)

$conversation = Prism::make('anthropic')
    ->conversation()
    ->say('Hello!');

// Add user message
$conversation->user('What is AI?');

// Get AI response
$response = $conversation->get();

3. Tool Integration

// Define a tool
$tool = Prism::tool()
    ->name('getWeather')
    ->description('Fetch weather data')
    ->parameters([
        'location' => 'string',
        'unit' => ['type' => 'string', 'enum' => ['celsius', 'fahrenheit']]
    ])
    ->handler(function ($location, $unit) {
        // Call external API or service
        return ['temperature' => 22, 'unit' => $unit];
    });

// Use in a conversation
$conversation = Prism::make('gemini')
    ->conversation()
    ->tools([$tool])
    ->say('What is the weather in Paris?');

4. Streaming Responses

Prism::make('openai')
    ->complete('Stream this response')
    ->stream()
    ->each(function ($chunk) {
        echo $chunk->content;
    });

5. Embeddings

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

Integration Tips

Laravel Service Providers

Register Prism in AppServiceProvider:

public function boot()
{
    Prism::extend('custom', function () {
        return new \Prism\Providers\CustomProvider();
    });
}

Macros for Customization

Extend Prism's base class:

Prism::macro('customMethod', function () {
    return $this->complete('Custom logic here');
});

Tool Integration with Laravel Jobs

// Define a tool that dispatches a job
$tool = Prism::tool()
    ->name('sendEmail')
    ->handler(function ($to, $subject, $body) {
        SendEmailJob::dispatch($to, $subject, $body);
        return ['status' => 'queued'];
    });

Caching Responses

$response = Prism::make('openai')
    ->complete('Frequent question')
    ->remember(3600) // Cache for 1 hour
    ->get();

Gotchas and Tips

Common Pitfalls

1. Provider-Specific Quirks

• OpenAI: Ensure max_tokens is set for non-streaming requests (removed as default in v0.99.6).
• Anthropic: Structured output mode (v0.100.0+) requires explicit schema definitions.
• Gemini: Tool calls may fail if thoughts are included unintentionally (fixed in v0.99.0).

2. Streaming Issues

• Double Events: Fixed in v0.99.10 for Gemini/Anthropic (check for duplicate start/end events).
• Tool Call Streaming: Ensure streamToolParams is enabled for real-time tool parameter streaming (v0.99.7+).

3. Tool Handling

• Tool Errors: Always handle ToolResultEvent with success: false for unhandled tool errors.
• Artifacts: Use tool()->artifacts() to attach files or metadata to tools (v0.99.11).

4. Configuration Overrides

• Base URLs: Some providers (e.g., Anthropic) allow configurable base URLs (v0.98.5).
• Default Models: Override in config/prism.php:

  'providers' => [
      'openai' => [
          'default_model' => 'gpt-4',
      ],
  ],
  

Debugging Tips

1. Enable Verbose Logging

Prism::debug(true); // Logs raw API requests/responses

2. Handle Exceptions

try {
    $response = Prism::make('openai')->complete('Test')->get();
} catch (\Prism\Exceptions\PrismException $e) {
    // Log or handle provider-specific errors
    if ($e instanceof \Prism\Exceptions\PrismProviderOverloadedException) {
        // Retry logic or fallback
    }
}

3. Validate Tool Schemas

• Use Prism::tool()->validate() to check schema syntax before runtime.
• Common issues:
  • Missing type in parameters.
  • Invalid enum values.
  • Nested objects without properties.

Extension Points

1. Custom Providers

Extend \Prism\Contracts\Provider:

class CustomProvider extends \Prism\Providers\BaseProvider
{
    public function complete($prompt, array $options = [])
    {
        // Custom logic
        return $this->response(['content' => 'Custom response']);
    }
}

2. Event Listeners

Listen for streaming events:

Prism::on('streaming', function ($event) {
    if ($event->type === 'content') {
        echo $event->content;
    }
});

3. Middleware for Requests

Add middleware to modify requests:

Prism::extend('openai', function () {
    $provider = new \Prism\Providers\OpenAIProvider();
    $provider->middleware(function ($request) {
        $request->headers->set('Custom-Header', 'Value');
    });
    return $provider;
});

4. Testing

Use the PrismTestCase trait:

use Prism\Testing\PrismTestCase;

class MyTest extends PrismTestCase
{
    public function testCompletion()
    {
        $this->mockPrism('openai', [
            'content' => 'Mocked response'
        ]);
        $response = Prism::make('openai')->complete('Test')->get();
        $this->assertEquals('Mocked response', $response->content);
    }
}

Performance Tips

1. Batch Embeddings

$embeddings = Prism::make('openai')
    ->embeddings(['text1', 'text2', 'text3'])
    ->batchSize(4) // If supported by provider
    ->get();

2. Cache Aggressively

Prism::make('openai')
    ->complete('Frequent query')
    ->remember(86400) // 24 hours
    ->get();

3. Streaming Efficiency

• Use stream()->each() for real-time processing to avoid memory buildup.
• Disable streaming for non-interactive use cases.

Provider-Specific Notes