ds_zagres_ai/BOT_README.md

OpenWebUI Bot Integration

This project integrates the Open WebUI bot to provide AI responses in OpenWebUI channels.

Overview

The bot connects to OpenWebUI via WebSocket and listens for messages in channels. When a message mentions the AI (using trigger words like @ai), the bot processes the message and sends a response back to the channel.

Integration with AI Service

The bot is integrated with the AI service and starts automatically when the service starts (if BOT_ENABLED=true in the .env file). You don't need to run the bot separately unless you want to test it independently.

Configuration

The bot is configured using the following environment variables in the .env file:

# OpenWebUI configuration
OPENWEBUI_URL=http://your-openwebui-url:8080
OPENWEBUI_API_KEY=your-openwebui-api-key

# Model configuration
DEFAULT_MODEL=llama3.1

# Bot configuration
BOT_ENABLED=true  # Set to 'true' to enable the bot, 'false' to disable it
BOT_SYSTEM_PROMPT="You are a helpful AI assistant."  # System prompt for the bot
BOT_TEMPERATURE=0.7  # Temperature for response generation (0.0 to 1.0)
BOT_MAX_TOKENS=2048  # Maximum number of tokens to generate
BOT_TOP_P=0.9  # Top-p sampling parameter (0.0 to 1.0)
BOT_TRIGGERS=@ai,@bot,@assistant,@chatbot  # Comma-separated list of triggers that will make the bot respond
BOT_RESPOND_TO_ALL=false  # Set to 'true' to make the bot respond to all messages, 'false' to only respond to mentions

These settings control how the bot behaves:

• BOT_SYSTEM_PROMPT: The system prompt that sets the bot's personality and behavior
• BOT_TEMPERATURE: Controls the randomness of the responses (higher values = more random)
• BOT_MAX_TOKENS: Maximum length of the generated responses
• BOT_TOP_P: Controls the diversity of the responses (higher values = more diverse)
• BOT_TRIGGERS: Words that will trigger the bot to respond (e.g., @ai)
• BOT_RESPOND_TO_ALL: If true, the bot will respond to all messages, not just those with triggers

Bot API Endpoints

The AI service provides the following endpoints to manage the bot:

• GET /bot/status: Get the status and configuration of the bot
• POST /bot/start: Start the bot with optional configuration parameters:
  • model_id: ID of the model to use (e.g., "llama3.1")
  • system_prompt: System prompt for the bot
  • temperature: Temperature for response generation (0.0 to 1.0)
  • max_tokens: Maximum number of tokens to generate
  • top_p: Top-p sampling parameter (0.0 to 1.0)
  • respond_to_all: Whether to respond to all messages (true/false)
• POST /bot/stop: Stop the bot if it's running

You can also check the bot status and configuration in the configuration endpoint:

• GET /config: Get the current configuration, including detailed bot status and settings

Examples

Start the bot with default settings:

curl -X POST http://localhost:5252/bot/start

Start the bot with custom settings:

curl -X POST http://localhost:5252/bot/start \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "gemma3",
    "system_prompt": "You are a friendly and helpful AI assistant.",
    "temperature": 0.8,
    "max_tokens": 1024,
    "top_p": 0.95,
    "respond_to_all": false
  }'

Get the bot status:

curl http://localhost:5252/bot/status

Stop the bot:

curl -X POST http://localhost:5252/bot/stop

Running the Bot Separately

If you want to run the bot separately from the AI service, you can use the provided scripts:

1. Using the Original AI Example

./run_openwebui_bot.py

This runs the original AI example from the Open WebUI bot repository.

2. Using Our Custom AI Bot

./run_custom_bot.py

This runs our custom AI bot implementation, which includes additional features like:

• Responding only to messages that mention the bot (using trigger words like @ai)
• Adding a robot emoji (🤖) to responses
• Better error handling
• Longer timeout for API calls

How It Works

The bot uses WebSockets to maintain a persistent connection to OpenWebUI and receive real-time events. When a message is received in a channel, the bot checks if it mentions the AI. If it does, the bot processes the message and sends a response back to the channel.

The bot uses the OpenAI-compatible API provided by OpenWebUI to generate responses to messages.

Troubleshooting

If the bot is not responding to messages, check the following:

1. Make sure the OpenWebUI URL and API key are correct in the .env file
2. Verify that the bot is connected to OpenWebUI by checking the logs
3. Make sure you're using one of the trigger words in your messages (e.g., @ai)
4. Check that the model ID is correct and available in your OpenWebUI instance

Differences from Webhook Approach

This bot uses WebSockets to connect to OpenWebUI, which is different from the webhook approach used in the previous implementation. The main differences are:

1. WebSockets: The bot maintains a persistent connection to OpenWebUI and receives real-time events.
2. Webhooks: The previous implementation used webhooks, where OpenWebUI sends HTTP requests to your service when messages are posted in channels.

The WebSocket approach is more efficient for real-time communication and doesn't require your service to be publicly accessible.