MixTechDevs/nasa-exoplanet-detection

Nasa Exoplanet Detection

Servicio de Machine Learning (API) para clasificar candidatos Kepler (KOI) como "CONFIRMED" o "FALSE POSITIVE" usando un modelo XGBoost serializado.

Estructura relevante del repositorio:

• —backend/ — código de la API (FastAPI).
• —models/ — artefactos del modelo: model.json y label-encoder.joblib.
• —requirements.txt — dependencias Python.
• —Dockerfile — imagen para ejecutar la API en contenedor.

Este README cubre cómo ejecutar el servicio localmente y con Docker, las variables de entorno disponibles y ejemplos de uso de los endpoints.

Requisitos previos

• —macOS (probado con zsh)
• —Python 3.10+ (recomendado 3.11/3.12)
• —pip
• —virtualenv o venv (opcional pero recomendado)
• —Docker (si quieres ejecutar la imagen)

Instalación y ejecución local (entorno virtual)

1) Clona el repositorio (si aún no lo hiciste):

git clone <repo-url>
cd nasa-exoplanet-detection

2) Crea y activa un entorno virtual:

python -m venv .venv
source .venv/bin/activate

3) Instala dependencias:

pip install --upgrade pip
pip install -r requirements.txt

4) Verifica que los archivos del modelo existen en models/:

ls -l models/model.json models/label-encoder.joblib

Si faltan, coloca allí model.json y label-encoder.joblib (nombres exactos) o ajusta las variables de entorno MODEL_PATH y ENCODER_PATH (ver sección Variables de entorno).

5) Ejecuta la API con Uvicorn (modo desarrollo):

# Puerto por defecto usado en desarrollo: 8000
uvicorn backend.main:app --host 0.0.0.0 --port 8000 --reload

Nota: el Dockerfile de este repositorio expone por defecto el puerto 7860; los ejemplos de Docker más abajo usan ese puerto.

Variables de entorno

Las rutas y puerto se pueden controlar con variables de entorno. Valores por defecto (en backend/config.py) son:

• —MODEL_PATH — ruta al archivo del modelo XGBoost (por defecto models/model.json).
• —ENCODER_PATH — ruta al LabelEncoder serializado (por defecto models/label-encoder.joblib).
• —HOST — host donde bindear la app (por defecto 0.0.0.0).
• —PORT — puerto (por defecto 8000 en configuración; el Dockerfile usa 7860).

Ejemplo de export para zsh antes de arrancar localmente:

export MODEL_PATH="$PWD/models/model.json"
export ENCODER_PATH="$PWD/models/label-encoder.joblib"
export PORT=8000

Ejecutar con Docker

Construir la imagen:

docker build -t exoplanet-api:latest .

Ejecutar la imagen (mapeando el puerto 7860 del contenedor al host):

docker run --rm -p 7860:7860 \
  -e MODEL_PATH=/app/models/model.json \
  -e ENCODER_PATH=/app/models/label-encoder.joblib \
  exoplanet-api:latest

Si quieres usar el puerto 8000 en lugar de 7860, ajusta el CMD del Dockerfile o lanza el contenedor con --entrypoint y ejecuta uvicorn manualmente.

Endpoints principales (API)

Base URL (si ejecutas localmente con uvicorn en 8000): http://localhost:8000

• —GET / — endpoint de prueba, devuelve si el modelo está listo.
• —GET /health — liveness probe.
• —GET /ready — readiness probe (200 solo si modelo y encoder cargados).
• —GET /model_metadata — devuelve la lista de features esperadas y las clases.
• —POST /predictcsvrow — recibir JSON con una sola fila (ver esquema abajo).
• —POST /predict_csv — subir CSV como multipart/form-data (varias filas).
• —POST /predictcsvraw — enviar CSV en el body (Content-Type: text/csv).

Esquema JSON para /predict_csv_row

Enviar un JSON con las columnas siguientes (todos numéricos):

koiprad, koidiccomsky, koidor, koimaxmultev, koimodelsnr, koimaxsngleev, koifwmstatsig, koinumtransits, koiror, koifwmsrao, koisrho, koiinsol, koiduration, koiteq, koi_period

Ejemplo mínimo usando curl:

curl -sS -X POST http://localhost:8000/predict_csv_row \
  -H "Content-Type: application/json" \
  -d '{"koi_prad":1.0,"koi_dicco_msky":0.5,"koi_dor":0.1,"koi_max_mult_ev":0.2,"koi_model_snr":10.0,"koi_max_sngle_ev":5.0,"koi_fwm_stat_sig":0.01,"koi_num_transits":3,"koi_ror":0.02,"koi_fwm_srao":0.1,"koi_srho":0.05,"koi_insol":1360.0,"koi_duration":2.5,"koi_teq":250.0,"koi_period":365.0}'

Respuesta esperada (ejemplo):

{
  "status": "success",
  "prediction": "FALSE POSITIVE",
  "probability_confirmed": 0.0099,
  "probability_false_positive": 0.9900,
  "model_used": "XGBoost (JSON)"
}

Subir CSV (varias filas)

Formato: CSV con encabezado que contenga exactamente las mismas columnas en la misma forma que la lista anterior. Ejemplo de petición multipart/form-data:

curl -sS -X POST http://localhost:8000/predict_csv \
  -F "file=@test_samples.csv;type=text/csv"

O enviar el CSV en el body (texto plano):

curl -sS -X POST http://localhost:8000/predict_csv_raw \
  -H "Content-Type: text/csv" \
  --data-binary @test_samples.csv

La respuesta es una lista de objetos con la misma estructura que el endpoint de fila única.

Troubleshooting / Preguntas frecuentes

• —"ERROR: No se encontró uno o más archivos." — revisa que models/model.json y models/label-encoder.joblib existan y que MODEL_PATH y ENCODER_PATH apunten a rutas accesibles.
• —Si la API devuelve 503 en /ready, el modelo o el encoder no cargaron correctamente; revisa los logs de arranque de uvicorn para ver la excepción.
• —Si recibes errores de conversión numérica, valida que el CSV o JSON solo contengan valores numéricos en las columnas esperadas.