first commit
This commit is contained in:
251
README.md
Normal file
251
README.md
Normal file
@@ -0,0 +1,251 @@
|
||||
# LLM Bot Framework
|
||||
|
||||
A template for building Discord bots powered by LLMs with natural language command parsing.
|
||||
|
||||
## Features
|
||||
|
||||
- **AI-Powered Parsing**: Uses LLMs to parse natural language into structured JSON with automatic retry and validation
|
||||
- **Module Registry**: Easily register domain-specific command handlers
|
||||
- **Flask API**: REST API with JWT authentication
|
||||
- **PostgreSQL**: Generic CRUD layer for any table
|
||||
- **Discord Bot**: Session management, login flow, background tasks
|
||||
- **Notifications**: Discord webhook + ntfy support out of the box
|
||||
- **Docker Ready**: Full docker-compose setup
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Copy environment config
|
||||
cp config/.env.example config/.env
|
||||
|
||||
# Edit with your values
|
||||
nano config/.env
|
||||
|
||||
# Start everything
|
||||
docker-compose up
|
||||
```
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
llm-bot-framework/
|
||||
├── api/
|
||||
│ ├── main.py # Flask app with auth routes
|
||||
│ └── routes/
|
||||
│ └── example.py # Example route module
|
||||
├── bot/
|
||||
│ ├── bot.py # Discord client
|
||||
│ ├── command_registry.py # Module registration
|
||||
│ └── commands/
|
||||
│ └── example.py # Example command module
|
||||
├── core/
|
||||
│ ├── postgres.py # Generic PostgreSQL CRUD
|
||||
│ ├── auth.py # JWT + bcrypt
|
||||
│ ├── users.py # User management
|
||||
│ └── notifications.py # Multi-channel notifications
|
||||
├── ai/
|
||||
│ ├── parser.py # LLM JSON parser
|
||||
│ └── ai_config.json # Model + prompts config
|
||||
├── scheduler/
|
||||
│ └── daemon.py # Background polling
|
||||
├── config/
|
||||
│ ├── schema.sql # Database schema
|
||||
│ └── .env.example # Environment template
|
||||
├── docker-compose.yml
|
||||
├── Dockerfile
|
||||
└── requirements.txt
|
||||
```
|
||||
|
||||
## Creating a Domain Module
|
||||
|
||||
### 1. Add Database Schema
|
||||
|
||||
Edit `config/schema.sql`:
|
||||
|
||||
```sql
|
||||
CREATE TABLE IF NOT EXISTS tasks (
|
||||
id UUID PRIMARY KEY,
|
||||
user_uuid UUID REFERENCES users(id) ON DELETE CASCADE,
|
||||
name VARCHAR(255) NOT NULL,
|
||||
completed BOOLEAN DEFAULT FALSE,
|
||||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
|
||||
);
|
||||
```
|
||||
|
||||
### 2. Create API Routes
|
||||
|
||||
Create `api/routes/tasks.py`:
|
||||
|
||||
```python
|
||||
import flask
|
||||
import sys, os
|
||||
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))))
|
||||
|
||||
import core.auth as auth
|
||||
import core.postgres as postgres
|
||||
import uuid
|
||||
|
||||
def register(app):
|
||||
@app.route('/api/tasks', methods=['GET'])
|
||||
def api_listTasks():
|
||||
header = flask.request.headers.get('Authorization', '')
|
||||
if not header.startswith('Bearer '):
|
||||
return flask.jsonify({'error': 'missing token'}), 401
|
||||
token = header[7:]
|
||||
|
||||
# Get user UUID from token
|
||||
from core.auth import decodeJwtPayload
|
||||
import json, base64
|
||||
payload = token.split('.')[1]
|
||||
payload += '=' * (4 - len(payload) % 4)
|
||||
decoded = json.loads(base64.urlsafe_b64decode(payload))
|
||||
user_uuid = decoded['sub']
|
||||
|
||||
tasks = postgres.select("tasks", {"user_uuid": user_uuid})
|
||||
return flask.jsonify(tasks), 200
|
||||
|
||||
@app.route('/api/tasks', methods=['POST'])
|
||||
def api_addTask():
|
||||
header = flask.request.headers.get('Authorization', '')
|
||||
if not header.startswith('Bearer '):
|
||||
return flask.jsonify({'error': 'missing token'}), 401
|
||||
token = header[7:]
|
||||
|
||||
data = flask.request.get_json()
|
||||
task = postgres.insert("tasks", {
|
||||
'id': str(uuid.uuid4()),
|
||||
'user_uuid': data['user_uuid'],
|
||||
'name': data['name'],
|
||||
})
|
||||
return flask.jsonify(task), 201
|
||||
```
|
||||
|
||||
Register it in `api/main.py`:
|
||||
|
||||
```python
|
||||
import api.routes.tasks as tasks_routes
|
||||
register_routes(tasks_routes)
|
||||
```
|
||||
|
||||
### 3. Create Bot Commands
|
||||
|
||||
Create `bot/commands/tasks.py`:
|
||||
|
||||
```python
|
||||
import sys, os
|
||||
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))))
|
||||
|
||||
from bot.command_registry import register_module
|
||||
import ai.parser as ai_parser
|
||||
|
||||
async def handle_task(message, session, parsed):
|
||||
action = parsed.get('action')
|
||||
token = session['token']
|
||||
user_uuid = session['user_uuid']
|
||||
|
||||
# Make API calls using the bot's apiRequest helper
|
||||
from bot.bot import apiRequest
|
||||
|
||||
if action == 'list':
|
||||
result, status = apiRequest('get', f'/api/tasks', token)
|
||||
if status == 200:
|
||||
lines = [f"- {t['name']}" for t in result]
|
||||
await message.channel.send("Your tasks:\n" + "\n".join(lines))
|
||||
else:
|
||||
await message.channel.send("Failed to fetch tasks.")
|
||||
|
||||
elif action == 'add':
|
||||
task_name = parsed.get('task_name')
|
||||
result, status = apiRequest('post', '/api/tasks', token, {
|
||||
'user_uuid': user_uuid,
|
||||
'name': task_name
|
||||
})
|
||||
if status == 201:
|
||||
await message.channel.send(f"Added task: **{task_name}**")
|
||||
else:
|
||||
await message.channel.send("Failed to add task.")
|
||||
|
||||
def validate_task_json(data):
|
||||
errors = []
|
||||
if 'action' not in data:
|
||||
errors.append('Missing required field: action')
|
||||
if data.get('action') == 'add' and 'task_name' not in data:
|
||||
errors.append('Missing required field for add: task_name')
|
||||
return errors
|
||||
|
||||
register_module('task', handle_task)
|
||||
ai_parser.register_validator('task', validate_task_json)
|
||||
```
|
||||
|
||||
### 4. Add AI Prompts
|
||||
|
||||
Edit `ai/ai_config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"prompts": {
|
||||
"command_parser": {
|
||||
"system": "You are a helpful assistant...",
|
||||
"user_template": "..."
|
||||
},
|
||||
"task_parser": {
|
||||
"system": "You parse task commands...",
|
||||
"user_template": "Parse: \"{user_input}\"\n\nReturn JSON with action (list/add/complete) and task_name."
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## AI Parser Usage
|
||||
|
||||
```python
|
||||
import ai.parser as ai_parser
|
||||
|
||||
# Basic usage
|
||||
parsed = ai_parser.parse(user_input, 'command_parser')
|
||||
|
||||
# With conversation history
|
||||
history = [("previous message", {"action": "add", "item": "test"})]
|
||||
parsed = ai_parser.parse(user_input, 'command_parser', history=history)
|
||||
|
||||
# Register custom validator
|
||||
ai_parser.register_validator('task', validate_task_json)
|
||||
```
|
||||
|
||||
## Notification Channels
|
||||
|
||||
```python
|
||||
import core.notifications as notif
|
||||
|
||||
# Set user notification settings
|
||||
notif.setNotificationSettings(user_uuid, {
|
||||
'discord_webhook': 'https://discord.com/api/webhooks/...',
|
||||
'discord_enabled': True,
|
||||
'ntfy_topic': 'my-alerts',
|
||||
'ntfy_enabled': True
|
||||
})
|
||||
|
||||
# Send notification
|
||||
settings = notif.getNotificationSettings(user_uuid)
|
||||
notif._sendToEnabledChannels(settings, "Task due: Buy groceries")
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `DISCORD_BOT_TOKEN` | Discord bot token |
|
||||
| `API_URL` | API URL (default: `http://app:5000`) |
|
||||
| `DB_HOST` | PostgreSQL host |
|
||||
| `DB_PORT` | PostgreSQL port |
|
||||
| `DB_NAME` | Database name |
|
||||
| `DB_USER` | Database user |
|
||||
| `DB_PASS` | Database password |
|
||||
| `JWT_SECRET` | JWT signing secret |
|
||||
| `OPENROUTER_API_KEY` | OpenRouter API key |
|
||||
| `OPENROUTER_BASE_URL` | OpenRouter base URL |
|
||||
| `AI_CONFIG_PATH` | Path to ai_config.json |
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
Reference in New Issue
Block a user