Improve AI assistant performance in group chats

[lechatg]

Enhance Conversation Management & Per-Group Bot Customization

Overview

This PR implements comprehensive bot enhancements focused on group/admin functionality, introducing customizable group personas, LangGraph-based conversation management, and improved user experience for community-focused features such as agent tools for RAG search group chat messages history.

---

Key Changes

1. 🎭 Group Persona System

Admins can now define custom bot personalities per group with instant updates (no redeployment needed). For use cases check Bot README.

How it works:

┌─────────────────────────────────────────────────────────────────┐
│                    ADMIN CONFIGURATION                          │
└─────────────────────────────────────────────────────────────────┘
                            ↓
              /groups → Group Settings → AI Assistant
                            ↓
              ┌──────────────────────────────┐
              │ Group Personality Prompt     │
              │ "Be enthusiastic about..."   │
              └──────────────────────────────┘
                            ↓
                    [Saved to Redis]
                            ↓
┌─────────────────────────────────────────────────────────────────┐
│                    BOT RESPONSE FLOW                            │
└─────────────────────────────────────────────────────────────────┘
                            ↓
              ┌──────────────────────────────┐
              │   User Message in Group      │
              └──────────────────────────────┘
                            ↓
              ┌──────────────────────────────┐
              │   Load Group Persona         │ ← From Redis/metadata
              └──────────────────────────────┘
                            ↓
              ┌──────────────────────────────┐
              │   System Prompt Builder      │
              │                              │
              │ Base Identity (Core Rules)   │
              │         +                    │
              │ Persona (Style Layer) ✨     │
              └──────────────────────────────┘
                            ↓
              ┌──────────────────────────────┐
              │   Safety Guardrails Check    │ ← Filters harmful instructions
              │   ✓ Ignore dangerous prompts │
              │   ✓ Maintain core identity   │
              └──────────────────────────────┘
                            ↓
              ┌──────────────────────────────┐
              │   LLM Agent (LangGraph)      │
              │   Responds with personality  │
              └──────────────────────────────┘
                            ↓
              ┌──────────────────────────────┐
              │   Group Chat Response        │
              │   (Styled per admin config)  │
              └──────────────────────────────┘
                            ↓
                          END

Group Admin View:

---

2. 🧠 LangGraph Architecture Migration

Context:
Following the repository-wide LangGraph migration strategy introduced in PR #13, this PR completes the Telegram bot integration with the Luka Agent framework. The bot maintains its own isolated lg_lukabot/ module to ensure standalone functionality while benefiting from the unified LangGraph architecture used across the platform.

Why isolated in the bot subproject?

• Standalone operation - Bot can run independently without web dependencies
• Clear boundaries - Telegram-specific logic separated from web implementation
• Easier testing - Isolated state management and tool configuration
• Gradual migration - Existing pydantic-ai handlers can coexist during transition

Key improvements: Eliminates manual Redis history management through automatic checkpointing, enables multi-turn tool execution loops, persists conversation state across restarts, unifies web and Telegram under a shared state schema, and provides built-in LangSmith observability.

Module Structure:

• lg_lukabot/ - Complete LangGraph integration
  • state.py - Agent state schema with conversation history
  • graph.py - Graph structure (agent → tools → workflow_update → END)
  • nodes.py - Graph nodes with persona injection & system prompt building
  • tools.py - LangChain tool wrappers (KB search, workflows, YouTube, etc.)
  • integration.py - Main agent execution with streaming support
  • checkpointer.py - Redis-based state persistence

---

3. 📚 Enhanced Knowledge Base Integration

Every group automatically becomes a searchable knowledge base. Now integrated with LangGraph for better context awareness.

Features:

• Natural language search: "Where was that coffee shop recommendation?"
• Time-based filters: "What exhibitions were discussed last week?"
• User filters: "What bugs did Sarah report?"
• Multi-group search across all accessible groups

---

4. ⚙️ Group Admin Controls

Fine-grained control over bot behavior in groups.

AI Assistant Modes:

• Answer All: Responds to every message (small teams/support channels)
• Mentions Only: Only responds when @mentioned (default, respectful)
• Silent: Indexes messages but doesn't respond (pure KB mode)

Moderation Tools:

• Auto-delete join/leave notifications
• Message indexing for searchable history
• Spam detection filters

---

5. 📦 Dependency Optimization

Removed:

• ❌ openai-whisper + torch - Unused dependencies (~2GB+ of unnecessary packages)

Added:

• ✅ langchain and langgraph packages

Result: Faster installation, smaller Docker images, no build toolchain required.

---

6. 📝 Comprehensive .env.example

• Clear configuration template with two deployment paths and inline documentation.
• Minimal setup consists of two required keys: BOT_TOKEN and OPENAI_API_KEY

---

7. 🐳 Docker Infrastructure Improvements

• Elasticsearch Integration: added Elasticsearch 8.11.0 to docker-compose.yml for Knowledge Base functionality

• Unique Service Naming: redis-sol-atlas-bot, elasticsearch-sol-atlas-bot to prevent conflicts when running multiple projects simultaneously

• Dockerfile Fix: changed CMD from python ./luka_bot/__main__.py to python -m luka_bot to resolve ModuleNotFoundError on container startup

---

8. 📖 Bot README Update with Real-World Use Cases

Added: Four detailed use cases showing what the bot can do:

1. Personal AI Assistant - ChatGPT in Telegram with conversation memory
2. Group Admin Controls - AI modes (Answer All/Mentions/Silent) + moderation tools
3. Group Persona System - Custom bot personalities with instant updates (no redeploy)
4. Knowledge Base Search - Natural language search across group message history

Quick Start redesign:

• Clear "Option A vs Option B" (local Python vs Docker)
• Service purpose explanations (Redis for FSM, Elasticsearch for KB)
• Minimal configuration requirements highlighted upfront

---

Checklist

• ✅ Tested bot running in local Python mode
• ✅ Tested bot running in in Docker mode
• ✅ Group persona setting and application
• ✅ AI Assistant group mode switching (Answer All / Mentions / Silent) by admin
• ✅ Message indexing in groups
• ✅ Admin moderation controls
• ✅ Verified Knowledge Base (tg messages history) search with filters
• ✅ Added tool filtering system
• ✅ Integrated LangGraph architecture
• ✅ Updated all handlers for LangGraph
• ✅ Removed unnecessary dependencies
• ✅ Updated bot README with clear use cases
• ✅ Fixed Docker deployment issues