app.main

  1#!/usr/bin/env python3
  2# -*- coding: utf-8 -*-
  3"""
  4Main Gradio Application Entry Point.
  5
  6This module serves as the main entry point for the Garbage Classifier
  7interactive demo. It orchestrates the creation of the Gradio interface,
  8combining data exploration, model training, and evaluation sections into
  9a unified web application with real-time carbon footprint tracking.
 10
 11Usage
 12-----
 13Command line:
 14    $ uv run python app/main.py
 15
 16The application will launch a Gradio interface accessible via web browser,
 17with an optional shareable link for remote access.
 18
 19Notes
 20-----
 21The application includes:
 22- Data Exploration: Visualize dataset statistics and prototypes
 23- Model Training: Train new models with custom hyperparameters
 24- Model Evaluation: Evaluate models and make predictions
 25- Carbon Tracking: Real-time display of cumulative carbon emissions
 26"""
 27__docformat__ = "numpy"
 28
 29import gradio as gr
 30from app.sections.data_exploration import data_exploration_tab
 31from app.sections.model_training import model_training_tab
 32from app.sections.model_evaluation import model_evaluation_tab
 33from source.utils import config as cfg
 34from source.utils.carbon_utils import format_total_emissions_display
 35from pathlib import Path
 36
 37
 38def get_emissions_path():
 39    """
 40    Get the path to the emissions CSV file.
 41
 42    Returns
 43    -------
 44    pathlib.Path
 45        Path object pointing to the emissions.csv file in the model directory.
 46
 47    Notes
 48    -----
 49    The emissions file is located in the same directory as the trained model
 50    checkpoint, as defined in the configuration.
 51    """
 52    return Path(cfg.MODEL_PATH).parent / "emissions.csv"
 53
 54
 55def update_carbon_display():
 56    """
 57    Update the carbon footprint display with latest emissions data.
 58
 59    Returns
 60    -------
 61    str
 62        HTML-formatted string containing the total carbon emissions statistics,
 63        including CO₂ equivalent mass and car distance equivalent.
 64
 65    Notes
 66    -----
 67    This function reads the emissions CSV file and formats the cumulative
 68    carbon footprint for display in the Gradio interface header.
 69    """
 70    return format_total_emissions_display(get_emissions_path())
 71
 72
 73def main():
 74    """
 75    Launch the main Gradio application interface.
 76
 77    Creates and configures a multi-tab Gradio interface with data exploration,
 78    model training, and evaluation capabilities. Includes a persistent carbon
 79    footprint counter in the header and custom CSS styling.
 80
 81    The interface includes:
 82    - Header with project title and carbon counter
 83    - Tab 1: Data Exploration (dataset visualization and analysis)
 84    - Tab 2: Training Interface (model training with custom parameters)
 85    - Tab 3: Model Evaluation (metrics visualization and inference)
 86
 87    Notes
 88    -----
 89    The application launches with `share=True`, which creates a public URL
 90    for remote access. Set to `False` for local-only access.
 91
 92    Custom CSS is injected to style the carbon counter with a gradient
 93    background and appropriate sizing.
 94
 95    See Also
 96    --------
 97    data_exploration_tab : Data exploration UI section
 98    model_training_tab : Model training UI section
 99    model_evaluation_tab : Model evaluation UI section
100    """
101    with gr.Blocks(title="Garbage Classifier Demo") as demo:
102        # Header with carbon counter
103        with gr.Row():
104            gr.Markdown("# 🗑️♻️ Garbage Classifier Interactive Demo")
105            carbon_display = gr.HTML(
106                value=update_carbon_display(), elem_id="carbon-counter"
107            )
108
109        # Tabs
110        with gr.Tabs():
111            with gr.Tab("Data Exploration"):
112                data_exploration_tab()
113
114            with gr.Tab("Training Interface"):
115                model_training_tab(carbon_display)
116
117            with gr.Tab("Model Evaluation"):
118                model_evaluation_tab(carbon_display)
119
120        # Add custom CSS for the carbon counter
121        demo.load(
122            fn=None,
123            js="""
124            function() {
125                const style = document.createElement('style');
126                style.textContent = `
127                    #carbon-counter {
128                        color: white !important;
129                        font-size: 1.0em;
130                        font-weight: bold;
131                        padding: 12px 20px;
132                        background: \
133                            linear-gradient(135deg, #667eea 0%, #764ba2 100%);
134                        border-radius: 8px;
135                        margin-left: auto;
136                        min-width: 500px;
137                        max-width: 800px;
138                    }
139                    #carbon-counter * {
140                        color: white !important;
141                    }
142                `;
143                document.head.appendChild(style);
144            }
145            """,
146        )
147
148    demo.launch(share=True)
149
150
151if __name__ == "__main__":
152    main()