Lexis

λέξις — word, speech, reason.

A Twitch bot powered by a local LLM (llama.cpp or any OpenAI-compatible server). Responds to chat intelligently with conversational context and configurable cooldown.

Overview

Lexis connects to a Twitch channel and responds to user messages using a locally running LLM. It can be triggered in two ways:

• Command prefix: !bot <message>
• Mention: @lexis (or whatever the bot's configured name is)

The conversation maintains a limited (configurable) context for coherent responses.

Requirements

• Python 3.12+
• LLM server running (llama.cpp on port 8099 by default)
• Twitch application with OAuth credentials

Setup

1. Clone and install

cd lexis
uv venv
source .venv/bin/activate
uv pip install -r requirements.txt

2. Set up environment variables

cp .env.example .env

Fill in .env with your Client ID and Secret, follow the steps to get them:

1. Go to https://dev.twitch.tv/console
2. Click "Register Your Application"
3. Fill in:
   • Name: any name for your app
   • OAuth Redirect URLs: http://localhost:17563
   • Category: Chat Bot
   • Client Type: Confidential
4. Copy the Client ID
5. Click "New Secret" under Client Secret, then copy it

Then set TWITCH_BOT_USERNAME and TWITCH_BROADCASTER_ID.

3. Configure the bot

Copy and edit config/bot_config.json:

cp config/bot_config.json.example config/bot_config.json

{
  "bot_name": "your_bot_name",
  "channel_name": "your_channel_name",
  "command_prefix": "!bot",
  "cooldown_seconds": 10,
  "llm_server": {
    "host": "localhost",
    "port": 8099,
    "model": "your_model_name"
  },
  "chat_context": {
    "max_turns": 4,
    "max_response_length": 450
  }
}

4. OAuth authentication

python setup_oauth.py

This will open your browser for Twitch login. Tokens will be saved to config/oauth_tokens.json.

5. Start the LLM server

# Example with llama.cpp
llama-server -m models/your_model.gguf --port 8099

6. Start the bot

python main.py

Project structure

lexis/
├── main.py                  # Main entry point
├── setup_oauth.py           # OAuth authentication script
├── llm_client.py            # Client for the LLM server
├── prompt_manager.py        # Prompt and conversation history management
├── response_queue.py        # FIFO queue for sequential responses
├── requirements.txt         # Python dependencies
├── .env.example             # Environment variables template
├── utils/
│   ├── logger.py            # Logging configuration
│   └── oauth.py             # OAuth token management utilities
├── config/
│   ├── bot_config.json      # Bot configuration
│   ├── bot_config.json.example  # Configuration template
│   └── oauth_tokens.json    # OAuth tokens (auto-generated, git-ignored)
├── prompts/
│   ├── system_prompt.txt    # System prompt / bot personality
│   └── command_prompts/     # Templates for specific commands
└── logs/                    # Activity logs (git-ignored)

Customization

Change the personality

Edit prompts/system_prompt.txt to modify the bot's behavior and style.

Add commands

Create files in prompts/command_prompts/ with custom templates.

Conversational context

In bot_config.json, adjust:

• max_turns: number of context turns (default: 4)
• max_response_length: max tokens per response (default: 450)
• cooldown_seconds: pause between responses (default: 10)

Notes

• The bot handles requests via a FIFO queue to prevent overlapping responses
• Conversational history is kept in memory only (not persistent)
• The LLM server must expose an OpenAI-compatible API (/v1/chat/completions)

License

MIT