kaviyarasu/ai-agent

A Laravel package for AI agent with multi-provider support

V1.6 2025-07-04 05:47 UTC

README

Latest Version on Packagist GitHub Tests Action Status GitHub Code Style Action Status Total Downloads

A flexible, modular AI service architecture for Laravel that supports multiple AI providers (Claude, OpenAI, Ideogram) with easy switching via configuration.

Features

  • 🤖 Multi-Provider Support: Claude, OpenAI, and Ideogram
  • 🔄 Easy Provider Switching: Switch providers at runtime or via configuration
  • 📝 Text Generation: Support for multiple text models
  • 🎨 Image Generation: Create images with DALL-E or Ideogram
  • 🎬 Video Generation: Future-ready video generation support
  • 🏗️ SOLID Architecture: Clean, maintainable code following SOLID principles
  • 🔧 Modular Design: Easy to extend with new providers or capabilities
  • 💾 Caching Support: Built-in caching for API responses
  • 📊 Rate Limiting: Configurable rate limiting per provider
  • 📝 Comprehensive Logging: Track all API interactions
  • 🛠️ Artisan Commands: Scaffolding commands for quick development

Installation

composer require kaviyarasu/ai-agent

This is publish migrations and config file

php artisan ai-agent:install"

or

php artisan vendor:publish --tag="ai-agent-migrations"
php artisan migrate
php artisan vendor:publish --tag="ai-agent-config"

This is the contents of the published config file:

return [
    'default_provider' => env('AI_DEFAULT_PROVIDER', 'claude'),

    'providers' => [
        'claude' => [
            'api_key' => env('CLAUDE_API_KEY'),
            'models' => [...],
        ],
        'openai' => [
            'api_key' => env('OPENAI_API_KEY'),
            'models' => [...],
        ],
        'ideogram' => [
            'api_key' => env('IDEOGRAM_API_KEY'),
            'models' => [...],
        ],
    ],

    // ... more configuration options
];

Usage

Basic Usage

use Kaviyarasu\AIAgent\Facades\AIAgent;

// Text generation
$response = AIAgent::text()->generateText('Write a story about a robot');

// Image generation
$imageUrl = AIAgent::image()->generateImage('A futuristic city at sunset');

// Switch provider at runtime
$response = AIAgent::provider('openai')->text()->generateText('Hello world');

Advanced Usage

Working with Specific Models

use Kaviyarasu\AIAgent\Facades\AIAgent;

// Use a specific Claude model
$response = AIAgent::provider('claude')
    ->text()
    ->switchModel('claude-3-opus-20240229')
    ->generateText('Explain quantum computing');

// Use DALL-E 3 for image generation
$imageUrl = AIAgent::provider('openai')
    ->image()
    ->switchModel('dall-e-3')
    ->generateImage('A serene landscape');

Module-Specific Services

// Storyboard module with specific providers
$characterService = app(\Kaviyarasu\AIAgent\Services\Modules\Storyboard\CharacterService::class);
$character = $characterService->generateCharacter('A brave knight');

$shotService = app(\Kaviyarasu\AIAgent\Services\Modules\Storyboard\ShotService::class);
$shot = $shotService->generateShot('The knight standing on a hill');

Direct Service Access

use Kaviyarasu\AIAgent\Services\Core\TextService;
use Kaviyarasu\AIAgent\Factory\ProviderFactory;

// Create services directly
$providerFactory = app(ProviderFactory::class);
$textService = new TextService($providerFactory);
$response = $textService->generateText('Hello world');

Creating AI Agents

The package includes a powerful scaffolding command to create AI agent classes:

# Create a basic text agent
php artisan ai-agent Blog/BlogAiAgent

# Create an image processing agent
php artisan ai-agent ImageProcessor --capability=image --provider=ideogram

# Create a video agent with logging and fallback
php artisan ai-agent VideoCreator --capability=video --with-logging --with-fallback

# Interactive mode
php artisan ai-agent

See the AI Agent Command Documentation for detailed usage and examples.

Configuration

Environment Variables

# Default provider
AI_DEFAULT_PROVIDER=claude

# Claude configuration
CLAUDE_API_KEY=your-claude-api-key
CLAUDE_MODEL=claude-3-sonnet-20241022

# OpenAI configuration
OPENAI_API_KEY=your-openai-api-key
OPENAI_MODEL=gpt-4

# Ideogram configuration
IDEOGRAM_API_KEY=your-ideogram-api-key
IDEOGRAM_MODEL=ideogram-v2

# Feature flags
AI_RATE_LIMITING_ENABLED=true
AI_CACHE_ENABLED=true
AI_LOGGING_ENABLED=true

# Module-specific providers
STORYBOARD_CHARACTER_PROVIDER=claude
STORYBOARD_SHOT_PROVIDER=ideogram

Provider Configuration

'providers' => [
    'claude' => [
        'api_key' => env('CLAUDE_API_KEY'),
        'models' => [
            'claude-3-sonnet-20241022' => [
                'name' => 'Claude 3 Sonnet',
                'max_tokens' => 4096,
                'capabilities' => ['text'],
            ],
            // ... more models
        ],
    ],
],

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

License

The MIT License (MIT). Please see License File for more information.