PHPackages zephyrisle/flarum-zai - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. zephyrisle/flarum-zai ActiveFlarum-extension[Utility & Helpers](/categories/utility) zephyrisle/flarum-zai ===================== An intelligent Flarum bot extension with moderation, interaction, and scheduling features. v1.0.0(2mo ago)110MITPHP Since Mar 2Pushed 2mo agoCompare [ Source](https://github.com/Zephyr-Isle/flarum-zai)[ Packagist](https://packagist.org/packages/zephyrisle/flarum-zai)[ RSS](/packages/zephyrisle-flarum-zai/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (1)Dependencies (1)Versions (2)Used By (0) Zai Bot for Flarum - Technical Documentation & User Guide ============================================================= [](#zai-bot-for-flarum---technical-documentation--user-guide) 1. Introduction --------------- [](#1-introduction) **Zai Bot** is an intelligent AI assistant extension for Flarum, powered by OpenAI (or compatible LLMs). It integrates deeply with your forum to provide automated interactions, content generation, moderation assistance, and user engagement features. 2. Core Features (10+ Modules) ------------------------------ [](#2-core-features-10-modules) ### 2.1 Intelligent Conversation & Commands [](#21-intelligent-conversation--commands) - **Context-Aware Replies**: The bot understands the context of the last 5 posts in a discussion. - **Command System**: - `/summary`: Generates a concise summary of the discussion. - `/expand`: Expands on the previous post with more details and examples. - `/profile @user`: Analyzes a user's recent activity and style. - `/faq`: Extracts a FAQ list from the current discussion. - `/title`: Suggests optimized titles for the discussion. - `/tone [style]`: Rewrites text in a specific tone (e.g., formal, funny). - `/translate [lang]`: Translates content to the target language. - `/explain`: Explains complex concepts from the previous post. ### 2.2 Engagement Automation [](#22-engagement-automation) - **Auto-Like**: Automatically likes posts when mentioned or when users ask for it. - **Auto-Posting**: Periodically posts new topics based on configured keywords to keep the forum active. - **Daily Digest**: Generates a daily summary of trending topics. - **Holiday & Birthday Wishes**: Automatically posts greetings on holidays and user birthdays. - **New User Welcome**: Automatically welcomes new users upon registration. ### 2.3 Smart Analysis [](#23-smart-analysis) - **Sentiment Analysis**: Detects negative sentiment in posts and replies with supportive messages (if enabled). - **RAG (Retrieval-Augmented Generation)**: Searches the forum for relevant past discussions to answer user questions accurately. - **Resource Detection**: Identifies resource sharing posts and thanks the author. - **Auto Tagging**: (Experimental) Analyzes post content to automatically assign relevant tags. --- 3. Configuration Guide ---------------------- [](#3-configuration-guide) ### 3.1 Basic Setup [](#31-basic-setup) 1. Go to **Admin Dashboard > Zai Bot**. 2. **API URL**: `https://api.openai.com/v1` (or your proxy). 3. **API Key**: Your OpenAI API Key. 4. **Model**: `gpt-3.5-turbo` or `gpt-4o`. 5. **Bot User ID**: The ID of the user account representing the bot (create a user named "Zai" first). ### 3.2 Feature Toggles [](#32-feature-toggles) Enable/Disable features as needed: - **Enable Bot**: Master switch. - **Enable Conversation Memory**: Required for context-aware replies. - **Enable Smart Search (RAG)**: Highly recommended for accurate answers. - **Enable Daily Digest**: Posts a daily summary. - **Enable Auto Posting**: Periodically posts new content. - **Enable Welcome Message**: Greets new users. - **Enable Sentiment Analysis**: Reacts to negative vibes. - **Tag Settings**: All tag settings use **tag slugs** (e.g., `general`, `welcome`, `birthday`), not numeric IDs. ### 3.3 Fine-tuning [](#33-fine-tuning) - **Persona Preset**: Define the bot's personality (e.g., "You are a helpful coding expert..."). - **Auto Posting Topics**: Comma-separated list of topics for the bot to write about. - **Auto Posting Tag Slugs**: Slugs of tags where the bot can post (e.g., `general, off-topic`). - **Custom Bot Name Triggers**: Regex to wake the bot without `@mention` (e.g., `/zai|helper/i`). --- 4. Advanced Usage & Commands -------------------------------- [](#4-advanced-usage--commands) ### 4.1 Console Commands (Cron Jobs) [](#41-console-commands-cron-jobs) Set up these cron jobs for automation: ``` # 1. Daily Digest (e.g., at 9 PM) 0 21 * * * cd /path/to/flarum && php flarum zai:dailydigest # 2. Auto Posting (e.g., every hour - checks interval internally) 0 * * * * cd /path/to/flarum && php flarum zai:autopost # 3. Holiday & Birthday Checks (e.g., at 8 AM) 0 8 * * * cd /path/to/flarum && php flarum zai:holiday 0 8 * * * cd /path/to/flarum && php flarum zai:birthday ``` ### 4.2 RAG Configuration [](#42-rag-configuration) - Ensure your database search is working. - The bot uses `DiscussionSearcher` to find relevant content. No external vector DB is required (uses Flarum's native search). --- 5. Agent & Tool Calling (External APIs) ------------------------------------------- [](#5-agent--tool-calling-external-apis) Zai runs in an **Agent** mode for post replies: the model can decide to call tools, receive tool results, and then continue the response. ### 5.1 Tool Call Format [](#51-tool-call-format) To call a tool, the model outputs a JSON object wrapped in tags: ``` ``` When a tool call happens, Zai executes it server-side and feeds the result back to the model as a system message, then the model continues to produce the final reply. ### 5.2 Built-in Tools [](#52-built-in-tools) - `like_post`: Like the current post. - `analyze_image`: Analyze a public image URL (enabled by `zephyrisle-zai.enable_image_analysis`). - `web_search`: Search the public web (disabled by default). - `fetch_url`: Fetch a public URL and return a readable excerpt (disabled by default). - `get_weather`: Get current weather for a location (disabled by default). - `post_holiday_greeting` / `post_birthday_greeting`: Create greeting discussions (**admin-only**, disabled by default). ### 5.3 Tool Settings (Defaults) [](#53-tool-settings-defaults) - `zephyrisle-zai.agent_max_turns` (default: 4) - `zephyrisle-zai.enable_web_search` (default: false) - `zephyrisle-zai.web_search_provider` (default: `duckduckgo`, optional: `serper`) - `zephyrisle-zai.serper_api_key` (required only when provider is `serper`) - `zephyrisle-zai.enable_web_fetch` (default: false) - `zephyrisle-zai.enable_weather` (default: false) - `zephyrisle-zai.enable_greeting_tools` (default: false) 6. Troubleshooting ------------------ [](#6-troubleshooting) ### 6.1 Common Issues [](#61-common-issues) - **CSRF Token Mismatch (TokenMismatchException)**: - **Cause**: This error occurs when making API requests (`POST /api/posts`) without a valid `X-CSRF-Token` header or API Key. It is **not** caused by the Zai Bot extension itself, but prevents you from posting to test the bot. - **Fix (Browser)**: Clear your browser cookies and ensure your `config.php` URL matches your browser URL exactly. - **Fix (Postman/API)**: Use an API Key (Master Token) to bypass CSRF. - Header: `Authorization: Token ; userId=1` - **Bot not replying**: - Check `storage/logs/flarum.log`. - Verify API Key and Credit balance. - Ensure Bot User ID is correct. - **"Class not found" errors**: - Run `composer dump-autoload`. - Ensure all dependencies are installed. - **Auto Posting not working**: - Check Cron jobs are running. - Check "Last Run Time" logic (it waits for the configured interval). ### 6.2 Performance [](#62-performance) - **Memory**: The bot stores conversation history in memory during the request. Long discussions may hit token limits. - **Latency**: API calls can take 2-10 seconds. The forum UI handles this asynchronously mostly, but initial reply generation is synchronous in the backend queue (or direct depending on setup). --- 7. Security & Best Practices -------------------------------- [](#7-security--best-practices) - **API Key**: Never share your API key. - **Moderation**: Enable "Enable Moderation" to filter bad content before sending to LLM. - **Rate Limiting**: The bot respects Flarum's flood control, but be mindful of API costs. - **Prompt Injection**: The system includes basic anti-tampering prompts, but always monitor bot activity. --- 8. Developer Guide ------------------ [](#8-developer-guide) - **Namespace**: `ZephyrIsle\Zai` - **Services**: - `BotService`: Handles LLM communication. - `CommandProcessor`: Parses `/cmd` inputs. - `SentimentService`: Analyzes text mood. - **Extending**: Listen to `Flarum\Post\Event\Posted` to add more triggers. ### Health Score 35 — LowBetter than 80% of packages Maintenance86 Actively maintained with recent releases Popularity8 Limited adoption so far Community6 Small or concentrated contributor base Maturity33 Early-stage or recently created project Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Unknown Total 1 Last Release 70d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/ac5dcab64b681ca4252624f74d6a75ffe53795b48eb30710fba9c367b4aeb0d8?d=identicon)[Zephyr-Isle](/maintainers/Zephyr-Isle) --- Top Contributors [![Zephyr-Isle](https://avatars.githubusercontent.com/u/133970629?v=4)](https://github.com/Zephyr-Isle "Zephyr-Isle (10 commits)") ### Embed Badge ![Health badge](/badges/zephyrisle-flarum-zai/health.svg) ``` [![Health](https://phpackages.com/badges/zephyrisle-flarum-zai/health.svg)](https://phpackages.com/packages/zephyrisle-flarum-zai) ``` ### Alternatives [fof/byobu Well integrated, advanced private discussions. 61105.8k9](/packages/fof-byobu)[fof/user-bio Add a user bio to user profiles 2196.5k9](/packages/fof-user-bio)[flarum/extension-manager An extension manager to install, update and remove extension packages from the interface (Wrapper around composer). 12211.5k](/packages/flarum-extension-manager)[flarum/nicknames Allow users to set nicknames. 10288.4k9](/packages/flarum-nicknames)[flarum/pusher See new discussions and posts in real-time using Pusher. 22367.3k4](/packages/flarum-pusher)[fof/drafts Allow users to create post and discussion drafts 1771.1k5](/packages/fof-drafts) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)