Filament Ai Chat Widget Laravel Package

Getting Started

Minimal Steps to First Use Case

1. Installation:

   composer require ferarandrei1/filament-ai-chat-widget
   php artisan vendor:publish --tag="filament-ai-chat-widget-migrations"
   php artisan migrate
   

   Add OpenAI credentials to .env:

   OPENAI_API_KEY=your_key_here
   OPENAI_ORGANIZATION=your_org
   

2. Register Plugin: In your PanelProvider, add:

   ->plugins([
       FilamentAiChatPlugin::make(),
   ])
   ->resources([
       AiKnowledgeBaseResource::class,
   ])
   

3. Clear Caches:

   php artisan optimize:clear
   

4. First Use Case:

   • Log in to your Filament panel.
   • The chat widget will appear automatically on all pages.
   • Type a question (e.g., "How do I configure Filament’s user management?").
   • The AI will respond using the default OpenAI model (e.g., gpt-4o-mini).

Implementation Patterns

Core Workflows

1. Chat Widget Integration

• Default Behavior: The widget appears as a floating sidebar on all authenticated Filament pages. Customize its position/size via config/filament-ai-chat-widget.php:

  'widget' => [
      'position' => 'right', // 'left' or 'right'
      'width' => '350px',
      'height' => '600px',
  ],
  

• Triggering AI Actions: Extend functionality by hooking into Filament events. Example: Auto-trigger AI when a resource is created:

  use Feraandrei1\FilamentAiChatWidget\Facades\AiChat;
  
  // In a ServiceProvider or Resource class
  AiChat::ask('User created: ' . $user->name . '. Suggest next steps.');
  

2. Knowledge Base Management

• Curating Responses: Use the AiKnowledgeBaseResource to add context-specific entries (e.g., internal policies, FAQs). Example entry:

  // Via Tinker or a Seeder
  \Feraandrei1\FilamentAiChatWidget\Models\AiKnowledgeBase::create([
      'title' => 'Filament User Roles',
      'content' => 'Admins can manage all users. Editors can only edit their own content.',
      'is_active' => true,
  ]);
  

• Prioritizing Entries: AI uses active entries first. Disable irrelevant entries via the Filament resource UI.

3. Model Context Protocol (MCP)

• Defining AI Rules: Create MCP files in config/filament-ai-chat-widget/mcp/ to enforce guidelines. Example (guidelines.md):

  # Filament AI Guidelines
  - Never suggest disabling security features like 2FA.
  - Always reference the knowledge base for Filament-specific questions.
  

• Dynamic Context: Pass context to AI calls programmatically:

  AiChat::ask('Explain this code:', $codeSnippet, [
      'context' => ['model' => 'gpt-4', 'temperature' => 0.3],
  ]);
  

4. Conversation History

• Persisting Chats: Each user’s conversations are auto-saved. Limit history size in config:

  'chat_history_limit' => 50, // Max conversations per user
  

• Soft Deletes: Recover deleted conversations via the AiChat facade:

  $deletedChat = AiChat::restoreConversation($id);
  

5. Token Management

• Tracking Usage: Monitor token consumption via the AiChat facade:

  $usage = AiChat::getLastUsage();
  // Returns: ['prompt_tokens' => 100, 'completion_tokens' => 200, 'total' => 300]
  

• Budget Alerts: Integrate with Laravel’s events to trigger alerts when usage exceeds thresholds:

  // In EventServiceProvider
  AiChat::onTokenLimitExceeded(function ($tokens) {
      Log::warning("AI token limit exceeded: {$tokens}");
      // Send Slack/email alert
  });
  

Integration Tips

Filament-Specific

• Resource-Specific AI: Extend the widget to show resource-specific help. Example: Add a getAiHelp() method to a resource:

  public static function getAiHelp(): string {
      return "This resource manages " . static::getModelLabel() . ". Use the bulk actions to export data.";
  }
  

  Then pass this to the AI:

  AiChat::ask('How do I use this page?', null, [
      'context' => ['resource_help' => Post::getAiHelp()],
  ]);
  

• Permissions: Restrict access to the chat widget or knowledge base via Filament’s gate system:

  FilamentAiChatPlugin::make()->middleware([
      \Feraandrei1\FilamentAiChatWidget\Middleware\RequireAdmin::class,
  ]);
  

OpenAI Customization

• Model Selection: Override the default model in config:

  'default_model' => 'gpt-4',
  

• Parameters: Adjust AI behavior per conversation:

  AiChat::ask('Write a test case for this:', $code, [
      'parameters' => ['temperature' => 0.1, 'max_tokens' => 100],
  ]);
  

UI Customization

• Theming: Override Livewire styles by publishing assets:

  php artisan vendor:publish --tag="filament-ai-chat-widget-assets"
  

  Then modify resources/views/vendor/filament-ai-chat-widget/....
• Localization: Translate UI strings via Filament’s localization system. Example:

  'messages' => [
      'chat_placeholder' => 'Ask about Filament or your workflow...',
  ],
  

Advanced Use Cases

• Webhook Triggers: Use Laravel’s queue:work to process AI responses asynchronously:

  AiChat::ask('Generate a report', null, [
      'callback' => function ($response) {
          Report::generate($response);
      },
  ]);
  

• Multi-Tenancy: Isolate knowledge bases per tenant by extending the AiKnowledgeBase model:

  class TenantAiKnowledgeBase extends AiKnowledgeBase {
      public function scopeForTenant($query, $tenantId) {
          return $query->where('tenant_id', $tenantId);
      }
  }
  

Gotchas and Tips

Pitfalls

1. OpenAI API Limits:

   • Issue: Hitting rate limits or token caps during peak usage.
   • Fix: Implement exponential backoff in your AiChat calls:

     try {
         AiChat::ask('...');
     } catch (\GuzzleHttp\Exception\RequestException $e) {
         if (str_contains($e->getMessage(), 'rate limit')) {
             sleep(10); // Retry after 10 seconds
             AiChat::ask('...'); // Retry
         }
     }
     

   • Tip: Use OpenAI’s usage metrics to monitor costs.

2. Knowledge Base Bloat:

   • Issue: Too many inactive entries slow down AI responses.
   • Fix: Archive inactive entries via a scheduled job:

     // app/Console/Commands/ArchiveKnowledgeBase.php
     public function handle() {
         AiKnowledgeBase::where('is_active', false)
             ->where('updated_at', '<', now()->subDays(30))
             ->update(['is_archived' => true]);
     }
     

3. MCP Misconfiguration:

   • Issue: AI ignores MCP rules due to malformed files.
   • Fix: Validate MCP files on registration. Example middleware:

     public function handle($request, Closure $next) {
         if (!file_exists(config('filament-ai-chat-widget.mcp_path') . '/guidelines.md')) {
             throw new \Exception('MCP guidelines file missing!');
         }
         return $next($request);
     }
     

4. Conversation History Growth:

   • Issue: Database bloat from unlimited chat history.
   • Fix: Set a strict limit in config and prune old data:

     'chat_history_limit' => 20, // Hard cap
     

     Add a model observer to auto-delete:

     AiChat::observe(function ($model) {
         if ($model->conversations()->count() > config('filament-ai-chat-widget.chat_history_limit')) {
             $model->conversations()->oldest()->delete();
         }
     });
     

5. Filament Caching:

   • Issue: Widget not appearing after installation.