Sistema MLOps completo para clasificación automática de documentos en español implementando todas las fases del ciclo CRISP-DM (Cross Industry Standard Process for Data Mining).

• ✅ Estructura CRISP-DM Completa: 6 fases separadas en módulos Python
• ✅ Paquete Publicable: Disponible en PyPI
• ✅ Containerizado: Docker image lista para producción
• ✅ CI/CD Automatizado: GitHub Actions workflows (test, Docker, PyPI, model registry)
• ✅ Versionado de Modelos: Registro automático de versiones y promoción a producción
• ✅ Evaluación Integral: Fairness, latencia, drift detection
• ✅ Documentación: Reportes CRISP-DM y presentación de negocio

# Opción 1: Desde PyPI
pip install proyecto-mlops

# Opción 2: Desarrollo local
git clone https://github.com/angelcast2002/PROYECTO-MLOPS.git
cd PROYECTO-MLOPS
pip install -e ".[dev]"

from proyecto_mlops import (
    load_raw_dataset,
    preprocess_dataframe,
    train_model,
    full_evaluation,
    promote_to_production
)

# 1. Cargar datos
df = load_raw_dataset("data/raw/dataset.csv")

# 2. Preprocesar
df_clean = preprocess_dataframe(df)

# 3. Entrenar modelo
texts = df_clean["text_norm"].tolist()
labels = df_clean["label"].tolist()
pipe, metrics = train_model(texts, labels)

# 4. Evaluar
eval_result = full_evaluation(pipe, texts_test, labels_test)

# 5. Desplegar
promote_to_production(version=1)

# CLI
python cli.py all

# Modo rápido (testing)
python cli.py all --fast 1000

# Docker
docker build -t proyecto-mlops:latest .
docker run -v $(pwd)/data:/app/data proyecto-mlops:latest

PROYECTO-MLOPS/
├── proyecto_mlops/                 # Paquete principal (publicable)
│   ├── __init__.py
│   ├── business_understanding/     # Fase 1: Objetivos de negocio
│   ├── data_understanding/         # Fase 2: Exploración de datos
│   ├── data_preparation/           # Fase 3: Preprocesamiento
│   ├── modeling/                   # Fase 4: Entrenamiento
│   ├── evaluation/                 # Fase 5: Evaluación
│   ├── deployment/                 # Fase 6: Despliegue
│   └── utils/                      # Utilidades compartidas
│
├── .github/workflows/              # CI/CD Automation
│   ├── ci.yml                      # Tests + Quality checks
│   ├── cd-docker.yml               # Docker build & push
│   ├── cd-pypi.yml                 # PyPI publishing
│   └── cd-model-registry.yml       # Model versioning
│
├── data/
│   ├── raw/                        # Datos originales
│   ├── processed/                  # Datos preprocesados
│   └── registry/                   # Versionado de datos
│
├── models/                         # Modelos entrenados
├── tests/                          # Tests unitarios
├── docs/                           # Documentación
│
├── Dockerfile                      # Containerización
├── setup.py                        # Configuración del paquete
├── requirements.txt                # Dependencias
├── cli.py                          # CLI principal
├── pipeline.py                     # Pipeline monolítico (legacy)
├── config.yaml                     # Configuración
│
├── CRISP_DM_REPORT.md             # Reporte técnico completo
├── BUSINESS_PRESENTATION.md        # Presentación de negocio
└── README.md                       # Este archivo

Además del paquete monolítico proyecto-mlops, el repo ahora expone paquetes independientes por fase y un agregador final:

packages/
    ├─ proyecto-core/       # utilidades y rutas compartidas
    ├─ proyecto-bu/         # Business Understanding
    ├─ proyecto-du/         # Data Understanding
    ├─ proyecto-dp/         # Data Preparation
    ├─ proyecto-modeling/   # Modeling
    ├─ proyecto-eval/       # Evaluation
    ├─ proyecto-deploy/     # Deployment
    └─ proyecto-final/      # Agregador + CLI multi-paquete

Instalación en desarrollo (editable):

pip install -e .\packages\proyecto-core
pip install -e .\packages\proyecto-bu
pip install -e .\packages\proyecto-du
pip install -e .\packages\proyecto-dp
pip install -e .\packages\proyecto-modeling
pip install -e .\packages\proyecto-eval
pip install -e .\packages\proyecto-deploy
pip install -e .\packages\proyecto-final

O bien, usa el script de instalación rápida (Windows/PowerShell):

pwsh -File .\scripts\dev_install.ps1

Uso de ejemplo:

from proyecto_dp import prepare_data_pipeline
from proyecto_modeling import train_model
from proyecto_final import full_evaluation

CLI del agregador:

proyecto-final all

Nota: el archivo pipeline.py se mantiene como shim de compatibilidad para los tests y, si no encuentra el paquete proyecto_dp, hace fallback al monolítico.

Además del paquete monolítico proyecto-mlops, cada etapa está publicada individualmente en PyPI. Links directos:

• Núcleo compartido: https://pypi.org/project/proyecto-core/
• Business Understanding: https://pypi.org/project/proyecto-bu/
• Data Understanding: https://pypi.org/project/proyecto-du/
• Data Preparation: https://pypi.org/project/proyecto-dp/
• Modeling: https://pypi.org/project/proyecto-modeling/
• Evaluation: https://pypi.org/project/proyecto-eval/
• Deployment: https://pypi.org/project/proyecto-deploy/
• Agregador (CLI multi-paquete): https://pypi.org/project/proyecto-mlops-final/
• Paquete monolítico: https://pypi.org/project/proyecto-mlops/

Para publicar nuevas versiones de todos los paquetes desde GitHub Actions, usa el workflow “CD - PyPI (multi-package)” (manual) o genera un tag packages-vX.Y.Z y se publicará en matriz.

Definición de objetivos de negocio, problemas, y criterios de éxito.

Ubicación: proyecto_mlops/business_understanding/

from proyecto_mlops import save_business_document
save_business_document()

Exploración, validación y esquematización de datos.

Ubicación: proyecto_mlops/data_understanding/

from proyecto_mlops import (
    load_raw_dataset,
    explore_data,
    save_data_schema,
    validate_schema
)

df = load_raw_dataset()
exploration = explore_data(df)
schema = save_data_schema()

Outputs:

• data/data_exploration_report.json
• docs/data_schema.json

Preprocesamiento: normalización, tokenización, limpieza, stemming.

Ubicación: proyecto_mlops/data_preparation/

from proyecto_mlops import prepare_data_pipeline

df_clean = prepare_data_pipeline(
    csv_path="data/raw/dataset.csv",
    use_lemmatization=False
)

Transformaciones:

• Normalización Unicode (lowercase, acentos)
• Tokenización (regex)
• Limpieza (stopwords, dígitos)
• Stemming (Snowball Spanish)

Output: data/processed/preprocesado.parquet

Entrenamiento de clasificador con TF-IDF + LinearSVC.

Ubicación: proyecto_mlops/modeling/

from proyecto_mlops import (
    train_model,
    cross_validate_model,
    hyperparameter_sweep
)

# Holdout validation
pipe, metrics = train_model(texts, labels)

# Cross-validation (5-fold)
cv_result = cross_validate_model(texts, labels)

# Hyperparameter sweep
results = hyperparameter_sweep(
    texts, labels,
    param_grid=[
        {"min_df": 1, "C": 0.1},
        {"min_df": 2, "C": 1.0},
        {"min_df": 3, "C": 10.0}
    ]
)

Configuración:

• Vectorización: TF-IDF (1,2)-grams
• Clasificador: LinearSVC (C=1.0)
• Validación: 5-Fold StratifiedKFold

Métricas de rendimiento, fairness, latencia.

Ubicación: proyecto_mlops/evaluation/

from proyecto_mlops import (
    evaluate_model,
    measure_latency,
    check_fairness,
    full_evaluation
)

# Evaluación completa
eval_result = full_evaluation(
    pipe=pipe,
    X_test=X_test,
    y_test=y_test,
    min_f1_per_class=0.70
)

Métricas:

• Accuracy, F1-Macro, F1-Weighted
• Latencia: P50, P95, P99
• Fairness: F1 mínima por clase ≥ 0.70

Registro, versionado, y promoción de modelos.

Ubicación: proyecto_mlops/deployment/

from proyecto_mlops import (
    register_model_in_registry,
    promote_to_production,
    get_production_model,
    create_deployment_package
)

# Registrar modelo
register_model_in_registry(
    model_path="models/svm_tfidf_v1.joblib",
    model_name="svm_tfidf",
    version=1,
    metrics=eval_result
)

# Promover a producción
promote_to_production(version=1)

# Crear paquete de deployment
package = create_deployment_package(
    model_path="models/svm_tfidf_v1.joblib"
)

Ejecuta en cada push/PR:

• ✅ Tests unitarios (pytest)
• ✅ Code quality (black, isort, flake8)
• ✅ Security scan (Trivy)
• ✅ Coverage reports (codecov)

Ejecuta en push a main:

• ✅ Build imagen Docker
• ✅ Push a Docker Hub (docker.io/angelcast2025/proyecto-mlops)
• ✅ Tagged con versión + latest

Ejecuta en tag v*:

• ✅ Build paquete Python
• ✅ Publish a TestPyPI (testing)
• ✅ Publish a PyPI (production)
• ✅ Create GitHub Release

Ejecuta después de CI exitoso:

• ✅ Run full pipeline
• ✅ Generate model metadata
• ✅ Upload artifacts (30 días retención)
• ✅ Update registry

Para una guía paso a paso de despliegue en DigitalOcean (Droplet Ubuntu) consulta: docs_project/DEPLOY_DIGITAL_OCEAN.md.

docker build -t proyecto-mlops:latest .

# Con volumen de datos
docker run -v $(pwd)/data:/app/data \
           -p 8000:8000 \
           proyecto-mlops:latest

# Con archivo de configuración
docker run -v $(pwd)/config.yaml:/app/config.yaml \
           proyecto-mlops:latest \
           python cli.py all

docker tag proyecto-mlops:latest angelcast2025/proyecto-mlops:latest
docker push angelcast2025/proyecto-mlops:latest

docker pull angelcast2025/proyecto-mlops:latest
docker pull angelcast2025/proyecto-mlops:0.1.6

pip install proyecto-mlops

pip install --index-url https://test.pypi.org/simple/ proyecto-mlops

# Desarrollo
pip install proyecto-mlops[dev]

# Docker support
pip install proyecto-mlops[docker]

1. CRISP_DM_REPORT.md (Este proyecto)

   • Reporte técnico completo de todas las fases CRISP-DM
   • Resultados, conclusiones y escalabilidad
   • 15+ páginas

2. BUSINESS_PRESENTATION.md

   • Presentación enfocada en valor de negocio
   • ROI, timeline, riesgos
   • Lenguaje ejecutivo (no técnico)

3. README.md

   • Guía de instalación y uso
   • Estructura del proyecto
   • Quick start

from proyecto_mlops import save_business_document, save_data_schema
from proyecto_mlops import save_data_exploration

# Business
save_business_document()

# Data
save_data_schema()
save_data_exploration()

# Instalar test dependencies
pip install pytest pytest-cov

# Ejecutar tests
pytest tests/ -v

# Con coverage
pytest tests/ --cov=proyecto_mlops --cov-report=html

metrics = {
    "predictions_per_minute": 120,
    "avg_latency_ms": 45,
    "p95_latency_ms": 180,
    "error_rate": 0.01,
    "drift_psi": 0.05,
    "model_accuracy": 0.82
}

• ⚠️ P95 latency > 300ms
• ⚠️ Error rate > 5%
• ⚠️ PSI (drift) > 0.2
• ⚠️ Accuracy drop > 10%

Para CI/CD completo, configura estos secrets:

DOCKER_USERNAME    # Docker Hub username
DOCKER_PASSWORD    # Docker Hub access token
PYPI_API_TOKEN     # PyPI API token
TEST_PYPI_API_TOKEN # TestPyPI API token

Ubicación: GitHub → Settings → Secrets and variables → Actions

• ✅ Versionado de código y datos
• ✅ Versionado de modelos
• ✅ Reproducibilidad
• ✅ CI/CD automation
• ✅ Containerización
• ✅ Infrastructure as Code
• ✅ Monitoring y alerting
• ✅ Model registry
• ✅ Deployment automation

• ✅ Preprocesamiento de texto
• ✅ Feature engineering (TF-IDF)
• ✅ Clasificación (LinearSVC)
• ✅ Cross-validation
• ✅ Hyperparameter tuning
• ✅ Fairness y equidad
• ✅ Latency optimization
• ✅ Drift detection

• ✅ Docker
• ✅ GitHub Actions
• ✅ Package distribution (PyPI)
• ✅ CI/CD workflows
• ✅ Security scanning

1. Desplegar en servidor de staging
2. Integrar FastAPI para inferencia
3. Configurar Prometheus + Grafana

1. Kubernetes deployment
2. Auto-scaling y load balancing
3. Advanced monitoring

1. A/B testing y canary deployments
2. Active learning loop
3. Multi-model serving

Pull requests son bienvenidos. Para cambios mayores, abre un issue primero.

MIT License - ver LICENSE file

Autores: Angel Castellanos, Alejandro Azurdia, Diego Morales, Sara Echeverría

Última actualización: Noviembre 13, 2025
Versión: 0.1.6
Estado: ✅ Producción Ready