Ia Exception Bundle Laravel Package

Getting Started

Minimal Steps

1. Install Dependencies:

   composer require symfony/ai-bundle darkwood/ia-exception-bundle
   

2. Configure AI Platform (e.g., OpenAI) in config/packages/ai.yaml:

   ai:
     platform:
       openai:
         api_key: '%env(OPENAI_API_KEY)%'
   

3. Enable the Bundle in config/bundles.php:

   Darkwood\IaExceptionBundle\DarkwoodIaExceptionBundle::class => ['all' => true],
   

4. Basic Configuration in config/packages/darkwood_ia_exception.yaml:

   darkwood_ia_exception:
     enabled: true
     only_status_codes: [500]
   

5. Test in Development:
   • Trigger a 500 error (e.g., throw new \RuntimeException('Test error')).
   • Verify the AI-generated explanation appears in the error page.

First Use Case

Debugging a Production 500 Error:

• A critical endpoint fails with a DatabaseConnectionException.
• Instead of a raw stack trace, the error page now shows:

  AI Analysis:
  - Probable Cause: MySQL server is unreachable (check DB_HOST in .env).
  - Suggested Fix: Restart the database service or verify credentials.
  

• Action: Use the AI suggestion to resolve the issue faster.

Implementation Patterns

Core Workflows

1. Synchronous Analysis (Default):

   • Trigger: kernel.exception event fires for status codes in only_status_codes.
   • Flow:
     • Exception data (class, message, trace) → AI agent → JSON response.
     • Response injected into Symfony’s default error template.
   • Use Case: Development/staging where latency is acceptable.

2. Asynchronous Analysis (Production):

   • Trigger: async: true in config.
   • Flow:
     • Return immediate error page with placeholder (e.g., "Analyzing...").
     • Frontend JS fetches /__ai_exception/{error_id} via AJAX.
     • AI response injected dynamically (fallback if timeout).
   • Use Case: Production where blocking kernel.exception is risky.

3. Caching Strategy:

   • Key: Hash of (exception_class, message, top_frames).
   • TTL: Configurable (default: 600s).
   • Use Case: Reduce API calls for repeated errors (e.g., rate-limited APIs).

Integration Tips

• Laravel Adaptation:

  • Replace Symfony’s ExceptionListener with Laravel’s App\Exceptions\Handler::render().
  • Use Laravel’s queue: system for async analysis:

    // In App\Exceptions\Handler
    public function render($request, Throwable $exception)
    {
        if ($exception instanceof \RuntimeException && $request->wantsJson()) {
            AiExceptionAnalysis::dispatch($exception)->delay(now()->addSeconds(5));
            return response()->json(['error' => 'Analysis queued'], 500);
        }
    }
    

  • Call a Symfony microservice for AI logic (if reusing this bundle).

• Symfony-Specific:

  • Twig Extensions: Override error.html.twig to include AI analysis:

    {% if exception.analysis %}
        <div class="ai-analysis">
            <h3>AI Analysis</h3>
            <p>{{ exception.analysis.explanation }}</p>
        </div>
    {% endif %}
    

  • Event Subscribers: Extend Darkwood\IaExceptionBundle\EventListener\ExceptionListener to add custom logic (e.g., filter sensitive data).

• Async Frontend:

  • Use Stimulus.js or Alpine.js to fetch /__ai_exception/{id}:

    document.addEventListener('DOMContentLoaded', () => {
        fetch(`/__ai_exception/${errorId}`)
            .then(response => response.json())
            .then(data => {
                document.getElementById('ai-analysis').innerHTML = `
                    <h4>Probable Causes</h4>
                    <ul>${data.probable_causes.map(c => `<li>${c}</li>`).join('')}</ul>
                `;
            });
    });
    

Configuration Patterns

Gotchas and Tips

Pitfalls

1. Sensitive Data Exposure:

   • Risk: Stack traces (include_trace: true) may leak file paths, method names, or environment variables.
   • Fix: Always set include_trace: false in production. Sanitize exception messages:

     // In a custom event subscriber
     $message = preg_replace('/\b(password|token|secret)\b/i', '[REDACTED]', $exception->getMessage());
     

2. AI Hallucinations:

   • Risk: LLM may suggest incorrect fixes (e.g., "Restart PHP-FPM" for a DB issue).
   • Fix:
     • Validate suggestions against logs/metrics.
     • Use confidence score to filter low-confidence responses:

       darkwood_ia_exception:
         min_confidence: 0.7  # Add this to config (requires bundle update)
       

3. Async Race Conditions:

   • Risk: Frontend JS may fetch stale or expired analysis.
   • Fix:
     • Use async_context_ttl (min 60s) to ensure context persists.
     • Add a timestamp check in the async endpoint:

       if (time() - $context['created_at'] > $config['async_context_ttl']) {
           throw new \RuntimeException('Context expired');
       }
       

4. Caching Quirks:

   • Risk: Cached responses may stale if exception details change slightly (e.g., line numbers).
   • Fix: Include more context in the cache key:

     # Customize the cache key logic in a service
     services:
         Darkwood\IaExceptionBundle\Cache\ExceptionCache:
             arguments:
                 $cacheKeyGenerator: '@app.ai_exception_cache_key_generator'
     

5. Symfony AI Bundle Dependencies:

   • Risk: Breaking changes in symfony/ai-bundle may break this bundle.
   • Fix: Pin versions in composer.json:

     "require": {
         "symfony/ai-bundle": "^0.8",
         "darkwood/ia-exception-bundle": "^1.3"
     }
     

Debugging Tips

1. Log AI Requests/Responses:

   • Enable Symfony’s HTTP client logging:

     framework:
         http_client:
             logging: true
     

   • Check var/log/dev.log for AI API calls.

2. Test Async Flow:

   • Simulate a slow AI response:

     darkwood_ia_exception:
         timeout_ms: 2000  # Force timeout
     

   • Verify the fallback message appears.

3. Inspect Cache:

   • Dump cached entries:

     $cache = $container->get('cache.app');
     $keys = $cache->getIterator()->getKeys();
     

4. Validate JSON Output:

   • Test the /__ai_exception/{id} endpoint directly:

     curl -H "Accept: application/json" http://localhost/__ai_exception/abc123
     

Extension Points

1. Custom AI Agents:

   • Extend Darkwood\IaExceptionBundle\Agent\AgentInterface to support custom LLMs:

     namespace App\Agent;
     
     use Darkwood\IaExceptionBundle\Agent\AgentInterface;
     
     class MistralAgent implements AgentInterface {
         public function analyze(Throwable $exception): array {
             // Call Mistral API
             return ['explanation' => 'Mistral-generated fix...'];
         }
     }
     

   • Register in services.yaml:

     services:
         App\Agent\MistralAgent: ~
     

2. Dynamic Status Codes:

   • Override only_status_codes per environment:

     when@prod:
         darkwood_ia_exception:
             only_status_codes: [500, 503]
     

3. Post-Analysis Hooks:

   • Subscribe to darkwood_ia_exception.analyzed event