Ai Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require laravel/ai
   

   Publish the config file:

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

2. Configure Providers: Edit .env with your preferred provider (e.g., OpenAI, Anthropic, Gemini):

   AI_PROVIDER=openai
   OPENAI_API_KEY=your_api_key_here
   

3. First Use Case: Generate text with a simple prompt:

   use Laravel\AI\Facades\AI;
   
   $response = AI::generateText('Explain Laravel AI SDK in 3 bullet points');
   echo $response->content;
   

4. Key Starting Points:

   • Laravel AI Docs (official reference)
   • config/ai.php (provider configurations)
   • app/Providers/AIServiceProvider.php (custom provider bindings)

Implementation Patterns

Core Workflows

1. Text Generation

Basic Usage:

$response = AI::generateText('Summarize this: ' . $longText);

With Model Selection:

$response = AI::generateText('Summarize', [
    'model' => 'gpt-4',
    'temperature' => 0.2,
]);

2. Agentic Workflows

Define Tools:

use Laravel\AI\Tools\Tool;

$tools = [
    Tool::fromClass(CalculateTaxTool::class),
    Tool::fromClass(FetchUserDataTool::class),
];

Run Agent:

$agent = AI::agent()
    ->tools($tools)
    ->create();

$response = $agent->call('Calculate tax for user ID 123');

3. Structured Output

Define Schema:

use Laravel\AI\Structured\StructuredOutput;

$schema = StructuredOutput::make()
    ->title('UserProfile')
    ->description('Extract user profile data')
    ->property('name', 'string')
    ->property('email', 'string')
    ->property('age', 'integer');

Generate Structured Data:

$response = AI::generateStructured($schema, 'Extract profile from: ' . $text);
$data = $response->content; // Parsed as array/object

4. Embeddings & Vector Search

Create Embeddings:

$embeddings = AI::embeddings()->for('Your text here')->create();

Similarity Search:

$results = AI::similaritySearch()
    ->usingModel(User::class, 'description')
    ->query('Find users interested in AI')
    ->limit(5)
    ->get();

5. Audio & Image Processing

Transcribe Audio:

$transcription = AI::transcribe('path/to/audio.mp3');

Generate Image:

$image = AI::generateImage('A futuristic cityscape');
$image->toHtml(); // Embed in Blade

Integration Tips

Service Container Binding

Bind custom providers in AIServiceProvider:

public function register()
{
    $this->app->bind('ai.provider.custom', function ($app) {
        return new CustomAIProvider();
    });
}

Middleware for AI Calls

Add middleware to log/validate AI requests:

AI::extend('openai', function ($app) {
    return new OpenAiGateway(
        $app['config']['services.openai'],
        new LogAIRequestsMiddleware()
    );
});

Queued AI Jobs

Offload heavy AI tasks:

AI::queueEmbeddings('path/to/file.txt')->later();

Blade Directives

Embed AI responses in views:

@php
    $summary = AI::generateText('Summarize: ' . $article->content);
@endphp
<div>{{ $summary->content }}</div>

Testing AI Responses

Use fake providers in tests:

AI::fake([
    'openai' => [
        'generateText' => 'Fake response',
    ],
]);

Gotchas and Tips

Pitfalls & Debugging

1. Provider-Specific Quirks

• OpenAI: Use providerOptions for non-standard endpoints (e.g., Azure OpenAI):

  AI::generateText('Prompt', ['providerOptions' => ['api_version' => '2023-05-15']]);
  

• Anthropic: Handle pause_turn tool continuations in agents:

  $agent->handleToolContinuation(function ($tool, $response) {
      if ($tool->name === 'pause_turn') {
          return 'Resumed...';
      }
  });
  

• Gemini: Validate image generation payloads (order of parts matters):

  AI::generateImage('Prompt', [
      'parts' => [
          ['text' => 'A red apple'],
          ['image' => Storage::path('apple.jpg')],
      ],
  ]);
  

2. Rate Limits & Costs

• Monitor Usage: Enable AI_DEBUG in .env to log token counts:

  AI_DEBUG=true
  

• Fallback Providers: Configure failover in config/ai.php:

  'providers' => [
      'openai' => [
          'failover' => ['anthropic', 'gemini'],
      ],
  ],
  

• Cache Responses: Use AI::cache() for static prompts:

  $response = AI::cache()->generateText('Static prompt', now()->addHours(1));
  

3. Structured Output Pitfalls

• Schema Validation: Ensure JSON Schema compatibility (avoid additionalProperties):

  $schema->property('metadata', 'object', ['additionalProperties' => false]);
  

• Strict Mode: Enable for strict schema enforcement:

  $response = AI::generateStructured($schema, 'Prompt', ['strict' => true]);
  

4. Agent Debugging

• Tool Errors: Handle tool execution failures:

  $agent->handleToolError(function ($tool, $error) {
      Log::error("Tool {$tool->name} failed: {$error->getMessage()}");
      return 'Fallback response';
  });
  

• Streaming: Capture partial responses:

  $agent->stream(function ($chunk) {
      echo $chunk->content;
  });
  

5. Embeddings & Vector Search

• Empty Inputs: Validate inputs to avoid RuntimeException:

  if (empty($text)) {
      throw new \InvalidArgumentException('Text cannot be empty');
  }
  $embeddings = AI::embeddings()->for($text)->create();
  

• Database Indexes: Optimize similarity search with full-text indexes:

  Schema::table('users', function ($table) {
      $table->fullText('description');
  });
  

Extension Points

1. Custom Providers

Extend the SDK with new providers:

namespace App\Providers;

use Laravel\AI\Contracts\Gateway;

class CustomGateway implements Gateway
{
    public function generateText(string $prompt, array $options = []): \Laravel\AI\Contracts\TextResponse
    {
        // Implement custom logic
    }
}

Register in AIServiceProvider:

AI::extend('custom', function () {
    return new CustomGateway();
});

2. Tool Customization

Add dynamic tools to agents:

$agent->tools(function () {
    return [
        Tool::fromClass(DynamicTool::class, ['param' => request('param')]),
    ];
});

3. Middleware for AI

Intercept AI calls globally:

AI::macro('before', function ($callback) {
    $originalGenerateText = AI::generateText(...);
    return function (...$args) use ($originalGenerateText, $callback) {
        $callback(...$args);
        return $originalGenerateText(...$args);
    };
});

4. Testing Helpers

Mock AI responses in tests:

AI::fake([
    'openai' => [
        'generateText' => fn($prompt) => 'Mock: ' . $prompt,
        'embeddings' => fn($text) => [0.1, 0.2, 0.3],
    ],
]);