Skip to content

README.md

Latest commit

 

History

History
305 lines (239 loc) · 11.8 KB

README.md

File metadata and controls

305 lines (239 loc) · 11.8 KB

ModelForge API

Python FastAPI scikit-learn Pydantic License Status

🧠 Overview

ModelForge API es una API REST de Machine Learning construida sobre FastAPI y scikit-learn, diseñada para exponer capacidades de entrenamiento y predicción de modelos ML a través de endpoints HTTP con validación estricta de datos mediante Pydantic.

El proyecto implementa una arquitectura de servicios en capas donde la lógica de negocio de ML — preprocesamiento de datos, selección de algoritmos, cálculo de métricas y persistencia de modelos — está completamente desacoplada de la capa de transporte HTTP. Los modelos entrenados se serializan con joblib y se persisten en disco dentro de storage/models/, permitiendo reutilizarlos en predicciones posteriores sin necesidad de reentrenamiento.

Este proyecto parece orientado a servir como backend de ML reutilizable, integrándose con sistemas de datos externos o frontends analíticos mediante su API versionada (/api/v1), y cuenta con documentación interactiva generada automáticamente por FastAPI (Swagger UI y ReDoc).

⚙️ Features

  • Entrenamiento on-demand: envía un dataset en formato JSON con el tipo de problema y algoritmo deseado, y la API entrena, evalúa y persiste el modelo automáticamente.
  • Predicción sobre modelos guardados: realiza inferencia sobre cualquier modelo previamente entrenado referenciándolo por su model_id.
  • Gestión de modelos: listado, consulta de metadatos y eliminación de modelos almacenados.
  • Cinco algoritmos ML: Linear Regression, Logistic Regression, Random Forest Regressor, Random Forest Classifier y K-Means Clustering.
  • Tres tipos de problemas soportados: Regresión, Clasificación y Clustering no supervisado.
  • Métricas completas por tipo de problema: Accuracy, Precision, Recall, F1-Score (clasif.), RMSE y R² (regresión).
  • Validación estricta de entradas con esquemas Pydantic en cada endpoint.
  • Documentación automática disponible en /docs (Swagger UI) y /redoc (ReDoc).
  • Health check en /health para monitoreo de disponibilidad.
  • CORS configurable desde variables de entorno para integración con frontends.
  • Multipart/form-data soportado via python-multipart para potencial carga de archivos.
  • Configuración por entorno con pydantic-settings y python-dotenv.

🛠️ Tech Stack

Capa Tecnología
Framework HTTP FastAPI
Servidor ASGI Uvicorn (con extras [standard]: websockets, HTTP/2)
Validación / Schemas Pydantic v2 + pydantic-settings
Motor ML scikit-learn
Manipulación de datos pandas, numpy
Persistencia de modelos joblib
Carga de archivos python-multipart
Variables de entorno python-dotenv
Testing pytest + pytest-cov + httpx
Lenguaje Python 3.9+

📦 Installation

Prerrequisitos

  • Python >=3.9
  • pip

Instalación local

# 1. Clonar el repositorio
git clone https://github.com/devsebastian44/ModelForge-API.git
cd ModelForge-API

# 2. Crear y activar entorno virtual
python -m venv venv

# Linux / macOS
source venv/bin/activate

# Windows
venv\Scripts\activate

# 3. Instalar dependencias
pip install -r requirements.txt

# 4. Configurar variables de entorno
cp .env.example .env
# Editar .env según tu entorno

▶️ Usage

Modo desarrollo (con auto-reload)

uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Modo producción (multi-worker)

uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4

Una vez iniciado el servidor, accede a:

  • Swagger UI (interactivo): http://localhost:8000/docs
  • ReDoc (documentación): http://localhost:8000/redoc
  • Health Check: http://localhost:8000/health

Endpoints disponibles

Método Ruta Descripción
POST /api/v1/training Entrenar un nuevo modelo ML
POST /api/v1/prediction Realizar predicción con un modelo guardado
GET /api/v1/models Listar todos los modelos entrenados
GET /api/v1/models/{model_id} Obtener metadatos de un modelo específico
DELETE /api/v1/models/{model_id} Eliminar un modelo persistido
GET /health Estado del servicio

Ejemplo: Entrenar un clasificador Random Forest

curl -X POST "http://localhost:8000/api/v1/training" \
  -H "Content-Type: application/json" \
  -d '{
    "dataset": [
      {"feature1": 1.2, "feature2": 3.4, "target": 0},
      {"feature1": 2.1, "feature2": 4.5, "target": 1},
      {"feature1": 3.3, "feature2": 2.2, "target": 0}
    ],
    "target_column": "target",
    "problem_type": "classification",
    "algorithm": "random_forest",
    "hyperparameters": {"n_estimators": 100, "max_depth": 5}
  }'

Ejemplo: Predecir con un modelo entrenado

curl -X POST "http://localhost:8000/api/v1/prediction" \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "model_20240125_123456",
    "data": [
      {"feature1": 1.5, "feature2": 3.2}
    ]
  }'

Ejecutar tests

# Instalar dependencias de testing
pip install pytest pytest-cov httpx

# Ejecutar suite completa
pytest tests/ -v

# Con reporte de cobertura
pytest tests/ --cov=app --cov-report=html

📁 Project Structure

ModelForge-API/
│
├── app/                          # Paquete principal de la aplicación
│   ├── main.py                   # Entry point FastAPI: instancia de app, CORS, routers
│   ├── config.py                 # Configuración centralizada con pydantic-settings
│   │
│   ├── api/                      # Capa de transporte HTTP
│   │   └── v1/
│   │       └── endpoints/        # Routers FastAPI por dominio
│   │           ├── training.py   # Endpoint POST /training
│   │           ├── prediction.py # Endpoint POST /prediction
│   │           └── models.py     # Endpoints GET/DELETE /models
│   │
│   ├── models/                   # Schemas Pydantic (contratos de la API)
│   │   ├── training.py           # TrainingRequest, TrainingResponse
│   │   ├── prediction.py         # PredictionRequest, PredictionResponse
│   │   └── model_info.py         # ModelInfo, ModelListResponse
│   │
│   ├── services/                 # Capa de lógica de negocio ML
│   │   ├── ml_service.py         # Orquestador principal: entrena y predice
│   │   ├── data_processor.py     # Preprocesamiento y validación del dataset
│   │   ├── model_manager.py      # Persistencia/carga de modelos con joblib
│   │   └── metrics_service.py    # Cálculo de métricas por tipo de problema
│   │
│   └── core/                     # Utilidades transversales
│       └── exceptions.py         # Excepciones personalizadas y manejadores HTTP
│
├── tests/                        # Suite de tests
│   └── test_api.py               # Tests de integración con httpx TestClient
│
├── storage/
│   └── models/                   # Almacenamiento de modelos serializados (.joblib)
│
├── .env.example                  # Plantilla de variables de entorno
├── requirements.txt              # Dependencias de producción
└── LICENSE                       # Licencia MIT

🔐 Security

  • Validación de esquemas con Pydantic v2: todas las entradas de la API son validadas estrictamente contra schemas tipados antes de llegar a la lógica de negocio, rechazando automáticamente datos malformados o con tipos incorrectos.
  • Manejo robusto de excepciones: excepciones personalizadas en core/exceptions.py previenen que errores internos del motor ML expongan stack traces al cliente.
  • CORS configurable por entorno: los orígenes permitidos se gestionan desde variables de entorno, evitando configuraciones permisivas hardcodeadas en producción.
  • Límite de tamaño de dataset: la capa de servicio implementa restricciones sobre el volumen de datos aceptado por request, previniendo ataques de denegación de servicio por payloads excesivamente grandes.
  • Sin almacenamiento de datos sensibles: el sistema solo persiste modelos serializados (.joblib), no los datasets de entrenamiento originales.
  • Separación de entornos via .env: las configuraciones sensibles de producción se mantienen fuera del código fuente mediante python-dotenv y pydantic-settings.

Para despliegues en producción se recomienda añadir autenticación mediante API keys o JWT, configurar HTTPS y limitar los orígenes CORS al dominio del cliente.

🌐 Repository Architecture

Este proyecto sigue una arquitectura distribuida de repositorios con separación de entornos:

  • GitHub — Presentación pública y portafolio: contiene el código fuente core sanitizado, documentación técnica y estructura del proyecto lista para reproducción.
  • GitLab — Laboratorio de datos e IA completo: contiene pipelines CI/CD, datasets de prueba, notebooks de experimentación, configuraciones de infraestructura y componentes de laboratorio privados.

🔗 Full Source Code

👉 Código completo disponible en GitLab: https://gitlab.com/group-data-ia-lab/ModelForge-API

🚀 Roadmap

Basado en la arquitectura actual detectada en el código, estas son las evoluciones técnicas sugeridas:

  • Autenticación y autorización: implementar API keys o JWT para proteger endpoints en producción.
  • Base de datos de metadatos: migrar el registro de modelos de sistema de archivos a SQLite/PostgreSQL con SQLAlchemy para búsquedas y filtros avanzados.
  • Entrenamiento asíncrono: usar BackgroundTasks de FastAPI o Celery para entrenar modelos pesados sin bloquear la respuesta HTTP.
  • Soporte para más algoritmos: SVM, XGBoost, LightGBM, redes neuronales via scikit-learn compatible API.
  • Versionado de modelos: permitir múltiples versiones de un mismo modelo y comparación de métricas entre versiones.
  • Carga de datasets por archivo: habilitar ingesta de CSV/Parquet directamente via multipart (ya soportado por python-multipart).
  • Containerización con Docker: Dockerfile y docker-compose para despliegue reproducible (infraestructura disponible en GitLab).
  • Pipeline CI/CD: automatización de tests, linting y despliegue en cada push (pipeline completo en GitLab).
  • Soporte MLflow: integración para tracking de experimentos, comparación de runs y registro centralizado de modelos.
  • Dashboard web: interfaz visual para entrenar, explorar y comparar modelos sin necesidad de curl o clientes API.
  • Límite de rate: middleware de rate-limiting para ambientes multi-tenant.
  • Exportación de modelos: endpoints para descargar modelos en formato ONNX o pickle para uso externo.

📄 License

Este proyecto está bajo la licencia MIT.

Licencia detectada directamente desde el archivo LICENSE en la raíz del repositorio.

👨‍💻 Author

Sebastian Zhunaula — @devsebastian44

Desarrollador full-stack e ingeniero de datos con enfoque en APIs de Machine Learning, arquitecturas orientadas a servicios y buenas prácticas de ingeniería de software aplicada a proyectos de IA.