Filament Copilot Laravel Package

Getting Started

Minimal Steps to First Use

1. Installation

   composer require eslam-reda-div/filament-copilot
   php artisan filament-copilot:install
   

   • Follow prompts to configure AI provider (e.g., OpenAI, Anthropic) and model.

2. First Integration

   • Access the Copilot via the default sidebar widget (auto-registered in Filament panels).
   • Type a query like: "Generate a CRUD form for the User resource with soft deletes enabled."
   • Observe real-time streaming responses and tool execution (e.g., creating a migration).

3. Key Files to Review

   • config/filament-copilot.php: Core settings (provider, rate limits, token budget).
   • app/Providers/FilamentCopilotServiceProvider.php: Customization entry point.
   • resources/views/vendor/filament-copilot/...: Override UI templates if needed.

Implementation Patterns

Workflows

1. Resource-Specific Queries

   • Use context-aware prompts like: "List all Post records with published_at in the last 30 days, sorted by views descending."
   • Leverage agent memory to retain context across conversations (e.g., "Show me the draft I started earlier").

2. Tool Execution

   • Automate repetitive tasks via tools:

     // Register a custom tool (e.g., in ServiceProvider)
     FilamentCopilot::registerTool(
         new FilamentCopilotTool(
             'generate:resource',
             'Generates a Filament resource for a given model.',
             fn (string $model) => $this->generateResource($model)
         )
     );
     

   • Tools appear in the UI as clickable actions (e.g., "Generate Resource").

3. Panel-Level Integration

   • Embed Copilot in custom pages:

     use EslamRedaDiv\FilamentCopilot\Widgets\CopilotWidget;
     
     public function getWidgets(): array
     {
         return [
             CopilotWidget::make(),
             // ... other widgets
         ];
     }
     

   • Restrict access by panel/role:

     FilamentCopilot::configureUsing(function (FilamentCopilot $copilot) {
         $copilot->visibleInPanels(['admin']);
     });
     

4. Conversation Management

   • Audit logs: Track all queries/tools via filament-copilot/audit-logs (default route).
   • Rate limiting: Configure per-user/monthly limits in config/filament-copilot.php:

     'rate_limits' => [
         'max_requests' => 50,
         'period' => 'month',
     ],
     

Integration Tips

• Laravel AI SDK: Ensure your AI provider (e.g., OpenAI) is configured in config/services.php.
• Token Budget: Monitor usage with:

  $remainingTokens = FilamentCopilot::getRemainingTokenBudget();
  

  • Add a widget to display this in your panel.
• Custom Models: Extend the FilamentCopilot class to add domain-specific logic:

  namespace App\Services;
  
  use EslamRedaDiv\FilamentCopilot\FilamentCopilot;
  
  class CustomCopilot extends FilamentCopilot
  {
      public function generateMarketingCopy(string $productName): string
      {
          // Custom logic
      }
  }
  

  Register it in ServiceProvider:

  FilamentCopilot::swap(new CustomCopilot());
  

Gotchas and Tips

Pitfalls

1. Token Budget Overruns

   • Issue: Copilot may fail silently if token limits are exceeded.
   • Fix: Enable debug mode in config and log warnings:

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

   • Workaround: Implement a fallback (e.g., cached responses) for low-budget users.

2. Tool Execution Security

   • Issue: Malicious tool inputs can execute arbitrary code.
   • Fix: Validate all tool inputs:

     FilamentCopilot::registerTool(
         new FilamentCopilotTool(
             'safe:query',
             'Runs a safe database query.',
             fn (string $query) => $this->validateAndRunQuery($query)
         )
     );
     

   • Tip: Use Laravel’s Str::of($input)->trim()->lower() for string sanitization.

3. Rate Limiting Conflicts

   • Issue: Concurrent requests may hit rate limits unexpectedly.
   • Fix: Configure async processing for non-critical tools:

     FilamentCopilot::registerTool(
         new FilamentCopilotTool(
             'async:task',
             'Processes tasks in the background.',
             fn ($payload) => Task::dispatch($payload)
         )
     );
     

4. Context Drift

   • Issue: Long conversations lose context.
   • Fix: Use agentMemory to persist key data:

     FilamentCopilot::configureUsing(function (FilamentCopilot $copilot) {
         $copilot->agentMemory()->useDatabase(); // or 'redis'
     });
     

Debugging

• Logs: Enable filament-copilot.log in config/logging.php.
• SSE Errors: Check browser console for streaming issues (e.g., CORS, connection drops).
• Tool Failures: Inspect filament-copilot/audit-logs for tool execution errors.

Extension Points

1. Custom UI Components

   • Override Blade templates in resources/views/vendor/filament-copilot/.
   • Example: Modify the chat input to include a "quick actions" dropdown:

     <x-filament-copilot::input>
         <x-slot name="after">
             <button wire:click="showQuickActions">Quick Actions</button>
         </x-slot>
     </x-filament-copilot::input>
     

2. Dynamic Tool Registration

   • Register tools conditionally (e.g., based on user role):

     FilamentCopilot::registerToolIf(
         fn () => auth()->user()->isAdmin(),
         new FilamentCopilotTool('admin:tool', '...')
     );
     

3. Provider Fallbacks

   • Handle API failures gracefully:

     FilamentCopilot::configureUsing(function (FilamentCopilot $copilot) {
         $copilot->onProviderFailure(function ($exception) {
             // Fallback to cached response or notify user
         });
     });
     

4. Local Testing

   • Use mockai for offline testing:

     FilamentCopilot::shouldMockResponses(true);
     FilamentCopilot::mockResponse('Generate a resource', 'Here is your resource code: ...');