hydroloom-ai

Hydroloom AI: Water Quality Index & Behavioral Clustering Platform

Hydroloom is a production-grade machine learning system for physical hydrological simulation, consumer water-use behavioral clustering, and supervised Water Quality Index (WQI) forecasting.

Architecture

• Supervised WQI Service: Multi-model regressors (LightGBM, XGBoost, CatBoost, Regularized Linear) + Level-1 Out-of-Fold (OOF) Stacking & Constrained Weighted Blending with AR(1) Residual Error Correction.
• Unsupervised Clustering Service: 4-archetype K-Means clustering ($k=4$) mapping consumer profiles (Conservationist, Average, Landscape Heavy, High Volume).
• Physical Hydrological Simulator: SCS Curve Number runoff, Markov-chain precipitation, and first-flush contaminant washoff kinetics.

Repository Contents

• artifacts/: Checkpoint weights, scalers, preprocessors, Optuna candidate registries, and SHAP explainers for North and South hemispheres.
• clustering_models/: Serialized K-Means models (kmeans_north_k4.joblib, kmeans_south_k4.joblib).
• metadata/: Evaluation metrics, lead-lag correlations, and feature importance registries.

Usage with Python

from huggingface_hub import hf_hub_download
import joblib

# Load clustering model
model_path = hf_hub_download(
    repo_id="tuboa2/hydroloom-ai",
    repo_type="model",
    filename="clustering_models/kmeans_north_k4.joblib"
)
kmeans_north = joblib.load(model_path)