Laravel Prism Upstage Solar Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require omiya0555/laravel-prism-upstage-solar
   php artisan vendor:publish --tag=config --provider="Omiya0555\LaravelPrismUpstage\PrismUpstageSolarServiceProvider"
   

   Configure .env with your Upstage Solar API key:

   UPSTAGE_SOLAR_API_KEY=your_api_key_here
   

2. First Use Case: Generate text via a route or controller:

   use Omiya0555\LaravelPrismUpstage\Facades\UpstageSolar;
   
   Route::get('/generate', function () {
       $response = UpstageSolar::generate('Write a blog post about Laravel 12 features.');
       return response()->json($response);
   });
   

3. Streaming Response:

   $stream = UpstageSolar::stream('Generate a real-time story');
   foreach ($stream as $chunk) {
       echo $chunk;
   }
   

Implementation Patterns

Core Workflows

1. Service Integration:

   • Use the facade (UpstageSolar) or inject the service (UpstageSolarService) into controllers/services.
   • Example:

     public function __construct(private UpstageSolarService $upstage) {}
     

2. Model Selection:

   • Configure default model in config/prism_upstage.php:

     'default_model' => 'upstage-solar-text-v1',
     

   • Override per request:

     UpstageSolar::generate('Prompt', ['model' => 'upstage-solar-text-v2']);
     

3. Request/Response Handling:

   • Customize request parameters:

     UpstageSolar::generate('Prompt', [
         'temperature' => 0.7,
         'max_tokens' => 1000,
     ]);
     

   • Parse responses with Laravel collections:

     collect($response)->each(function ($chunk) {
         // Process chunks
     });
     

4. Error Handling:

   • Wrap calls in try-catch:

     try {
         $response = UpstageSolar::generate('Prompt');
     } catch (\Omiya0555\LaravelPrismUpstage\Exceptions\UpstageSolarException $e) {
         Log::error($e->getMessage());
         return response()->json(['error' => 'Generation failed'], 500);
     }
     

5. Queueing Long Tasks:

   • Dispatch jobs for async processing:

     GenerateTextJob::dispatch('Your prompt here')->onQueue('upstage');
     

Integration Tips

• Prism Integration: Leverage Prism’s caching layer for repeated prompts:

  $cachedResponse = UpstageSolar::generate('Repeated prompt', ['cache' => true]);
  

• View Integration: Stream responses directly to Blade:

  <div id="output"></div>
  @push('scripts')
      <script>
          const eventSource = new EventSource('/stream-endpoint');
          eventSource.onmessage = (e) => {
              document.getElementById('output').innerHTML += e.data;
          };
      </script>
  @endpush
  

• Testing: Mock the service in tests:

  $this->mock(UpstageSolarService::class)->shouldReceive('generate')
      ->once()->andReturn(['response' => 'Mocked text']);
  

Gotchas and Tips

Pitfalls

1. API Key Management:

   • Never hardcode API keys in config files. Use Laravel’s .env and validate in AppServiceProvider:

     if (!config('services.upstage.api_key')) {
         throw new \RuntimeException('Upstage Solar API key not configured.');
     }
     

2. Rate Limits:

   • Monitor API usage via Upstage’s dashboard. Implement exponential backoff in retries:

     use Symfony\Component\HttpClient\RetryableHttpClient;
     
     $client = new RetryableHttpClient(
         new HttpClient(),
         [
             'max_retries' => 3,
             'delay' => 1000,
             'multiplier' => 2,
         ]
     );
     

3. Streaming Quirks:

   • Ensure streaming responses are closed properly to avoid memory leaks:

     $stream = UpstageSolar::stream('Prompt');
     foreach ($stream as $chunk) {
         // Process chunk
     }
     $stream->close(); // Critical for cleanup
     

4. Model Availability:

   • Check Upstage’s model documentation for deprecated models. Validate in config:

     $validModels = ['upstage-solar-text-v1', 'upstage-solar-text-v2'];
     if (!in_array(config('prism_upstage.default_model'), $validModels)) {
         throw new \InvalidArgumentException('Invalid model configured.');
     }
     

Debugging

1. Enable Logging: Configure in config/prism_upstage.php:

   'debug' => env('UPSTAGE_DEBUG', false),
   

   Logs will appear in storage/logs/laravel.log.

2. Payload Inspection: Use Laravel’s dd() to inspect raw requests/responses:

   $response = UpstageSolar::generate('Prompt', ['debug' => true]);
   dd($response->getPayload());
   

3. Common Errors:

   • 401 Unauthorized: Verify API key in .env.
   • 429 Too Many Requests: Implement retry logic (see above).
   • 500 Internal Server Error: Check Upstage’s status page or contact support.

Extension Points

1. Custom Models: Extend the service to support additional Upstage models:

   namespace App\Services;
   
   use Omiya0555\LaravelPrismUpstage\UpstageSolarService;
   
   class CustomUpstageService extends UpstageSolarService {
       public function generateCustomPrompt(string $prompt): array {
           return $this->callApi('custom-endpoint', ['prompt' => $prompt]);
       }
   }
   

2. Middleware: Add request validation middleware:

   namespace App\Http\Middleware;
   
   use Closure;
   use Omiya0555\LaravelPrismUpstage\Facades\UpstageSolar;
   
   class ValidateUpstagePrompt {
       public function handle($request, Closure $next) {
           $prompt = $request->input('prompt');
           if (strlen($prompt) < 10) {
               throw UpstageSolar::invalidPromptException('Prompt too short.');
           }
           return $next($request);
       }
   }
   

3. Event Listeners: Listen for generation events to log usage or trigger actions:

   namespace App\Listeners;
   
   use Omiya0555\LaravelPrismUpstage\Events\TextGenerated;
   
   class LogTextGeneration {
       public function handle(TextGenerated $event) {
           \Log::info('Generated text', ['prompt' => $event->prompt, 'response' => $event->response]);
       }
   }