ds_zagres_ai/BOT_README.md

# OpenWebUI Bot Integration

This project integrates the [Open WebUI bot](https://github.com/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:
```bash
curl -X POST http://localhost:5252/bot/start
```

Start the bot with custom settings:
```bash
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:
```bash
curl http://localhost:5252/bot/status
```

Stop the bot:
```bash
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

```bash
./run_openwebui_bot.py
```

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

### 2. Using Our Custom AI Bot

```bash
./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.