Download the PHP package webbycrown/laraknow-ai without Composer

LaraKnow AI

A reusable Laravel AI assistant package with safe read-only database tools, conversation history, and a polished chat UI.

LaraKnow AI adds a configurable assistant to any Laravel application. It can answer customer-support or staff-support questions, use safe database tools for allowed tables, preserve conversation context, and render a widget or full-page chat UI.

Version: dev-main

The package stays generic. Host applications decide the business meaning, allowed tables, sensitive columns, routes, branding, and AI provider.

See the Changelog section below for release notes and version history.

📺 Demo Video

▶️ Watch Full Video on YouTube

Highlights

• Reusable Laravel package for CRM, admin panel, booking, eCommerce, SaaS, and other host apps.
• Laravel AI provider integration through the host project's config/ai.php.
• Read-only database tools with table allowlists and blocked columns.
• Grounded responses from verified tool results.
• Cleaner record formatting for readable chat replies.
• Short aggregate answers for count/total questions.
• Conversation history for authenticated users.
• Widget and full-page Blade chat component.
• Safe defaults for prompt security, grounding, rate limiting, schema cache, and response limits.
• Minimal published config so end developers configure only what matters.

Requirements

Installation

1. Add The Repository

If the package is not registered on Packagist, add it as a VCS repository in the host project's composer.json.

2. Install The Package

Laravel package discovery registers the service provider automatically.

3. Publish Laravel AI Configuration

4. Publish LaraKnow Files

5. Run Migrations

6. Clear Cached Configuration

AI Provider Setup

LaraKnow uses the host application's Laravel AI configuration. Configure your provider in config/ai.php and set the needed keys in .env.

Only set keys for providers you actually use. Provider rate limits are controlled by the provider, not by LaraKnow. If one provider stops after a few messages while another continues, check the provider's quota, model limit, and Laravel logs.

Basic Usage

Widget Mode

Full-Page Mode

Published assets are expected at:

If jQuery is already loaded, LaraKnow reuses it. Otherwise, the component loads the package's default jQuery CDN fallback.

Routes

The default route prefix is:

The default route name prefix is laraknow-ai, so route helpers inside the package use names such as laraknow-ai.chat and laraknow-ai.welcome.

Main routes:

Check routes:

Protect routes in config/laraknow.php when needed:

If you need a different named route prefix, update this value as well:

To disable the built-in rate limiter entirely, set:

Configuration

After publishing, edit:

The config is intentionally small. Most technical defaults live inside the package so host developers do not accidentally break response grounding, query limits, prompt safety, schema cache, or rate limiting.

Recommended Shape

Assistant Instructions

Use business language, not package internals. Good instructions tell the assistant:

• what the application is
• what questions are supported
• which tables represent business concepts
• which statuses or codes have meaning
• when to ask follow-up questions
• how detailed answers should be

Example:

Allowed Tables

Only allowed tables can be inspected or queried.

For production, prefer an explicit list. Leaving it empty allows all non-blocked tables and is best reserved for trusted internal testing.

Blocked Columns

Blocked columns are never selected or shown.

Use table-specific blocking when only one table needs extra privacy:

Advanced Query Behavior

LaraKnow uses internal package defaults for safe query limits, prompt security, response grounding, schema filtering, and audit logging. Host applications do not configure these behaviors directly through config/laraknow.php.

UI Settings

The ui section controls only the chat appearance and labels. It does not change database access or AI safety.

Common edits:

Response Behavior

LaraKnow tries to keep answers grounded and readable:

• Count/total prompts return concise aggregate answers.
• Detail/list prompts return a limited, readable list.
• Record replies are formatted as compact Markdown blocks, not raw pipe-separated rows.
• Long description-like columns are hidden by default unless the user asks for details.
• If no verified records are found, the assistant returns a clear no-data response.
• The assistant should not claim database values that were not returned by tools.

Example record reply:

Example metric reply:

API Response Format

Successful chat responses use a predictable payload:

Errors include a stable error object and an HTTP status code:

How It Works

1. The user sends a message from the chat UI.
2. The frontend posts to the chat route.
3. The controller validates the request and safety boundaries.
4. The AI agent combines locked package rules with host config instructions.
5. Database tools inspect only allowed tables and non-blocked fields.
6. SQL execution is read-only and validated before returning data.
7. The reply is grounded, normalized, and returned with data, suggestion, and conversation_id.

Security Model

LaraKnow is built around least privilege.

Protected by default:

• environment values and API keys
• prompts, package internals, and configuration details
• source code, stack traces, and raw SQL
• destructive SQL operations
• sensitive columns such as passwords and tokens
• records from tables that are not allowed
• conversation history belonging to other users

Database tools are read-only and validate table names, selected columns, blocked keywords, limits, and result columns before returning data.

Troubleshooting

Package Routes Are Missing

Confirm the route prefix:

Chat Says Conversation Tables Are Missing

Assets Are Missing

Then clear browser cache.

jQuery Is Not Available

Load jQuery in the host layout, or allow the package's default CDN fallback. For strict CSP environments, load jQuery from a local asset before rendering the LaraKnow component.

The Assistant Gives Wrong Business Answers

Check config/laraknow.php:

• Are the correct tables listed in allowed_tables?
• Are relationships and business statuses described in instructions?
• Are status aliases or numeric scaling rules needed?
• Are important columns accidentally blocked?
• Did you run php artisan config:clear after editing config?

AI Provider Fails Or Rate Limits

Check:

• .env provider key
• config/ai.php default provider
• provider model availability
• provider account quota and rate limits
• Laravel logs for the returned error.id

Development Checklist

After package changes, run:

For route verification:

License

LaraKnow AI is distributed as a reusable Laravel package. Configure and deploy it according to the security requirements of each host application.

📊 Changelog

v1.0.0

• ✨ Initial release of LaraKnow AI, a reusable Laravel assistant package.
• 🔒 Added safe read-only database tools with allowed table allowlists and blocked column protections.
• 💬 Added conversation history, chat UI support, publishable assets, and configurable route prefix/middleware.
• ⚙️ Integrated with Laravel AI through host config/ai.php for provider configuration.
• 🎨 Added UI customization, numeric scaling, categorical aliases, and response grounding features.
• 🛡️ Added security model with prompt safety, SQL validation, blocked sensitive data, and rate limiting.
• 📚 Documented package installation, configuration, usage, troubleshooting, and developer checklist.