Upload 21 files

.gitattributes

@@ -33,3 +33,6 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+database/edullm_store/index.faiss filter=lfs diff=lfs merge=lfs -text
+docs/curriculo-nacional-de-la-educacion-basica.pdf filter=lfs diff=lfs merge=lfs -text
+docs/programa-curricular-educacion-primaria_compressed.pdf filter=lfs diff=lfs merge=lfs -text

Dockerfile

@@ -0,0 +1,32 @@
+# Usar Python 3.11 como base
+FROM python:3.11-slim
+
+# Instalar dependencias del sistema
+RUN apt-get update && apt-get install -y \
+    pandoc \
+    build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+# Establecer el directorio de trabajo
+WORKDIR /app
+
+# Copiar los archivos de requisitos primero para aprovechar la caché de Docker
+COPY requirements.txt .
+
+# Instalar dependencias de Python
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Crear estructura de directorios
+RUN mkdir -p config database/edullm_store docs logs
+
+# Copiar el archivo .env de ejemplo si existe
+COPY config/.env.example config/.env
+
+# Copiar el resto del código
+COPY . .
+
+# Asegurar que la base de datos exista
+RUN touch database/edullm_store/.gitkeep
+
+# Comando para ejecutar la aplicación
+CMD ["python", "main.py"] 

config/.env

@@ -0,0 +1,27 @@
+# ==========================================
+# 🔑 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

config/system_prompt_deco_v2.txt

@@ -0,0 +1,56 @@
+Generar únicamente materiales educativos alineados al CNEB, MBDD y MINEDU–Perú.
+
+1. **Entrega en Markdown limpio**
+
+* **Ficha**: Metadatos; Resumen; Desarrollo; Preguntas DECO; Conclusión; Recomendación; Instrumento\*
+* **Resumen temático**: Metadatos; Ideas clave (≥3); Desarrollo; Conclusión
+* **Banco de preguntas**: Metadatos; Preguntas DECO (≥10); Clave opcional
+* **Rúbrica/Lista**: Metadatos; Criterios; Niveles; Descriptores
+  \*Incluir solo si se solicita
+
+2. **Variables obligatorias** (si falta, solicitar):
+   Área curricular, Grado, Bimestre, Competencia, Capacidad, Desempeño esperado
+
+3. **Ejemplo (ficha)**
+
+```markdown
+## {{Título}}
+
+**Área:** {{}}  **Grado:** {{}}  **Bimestre:** {{}}  
+**Competencia:** {{}}  **Capacidad:** {{}}  **Desempeño:** {{}}
+
+### Resumen conceptual (60–100 palabras)
+
+### Ideas clave (≥3)
+- …
+- …
+- …
+
+### Desarrollo (contexto peruano)
+
+### Preguntas DECO:
+- Literal (3)  
+- Inferencial (≥5)  
+- Crítico (2)  
+- Integradora (si aplica)
+
+### Conclusión (≤40 palabras)
+
+### Recomendación (breve)
+
+### Instrumento (tabla Markdown, si solicitado)
+```
+
+4. **Tipos DECO**
+
+* Literal
+* Inferencial
+* Crítico
+* Integradora
+
+5. **Restricciones**
+
+* No temas médicos, legales o sensibles
+* Contexto peruano
+* Máx. 1500 palabras
+* Sin instrucciones técnicas ni comentarios meta

core/integrations/doc_converter.py

@@ -0,0 +1,98 @@
+# core/integrations/doc_converter
+import os
+import re
+import uuid
+import tempfile
+import pypandoc
+from loguru import logger
+from fastapi.responses import FileResponse
+
+# Control de descargas (máximo 2 por archivo)
+_descargas = {}
+
+
+def limpiar_lineas_hr(markdown_text: str) -> str:
+    """Reemplaza líneas horizontales '---' por saltos de línea."""
+    return re.sub(r"^\s*---\s*$", "\n", markdown_text, flags=re.MULTILINE)
+
+
+def normalizar_ecuaciones(md: str) -> str:
+    """Convierte ecuaciones LaTeX escapadas a formato estándar."""
+    md = re.sub(r"\\\[\s*(.*?)\s*\\\]", r"$$\1$$", md, flags=re.DOTALL)
+    md = re.sub(r"\\\(\s*(.*?)\s*\\\)", r"$\1$", md, flags=re.DOTALL)
+    return md
+
+
+def limpiar_backticks(markdown_text: str) -> str:
+    """
+    Elimina los backticks triples si encapsulan todo el contenido.
+    """
+    markdown_text = markdown_text.strip()
+    if markdown_text.startswith("```") and markdown_text.endswith("```"):
+        logger.info("🧹 Eliminando backticks triples de la respuesta LLM.")
+        return markdown_text[3:-3].strip()
+    return markdown_text
+
+
+def procesar_markdown(markdown_content: str) -> dict:
+    try:
+        # Limpieza previa del contenido
+        markdown_content = limpiar_backticks(markdown_content)
+        contenido_limpio = normalizar_ecuaciones(limpiar_lineas_hr(markdown_content))
+
+        uid = str(uuid.uuid4())
+        temp_dir = tempfile.gettempdir()
+        input_md = os.path.join(temp_dir, f"{uid}.md")
+        output_docx = os.path.join(temp_dir, f"{uid}.docx")
+
+        with open(input_md, "w", encoding="utf-8") as f:
+            f.write(contenido_limpio)
+
+        pypandoc.convert_file(
+            source_file=input_md,
+            to="docx",
+            outputfile=output_docx,
+            format="md",
+            extra_args=["--standalone"],
+        )
+
+        os.remove(input_md)
+        _descargas[uid] = 0
+
+        logger.success(f"✅ DOCX generado correctamente: {output_docx}")
+        return {"message": "Archivo DOCX generado exitosamente.", "file_id": uid}
+
+    except Exception as e:
+        logger.error(f"❌ Error al procesar Markdown: {e}")
+        return {"error": "Fallo en la conversión de Markdown a DOCX."}
+
+
+def gestionar_descarga(file_id: str):
+    """
+    Controla la descarga de archivos. Permite solo 2 descargas por archivo.
+    """
+    temp_dir = tempfile.gettempdir()
+    output_docx = os.path.join(temp_dir, f"{file_id}.docx")
+
+    if not os.path.exists(output_docx):
+        logger.warning(f"⚠️ Archivo no encontrado: {output_docx}")
+        return {"error": "El archivo no existe o fue eliminado.", "status": 404}
+
+    if file_id not in _descargas:
+        logger.warning(f"⚠️ ID inválido de descarga: {file_id}")
+        return {"error": "ID de archivo no válido.", "status": 400}
+
+    if _descargas[file_id] >= 2:
+        os.remove(output_docx)
+        del _descargas[file_id]
+        logger.info(f"🗑️ Archivo eliminado tras exceder descargas: {file_id}")
+        return {"error": "Límite de descargas alcanzado.", "status": 410}
+
+    _descargas[file_id] += 1
+    logger.info(f"⬇️ Descarga {_descargas[file_id]} de 2 para archivo: {file_id}")
+
+    return FileResponse(
+        path=output_docx,
+        filename="material_educativo.docx",
+        media_type="application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    )

core/integrations/telegram_bot.py

@@ -0,0 +1,237 @@
+# core/integrations/telegram_bot.py
+import os
+import re
+import tempfile
+import time
+
+import fitz  # PyMuPDF
+from docx import Document
+from dotenv import load_dotenv
+from telegram import InlineKeyboardButton, InlineKeyboardMarkup, InputFile, Update
+from telegram.ext import (
+    ApplicationBuilder,
+    CallbackQueryHandler,
+    CommandHandler,
+    ContextTypes,
+    MessageHandler,
+    filters,
+)
+
+from core.integrations.doc_converter import gestionar_descarga, procesar_markdown
+from core.logging.usage_logger import registrar_uso
+from core.pipeline.edullm_rag_pipeline import edullm_rag_pipeline
+
+# ==== CONFIGURACIÓN GENERAL ====
+load_dotenv(dotenv_path="config/.env")
+TELEGRAM_TOKEN = os.getenv("TELEGRAM_TOKEN")
+DOCX_FILENAME = "material_educativo.docx"
+FORMAT_WARNING_IMAGE = "assets/formatos_soportados.png"
+
+if not TELEGRAM_TOKEN:
+    raise ValueError("❌ TELEGRAM_TOKEN no está definido en las variables de entorno.")
+
+
+# ==== FUNCIONES AUXILIARES ====
+def extract_text_from_pdf(file_path):
+    text = ""
+    with fitz.open(file_path) as pdf:
+        for page in pdf:
+            text += page.get_text()
+    return text.strip()
+
+
+def extract_text_from_docx(file_path):
+    doc = Document(file_path)
+    return "\n".join(para.text for para in doc.paragraphs if para.text.strip())
+
+
+def extract_text_from_txt(file_path):
+    with open(file_path, "r", encoding="utf-8") as f:
+        return f.read().strip()
+
+
+def escape_markdown(text: str) -> str:
+    """
+    Escapa caracteres especiales para MarkdownV2 de Telegram.
+    """
+    escape_chars = r"_*[]()~`>#+-=|{}.!"
+    return re.sub(f"([{re.escape(escape_chars)}])", r"\\\1", text)
+
+
+def detectar_tipo_entrada(user_input) -> str:
+    if isinstance(user_input, str):
+        return "Texto"
+    elif isinstance(user_input, bytes):
+        return "Imagen"
+    else:
+        return "Otro"
+
+
+# ==== COMANDO /start ====
+async def start(update: Update, context: ContextTypes.DEFAULT_TYPE):
+    await update.message.reply_text(
+        "👋 Bienvenido a *EduLLM Bot*.\n\n"
+        "Acepto: *Texto*, *Imagen*, *PDF*, *DOCX* o *TXT*.\n"
+        "Generaré material educativo listo para descargar en DOCX.",
+        parse_mode="Markdown",
+    )
+
+
+# ==== MANEJO DE MENSAJES ====
+async def handle_message(update: Update, context: ContextTypes.DEFAULT_TYPE):
+    user_input = ""
+
+    try:
+        if update.message.text:
+            user_input = update.message.text
+
+        elif update.message.photo:
+            photo = update.message.photo[-1]
+            file = await photo.get_file()
+            with tempfile.NamedTemporaryFile(delete=False, suffix=".jpg") as temp_img:
+                await file.download_to_drive(temp_img.name)
+                with open(temp_img.name, "rb") as img_file:
+                    user_input = img_file.read()
+
+        elif update.message.document:
+            file = await update.message.document.get_file()
+            ext = update.message.document.file_name.split(".")[-1].lower()
+
+            with tempfile.NamedTemporaryFile(delete=False, suffix=f".{ext}") as tmp_doc:
+                await file.download_to_drive(tmp_doc.name)
+
+                if ext == "pdf":
+                    extracted_text = extract_text_from_pdf(tmp_doc.name)
+                elif ext == "docx":
+                    extracted_text = extract_text_from_docx(tmp_doc.name)
+                elif ext == "txt":
+                    extracted_text = extract_text_from_txt(tmp_doc.name)
+                else:
+                    await enviar_mensaje_formato_no_soportado(update)
+                    return
+
+                mensaje_texto = update.message.caption or ""
+                user_input = f"{mensaje_texto}\n\n{extracted_text}".strip()
+
+        elif update.message.audio or update.message.voice or update.message.video:
+            await update.message.reply_text(
+                "🎙️🎥 *Audios y videos no son compatibles.* Solo acepto texto, imágenes o documentos (PDF, DOCX, TXT).",
+                parse_mode="Markdown",
+            )
+            return
+
+        elif update.message.sticker:
+            await update.message.reply_text(
+                "🟢 Gracias por el sticker, pero necesito texto, imagen o documento educativo."
+            )
+            return
+
+        elif update.message.location:
+            await update.message.reply_text(
+                "📍 He recibido tu ubicación, pero solo trabajo con contenido educativo."
+            )
+            return
+
+        elif update.message.contact:
+            await update.message.reply_text(
+                "📞 Recibí un contacto, pero por favor envíame contenido académico (texto, imagen o documento)."
+            )
+            return
+
+        elif update.message.animation:
+            await update.message.reply_text(
+                "🎞️ Los GIFs no son compatibles. Por favor envía texto, imagen o documentos."
+            )
+            return
+
+        else:
+            await enviar_mensaje_formato_no_soportado(update)
+            return
+
+    finally:
+        for temp_var in ["temp_img", "tmp_doc"]:
+            if temp_var in locals() and os.path.exists(locals()[temp_var].name):
+                os.remove(locals()[temp_var].name)
+
+    if not user_input:
+        await update.message.reply_text("⚠️ No se pudo obtener contenido válido.")
+        return
+
+    await update.message.reply_text("⏳ Generando tu material educativo...")
+    start_time = time.time()
+    try:
+        resultado_md = edullm_rag_pipeline(user_input)
+        exito = True
+    except Exception as e:
+        resultado_md = f"❌ Error: {str(e)}"
+        exito = False
+    duracion = time.time() - start_time
+    registrar_uso(
+        user_id=update.effective_user.id,
+        username=update.effective_user.username,
+        tipo_entrada=detectar_tipo_entrada(user_input),
+        duracion_segundos=duracion,
+        exito=exito,
+    )
+    context.user_data["ultimo_markdown"] = resultado_md
+
+    preview = resultado_md[:1000] + ("\n..." if len(resultado_md) > 1000 else "")
+    preview_safe = escape_markdown(preview)
+    await update.message.reply_text(
+        f"✅ *Material generado*:\n\n```\n{preview_safe}\n```", parse_mode="MarkdownV2"
+    )
+
+    botones = [[InlineKeyboardButton("📄 Descargar DOCX", callback_data="descargar_docx")]]
+    await update.message.reply_text(
+        "¿Deseas descargar el material?", reply_markup=InlineKeyboardMarkup(botones)
+    )
+
+
+# ==== MENSAJE DE FORMATO NO SOPORTADO ====
+async def enviar_mensaje_formato_no_soportado(update: Update):
+    await update.message.reply_photo(
+        photo=InputFile(FORMAT_WARNING_IMAGE),
+        caption="⚠️ *Formato no soportado.*\n\nAcepto:\n- Texto\n- Imagen\n- PDF (.pdf)\n- Word (.docx)\n- Texto plano (.txt)",
+        parse_mode=None,
+    )
+
+
+# ==== CALLBACK BOTONES ====
+async def button_handler(update: Update, context: ContextTypes.DEFAULT_TYPE):
+    query = update.callback_query
+    await query.answer()
+
+    if query.data == "descargar_docx":
+        markdown_content = context.user_data.get("ultimo_markdown")
+        if not markdown_content:
+            await query.edit_message_text("⚠️ No hay material disponible para convertir.")
+            return
+
+        resultado = procesar_markdown(markdown_content)
+        if "error" in resultado:
+            await query.edit_message_text("❌ Error al generar el archivo DOCX.")
+            return
+
+        file_id = resultado["file_id"]
+        file_response = gestionar_descarga(file_id)
+
+        if isinstance(file_response, dict):
+            await query.edit_message_text(f"⚠️ {file_response.get('error')}")
+        else:
+            await query.edit_message_text("📥 Aquí tienes tu archivo DOCX:")
+            await context.bot.send_document(
+                chat_id=query.message.chat_id,
+                document=file_response.path,
+                filename=DOCX_FILENAME,
+            )
+
+
+# ==== INICIAR BOT ====
+def start_bot():
+    app = ApplicationBuilder().token(TELEGRAM_TOKEN).build()
+    app.add_handler(CommandHandler("start", start))
+    app.add_handler(MessageHandler(filters.ALL, handle_message))
+    app.add_handler(CallbackQueryHandler(button_handler))
+
+    print("🤖 EduLLM Bot en ejecución...")
+    app.run_polling()

core/llm/llm_manager.py

@@ -0,0 +1,96 @@
+# core/llm/llm_manager.py
+import os
+import base64
+from openai import OpenAI
+from dotenv import load_dotenv
+from loguru import logger
+
+load_dotenv(dotenv_path="config/.env")
+
+
+class LLMManager:
+    """Gestor de interacción con modelos de lenguaje compatibles con la API de OpenAI."""
+
+    def __init__(self):
+        self.api_key = os.getenv("LLM_API_KEY")
+        self.base_url = os.getenv("LLM_BASE_URL")
+        self.model = os.getenv("LLM_MODEL_NAME")
+        self.client = OpenAI(api_key=self.api_key, base_url=self.base_url)
+        self.prompt_system = self._load_system_prompt()
+
+    def _load_system_prompt(self) -> str:
+        """Carga el prompt del sistema desde 'config/prompt_system.txt'."""
+        path_system_prompt = os.getenv("PATH_SYSTEM_PROMPT")
+        try:
+            with open(path_system_prompt, "r", encoding="utf-8") as f:
+                logger.info("✅ Prompt del sistema cargado correctamente.")
+                return f.read().strip()
+        except FileNotFoundError:
+            logger.warning(
+                f"⚠️ No se encontró '{path_system_prompt}'. Se usará un prompt por defecto."
+            )
+            return "Eres un asistente educativo del MINEDU."
+
+    def _encode_image(self, image_bytes: bytes) -> str:
+        """Convierte bytes de imagen a Base64."""
+        logger.debug("🔄 Codificando imagen a Base64.")
+        return base64.b64encode(image_bytes).decode("utf-8")
+
+    def generate_response(
+        self, user_query: str, context: str = "", image: bytes = None
+    ) -> str:
+        """Genera respuesta multimodal (texto + imagen) o solo texto."""
+        try:
+            logger.info("🔹 Generando respuesta para la consulta del usuario.")
+            messages = []
+
+            # Añadir prompt del sistema
+            if self.prompt_system:
+                messages.append({"role": "system", "content": self.prompt_system})
+
+            # Si es imagen (multimodal)
+            if image:
+                logger.debug("🖼️ Procesando entrada multimodal con imagen.")
+                base64_image = self._encode_image(image)
+
+                messages.append(
+                    {
+                        "role": "user",
+                        "content": [
+                            {
+                                "type": "text",
+                                "text": user_query
+                                if user_query
+                                else "Describe esta imagen con enfoque educativo.",
+                            },
+                            {
+                                "type": "image_url",
+                                "image_url": {
+                                    "url": f"data:image/png;base64,{base64_image}"
+                                },
+                            },
+                        ],
+                    }
+                )
+
+            else:
+                # Solo texto, con posible contexto
+                full_prompt = user_query
+                if context:
+                    logger.debug("➕ Añadiendo contexto al mensaje.")
+                    full_prompt = f"{context}\n\nPregunta: {user_query}"
+
+                messages.append({"role": "user", "content": full_prompt})
+
+            # Llamada al modelo
+            response = self.client.chat.completions.create(
+                model=self.model,
+                messages=messages,
+            )
+
+            logger.success("✅ Respuesta generada correctamente.")
+            return response.choices[0].message.content
+
+        except Exception as e:
+            logger.error(f"❌ Error al generar respuesta: {str(e)}")
+            return f"Error al generar respuesta: {str(e)}"

core/logging/usage_logger.py

@@ -0,0 +1,80 @@
+import time
+import json
+from pathlib import Path
+from typing import Literal, Optional
+
+# Rutas
+LOG_FILE = Path("logs/registro_uso.json")
+USER_STATS_FILE = Path("logs/usuarios.json")
+
+# Crear carpeta si no existe
+LOG_FILE.parent.mkdir(parents=True, exist_ok=True)
+
+# Tipo de entrada admitida
+TipoEntrada = Literal["Texto", "Imagen", "PDF", "DOCX", "TXT", "Otro"]
+
+
+def registrar_uso(
+    user_id: int,
+    username: Optional[str],
+    tipo_entrada: TipoEntrada,
+    duracion_segundos: float,
+    exito: bool,
+    fuente: Optional[str] = "telegram_bot",
+) -> None:
+    """
+    Registra un evento de uso y actualiza el historial acumulado por usuario.
+    """
+    timestamp = time.strftime("%Y-%m-%d %H:%M:%S")
+    log_entry = {
+        "timestamp": timestamp,
+        "user_id": user_id,
+        "username": username or "N/A",
+        "tipo_entrada": tipo_entrada,
+        "duracion_segundos": round(duracion_segundos, 2),
+        "exito": exito,
+        "fuente": fuente,
+    }
+
+    # Guardar log individual
+    try:
+        registros = []
+        if LOG_FILE.exists():
+            with open(LOG_FILE, "r", encoding="utf-8") as f:
+                registros = json.load(f)
+        registros.append(log_entry)
+        with open(LOG_FILE, "w", encoding="utf-8") as f:
+            json.dump(registros, f, indent=2, ensure_ascii=False)
+    except Exception as e:
+        print(f"[ERROR] No se pudo guardar el registro individual: {e}")
+
+    # Actualizar conteo acumulado
+    try:
+        resumen = {}
+        if USER_STATS_FILE.exists():
+            with open(USER_STATS_FILE, "r", encoding="utf-8") as f:
+                resumen = json.load(f)
+
+        uid = str(user_id)
+        if uid not in resumen:
+            resumen[uid] = {
+                "username": username or "N/A",
+                "total_usos": 0,
+                "exitosos": 0,
+                "fallidos": 0,
+                "ultima_vez": timestamp
+            }
+
+        resumen[uid]["username"] = username or "N/A"
+        resumen[uid]["total_usos"] += 1
+        resumen[uid]["ultima_vez"] = timestamp
+        if exito:
+            resumen[uid]["exitosos"] += 1
+        else:
+            resumen[uid]["fallidos"] += 1
+
+        with open(USER_STATS_FILE, "w", encoding="utf-8") as f:
+            json.dump(resumen, f, indent=2, ensure_ascii=False)
+
+    except Exception as e:
+        print(f"[ERROR] No se pudo actualizar el resumen de usuarios: {e}")

core/pipeline/edullm_rag_pipeline.py

@@ -0,0 +1,83 @@
+# edullm_rag_pipeline.py
+
+# =========================
+# 📦 IMPORTACIONES
+# =========================
+import os
+from typing import Union
+
+from dotenv import load_dotenv
+from loguru import logger
+from pydantic import BaseModel
+
+from core.pipeline.utils import limitar_contexto, limpiar_contexto_bruto, validar_input
+from vectorstore.embeddings import EmbeddingManager
+from vectorstore.distance_strategy import DistanceStrategyManager
+from vectorstore.vectorstore_manager import VectorStoreManager
+from llm.llm_manager import LLMManager
+
+# =========================
+# ⚙️ CONFIGURACIÓN INICIAL
+# =========================
+load_dotenv(dotenv_path="config/.env")
+VECTORSTORE_PATH = os.getenv("VECTORSTORE_PATH", "docs/")
+VECTORSTORE_NAME = os.getenv("VECTORSTORE_NAME", "edullm_store")
+
+# =========================
+# 🚀 INICIALIZACIÓN DE COMPONENTES
+# =========================
+embeddings = EmbeddingManager.get_embeddings()
+strategy_mgr = DistanceStrategyManager()
+vector_mgr = VectorStoreManager(path=VECTORSTORE_PATH, name=VECTORSTORE_NAME)
+llm_manager = LLMManager()
+
+
+# =========================
+# 📄 MODELOS
+# =========================
+class Documento(BaseModel):
+    contenido: str
+    fuente: str
+    puntaje: float
+
+
+# =========================
+# 🛠️ FUNCIONES UTILITARIAS
+# =========================
+
+
+def init_vectorstore(force_rebuild: bool = False):
+    """Inicializa o reconstruye el vectorstore si es necesario."""
+    if force_rebuild or not vector_mgr.exist_vectorstore():
+        vector_mgr.create_vectorstore()
+
+
+# =========================
+# 🎯 PIPELINE PRINCIPAL
+# =========================
+def edullm_rag_pipeline(
+    input_data: Union[str, bytes], top_k: int = 4, search_type: str = "similarity"
+) -> str:
+    """Pipeline RAG para procesamiento multimodal y generación de respuesta educativa."""
+    if not validar_input(input_data):
+        logger.error("❌ Entrada inválida. Debes proporcionar texto o imagen válida.")
+        return "Error: Entrada no válida."
+
+    if isinstance(input_data, bytes):
+        return llm_manager.generate_response(
+            user_query="Procesa la imagen adjunta y responde según el contexto educativo.",
+            image=input_data,
+        )
+
+    retriever = vector_mgr.as_retriever(search_type=search_type, k=top_k)
+    docs = retriever.invoke(input_data)
+
+    if not docs:
+        contexto_final = "No se encontró contexto relevante."
+        logger.warning("⚠️ Sin resultados en FAISS para la consulta.")
+    else:
+        contexto_bruto = "\n\n".join(d.page_content for d in docs)
+        contexto_limpio = limpiar_contexto_bruto(contexto_bruto)
+        contexto_final = limitar_contexto(contexto_limpio)
+
+    return llm_manager.generate_response(user_query=input_data, context=contexto_final)

core/pipeline/utils.py

@@ -0,0 +1,47 @@
+# core/pipeline/utils
+import re
+from typing import Union
+
+
+def limpiar_contexto_bruto(contexto: str) -> str:
+    """Optimiza el contexto eliminando saltos de línea redundantes, espacios excesivos y corrigiendo puntuación."""
+    contexto = contexto.strip()
+
+    # 1️⃣ Reemplaza saltos de línea múltiples por un espacio si hay punto antes, o por punto y espacio si no hay.
+    contexto = re.sub(
+        r"\.\s*\n+", ". ", contexto
+    )  # Si ya hay punto antes del salto, limpia
+    contexto = re.sub(
+        r"(?<!\.)\n+", ". ", contexto
+    )  # Si NO hay punto antes, agrega punto
+
+    # 2️⃣ Elimina espacios múltiples
+    contexto = re.sub(r"\s{2,}", " ", contexto)
+
+    # 3️⃣ Corrige puntos dobles o triples
+    contexto = re.sub(r"\.{2,}", ".", contexto)
+
+    # 4️⃣ Elimina punto al inicio si quedó por error
+    contexto = re.sub(r"^\.\s*", "", contexto)
+
+    # 5️⃣ Asegura que termine en punto
+    if not contexto.endswith("."):
+        contexto += "."
+
+    return contexto.strip()
+
+
+def limitar_contexto(contexto: str, max_tokens: int = 1500) -> str:
+    """Recorta el contexto si excede el límite de tokens."""
+    if len(contexto) > max_tokens:
+        return contexto[:max_tokens] + "\n[Contexto truncado...]"
+    return contexto
+
+
+def validar_input(input_data: Union[str, bytes]) -> bool:
+    """Valida que la entrada sea texto no vacío o bytes (imagen)."""
+    if isinstance(input_data, str):
+        return bool(input_data.strip())
+    if isinstance(input_data, bytes):
+        return True
+    return False

core/vectorstore/distance_strategy.py

@@ -0,0 +1,21 @@
+# core/vectorstore/distance_strategy
+from langchain_community.vectorstores.faiss import DistanceStrategy
+
+
+class DistanceStrategyManager:
+    """
+    Gestor de estrategia de distancia para FAISS.
+    Estratégia fija: COSINE (vectores normalizados).
+    """
+
+    _instance = None
+
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    @property
+    def strategy(self) -> DistanceStrategy:
+        # Estrategia única y permanente para todas las búsquedas
+        return DistanceStrategy.COSINE

core/vectorstore/document_processor.py

@@ -0,0 +1,43 @@
+# core/vectorstore/document_processor.py
+import os
+
+from langchain_community.document_loaders import (
+    DirectoryLoader,
+    Docx2txtLoader,
+    PyMuPDFLoader,
+    TextLoader,
+)
+
+
+class DocumentProcessor:
+    """Document Processor class to process files in a directory."""
+
+    def __init__(self, path: str):
+        """Document Processor class to process files in a directory."""
+        self.path = path
+
+    def files_to_texts(self) -> list:
+        """Convert files in a directory to text."""
+        loaders_config = {
+            "*.pdf": PyMuPDFLoader,
+            "*.txt": (TextLoader, {"encoding": "utf-8"}),
+            "*.docx": Docx2txtLoader,
+            "*.doc": Docx2txtLoader,
+        }
+
+        loaders = [
+            DirectoryLoader(
+                path=self.path,
+                glob=glob,
+                loader_cls=loader if isinstance(loader, type) else loader[0],
+                loader_kwargs=loader[1] if isinstance(loader, tuple) else None,
+            )
+            for glob, loader in loaders_config.items()
+            if any(fname.endswith(glob[1:]) for fname in os.listdir(self.path))
+        ]
+
+        documents = []
+        for loader in loaders:
+            documents.extend(loader.load())
+
+        return documents

core/vectorstore/embeddings.py

@@ -0,0 +1,39 @@
+# core/vectorstore/embeddings.py
+import os
+
+from dotenv import load_dotenv
+from langchain_huggingface import HuggingFaceEmbeddings
+
+load_dotenv(dotenv_path="config/.env")
+
+
+class EmbeddingManager:
+    """
+    Singleton para gestionar embeddings HuggingFace normalizados (coseno).
+    """
+
+    _instance = None
+
+    def __new__(cls):
+        if cls._instance is None:
+            # Leer nombre de modelo, con valor por defecto
+            model = os.getenv(
+                "MODEL_EMBEDDINGS",
+                "sentence-transformers/distiluse-base-multilingual-cased",
+            )
+            cls._instance = super().__new__(cls)
+            # Aquí creamos el atributo de instancia
+            cls._instance.embeddings = HuggingFaceEmbeddings(
+                model_name=model,
+                encode_kwargs={"normalize_embeddings": True},
+            )
+        return cls._instance
+
+    @classmethod
+    def get_embeddings(cls):
+        """
+        Devuelve el objeto de embeddings del singleton.
+        """
+        if cls._instance is None:
+            cls._instance = cls()
+        return cls._instance.embeddings

core/vectorstore/vectorstore_manager.py

@@ -0,0 +1,136 @@
+# core/vectorstore/vectorstore_manager.py
+import os
+import faiss
+from langchain.text_splitter import RecursiveCharacterTextSplitter
+from langchain_community.docstore.in_memory import InMemoryDocstore
+from langchain_community.vectorstores import FAISS as FAISS_STORE
+from vectorstore.document_processor import DocumentProcessor
+from vectorstore.embeddings import EmbeddingManager
+from vectorstore.distance_strategy import DistanceStrategyManager
+from loguru import logger
+
+
+class VectorStoreManager:
+    """
+    Gestión minimalista de FAISS para EDULLM:
+    - Indexa documentos
+    - Carga/guarda el índice
+    - Expone retriever para RAG
+    """
+
+    def __init__(self, path: str, name: str):
+        self.path = path
+        self.store_path = os.path.join("database", name)
+        self.embeddings = EmbeddingManager.get_embeddings()
+        self.strategy = DistanceStrategyManager().strategy
+        self.vectorstore = None
+        logger.info(f"🔹 Inicializando VectorStoreManager en ruta: {self.store_path}")
+        self._initialize()
+
+    def _initialize(self):
+        if self.exist_vectorstore():
+            logger.info("✅ Índice FAISS encontrado. Cargando desde disco...")
+            self.vectorstore = self.load_vectorstore()
+        else:
+            logger.warning("⚠️ No existe índice previo. Creando índice vacío...")
+            dummy = self.embeddings.embed_query("init")
+            index = faiss.IndexFlatL2(len(dummy))
+            self.vectorstore = FAISS_STORE(
+                embedding_function=self.embeddings,
+                index=index,
+                docstore=InMemoryDocstore(),
+                index_to_docstore_id={},
+                distance_strategy=self.strategy,
+            )
+
+    def create_vectorstore(self) -> None:
+        logger.info(f"🚀 Procesando documentos en '{self.path}' para indexar...")
+        docs = DocumentProcessor(self.path).files_to_texts()
+        splitter = RecursiveCharacterTextSplitter(chunk_size=1000, chunk_overlap=400)
+        chunks = splitter.split_documents(docs)
+        self.vectorstore.add_documents(chunks)
+        self.save_vectorstore()
+        logger.success("🎯 Vectorstore creado y guardado correctamente.")
+
+    def save_vectorstore(self) -> None:
+        try:
+            os.makedirs(self.store_path, exist_ok=True)
+            self.vectorstore.save_local(self.store_path)
+            logger.info(f"💾 Índice guardado en '{self.store_path}'.")
+        except Exception as e:
+            logger.error(f"❌ Error al guardar el vectorstore: {e}")
+
+    def load_vectorstore(self):
+        try:
+            logger.info(f"📂 Cargando vectorstore desde '{self.store_path}'.")
+            return FAISS_STORE.load_local(
+                folder_path=self.store_path,
+                embeddings=self.embeddings,
+                allow_dangerous_deserialization=True,
+                distance_strategy=self.strategy,
+            )
+        except Exception as e:
+            logger.error(f"❌ Error al cargar el vectorstore: {e}")
+            raise
+
+    def exist_vectorstore(self) -> bool:
+        """Verifica si el vectorstore existe, creando la carpeta base si es necesario."""
+        base_dir = "database"
+
+        if not os.path.isdir(base_dir):
+            logger.warning(f"📂 Directorio base '{base_dir}' no encontrado. Creando...")
+            os.makedirs(base_dir, exist_ok=True)
+            return False
+
+        if os.path.isdir(self.store_path):
+            logger.info(f"✅ Vectorstore encontrado en '{self.store_path}'.")
+            return True
+        else:
+            logger.info(f"ℹ️ Vectorstore no existe aún en '{self.store_path}'.")
+            return False
+
+    def as_retriever(
+        self,
+        search_type: str = "similarity_score_threshold",
+        k: int = 4,
+        score_threshold: float = 0.75,
+        fallback_to_similarity: bool = True,
+        **kwargs,
+    ):
+        if not self.vectorstore:
+            self.vectorstore = self.load_vectorstore()
+
+        logger.debug(
+            f"🔍 Configurando retriever: type={search_type}, k={k}, threshold={score_threshold}"
+        )
+        search_kwargs = {"k": k, "score_threshold": score_threshold}
+        retriever = self.vectorstore.as_retriever(
+            search_type=search_type, search_kwargs=search_kwargs
+        )
+
+        if fallback_to_similarity:
+            logger.info(
+                "🛡️ Fallback activado: Si no hay resultados, se usará búsqueda por similarity."
+            )
+
+            class SafeRetriever:
+                def __init__(self, primary, fallback):
+                    self.primary = primary
+                    self.fallback = fallback
+
+                def invoke(self, query):
+                    docs = self.primary.invoke(query)
+                    if not docs:
+                        logger.warning(
+                            "⚠️ Sin resultados en threshold. Aplicando fallback a similarity."
+                        )
+                        return self.fallback.invoke(query)
+                    return docs
+
+            fallback_retriever = self.vectorstore.as_retriever(
+                search_type="similarity", search_kwargs={"k": k}
+            )
+
+            return SafeRetriever(retriever, fallback_retriever)
+
+        return retriever

database/edullm_store/index.faiss

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f6c2ede3f19b16d718dca7ce671ff05cd9b78791f7ed354008f04683c8d2ff91
+size 3245613

database/edullm_store/index.pkl

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6bacc3eb65b08b3b873d12c628f7b5d75c121c526b79d9aa1b4850ca39f8e01b
+size 2286011

docs/curriculo-nacional-de-la-educacion-basica.pdf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a745ca842113f53609c435df9a13eda67371164b22ccb8492b2b02167dc2299b
+size 12381710

docs/programa-curricular-educacion-primaria_compressed.pdf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:161de73bc723682387ff1f3e70ec9424a14c5c652518cd49723443c423852387
+size 22097096

main.py

@@ -0,0 +1,14 @@
+from core.integrations.telegram_bot import start_bot
+
+
+def run_telegram_bot():
+    start_bot()
+
+
+if __name__ == "__main__":
+    try:
+        # Iniciar solo el bot de Telegram
+        run_telegram_bot()
+        print("✅ Bot de Telegram está en ejecución...")
+    except KeyboardInterrupt:
+        print("¡Hasta pronto!")

requirements.txt

@@ -0,0 +1,17 @@
+faiss-cpu>=1.10.0
+langchain>=0.3.24
+langchain-community>=0.3.22
+langchain-huggingface>=0.1.2
+langchain-openai>=0.3.14
+python-telegram-bot>=22.0
+loguru>=0.7.3
+python-dotenv>=1.0.1
+pypandoc>=1.15
+pillow>=11.2.1
+pymupdf>=1.25.5
+pypdf2>=3.0.1
+python-docx>=1.1.2
+reportlab>=4.4.0
+docx2txt>=0.9
+pytest>=8.3.5
+pytest-cov>=6.1.1