README

Reusable Laravel database-aware AI chatbot using Ollama.

Ridgeben Smart Chatbot is a Laravel package that connects your website database with a local AI model through Ollama. It searches your configured database tables, prepares useful context, and sends that context to Ollama so users receive natural, helpful, and database-based answers.

Requirements

Before installing, make sure your project has:

PHP 8.1 or higher
Laravel 10, 11, 12, or 13
Composer
MySQL or any Laravel-supported database
Ollama installed on your local machine or server

Install Ollama

Install Ollama from:

https://ollama.com

Pull the recommended model:

ollama pull llama3.2:3b

Start Ollama:

ollama serve

Check if the model is available:

ollama list

Package Installation

Install the package using Composer:

composer require ridgeben/smart-chatbot

For Laravel 10 projects, use:

composer require ridgeben/smart-chatbot:^1.0.1

After installing the package, run the installer command:

php artisan smart-chatbot:install

The installer will ask setup questions such as:

Website name
Assistant name
Business type
Database table name
Title/name column
Searchable columns
Context columns
Active/status column
Active/status value
Blade layout injection

One-Line Installation

For Linux/macOS/Git Bash:

composer require ridgeben/smart-chatbot && php artisan smart-chatbot:install

For Windows PowerShell:

composer require ridgeben/smart-chatbot; php artisan smart-chatbot:install

For Laravel 10 on Windows PowerShell:

composer require ridgeben/smart-chatbot:^1.0.1; php artisan smart-chatbot:install

Example: Real Estate Website Installation

php artisan smart-chatbot:install --force --inject-widget --website="Bridge Holdings Limited" --assistant="Bridge Holdings Assistant" --business="real estate company" --source-type=project --table=projects --title-column=project_title --searchable=project_title,project_slug,short_description,project_description,project_video_description,feature_text,location_description --context=project_title,project_slug,short_description,project_description,project_video_description,feature_text,location_description,location_url --active-column=status --active-value=1

Example: eCommerce Website Installation

php artisan smart-chatbot:install --force --inject-widget --website="My Shop" --assistant="Shop Assistant" --business="eCommerce website" --source-type=product --table=items --title-column=name --searchable=name,slug,description,short_details,specification --context=name,slug,price,discount_price,stock,description,short_details,specification --active-column=status --active-value=1

Example: Service Website Installation

php artisan smart-chatbot:install --force --inject-widget --website="My Company" --assistant="Company Assistant" --business="service company" --source-type=service --table=services --title-column=title --searchable=title,slug,short_description,description --context=title,short_description,description --active-column=status --active-value=1

What the Installer Does

The installer command automatically:

1. Creates or updates config/smart-chatbot.php
2. Adds chatbot-related values to .env
3. Configures Ollama URL and model
4. Configures website name, assistant name, and business type
5. Configures database source mapping
6. Adds chatbot widget to your Blade layout if possible
7. Clears Laravel cache

Manual Widget Installation

If the installer cannot detect your Blade layout automatically, add this manually before </body> in your main Blade layout:

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

Common layout files:

resources/views/app.blade.php
resources/views/layouts/app.blade.php
resources/views/layouts/master.blade.php
resources/views/layouts/frontend.blade.php

For Inertia projects, add it inside resources/views/app.blade.php before </body>:

<body>
    @inertia

    @include('smart-chatbot::widget')
</body>

Environment Variables

The installer will add these automatically, but you can also add them manually:

SMART_CHATBOT_ENABLED=true
SMART_CHATBOT_NAME="Website Assistant"
SMART_CHATBOT_WEBSITE_NAME="Your Website Name"
SMART_CHATBOT_BUSINESS_TYPE="business"

OLLAMA_URL=http://127.0.0.1:11434
OLLAMA_MODEL=llama3.2:3b
OLLAMA_TIMEOUT=180

Configuration File

After installation, the main config file will be created here:

config/smart-chatbot.php

The most important section is:

'sources' => [
    [
        'source_type' => 'project',
        'table' => 'projects',
        'primary_key' => 'id',
        'title_column' => 'project_title',

        'searchable_columns' => [
            'project_title',
            'project_slug',
            'short_description',
            'project_description',
        ],

        'context_columns' => [
            'project_title' => 'Project Name',
            'short_description' => 'Short Description',
            'project_description' => 'Project Description',
        ],

        'active_column' => 'status',
        'active_value' => 1,
    ],
],

This tells the chatbot which database table and columns it should search.

How It Works

User sends question
↓
Laravel chatbot route receives request
↓
Package searches configured database tables
↓
Package builds useful context
↓
Context is sent to Ollama
↓
Ollama paraphrases the database information
↓
Answer returns to chatbot widget

The chatbot is designed to answer from your website database. It should not invent exact project names, product prices, stock, status, locations, or other factual details if they are not available in the configured database context.

Useful Commands

Clear Laravel cache:

php artisan optimize:clear

Check if the chatbot command is available:

For Windows PowerShell or CMD:

php artisan list | findstr smart-chatbot

For Linux/macOS/Git Bash:

php artisan list | grep smart-chatbot

Check routes:

php artisan route:list

The chatbot route should appear as:

POST smart-chatbot/ask

Testing

After installation, run:

php artisan serve

Visit your website and test questions such as:

hello
who are you?
tell me about [project/product/service name]
what facilities do you have?
what is the price?
is it available?
clear memory

Troubleshooting

Command Not Found

If this command does not work:

php artisan smart-chatbot:install

Run:

composer dump-autoload
php artisan package:discover
php artisan optimize:clear

Then check:

php artisan list | findstr smart-chatbot

Chatbot Widget Not Showing

Make sure this line exists before </body>:

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

Then run:

php artisan optimize:clear

Ollama Not Responding

Make sure Ollama is running:

ollama serve

Check model:

ollama list

Install model if needed:

ollama pull llama3.2:3b

Check .env:

OLLAMA_URL=http://127.0.0.1:11434
OLLAMA_MODEL=llama3.2:3b

Chatbot Cannot Find Database Information

Check your config:

config/smart-chatbot.php

Make sure:

table name is correct
title column exists
searchable columns exist
context columns exist
active_column and active_value are correct

You can test columns using Laravel Tinker:

php artisan tinker

Then:

Schema::getColumnListing('your_table_name');

Composer Error: Missing ext-exif

If Composer shows:

spatie/image requires ext-exif

Enable exif in your PHP configuration.

On Windows, open:

C:\Program Files\php-8.3\php.ini

Find:

;extension=exif

Change it to:

extension=exif

Then restart your terminal and check:

php -m | findstr exif

Security Notes

Do not configure private or sensitive tables as chatbot sources.

Avoid exposing:

users
admins
passwords
sessions
orders with private customer data
payment information
API keys
tokens
private emails
private phone numbers

Only use public website information that visitors are allowed to know.

Production Notes

For production:

1. Keep Ollama private.
2. Do not expose Ollama directly to the internet.
3. Let Laravel call Ollama through localhost or a private server.
4. Use route throttling.
5. Limit question length.
6. Only configure public database tables.
7. Monitor storage/logs/laravel.log for errors.

Update Package

To update the package:

composer update ridgeben/smart-chatbot
php artisan optimize:clear

License

MIT

ridgeben / smart-chatbot

Maintainers

Package info

Statistics

Security