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.

Related MCP server: GoldenGate MCP Server

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.