California Housing MCP Agent

Practica end-to-end de MLOps con el dataset California Housing. El proyecto entrena modelos de regresion, registra el mejor en MLflow, sirve predicciones con FastAPI, expone herramientas MCP y ofrece un frontend HTML para inferencia individual, batch y chat con agente.

Componentes

• training/train.py: entrena candidatos, evalua metricas y registra el modelo ganador en MLflow.
• api/main.py: aplicacion FastAPI con lifespan, CORS, observabilidad basica y servidor MCP embebido opcional.
• api/routes/v1/: endpoints de health, prediccion, batch, metadatos y chat del agente.
• agent/runtime.py: runtime del agente conectado a MCP mediante OpenAI Agents SDK y LiteLLM.
• frontend/index.html: interfaz local para probar predicciones y batch scoring.

Requisitos

• Python 3.11 o superior.
• uv instalado.
• Una clave de Gemini si FREE_MODEL=true, o una clave de OpenAI si FREE_MODEL=false.

Configuracion

uv sync
Copy-Item .env.example .env

Edita .env y define solo las claves que vayas a usar:

• GEMINI_API_KEY cuando FREE_MODEL=true.
• OPENAI_API_KEY cuando FREE_MODEL=false.

Entrenar y registrar el modelo

En una terminal, arranca MLflow:

uv run --env-file .env -- mlflow server --backend-store-uri sqlite:///mlflow.db --default-artifact-root ./mlruns --host 127.0.0.1 --port 5000

En otra terminal, ejecuta el entrenamiento:

uv run --env-file .env -- python training/train.py

El script compara candidatos, registra el modelo si mejora el historico y asigna el alias configurado en MLFLOW_MODEL_ALIAS.

Ejecutar la API

Con MLflow disponible y un modelo registrado:

uv run --env-file .env -- uvicorn api.main:app --reload --host 127.0.0.1 --port 8000

Endpoints principales:

• GET /api/v1/health
• POST /api/v1/predict
• POST /api/v1/batch-predict
• GET /api/v1/model-info
• GET /api/v1/schema
• POST /api/v1/agent/chat
• POST /mcp cuando ENABLE_MCP_SERVER=1

La documentacion OpenAPI queda disponible en http://127.0.0.1:8000/docs.

Frontend

Abre frontend/index.html en el navegador y usa http://127.0.0.1:8000/api/v1 como base URL. La pantalla permite:

• prediccion individual,
• subida de CSV para batch scoring,
• chat con el agente,
• inspeccion de request/response JSON y metricas de entrada.