Ai Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require laravel/ai
   

   Publish the config file (if needed):

   php artisan vendor:publish --provider="Laravel\AI\AIServiceProvider"
   

2. Configure Provider: Add your API key to .env (e.g., OPENAI_API_KEY=your_key_here) and define the provider in config/ai.php:

   'default' => env('AI_PROVIDER', 'openai'),
   'providers' => [
       'openai' => [
           'key' => env('OPENAI_API_KEY'),
           'options' => [], // Support for provider-specific options
           'strict' => env('AI_STRICT_MODE', false), // New: Opt-in strict mode
       ],
       // Add other providers (e.g., 'anthropic', 'gemini', 'openrouter')
   ],
   

3. First Use Case: Generate a simple completion in a controller or service:

   use Laravel\AI\Facades\AI;
   
   $response = AI::make('openai')->get('gpt-3.5-turbo')->complete('Explain Laravel AI SDK in 3 bullet points.');
   return $response->choices[0]->text;
   

4. New: Strict Mode Enable strict mode for OpenAI providers via config or attribute:

   // Config
   'providers' => [
       'openai' => [
           'strict' => true,
       ],
   ],
   // Or via attribute
   #[Strict]
   public function generateStrictResponse() {
       $response = AI::make('openai')->get('gpt-3.5-turbo')->complete('Strict prompt');
   }
   

5. New: Conversation List Retrieval Fetch conversations directly from the store:

   $conversations = AI::conversations()->all();
   

Where to Look First

• Documentation: Laravel AI SDK Docs (updated for v0.7.0).
• Config File: config/ai.php for strict mode and provider options.
• Facades: Laravel\AI\Facades\AI for quick access to AI services.
• Error Handling: New exceptions like InsufficientCreditsException and improved validation.
• Strict Mode: Check #[Strict] attribute usage and strict config option.

Implementation Patterns

Core Workflows

1. Basic Prompting (Updated):

   $result = AI::make('openai')->get('gpt-4')->complete('Summarize this: ' . $longText);
   

2. Strict Mode Responses (New):

   // Via config
   AI::make('openai')->get('gpt-3.5-turbo')->strict()->complete('Strict prompt');
   
   // Via attribute
   #[Strict]
   public function strictResponse() {
       $response = AI::make('openai')->get('gpt-3.5-turbo')->complete('Strict prompt');
   }
   

3. Tools and Agents (Updated):

   • Bedrock Converse with Provider Options:

     $agent = new Agent('bedrock', 'anthropic.claude-v2', [
         'providerOptions' => ['temperature' => 0.5],
     ]);
     $response = $agent->call('Query', 'Analyze this document');
     

4. Embeddings with Closure Options (New):

   $embedding = AI::make('openai')->get()->embed('Laravel AI SDK', [
       'options' => fn() => ['cached' => true],
   ]);
   

5. Audio Support (Updated):

   • Transcription with Provider Options:

     $transcription = AI::make('openrouter')->get('whisper')->transcribe($audioFile, [
         'providerOptions' => ['language' => 'en'],
     ]);
     

6. Conversations (Updated):

   • List Conversations:

     $conversations = AI::conversations()->all();
     $conversation = AI::conversations()->find(1);
     

   • Rehydrate Attachments:

     $history = $conversation->history()->withAttachments()->get();
     

7. Image Generation (Updated):

   • OpenRouter Image+Text Support:

     $image = AI::make('openrouter')->get('dall-e-3')->generate(
         'A futuristic Laravel logo with the text "AI Powered"',
         ['size' => '1024x1024']
     );
     

8. Document Validation (New):

   • Reranking with Empty List Handling:

     try {
         $reranked = AI::make('cohere')->rerank($query, []); // Throws exception
     } catch (\Laravel\AI\Exceptions\InvalidInputException $e) {
         // Handle empty document list
     }
     

Integration Tips

• Service Layer: Encapsulate AI logic with strict mode and error handling:

  class AIContentGenerator {
      public function __construct(private AI $ai) {}
  
      #[Strict]
      public function generateSummary(string $content): string {
          return $this->ai->make('openai')->get('gpt-3.5-turbo')->complete(
              "Summarize this in 3 bullet points: $content"
          )->choices[0]->text;
      }
  }
  

• Error Handling: Leverage new exceptions:

  try {
      $response = AI::make('openrouter')->get()->complete($prompt);
  } catch (\Laravel\AI\Exceptions\InsufficientCreditsException $e) {
      // Handle credit errors
  } catch (\Laravel\AI\Exceptions\InvalidInputException $e) {
      // Handle blank/empty inputs
  }
  

• Testing: Use updated fake methods:

  AI::fake(['openai']);
  AI::shouldReceive('complete')
      ->once()
      ->andThrow(new \Laravel\AI\Exceptions\InsufficientCreditsException());
  

• Database Connection: Respect configured connection in models:

  // Use a specific connection
  AI::conversations()->setConnection('mysql_secondary')->all();
  

• Documentation: Check updated PHPDoc for @throws in methods like:

  AI::make('azure-openai')->get()->generateImage(); // Throws RuntimeException
  

Gotchas and Tips

Pitfalls

1. Strict Mode (New):

   • Breaking Change: Strict mode is now opt-in and can be enforced via config or attribute.
   • Impact: Agents without #[Strict] will send strict: false to providers.
   • Fix: Update agents to use #[Strict] or configure strict: true in config/ai.php.

2. Input Validation (Updated):

   • Blank Input Rejection: Methods now reject blank/empty inputs (e.g., embeddings, reranking, image generation).
   • Example:

     try {
         AI::make('openai')->get()->embed(''); // Throws InvalidInputException
     } catch (\Laravel\AI\Exceptions\InvalidInputException $e) {}
     

3. Provider-Specific Quirks (Updated):

   • Anthropic:
     • Handle 529 overloaded responses and insufficient credits.
     • Use providerOptions for reasoning_content:

       $agent = new Agent('anthropic', 'claude-3', [
           'providerOptions' => ['reasoning_content' => 'Previous context...'],
       ]);
       

   • OpenRouter/DeepSeek:
     • Throw InsufficientCreditsException for credit errors.
   • Bedrock:
     • Pass providerOptions through to Converse:

       $agent->call('Query', 'Analyze', ['providerOptions' => ['temperature' => 0.3]]);
       

4. Conversations:

   • Attachment Rehydration: Ensure withAttachments() is used when loading history.
   • Database Connection: Models now respect configured connection (e.g., mysql_secondary).

5. Image Generation:

   • OpenRouter: Removed image+text restriction for supported models.
   • Blank Size/Quality: Reverted rejection of blank size/quality (now optional).

6. Documentation:

   • Updated @throws annotations for methods like:
     • OpenAiGateway::generateTranscription()
     • AzureOpenAiGateway::generateImage()
     • Image::of() and Embeddings::for()

Debugging Tips

• Strict Mode Debugging:

  // Check if strict mode is active
  if (AI::make('openai')->get()->isStrict()) {
      logger()->debug('Strict mode enabled');
  }