9. Dependencias y librerías

Análisis de cada dependencia: qué es, para qué se usa en este proyecto, alternativas, riesgos de actualización y compatibilidad. Definidas en pyproject.toml, organizadas en el core + 4 grupos opcionales (dev, analysis, cloud, xai).

9.1. Estructura de dependencias

make install instala todo: pip install -e ".[dev,analysis,xai,cloud]". Los grupos permiten instalar solo lo necesario (p.ej. producción sin dev).

9.2. Dependencias core (siempre requeridas)

torch (>=2.2, <2.13) — el framework de deep learning

Qué es: PyTorch, la librería de tensores y autodiferenciación. Uso: todo el modelado, entrenamiento, gradientes (loss.backward()), y los hooks de Grad-CAM. Es el cimiento. Alternativas: TensorFlow/Keras, JAX. Por qué PyTorch: ecosistema de investigación dominante, timm y LIME se integran fácil, API imperativa clara. Nota: el despliegue apunta a TFLite, así que habrá un puente PyTorch→TFLite (vía ONNX o conversión) en el futuro. Riesgo de actualización: medio. Cambios entre versiones mayores pueden romper APIs; el rango <2.13 acota. cuDNN/CUDA deben ser compatibles con la GPU.

torchvision (>=0.17, <0.28)

Qué es: modelos, transforms y utilidades de visión de PyTorch. Uso: las arquitecturas EfficientNet-B0 y ShuffleNetV2, y todos los transforms de augmentation (T.Resize, T.ColorJitter, etc.). Riesgo: debe versionar en pareja con torch (versiones acopladas). Actualizar una sin la otra rompe.

timm (>=0.9, <1.1) — modelos que torchvision no trae

Qué es: PyTorch Image Models, cientos de arquitecturas modernas. Uso: EfficientNet-Lite0/B4, MobileNetV3, GhostNetV2, FastViT — todas las que no están en torchvision. create_model(..., num_classes=N) construye con la cabeza ya adaptada. Riesgo: medio. La transición 0.9→1.0 cambió algunas APIs; el rango <1.1 lo contiene. Los nombres de modelos deben coincidir exactamente con los del hub de timm.

Pillow (>=10.0, <13.0)

Qué es: manipulación de imágenes (PIL). Uso: load_and_normalize_image (abrir, EXIF, convertir RGB) y la validación de integridad en create_splits.py (Image.verify()). Riesgo: bajo. Comportamiento estable; el guard if img is raw cubre diferencias entre versiones antiguas.

pandas (>=2.0, ❤️.0)

Qué es: DataFrames. Uso: todos los manifiestos de split, predictions.csv, reportes, agregaciones de fidelidad. Los splits son DataFrames. Riesgo: medio. pandas 2.2/3.0 cambió el comportamiento de groupby (excluir la columna de agrupación), lo que ya causó un bug en _cap_manifest_per_class — resuelto iterando el groupby en vez de .apply. Un ejemplo real de por qué acotar versiones importa.

scikit-learn (>=1.4, <1.10)

Qué es: ML clásico y utilidades. Uso: train_test_split (el split estratificado) y las métricas (f1_score, accuracy_score, classification_report, confusion_matrix). Riesgo: bajo. API muy estable.

pyyaml, python-dotenv, tqdm

• pyyaml: lee config/dataset.yaml. Riesgo bajo.
• python-dotenv: carga .env (rutas). Riesgo bajo.
• tqdm: barras de progreso (indexado, épocas). Puramente cosmético; riesgo nulo.

9.3. Grupo xai — explicabilidad

lime (>=0.2)

Qué es: implementación de LIME. Uso: LimeImageExplainer en visual_report.py. Alternativas: SHAP, Captum (de PyTorch). Por qué LIME: explicaciones por superpíxel intuitivas para no-expertos (agrónomos), model-agnostic. Riesgo: la librería está poco mantenida; es estocástica (de ahí lime_stability.py).

scikit-image (>=0.22)

Uso: segmentación de superpíxeles y mark_boundaries (los bordes verdes de los paneles LIME). Riesgo: bajo.

matplotlib (>=3.8)

Uso: renderizar los PNG de reportes (paneles LIME, Grad-CAM, grids de augmentation). También en dev. Riesgo: bajo.

9.4. Grupo cloud — hosting y cómputo remoto

• huggingface_hub: descargar/subir clean/ del HF Datasets Hub. Fuente primaria del dataset.
• gdown: fallback de descarga desde Google Drive.
• modal: ejecutar los pipelines en GPU en la nube (scripts/modal/). Riesgo: Modal evoluciona rápido; su API puede cambiar.

9.5. Grupo analysis — exploración de datos (fase de construcción)

• imagededup: detección de duplicados (perceptual) durante la limpieza — complementa la dedup exacta.
• fiftyone + mongoengine/motor: visualización interactiva de datasets (requiere MongoDB). Usado en EDA, no en el pipeline de entrenamiento.
• imageio: E/S de imágenes auxiliar.

Estas son de fase de análisis, no de entrenamiento; por eso están en un grupo opcional separado.

9.6. Grupo dev — desarrollo

• ruff: linter + formateador (muy rápido). make lint/make fmt. Config en pyproject.toml (line-length 100, reglas E/F/W/I).
• pyright: verificador de tipos estáticos. make check.
• jupyterlab/ipykernel: el notebook de EDA (notebooks/01_eda.ipynb).
• seaborn: gráficos estadísticos del EDA.

9.7. Versiones fijadas en Modal (importante)

scripts/modal/_common.py fija exactamente torch==2.12.1, torchvision==0.27.1 (con índice CUDA cu126). Por qué exacto y no rango: el entorno remoto debe ser idéntico entre corridas y entre train.py/explain.py para que los checkpoints sean intercambiables. Un rango podría instalar versiones distintas en momentos distintos, rompiendo la reproducibilidad de la nube.

9.8. Matriz de riesgo de actualización

Dependencia	Riesgo	Por qué
torch / torchvision	🟠 Medio-Alto	Acopladas entre sí y con CUDA; cambios de API
timm	🟠 Medio	Cambios 0.9→1.0; nombres de modelos
pandas	🟠 Medio	Cambios de groupby ya causaron un bug
lime	🟡 Medio	Poco mantenida; estocástica
modal	🟡 Medio	Evoluciona rápido
Pillow, sklearn, pyyaml, dotenv, tqdm	🟢 Bajo	APIs estables

Recomendación de mantenimiento: actualizar torch+torchvision juntos y validar con make test-loader + un entrenamiento corto antes de confiar. Ver Riesgos técnicos.

Siguiente

Dónde puede fallar o volverse frágil el sistema: Riesgos técnicos.