zephyrisle/flarum-zai

An intelligent Flarum bot extension with moderation, interaction, and scheduling features.

Maintainers

Details

github.com/Zephyr-Isle/flarum-zai

Source

Issues

Installs: 3

Dependents: 0

Suggesters: 0

Security: 0

Stars: 0

Watchers: 0

Forks: 0

Open Issues: 0

Type:flarum-extension

pkg:composer/zephyrisle/flarum-zai

dev-main 2026-02-11 11:08 UTC

Requires

MIT 04faa398d6809642fe81bbdf3f1c79c954b3d1cb

  • ZephyrIsle <author.woop@example.com>

This package is auto-updated.

Last update: 2026-02-11 11:16:20 UTC

README

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.1 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

  • 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

  • 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.1 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

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

  • 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.1 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

  • 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)

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

To call a tool, the model outputs a JSON object wrapped in tags:

<<TOOL_CALL: {"name":"tool_name","args":{...}}>>

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

  • 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)

  • 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.1 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 <your_api_key>; 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

  • 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

  • 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

  • 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.