Laravel Ai Guard Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require subhashladumor1/laravel-ai-guard
   php artisan vendor:publish --provider="SubhashLadumor\AiGuard\AiGuardServiceProvider" --tag="config"
   

   Publish the config file to config/ai-guard.php and update your .env with:

   AI_GUARD_ENABLED=true
   AI_GUARD_DEFAULT_BUDGET=100  # in USD
   AI_GUARD_CURRENCY=USD
   

2. First Use Case: Wrap an AI Call Use the AiGuard facade to wrap your first AI SDK call:

   use SubhashLadumor\AiGuard\Facades\AiGuard;
   
   $response = AiGuard::execute(function () {
       return \Laravel\AI\Facades\AI::complete('gpt-3.5-turbo', 'Explain Laravel AI Guard');
   });
   

3. Verify Setup Check the ai_guard_logs table for recorded usage:

   php artisan tinker
   >>> \SubhashLadumor\AiGuard\Facades\AiGuard::getUsageHistory();
   

Implementation Patterns

Core Workflows

1. Budget Enforcement Define budgets per user/tenant in config/ai-guard.php:

   'budgets' => [
       'users' => [
           'admin@example.com' => 50, // USD
       ],
       'tenants' => [
           'acme' => 200, // USD
       ],
   ],
   

   Use middleware to auto-apply budgets:

   \SubhashLadumor\AiGuard\Http\Middleware\EnforceAIBudget::class,
   

2. Dynamic Cost Estimation Estimate costs before execution:

   $estimatedCost = AiGuard::estimateCost(
       \Laravel\AI\Facades\AI::make('gpt-3.5-turbo')->prompt('Your prompt')
   );
   if ($estimatedCost > $user->ai_budget) {
       abort(429, 'AI budget exceeded');
   }
   

3. Rate Limiting Combine with Laravel’s rate limiting:

   Route::middleware(['throttle:100,1', 'ai.guard'])->group(...);
   

Integration Tips

• Laravel AI SDK: Works seamlessly with Laravel\AI\Facades\AI (v12.x).
• Custom AI Providers: Extend SubhashLadumor\AiGuard\Contracts\CostCalculator for non-OpenAI LLMs.
• Logging: Use AiGuard::logManualUsage($cost, $model, $userId) for non-AI-SDK calls.
• Webhooks: Integrate with Stripe/OpenAI billing via AiGuard::webhook() events.

Example: SaaS Multi-Tenant Budgeting

// In a service class
public function generateReport(User $user, string $prompt)
{
    $tenantBudget = config("ai-guard.budgets.tenants.{$user->tenant}");

    return AiGuard::execute(function () use ($user, $prompt) {
        return \Laravel\AI\Facades\AI::complete('gpt-4', $prompt)
            ->withBudget($tenantBudget)
            ->withUser($user);
    });
}

Gotchas and Tips

Pitfalls

1. Token vs. Cost Mismatch

   • Issue: OpenAI’s token pricing changes; hardcoded values in config/ai-guard.php may become stale.
   • Fix: Use AiGuard::syncPricing() to fetch live rates or extend CostCalculator to pull from an API.

2. Budget Leaks

   • Issue: Forgetting to wrap AI calls in AiGuard::execute() bypasses budget checks.
   • Fix: Use a global middleware (e.g., HandleIncomingAiRequests) to auto-wrap all AI routes.

3. Concurrency Issues

   • Issue: Race conditions when multiple requests hit the same budget.
   • Fix: Use database transactions:

     AiGuard::execute(function () use ($aiCall) {
         return DB::transaction(function () use ($aiCall) {
             return $aiCall();
         });
     });
     

4. Logging Overhead

   • Issue: High-volume apps may slow down due to log writes.
   • Fix: Batch logs with AiGuard::flushLogs() or disable logging in config/ai-guard.php for non-critical paths.

Debugging

• Check Logs:

  php artisan ai-guard:logs --user=1 --limit=10
  

• Simulate Costs: Override pricing in config/ai-guard.php for testing:

  'pricing' => [
      'gpt-3.5-turbo' => 0.001, // Test with $0.001/1k tokens
  ],
  

• Common Errors:
  • BudgetExceededException: Budget logic failed (check tenants vs. users keys).
  • UnsupportedModelException: Model not in config/ai-guard.pricing.

Extension Points

1. Custom Calculators Create a calculator for a new LLM (e.g., Anthropic):

   namespace App\Services;
   
   use SubhashLadumor\AiGuard\Contracts\CostCalculator;
   
   class AnthropicCalculator implements CostCalculator
   {
       public function calculateCost(string $model, int $tokens): float
       {
           return match ($model) {
               'claude-v1' => $tokens * 0.008,
               default => throw new \InvalidArgumentException("Unsupported model: {$model}"),
           };
       }
   }
   

   Register it in config/ai-guard.php:

   'calculators' => [
       'anthropic' => \App\Services\AnthropicCalculator::class,
   ],
   

2. Webhook Events Listen for budget alerts:

   AiGuard::onBudgetExceeded(function ($event) {
       \Log::warning("Budget alert for user {$event->userId}: {$event->remaining} USD left");
       // Send Slack/email notification
   });
   

3. Slack/Email Alerts Use Laravel Notifications with the AiGuard events:

   AiGuard::onHighUsage(function ($event) {
       $user = User::find($event->userId);
       Notification::route('mail', $user->email)
           ->notify(new AIBudgetAlert($event->remaining));
   });
   

Config Quirks

• Currency: Only USD is fully supported; extend CostCalculator for other currencies.
• Budget Granularity: Budgets are per day by default. Override with:

  AiGuard::withBudget($amount, now()->addDays(7)); // Weekly budget
  

• Zero Budget: Set to 0 to disable AI entirely for a user/tenant.