README

ModelMind

ModelMind is a secure, configurable, model-aware AI chat assistant for Laravel applications.

It gives any Laravel app a reusable Blade/Tailwind chat modal, persisted conversation history, configurable Eloquent model context, safe column auto-discovery, learning memory, feedback, and an OpenAI provider behind a clean package interface.

Demo Store

Try ModelMind in Market Lane Store, a sample store and showcase application for MBS packages with ModelMind installed for testing.

Features

Drop-in Blade chat modal with Tailwind-friendly styles.
Headless JSON API mode for React, Vue, Inertia, and mobile clients.
Optional streaming responses for faster-feeling chat UIs.
@modelMind, @modelMindModal, @modelMindStyles, and @modelMindScripts directives.
Built-in presets for store, admin, support, docs, and CRM applications.
Configurable widget position, width, offset, z-index, labels, prompt tone, and brand mark.
Model-aware answers from only the Eloquent models you explicitly enable.
User-aware context with guard, role, tenant, and Gate/policy scoping.
Ranked retrieval with weighted columns, fuzzy matching, multilingual normalization, optional Scout, and optional vector search.
Auto-discovered columns with sensitive field filtering.
Per-model control through the HasModelMindContext trait.
Persisted chat sessions, message history, user feedback, and learned knowledge.
Current-page awareness so visitors can ask about the product, record, or content they are viewing.
Usage analytics and Laravel events for latency, token usage, provider/model usage, failures, feedback rate, action clicks, generated answers, and learned memory.
Configurable table prefix for clean package ownership.
Safe named-route action buttons from configured Laravel routes.
Source citations that show the model, record, fields used, and optional record button.
Multilingual chat: visitors can ask and receive answers in their language, even when your stored application data is in one database language.
Provider drivers for OpenAI, Anthropic, Gemini, Ollama, and custom AI gateways.

Quick Start

Install the package:

composer require mbs047/model-mind

Publish the package assets and run migrations:

php artisan model-mind:install
php artisan migrate

Add your OpenAI credentials:

OPENAI_API_KEY=sk-your-key
OPENAI_ORGANIZATION=org-your-organization-id
MODEL_MIND_PROVIDER=openai
MODEL_MIND_MODEL=gpt-5-nano

Render ModelMind in your Blade layout:

@modelMindStyles
@modelMindModal
@modelMindScripts

Or use the one-line directive:

@modelMind

Enable the models the assistant is allowed to know about in config/model-mind.php:

'models' => [
    App\Models\Product::class => [
        'enabled' => true,
        'label' => 'Products',
        'description' => 'Public product catalog.',
        'columns' => 'auto',
        'include' => ['name', 'slug', 'summary', 'price'],
        'exclude' => ['internal_notes'],
        'relations' => ['category:id,name'],
        'limit' => 50,
        'order_by' => ['updated_at' => 'desc'],
    ],
],

Inspect the exact context before using it in production:

php artisan model-mind:inspect-context

That is the whole first path: install, configure credentials, render the widget, enable safe model context, inspect it, and ask questions from your app.

Common Options

MODEL_MIND_BRAND_MARK=MBS
MODEL_MIND_PRESET=store
MODEL_MIND_THEME=auto
MODEL_MIND_POSITION=bottom-right
MODEL_MIND_WIDTH=25rem
MODEL_MIND_OFFSET=1.25rem
MODEL_MIND_Z_INDEX=9999
MODEL_MIND_TABLE_PREFIX=model_mind_
MODEL_MIND_PROVIDER=openai
MODEL_MIND_API_ENABLED=true
MODEL_MIND_API_PREFIX=api/model-mind
MODEL_MIND_DEFAULT_QUESTIONS="What can you help with?|What data can you see?|How do I configure you?"
MODEL_MIND_SESSION_LIFETIME_MINUTES=120
MODEL_MIND_STREAMING=false
MODEL_MIND_BACKGROUND_MODE=after_response
MODEL_MIND_BACKGROUND_QUEUE=model-mind
MODEL_MIND_CONTEXT_CACHE_SECONDS=600
MODEL_MIND_RETRIEVAL_ENABLED=true
MODEL_MIND_RETRIEVAL_FUZZY=true
MODEL_MIND_RETRIEVAL_MULTILINGUAL=true
MODEL_MIND_INFER_ROUTE_ACTIONS=true
MODEL_MIND_CITATIONS_ENABLED=true
MODEL_MIND_INFER_SOURCE_CITATIONS=true
MODEL_MIND_PAGE_CONTEXT_ENABLED=true
MODEL_MIND_ANALYTICS_ENABLED=true
MODEL_MIND_MAX_OUTPUT_TOKENS=450
MODEL_MIND_STYLES_ASSET=vendor/model-mind/model-mind.css
MODEL_MIND_SCRIPTS_ASSET=vendor/model-mind/model-mind.js

Supported widget positions are bottom-right, bottom-left, bottom-center, top-right, top-left, top-center, center, center-left, and center-right. Short aliases are accepted for top, bottom, left, and right.

Full Documentation

Read the documentation index in docs/README.md. Start with docs/examples.md for simple and advanced copyable setups. Each major feature has its own focused guide: installation, Blade rendering, themes, public assets, headless API mode, streaming responses, provider drivers, model configuration, multilingual answers, retrieval, route actions, source citations, authorization, security, learning memory, feedback, current page context, analytics, events and hooks, background queues, table prefixes, routes, performance, and testing.

For starter configuration by application type, run:

php artisan model-mind:preset --list
php artisan model-mind:preset store --json

For custom UI work, read docs/customizing-the-modal.md. You can publish the default modal view, or point ModelMind to a new modal plus custom public CSS and JavaScript assets.

For application links, configure named route actions in config/model-mind.php; ModelMind will only turn approved route tokens into buttons.

Security

ModelMind is explicit by design. It does not expose every model automatically, filters common sensitive columns, respects model $hidden and $visible, strips HTML from context values by default, and treats database content as data rather than instructions.

Review SECURITY.md before reporting vulnerabilities or enabling sensitive production data.

Contributing

Pull requests are welcome. Please read CONTRIBUTING.md, run the test suite, and keep the package behavior secure by default.

composer install
composer test
composer format

License

ModelMind is open-sourced software licensed under the MIT license.

mbs047 / model-mind

Maintainers

Package info

Fund package maintenance!

Statistics

Security

README

ModelMind

Demo Store

Features

Quick Start

Common Options

Full Documentation

Security

Contributing

License