README.md

---
title: Edullm
emoji: ⚡
colorFrom: indigo
colorTo: green
sdk: docker
pinned: false
license: mit
---

# 📚 GEN\_EDU\_IA: Sistema RAG Educativo con LLM y FAISS

**GEN\_EDU\_IA** es una solución integral que combina un pipeline RAG (Retrieval-Augmented Generation) con modelos LLM, gestión de vectores mediante FAISS y un bot de Telegram interactivo. Este sistema permite generar automáticamente materiales pedagógicos a partir de texto o imágenes, entregando el resultado en formato DOCX listo para ser utilizado por docentes.

---

## 🚀 Características Principales

* ⚡ **Pipeline RAG**: Integración de recuperación de contexto con generación automática usando LLM.
* 🤖 **Bot de Telegram**: Interfaz conversacional para docentes, soporta texto e imágenes.
* 📄 **Conversión Automática**: Generación de documentos en formato DOCX desde Markdown.
* 🗂️ **Gestión de Vectorstore**: Indexación eficiente de documentos educativos con FAISS.
* 📝 **Soporte Multimodal**: Procesamiento tanto de texto como de imágenes.

---

## 📂 Estructura del Proyecto

```
GEN_EDU_IA/
├── config/                # Configuración (.env, prompts)
├── core/                  # Lógica principal del sistema
│   ├── integrations/      # Integraciones (Bot, conversión DOCX)
│   ├── llm/               # Gestión del modelo LLM
│   ├── pipeline/          # Pipeline RAG
│   └── vectorstore/       # Gestión de FAISS
├── database/              # Almacenamiento del índice FAISS
│   └── edullm_store/      # Índice vectorial preconstruido
├── docs/                  # Documentación y materiales educativos
├── logs/                  # Registros del sistema
├── scripts/               # Scripts de ejecución
├── tests/                 # Pruebas unitarias
├── Dockerfile            # Configuración de Docker
├── requirements.txt      # Dependencias de Python
├── main.py              # Lanzador principal del sistema
└── README.md            # Documentación del proyecto
```

---

## ⚙️ Requisitos Previos

### Opción 1: Instalación Local
* **Python 3.11+**
* **pip** instalado
* **Pandoc** instalado
* Instalación de `uv` para una gestión eficiente de dependencias:
```bash
pip install uv
```

### Opción 2: Usando Docker
* **Docker** instalado
* **Docker Compose** (opcional)

---

## 📦 Instalación

### Opción 1: Instalación Local

1. Clona el repositorio:
```bash
git clone https://github.com/tu-usuario/gen-edu-ia.git
cd gen-edu-ia
```

2. Instala las dependencias:
```bash
uv sync
```

### Opción 2: Usando Docker

1. Construye la imagen:
```bash
docker build -t gen-edu-ia .
```

2. Ejecuta el contenedor:
```bash
docker run -d \
  --name gen-edu-ia \
  -v $(pwd)/config:/app/config \
  -v $(pwd)/database:/app/database \
  -v $(pwd)/docs:/app/docs \
  -v $(pwd)/logs:/app/logs \
  gen-edu-ia
```

---

## 🚨 Configuración

1. Copia el archivo de ejemplo y configura las variables:
```bash
cp config/.env.example config/.env
```

2. Edita el archivo `config/.env` con tus credenciales:

```dotenv
# ==========================================
# 🔑 CONFIGURACIÓN DEL BOT DE TELEGRAM
# ==========================================
TELEGRAM_TOKEN=your_telegram_bot_token

# ==========================================
# 🤖 CONFIGURACIÓN DEL MODELO LLM
# ==========================================
LLM_MODEL_NAME=gpt-3.5-turbo
LLM_API_KEY=your_openai_api_key
LLM_BASE_URL=https://api.openai.com/v1

# ==========================================
# 📚 CONFIGURACIÓN DEL VECTORSTORE
# ==========================================
VECTORSTORE_PATH=docs/
VECTORSTORE_NAME=edullm_store

# ==========================================
# 📝 CONFIGURACIÓN DE PROMPTS
# ==========================================
PATH_SYSTEM_PROMPT=config/prompt_system.txt

# ==========================================
# 🔄 CONFIGURACIÓN DE EMBEDDINGS
# ==========================================
MODEL_EMBEDDINGS=sentence-transformers/distiluse-base-multilingual-cased
```

3. Asegúrate de tener:
   - Un token válido de Bot de Telegram (obtenido de @BotFather)
   - Una API key válida para el servicio LLM
   - El archivo `prompt_system.txt` en la carpeta `config/`
   - Documentos en la carpeta `docs/` o un índice preconstruido en `database/edullm_store/`

---

## 🚀 Ejecución del Proyecto

### Opción 1: Local
```bash
uv run main.py
```

### Opción 2: Docker
```bash
docker start gen-edu-ia
```

El sistema iniciará:
* 🤖 **Bot de Telegram listo para recibir mensajes**

---

## 🎯 Uso del Bot EduLLM

1. Abre Telegram y busca tu bot con el token configurado
2. Envía un texto descriptivo o una imagen (puede ser una foto de una pizarra)
3. El bot generará automáticamente un material educativo
4. Recibirás un botón para descargar el archivo en formato **DOCX**

### Comandos Disponibles
* `/start` - Inicia el bot y muestra el mensaje de bienvenida
* `/help` - Muestra la ayuda y los comandos disponibles
* `/about` - Muestra información sobre el sistema

---

## 🧪 Ejecución de Pruebas

```bash
uv run pytest
```

Esto mostrará un reporte detallado del estado de las pruebas y el porcentaje de cobertura.

---

## 📊 Tecnologías Utilizadas

* **Python 3.11**
* **Telegram Bot API**
* **LangChain & FAISS**
* **OpenAI / Groq API**
* **pypandoc** (Conversión Markdown → DOCX)
* **Loguru** (Logging avanzado)
* **Pytest** (Testing)
* **Docker** (Containerización)

---

## ✅ Estado del Proyecto

✔️ Versión estable funcional
✔️ Generación de materiales educativos validada
✔️ Integración completa entre RAG, LLM y el Bot de Telegram
✔️ Soporte para Docker

---

## 🚧 Próximas Mejoras

* Implementación de control de usuarios por roles
* Almacenamiento persistente de historial de materiales generados
* Dashboard web para administración
* Soporte para más formatos de exportación (PDF, HTML)
* Mejoras en la gestión de memoria y recursos
* Optimización del pipeline RAG

---

## 📝 Notas Adicionales

### Gestión de Memoria
El sistema está optimizado para funcionar con recursos limitados, pero se recomienda:
- Mínimo 2GB de RAM para el contenedor Docker
- 1GB de espacio en disco para la base de datos vectorial
- Conexión estable a Internet para las APIs

### Mantenimiento
* Los logs se almacenan en `logs/`
* La base de datos vectorial se mantiene en `database/edullm_store/`
* Los documentos procesados se almacenan en `docs/`

### Solución de Problemas
Si encuentras algún error:
1. Revisa los logs en `logs/`
2. Verifica las variables de entorno en `config/.env`
3. Asegúrate de que los servicios externos (Telegram, LLM API) estén disponibles
4. Comprueba que los volúmenes Docker estén correctamente montados