🤖LM Studio Telegram Bot [YAIS-NXZ] v2.0.3

Chatea con tus Modelos de Lenguaje (LLMs) directamente desde Telegram usando LM Studio.
Una interfaz de bot potente, eficiente y altamente configurable para LM Studio con persistencia completa, soporte de voz (STT/TTS) y mejoras UX.

🚀 Instalación Rapida (Windows)

La instalación ha sido completamente simplificada con un script Setup interactivo. No necesitas conocimientos técnicos avanzados.

Pre-requisitos

• LM Studio: Asegúrate de tener LM Studio instalado y el servidor local ejecutándose.
• Python: Instala Python 3.8+ y, durante la instalación, asegúrate de marcar la opción "Add Python to PATH".
• Git: Clona el repositorio usando Git.

Pasos de Instalación

1. Clona el repositorio:

   git clone https://github.com/xnexuzx/lmstudio-telegram-bot
   cd lmstudio-telegram-bot

2. Ejecuta el script de configuración interactivo: Haz doble clic en Setup.bat. Una ventana de la consola se abrirá y te guiará a través de todo el proceso:

   • Creará un entorno virtual (venv) si no existe.
   • Instalará todas las dependencias de Python desde requirements.txt.
   • Te hará preguntas sencillas para generar tu archivo .env y configurar modelos locales de audio:
     • [1/8] Token de tu bot de Telegram.
     • [2/8] Tu ID de usuario de Telegram numérico.
     • [3/8] URL de tu servidor LM Studio (por defecto: localhost).
     • [4/8] Nombre del modelo inicial por defecto.
     • [5/8] Clave de API de Exa Search (opcional).
     • [6/8] Configuración de Arranque Automático en Windows.
     • [7/8] Descarga e instalación del modelo STT (Canary-1B-v2 ~380 MB).
     • [8/8] Descarga e instalación del modelo TTS (Kokoro-82M v1.0 ~330 MB).

3. Inicia el bot: Una vez que Setup.bat termine, haz doble clic en start.bat. El bot se iniciará en segundo plano de forma silenciosa.

4. Detén el bot: Para detener el bot, simplemente ejecuta stop.bat.

---

✨ Características Principales

🎙️ Voz e Inteligencia de Audio Offline (STT / TTS)

• Speech-to-Text (STT) Multilingüe con Canary-1B-v2: Transcribe notas de voz y audios en más de 25 idiomas con normalización de audio a 16kHz y fallback seguro.
• Modo Solo Transcripción / Bloc de Notas (/transcript): Transcripción rápida de notas de voz sin invocar al LLM e ignorando mensajes de texto para usar el chat como bloc de notas personal, con botón [🤖 Send to AI] bajo demanda.
• Text-to-Speech (TTS) con Kokoro-82M: Síntesis de voz offline en CPU en formato nativo OGG Opus para Telegram, autodescarga de memoria tras inactividad y catálogo de 17 voces con soporte español e inglés (/voices).
• Control de Velocidad de Locución (0.6x - 1.2x): Selector interactivo de velocidad en /voices con opciones [0.6x] [0.8x] [1.0x] [1.1x] [1.2x], persistido en SQLite.
• Sanitización de Texto para Audio: El bot limpia automáticamente sintaxis Markdown, bloques de código, URLs y etiquetas antes de sintetizar, asegurando una lectura natural.
• AutoTTS: Modo automático para recibir notas de voz habladas con cada respuesta del asistente.

🔘 Botonera de Acciones Interactivas por Mensaje

• [↩️ Undo]: Elimina el último turno completo (mensaje del usuario, transcripción STT, respuesta de texto del bot y notas de voz generadas) de Telegram, de la memoria activa y de SQLite.
• [🔄 Retry]: Regenera la respuesta del asistente con confirmación interactiva de dos pasos (30s TTL), limpiando la respuesta y audios anteriores.
• [🔊 Listen]: Escucha la respuesta del asistente en una nota de voz nativa con indicador visual continuo ("grabando mensaje de voz...").

📝 Gestión Inteligente de Conversaciones

• Streaming de Respuestas: Simula una generación en tiempo real editando los mensajes a medida que se generan.
• Exportación Automática de Archivos: Si el LLM genera código extenso o etiquetas <file>, se extrae como archivo adjunto descargable.
• División Inteligente de Mensajes: Divide respuestas largas respetando etiquetas HTML y bloques de código.
• Control de Razonamiento / Thinking: Controla mediante el payload de LM Studio si los modelos de razonamiento (DeepSeek R1, QwQ) deben activar o desactivar su pensamiento interno.
• Múltiples Chats Independientes: Administra varias conversaciones simultáneamente.
• Chats Persistentes y Temporales: Elige entre guardar una conversación o tener un chat rápido y temporal.

🛡️ Experiencia de Usuario Mejorada

• Idioma Estándar (Inglés): Toda la interfaz de usuario (botones, mensajes de error, alertas) está estrictamente en inglés para prevenir problemas de internacionalización.
• Spinner Animado: Retroalimentación visual inmediata con SpinnerManager, con auto-limpieza ante errores y eliminación física de mensajes obsoletos de Telegram cuando el contenido se contrae.
• Mensajes de Error Específicos: Diferentes mensajes para 404, timeout, errores de servidor, etc.
• Validación de Imágenes: El bot verifica automáticamente si el modelo soporta visión antes de procesar fotos.
• Limpieza Automática de Memoria: Gestión inteligente de recursos para chats inactivos.

📄 Inyección Directa de Archivos y Documentos

• Procesamiento de Archivos y Código: Envía archivos de texto plano o código (.py, .js, .txt, .json, etc.) directamente al chat para que el bot los analice en su respuesta.
• Límite Dinámico por Contexto: El tamaño máximo admisible se calcula automáticamente reservando el 75% del context_length activo (ej. ~384 KB en 128k, ~12 KB en 4k).
• Filtrado Binario Seguro: Rechaza de forma segura ejecutables (.exe), imágenes o archivos binarios corruptos protegiendo la sesión del usuario.

🌐 Búsqueda Web con Exa (Admin)

• Búsqueda Web Autónoma: El LLM puede solicitar búsquedas web en tiempo real emitiendo tags <search>, que son interceptados automáticamente.
• Flujo de Confirmación: Los administradores aprueban o deniegan cada búsqueda con botones inline (✅ Allow / ❌ Deny).
• Toggle Global: Activa/desactiva la capacidad de búsqueda web desde /settings, con persistencia en base de datos.

📍 Ubicación y Contexto Temporal

• Comando /location: Configura tu ubicación y zona horaria compartiendo GPS nativo o escribiendo el nombre de tu ciudad.
• Metadatos de Entorno: El bot inyecta automáticamente [USER ENVIRONMENT] (nombre, idioma, ubicación, timezone) y marca de tiempo local en cada petición al LLM, sin contaminar el historial.
• Gestión Simple: Botón 🗑️ Remove Location para limpiar los datos en cualquier momento.

🎙️ Reconocimiento de Voz (Speech-to-Text)

• Transcripción Local de Notas de Voz: Envía notas de voz directamente en Telegram; el bot las transcribe en CPU usando NVIDIA Canary-1B-v2 cuantizado (INT8 ~797 MB) vía sherpa-onnx sin consumir VRAM de la GPU.
• Soporte para 25 Idiomas ISO: Detecta automáticamente el idioma de tu cliente de Telegram y normaliza variantes regionales (es-419, en-US, pt-BR, etc.) con fallback a inglés.
• Modo Solo Transcripción / Bloc de Notas (/transcript): Alterna temporalmente entre el modo de conversación con IA y el modo de transcripción limpia. En modo solo transcripción, entrega el texto en un bloque de cita <blockquote> limpio listo para copiar en 1 toque, ignorando los mensajes de texto convencionales para usar el chat como bloc de notas, con un botón interactivo [🤖 Send to AI] para consultar a la IA bajo demanda.
• Gestión Inteligente de RAM (TTL 10 min): Descarga automáticamente el modelo STT de la memoria RAM tras 10 minutos de inactividad de voz, liberando hasta 1 GB de memoria del sistema.
• Auto-Truncado Inteligente: Salvaguarda automáticamente el 75% del contexto activo con ratios calibrados por fuente si la nota de voz es muy extensa.
• ChatActions Nativas: Emisión de acciones de estado (typing..., uploading document...) en la barra superior de Telegram.

⚡ Rendimiento y Eficiencia

• Optimización de Producción (-O): Ejecución con Python en modo óptimo para silenciar aserciones y ahorrar memoria RAM.
• Micro-Optimizaciones Base:
  • Pre-compilación de Regex: Ahorra miles de ciclos de CPU compilando globalmente las expresiones de transformación Markdown.
  • Caché en RAM (@lru_cache): Minimiza brutalmente las lecturas al disco duro almacenando la validación de seguridad de los usuarios (allowlist).
• Optimizado con Long Polling: Consumo mínimo de CPU y red.
• Gestión de Timeouts Robusta: Previene conexiones colgadas y mejora la estabilidad.

🔧 Administración y Seguridad

• Gestión de Modelos Completa: Administra modelos directamente desde la interfaz del bot.
• Control de Acceso estricto: Sistema de lista blanca (allowlist) para usuarios autorizados.
• Personalización Persistente:
  • Prompts de Sistema: Personaliza la personalidad del bot. Los administradores pueden crear prompts y los usuarios pueden elegir entre ellas.
  • Selección de Modelo: Elige y guarda tu modelo de LM Studio preferido.
• Soporte para Grupos: Menciona al bot en un grupo para que responda en el hilo correspondiente.

---

👨‍💻 Comandos del Bot

Comandos para Todos los Usuarios (Autorizados)

• /start: Muestra el mensaje de bienvenida.
• /help: Muestra la lista de comandos disponibles.
• /transcript: Alterna entre el modo conversacional con IA y el modo solo transcripción (bloc de notas).
• /voices: Abre el catálogo de voces TTS, control de velocidad (0.6x - 1.2x) y activación de AutoTTS.
• /location: Configura tu ubicación y zona horaria para personalizar el contexto del LLM.
• /new: Inicia una nueva sesión limpia en RAM.
• /new_custom: Inicia una sesión temporal con un system prompt personalizado a introducir.
• /save: Guarda la conversación actual (incluyendo la system prompt) en la base de datos para continuarla en el futuro.
• /view_prompt: Permite visualizar el system prompt activo en la sesión actual.
• /prompts: Permite seleccionar un "system prompt" predeterminado. La selección es persistente e iniciará nuevos chats con esta personalidad.
• /chats: Abre el menú para gestionar tus conversaciones guardadas (cargar, eliminar).
• /retry: Regenera la última respuesta del asistente (descartando la anterior).
• /cancel: Detiene inmediatamente la generación de texto en curso.
• /export: Descarga todo el historial del chat activo en un archivo Markdown (.md).
• /history: Muestra el historial de la conversación activa.

Opciones Dinámicas de UI (Configurables en Settings)

• 🧠 Control de Razonamiento (Thinking): Con esta opción activada por el administrador, los modelos de razonamiento (como DeepSeek R1, QwQ, etc.) activan su proceso de pensamiento interno (chat_template_kwargs={"enable_thinking": True}). Si se desactiva, el bot fuerza reasoning_effort="none" para inferencias directas y veloces sin razonamiento extendido.

Notas de Persistencia

• Selección de Modelo: Tu modelo de LM Studio preferido se guarda automáticamente y se restaura al reiniciar el bot.
• Configuración Personal: Todos los ajustes (prompts, modelo seleccionado) se persisten en la base de datos.
• Historial de Chats: Puedes cambiar entre diferentes conversaciones y tu historial se mantiene intacto.

Comandos de Administrador

Los administradores (definidos en ADMIN_IDS) tienen acceso a comandos adicionales para gestionar el bot:

• /settings: Abre el menú principal de ajustes de administrador.
• /adduser <user_id> [user_name]: Añade un usuario a la lista de permitidos.
• /rmuser <user_id>: Elimina un usuario de la lista de permitidos.
• /listusers: Muestra todos los usuarios autorizados.

Menú de Ajustes de Administrador (/settings)

Desde este menú, los administradores pueden:

• Gestión de Modelos y Generación:
  • Cambiar el LLM activo (♻️ Switch LLM): Selector optimizado con callbacks compactos por índice para modelos de nombres largos, filtrando modelos no-chat (embeddings y proyectores visuales).
  • Ajustar Temperatura (🌡️ Temperature): Modificar la temperatura global de inferencia.
  • Ajustar Contexto (📏 Context Length): Definir la longitud de contexto (max_tokens) para las respuestas.
  • Toggle de Razonamiento (🧠 Thinking): Activar o desactivar la generación del proceso de razonamiento del modelo.
  • Toggle de Búsqueda Web (🌐 Exa Web Search): Activar o desactivar la capacidad del LLM para consultar la web en vivo (solo admins).
  • Reinicio Forzado (🔄 Force Restart): Reiniciar el bot de forma remota lanzando un daemon silencioso (pythonw.exe) con confirmación de seguridad en dos pasos.
• Administrar Prompts (⚙️ Manage Prompts):
  • Crear, ver y eliminar los prompts de sistema personalizados que todos los usuarios podrán seleccionar.
• Gestión de Usuarios (📋 Remove Users):
  • Ver la lista paginada de usuarios autorizados y revocarlos directamente desde la interfaz.

---

⚙️ Configuración de Variables de Entorno (.env)

Parámetro	Descripción	Requerido	Valor por Defecto	Ejemplo
TOKEN	El token de tu bot de Telegram.	Sí		123456:ABC-DEF123456
ADMIN_IDS	ID numérico del usuario administrador.	Sí		123456789
EXA_API_KEY	Clave de API de Exa para búsqueda web autónoma.	No		exa-xxxxxxxxxxxx
INITMODEL	El modelo que se cargará por defecto al iniciar el bot.	No	ornith-1.0-35b-heretic-mtp-apex	ornith-1.0-35b-heretic-mtp-apex
LMSTUDIO_BASE_URL	La URL o IP de tu servidor LM Studio. Si está en la misma máquina, localhost es suficiente.	No	localhost	192.168.1.100
LMSTUDIO_PORT	El puerto de tu servidor LM Studio.	No	1234	1234
TIMEOUT	Tiempo máximo en segundos para esperar una respuesta de la API.	No	3000	3000
LOG_LEVEL	Nivel de logging del bot.	No	INFO	DEBUG
CANARY_MODEL_DIR	Directorio local de los binarios ONNX de Canary-1B-v2.	No	./models/canary-1b-v2	./models/canary-1b-v2
KOKORO_MODEL_DIR	Directorio local de los binarios ONNX de Kokoro-82M v1.0.	No	./models/kokoro	./models/kokoro

---

🏗️ Mejoras Técnicas (v2.0.0 & v2.0.1)

El salto a las versiones 2.0.x incluye una migración arquitectónica masiva hacia LM Studio y refactorizaciones críticas que elevan el bot a un estándar de producción:

Estructura y Organización

• Paquete bot/utils/ reestructurado: Módulos separados para diferentes funcionalidades (document.py, web_search.py, spinner.py, text.py, image.py).
• Clase SpinnerManager: Gestor centralizado de indicadores de progreso con limpieza automática y parametrización de estados aislados por usuario.
• Separación de responsabilidades: Código más modular y mantenible.

Calidad del Código

• Docstrings completas: Todas las funciones públicas incluyen documentación detallada.
• Type hints completos: Tipado fuerte en todo el código base sin fallos de NoneType.
• Logging estructurado: Reemplazo de print() por sistema de logging profesional.

Robustez y Concurrencia

• Aislamiento Anti-Spam (Queue Lock): Procesa peticiones de LM Studio estrictamente una a una, previniendo cuelgues del servidor. Rechaza de forma educada peticiones simultáneas del mismo usuario (Anti-Spam).
• Suite de Pruebas E2E (98 Tests): Integración masiva de tests automatizados (pytest) simulando concurrencia, resiliencia de red, formateo HTML severo, inyección de metadatos de ubicación, parsing de documentos, STT con Canary-1B-v2 en CPU, modo efímero /transcript, síntesis TTS con Kokoro-82M, generación real contra LM Studio y validación de autenticación.
• Manejo de errores mejorado: Captura y manejo específico de diferentes tipos de errores.

Refinamientos de Streaming

• Bugfix de Extracción de Código (Regex → rfind): Se eliminó una expresión regular codiciosa que cortaba prematuramente el texto del chat al confundir bloques de código ya cerrados con bloques activos. Sustituida por una búsqueda de índices exacta que evalúa únicamente el último bloque sin cerrar de forma quirúrgica.
• Limpieza de Mensajes Fantasma: El SpinnerManager ahora detecta cuándo el número de chunks activos disminuye (ej. al extraer un bloque gigante) y elimina físicamente los mensajes sobrantes de Telegram, evitando basura visual congelada en el chat.
• Corrección de Espaciado en Modelos de Razonamiento: Eliminado el doble salto de línea (\n\n) que aparecía entre el bloque <think> y la respuesta final del modelo.

---

🐳 Instalación con Docker (Avanzado)

Próximamente...

---

📄 Licencia

Este proyecto está bajo la Licencia MIT. Consulta el archivo LICENSE para más detalles.