vibe-bot/README.md

# Vibe Discord Bot with RAG Chat History

A Discord bot that stores long-term chat history using SQLite with RAG (Retrieval-Augmented Generation) capabilities. It supports custom bots with personalities, text-to-speech via Kokoro, image generation, and image editing.

- [Vibe Discord Bot with RAG Chat History](#vibe-discord-bot-with-rag-chat-history)
  - [Available Commands](#available-commands)
    - [Custom Bot Management](#custom-bot-management)
    - [Using Custom Bots](#using-custom-bots)
    - [Text-to-Speech](#text-to-speech)
    - [Image Commands](#image-commands)
    - [Bot Conversations](#bot-conversations)
    - [Chat History](#chat-history)
  - [Features](#features)
  - [Setup](#setup)
    - [Prerequisites](#prerequisites)
    - [Environment Variables](#environment-variables)
    - [Installation](#installation)
    - [Running the Bot](#running-the-bot)
  - [How It Works](#how-it-works)
    - [Database Structure](#database-structure)
    - [RAG Process](#rag-process)
  - [File Structure](#file-structure)
  - [Building](#building)
    - [Local](#local)
    - [Container](#container)
  - [Testing](#testing)
  - [Configuration](#configuration)

## Available Commands

### Custom Bot Management

| Command                            | Description                            | Example Usage                                        |
| ---------------------------------- | -------------------------------------- | ---------------------------------------------------- |
| `!custom-bot <name> <personality>` | Create a custom bot with a personality | `!custom-bot alfred you are a proper british butler` |
| `!list-custom-bots`                | List all available custom bots         | `!list-custom-bots`                                  |
| `!delete-custom-bot <name>`        | Delete your custom bot (owner only)    | `!delete-custom-bot alfred`                          |

### Using Custom Bots

Once you create a custom bot, interact with it by prefixing your message with the bot name:

```text
!<bot_name> <your message>
```

**Example:**

1. Create a bot: `!custom-bot alfred you are a proper british butler`
2. Use the bot: `alfred Could you fetch me some tea?`
3. The bot will respond in character as a British butler

### Text-to-Speech

| Command                    | Description                             | Example Usage                   |
| -------------------------- | --------------------------------------- | ------------------------------- |
| `!speak <text>`            | Convert text to speech (MP3 attachment) | `!speak hello world`            |
| `!speak <bot_name> <text>` | Have a custom bot respond and speak     | `!speak alfred what time is it` |

### Image Commands

| Command      | Description                          | Example Usage                              |
| ------------ | ------------------------------------ | ------------------------------------------ |
| `!doodlebob` | Generate an image from a text prompt | `!doodlebob a cat sitting on the moon`     |
| `!retcon`    | Edit an attached image with text     | `!retcon <image attachment> Make it sunny` |

### Bot Conversations

| Command                                | Description                                 | Example Usage                                    |
| -------------------------------------- | ------------------------------------------- | ------------------------------------------------ |
| `!talkforme <bot1> <bot2> <n> <topic>` | Have two bots discuss a topic for n replies | `!talkforme alfred jarvis 4 the meaning of life` |

### Chat History

| Command               | Description                           | Example Usage     |
| --------------------- | ------------------------------------- | ----------------- |
| `!history <bot_name>` | View the chat history of a custom bot | `!history alfred` |

## Features

- **Long-term chat history storage**: Persistent storage of all bot interactions in SQLite
- **RAG-based context retrieval**: Smart retrieval of relevant conversation history using vector embeddings
- **Custom bots**: Create unlimited bots with unique personalities
- **Text-to-speech**: Kokoro TTS engine converts bot responses to MP3 audio
- **Image generation**: Generate images from text prompts via OpenAI-compatible API
- **Image editing**: Edit uploaded images with text instructions
- **Bot conversations**: Two custom bots can discuss a topic autonomously
- **Chat history**: View the full conversation history of any custom bot with `!history`
- **Automatic message cleanup**: Configurable limits on stored messages

## Setup

### Prerequisites

- Python 3.13 or higher
- [uv](https://docs.astral.sh/uv/) package manager
- Discord bot token
- OpenAI-compatible API endpoints (for chat, embeddings, and image generation)

### Environment Variables

Create a `.env` file with the following variables:

```bash
# Discord Bot Token (required)
DISCORD_TOKEN=your_discord_bot_token

# Chat/Completion API (required)
CHAT_ENDPOINT=https://your-api.com/v1
COMPLETION_ENDPOINT=https://your-api.com/v1
CHAT_ENDPOINT_KEY=your_api_key
COMPLETION_ENDPOINT_KEY=your_api_key
CHAT_MODEL=your_model_name
COMPLETION_MODEL=your_model_name

# Image Generation (required)
IMAGE_GEN_ENDPOINT=https://your-api.com/v1
IMAGE_EDIT_ENDPOINT=https://your-api.com/v1
IMAGE_GEN_ENDPOINT_KEY=your_api_key
IMAGE_EDIT_ENDPOINT_KEY=your_api_key
IMAGE_GEN_MODEL=gen
IMAGE_EDIT_MODEL=edit

# Embedding API (required)
EMBEDDING_ENDPOINT=https://your-api.com/v1
EMBEDDING_ENDPOINT_KEY=your_api_key
EMBEDDING_MODEL=your_embed_model

# Optional: TTS Configuration
TTS_MODEL_PATH=kokoro-v1.0.onnx
TTS_VOICES_PATH=voices-v1.0.bin
TTS_VOICE=af_sarah
TTS_SPEED=1.0

# Optional: Database/Chat Settings
DB_PATH=chat_history.db
MAX_COMPLETION_TOKENS=1000
MAX_HISTORY_MESSAGES=1000
SIMILARITY_THRESHOLD=0.7
TOP_K_RESULTS=5
```

### Installation

1. Clone the repository and sync dependencies:

    ```bash
    uv sync
    ```

2. Ensure the TTS model files are present in the project root:

   - `kokoro-v1.0.onnx`
   - `voices-v1.0.bin`

### Running the Bot

```bash
uv run python -m vibe_bot.main
```

## How It Works

### Database Structure

The system uses SQLite with three tables:

1. **chat_messages**: Stores message metadata
    - `message_id`, `user_id`, `username`, `content`, `bot_name`, `timestamp`, `channel_id`, `guild_id`

2. **message_embeddings**: Stores vector embeddings for RAG
   - `message_id` (PK), `embedding` (binary blob of float32 values)

3. **custom_bots**: Stores custom bot configurations
   - `bot_name` (PK), `system_prompt`, `created_by`, `created_at`, `is_active`

### RAG Process

1. When a message is sent to a custom bot, it's stored in `chat_messages`
2. An embedding is generated via the configured embedding API and stored in `message_embeddings`
3. When a new message is sent:
   - The system retrieves recent messages from the same user
   - It searches for semantically similar messages using cosine similarity on embeddings
   - Relevant context (user + bot message pairs) is prepended to the prompt
   - The LLM generates a response with awareness of past conversations

## File Structure

```text
vibe_discord_bots/
├── vibe_bot/
│   ├── __init__.py            # Package marker
│   ├── main.py                # Main bot application (commands, event handlers)
│   ├── config.py              # Environment variable loading and validation
│   ├── database.py            # SQLite database with RAG + CustomBotManager
│   ├── llama_wrapper.py       # OpenAI-compatible API wrappers (chat, images, embeddings)
│   ├── tts.py                 # Kokoro TTS engine
│   └── tests/
│       ├── conftest.py        # Shared test fixtures
│       ├── test_main.py       # Bot command tests
│       ├── test_config.py     # Config loading tests
│       ├── test_database.py   # Database + CustomBotManager tests
│       ├── test_llama_wrapper.py  # API wrapper tests
│       └── test_tts.py        # TTS engine tests
├── pyproject.toml             # Project dependencies (uv)
├── uv.lock                    # Locked dependency versions
├── .env                       # Environment variables
├── kokoro-v1.0.onnx           # Kokoro TTS model
├── voices-v1.0.bin            # Kokoro voice definitions
├── Containerfile              # Podman/Docker build file
└── README.md                  # This file
```

## Building

### Local

```bash
# Sync dependencies
uv sync

# Run the bot
uv run python -m vibe_bot.main
```

### Container

```bash
# Build the container image
podman build -t vibe-bot:latest .

# Run with environment file
podman run --env-file .env localhost/vibe-bot:latest
```

## Testing

Run the full test suite:

```bash
uv run pytest vibe_bot/tests/ -v
```

Run linters:

```bash
# Ruff (linter + formatter)
uv run ruff check vibe_bot/

# Mypy (type checking)
uv run mypy vibe_bot/

# Pyright (type checking)
uv run pyright vibe_bot/

# Black (formatter check)
uv run black --check vibe_bot/
```

## Configuration

| Variable                | Default            | Description                           |
| ----------------------- | ------------------ | ------------------------------------- |
| `DISCORD_TOKEN`         | *(required)*       | Discord bot authentication token      |
| `CHAT_ENDPOINT`         | *(required)*       | OpenAI-compatible chat API URL        |
| `CHAT_MODEL`            | *(required)*       | Model name for chat completions       |
| `IMAGE_GEN_ENDPOINT`    | *(required)*       | Image generation API URL              |
| `IMAGE_EDIT_ENDPOINT`   | *(required)*       | Image editing API URL                 |
| `EMBEDDING_ENDPOINT`    | *(required)*       | Embedding API URL                     |
| `EMBEDDING_MODEL`       | *(required)*       | Model name for text embeddings        |
| `MAX_COMPLETION_TOKENS` | `1000`             | Max tokens in LLM responses           |
| `MAX_HISTORY_MESSAGES`  | `1000`             | Max messages kept in the database     |
| `SIMILARITY_THRESHOLD`  | `0.7`              | Min cosine similarity for RAG context |
| `TOP_K_RESULTS`         | `5`                | Number of similar messages retrieved  |
| `TTS_MODEL_PATH`        | `kokoro-v1.0.onnx` | Path to Kokoro ONNX model file        |
| `TTS_VOICES_PATH`       | `voices-v1.0.bin`  | Path to Kokoro voices binary file     |
| `TTS_VOICE`             | `af_sarah`         | Default voice for TTS                 |
| `TTS_SPEED`             | `1.0`              | Speech speed multiplier               |
| `DB_PATH`               | `chat_history.db`  | SQLite database file path             |