README

A comprehensive Laravel package for building AI-powered chatbots and agents with support for multiple AI providers (OpenAI, Anthropic, Google AI). Features include encrypted API key management, AI agent creation with custom prompts, function calling tools, and a beautiful web interface for managing your AI infrastructure.

Repository: https://github.com/saurabhshukla-developer/laravel-ai-chatbot

✨ Features

• 🔐 Secure API Key Management - Encrypted storage with support for multiple providers
• 🤖 AI Agent Builder - Create custom AI agents with personalized prompts and configurations
• 🛠️ Function Calling Tools - Powerful tool system for extending AI capabilities
  • File-based tools (auto-discovered PHP classes)
  • Database-backed tools (managed via web UI)
  • Easy tool creation with artisan commands
• 🌐 Multi-Provider Support - OpenAI, Anthropic (Claude), and Google AI
• 💬 Built-in Chat Interface - Ready-to-use web UI for testing agents
• 🎨 Beautiful Web Dashboard - Manage keys, agents, and tools through an intuitive interface
• 🔌 Programmatic API - Full code integration support for Laravel applications
• 📡 Streaming Responses - Real-time response streaming for better UX
• ✅ Fully Tested - Comprehensive test suite with 51 passing tests

Installation

For stable release (recommended):

composer require saurabhshukla-developer/laravel-ai-chatbot:^1.1.1

For development version:

composer config repositories.laravel-ai-chatbot vcs https://github.com/saurabhshukla-developer/laravel-ai-chatbot
composer require saurabhshukla-developer/laravel-ai-chatbot:dev-master

Publish configuration and migrations:

php artisan vendor:publish --provider="LaravelAI\Chatbot\ChatbotServiceProvider" --tag="chatbot-config"
php artisan vendor:publish --provider="LaravelAI\Chatbot\ChatbotServiceProvider" --tag="chatbot-migrations"
php artisan migrate

For detailed setup instructions, see docs/SETUP.md.

Updating to Latest Version

If you're already using this package and want to update to version 1.1.1:

composer update saurabhshukla-developer/laravel-ai-chatbot
php artisan migrate
php artisan cache:clear

What's New in 1.1.1:

• Fixed tools folder-info route errors
• Enhanced documentation organization
• Comprehensive test coverage (51 tests, 100% passing)
• Professional documentation formatting

New Feature: File-Based Tools - Create tools by simply adding PHP files! See docs/QUICK_START_TOOLS.md for a 3-step guide.

📦 Installation

Quick Install

composer require saurabhshukla-developer/laravel-ai-chatbot:dev-master
php artisan vendor:publish --provider="LaravelAI\Chatbot\ChatbotServiceProvider"
php artisan migrate

Detailed Installation

Step 1: Install via Composer

Stable release (recommended):

composer require saurabhshukla-developer/laravel-ai-chatbot:^1.1.1

Development version:

# Add repository first
composer config repositories.laravel-ai-chatbot vcs https://github.com/saurabhshukla-developer/laravel-ai-chatbot

# Then require dev-master version
composer require saurabhshukla-developer/laravel-ai-chatbot:dev-master

Step 2: Publish Configuration and Migrations

php artisan vendor:publish --provider="LaravelAI\Chatbot\ChatbotServiceProvider" --tag="chatbot-config"
php artisan vendor:publish --provider="LaravelAI\Chatbot\ChatbotServiceProvider" --tag="chatbot-migrations"

Step 3: Run Migrations

php artisan migrate

Step 4: (Optional) Publish Views

If you want to customize the views:

php artisan vendor:publish --provider="LaravelAI\Chatbot\ChatbotServiceProvider" --tag="chatbot-views"

Configuration

After publishing the configuration file, you can customize it at config/chatbot.php:

return [
    'default_provider' => env('CHATBOT_DEFAULT_PROVIDER', 'openai'),
    
    'providers' => [
        'openai' => [
            'name' => 'OpenAI',
            'api_url' => env('OPENAI_API_URL', 'https://api.openai.com/v1'),
            'model' => env('OPENAI_MODEL', 'gpt-4'),
            // ...
        ],
        // ...
    ],
    
    'storage_driver' => env('CHATBOT_STORAGE_DRIVER', 'database'),
    
    'routes' => [
        'prefix' => env('CHATBOT_ROUTE_PREFIX', 'chatbot'),
        'middleware' => ['web'],
    ],
];

Usage

Managing API Keys

1. Navigate to /chatbot/api-keys in your browser
2. Click "Add API Key"
3. Select your provider and enter your API key
4. Optionally set it as the default for that provider

Creating AI Agents

1. Navigate to /chatbot/agents in your browser
2. Click "Create Agent"
3. Fill in the agent details:
   • Name: A descriptive name for your agent
   • Provider: Choose OpenAI, Anthropic, or Google AI
   • Model: (Optional) Specific model to use
   • System Prompt: (Optional) Define the agent's behavior and personality
   • Tools: (Optional) Select tools that the agent can use
4. Save the agent

Creating Tools

Method 1: File-Based Tools (Recommended - Easiest!)

Super Easy - Use Artisan Command:

php artisan chatbot:make-tool Calculator

That's it! Edit app/Tools/CalculatorTool.php and customize it.

Or create manually - Create PHP files in app/Tools/ directory:

<?php

namespace App\Tools;

use LaravelAI\Chatbot\Tools\BaseTool;

class CalculatorTool extends BaseTool
{
    public function name(): string
    {
        return 'Calculator';
    }

    public function description(): string
    {
        return 'Performs mathematical calculations';
    }

    public function parameters(): array
    {
        return [
            'properties' => [
                'expression' => [
                    'type' => 'string',
                    'description' => 'Mathematical expression (e.g., "2 + 2")',
                ],
            ],
            'required' => ['expression'],
        ];
    }

    public function execute(array $arguments): mixed
    {
        $expression = $arguments['expression'];
        $result = eval("return {$expression};");
        return ['result' => $result];
    }
}

That's it! The tool is automatically discovered and available for your agents. No database setup needed!

Available Commands:

• php artisan chatbot:make-tool Name - Create a new tool
• php artisan chatbot:test-tool slug - Test a tool
• php artisan chatbot:list-tools - List all tools

See docs/EASY_TOOL_CREATION.md for details.

Method 2: Database Tools (Via Web UI)

1. Navigate to /chatbot/tools in your browser
2. Click "Create Tool"
3. Fill in the tool details and save

For detailed examples, see:

• docs/TOOLS_README.md - File-based tools guide (Recommended)
• docs/TOOLS_EXAMPLES.md - Database tools and advanced examples

Using Agents in Code

Basic Chat

use LaravelAI\Chatbot\Facades\Chatbot;

// Get an agent by slug or ID
$agent = Chatbot::getAgent('my-agent-slug');

// Chat with the agent
$response = Chatbot::chat($agent, 'Hello, how are you?');

echo $response['content'];

Using Specific Provider

use LaravelAI\Chatbot\Facades\Chatbot;

// Use a specific provider
$provider = Chatbot::provider('openai');

// Create an agent programmatically
$agent = Chatbot::createAgent([
    'name' => 'Customer Support Bot',
    'slug' => 'customer-support',
    'provider' => 'openai',
    'system_prompt' => 'You are a helpful customer support assistant.',
    'is_active' => true,
]);

// Chat with the agent
$response = Chatbot::chat($agent, 'I need help with my order');

Streaming Responses

use LaravelAI\Chatbot\Facades\Chatbot;

$agent = Chatbot::getAgent('my-agent');

foreach (Chatbot::streamChat($agent, 'Tell me a story') as $chunk) {
    if (!$chunk['done']) {
        echo $chunk['content'];
        flush();
    }
}

Advanced Options

$response = Chatbot::chat($agent, 'Your message', [
    'temperature' => 0.9,
    'max_tokens' => 1000,
    'model' => 'gpt-4-turbo', // Override agent's default model
]);

Using Agents with Tools

use LaravelAI\Chatbot\Facades\Chatbot;
use LaravelAI\Chatbot\Models\Tool;

// Get an agent
$agent = Chatbot::getAgent('math-assistant');

// Tools are automatically included when chatting
$response = Chatbot::chat($agent, 'What is 25 * 4?');

// The AI can use assigned tools to answer the question
echo $response['content'];

// To assign tools programmatically:
$calculatorTool = Tool::where('slug', 'calculator')->first();
$agent->tools()->attach($calculatorTool->id);

For more tool examples, see docs/TOOLS_EXAMPLES.md

📚 Documentation

Comprehensive documentation is available in the docs/ directory:

Getting Started

• Quick Start Tools - Create your first tool in 3 steps
• Setup Guide - Detailed installation and configuration
• Quickstart - Quick overview of the package

Tools & Development

• Tools Guide - Complete guide to creating and using tools
• Tool Examples - Real-world examples and use cases
• Easy Tool Creation - Simplified tool creation guide

Testing & Troubleshooting

• Testing Guide - Comprehensive testing documentation
• Troubleshooting - Common issues and solutions
• Tool Troubleshooting - Tool-specific issues

See docs/README.md for the complete documentation index.

Direct Provider Access

use LaravelAI\Chatbot\Facades\Chatbot;

$provider = Chatbot::provider('openai');
$response = $provider->chat($agent, 'Hello');

Routes

The package automatically registers the following routes (with /chatbot prefix by default):

• GET /chatbot/api-keys - List all API keys
• GET /chatbot/api-keys/create - Create new API key form
• POST /chatbot/api-keys - Store new API key
• GET /chatbot/api-keys/{id}/edit - Edit API key form
• PUT /chatbot/api-keys/{id} - Update API key
• DELETE /chatbot/api-keys/{id} - Delete API key
• GET /chatbot/agents - List all agents
• GET /chatbot/agents/create - Create new agent form
• POST /chatbot/agents - Store new agent
• GET /chatbot/agents/{id} - View agent details and chat
• GET /chatbot/agents/{id}/edit - Edit agent form
• PUT /chatbot/agents/{id} - Update agent
• DELETE /chatbot/agents/{id} - Delete agent
• POST /chatbot/agents/{id}/chat - Chat with agent (API endpoint)
• GET /chatbot/tools - List all tools
• GET /chatbot/tools/create - Create new tool form
• POST /chatbot/tools - Store new tool
• GET /chatbot/tools/{id} - View tool details
• GET /chatbot/tools/{id}/edit - Edit tool form
• PUT /chatbot/tools/{id} - Update tool
• DELETE /chatbot/tools/{id} - Delete tool

Environment Variables

You can set these in your .env file:

CHATBOT_DEFAULT_PROVIDER=openai
CHATBOT_STORAGE_DRIVER=database
CHATBOT_ROUTE_PREFIX=chatbot

# Provider-specific (optional if using database storage)
OPENAI_API_KEY=your-openai-key
ANTHROPIC_API_KEY=your-anthropic-key
GOOGLE_AI_API_KEY=your-google-key

Security

• API keys stored in the database are encrypted using Laravel's encryption
• Make sure your APP_KEY is set in your .env file
• API keys are never displayed in plain text in the UI
• Consider adding authentication middleware to protect the routes

Supported Providers

OpenAI

• Models: gpt-4, gpt-4-turbo, gpt-3.5-turbo, etc.
• API Documentation: https://platform.openai.com/docs

Anthropic (Claude)

• Models: claude-3-opus, claude-3-sonnet, claude-3-haiku, etc.
• API Documentation: https://docs.anthropic.com

Google AI

• Models: gemini-pro, gemini-pro-vision, etc.
• API Documentation: https://ai.google.dev/docs

Customization

Custom Provider

To add a custom provider, create a new provider class:

namespace App\Providers;

use LaravelAI\Chatbot\Providers\BaseProvider;
use LaravelAI\Chatbot\Models\AiAgent;

class CustomProvider extends BaseProvider
{
    protected function getProviderName(): string
    {
        return 'custom';
    }

    // Implement required methods...
}

Then register it in the ChatbotManager class.

Custom Views

Publish the views and customize them:

php artisan vendor:publish --tag="chatbot-views"

Views will be published to resources/views/vendor/chatbot/.

📋 Requirements

• PHP: 8.1 or higher
• Laravel: 10.x, 11.x, or 12.x
• Dependencies: Guzzle HTTP Client (automatically installed)
• Database: MySQL, PostgreSQL, or SQLite

🤝 Contributing

Contributions are welcome! Please see our Contributing Guide for details.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

🐛 Support & Issues

• Bug Reports: GitHub Issues
• Security Issues: See SECURITY.md for reporting vulnerabilities
• Documentation: Check docs/ for detailed guides

📝 Changelog

See CHANGELOG.md for a complete list of changes and version history.

👤 Author

Saurabh Shukla

• GitHub: @saurabhshukla-developer
• Email: saurabhshukla.developer@gmail.com

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Made with ❤️ for the Laravel community