|
1 | | -# Juanito - Tu Bot de Telegram con IA |
2 | | - |
3 | | -Juanito es un bot de Telegram avanzado que utiliza modelos de IA locales (Ollama + Whisper) para interactuar contigo de múltiples formas. |
4 | | - |
5 | | -## Características |
6 | | - |
7 | | -* **Chat Inteligente**: Conversa con naturalidad usando modelos como `qwen` o `llama`. |
8 | | -* **Visión Artificial**: Envíale una foto y te dirá lo que ve (usando `llava`). |
9 | | -* **Audio a Texto**: Envíale una nota de voz y te responderá por escrito (usando `whisper`). |
10 | | -* **Personalidad Dinámica**: Juanito tiene estados de ánimo cambiantes (sarcástico, eufórico, vago...). |
11 | | -* **Memoria**: Recuerda el contexto de la conversación (hasta 10 mensajes). |
12 | | - |
13 | | -## Requisitos Previos |
14 | | - |
15 | | -1. **Python 3.8+** |
16 | | -2. **Ollama**: Debes tener [Ollama](https://ollama.com/) instalado y corriendo. |
17 | | - * Modelos sugeridos: `ollama pull qwen2.5:7b` (chat) y `ollama pull llava` (visión). |
18 | | -3. **FFmpeg**: Necesario para procesar audio. |
19 | | - * Linux (Debian/Ubuntu): `sudo apt install ffmpeg` |
20 | | - * Windows: Descargar e instalar FFmpeg y añadirlo al PATH. |
21 | | -4. **Telegram**: Debes tener una cuenta de Telegram y un bot creado con @BotFather. |
22 | | - |
23 | | -## Instalación |
24 | | - |
25 | | -1. Clona este repositorio o descarga los archivos. |
26 | | -2. Instala las dependencias de Python: |
27 | | - ```bash |
28 | | - pip install -r requirements.txt |
29 | | - ``` |
30 | | -3. Configura tus variables de entorno: |
31 | | - * Crea un archivo `.env` basado en `.env.example`. |
32 | | - * Añade tu `TELEGRAM_TOKEN` (consíguelo con @BotFather). |
33 | | - * Ajusta los nombres de tus modelos de Ollama si es necesario. |
34 | | - |
35 | | -## Uso |
36 | | - |
37 | | -1. Ejecuta el bot: |
38 | | - ```bash |
39 | | - python Telegram_AI_bot.py |
40 | | - ``` |
41 | | -2. Abre Telegram y busca a tu bot. |
42 | | -3. Comandos disponibles: |
43 | | - * `/start`: Inicia la conversación. |
44 | | - * `/mood`: Consulta o cambia el humor de Juanito. |
45 | | - * `/clear`: Borra la memoria de la conversación actual. |
46 | | - * `/help`: Muestra la ayuda. |
47 | | - |
48 | | -## Estructura del Proyecto |
49 | | - |
50 | | -* `Telegram_AI_bot.py`: Código principal del bot. |
51 | | -* `.env`: Configuración y secretos (¡No compartir!). |
52 | | -* `requirements.txt`: Lista de librerías necesarias. |
53 | | -* `juanito_bot.db`: Base de datos SQLite (se crea automáticamente). |
54 | | - |
55 | | -## Prueba el bot en Telegram |
56 | | - |
57 | | -* @juanitoAI_el_bot |
58 | | - |
59 | | - |
60 | | -# Información adicional |
61 | | - |
| 1 | +# 🤖 JuanitoAI — Asistente de IA Multicanal y Modular |
| 2 | + |
| 3 | +JuanitoAI es un asistente de Inteligencia Artificial ("bot") diseñado inicialmente para Telegram, pero refactorizado con una arquitectura core modular para permitir la futura integración con otros canales. |
| 4 | + |
| 5 | +El bot combina potentes modelos de lenguaje a través de Ollama, capacidades de visión, reconocimiento de voz usando Whisper, y generación de imágenes mediante modelos libres. Todo gestionado con una base de datos local (SQLite) para mantener el contexto, el humor y la memoria semántica a largo plazo de los usuarios. |
| 6 | + |
| 7 | +## 🌟 Características Principales |
| 8 | + |
| 9 | +Juanito está diseñado para ser **privado**, **local** y altamente personalizable: |
| 10 | + |
| 11 | +- **💬 Modelos LLM Locales / Cloud (Ollama):** Configura cualquier modelo de texto soportado por Ollama para el razonamiento principal. |
| 12 | +- **👁️ Visión Artificial:** Analiza fotos mediante un modelo de visión (como LLaVA) para interpretar imágenes y responder sobre ellas. |
| 13 | +- **🎤 Reconocimiento de Voz (Whisper):** Transcripción local de notas de voz. Si el audio es excesivamente largo (+1 minuto), genera un resumen ejecutivo automático. |
| 14 | +- **🧠 Memoria y Contexto Persistente:** Utiliza SQLite para el historial de la conversación. Incorpora un sistema de "humor" cambiante y una **memoria semántica** que extrae hechos biográficos del usuario en segundo plano para personalizar futuras respuestas. |
| 15 | +- **🎨 Generación de Imágenes Fotorealistas:** Genera imágenes directamente en la conversación apoyándose en la API de HuggingFace Inferencia (FLUX / SDXL). |
| 16 | +- **📝 Sistema de Notas y Recordatorios:** Herramientas de productividad para guardar apuntes (`/nota`) y programar avisos temporales asíncronos (`/remind`). |
| 17 | +- **🌐 Investigación Web Profunda:** Dos modos operativos: búsqueda rápida (`/search`) e investigación profunda (`/deepsearch`), donde un agente autónomo descarga webs enteras y extrae bibliografía real. |
| 18 | +- **📚 Soporte de Documentos:** Lee y contesta sobre archivos de texto planos (`.txt`, `.md`, `.csv`). |
| 19 | +- **🛡️ Seguridad y Rate Limiting:** Soporte integrado de "whitelists" de usuarios permitidos, límites de mensajes por minuto para evitar abusos, y roles de administrador. |
| 20 | + |
| 21 | +--- |
| 22 | + |
| 23 | +## 🏗️ Arquitectura (Fila Modular) |
| 24 | + |
| 25 | +El proyecto separa de forma estricta la lógica agnóstica de los adaptadores específicos de cada red social. |
| 26 | + |
| 27 | +```text |
| 28 | +juanitoAI/ |
| 29 | +├── core/ # 🧠 Lógica central (Agnóstica a plataformas) |
| 30 | +│ ├── config.py # Variables de entorno y logging |
| 31 | +│ ├── database.py # Gestión SQLite (historial, notas, perfiles) |
| 32 | +│ ├── llm.py # Wrapper para Ollama AsyncClient |
| 33 | +│ ├── speech_to_text.py # Wrapper para el modelo Whisper local |
| 34 | +│ ├── web_search.py # Motor de búsquedas simples y profundas |
| 35 | +│ ├── models.py # Clases de dominio |
| 36 | +│ └── services/ |
| 37 | +│ ├── conversation.py # Orquestador del pipeline de chat |
| 38 | +│ ├── image_generation.py # Gestor multiproveedor de imágenes HF |
| 39 | +│ ├── scheduler.py # Demon de recordatorios en segundo plano |
| 40 | +│ ├── semantic_memory.py # Extracción periódica de hechos de usuarios |
| 41 | +│ └── monitoring.py # Stats del servidor (RAM, CPU, Disco) |
| 42 | +│ |
| 43 | +├── channels/ # 🔌 Adaptadores para canales de chat |
| 44 | +│ ├── telegram/ # Cliente nativo de Telegram |
| 45 | +│ │ ├── handlers.py # Controladores de comandos puros |
| 46 | +│ │ └── mapper.py # Serializador de Telegram a core.Message |
| 47 | +│ |
| 48 | +└── Telegram_AI_bot.py # 🚀 Entrypoint principal y orquestador |
| 49 | +``` |
| 50 | + |
| 51 | +--- |
| 52 | + |
| 53 | +## 🛠️ Instalación y Requisitos |
| 54 | + |
| 55 | +Para correr Juanito, es recomendable usar un entorno virtual para evitar conflictos de dependencias. |
| 56 | + |
| 57 | +### 1. Requisitos previos |
| 58 | +- **Python 3.9+** |
| 59 | +- **Ollama** instalado y ejecutándose localmente o accesible vía red. |
| 60 | +- **FFmpeg** (requerido por Whisper para procesar los audios): |
| 61 | + - Ubuntu/Debian: `sudo apt update && sudo apt install ffmpeg` |
| 62 | + - macOS: `brew install ffmpeg` |
| 63 | + |
| 64 | +### 2. Entorno virtual e Instalación |
| 65 | +```bash |
| 66 | +# Crear entorno virtual |
| 67 | +python3 -m venv venv |
| 68 | +source venv/bin/activate |
| 69 | + |
| 70 | +# Instalar dependencias |
| 71 | +pip install -r requirements.txt |
| 72 | +``` |
| 73 | + |
| 74 | +<<<<<<< Updated upstream |
62 | 75 | * Creado por David Carreres Gómez. |
63 | 76 | * Fecha: 19/02/2026 |
64 | 77 | * Versión: 1.0 (Prototipo) |
65 | 78 | * Licencia: GPL-3.0 |
| 79 | +======= |
| 80 | +### 3. Configuración (`.env`) |
| 81 | +Antes de iniciar, debes preparar tus API keys. Copia el archivo de ejemplo: |
| 82 | +```bash |
| 83 | +cp ejemplo.env .env |
| 84 | +nano .env |
| 85 | +``` |
| 86 | +_(Ver la sección de Variables de Entorno)_. |
| 87 | + |
| 88 | +### 4. Lanzamiento |
| 89 | +```bash |
| 90 | +# Iniciar el bot de forma normal dentro de una screen/tmux |
| 91 | +python Telegram_AI_bot.py |
| 92 | +``` |
| 93 | + |
| 94 | +--- |
| 95 | + |
| 96 | +## ⚙️ Variables de Entorno (`.env`) |
| 97 | + |
| 98 | +| Variable | Descripción | Ejemplo | |
| 99 | +|----------|-------------|---------| |
| 100 | +| `TELEGRAM_TOKEN` | Tu token del BotFather de Telegram. | `123456...` | |
| 101 | +| `OLLAMA_MODEL_CHAT` | Modelo principal para texto. | `kimi-k2.5:cloud` | |
| 102 | +| `OLLAMA_MODEL_VISION` | Modelo auxiliar para imágenes. | `gemma3:27b-cloud` | |
| 103 | +| `WHISPER_MODEL_SIZE` | Tamaño del modelo STT (tiny, base, small...). | `base` | |
| 104 | +| `DB_PATH` | Ruta a la base de datos local SQLite. | `juanito_bot.db` | |
| 105 | +| `ALLOWED_USER_IDS` | IDs de Telegram permitidos (separados por coma). Vacío = Abierto a todos. | `1234,9876` | |
| 106 | +| `ADMIN_USER_IDS` | IDs o **@usernames** de administradores. | `@admin,123` | |
| 107 | +| `RATE_LIMIT` | Control antispam:`RATE_LIMIT_MESSAGES` / `RATE_LIMIT_WINDOW` (msgs/segs) | `20`, `60` | |
| 108 | +| `HF_API_TOKEN` | Token gratuito de lectura de HuggingFace para generación de imágenes (hf_...). | `hf_xxxxx...` | |
| 109 | + |
| 110 | +--- |
| 111 | + |
| 112 | +## 🤖 Comandos y Capacidades |
| 113 | + |
| 114 | +### Comandos Generales |
| 115 | +- `/start` - Despierta al bot y muestra el mensaje inicial literario. |
| 116 | +- `/help` - Despliega el menú categorizado de ayuda funcional. |
| 117 | +- `/clear` - Borra el historial conversacional y de sesión del usuario. |
| 118 | +- `/mood` y `/mood <estado>` - Visualiza o inyecta a la fuerza una personalidad temporal. |
| 119 | +- `/img <prompt>` - Traduce tu prompt, procesa la solicitud con FLUX/SDXL, y manda una imagen generada. |
| 120 | +- `/remind <minutos> <tarea>` - Encola un trabajo asíncrono para ser invocado N minutos después en el chat. |
| 121 | +- `/nota <apunte>` - Escribe silenciosamente una nota persistente. |
| 122 | +- `/notas` - Recupera la lista completa de apuntes manuales para lectura. |
| 123 | +- `/search <texto>` - Utiliza el API de DuckDuckGo para recuperar un extracto flash web. |
| 124 | +- `/deepsearch <consulta>` - Detona un scraping pasivo; el bot descarga múltiples artículos crudos, los lee mediante LLM y emite una investigación citada. |
| 125 | + |
| 126 | +### Comandos de Administración |
| 127 | +- `/vps` - Analiza el uso de CPU, RAM Swap y FS Disk del host. |
| 128 | +- `/models` - Hace ping al servidor Ollama devolviendo el listado bruto JSON de pesos. |
| 129 | + |
| 130 | +### Tareas en Segundo Plano (Sin comandos explícitos) |
| 131 | +- **Extracción Biográfica (Memoria Semántica):** Juanito captura sentencias factuales sobre el interlocutor en _background_ cada cierto número de turnos. Este compendio se inyecta pasivamente en prompts futuros. |
| 132 | +- **Resumidor Transcriptor:** Audios que superen el límite sintáctico de tokens tras pasar por el pipe de Whisper son cortocircuitados hacia un sub-agente dedicado que esquematiza la información del audio, previniendo el desbordamiento conversacional. |
| 133 | + |
| 134 | +## 📝 Desarrollador |
| 135 | + |
| 136 | +Creado y diseñado por **David Carreres Gómez**. |
| 137 | +Arquitectura Final y Refactor Modular completado en 2026. |
| 138 | +>>>>>>> Stashed changes |
0 commit comments