katema/laravel-genai

Drop-in Generative AI for Laravel applications - opinionated, extensible, and production-ready

v1.0.1 2025-12-27 23:21 UTC

Requires

• php: ^8.1|^8.2|^8.3
• guzzlehttp/guzzle: ^7.0
• illuminate/contracts: ^9.0|^10.0|^11.0|^12.0
• illuminate/support: ^9.0|^10.0|^11.0|^12.0

Requires (Dev)

• mockery/mockery: ^1.5
• orchestra/testbench: ^7.0|^8.0|^9.0|^10.0
• phpunit/phpunit: ^10.0|^11.0

MIT

• Aaron Katema

• laravel
• ai
• Gemini
• openai
• llm
• claude
• generative-ai

README

Drop-in Generative AI for Laravel applications - opinionated, extensible, and production-ready.

Features

• 🎯 Simple API - Clean, Laravel-native syntax
• 🔌 Provider Agnostic - OpenAI, Claude, Gemini, Ollama, or custom
• 📝 Prompt Management - Version control your prompts
• 💾 Context Management - Maintain conversation context
• 🎨 Model Integration - Add AI to Eloquent models with traits
• 📊 Cost Tracking - Monitor tokens and costs
• 🔒 Production Ready - Rate limiting, validation, error handling
• 🚀 Queue Support - Async AI operations

Installation

composer require katema/laravel-genai
php artisan genai:install

Set your API key in .env:

GENAI_PROVIDER=openai
OPENAI_API_KEY=your-api-key-here
OPENAI_MODEL=gpt-4-turbo-preview

Quick Start

Basic Text Generation

use Katema\LaravelGenAI\Facades\AI;

$response = AI::text('Write a product description for a coffee mug');
echo $response->content;

Chat Conversations

$messages = [
    ['role' => 'user', 'content' => 'What is Laravel?'],
];

$response = AI::chat($messages);
echo $response->content;

Structured JSON Output

$data = AI::json('Generate a user profile with name, email, and bio');
// Returns: ['name' => 'John Doe', 'email' => '[e-mail]', 'bio' => '...']

With Context

$response = AI::withContext([
    'user' => auth()->user()->name,
    'company' => 'Acme Corp'
])->text('Write a welcome email');

Prompt Management

Create reusable prompts in resources/prompts/:

prompts/marketing/product_description.md:

Generate a compelling product description for:

**Product:** {{product_name}}
**Category:** {{category}}
**Features:** {{features}}

Make it persuasive and highlight benefits.

Use it in your code:

$response = AI::prompt('marketing.product_description', [
    'product_name' => 'Smart Coffee Maker',
    'category' => 'Kitchen Appliances',
    'features' => 'WiFi enabled, programmable, auto-shutoff'
]);

Model Integration

Add AI capabilities to your Eloquent models:

use Katema\LaravelGenAI\Traits\HasAI;

class Product extends Model
{
    use HasAI;
}

Then use it:

$product = Product::find(1);

// Generate a summary
$summary = $product->summarize();

// Generate a description
$description = $product->describe();

// Ask questions about the model
$insights = $product->insights('What makes this product unique?');

Multiple Providers

Switch between providers easily:

// Use OpenAI
$response = AI::driver('openai')->text('Hello');

// Use Claude
$response = AI::driver('claude')->text('Hello');

Configure providers in config/genai.php:

'providers' => [
    'openai' => [
        'api_key' => env('OPENAI_API_KEY'),
        'model' => env('OPENAI_MODEL', 'gpt-4-turbo-preview'),
    ],
    'claude' => [
        'api_key' => env('CLAUDE_API_KEY'),
        'model' => env('CLAUDE_MODEL', 'claude-3-5-sonnet-20241022'),
    ],
],

Advanced Usage

System Prompts

$response = AI::withSystemPrompt('You are a helpful marketing assistant')
    ->chat($messages);

Custom Options

$response = AI::text('Write a story', [
    'temperature' => 0.9,
    'max_tokens' => 500,
    'model' => 'gpt-4'
]);

Fresh Context

AI::withContext(['user' => 'Alice'])
    ->text('First request');

// Clear context for next request
AI::fresh()->text('Second request');

Cost Tracking

All responses include cost and token information:

$response = AI::text('Hello');

echo $response->tokensUsed; // 150
echo $response->cost;       // 0.0045
echo $response->model;      // gpt-4-turbo-preview
echo $response->provider;   // openai

Configuration

Publish the config file:

php artisan vendor:publish --tag=genai-config

Key configuration options:

// Default provider
'default' => env('GENAI_PROVIDER', 'openai'),

// Rate limiting
'rate_limits' => [
    'enabled' => true,
    'max_requests_per_minute' => 60,
    'max_tokens_per_day' => 100000,
],

// Safety
'safety' => [
    'prompt_injection_detection' => true,
    'output_validation' => true,
    'max_prompt_length' => 10000,
],

Artisan Commands

# Install the package
php artisan genai:install

# Create a new prompt template
php artisan genai:prompt marketing.email

# Test a prompt
php artisan genai:test marketing.email --var="product=Coffee"

Contributing

We welcome contributions! Please see CONTRIBUTING.md for details.

Security

If you discover any security issues, please email [e-mail] instead of using the issue tracker.

License

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

Credits

• Aaron Katema
• All Contributors

Built with ❤️ for the Laravel community