Spaces:
Sleeping
Sleeping
| title: GreenPath AI Emission Tracker | |
| emoji: 🌿 | |
| colorFrom: green | |
| colorTo: blue | |
| sdk: streamlit | |
| sdk_version: "1.28.1" | |
| app_file: app.py | |
| pinned: true | |
| # 🌱 GreenPath: AI & Data Analytics Platform for Reducing Shipment CO₂ Emissions | |
| **Designed and Developed by Sayed Mohd Zayeem Khateeb** | |
| [](https://www.python.org/downloads/) | |
| [](https://streamlit.io/) | |
| [](https://fastapi.tiangolo.com/) | |
| ## 🎯 Overview | |
| GreenPath is an **AI-powered platform** that helps logistics and supply chain companies **measure, analyze, and reduce CO₂ emissions per shipment** while recommending **optimized delivery routes** that minimize emissions without significantly affecting delivery time or cost. | |
| ### 🏆 Key Achievements | |
| - **22% reduction in CO₂ emissions** through green route optimization | |
| - **Real-time emission tracking** with IPCC-compliant calculations | |
| - **Multi-objective optimization** balancing emissions, cost, and delivery time | |
| - **Professional dashboard** with eco-friendly design and advanced analytics | |
| ## 🌟 Core Features | |
| ### 1. 🧮 CO₂ Emission Calculator | |
| - **Formula-based estimation**: `CO₂ = Distance × Weight × EmissionFactor` | |
| - **Multiple transport modes**: Road, Rail, Air, Ship (Container & Bulk) | |
| - **IPCC 2019 Guidelines compliance** for emission factors | |
| - **Carbon tax cost calculation** with customizable rates | |
| ### 2. 🗺️ Green Route Recommendation Engine | |
| - **OpenRouteService API integration** for accurate routing | |
| - **Multi-modal transport optimization** (truck + rail combinations) | |
| - **Time constraint balancing** (max 10% time penalty for green options) | |
| - **Emission reduction visualization** with percentage improvements | |
| ### 3. 📊 Analytics Dashboard | |
| - **Professional eco-friendly design** (green accents, clean layout) | |
| - **Real-time KPIs**: Total emissions, reduction percentage, carbon tax savings | |
| - **Interactive visualizations**: Transport mode comparison, emission trends | |
| - **Regional analysis** and performance metrics | |
| ### 4. 📈 Business Impact Simulation | |
| - **Scenario analysis**: "What if X% shipments use optimized routes?" | |
| - **Financial impact**: Carbon tax savings and ESG score improvement | |
| - **ROI calculations** for sustainability investments | |
| - **Regulatory compliance** readiness assessment | |
| ### 5. 📋 Comprehensive Reporting | |
| - **PDF reports** with executive summaries and recommendations | |
| - **Excel exports** with detailed shipment data and analytics | |
| - **Downloadable formats** for management review and compliance | |
| ## 🚀 Quick Start | |
| ### Option 1: Streamlit Web App (Recommended) | |
| ```bash | |
| # Clone the repository | |
| git clone https://github.com/zayeemskhateeb-cloud/greenpath-ai-emission-tracker.git | |
| cd greenpath-ai-emission-tracker | |
| # Install dependencies | |
| pip install -r requirements.txt | |
| # Run the Streamlit app | |
| streamlit run streamlit_app.py | |
| # Access at http://localhost:8501 | |
| ``` | |
| ### Option 2: FastAPI Backend + Frontend | |
| ```bash | |
| # Terminal 1: Start FastAPI backend | |
| cd src/api | |
| python main.py | |
| # Backend available at http://localhost:8000 | |
| # Terminal 2: Start Streamlit frontend | |
| streamlit run streamlit_app.py | |
| # Frontend available at http://localhost:8501 | |
| ``` | |
| ### Option 3: Docker Deployment | |
| ```bash | |
| # Build and run with Docker Compose | |
| docker-compose up -d | |
| # Access services: | |
| # - Streamlit: http://localhost:8501 | |
| # - FastAPI: http://localhost:8000 | |
| # - API Docs: http://localhost:8000/docs | |
| ``` | |
| ## 🛠️ Technology Stack | |
| ### Backend & AI | |
| - **Python 3.8+** - Core programming language | |
| - **FastAPI** - High-performance API framework | |
| - **SQLAlchemy** - Database ORM with SQLite | |
| - **Pandas & NumPy** - Data processing and analytics | |
| - **Scikit-learn** - Machine learning capabilities | |
| ### Frontend & Visualization | |
| - **Streamlit** - Interactive web application framework | |
| - **Plotly** - Advanced data visualizations | |
| - **Folium** - Interactive maps for route visualization | |
| - **Custom CSS** - Professional eco-friendly design | |
| ### APIs & Integration | |
| - **OpenRouteService** - Route optimization and geocoding | |
| - **IPCC Emission Factors** - Scientifically accurate CO₂ calculations | |
| - **RESTful APIs** - Seamless integration capabilities | |
| ### Reports & Export | |
| - **ReportLab** - Professional PDF report generation | |
| - **OpenPyXL** - Excel export functionality | |
| - **Custom templates** - Branded report formats | |
| ## 📁 Project Structure | |
| ``` | |
| greenpath-ai-emission-tracker/ | |
| ├── src/ | |
| │ ├── api/ # FastAPI backend | |
| │ │ └── main.py # API endpoints and logic | |
| │ ├── emissions/ # CO₂ calculation engine | |
| │ │ └── emission_calculator.py | |
| │ ├── route_optimizer/ # Green route optimization | |
| │ │ └── green_route_optimizer.py | |
| │ ├── database/ # Data models and storage | |
| │ │ └── models.py | |
| │ └── reports/ # Report generation | |
| │ └── report_generator.py | |
| ├── streamlit_app.py # Main Streamlit application | |
| ├── requirements.txt # Python dependencies | |
| ├── docker-compose.yml # Container orchestration | |
| ├── .env.example # Environment variables template | |
| └── README.md # This file | |
| ``` | |
| ## 🔧 Configuration | |
| ### 1. Environment Setup | |
| ```bash | |
| # Copy environment template | |
| cp .env.example .env | |
| # Add your API keys (optional for basic functionality) | |
| OPENROUTESERVICE_API_KEY=your_key_here | |
| DATABASE_URL=sqlite:///greenpath.db | |
| ``` | |
| ### 2. API Keys (Optional) | |
| - **OpenRouteService**: For enhanced routing (free tier available) | |
| - **No API keys required** for basic emission calculations and demo functionality | |
| ### 3. Database | |
| - **SQLite** (default): Automatic setup, no configuration needed | |
| - **PostgreSQL**: Update DATABASE_URL in .env for production | |
| ## 📊 Usage Examples | |
| ### Emission Calculator | |
| ```python | |
| from src.emissions.emission_calculator import EmissionCalculator, TransportMode | |
| calculator = EmissionCalculator() | |
| # Calculate emissions for a truck shipment | |
| result = calculator.calculate_emissions( | |
| distance_km=500, | |
| weight_tonnes=2.5, | |
| transport_mode=TransportMode.ROAD_TRUCK | |
| ) | |
| print(f"CO₂ Emissions: {result['co2_emissions_kg']} kg") | |
| # Output: CO₂ Emissions: 77.5 kg | |
| ``` | |
| ### Route Optimization | |
| ```python | |
| from src.route_optimizer.green_route_optimizer import GreenRouteOptimizer | |
| optimizer = GreenRouteOptimizer() | |
| # Get green route recommendations | |
| recommendations = optimizer.recommend_green_routes( | |
| origin="New York, NY", | |
| destination="Los Angeles, CA", | |
| weight_tonnes=5.0 | |
| ) | |
| print(f"Greenest option: {recommendations['summary']['greenest_option']}") | |
| ``` | |
| ## 📈 Business Impact | |
| ### Environmental Benefits | |
| - **Up to 22% reduction** in CO₂ emissions per shipment | |
| - **IPCC-compliant** emission calculations for accurate reporting | |
| - **Carbon footprint tracking** with detailed analytics | |
| - **ESG score improvement** through sustainability metrics | |
| ### Financial Benefits | |
| - **Carbon tax savings**: Potential $1,250+ monthly savings | |
| - **Regulatory compliance**: Readiness for emission regulations | |
| - **Operational efficiency**: Optimized route planning | |
| - **Brand reputation**: Enhanced sustainability profile | |
| ### Operational Benefits | |
| - **Real-time monitoring** of emission performance | |
| - **Data-driven decisions** with comprehensive analytics | |
| - **Scalable solution** for growing logistics operations | |
| - **Integration-ready** APIs for existing systems | |
| ## 🎨 Design Philosophy | |
| ### Eco-Friendly Theme | |
| - **Primary Color**: 🌱 Green (#2ECC71) for sustainability focus | |
| - **Secondary**: ⚪ Clean whites and soft greys (#F8F9FA) | |
| - **Accent**: 🔵 Professional navy (#34495E) for trust | |
| - **Typography**: Modern sans-serif fonts (Roboto, Inter) | |
| ### User Experience | |
| - **Minimalist design** with purpose-driven interfaces | |
| - **Mobile responsive** layout for all devices | |
| - **Intuitive navigation** with clear visual hierarchy | |
| - **Professional aesthetics** suitable for enterprise use | |
| ## 🚀 Deployment Options | |
| ### 1. Streamlit Cloud (Recommended) | |
| ```bash | |
| # Push to GitHub and deploy via Streamlit Cloud | |
| # Automatic deployment with GitHub integration | |
| ``` | |
| ### 2. Heroku | |
| ```bash | |
| # Deploy to Heroku with Procfile | |
| echo "web: streamlit run streamlit_app.py --server.port=\$PORT --server.address=0.0.0.0" > Procfile | |
| git add . && git commit -m "Deploy to Heroku" | |
| heroku create your-app-name | |
| git push heroku main | |
| ``` | |
| ### 3. Docker Production | |
| ```bash | |
| # Production deployment with Docker | |
| docker-compose -f docker-compose.prod.yml up -d | |
| ``` | |
| ## 📋 API Documentation | |
| ### FastAPI Endpoints | |
| - **GET** `/` - Health check and API information | |
| - **POST** `/calculate-emissions` - Calculate CO₂ emissions | |
| - **GET** `/compare-transport-modes` - Compare emission factors | |
| - **POST** `/optimize-route` - Get green route recommendations | |
| - **POST** `/scenario-analysis` - Business impact simulation | |
| - **GET** `/emission-factors` - IPCC emission factors reference | |
| ### Interactive API Docs | |
| Access comprehensive API documentation at `http://localhost:8000/docs` when running the FastAPI backend. | |
| ## 🧪 Testing & Validation | |
| ### Emission Calculations | |
| - **IPCC 2019 Guidelines** compliance verification | |
| - **Transport mode accuracy** testing with real-world data | |
| - **Carbon tax calculations** with multiple rate scenarios | |
| ### Route Optimization | |
| - **Multi-modal efficiency** testing across different distances | |
| - **Time penalty validation** within acceptable limits | |
| - **Cost-benefit analysis** for optimization recommendations | |
| ## 🤝 Contributing | |
| We welcome contributions to improve GreenPath! Here's how to get started: | |
| 1. **Fork the repository** | |
| 2. **Create a feature branch**: `git checkout -b feature/AmazingFeature` | |
| 3. **Commit your changes**: `git commit -m 'Add AmazingFeature'` | |
| 4. **Push to the branch**: `git push origin feature/AmazingFeature` | |
| 5. **Open a Pull Request** | |
| ### Development Guidelines | |
| - Follow **PEP 8** Python style guidelines | |
| - Add **comprehensive docstrings** for new functions | |
| - Include **unit tests** for new features | |
| - Update **documentation** for API changes | |
| ## 📄 License | |
| This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details. | |
| ## 👨💻 Author | |
| **Sayed Mohd Zayeem Khateeb** | |
| - 🌐 **GitHub**: [@zayeemskhateeb-cloud](https://github.com/zayeemskhateeb-cloud) | |
| - 💼 **LinkedIn**: [Sayed Mohd Zayeem Khateeb](https://www.linkedin.com/in/zayeemkhateeb) | |
| - 📧 **Email**: [zayeem.s.khateeb@gmail.com](mailto:zayeem.s.khateeb@gmail.com) | |
| ## 🙏 Acknowledgments | |
| - **IPCC** for emission factor guidelines and methodology | |
| - **OpenRouteService** for routing and geocoding services | |
| - **Streamlit** for the amazing web app framework | |
| - **FastAPI** for high-performance API development | |
| - **Open-source community** for excellent libraries and tools | |
| ## 🌟 Star History | |
| If you find GreenPath helpful for your sustainability goals, please ⭐ **star this repository**! | |
| --- | |
| <div align="center"> | |
| **🌱 GreenPath - Making Logistics Sustainable, One Route at a Time** | |
| *Designed with ❤️ for a greener future* | |
| </div> | |