Add app.py and setup files for Hugging Face Space

README.md

@@ -1,12 +1,198 @@
 ---
-title: Module3
-emoji: 📊
-colorFrom: purple
-colorTo: green
-sdk: gradio
-sdk_version: 6.0.0
-app_file: app.py
+title: "Coffee Cup Points Estimator"
+emoji: "☕️"
+colorFrom: "brown"
+colorTo: "green"
+sdk: "gradio"
+sdk_version: "5.49.1"
+app_file: "app.py"
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+
+
+# Module3Project
+
+# Overview 
+Predict coffee quality scores based on sensory attributes using a RandomForest model and an MLOps pipeline. 
+This project demonstrates an end-to-end MLOps pipeline: data ingestion, preprocessing, model training, containerization, cloud deployment, and front-end integration.
+
+# Data
+For this project, we are using data on coffee quality found here:
+https://www.kaggle.com/datasets/volpatto/coffee-quality-database-from-cqi
+
+The cleaned coffee dataset is publicly hosted on Google Cloud Storage for reproducibility.
+The preprocessing pipeline automatically downloads it via the data.url field in config.yaml.
+
+Cleaned data is hosted in Google Cloud Storage:
+https://storage.googleapis.com/coffee-quality-data/preprocessed_data.csv
+
+# Architecture 
+Data → Cloud (GCS) → Preprocess (ColumnTransformer) → Train (RandomForest) → FastAPI → Gradio frontend
+
+## Frontend Architecture 
+┌───────────────┐       ┌─────────────┐       ┌───────────────┐       ┌──────────────┐
+│  Kaggle Data  │  →    │  GCS Bucket │  →    │  FastAPI (API)│  →    │ Gradio UI    │
+└───────────────┘       └─────────────┘       └───────────────┘       └──────────────┘
+
+# Frontend 
+The Gradio-based frontend is deployed at: 
+
+# Cloud Deployment: 
+The FastAPI container is deployed on Google Cloud Run at:
+Base URL:
+https://coffee-api-354131048216.us-central1.run.app
+
+Endpoints:
+
+- /health – Health check
+- /predict_named – POST endpoint for predictions
+- /docs - API documentation (Swagger) 
+	
+Example cURL:
+```
+curl -X POST "https://coffee-api-354131048216.us-central1.run.app/predict_named" \
+  -H "Content-Type: application/json" \
+  -d '{"rows":[{"Aroma":7.5,"Flavor":6.0,"Body":5.5,"Acidity":8.0,"Sweetness":9.0,"Balance":7.0,"Aftertaste":6.5,"Clean.Cup":9.0}]}'
+```
+
+# Setup:
+```
+python -m venv venv
+source venv/bin/activate        # Windows: venv\Scripts\activate
+pip install --upgrade pip
+pip install -r requirements.txt
+```
+# Testing/running scripts
+To test preprocess.py: 
+```
+python scripts/preprocess.py
+```
+Confirm all output files exist by running: 
+```
+ls -l data/cleaned/X_train.csv data/cleaned/X_test.csv data/cleaned/y_train.csv data/cleaned/y_test.csv artifacts/preprocessor.joblib
+```
+We wrote a unit test script tests/test_preprocessor.py, to run it: 
+```
+pip install pytest
+pytest -q
+```
+
+To run the server, do health check use sample predict payload: 
+```
+uvicorn app.server:app --reload --port 8000 
+curl http://127.0.0.1:8000/health
+curl -X POST "http://127.0.0.1:8000/predict_named" \
+  -H "Content-Type: application/json" \
+  -d '{"rows":[ {"Aroma":7.5,"Flavor":6.0,"Number.of.Bags":1,"Category.One.Defects":0} ] }'
+```
+
+To train the model:
+```
+python scripts/train.py
+```
+Ensure artifacts/model.joblib was built
+
+To run the UI app start the server and type in CLI: 
+```
+python app/frontend.py
+Enter 3 when prompted:
+  wandb: (1) Create a W&B account
+  wandb: (2) Use an existing W&B account
+  wandb: (3) Don't visualize my results
+  My personal login is needed to sign in here to update to wandb website
+
+```
+Open link in browser
+
+# Model
+We used a RandomForestRegression for the model. Test size is 20% of dataset. Model has accuracy of 94.2% with 100 estimators.
+
+W and B tracks model performance. Data can be found in wandb/run.../files/wandb-summary.json. Data is presented like this:
+```
+{
+  "_timestamp":1.763876781125257e+09,
+  "_wandb":{"runtime":2},
+  "_runtime":2,
+  "_step":0,
+  "R2":0.9424069488737763,
+  "RMSE":0.5528660703704987,
+  "MAE":0.31615526315789416,
+  "MAPE":0.39006294567905464
+}
+```
+These perfomance metrics are also stored in artifacts.metrics.json like this:
+```
+{
+    "R2": 0.9424069488737761,
+    "RMSE": 0.5528660703704994,
+    "MAE": 0.31615526315789455,
+    "MAPE": 0.39006294567905514
+}
+```
+The 94.2% R2 value shows very good fit and a cup score that correlates strongly with the other columns. The RMSE 0f 0.55 shows a small predicition error and therefore reinforces the model's high preformance.  The MAE of 0.314 also shows a small error to the actual cup points. MAPE shows average percentage error of 39% which shows medium accuracy. This could be due to the small size dataset the model was trained on.
+
+# 🐳 Docker and Testing 
+## Build the image 
+```
+# from the project root
+docker build -t coffee-api:dev .
+docker run --rm -e WANDB_MODE=offline -p 8000:8000 coffee-api:dev
+```
+Note: Use WANDB_MODE=offline (as shown above) when running inside Docker or CI to prevent login prompts from Weights & Biases. If you have a W&B API key, set it via WANDB_API_KEY=your_key to enable cloud logging.
+
+## Run the container 
+```
+docker run --rm -p 8000:8000 \
+  -v "$(pwd)/artifacts":/app/artifacts \
+  -v "$(pwd)/config.yaml":/app/config.yaml \
+  -v "$(pwd)/data":/app/data \
+  coffee-api:dev
+```
+Then open:
+	•	Health check: http://127.0.0.1:8000/health
+	•	Interactive docs: http://127.0.0.1:8000/docs
+
+If artifacts are missing, the container automatically runs scripts/preprocess.py to generate them.
+
+## Run tests inside the container 
+
+To verify reproducibility of preprocessing and data pipeline:
+```
+docker run --rm -v "$(pwd)":/app -w /app coffee-api:dev python -m pytest -q
+```
+Expect output: 
+```
+...
+3 passed in ~0.9s
+```
+
+## Docker-related notes: 
+- Ports: container exposes 8000 (mapped to host port 8000)
+- Artifacts (preprocessor.joblib, model.joblib) are mounted from the host for faster iteration
+
+# Limitations & Ethics
+Predictions depend on sensory ratings, which are subjective.
+The model is not suitable for real-world evaluation of coffee quality without expert calibration.
+The dataset may contain sampling bias by country or producer, and model predictions should not be used for commercial grading without calibration against expert cuppers.
+
+# Notes / Gotchas
+- config.yaml may include data.input_columns — if present the server will require/expect those columns and reindex incoming payloads automatically. 
+- The server will try to load artifacts/preprocessor.joblib and artifacts/model.joblib. If those are missing the server returns deterministic dummy predictions (development mode).
+
+# ☁️ Cloud Services Used
+- **Google Cloud Storage (GCS):** Stores the cleaned dataset (`preprocessed_data.csv`) publicly.
+- **Google Cloud Run:** Hosts and serves the FastAPI model API container.
+- **Weights & Biases (W&B):** Tracks model training metrics and performance.
+
+# Hugging Face
+
+# 🧠 Authors
+- Eugenia Tate
+- Avery Estopinal
+
+# References: 
+- OpenAI. (2025). ChatGPT (Version 5.1) [Large language model]. https://chat.openai.com We used ChatGPT (OpenAI GPT-5.1) to assist with code snippets. 
+Portions of the preprocessing, frontend, train and most of server code were assisted by ChatGPT (OpenAI GPT-5.1). Authors verified and adapted the generated code. 
+Authors fully understand what the code does and how to apply the knowledge in the future.
+- Kaggle Coffee Quality Data (Volpatto, 2020) https://www.kaggle.com/datasets/volpatto/coffee-quality-database-from-cqi 

app.py

@@ -0,0 +1,251 @@
+# app/frontend.py  
+# Author: Eugenia Tate 
+# Date: 11/23/2025
+
+# CITATION: 
+# ChatGPT was used to prototype robust JSON-sanitization and input-coercion logic when encountering serialization errors 
+# and mixed user inputs (strings, noisy numeric text, pandas / numpy scalars). A recursive approach and conversion patterns 
+# were suggested; we reviewed and thoroughly tested the code locally. See coerce_and_clamp_dict() and make_json_safe() below. 
+
+# import necessary helpers 
+import os
+import yaml
+import json
+import math
+import pandas as pd, numpy as np  # table handling 
+import gradio as gr   # UI 
+import requests   # to call API server 
+from typing import Dict, Any, List
+
+# point to config.yaml file to retrieve API URL 
+CONFIG_PATH = os.path.join(os.getcwd(), "config.yaml")
+# The above line was modified by ChatGPT 5.1 at 10:41a on 11/24/25 to work with Hugging Face
+# if config exists - load it 
+if os.path.exists(CONFIG_PATH):
+    with open(CONFIG_PATH, "r") as f:
+        cfg = yaml.safe_load(f)
+# if config does not exist - it falls back to being an empty dict
+else:
+    cfg = {}
+
+# server endpoint UI will use for POST; if confid is missing fallback to predict_named
+API_URL = cfg.get("api_url", {}).get("FastAPI", "http://127.0.0.1:8000/predict_named")
+
+# reduced set of sensible columns exposed in UI to the end user
+INPUT_COLS = [
+    "Aroma", "Flavor", "Aftertaste", "Acidity",
+    "Body", "Balance", "Sweetness", "Clean.Cup"
+]
+# help text for the end user explaining Clean Cup feature
+CLEAN_CUP_HELP = (
+    "Clean.Cup indicates the absence of off-flavors or defects (higher is better). "
+    "Typically scored on the same sensory scale as other cup attributes."
+)
+# enforcing 0 to 10 possible values for input 
+RANGES = {c: (0.0, 10.0) for c in INPUT_COLS}
+
+# ------------------------------------ CITED BLOCK --------------------------------------------------------------------
+# implemented using ChatGPT (conversation 2025-11-23) to help normalize free-form user input into numeric values within range
+# convert user values to allowed 0 - 10 range to avoid errors/crashes: handles blanks, strings, noisy input by stripping chars 
+# and sets None for missing / invalid entries (JSON's null)
+def coerce_and_clamp_dict(row: Dict[str, Any]) -> Dict[str, Any]:
+    # out = {}
+    out: Dict[str, Any] = {}
+    # iterates over 8 input columns 
+    for k in INPUT_COLS:
+        v = row.get(k, "")
+        # if a value user types is blank or string - converts it into np.nan
+        # or if user types something like "7.5pts" it strips the letters and keeps the number 
+        if v is None or (isinstance(v, str) and v.strip() == ""):
+            # out[k] = np.nan
+            out[k] = None
+            continue
+        # tries to convert to float 
+        fv = None
+        try:
+            fv = float(v)
+        except Exception:
+            # try to strip out non-digit characters (e.g. "7.5pts" -> "7.5")
+            try:
+                cleaned = "".join(ch for ch in str(v) if (ch.isdigit() or ch in ".-"))
+                fv = float(cleaned) if cleaned not in ("", ".", "-") else None
+            except Exception:
+                fv = None
+        # if conversion failed -> None
+        if fv is None or (isinstance(fv, float) and (math.isnan(fv) or math.isinf(fv))):
+            out[k] = None
+            continue
+        # once we have a clean numeric - it is clamped to be within [0,10] range of valid inputs 
+        # if user typed 13 it will be clmaped to 10
+        # if user typed -2 it will become 0
+        lo, hi = RANGES.get(k, (None, None))
+        if lo is not None and hi is not None:
+            fv = max(lo, min(hi, fv))
+        out[k] = float(fv)
+    # returns a clean dict to be sent to server 
+    return out
+
+# ChatGPT 5.1 used to prototype this recursive JSON-sanitizer 
+# This function recursively walks nested containers (dicts, lists, tuples) and ensures any nested 
+# structure (e.g. {"payload": [{"Aroma": np.nan}]}) becomes JSON-safe everywhere, not just the top level
+def make_json_safe(obj):
+    # dict
+    if isinstance(obj, dict):
+        return {k: make_json_safe(v) for k, v in obj.items()}
+    # list/tuple
+    if isinstance(obj, (list, tuple)):
+        return [make_json_safe(v) for v in obj]
+    # numpy scalar -> python scalar
+    try:
+        import numpy as _np
+        if isinstance(obj, _np.generic):
+            return make_json_safe(obj.item())
+    except Exception:
+        pass
+    # floats: map NaN/Inf -> None
+    if isinstance(obj, float):
+        if math.isnan(obj) or math.isinf(obj):
+            return None
+        return float(obj)
+    # ints, bool, str, None: ok
+    if isinstance(obj, (int, bool, str)) or obj is None:
+        return obj
+    # fallback
+    try:
+        return str(obj)
+    except Exception:
+        return None
+    
+
+# ------------------------------------------ END CITED BLOCK ------------------------------------------------
+
+# helper function that returns True if every value in a row is null or numeric 0, otherwise - False
+def _row_is_all_null_or_zero(row: Dict[str, Any]) -> bool:
+    for v in row.values():
+        # missing/null -> keep scanning (counts as "no numeric input")
+        if v is None:
+            continue
+        # numeric non-zero -> row is VALID
+        if isinstance(v, (int, float)) and v != 0:
+            return False
+        # anything else (string, etc) is considered missing/invalid; continue 
+        # but coerce_and_clamp_dict should have converted those to None or numeric
+    return True
+
+# sends JSON to server endpoint, returns a tuple (predictions list, raw resposnse/error)
+def call_api_named(payload_rows: List[Dict[str, Any]]):
+    # sanitize payload so it's JSON-serializable and uses `null` for missing
+    safe_body = {"rows": make_json_safe(payload_rows)}
+    try:
+        payload_str = json.dumps(safe_body)
+    except Exception as e:
+        return None, f"Serialization error: {e}"
+    # tries calling POST to get predictions using requests lib
+    headers = {"Content-Type": "application/json"}
+    try:
+        response = requests.post(API_URL, data=payload_str, headers=headers, timeout=10)   # timeout at 10 sec to avoid hanging 
+        response.raise_for_status()
+        # returns prediction list and full raw text response to be used within debug box on SUCCESS (200 OK) 
+        return response.json().get("predictions", []), response.text
+    except Exception as e:
+        return None, f"API error: {e}"   # on error return None 
+
+#prettifies prediction and debug JSON 
+def predict_from_rows_of_dicts(rows_of_dicts: List[Dict[str, Any]]):
+    payload_rows = [coerce_and_clamp_dict(row) for row in rows_of_dicts]
+    # decide whether submission is allowed:
+    # - if every submitted row is all-null-or-zero, refuse
+    all_rows_invalid = all(_row_is_all_null_or_zero(r) for r in payload_rows)
+    if all_rows_invalid:
+        debug = {"payload": payload_rows, "response_raw": "skipped - all values missing or zero"}
+        return "Please enter at least one numeric attribute (non-zero) before submitting.", json.dumps(debug, indent=2)
+    # Otherwise proceed and call API (allowed if at least one row has a non-zero numeric)
+    preds, raw = call_api_named(payload_rows)
+    # building a debug dictionary containing both payload and raw server response
+    debug = {"payload": payload_rows, "response_raw": raw}
+    # if API fails - return empty prediction and debug JSON for debugging 
+    if preds is None:
+        return "", json.dumps(debug, indent=2)
+    # prettifying predictions upon successful call to be user-friendly 
+    prettified_pred = [f"Predicted Coffee Quality Points = {round(float(p), 1)}" for p in preds]   # rounding predictions to 1 decimal place (user friendly)
+    #returns prettified prediction and debug JSON for debug box 
+    return "\n".join(prettified_pred), json.dumps(debug, indent=2)
+
+
+def predict_from_table(table):
+    rows_of_dicts = table_to_list_of_dicts(table)
+    return predict_from_rows_of_dicts(rows_of_dicts)
+
+
+# ------------------------------------ CITED BLOCK -------------------------------------
+# ChatGPT was used on 11/23/2025 to fix this function due to encountering errors to help deal 
+# with 2 possible incoming formats: Dataframe and list of lists. 
+
+# helper function puts input into proper expected by server format of list-of-dicts keyed by INPUT_COLS:
+# [{"Aroma": 7.5, "Flavor": 8.0, ...}]; 
+# fills missing columns with empty strings so coerce_and_clamp_dict() can convert them to np.nan
+def table_to_list_of_dicts(table):
+    # if table passed in is an instance of Dataframe obj - turn it into a dict 
+    if isinstance(table, pd.DataFrame):
+        df = table
+        return [df.iloc[i].to_dict() for i in range(len(df))]
+    # else - assume table is a list of lists and manually pair each element to corresponding column 
+    rows = []
+    for row in table:
+        # ensure row has right length
+        vals = list(row) + [""] * max(0, len(INPUT_COLS) - len(row))
+        rows.append({col: vals[i] for i, col in enumerate(INPUT_COLS)})
+    return rows
+# ------------------------------- END CITED BLOCK -------------------------------------------
+
+
+# -------------------------------- Gradio UI ------------------------------------------------------
+with gr.Blocks(title="Coffee Quality Points Estimator") as demo:
+    # inline HTML/CSS to style user instructions 
+    gr.Markdown("<h1 style='text-align:center;color:#08306B'>Coffee Quality Points Estimator</h1>")
+    gr.Markdown(
+        "<div style='font-size:17px;font-weight:700;color:#2b6cb0'>"
+        "Instructions: Fill the known sensory attributes (0–10). Leave unknowns blank and the model will "
+        "attempt to infer missing values. Then click <b style='color:#ff6600'>Submit</b> to estimate the "
+        "<b>Coffee Quality Points</b> (Total.Cup.Points). Higher scores mean better coffee quality.</div>"
+    )
+
+    with gr.Row():
+        # presents 1 row by default with INPUT_COLS 
+        df_input = gr.Dataframe(
+            headers=INPUT_COLS,
+            value=[["" for _ in INPUT_COLS]],    # list of lists to avoid validation errors encountered on testing 
+            # ------------------------- ChatGPT 5.1 was used to fix the issues on 11/23/2025 ---------------------
+            row_count=1,
+            col_count=len(INPUT_COLS),
+            interactive=True,
+            label="Enter Known Columns (0–10 range; numeric values preferred)"
+        )
+
+    with gr.Row():
+        submit_btn = gr.Button("Submit", variant="primary")
+
+    with gr.Row():
+        # short prediction for the user 
+        pred_out = gr.Textbox(label="Predicted Coffee Quality Points", lines=1, interactive=False)
+
+    with gr.Row():
+        # full debug info for developer 
+        debug_out = gr.Textbox(label="Debug (payload + raw response)", lines=10, interactive=False)
+
+    with gr.Row():
+        gr.Markdown(f"<b>Note:</b> <i>{CLEAN_CUP_HELP}</i>")
+
+    # When user clicks Submit, Gradio sends the contents of the table to table_to_list_of_dicts(). 
+    # the content can either be a Dataframe or list of lists and the helper function can handle both
+    # making the format consistent with FastAPI expectations
+    def submit_table(table):
+        rows_of_dicts = table_to_list_of_dicts(table)
+        return predict_from_rows_of_dicts(rows_of_dicts)
+    
+    # fires up the actual prediction
+    submit_btn.click(predict_from_table, inputs=[df_input], outputs=[pred_out, debug_out])
+
+if __name__ == "__main__":
+    # auto opens the demo in browser 
+    demo.launch()

config.yaml

@@ -0,0 +1,73 @@
+data:
+# url empty for now so script will default to local file; modify later as needed
+  url: "https://storage.googleapis.com/coffee-quality-data/preprocessed_data.csv"
+  local_path: "data/raw/raw_data.csv"
+  preprocessed_path: "data/preprocessed/preprocessed_data.csv"
+  target: "Total.Cup.Points"
+  input_columns:
+  - Number.of.Bags
+  - Category.One.Defects
+  - Category.Two.Defects
+  - Aroma
+  - Flavor
+  - Aftertaste
+  - Acidity
+  - Body
+  - Balance
+  - Uniformity
+  - Clean.Cup
+  - Sweetness
+  - Cupper.Points
+  - Moisture
+  - Quakers
+  - altitude_low_meters
+  - altitude_high_meters
+  - altitude_mean_meters
+  - Species
+  - Owner
+  - Country.of.Origin
+  - Mill
+  - ICO.Number
+  - Company
+  - Altitude
+  - Region
+  - Producer
+  - Bag.Weight
+  - In.Country.Partner
+  - Harvest.Year
+  - Grading.Date
+  - Owner.1
+  - Variety
+  - Processing.Method
+  - Color
+  - Expiration
+  - Certification.Body
+  - Certification.Address
+  - Certification.Contact
+  - unit_of_measurement
+  
+# model details to be added later during train.py work 
+train:
+  test_size: 0.2
+  random_state: 42
+  model_params:
+    n_estimators: 100
+    random_state: 42
+    n_jobs: -1
+
+paths:
+  X_train: "data/cleaned/X_train.csv"
+  X_test: "data/cleaned/X_test.csv"
+  y_train: "data/cleaned/y_train.csv"
+  y_test: "data/cleaned/y_test.csv"
+  
+artifacts:
+  model: "artifacts/model.joblib"
+  preprocessor: "artifacts/preprocessor.joblib"
+  metrics: "artifacts/metrics.json"
+# The above snippet was generated by chatGPT 5.1 at 10:20p at 11/20/25.
+
+api_url:
+  # FastAPI: "http://127.0.0.1:8000/predict_named"
+  FastAPI: "https://coffee-api-354131048216.us-central1.run.app/predict_named" 
+

requirements.txt

@@ -0,0 +1,14 @@
+fastapi>=0.95
+uvicorn[standard]>=0.22.0
+pydantic>=1.10
+PyYAML==6.0
+joblib==1.3.2
+scikit-learn==1.7.2
+numpy==1.26.4
+pandas==2.2.2
+gradio==3.41.0
+requests==2.31.0
+wandb==0.23.0
+
+# test / dev tools
+pytest>=7.4