📚 Sistema de Indexación y Búsqueda de Documentos XML

📖 Descripción

Aplicación web de recuperación de información que indexa colecciones de documentos XML validados contra un esquema XSD. El sistema extrae automáticamente las Unidades Estructurales (UE) definidas en el esquema y crea un índice con campos dinámicos para cada UE, permitiendo búsquedas avanzadas con métricas de relevancia.

Tarea 7 - Equipo 7:

• Joel Alexander Jiménez Jiménez
• Rodolfo Gilberto Castillo Vega
• José Ramón Gascón Enriquez

✨ Características

• ✅ Validación XML/XSD: Valida documentos XML contra esquemas XSD utilizando lxml
• ✅ Extracción de UE: Detecta y extrae automáticamente Unidades Estructurales
• ✅ Indexación dinámica: Crea índices con campos dinámicos según las UE del esquema
• ✅ Búsqueda avanzada: Búsqueda simple, por campo y multi-campo con Whoosh
• ✅ Interfaz web moderna: UI responsive con tema oscuro
• ✅ 4 modos de carga: XSD+Carpeta, Auto-detección, Subir archivos, Descargar desde URL
• ✅ Métricas visuales: Gráficos de relevancia y distribución de resultados
• ✅ Sugerencias de búsqueda: Autocompletado basado en contenido indexado
• ✅ Palabras relacionadas: Panel con términos semánticamente relacionados
• ✅ Análisis en español: Soporte para análisis de texto en español

📁 Estructura del Proyecto

tarea_final_sistemas/
├── src/
│   ├── modules/
│   │   ├── __init__.py
│   │   ├── xml_validator.py # Validación XML y extracción de UE
│   │   ├── indexer.py       # Indexación con Whoosh
│   │   └── searcher.py      # Búsqueda de documentos
│   ├── utils/
│   │   └── file_utils.py    # Utilidades de archivos
│   └── web/
│       ├── app.py           # Aplicación Flask (servidor)
│       └── templates/
│           └── index.html   # Interfaz web
├── data/                    # Datos de ejemplo
│   ├── documento.xsd        # Esquema XSD de ejemplo
│   └── *.xml                # Documentos XML de ejemplo
├── tests/                   # Pruebas unitarias
│   ├── test_xml_validator.py
│   ├── test_indexer_searcher.py
│   └── test_file_utils.py
├── uploads/                 # Archivos subidos temporalmente
├── index/                   # Índice Whoosh (generado)
├── pyproject.toml           # Configuración del proyecto
├── uv.lock                  # Lock file de dependencias
└── README.md                # Este archivo

📋 Requisitos

• Python 3.9 o superior
• UV (gestor de paquetes ultrarrápido)

---

🚀 Instalación

Paso 1: Clonar el repositorio

git clone <url-del-repositorio>
cd tarea_final_sistemas

Paso 2: Instalar UV

UV es un gestor de paquetes Python extremadamente rápido desarrollado por Astral. Selecciona tu sistema operativo:

🐧 Linux

Opción A - Script oficial (recomendado):

curl -LsSf https://astral.sh/uv/install.sh | sh

Opción B - Con wget:

wget -qO- https://astral.sh/uv/install.sh | sh

Opción C - Con pipx:

pipx install uv

Después de instalar, reinicia tu terminal o ejecuta:

source ~/.bashrc
# o si usas zsh:
source ~/.zshrc

Verificar instalación:

uv --version

🍎 macOS

Opción A - Script oficial (recomendado):

curl -LsSf https://astral.sh/uv/install.sh | sh

Opción B - Con Homebrew:

brew install uv

Opción C - Con pipx:

pipx install uv

Después de instalar, reinicia tu terminal o ejecuta:

source ~/.zshrc
# o si usas bash:
source ~/.bash_profile

Verificar instalación:

uv --version

🪟 Windows

Opción A - PowerShell (recomendado):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Opción B - Con winget:

winget install --id=astral-sh.uv -e

Opción C - Con Scoop:

scoop install uv

Opción D - Con pip:

pip install uv

Después de instalar, reinicia PowerShell o CMD.

Verificar instalación:

uv --version

Paso 3: Crear entorno virtual e instalar dependencias

# Crear entorno virtual (automático con uv sync)
uv sync

Este comando:

1. Crea automáticamente un entorno virtual en .venv/
2. Lee las dependencias de pyproject.toml
3. Instala todas las dependencias necesarias

Paso 4: (Opcional) Activar el entorno virtual manualmente

Si necesitas activar el entorno para otros propósitos:

# Linux/macOS
source .venv/bin/activate

# Windows (PowerShell)
.venv\Scripts\Activate.ps1

# Windows (CMD)
.venv\Scripts\activate.bat

---

▶️ Ejecución

Iniciar el servidor web

uv run python -m src.web.app

Abrir la aplicación

Una vez iniciado el servidor, abre tu navegador en:

http://localhost:5000

---

🖥️ Guía de Uso

1. Pestaña Configuración

La aplicación ofrece 4 modos de carga de documentos:

Modo	Descripción
📁 XSD + Carpeta	Selecciona un archivo XSD y una carpeta con XMLs
🔍 Auto-detectar	Detecta automáticamente el esquema desde los XMLs
📤 Subir Archivos	Sube archivos XML directamente desde tu computadora
🌐 URL	Descarga documentos XML desde una URL

Pasos:

1. Selecciona el modo de carga deseado
2. Proporciona los archivos/carpeta según el modo
3. Haz clic en "Indexar Documentos"
4. Espera a que se complete la indexación

2. Pestaña Búsqueda

Búsqueda simple:

• Escribe tu consulta en el campo de búsqueda
• Las sugerencias aparecerán mientras escribes
• Presiona Enter o haz clic en "Buscar"

Búsqueda por campo:

1. Activa "Búsqueda por campo"
2. Selecciona el campo (título, autor, resumen, etc.)
3. Escribe tu consulta
4. Busca

Panel de palabras relacionadas:

• A la derecha verás términos relacionados con tu búsqueda
• Haz clic en cualquier palabra para buscarla

3. Pestaña Métricas

Visualiza estadísticas de tus búsquedas:

• Distribución de relevancia: Gráfico de barras con scores
• Coincidencias por campo: Dónde se encontraron los términos
• Tendencia de scores: Línea temporal de relevancia

4. Pestaña Ayuda

Documentación completa y guía de uso dentro de la aplicación.

---

🧪 Pruebas

Ejecutar todas las pruebas

uv run pytest

Ejecutar con información detallada

uv run pytest -v

Ejecutar con cobertura de código

uv run pytest --cov=src

Ejecutar pruebas específicas

# Solo pruebas de validación XML
uv run pytest tests/test_xml_validator.py -v

# Solo pruebas de indexación y búsqueda
uv run pytest tests/test_indexer_searcher.py -v

# Solo pruebas de utilidades
uv run pytest tests/test_file_utils.py -v

---

🛠️ Tecnologías Utilizadas

Tecnología	Propósito
Python 3.9+	Lenguaje de programación
Flask	Framework web para el servidor
lxml	Parsing XML, validación XSD, XPath
Whoosh	Motor de indexación y búsqueda full-text
UV	Gestión ultrarrápida de paquetes Python
Chart.js	Visualización de métricas
pytest	Framework de pruebas unitarias

---

📊 Esquema XSD de Ejemplo

El proyecto incluye un esquema XSD de ejemplo (data/documento.xsd) con las siguientes Unidades Estructurales:

Campo	Descripción
titulo	Título del documento
autor	Autor del documento
fecha	Fecha de creación
resumen	Resumen del contenido
cuerpo	Cuerpo principal del documento
conclusiones	Conclusiones
referencias	Referencias bibliográficas
palabras_clave	Palabras clave del documento

---

📈 Flujo de Trabajo

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  Documentos XML │────▶│   Validación     │────▶│  Extracción UE  │
└─────────────────┘     │     (XSD)        │     └────────┬────────┘
                        └──────────────────┘              │
                                                          ▼
┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   Resultados    │◀────│    Búsqueda      │◀────│   Indexación    │
│   + Métricas    │     │    (Whoosh)      │     │    (Whoosh)     │
└─────────────────┘     └──────────────────┘     └─────────────────┘

---

🐛 Solución de Problemas

UV no se reconoce como comando

Linux/macOS:

export PATH="$HOME/.cargo/bin:$PATH"
source ~/.bashrc  # o ~/.zshrc

Windows: Reinicia PowerShell o CMD después de la instalación.

Error de permisos en Linux/macOS

chmod +x ~/.cargo/bin/uv

El servidor no inicia

Verifica que el puerto 5000 esté disponible:

# Linux/macOS
lsof -i :5000

# Windows
netstat -ano | findstr :5000

Errores de dependencias

# Limpiar y reinstalar
rm -rf .venv uv.lock
uv sync

---

📝 Licencia

Este proyecto fue desarrollado como parte del curso de Recuperación de Información - UACJ.

---

👥 Contacto

Para preguntas o sugerencias, contactar a los miembros del Equipo 7.