Introducción

GODML es un framework Governed, Observable & Declarative para construir, versionar y desplegar modelos ML con gobernanza de datos.

🏛️ Governed: cumplimiento y trazabilidad de extremo a extremo.
👁️ Observable: métricas, logs y auditoría integrados.
📋 Declarative: pipelines definidos en YAML, reproducibles.

Corre en local o en la nube y abraza el open source (MLflow, Feast, FastAPI, XGBoost, scikit-learn, etc.).

📁 Arquitectura del Framework

Framework modular con servicios desacoplados (core, config, model, dataprep, deploy, monitoring y compliance). Cada módulo hace una cosa y la hace bien, facilitando escalabilidad, pruebas y despliegues independientes. Integraciones nativas con MLflow, Docker y nubes (S3/ECR/ECS/EKS/SageMaker).

godml/
├── compliance_service/     # 🔒 Servicios de cumplimiento (PCI-DSS, PII)
├── config_service/         # ⚙️ Gestión de configuración YAML
├── core_service/           # 🎯 Motor principal de ejecución
├── dataprep_service/       # 📊 Preparación declarativa de datos
├── deploy_service/         # 🚀 Servicios de despliegue y serving
├── model_service/          # 🤖 Gestión y registro de modelos
├── monitoring_service/     # 📈 Monitoreo y observabilidad
├── providers/              # 🔌 Integraciones (MLflow, SageMaker, Vertex)
├── utils/                  # 🛠️ Utilidades del framework
├── godml_cli.py            # 💻 CLI principal
└── notebook_api.py         # 📓 API para notebooks

🚀 Instalación y Configuración

Se instala vía pip install godml. En minutos tienes un proyecto inicializable con godml init, un YAML declarativo y comandos CLI que te llevan del dataset al modelo productivo con time-to-value corto y cero fricción.

# Instalación
pip install godml

# Crear nuevo proyecto
godml init mi-proyecto-ml

Estructura generada

Plantilla estándar con carpetas para datos, modelos por entorno (experiments/staging/production), outputs y servicios de deploy. Este layout promueve orden, reproducibilidad y handoffs limpios entre equipos (Data/ML/DevOps).

mi-proyecto-ml/
├── godml.yml              # 🎯 Configuración principal
├── data/                  # 📊 Datasets
├── outputs/               # 📈 Predicciones
├── models/                # 🤖 Modelos por entorno
│   ├── production/
│   ├── staging/
│   └── experiments/
├── deploy_service/        # 🚀 Servicios de despliegue
├── Dockerfile             # 🐳 Contenedor Docker
└── README.md              # 📖 Documentación

⚙️ Configuración Principal (godml.yml)

Archivo fuente de verdad: define dataset, modelo, hiperparámetros, métricas mínimas, cumplimiento, y despliegue (batch/realtime) por ambiente. Cambias el YAML, cambias el pipeline: infra como código aplicada al MLOps.

godml.yml (mínimo viable)
dataset:
  uri: data/sales.csv
  target: sales
  hash: auto

model:
  type: xgboost
  params:
    max_depth: 4
    eta: 0.1
    objective: reg:squarederror

split:
  test_size: 0.2
  random_state: 42

governance:
  tracking: mlflow
  compliance: pci-dss  # enmascarado automático si aplica

deploy:
  realtime: true
  batch_output: outputs/predictions.csv
  environments:
    development:
      host: 0.0.0.0
      port: 8000
      docker_tag: godml:dev

💻 CLI — Comandos Principales

Comandos para inicializar, entrenar (run), servir (serve), desplegar (deploy), calcular hash de datasets y ejecutar dataprep. Todo operable en local, contenedor o CI/CD, con logs claros y salidas auditable-ready.

# Inicializar proyecto
godml init mi-proyecto

# Ejecutar pipeline completo
godml run -f godml.yml

# Calcular hash de dataset y actualizar YAML
godml calc-hash ./data/churn.csv --update-yaml godml.yml

Serving y despliegue

# Servir modelo como API
godml serve dev

# Desplegar con Docker (por ambiente)
godml deploy mi-proyecto dev

Preparación de datos

# Validar receta de datos
godml dataprep validate recipe.yml

# Vista previa de transformaciones
godml dataprep preview recipe.yml --limit 20

# Ejecutar preparación completa
godml dataprep run recipe.yml --env production

📊 DataPrep Service — Preparación Declarativa

Recetas YAML para inputs, transformaciones y validaciones (select, fillna, one_hot, scaling, dedupe, etc.). Produce salidas versionables y verificadas. Menos notebooks ad-hoc, más pipelines repetibles.

Estructura de receta YAML

godml.yml (mínimo viable)
# recipe.yml - Receta de preparación de datos
dataprep:
  # 📥 INPUTS
  inputs:
    - name: raw_customers
      connector: csv
      uri: ./data/customers.csv
      options:
        sep: ","
        encoding: utf-8

  # 🔧 TRANSFORMACIONES
  steps:
    # Seleccionar columnas
    - op: select
      params:
        columns: ["id", "age", "income", "email"]

    # Rellenar valores nulos
    - op: fillna
      params:
        strategy: mean
        columns: ["age", "income"]

    # Codificación one-hot
    - op: one_hot
      params:
        columns: ["category"]
        drop_first: true

    # Escalado estándar
    - op: standard_scale
      params:
        columns: ["income", "age"]

    # Eliminar duplicados
    - op: drop_duplicates
      params:
        subset: ["id"]

  # ✅ VALIDACIONES
  validations:
    - type: expect_non_null
      args: ["id", "email"]

    - type: expect_unique
      args: ["id"]

    - type: expect_range
      args:
        column: age
        min: 18
        max: 100

  # 📤 OUTPUTS
  outputs:
    - name: clean_data
      connector: csv
      uri: ./data/customers_clean.csv

# 🔒 COMPLIANCE
governance:
  compliance: pci-dss  # Aplica automáticamente PCI-DSS

Transformaciones disponibles

| Operación         | Descripción               | Parámetros                                 |
| ----------------- | ------------------------- | ------------------------------------------ |
| `select`          | Seleccionar columnas      | `columns: ["col1", "col2"]`                |
| `rename`          | Renombrar columnas        | `mapping: {old: new}`                      |
| `drop_columns`    | Eliminar columnas         | `columns: ["col1"]`                        |
| `fillna`          | Rellenar nulos            | `strategy: mean/median/constant`           |
| `dropna`          | Eliminar filas con nulos  | `subset: ["col1"], how: any/all`           |
| `one_hot`         | Codificación one-hot      | `columns: ["cat"], drop_first: true`       |
| `label_encode`    | Codificación de etiquetas | `columns: ["status"]`                      |
| `standard_scale`  | Escalado estándar         | `columns: ["num1", "num2"]`                |
| `minmax_scale`    | Escalado min-max          | `columns: ["score"], feature_range: [0,1]` |
| `drop_duplicates` | Eliminar duplicados       | `subset: ["id"], keep: first`              |

📓 API para Notebooks

Funciones de alto nivel (p. ej., quick_train, train_from_yaml) y una clase GodmlNotebook para configurar, entrenar y guardar modelos desde notebooks sin perder gobernanza ni trazabilidad.

DataPrep inline Ejemplo Notebooks(casting + imputación + encoding)

# 1) Receta GODML sin strip_strings
recipe = {
    "inputs": [{"name": "raw", "connector": "csv", "uri": inp}],
    "steps": [
        {"op": "select", "params": {"columns": [
            "survived" if "survived" in df_local.columns else "Survived",
            "Pclass", "Sex", "Age", "SibSp", "Parch", "Fare", "Embarked"
        ]}},
        {"op": "safe_cast", "params": {"mapping": {
            "Age": "float", "Fare": "float",
            "Pclass": "int", "SibSp": "int", "Parch": "int"
        }}},
        {"op": "fillna", "params": {"columns": {"Age": 28.0, "Embarked": "S"}}},
        {"op": "fillna", "params": {"columns": {"Fare": 14.45}}},
        {"op": "one_hot", "params": {"columns": ["Sex", "Embarked"], "drop_first": True}},
        {"op": "rename", "params": {"mapping": {"Survived": "survived"}}},
        {"op": "safe_cast", "params": {"mapping": {"survived": "int"}}},
        {"op": "drop_duplicates", "params": {}},
    ],
    "outputs": [{"name": "clean", "connector": "csv", "uri": out}],
}

df_clean = nb.dataprep_run_inline(recipe)
print("✅ DataPrep OK — shape:", df_clean.shape)
nb.summarize_df(df_clean)

Uso básico

from godml.notebook_api import GodmlNotebook

# Crear instancia
godml = GodmlNotebook()

# Configurar pipeline
godml.create_pipeline(
    name="churn_predictor",
    model_type="random_forest",
    hyperparameters={"max_depth": 10, "n_estimators": 100},
    dataset_path="./data/customers.csv"
)

# Entrenar modelo
godml.train()

# Guardar por entorno
godml.save_model(model_name="churn_rf", environment="experiments")

Funciones rápidas

from godml.notebook_api import quick_train, train_from_yaml

# Entrenamiento rápido
quick_train(
    model_type="xgboost",
    hyperparameters={"eta": 0.1, "max_depth": 4},
    dataset_path="./data/churn.csv"
)

# Desde YAML existente
train_from_yaml("./godml.yml")

🤖 Modelos y Métricas

Soporte out-of-the-box para XGBoost, RandomForest, LightGBM (y extensiones). Métricas típicas de clasificación (Accuracy, AUC, F1) y regresión (MSE/RMSE/MAE), con umbrales exigibles para gates de calidad.

Modelos soportados

| Algoritmo       | Tipo              | Hiperparámetros clave           |
| --------------- | ----------------- | ------------------------------- |
| `xgboost`       | Gradient Boosting | `max_depth`, `eta`, `objective` |
| `random_forest` | Ensemble          | `n_estimators`, `max_depth`     |

Métricas disponibles

- ✅ auc — Area Under Curve

- ✅ accuracy — Precisión general

- ✅ precision — Precisión por clase

- ✅ recall — Recall por clase

- ✅ f1 — F1 Score

🚀 Despliegue y Serving

Serving realtime con FastAPI y batch a archivos o bases. Despliegue con Docker por ambiente y hooks para API Gateway/ALB. Endpoints estándar (/predict, /health, /docs) y playbook listo para ECS/EKS.

API de predicción (ejemplo)

import requests

# Realizar predicción
response = requests.post(
    "http://localhost:8000/predict",
    json={"features": [1.2, 3.4, 5.6, 7.8]}
)

prediction = response.json()
# {"prediction": 0.85, "model_version": "1.0.0"}

Endpoints disponibles

- POST /predict — Realizar predicciones

- GET /health — Estado del servicio

- GET /docs — Documentación Swagger

- GET /model/info — Información del modelo

🏛️ Gobernanza y Compliance

PII detection + mascarado (p. ej., PCI-DSS), hashing de datasets, linaje, owners y tags. Todo pensado para auditorías y SLA de seguridad sin dramas: cumple, registra y demuestra.

Características automáticas

- ✅ Hash del dataset para trazabilidad

- ✅ Metadatos del modelo (parámetros, métricas)

- ✅ Información de ownership y tags

- ✅ Linaje completo del pipeline

- ✅ Versionado automático de experimentos

godml.yml
# PCI-DSS automático
governance:
  compliance: pci-dss

# Detección de PII
from godml.compliance_service.pii_detector import PIIDetector

detector = PIIDetector()
pii_found = detector.scan_dataframe(df)

📈 Monitoreo y Observabilidad

Tracking en MLflow (experimentos, parámetros, métricas y artifacts), logging estructurado y puntos de integración con Prometheus. Lo necesario para operar modelos con visibilidad de punta a punta.

MLflow integrado

# Ver experimentos
mlflow ui
# Acceder a: http://localhost:5000

Logging estructurado

from godml.monitoring_service.logger import get_logger

logger = get_logger()
logger.info("Pipeline iniciado", extra={"model_type": "xgboost"})

🔧 Desarrollo y Extensión

Dependencias principales (ejemplo)

dependencies = [
    "typer[all]==0.12.3",      # CLI
    "pandas==2.3.0",           # Datos
    "scikit-learn==1.4.2",     # ML
    "xgboost==3.0.2",          # Gradient Boosting
    "mlflow==3.1.1",           # Tracking
    "fastapi",                 # API (opcional)
    "boto3==1.26.143"          # AWS (opcional)
]

Crear modelos personalizados

from godml.model_service.base_model_interface import BaseModel

class MiModeloPersonalizado(BaseModel):
    def train(self, X, y, **kwargs):
        # Implementar entrenamiento
        pass

    def predict(self, X):
        # Implementar predicción
        pass

🚀 Flujo de Trabajo Completo

# 1. Instalar
pip install godml

# 2. Crear proyecto
godml init mi-proyecto-churn

# 3. Preparar datos (opcional)
godml dataprep run data_recipe.yml

# 4. Configurar pipeline
cd mi-proyecto-churn
vim godml.yml

# 5. Entrenar modelo
godml run -f godml.yml

# 6. Revisar experimentos
mlflow ui

# 7. Servir modelo
godml serve dev

# 8. Desplegar
godml deploy mi-proyecto-churn production

📚 Recursos y Soporte

📦 GODML en PyPI: https://pypi.org/project/godml/
🐛 Reportar Issues: agtzrubio@dagmalia.com
💬 Discusiones
📧 Contacto: agtzrubio@dagmalia.com

Licencias compatibles

✅ MIT License
✅ BSD 3-Clause
✅ Apache 2.0
🟢 Uso comercial permitido

📋 Changelog

v0.4.0

✅ DataPrep service con transformaciones declarativas
✅ Compliance automático (PCI-DSS, PII detection)
✅ Deploy service con Docker integrado
✅ Notebook API mejorada con gestión de entornos

v0.3.0

✅ Entrenamiento rápido desde notebooks
✅ Guardado por entornos (experiments, production)
✅ Funciones quick_train, train_from_yaml
✅ Mejor integración con YAML

Generado con ❤️ por GODML Framework v0.4.0 Governed, Observable & Declarative Machine Learning

📁 Arquitectura del Framework​

🚀 Instalación y Configuración​

Estructura generada​

⚙️ Configuración Principal (godml.yml)​

💻 CLI — Comandos Principales​

📊 DataPrep Service — Preparación Declarativa​

📓 API para Notebooks​

🤖 Modelos y Métricas​

🚀 Despliegue y Serving​

🏛️ Gobernanza y Compliance​

📈 Monitoreo y Observabilidad​

🔧 Desarrollo y Extensión​

🚀 Flujo de Trabajo Completo​

📚 Recursos y Soporte​

Licencias compatibles​

📋 Changelog​