Laravel Ai Chatbox Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require syafiq-unijaya/laravel-ai-chatbox
   php artisan vendor:publish --provider="SyafiqUnijaya\LaravelAiChatbox\LaravelAiChatboxServiceProvider" --tag="config"
   php artisan migrate
   

2. Configure API Update .env with your AI provider credentials (e.g., OpenAI, Ollama):

   AI_CHATBOX_API_KEY=your_api_key_here
   AI_CHATBOX_MODEL=gpt-3.5-turbo
   AI_CHATBOX_PROVIDER=openai  # or 'ollama', 'groq', etc.
   

3. First Use Case Add the chatbox to a Blade template:

   @aiChatbox
   

   This renders the Vue 3 frontend with default styling.

Key Initial Steps

• Test API Connection: Run php artisan ai:test-connection to verify your AI provider is working.
• Admin Dashboard: Access /ai-chatbox/admin to manage conversations, models, and RAG configurations.
• Basic Usage: Use the PHP facade in controllers:

  use SyafiqUnijaya\LaravelAiChatbox\Facades\AiChatbox;
  
  $response = AiChatbox::sendMessage("Hello, how are you?", [
      'model' => 'gpt-4',
      'temperature' => 0.7,
  ]);
  

Implementation Patterns

Core Workflows

1. Integrating with Existing Views

   • Use @aiChatbox directive in Blade templates for a quick drop-in.
   • Customize via config (e.g., ai_chatbox.php):

     'widget' => [
         'position' => 'bottom-right', // 'top-left', 'bottom-right', etc.
         'width' => '350px',
         'theme' => 'light', // 'dark', 'custom'
     ],
     

2. Streaming Responses

   • Enable streaming in the frontend by setting streaming: true in the config.
   • Handle streaming in PHP:

     AiChatbox::streamMessage("What's the weather today?", function ($chunk) {
         // Process chunks in real-time (e.g., log, display, or analyze)
     });
     

3. RAG (Retrieval-Augmented Generation)

   • Setup: Configure RAG sources in config/ai_chatbox.php:

     'rag' => [
         'sources' => [
             'documents' => [
                 'type' => 'database', // or 'filesystem', 's3', etc.
                 'model' => SyafiqUnijaya\LaravelAiChatbox\RAG\Sources\DatabaseSource::class,
                 'config' => [
                     'table' => 'knowledge_base',
                     'column' => 'content',
                 ],
             ],
         ],
     ],
     

   • Usage: Automatically enabled for conversations. Add context to messages:

     AiChatbox::sendMessage("Explain our product features.", [
         'rag' => ['sources' => ['documents']],
     ]);
     

4. Conversation Memory

   • Session-Based: Messages persist per user session by default.
   • Database Storage: Enable in config:

     'memory' => [
         'driver' => 'database',
         'table' => 'ai_chatbox_conversations',
     ],
     

   • Custom Logic: Extend the Conversation model or use middleware to manage memory.

Integration Tips

• API Rate Limiting: Implement middleware to handle rate limits (e.g., SyafiqUnijaya\LaravelAiChatbox\Middleware\RateLimit).
• Vue 3 Customization:
  • Override the frontend by publishing assets:

    php artisan vendor:publish --tag="ai-chatbox-assets"
    

  • Extend the Vue component in resources/js/ai-chatbox.js.
• Multi-Tenant Support: Use the tenant() method on the facade to scope conversations:

  AiChatbox::tenant('company_123')->sendMessage("Hello...");
  

• Webhooks: Listen for conversation events via Laravel events:

  AiChatbox::onMessageSent(function ($message) {
      // Log or process the message
  });
  

Gotchas and Tips

Common Pitfalls

1. API Key Security

   • Never hardcode API keys in Blade templates or client-side JavaScript.
   • Use environment variables and validate them in config:

     if (empty(config('ai_chatbox.api_key'))) {
         throw new \RuntimeException("AI_CHATBOX_API_KEY is not set.");
     }
     

2. Token Limits

   • Long conversations may hit token limits. Implement a cleanup job:

     AiChatbox::pruneOldConversations(30); // Keep last 30 messages
     

   • Monitor usage with AiChatbox::getTokenUsage().

3. RAG Performance

   • Large document sets slow down retrieval. Optimize with:
     • Database indexing (e.g., full-text search).
     • Chunking strategies (e.g., split documents into smaller segments).
   • Test retrieval speed with:

     php artisan ai:rag-test
     

4. Streaming Issues

   • Ensure your AI provider supports streaming (e.g., OpenAI’s stream: true).
   • Handle disconnections gracefully in the frontend:

     // In ai-chatbox.js
     useEffect(() => {
         const eventSource = new EventSource(`/ai-chatbox/stream/${conversationId}`);
         eventSource.onerror = () => {
             // Fallback to polling or notify user
         };
     }, [conversationId]);
     

Debugging Tips

1. Log AI Responses Enable logging in config:

   'logging' => [
       'enabled' => true,
       'channel' => 'single',
   ],
   

   View logs in storage/logs/ai_chatbox.log.

2. Validate API Responses Use the debug method to inspect raw responses:

   $response = AiChatbox::sendMessage("Test", ['debug' => true]);
   dd($response->raw());
   

3. Frontend Debugging

   • Toggle Vue devtools to inspect the chatbox component state.
   • Check browser console for errors (e.g., failed API calls).

Extension Points

1. Custom Providers Extend the Provider class to support non-OpenAI APIs:

   namespace App\Providers;
   
   use SyafiqUnijaya\LaravelAiChatbox\Contracts\Provider;
   
   class CustomProvider implements Provider {
       public function send($message, array $options) {
           // Implement custom logic
       }
   }
   

   Register in config:

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

2. Middleware Add custom logic before/after API calls:

   AiChatbox::before(function ($request) {
       // Modify request (e.g., add headers)
   });
   
   AiChatbox::after(function ($response) {
       // Process response (e.g., sanitize output)
   });
   

3. Event Listeners Extend functionality via events:

   // Listen for message sending
   AiChatbox::onMessageSending(function ($message) {
       // Modify message or cancel
       return $message;
   });
   
   // Listen for responses
   AiChatbox::onMessageReceived(function ($message, $response) {
       // Log or process response
   });
   

4. Custom RAG Sources Add new data sources (e.g., S3, Elasticsearch):

   'rag' => [
       'sources' => [
           's3_documents' => [
               'type' => 's3',
               'model' => App\RAG\Sources\S3Source::class,
               'config' => [
                   'bucket' => 'my-bucket',
                   'prefix' => 'docs/',
               ],
           ],
       ],
   ],
   

Configuration Quirks

1. Model Fallbacks If a model fails, specify fallbacks:

   'models' => [
       'gpt-3.5-turbo' => [
           'provider' => 'openai',
           'fallback' => 'gpt-3.5-turbo-0301',
       ],
   ],
   

2. CORS for Streaming Ensure your server allows streaming endpoints:

   // In routes/web.php
   Route::middleware(['cors:sanctum'])->group(function () {
       // AI streaming routes
   });
   

3. Vue 3 Compatibility

   • If using Laravel Mix/Vite, ensure Vue 3 is properly set up.
   • For custom builds, alias the chatbox component: