README

A modular, reusable Laravel package that provides AI-powered chatbot functionality. It features polymorphic attachment to any Eloquent model, multi-provider LLM support (OpenAI, Gemini, and Claude), context window folding and summarization, and robust quota enforcement for guests and authenticated users.

Features

Polymorphic Conversations: Attach chat sessions to any Eloquent model (e.g., Tickets, Orders, Users, Projects) via a simple Trait.
Multi-Provider LLM Engine: Switch dynamically between OpenAI (ChatGPT), Google Gemini, and Anthropic Claude.
Smart Context Management: Automatically fold older chat histories into session-specific summaries once token thresholds are reached.
Quota & Token Tracking: Track precise token counts utilizing yethee/tiktoken. Enforce limits on daily/monthly usage.
Signed HMAC Guest Sessions: Safely verify guest user rates with cryptographically signed tokens to prevent forging.
Built-in REST API: Ready-to-go endpoints for managing sessions, conversation streams, and rate tracking.

Installation

Add the package to your Laravel application.

composer require shahriar/laravel-chatbot

Publish the config file:

php artisan vendor:publish --provider="Shahriar\LaravelChatbot\Providers\ChatbotServiceProvider" --tag="chatbot-config"

Run database migrations to generate the schema:

php artisan migrate

Database Schema

The package includes three core tables:

chatbot_sessions: Holds polymorphic owner metadata, user association, system prompts, current token counts, and conversation summaries.
chatbot_messages: Stores message exchanges between user and assistant.
chatbot_quotas: Logs token and message usage statistics for guests and authenticated users within daily or monthly periods.

Configuration

The configuration details are located in config/chatbot.php:

return [
    'default' => env('CHATBOT_PROVIDER', 'openai'),

    'providers' => [
        'openai' => [
            'api_key' => env('OPENAI_API_KEY'),
            'model' => env('CHATBOT_OPENAI_MODEL', 'gpt-4o'),
            'context_window' => 128000,
            'history_token_budget' => 4000,
            'reserved_output_tokens' => 1000,
        ],
        'gemini' => [
            'api_key' => env('GEMINI_API_KEY'),
            'model' => env('CHATBOT_GEMINI_MODEL', 'gemini-1.5-flash'),
            'context_window' => 1048576,
            'history_token_budget' => 8000,
            'reserved_output_tokens' => 2000,
        ],
        'claude' => [
            'api_key' => env('ANTHROPIC_API_KEY'),
            'model' => env('CHATBOT_CLAUDE_MODEL', 'claude-3-5-sonnet-20240620'),
            'context_window' => 200000,
            'history_token_budget' => 8000,
            'reserved_output_tokens' => 2000,
        ],
    ],

    'quota' => [
        'enabled' => true,
        'reset_period' => 'daily', // 'daily' or 'monthly'
        'guest' => [
            'tokens_per_day' => 2000,
            'messages_per_day' => 20,
        ],
        'authenticated' => [
            'tokens_per_day' => 10000,
            'messages_per_day' => 100,
        ],
    ],
    
    // ...
];

Programmatic Usage

1. Attaching Chat Sessions to Models

Apply the HasChatSessions trait to your Eloquent models:

use Illuminate\Database\Eloquent\Model;
use Shahriar\LaravelChatbot\Traits\HasChatSessions;

class SupportTicket extends Model
{
    use HasChatSessions;
}

Now, easily start and fetch sessions:

$ticket = SupportTicket::find(1);

// Start a session
$session = $ticket->startChat([
    'title' => 'Server Configuration Issue',
    'system_prompt' => 'You are a senior Linux administrator assisting with server setup.'
]);

// Access sessions
$sessions = $ticket->chatSessions;

2. Processing Messages with the Facade

Send messages using the Chatbot Facade:

use Shahriar\LaravelChatbot\Facades\Chatbot;

$session = ChatbotSession::find($sessionId);

// Send message (uses default provider and model)
$responseMessage = Chatbot::sendMessage($session, 'How do I restart Nginx?');

echo $responseMessage->content;

// Send message using a different model or provider dynamically
$responseMessage = Chatbot::sendMessage($session, 'Write an alias for that.', [
    'provider' => 'gemini',
    'model' => 'gemini-1.5-pro'
]);

Web API Routes

When enabled, the package registers the following prefix-independent JSON routes (default: /api/chatbot):

Method	Endpoint	Description	Middleware
`POST`	`/sessions`	Create a new chatbot session	`api`
`POST`	`/sessions/{session}/messages`	Send a message to the chatbot	`api`, `chatbot.quota`
`GET`	`/sessions/{session}/messages`	Fetch message history for a session	`api`
`GET`	`/quota`	View current user/guest quota status	`api`, `chatbot.quota`

Guest Session Handling

If a request is made by an unauthenticated user, the chatbot.quota middleware dynamically attaches a cryptographically signed HMAC token (X-Guest-Token) to the response headers and cookies. The client should persist this token and supply it on subsequent calls (as a cookie or header) to preserve limits and prevent quota tampering.

API Response Metadata

The message-sending endpoint returns the assistant message along with current quota tracking limits inside the response body metadata:

{
  "data": {
    "id": 15,
    "role": "assistant",
    "content": "To restart Nginx, run: sudo systemctl restart nginx",
    "token_count": 14,
    "created_at": "2026-08-12T12:00:00Z"
  },
  "meta": {
    "quota": {
      "tokens_used": 145,
      "tokens_remaining": 1855,
      "messages_used": 2,
      "messages_remaining": 18,
      "resets_at": "2026-08-13T00:00:00Z"
    }
  }
}

Customizing & Overriding Core Classes

You can publish the default controller and middleware files directly into your application space. This allows you to customize their logic (e.g. extending them, changing middleware logic, or adding custom API validation structures).

1. Publish the Controller

Run the following artisan command to copy the controller class:

php artisan vendor:publish --provider="Shahriar\LaravelChatbot\Providers\ChatbotServiceProvider" --tag="chatbot-controller"

This will copy the file to app/Http/Controllers/Chatbot/ChatbotController.php. You can modify it, adjust the namespace to App\Http\Controllers\Chatbot, and update your config/chatbot.php:

'controller_class' => \App\Http\Controllers\Chatbot\ChatbotController::class,

2. Publish the Middleware

Run the following artisan command to copy the quota rate-limiting middleware:

php artisan vendor:publish --provider="Shahriar\LaravelChatbot\Providers\ChatbotServiceProvider" --tag="chatbot-middleware"

This copies the middleware file to app/Http/Middleware/CheckChatbotQuota.php. Adjust the namespace to App\Http\Middleware and point the config file to it:

'middleware_class' => \App\Http\Middleware\CheckChatbotQuota::class,

Testing

Run tests locally using PHPUnit:

php ./vendor/bin/phpunit

hassan-shahriar-1 / laravel-chatbot

Maintainers

Package info

Statistics

Security