🦙Ollama Telegram Bot [YAIS-NXZ] v1.0.5

Chatea con tus Modelos de Lenguaje (LLMs) directamente desde Telegram.
Una interfaz de bot potente, eficiente y altamente configurable para Ollama con persistencia completa y mejoras UX.

Nota sobre el Origen: Este es un fork del proyecto original rikkichy/ollama-telegram. El código ha sido refactorizado para mejorar la modularidad, añadir nuevas funciones y simplificar drásticamente la instalación en principalmente en Windows. Todo el crédito por el codigo base pertenece a rikkichy.

🚀 Instalación Rapida (Windows)

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

Pre-requisitos

• Ollama: Asegúrate de tener Ollama instalado y 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/ollama-telegram-bot
   cd ollama-telegram-bot

   (Reemplaza xnexuzx con tu nombre de usuario de GitHub si hiciste Fork).

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á 4 preguntas sencillas para generar tu archivo .env:
     • Token de tu bot de Telegram (obtenido de @BotFather).
     • Tu ID de usuario de Telegram (obtenido de @userinfobot).
     • URL de tu servidor Ollama (por defecto: localhost).
     • Modelo de Ollama por predeterminado al iniciar (por defecto: qwen3:4b-instruct).

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.

¡Listo! El bot está funcionando y listo para usar.

---

✨ Características Principales

🚀 Instalación y Configuración

• Instalación Guiada: Scripts interactivos que te configuran todo el entorno en minutos.
• Persistencia Completa: Tus selecciones (modelos, prompts, configuraciones) se guardan automáticamente y se restauran al reiniciar.

📝 Gestión Inteligente de Conversaciones

• Streaming de Respuestas: Simula una generación en tiempo real editando los mensajes a medida que se generan.
• División Inteligente de Mensajes: Divide automáticamente las respuestas largas manteniendo la coherencia.
• 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

• Spinner Animado Robusto: Indicador de progreso con limpieza automática en errores y estados por usuario.
• 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.

⚡ Rendimiento y Eficiencia

• Optimizado con Long Polling: Consumo mínimo de CPU y red.
• Gestión de Timeouts Robusta: Previene conexiones colgadas y mejora la estabilidad.
• Logging Estructurado: Sistema de registro profesional para monitoreo y depuración.

🔧 Administración y Seguridad

• Gestión de Modelos Completa: Administra modelos de Ollama (pull, rm) 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 Ollama 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.
• /prompts: Permite seleccionar un "system prompt" para cambiar la personalidad del bot. La selección es persistente y se guarda automáticamente.
• /chats: Abre el menú para gestionar tus conversaciones (crear, cambiar, eliminar).
• /reset: Limpia el historial de la conversación actual, volviéndola un chat temporal.
• /history: Muestra el historial de la conversación activa.

Notas de Persistencia

• Selección de Modelo: Tu modelo de Ollama 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.
• /pullmodel <model_name>: Descarga un modelo desde el registro de Ollama.

Menú de Ajustes de Administrador (/settings)

Desde este menú, los administradores pueden:

• Gestión de Modelos:
  • Cambiar el LLM activo: Seleccionar qué modelo de Ollama usar (se guarda como predeterminado para todos los usuarios).
  • Eliminar un LLM: Borrar un modelo del servidor de Ollama.
• Administrar Prompts:
  • Crear, ver y eliminar los prompts de sistema personalizados que todos los usuarios podrán seleccionar.
• Gestión de Usuarios:
  • Listar y Eliminar Usuarios: Ver la lista de usuarios autorizados y eliminarlos directamente desde un menú interactivo.

---

⚙️ 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
INITMODEL	El modelo de Ollama que se cargará por defecto al iniciar el bot.	No	qwen3:4b-instruct	mistral:latest
OLLAMA_BASE_URL	La URL o IP de tu servidor Ollama. Si está en la misma máquina, localhost es suficiente.	No	localhost	192.168.1.100
OLLAMA_PORT	El puerto de tu servidor Ollama.	No	11434	11434
TIMEOUT	Tiempo máximo en segundos para esperar una respuesta de Ollama.	No	3000	3000
LOG_LEVEL	Nivel de logging del bot.	No	INFO	INFO

---

🏗️ Mejoras Técnicas (v1.0.5)

La versión 1.0.5 incluye una refactorización completa que mejora significativamente la calidad y mantenibilidad del código:

Estructura y Organización

• Paquete bot/utils/ reestructurado: Módulos separados para diferentes funcionalidades.
• Clase SpinnerManager: Gestor centralizado de indicadores de progreso con limpieza automática.
• 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.
• Logging estructurado: Reemplazo de print() por sistema de logging profesional.

Robustez

• Manejo de errores mejorado: Captura y manejo específico de diferentes tipos de errores.
• Validación de entradas: Comprobaciones adicionales para mayor seguridad.
• Gestión de memoria: Limpieza automática de recursos para prevenir fugas.

---

🐳 Instalación con Docker (Avanzado)

Próximamente...

---

📄 Licencia

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