README

An AI-powered chat bubble for Statamic that provides intelligent assistance with site content using Prism AI and Statamic search integration.

Features

This addon provides:

AI-powered chat bubble with streaming responses
Statamic search integration via AI tools for content assistance
Markdown rendering with syntax highlighting
Expandable thinking process display
Mobile-responsive design with floating chat window
Tool execution tracking for transparency

How to Install

1. Install via Composer

composer require kauffinger/agentic-chat-bubble

2. Frontend Integration

Add the chat bubble component to your layout template:

<!-- In your layout file (e.g., resources/views/layout.antlers.html) -->
{{ nocache }}
    {{ livewire:agentic-chat-bubble }}
{{ /nocache }}

Important: The Livewire component must be wrapped in a {{ nocache }} tag to ensure proper functionality with Statamic's static caching. This prevents the component from being cached and ensures it remains interactive.

3. Install Required NPM Dependencies

The addon requires two JavaScript libraries for markdown processing and syntax highlighting. Install them in your main application:

npm install markdown-it highlight.js

4. Import JavaScript Component

Import and register the markdownProcessor component in your main JavaScript file:

// In resources/js/site.js
import markdownProcessor from '../../vendor/kauffinger/agentic-chat-bubble/resources/js/components/markdownProcessor.js';

// Register with Alpine.js
Alpine.data('markdownProcessor', markdownProcessor);

5. Import CSS Styles

The addon's styles need to be imported into your application's CSS:

For Statamic Peak users:

/* In resources/css/peak.css */
@import '../../vendor/kauffinger/agentic-chat-bubble/resources/css/addon.css';

For other setups:

/* In your main CSS file (e.g., resources/css/app.css or site.css) */
@import '../../vendor/kauffinger/agentic-chat-bubble/resources/css/addon.css';

Important: Make sure your Tailwind configuration scans the addon's views for classes:

// In tailwind.config.js
module.exports = {
  content: [
    // ... your existing paths
    './vendor/kauffinger/agentic-chat-bubble/resources/views/**/*.blade.php',
  ],
  // ... rest of config
};

After adding the imports and updating Tailwind config, rebuild your assets:

npm run build

6. Publish Configuration (Optional)

To customize the addon settings, publish the config file:

php artisan vendor:publish --tag="agentic-chat-bubble-config"

This will create config/agentic-chat-bubble.php where you can configure:

AI provider and model
System prompt
UI settings
Max message length and other limits

7. Other Dependencies

Ensure your application has the following dependencies (likely already installed):

Livewire
Alpine.js with collapse plugin
Prism AI package for chat functionality

Configuration

After publishing the config file, you can customize:

AI Settings

'provider' => env('AGENTIC_CHAT_PROVIDER', 'openai'), // openai, anthropic, google, ollama
'model' => env('AGENTIC_CHAT_MODEL', 'gpt-4-mini'),
'system_prompt' => env('AGENTIC_CHAT_SYSTEM_PROMPT', '...'),
'max_steps' => env('AGENTIC_CHAT_MAX_STEPS', 5),

UI Settings

'ui' => [
    'position' => 'bottom-left', // bottom-left, bottom-right
    'thinking_button_text' => '🧠',
    'thinking_prose_size' => 'prose-sm',
],

Customizing UI Text

All UI text (titles, placeholders, messages) is managed through Laravel's translation system. To customize these texts:

Publish the language files:

php artisan vendor:publish --tag="agentic-chat-bubble-lang"

Edit the published translation file at resources/lang/vendor/agentic-chat-bubble/en/chat-bubble.php:

return [
    'title' => 'Assistant',
    'placeholder' => 'Type your message...',
    'send' => 'Send',
    // ... other translations
];

For other languages, create additional translation files in the appropriate language directory (e.g., resources/lang/vendor/agentic-chat-bubble/de/chat-bubble.php for German).

GDPR Compliance

The addon includes built-in GDPR compliance features that require user consent before sending messages to AI providers.

Configuration

Enable GDPR mode by setting enabled to true in the config file:

'gdpr' => [
    'enabled' => env('AGENTIC_CHAT_GDPR_ENABLED', false),
    'consent_text' => 'This chat uses AI services to process your messages. Your messages will be sent to our AI provider for processing. Do you consent to this data processing?',
    'consent_button_text' => 'I Consent',
    'decline_button_text' => 'No Thanks',
    'declined_message' => 'You need to provide consent to use the chat assistant. You can close this window and reopen it if you change your mind.',
],

Customizing Consent Messages

All GDPR-related text is managed through Laravel's translation system. To customize these messages:

Publish the language files (if not already done):

php artisan vendor:publish --tag="agentic-chat-bubble-lang"

Edit the consent-related translations in resources/lang/vendor/agentic-chat-bubble/en/chat-bubble.php:

return [
    // ... other translations
    'privacy_notice' => 'Privacy Notice',
    'consent_text' => 'We process your messages to provide assistance. Your data will be handled according to our privacy policy.',
    'consent_button' => 'I Consent',
    'decline_button' => 'No Thanks',
    'declined_message' => 'You have declined consent. Chat functionality is disabled.',
    'chat_disabled' => 'Chat is disabled without consent',
    'reconsider_consent' => 'Reconsider consent',
];

The GDPR feature itself is still enabled/disabled via the config file:

'gdpr' => [
    'enabled' => env('AGENTIC_CHAT_GDPR_ENABLED', false),
],

How It Works

When GDPR mode is enabled:

First Message: Users see a consent modal when they try to send their first message
Consent Given: Users can chat normally after giving consent
Consent Declined: Chat is disabled, but users can reconsider their decision at any time
Session Persistence: Consent choice is stored in the session and persists until the session expires

The consent modal clearly explains that messages will be sent to AI providers for processing, ensuring transparency and compliance with data protection regulations.

Rate Limiting

Configure rate limiting to prevent abuse:

'rate_limit' => [
    'enabled' => env('AGENTIC_CHAT_RATE_LIMIT_ENABLED', true),
    'max_messages' => env('AGENTIC_CHAT_RATE_LIMIT_MAX', 30),
    'decay_minutes' => env('AGENTIC_CHAT_RATE_LIMIT_DECAY', 1),
],

Custom Tools

'tools' => [
    // Default tools (Statamic search)
    \Kauffinger\AgenticChatBubble\Tools\GetAvailableStatamicIndexesTool::class,
    \Kauffinger\AgenticChatBubble\Tools\StatamicSearchTool::class,

    // Add your custom tools
    \App\Tools\WeatherTool::class,
    \App\Tools\DatabaseQueryTool::class,

    // Tools with dependencies via closure
    fn() => new \App\Tools\ApiTool(config('services.api_key')),
]

Creating Custom Tools

Custom tools must implement the Prism\Prism\Tool interface:

namespace App\Tools;

use Prism\Prism\Tool;

class WeatherTool extends Tool
{
    public function __construct()
    {
        $this
            ->as('get_weather')
            ->for('Get current weather for a location')
            ->withStringParameter('location', 'City name or coordinates')
            ->using($this);
    }

    public function __invoke(string $location): string
    {
        // Your tool logic here
        return "The weather in {$location} is sunny and 72°F";
    }
}

Dynamic Tool Registration

You can also register tools programmatically in your AppServiceProvider or any service provider:

use Kauffinger\AgenticChatBubble\ServiceProvider as ChatBubbleServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    public function boot()
    {
        // Register a single tool
        ChatBubbleServiceProvider::registerTool(\App\Tools\WeatherTool::class);

        // Register multiple tools
        ChatBubbleServiceProvider::registerTools([
            \App\Tools\DatabaseTool::class,
            fn() => new \App\Tools\ApiTool($this->app['api.client']),
        ]);

        // Conditionally register tools
        if (config('services.weather.enabled')) {
            ChatBubbleServiceProvider::registerTool(\App\Tools\WeatherTool::class);
        }
    }
}

This is useful for:

Conditional tool registration based on environment or config
Registering tools from other packages
Tools that require complex initialization logic

Usage

Once installed, users will see a floating chat bubble in the bottom-left corner that provides:

Content search across your Statamic site
AI-powered answers based on your site's content
Streaming responses with real-time tool usage display
Expandable "thinking" process for transparency

Requirements

Statamic 5.0+
Prism AI package configured with OpenAI
Alpine.js and Livewire for frontend functionality

kauffinger / agentic-chat-bubble

Maintainers

Details

README

Features

How to Install

1. Install via Composer

2. Frontend Integration

3. Install Required NPM Dependencies

4. Import JavaScript Component

5. Import CSS Styles

For Statamic Peak users:

For other setups:

6. Publish Configuration (Optional)

7. Other Dependencies

Configuration

AI Settings

UI Settings

Customizing UI Text

GDPR Compliance

Configuration

Customizing Consent Messages

How It Works

Rate Limiting

Custom Tools

Creating Custom Tools

Dynamic Tool Registration

Usage

Requirements