Buy me a soda

Enter any amount below

Amount

Bears AI Chatbot

Complete Documentation: An AI knowledgebase chatbot solution for Joomla 5 with Retrieval-Augmented Generation (RAG) powered by IONOS AI Model Hub Document Collections, plus comprehensive analytics and keyword extraction.

Overview & Features

Bears AI Chatbot is a comprehensive AI-powered knowledge base solution for Joomla 5 that combines modern AI chat capabilities with powerful analytics and content management features.

🤖 AI Chat Integration

OpenAI-compatible chat via IONOS AI Model Hub with support for multiple models including Llama 3, Mixtral, and Mistral.

📚 RAG (Retrieval-Augmented Generation)

Automatic ingestion of Joomla articles and optional Kunena forum posts with intelligent document retrieval.

📊 Advanced Analytics

Comprehensive usage tracking, cost analysis, token consumption, and performance metrics.

🔍 Keyword Extraction NEW

Intelligent keyword extraction from user messages with configurable ignore words and multi-language support.

♿ Full Accessibility WCAG 2.1 AA

Complete accessibility support with screen reader compatibility, keyboard navigation, and ARIA labels.

🎨 Customizable UI ENHANCED

Flexible positioning, auto dark mode detection, copy conversation, text-to-speech, and responsive design.

⚙️ Automated Management

Background processing with Joomla Scheduler integration for content synchronization.

Package Components

Component Type Purpose
mod_bears_aichatbot Site Module Frontend chat UI and chat flow management
plg_task_bears_aichatbot Task Plugin Background ingestion queue and reconcile jobs
plg_content_bears_aichatbot Content Plugin Enqueues ingestion jobs on content changes
com_bears_aichatbot Admin Component Analytics dashboard, usage tracking, collection management

Requirements

System Requirements: Ensure your system meets these minimum requirements before installation.
  • Joomla: Version 5.x or higher
  • PHP: Version 8.1 or higher
  • IONOS Account: AI Model Hub account with API token
  • Optional: Kunena forum component (if you want forum posts included)
  • Server: Outbound HTTPS connections enabled
  • Database: MySQL 5.7+ or MariaDB 10.3+

Installation Guide

Quick Install: The package installer handles most configuration automatically.
  1. Download the Package
    Download pkg_bears_aichatbot.zip from the official repository.
  2. Install via Joomla
    Go to System → Install → Extensions and upload the package file.
  3. Automatic Setup
    The installer will automatically:
    • Enable the Task and Content plugins
    • Create Scheduler tasks (Reconcile: daily at midnight, Queue processor: manual)
    • Create required database tables
  4. Publish Module
    Go to Content → Site Modules and create a new "Bears AI Chatbot" module instance.
  5. Configure IONOS Credentials
    Configure your IONOS API token and model settings in the module parameters.

Configuration

Module Configuration

Primary Configuration: All main settings are configured through the module parameters.

IONOS API Settings

Setting Required Description
IONOS Token Required Your IONOS access token for API authentication
IONOS Token ID Optional Token identifier for enhanced security
IONOS Endpoint Required Default: https://openai.inference.de-txl.ionos.com/v1/chat/completions
Model Required Select from available models (Llama 3 70B/8B, Mixtral 8x7B, etc.)

Knowledge Sources

  • Article Categories: Select Joomla content categories to include
  • Article Limit: Maximum articles to consider (default: 500)
  • Additional URLs: External URLs to include (one per line)
  • Kunena Integration: Include forum posts in knowledge base
  • Sitemap Support: Include site structure for better navigation

Retrieval Settings

  • Top K (default: 6): Number of most relevant document snippets to retrieve
  • Min Score (default: 0.2): Minimum relevance threshold (0.0-1.0)

UI Customization

  • Position: Bottom-right, bottom-left, middle-right, middle-left
  • Dimensions: Width (default: 400px), Height (default: 500px)
  • Offsets: Distance from edges in pixels
  • Dark Mode: Manual enable or auto-detection based on system preference
  • Button Label: Custom text for side position buttons

User Experience Features NEW

  • Auto Dark Mode: Automatically detects and follows system dark mode preference
  • Copy Conversation: One-click copy of entire chat history with timestamps
  • Connection Status: Optional online/offline indicator (configurable interval, disabled by default)
  • Text-to-Speech: Browser-based narration of AI responses (configurable default)
  • Persistent Preferences: User settings saved in browser localStorage

Scheduler Tasks & Content Processing

Critical Setup Step: The scheduler tasks are essential for populating your document collection and enabling advanced AI retrieval. Without running these tasks, your chatbot will only use basic Joomla article search.

Understanding the Docs Table

The #__aichatbot_docs table is the mapping table that tracks which Joomla articles have been uploaded to your IONOS Document Collection. It serves as:

  • Content Tracker: Maps Joomla article IDs to IONOS document IDs
  • Change Detection: Uses content hashes to detect when articles are modified
  • Sync Manager: Prevents duplicate uploads and manages deletions
  • Status Monitor: Shows which content is successfully indexed
Empty Docs Table (0 records): This means your content hasn't been processed yet. The chatbot is only using basic search instead of AI-powered document retrieval.

The Two Scheduler Tasks Explained

🔄 "Bears AI Chatbot: Reconcile"

Purpose: Full content synchronization

When to run: Initially (to populate docs table), then daily/weekly

What it does:

  • Scans ALL articles in selected categories
  • Uploads new articles to IONOS
  • Updates changed articles (detects via hash)
  • Removes deleted/unpublished articles
  • Populates the docs table with mappings

⚡ "Bears AI Chatbot: Process Queue"

Purpose: Incremental updates

When to run: Frequently (every 15-30 minutes)

What it does:

  • Processes queued upload/delete jobs
  • Handles real-time content changes
  • Works on smaller batches for efficiency
  • Triggered by content plugin events

Initial Setup Process

  1. Verify Prerequisites
    • IONOS credentials configured in module
    • Content categories selected
    • Published articles exist in those categories
    • Task plugin is enabled
  2. Run Reconcile Task First
    • Go to System → Scheduler
    • Find "Bears AI Chatbot: Reconcile"
    • Click "Run Now"
    • Wait for completion (may take several minutes)
  3. Verify Results
    • Go to Components → Bears AI Chatbot → Status
    • Check "Docs table exists (X records)" where X > 0
    • Verify collection ID exists
  4. Set Up Regular Schedules
    • Reconcile: Weekly at 2 AM Sunday (0 2 * * 0)
    • Process Queue: Every 30 minutes (*/30 * * * *)

Collection Diagnostics Explained

Diagnostic Meaning Action Required
✅ Docs table exists (0 records) Table created but no content processed Run Reconcile task
✅ Docs table exists (X records) X articles successfully mapped ✅ Working correctly
❌ Docs table missing Database table not created Reinstall package or run SQL manually
✅ Collection ID exists IONOS collection created ✅ Working correctly
❌ No collection ID IONOS collection not created Check credentials, run Reconcile task

Troubleshooting Empty Docs Table

Problem: Collection diagnostics show "Docs table exists (0 records)"

Step-by-Step Resolution:

  1. Check Task Plugin Status
    • Go to Extensions → Plugins
    • Search for "Task - Bears AI Chatbot"
    • Ensure it's Published
  2. Verify Module Configuration
    • IONOS Token is configured
    • Model is selected
    • Content categories are selected
    • Published articles exist in those categories
  3. Run Reconcile Task Manually
    • Go to System → Scheduler
    • Find "Bears AI Chatbot: Reconcile"
    • Click "Run Now"
    • Check execution log for errors
  4. Check Task Execution Results
    • Look for success message like "Reconcile: X upserts, Y deletes"
    • If errors, check IONOS credentials and API connectivity
    • Verify articles are published and in selected categories
  5. Verify Collection Population
    • Return to Components → Bears AI Chatbot → Status
    • Should now show "Docs table exists (X records)" where X > 0
    • Test chatbot - should now use enhanced AI retrieval

Common Task Execution Errors

Error Cause Solution
"Missing IONOS credentials" Token not configured Configure IONOS token in module settings
"No articles found" No published articles in selected categories Check category selection and article status
"HTTP 401 Unauthorized" Invalid IONOS token Verify token is correct and active
"Collection not found" Collection ID invalid Clear collection ID, let task recreate

Performance Considerations

  • Initial Reconcile: May take 5-15 minutes for large sites
  • Batch Size: Default 50 articles per batch (configurable)
  • Rate Limits: IONOS API has rate limits - tasks handle this automatically
  • Memory Usage: Large articles may require increased PHP memory limit

Recommended Task Frequencies

Optimal Schedule: For most Joomla sites, we recommend weekly reconcile and 30-minute queue processing for the best balance of performance, cost, and user experience.

Standard Recommendation (Most Sites)

🔄 Reconcile Task: WEEKLY

Schedule: 0 2 * * 0 (Sunday 2 AM)

Why Weekly:

  • Heavy operation - scans ALL articles
  • Resource intensive (5-15 minutes)
  • Most sites don't change content daily
  • Comprehensive cleanup and integrity checks
  • Cost-effective API usage

⚡ Process Queue: EVERY 30 MINUTES

Schedule: */30 * * * *

Why 30 Minutes:

  • Lightweight operation (seconds to complete)
  • Handles real-time content changes
  • Good balance of timeliness vs efficiency
  • Prevents queue buildup
  • Maintains current chatbot responses

Alternative Schedules by Site Type

Site Type Reconcile Task Process Queue Use Case
High-Activity Sites
Multiple daily updates		 Weekly (Sunday 2 AM) Every 15 minutes
*/15 * * * *		 News sites, active blogs, e-commerce
Medium-Activity Sites
Few updates per day		 Weekly (Sunday 2 AM) Every 30 minutes
*/30 * * * *		 Corporate sites, documentation, forums
Low-Activity Sites
Updates few times per week		 Weekly (Sunday 2 AM) Every hour
0 * * * *		 Personal blogs, small business sites
Static/Archive Sites
Rare updates		 Monthly (1st Sunday)
0 2 1-7 * 0		 Every 2 hours
0 */2 * * *		 Documentation archives, legacy sites

Performance Considerations

🚫 Why Not More Frequent Reconcile?

  • API Rate Limits: IONOS has limits that reconcile can hit
  • Server Load: Full scans are CPU/memory intensive
  • Unnecessary: Most content doesn't change daily
  • Cost: More API calls = higher expenses

⚡ Why Not Less Frequent Queue Processing?

  • User Experience: Delays in content appearing
  • Queue Buildup: Jobs accumulate, slowing processing
  • Real-time Expectation: Users expect current content
  • Search Relevance: Outdated results frustrate users

Monitoring & Adjustment Signs

Monitor Your System: Watch for these indicators to adjust your schedule as needed.
Signs You Need More Frequent Reconcile:
  • Docs table count doesn't match article count
  • Old deleted articles still appearing in search results
  • Major content changes not reflected in chatbot
  • Collection diagnostics showing inconsistencies
Signs You Need More Frequent Queue Processing:
  • New articles not appearing in chatbot for hours
  • Queue jobs table (#__aichatbot_jobs) growing large
  • Users reporting outdated search results
  • Content plugin creating jobs faster than processing
Signs You Can Reduce Frequency:
  • Queue jobs table usually empty
  • Very low content change frequency
  • Server resource constraints
  • Budget concerns with API usage
Success Indicator: Once the Reconcile task runs successfully, your chatbot will use AI-powered document retrieval instead of basic search, providing much more accurate and contextual responses.

User Interface Features NEW

Enhanced UX: The chatbot now includes several convenience features for improved user experience.

Chat Toolbar Controls

📋 Copy Conversation

Click the copy button to copy the entire chat history to clipboard. The conversation is formatted with timestamps and role labels (You/AI) for easy sharing or documentation.

🌙 Dark Mode Toggle

Switch between light and dark themes manually. When not manually set, the chatbot automatically detects and follows your system's dark mode preference.

🔊 Text-to-Speech

Click the speaker icon to enable AI response narration. Uses your browser's built-in speech synthesis with automatic language detection. User preference is saved locally.

🔌 Connection Status

Optional indicator showing online/offline status. Configurable check interval (0 to disable, 10-300 seconds). Disabled by default for better performance.

Configuration Options

Feature Admin Setting User Control Persistence
Dark Mode Enable/Disable in module Toggle button in chat Saved in localStorage
Auto Dark Mode Active when dark mode disabled Follows system preference Automatic detection
Text-to-Speech Default on/off in module Toggle button in chat Saved in localStorage
Connection Status Interval in seconds (0=disabled) View only Optional monitoring

User Preference Priority

  1. User Toggle: If user manually toggles a setting, their preference takes priority
  2. Saved Preference: User preferences are saved in browser localStorage
  3. Module Default: If no user preference exists, module settings are used
  4. System Detection: For dark mode, system preference is detected when not manually set

Text-to-Speech Details

  • Browser Support: Works in Chrome, Firefox, Safari, Edge, and mobile browsers
  • Voice Selection: Uses system default voice for detected language
  • Text Processing: Automatically removes HTML and markdown for clean speech
  • Interruption: Stops speaking when user sends new message
  • Volume: Set at 80% for clear but non-intrusive narration

Connection Status Behavior

  • Configurable: Set check interval in module settings (0 to disable)
  • Online (Green): Normal operation, all features available
  • Offline (Red): Message sending disabled, user notified
  • Performance: Disabled by default to reduce network requests
  • Smart Checking: Pauses when tab is hidden to save resources

Accessibility Features WCAG 2.1 AA

Fully Accessible: Bears AI Chatbot meets WCAG 2.1 AA standards and provides an inclusive experience for all users.

Screen Reader Support

🔊 ARIA Labels & Live Regions

Complete ARIA labeling for all interactive elements with live regions that announce new messages and state changes to screen readers.

📢 Status Announcements

Real-time announcements for chat open/close, loading states, AI processing, and error messages.

🏷️ Message Role Identification

Clear distinction between user messages, AI responses, and error messages for screen reader users.

📝 Semantic HTML Structure

Proper use of HTML5 semantic elements (dialog, log, form, article) with appropriate roles.

Keyboard Navigation

Keyboard Shortcut Action Context
Ctrl+/ or Cmd+/ Open chat Anywhere on page
Escape Close chat When chat is open
Enter Send message In message input field
Tab Navigate elements Full keyboard navigation

Visual Accessibility

  • High Contrast Mode: Enhanced borders and styling when high contrast is enabled
  • Focus Indicators: Visible focus outlines that meet WCAG contrast requirements
  • Dark Mode: Accessible dark theme with proper color contrast ratios
  • Reduced Motion: Respects user's motion preferences and disables animations when requested
  • Responsive Design: Works at all zoom levels up to 200% without horizontal scrolling

Multi-Language Accessibility

The chatbot includes 15+ accessibility-specific language strings that can be translated:

MOD_BEARS_AICHATBOT_OPEN_CHAT="Open AI chatbot" MOD_BEARS_AICHATBOT_CLOSE_CHAT="Close chatbot" MOD_BEARS_AICHATBOT_CHAT_DESCRIPTION="AI-powered knowledge base assistant. Press Ctrl+/ to open, Escape to close." MOD_BEARS_AICHATBOT_USER_MESSAGE="Your message" MOD_BEARS_AICHATBOT_BOT_MESSAGE="AI assistant response" MOD_BEARS_AICHATBOT_THINKING="AI is researching your question"

Technical Implementation

  • ARIA Live Regions: aria-live="polite" for messages, aria-live="assertive" for status
  • Form Labels: Explicit <label> elements with for attributes
  • Loading States: aria-busy attributes and status updates
  • Screen Reader Only Content: .bears-sr-only class for hidden accessibility content
  • Focus Management: Auto-focus on input when chat opens, proper focus indicators

WCAG 2.1 Compliance Status

Level Status Details
Level A ✅ Compliant Keyboard accessible, proper labels, skip links
Level AA ✅ Compliant Color contrast, focus management, ARIA labels
Level AAA 🔄 Partial Enhanced error identification could be improved

Testing Your Accessibility

To test the accessibility features:

  1. Screen Reader Testing: Use NVDA (Windows), JAWS (Windows), or VoiceOver (Mac)
  2. Keyboard Navigation: Navigate using only the Tab, Enter, and Escape keys
  3. High Contrast: Enable high contrast mode in your operating system
  4. Zoom Testing: Test at 200% zoom level
  5. Reduced Motion: Enable "Reduce motion" in your system accessibility settings

Keyword Extraction NEW

Smart Analytics: Automatically extract and analyze keywords from user messages to understand usage patterns.

Configuration Options

Setting Default Description
Minimum Keyword Length 3 Minimum characters for a word to be considered (1-10)
Maximum Keyword Length 50 Maximum characters for a word to be considered (10-100)
Ignore Words 300+ English words Comma-separated list of words to ignore during extraction

Default Ignore Words

The system includes a comprehensive list of 300+ common English ignore words including:

a, able, about, above, across, act, actually, add, after, again, against, age, ago, agree, all, almost, alone, along, already, also, although, always, am, among, an, and, anger, angry, animal, another, answer, any, anyone, anything, anyway, appear, are, area, around, as, ask, at, attack, away...

Multi-Language Support

To support other languages, create language-specific overrides:

  1. Go to System → Manage → Language Overrides
  2. Create override for MOD_BEARS_AICHATBOT_IGNORE_WORDS_DEFAULT
  3. Add comma-separated ignore words for your language

Administrator Component

Access: Navigate to Components → Bears AI Chatbot in the Joomla administrator.

Dashboard Views

1. Status View

  • System status and configuration overview
  • IONOS API connectivity diagnostics
  • Quick usage statistics
  • Database table status

2. Usage View

  • Detailed usage logs with filtering
  • CSV export functionality
  • Token consumption tracking
  • Cost analysis per request

3. Collections View

  • IONOS document collection management
  • Collection metadata and statistics
  • Rebuild collection functionality
  • Document count tracking

4. Keywords View NEW

  • Top keywords by usage frequency
  • Success rates per keyword
  • Trending keywords (last 7 days)
  • Time period filtering options

Analytics & Reporting

Key Performance Indicators (KPIs)

  • Total Requests: Number of chat interactions
  • Token Usage: Prompt, completion, and total tokens
  • Cost Tracking: Estimated costs in USD
  • Success Rates: Answered vs refused vs error rates
  • Collection Size: Number of documents indexed

Available Charts

📈 Tokens Over Time

Stacked chart showing prompt and completion token usage trends

🔄 Requests and Errors

Success vs error rates over time

💰 Spend Over Time

Cost analysis and spending trends in USD

⚡ Latency Analysis

Average and maximum response times

📊 Token Distribution

Histogram of token usage patterns

🎯 Outcomes

Breakdown of answered, refused, and error responses

Keyword Analytics NEW

  • Usage Statistics: Total keywords, queries, success rates
  • Top Keywords: Most frequently used terms
  • Trending Analysis: Keywords gaining popularity
  • Success Correlation: Which keywords lead to successful answers
  • Time Filtering: 7/30/60/90 days, YTD, all time

Troubleshooting

Common Issues

Authentication Errors
If you receive authentication errors, verify your IONOS token and token ID are correct and have the necessary permissions.

Chat Not Working

  • Check IONOS API credentials in module settings
  • Verify the selected model is available in your IONOS account
  • Ensure outbound HTTPS connections are allowed
  • Check browser console for JavaScript errors

No Search Results

  • Verify document collection exists and has content
  • Run the reconcile task to sync content
  • Check if articles are published and in selected categories
  • Lower the minimum score threshold

Scheduler Tasks Not Running

  • Enable Joomla Scheduler in Global Configuration
  • Check task status in System → Manage → Scheduled Tasks
  • Manually run tasks to test functionality
  • Verify cron job is configured on your server

Keywords Not Extracting

  • Check keyword extraction settings in module configuration
  • Verify minimum/maximum length settings
  • Review ignore words list for your language
  • Check error logs for extraction failures

Debug Information

Enable debug logging by adding this to your Joomla configuration:

public $log_level = 'DEBUG'; public $log_categories = ['bears_aichatbot'];

Advanced Topics

Database Schema

Table Purpose
#__aichatbot_usage Usage logs with metrics and costs
#__aichatbot_docs Mapping of Joomla content to remote document IDs
#__aichatbot_jobs Ingestion queue for content processing
#__aichatbot_state Centralized operational state
#__aichatbot_collection_stats Daily snapshots for collection size tracking
#__aichatbot_keywords Keyword extraction analytics

Cost Calculation

The system uses IONOS standard pricing for cost estimation:

  • Prompt tokens: $0.0004 per 1K tokens
  • Completion tokens: $0.0006 per 1K tokens
  • Formula: (prompt/1000) * 0.0004 + (completion/1000) * 0.0006

Collection Management

Document collections are automatically created and managed:

  • Auto-creation: First chat or task run creates collection
  • Synchronization: Content changes trigger background updates
  • Reconciliation: Daily task ensures consistency
  • Rebuild: Manual rebuild option for complete refresh

API Reference

IONOS API Endpoints

Endpoint Method Purpose
/v1/chat/completions POST Chat completions
/collections GET/POST List/create collections
/collections/{id}/query POST Query documents
/collections/{id}/documents POST/DELETE Manage documents

Component API

The administrator component provides JSON APIs for:

  • Usage data: index.php?option=com_bears_aichatbot&task=getUsageData
  • Collection info: index.php?option=com_bears_aichatbot&task=getCollectionInfo
  • Keyword stats: index.php?option=com_bears_aichatbot&task=getKeywordStats
  • Delete collection: index.php?option=com_bears_aichatbot&task=deleteCollection
Security: All admin APIs require core.manage permissions and are CSRF-protected.

Support & Updates

Version: This documentation covers Bears AI Chatbot v2025.09.14 and later versions.

Getting Help

  • Documentation: Check this guide and the README.md file
  • Debug Logs: Enable debug logging for detailed error information
  • System Status: Use the Status view in the admin component
  • Issues & Support: Report issues or get help at GitHub Issues

License

Bears AI Chatbot is released under the GNU General Public License v3.0 or later. See the LICENSE file for complete terms.

Credits

  • Original Development: N6REJ
  • Joomla 5 Enhancements: RAG integration, analytics, and keyword extraction
  • IONOS Integration: AI Model Hub and Document Collections API
Thank you for using Bears AI Chatbot! We hope this documentation helps you get the most out of your AI-powered knowledge base.

Sorry, this website uses features that your browser doesn’t support. Upgrade to a newer version of Firefox, Chrome, Safari, or Edge and you’ll be all set.