Download the PHP package creativecrafts/laravel-ai-assistant without Composer

Laravel AI Assistant

Laravel AI Assistant is an enterprise-grade, comprehensive package designed to seamlessly integrate OpenAI's powerful language models into your Laravel applications. It provides an easy-to-use, fluent API with advanced features including streaming responses, background job processing, lazy loading optimization, comprehensive metrics collection, robust security controls, and sophisticated error handling. Perfect for building production-ready AI-powered applications with enterprise-level reliability and performance.

🔄 Migration Guide (Version 3.x is current in beta and not ready for production)

Upgrading to Latest Version

From v2.x to v3.x

• Breaking Change: The default model has been updated from gpt-4 to gpt-5
• Breaking Change: Streaming configuration has been moved from root level to streaming array
• New Feature: Responses API is now the default for new installations
• Configuration Changes:

From v1.x to v2.x

• Breaking Change: Minimum PHP version increased to 8.2
• Breaking Change: Laravel 9 support dropped, minimum Laravel 10 required
• New Feature: Background job processing added
• Configuration Changes:

Migration Steps

1. Update Dependencies:

2. Update Configuration:

3. Update Environment Variables:

   • Review your .env file against the new configuration options
   • Update any deprecated environment variables

4. Test Your Implementation:

   • Run your test suite to ensure compatibility
   • Check for any deprecated method usage
5. Update Database (if using Eloquent persistence):

Deprecated Features

• ⚠️ Assistant::sendMessage() - Use sendChatMessage() instead
• ⚠️ Root-level streaming config - Use streaming array configuration
• ⚠️ Legacy thread management - Migrate to Responses API for better performance

For detailed migration instructions, see the migration documentation.

Table of Contents

• Overview
• Features
• Choosing the right class
• Installation
• Configuration
• Core Usage
• Advanced Features
  • Streaming Service
  • Background Jobs
  • Lazy Loading
  • Metrics Collection
  • Security Features
  • Performance Optimizations
• Error Handling & Exceptions
• Best Practices
• Cookbook
  • Chat with JSON output
  • Function calling with a Laravel job executor (queue)
  • Attach files and enable file search (vector stores)
• Examples
• Testing
• Contributing
• License

Overview

Laravel AI Assistant simplifies the integration of AI models into your Laravel application with enterprise-grade features. Whether you're building a conversational chatbot, automating content creation, transcribing audio files, or processing large-scale AI operations, this package provides a clean, expressive API to handle complex tasks with minimal effort.

The package now includes advanced architectural improvements:

• Enterprise-grade streaming with memory management and performance monitoring
• Background job processing for long-running AI operations
• Lazy loading optimization for better resource management
• Comprehensive metrics collection for monitoring and analytics
• Advanced security features including rate limiting and request validation
• Sophisticated error handling with custom exception types
• Performance optimizations including caching and connection pooling

⚡ Quick Start (5 Minutes)

Get up and running with Laravel AI Assistant in just 5 minutes:

1. Install the Package

2. Set Your API Key

Add your OpenAI API key to your .env file:

3. Publish Configuration (Optional)

4. Start Using AI Assistant

5. Enable Advanced Features (Optional)

For production use, consider enabling these features in your .env:

That's it! You now have a powerful AI assistant integrated into your Laravel application. Continue reading for advanced features and configuration options.

Features

Core Features

• Fluent API: Chain method calls for a clean and intuitive setup
• Chat Messaging: Easily manage user, developer, and tool messages
• Audio Transcription: Convert audio files to text with optional prompts
• Tool Integration: Extend functionality with file search, code interpreter, and custom function calls
• Custom Configuration: Configure model parameters, temperature, top_p, and more
• DTOs & Factories: Use data transfer objects to structure and validate your data

Advanced Features

• Streaming Service: Real-time response streaming with memory management and buffering
• Background Jobs: Queue long-running AI operations with progress tracking
• Lazy Loading: Optimize resource usage with intelligent lazy initialization
• Metrics Collection: Comprehensive monitoring of API usage, performance, and costs
• Security Service: Advanced security with API key validation, rate limiting, and request signing
• Error Handling: Robust exception system with 8+ custom exception types
• Performance Monitoring: Memory usage tracking and performance optimization
• Caching & Optimization: Intelligent caching for improved performance

Choosing the right class

Pick the entrypoint that best matches your use case:

• AiAssistant (Responses API)

  • Ephemeral, per-turn options. Best for one-off chat turns with modern Responses + Conversations APIs.
  • Strongly-typed DTOs are available via sendChatMessageDto() and ResponseEnvelope via sendChatMessageEnvelope().
  • Great when you want full control over tools, files, response formats, and streaming.

• Assistant (legacy Chat Completions style)

  • Persistent-style builder with backwards compatibility. Returns arrays by default, DTO via sendChatMessageDto().
  • Useful when migrating existing code; supports streaming and many configuration options.
• Facade Ai
  • Ai::chat() provides a discoverable, typed ChatSession over AiAssistant.
  • Ai::assistant() gives you the Assistant builder when you prefer that flow.

Quick examples

• One-off turn (modern Responses API)

• Streaming (text chunks)

• Assistant (legacy-style)

When to choose which

• Prefer Ai::chat() / AiAssistant for new work and modern Responses + Conversations features (tool calls, file_search, json_schema).
• Use Assistant when migrating older code or when its builder API matches your needs today.

See also: Migration Guide in docs/Migrate_from_AssistantAPI_to_ResponseAPI.md.

Installation

You can install the package via composer:

You can publish the config file with:

Configuration

After publishing, you will find a configuration file at config/ai-assistant.php. The configuration includes:

API Credentials

Set your OpenAI API key and organization:

Note:

• This package can optionally use openai-php/client ^0.10. If you install the SDK, you can use the full client; otherwise the package provides internal Compat classes and class aliases so common OpenAI\… types resolve at runtime.
• For chat completions use $client->chat()->create([...]). For legacy text completions use $client->completions()->create([...]). Do not chain $client->chat()->completions()->create([...]).
• AppConfig::openAiClient requires only ai-assistant.api_key. The organization id is optional. If provided, it will be used; otherwise the client is created with API key only.
• Configuration uses the key max_completion_tokens. AppConfig maps this to the OpenAI API parameter max_tokens in request payloads.

Model Settings

Configure your default models for different operations:

Advanced Configuration

Configure advanced features like streaming, caching, and security:

Core Usage

Initializing the Assistant

Create a new assistant instance using the fluent API:

Basic Chat Operations

Configure and send chat messages:

Audio Transcription

Transcribe audio files with language specification:

Creating AI Assistants

Create and configure AI assistants with custom tools:

Advanced Features

Streaming Service

The streaming service provides real-time response processing with advanced memory management and performance monitoring.

Basic Streaming Usage

Advanced Streaming Configuration

Streaming Metrics

Background Jobs

Queue long-running AI operations with progress tracking and retry mechanisms.

Queuing Operations

Batch Operations

Job Monitoring

Lazy Loading

Optimize resource usage with intelligent lazy initialization of AI models and HTTP clients.

Resource Registration

AI Model Lazy Loading

Performance Metrics

Metrics Collection

Comprehensive monitoring and analytics for API usage, performance, and costs.

API Monitoring

Performance Analysis

System Health Monitoring

Security Features

Advanced security controls including API key validation, rate limiting, and request integrity.

API Key Validation

Rate Limiting

Request Integrity

Data Sanitization

Performance Optimizations

Memory Management

Caching Strategies

Advanced Caching Configuration

Configure caching for optimal performance in your environment variables:

Cache Best Practices

Queue Configuration for Background Jobs

Configure background job processing for better scalability:

Environment Configuration

Queue Setup Examples

Redis Queue Configuration

Load Testing and Performance Verification

Performance Benchmarking

Run the included performance tests to verify package performance:

Load Testing Setup

Create load testing scenarios for your application:

Production Load Testing

Use tools like Apache Bench or Siege for production load testing:

Performance Monitoring

Set up comprehensive metrics collection:

Scaling Best Practices

1. Queue Management: Use dedicated queue workers for AI processing
2. Connection Pooling: Enable HTTP connection pooling for better throughput
3. Caching Strategy: Implement multi-layer caching (Redis + Application)
4. Resource Monitoring: Set up alerts for memory and performance thresholds
5. Load Balancing: Distribute requests across multiple application instances
6. Rate Limiting: Implement appropriate rate limiting for API endpoints

Error Handling & Exceptions

The package includes 8+ custom exception types for precise error handling:

Exception Types

Exception Handling Examples

Configuration Validation

Best Practices

Performance Best Practices

1. Use Streaming for Real-time Applications

2. Queue Long-running Operations

3. Implement Lazy Loading for Resources

Security Best Practices

1. Always Validate API Keys

2. Implement Rate Limiting

3. Sanitize Sensitive Data in Logs

Monitoring Best Practices

1. Enable Comprehensive Metrics

2. Set Up Health Monitoring

3. Monitor Token Usage and Costs

Cookbook

Chat with JSON output

Tips:

• Prefer Ai::chat() for modern Responses + Conversations flows.
• setToolChoice('none') if you want pure JSON without tool calls.

Function calling with a Laravel job executor (queue)

This recipe demonstrates enabling queued function (tool) execution. The executor dispatches tool calls as jobs and returns an inline result for determinism while the job runs in your queue.

1) Configure the executor to queue

• In .env:

• Or dynamically in code (e.g., for tests or one-off scripts):

2) Define a callable tool and let the assistant invoke it

Notes:

• With AI_TOOL_CALLING_EXECUTOR=queue, the package dispatches ExecuteToolCallJob internally (requires a working queue).
• For local development, set executor to sync to avoid queue setup: AI_TOOL_CALLING_EXECUTOR=sync.
• Related config: AI_TOOL_CALLING_MAX_ROUNDS, AI_TOOL_CALLING_PARALLEL.

Troubleshooting:

• If jobs don’t run, verify your queue worker and connection settings.
• Check logs: the executor logs dispatch events with correlation IDs.

Attach files and enable file search (vector stores)

Variants:

• Disable automatic file_search while still attaching files:

📊 Performance Benchmarks

Laravel AI Assistant is optimized for enterprise-scale applications. Below are performance metrics and optimization recommendations:

Benchmark Results

Response Times (Average)

• Simple Chat Message: ~800ms-1.2s (depends on model and complexity)
• Streaming Response: First token ~400ms, subsequent tokens ~50-100ms
• File Processing: ~2-5s per MB (varies by file type)
• Background Jobs: Queue dispatch ~50ms, processing time varies

Throughput (With Connection Pooling)

• Concurrent Requests: Up to 100 simultaneous connections
• Requests per Second: 50-150 RPS (depends on response complexity)
• Memory Usage: ~10-50MB per active request
• Connection Reuse: 80-90% efficiency with pooling enabled

Performance Optimization Tips

1. Enable Connection Pooling

Impact: 30-50% improvement in response times for multiple requests

2. Use Background Jobs for Long Operations

Impact: Prevents blocking the main thread, improves user experience

3. Optimize Streaming Configuration

Impact: 60-80% faster perceived response times for long responses

4. Configure Memory Monitoring

Impact: Prevents memory exhaustion, maintains system stability

5. Enable Metrics Collection

Impact: Provides insights for further optimization

Model-Specific Performance

Scaling Recommendations

Small Applications (< 1,000 requests/day)

Medium Applications (1,000 - 50,000 requests/day)

Large Applications (> 50,000 requests/day)

Monitoring & Profiling

The package provides built-in performance monitoring:

Examples

Example 1: Building a Chat Interface with Streaming

Example 2: Background Processing with Progress Tracking

Example 3: Advanced AI Assistant with Custom Tools

Example 4: Comprehensive Monitoring Dashboard

Environment Variables

Add the following to your .env file:

Notes:

• If you set AI_ASSISTANT_PERSISTENCE_DRIVER=eloquent, publish and run the package migrations:

• You can optionally publish Eloquent model stubs for customization:

• With hasMigrations([...]), the package can also load migrations without publishing; publish only if you need to customize.

🔧 Troubleshooting

Common issues and their solutions when working with Laravel AI Assistant:

Installation & Configuration Issues

Issue: "Class 'OpenAI\Client' not found"

Solution:

Issue: "OPENAI_API_KEY environment variable is required"

Solution:

1. Add your API key to .env:

2. Clear config cache:

Issue: Service provider not loading

Solution:

Runtime Issues

Issue: "Connection timeout" errors

Symptoms: Requests taking too long or timing out Solutions:

1. Increase timeout values:

2. Enable connection pooling:

Issue: High memory usage

Symptoms: Memory exhaustion during large operations Solutions:

1. Enable memory monitoring:

2. Use background jobs for large operations:

Issue: "Rate limit exceeded" errors

Symptoms: 429 HTTP status codes from OpenAI Solutions:

1. Enable retry mechanism:

2. Implement request queuing:

Database & Persistence Issues

Issue: "Table doesn't exist" when using Eloquent persistence

Solution:

Issue: Eloquent models not found

Solution:

Performance Issues

Issue: Slow response times

Diagnostic Steps:

1. Check your model selection:

2. Enable streaming for better perceived performance:

3. Use connection pooling:

Issue: Queue jobs not processing

Solution:

1. Ensure queue worker is running:

2. Check queue configuration:

API & Authentication Issues

Issue: "Invalid API key" errors

Solutions:

1. Verify your API key format (starts with sk-):

2. Check API key permissions in OpenAI dashboard
3. Ensure no extra spaces in .env file

Issue: Organization access errors

Solution:

Streaming Issues

Issue: Streaming responses not working

Solutions:

1. Check if streaming is enabled:

2. Verify buffer settings:

3. Ensure proper headers in your frontend:

Development & Testing Issues

Issue: Tests failing with API key errors

Solution: Use the test configuration override:

Issue: Mock responses not working

Solution:

Debug Mode

Enable debug logging for troubleshooting:

Then check your Laravel logs:

Getting Help

If you're still experiencing issues:

1. Check the logs: Laravel logs often contain detailed error information
2. Review configuration: Compare your config with the defaults
3. Test with minimal setup: Try with basic configuration first
4. Check GitHub issues: Search existing issues for similar problems
5. Create an issue: Provide detailed error messages and configuration

Useful Commands for Debugging

Testing

Bootstrap: tests/Pest.php applies the shared TestCase across the test suite. The shared tests/TestCase.php configures:

• database.default = testing
• ai-assistant.api_key = 'test_key_123' (bypasses ServiceProvider OPENAI_API_KEY validation in tests)

If you author tests that boot the app outside the shared TestCase, set this config key manually inside the test or provide OPENAI_API_KEY in env to avoid ConfigurationValidationException during package boot.

The package has 100% code and mutation test coverage. Run tests using:

Compatibility

• PHP: 8.1, 8.2, 8.3+
• Laravel: 9.x, 10.x, 11.x
• OpenAI API: Compatible with latest API versions as of December 2024

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details on how to contribute to this package.

Security Vulnerabilities

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

Credits

• Godspower Oduose
• All Contributors

License

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

Responses + Conversations (New API)

This package now uses OpenAI's Responses + Conversations APIs under the hood. Below are copy‑paste examples that match the current fluent methods and payload shapes.

Quickstart: Start and use a conversation

To continue the same conversation:

Instructions (system/developer persona)

Tool choice and response format (json_schema)

File search and attachments

Disable auto file_search insertion if you want to pass file_ids but avoid the tool:

Images: from file and by URL

Streaming with onEvent and shouldStop

Cancel an in‑flight response

Continue a turn with tool results

Deprecation notes (legacy Assistants/Threads/Runs)

The following legacy methods are deprecated. Use the new replacements:

• createThread(), writeMessage(), runMessageThread(), listMessages() → startConversation(), sendChatMessage()/streamChatMessage(), and AssistantService::listConversationItems().
• createAssistant/getAssistantViaId → Prefer local config + per‑turn instructions via instructions().

See docs/Migrate_from_AssistantAPI_to_ResponseAPI.md for the complete migration guide.

QA checklist for examples

• Configured OPENAI_API_KEY and default model in config/ai-assistant.php
• Confirmed conversationId is returned and reused across turns
• Verified streaming events print deltas and respect early stop
• Validated tool_call flow with continueWithToolResults()
• Confirmed cancelResponse() works with an in‑flight response ID
• Verified addImageFromFile/addImageFromUrl block shapes in payload
• Checked file_search toggles based on includeFileSearchTool()/useFileSearch(false)

Additional Documentation

• Architecture Overview: docs/ARCHITECTURE.md
• Code Map: docs/CODEMAP.md
• Migration Guide: docs/Migrate_from_AssistantAPI_to_ResponseAPI.md
• Tests Guide: tests/README.md
• Contributing: CONTRIBUTING.md

Migration Guide (2.0)

This release introduces a unified, typed, Laravel-native API while preserving backwards compatibility. Here’s how to migrate gradually.

Key goals

• Prefer Ai::chat() entrypoint and the ChatSession for discoverability and strong typing.
• Keep existing code working, but note deprecations on array-returning methods.

Recommended new entrypoint

Files and Tools helpers

Backwards compatibility and deprecations

• AiAssistant::sendChatMessage(): array is deprecated. Use one of:
  • Ai::chat()->send() which returns ChatResponseDto, or
  • AiAssistant::sendChatMessageDto(): ChatResponseDto, or
  • AiAssistant::sendChatMessageEnvelope(): ResponseEnvelope
• AiAssistant::continueWithToolResults(array): array is deprecated. Use:
  • Ai::chat()->continueWithToolResults($results) → ChatResponseDto, or
  • AiAssistant::continueWithToolResultsDto()/continueWithToolResultsEnvelope()
• AiAssistant::reply(?string): array is deprecated. Use:
  • Ai::chat($message)->send() or Ai::chat()->setUserMessage($message)->send()
• Assistant::sendChatMessage(): array is deprecated. Use:
  • Assistant::sendChatMessageDto(): ChatResponseDto, or
  • Ai::chat() for the new fluent chat entrypoint

Why DTOs?

• ChatResponseDto provides a stable, typed surface while preserving access to the underlying normalized array via toArray().
• StreamingEventDto provides a consistent event shape for streaming.
• ResponseEnvelope represents the normalized Responses API envelope when you need full fidelity.

Minimal migration examples

Notes

• All deprecated methods remain functional in 2.x for BC but will be removed in a future major release. Update at your convenience.
• The new API follows Laravel conventions (facades + fluent builders) and improves discoverability (tools(), files()).
• Tests and fakes continue to work. For unit tests, prefer asserting on DTOs.