Laravel Ai Chatbox Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require developer-unijaya/laravel-ai-chatbox
   php artisan vendor:publish --provider="DeveloperUnijaya\LaravelAiChatbox\ServiceProvider" --tag="config"
   php artisan migrate
   

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

   AI_CHATBOX_PROVIDER=openai
   OPENAI_API_KEY=your_key_here
   

3. Basic Usage Add the chatbox widget to a Blade view:

   @chatbox
   

   Or use the Vue component directly in a frontend framework:

   <template>
     <ai-chatbox />
   </template>
   

4. First Interaction Trigger a chat via JavaScript:

   window.aiChatbox.sendMessage("Hello, how can you help me?");
   

Implementation Patterns

Core Workflows

1. RAG Integration

   • Embed Documents: Use the ChatboxDocument model to store and embed documents for retrieval-augmented generation (RAG).

     $document = new ChatboxDocument();
     $document->content = "Your document content here";
     $document->save();
     

   • Query with RAG: Enable RAG in the config (rag_enabled=true) and query with context:

     $response = AiChatbox::query("What is this document about?", ['rag' => true]);
     

2. Streaming Responses

   • Enable streaming in the config (streaming_enabled=true) and handle chunks in the frontend:

     window.aiChatbox.sendMessage("Stream this response", {
       onStream: (chunk) => console.log(chunk)
     });
     

3. Customizing Prompts

   • Override the default system prompt via the config:

     'system_prompt' => "You are a helpful assistant for our Laravel application.",
     

   • Or dynamically pass prompts per request:

     $response = AiChatbox::query("Help me", [
       'prompt' => "Act as a Laravel expert."
     ]);
     

4. Multi-Provider Support

   • Switch providers dynamically (e.g., fallback to Ollama if OpenAI fails):

     AiChatbox::setProvider('ollama');
     $response = AiChatbox::query("Your question");
     

5. Vue 3 Frontend Integration

   • Customize UI: Extend the Vue component by creating a child component:

     <template>
       <ai-chatbox @message-sent="customLogic">
         <template #message="{ message }">
           <div class="custom-message">{{ message.text }}</div>
         </template>
       </ai-chatbox>
     </template>
     

   • Event Handling: Listen to chatbox events:

     window.aiChatbox.$on('response-received', (response) => {
       // Handle response
     });
     

6. Middleware for Authenticated Chats

   • Protect chat routes or data with Laravel middleware:

     Route::middleware(['auth'])->group(function () {
         Route::post('/chat', [AiChatboxController::class, 'handle']);
     });
     

Gotchas and Tips

Common Pitfalls

1. API Rate Limits

   • Issue: OpenAI/Groq APIs throttle requests. Streaming or rapid-fire messages may fail.
   • Fix: Implement exponential backoff in your frontend:

     async function sendMessage(message) {
       try {
         await window.aiChatbox.sendMessage(message, {
           retryDelay: 1000 // ms
         });
       } catch (error) {
         if (error.response?.status === 429) {
           await new Promise(resolve => setTimeout(resolve, 1000));
           sendMessage(message); // Retry
         }
       }
     }
     

2. RAG Performance

   • Issue: Large document sets slow down retrieval.
   • Fix:
     • Use chunk_size and overlap in config to optimize embeddings.
     • Cache embeddings with Laravel’s cache:

       'rag' => [
           'cache_embeddings' => true,
       ],
       

3. Vue Component Conflicts

   • Issue: Global ai-chatbox variable conflicts with other libraries.
   • Fix: Use a unique namespace:

     window.laravelAiChatbox = new AiChatbox();
     

4. Ollama Local Setup

   • Issue: Ollama may not be running or misconfigured.
   • Fix:
     • Ensure Ollama is running locally (ollama serve).
     • Set the correct endpoint in config:

       'ollama' => [
           'endpoint' => 'http://localhost:11434',
       ],
       

5. Token Limits

   • Issue: Long conversations exceed token limits.
   • Fix:
     • Truncate old messages in the frontend:

       window.aiChatbox.setMaxMessages(5); // Keep only last 5 messages
       

     • Use temperature and max_tokens in config to control response length.

6. Frontend State Management

   • Issue: Chat state resets on page refresh.
   • Fix: Persist messages to Laravel storage:

     // Store messages
     $user->messages()->create(['content' => $message]);
     

     // Load messages on init
     window.aiChatbox.loadMessages();
     

Debugging Tips

1. Log API Responses Enable debug mode in config:

   'debug' => true,
   

   Check Laravel logs for raw API responses.

2. Validate Prompts Use AiChatbox::validatePrompt() to check for issues before sending:

   if (!AiChatbox::validatePrompt("Your prompt here")) {
       // Handle invalid prompt
   }
   

3. Test with Mock Providers Use the mock provider in config for local testing:

   'provider' => 'mock',
   

   Mock responses are defined in config/ai-chatbox.php under mock_responses.

Extension Points

1. Custom Providers Extend the AiProvider interface to support new APIs:

   class CustomProvider implements AiProvider {
       public function generate($prompt, array $options) {
           // Implement custom logic
       }
   }
   

   Register the provider in the config:

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

2. Webhook Integration Trigger actions via webhooks (e.g., save responses to a database):

   AiChatbox::onResponse(function ($response) {
       \App\Models\ChatLog::create([
           'user_id' => auth()->id(),
           'response' => $response['content'],
       ]);
   });
   

3. Dynamic UI Themes Pass theme options to the Vue component:

   <ai-chatbox :theme="{ primaryColor: '#3b82f6' }" />
   

   Extend the default theme in resources/js/ai-chatbox/theme.js.

4. Moderation Middleware Add moderation checks before sending prompts:

   AiChatbox::beforeSend(function ($prompt) {
       if (str_contains(strtolower($prompt), 'inappropriate')) {
           throw new \Exception("Prompt rejected.");
       }
   });