README

Lightweight, config-driven Laravel package for scoped AI chat using Groq (default free), OpenRouter, and OpenAI.

Requirements

PHP ^8.2
Laravel ^10|^11|^12

Installation

composer require pkc/laravel-ai-chatbot
php artisan ai-chatbot:install

The install command will:

Ask which provider to use (groq / openai / openrouter)
Prompt for the API key (secret input)
Write values to .env
Publish config/ai-chatbot.php

Local path development (before Packagist)

In your Laravel app composer.json:

"repositories": [
  {
    "type": "path",
    "url": "../ai-chatbot",
    "options": { "symlink": true }
  }
]

Then:

composer require pkc/laravel-ai-chatbot:@dev

Configuration

Published config: config/ai-chatbot.php

Key	Description
`default_provider`	`groq`, `openai`, or `openrouter`
`timeout`	HTTP timeout in seconds (default `30`)
`providers.*`	API key, base URL, and model per provider
`allowed_scopes`	Role-based topics (`customer`, `admin`)
`rejection_message`	Polite off-topic refusal template
`widget.*`	Floating bottom-page chat icon settings

Environment variables

AI_CHATBOT_PROVIDER=groq
AI_CHATBOT_TIMEOUT=30

GROQ_API_KEY=
GROQ_BASE_URL=https://api.groq.com/openai/v1
GROQ_MODEL=llama-3.3-70b-versatile

OPENAI_API_KEY=
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-4o-mini

OPENROUTER_API_KEY=
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
OPENROUTER_MODEL=meta-llama/llama-3.3-70b-instruct:free
OPENROUTER_SITE_URL=
OPENROUTER_SITE_NAME=AI Chatbot

Usage

Floating chatbot icon (UI)

Add this once near the end of your main Blade layout (before </body>):

@include('ai-chatbot::widget')

That renders a fixed chat icon at the bottom of the page. Clicking it opens a chat panel that posts to POST /ai-chatbot/ask.

Optional widget settings in config/ai-chatbot.php (or env):

Key / env	Description
`widget.enabled` / `AI_CHATBOT_WIDGET_ENABLED`	Show or hide the icon (default `true`)
`widget.title` / `AI_CHATBOT_WIDGET_TITLE`	Panel header title
`widget.greeting` / `AI_CHATBOT_WIDGET_GREETING`	First bot message
`widget.role` / `AI_CHATBOT_WIDGET_ROLE`	Role used for scope guardrails (`customer` / `admin`)
`widget.position` / `AI_CHATBOT_WIDGET_POSITION`	`right` (default) or `left`
`widget.primary_color` / `AI_CHATBOT_WIDGET_COLOR`	FAB / header color (default `#0f766e`)

Publish the Blade view to customize markup:

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

Service class

use Laradevsumon\AIChatbot\Services\AIChatService;

$result = app(AIChatService::class)->ask(
    prompt: 'Where is my order?',
    role: 'customer',
    context: ['order_id' => 'ORD-1001', 'status' => 'shipped']
);

if ($result['success']) {
    echo $result['message'];
} else {
    logger()->warning($result['error']);
}

Facade

use Laradevsumon\AIChatbot\Facades\AIChat;

$result = AIChat::ask('How do I process a refund?', 'admin');

Response shape

[
    'success' => true,
    'message' => 'Your order is on the way.',
    'provider' => 'groq',
    'model' => 'llama-3.3-70b-versatile',
    // 'error' => '...' // only on failure
]

Floating widget (automatic)

After install, a floating chat icon is auto-injected before </body> on:

Storefront pages → customer role (Store Assistant)
Admin pages (/admin/*) → admin role (Admin Assistant)

No Blade @include is required. Toggle via .env:

AI_CHATBOT_WIDGET_ENABLED=true
AI_CHATBOT_WIDGET_AUTO_INJECT=true
AI_CHATBOT_WIDGET_SHOW_ON_WEB=true
AI_CHATBOT_WIDGET_SHOW_ON_ADMIN=true
AI_CHATBOT_WIDGET_COLOR=#2563eb

Scope guardrails

The package injects a strict system prompt built from allowed_scopes for the given role. The model is instructed to refuse general knowledge, coding help, politics, and other off-topic questions using rejection_message.

Edit scopes in config/ai-chatbot.php to match your store.

Testing

cd /path/to/ai-chatbot
composer install
composer test

Tests use Orchestra Testbench and Http::fake() — no live API key required.

Publishing to Packagist

See PUBLISHING.md for GitHub tagging, Packagist submission, and webhook setup.

Before publishing, replace placeholders:

Composer name: pkc/laravel-ai-chatbot
PHP namespace: Laradevsumon\AIChatbot
Author name/email in composer.json and LICENSE

License

MIT — see LICENSE.

laradevsumon / laravel-ai-chatbot

Maintainers

Package info

Statistics

Security