Ai Assistant Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require kwakuofosuagyeman/ai-assistant
   php artisan vendor:publish --tag=ai-config
   

   Configure .env with your provider API key (e.g., OPENAI_API_KEY=your_key).

2. First Use Case: Inject the AIService facade or bind it in the service container:

   use KwakuOfosuAgyeman\AIAssistant\Facades\AIService;
   
   // Generate text
   $response = AIService::generateText('openai', 'Write a blog post about Laravel AI integration');
   

3. Where to Look First:

   • config/ai.php: Default provider, provider-specific settings.
   • app/Providers/AIServiceProvider.php: Service container binding (if extended).
   • tests/ (if available): Example usage patterns.

Implementation Patterns

Core Workflows

1. Provider-Agnostic Calls: Use the AIService facade to abstract provider logic:

   // Switch providers without changing business logic
   $response = AIService::generateText(config('ai.default'), $prompt);
   

2. Dynamic Provider Selection: Pass provider names dynamically (e.g., from user input or config):

   $provider = request()->input('provider', config('ai.default'));
   $result = AIService::generateEmbeddings($provider, $text);
   

3. Laravel Integration:

   • Commands: Schedule AI tasks (e.g., content generation) via Artisan:

     use KwakuOfosuAgyeman\AIAssistant\Facades\AIService;
     
     AIService::generateText('openai', 'Draft a weekly newsletter');
     

   • Jobs: Dispatch AI tasks asynchronously:

     GenerateContentJob::dispatch('claude', $prompt)->onQueue('ai');
     

4. Service Container Binding: Extend or replace the default service binding:

   $this->app->bind('ai', function ($app) {
       return new CustomAIService($app['config']['ai']);
   });
   

5. Model Observers/Events: Trigger AI actions on model events (e.g., saved):

   class PostObserver {
       public function saved(Post $post) {
           AIService::generateEmbeddings('openai', $post->content);
       }
   }
   

Integration Tips

• Caching Responses: Cache AI-generated content to reduce API calls:

  $cacheKey = "ai_{$provider}_{$prompt}";
  return Cache::remember($cacheKey, now()->addHours(1), function () use ($provider, $prompt) {
      return AIService::generateText($provider, $prompt);
  });
  

• Rate Limiting: Use Laravel’s throttle middleware for API-heavy routes:

  Route::middleware(['throttle:10,1'])->group(function () {
      Route::post('/ai/generate', [AIController::class, 'generate']);
  });
  

• Logging: Log AI interactions for debugging/auditing:

  AIService::generateText('openai', $prompt)
      ->then(fn($response) => Log::info('AI Response', ['response' => $response]));
  

Gotchas and Tips

Pitfalls

1. API Key Exposure:

   • Never commit .env files. Use Laravel’s .env.example for templates.
   • Restrict API keys to specific IPs if possible (e.g., via provider dashboard).

2. Provider-Specific Quirks:

   • OpenAI: May throttle requests without a Organization header. Add to config/ai.php:

     'openai' => [
         'api_key' => env('OPENAI_API_KEY'),
         'organization' => env('OPENAI_ORG_ID'), // Optional but recommended
     ],
     

   • Gemini/Claude: Check for rate limits or token restrictions in their docs.

3. Error Handling:

   • The package includes basic try...catch, but extend for custom logic:

     try {
         $response = AIService::generateText('openai', $prompt);
     } catch (\KwakuOfosuAgyeman\AIAssistant\Exceptions\AIException $e) {
         Log::error("AI Error: " . $e->getMessage());
         return back()->with('error', 'AI service unavailable');
     }
     

4. Cost Management:

   • Monitor token usage (e.g., via strlen($prompt)) to avoid unexpected charges.
   • Implement a max_tokens config limit per request:

     'openai' => [
         'max_tokens' => 1000, // Default or per-route
     ],
     

Debugging

• Enable API Debugging: Add to config/ai.php:

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

  Logs will include request/response payloads.

• Test Locally: Use mock providers (e.g., ai-mock) during development:

  $this->app->bind('ai', function () {
      return new \KwakuOfosuAgyeman\AIAssistant\Providers\MockAIProvider();
  });
  

Extension Points

1. Custom Providers: Extend the AIProvider interface to add support for new services:

   class CustomAIProvider implements AIProvider {
       public function generateText(string $prompt): string {
           // Implement logic for your provider
       }
   }
   

   Register in config/ai.php:

   'providers' => [
       'services' => [
           'custom' => [
               'class' => \App\Providers\CustomAIProvider::class,
           ],
       ],
   ],
   

2. Middleware: Add pre/post-processing middleware:

   AIService::extend(function ($service) {
       $service->preGenerate(function ($prompt) {
           return "Refined: " . $prompt; // Example: Add context
       });
   });
   

3. Event Listeners: Listen for AI events (e.g., AIRequestSent, AIResponseReceived):

   event(new AIRequestSent($provider, $prompt));
   

Config Quirks

• Default Provider: Override dynamically in routes/controllers:

  config(['ai.default' => 'gemini']);
  

• Environment Variables: Use env() helpers for dynamic keys:

  'openai' => [
      'api_key' => env('OPENAI_API_KEY_' . config('app.env')),
  ],
  

• Fallback Providers: Define a fallback chain in config/ai.php:

  'fallback_providers' => ['openai', 'gemini', 'claude'],