README.md

metadata

title: EcoLogits Chat
emoji: 🌱
colorFrom: green
colorTo: blue
sdk: gradio
sdk_version: 4.44.0
app_file: app.py
pinned: false
license: mit
short_description: Mistral tracking environmental impact real-time
suggested_hardware: cpu-basic
suggested_storage: small
tags:
  - mistral
  - ecologits
  - environment
  - sustainability
  - ai-chat
  - carbon-footprint
  - energy-consumption
python_version: 3.12
fullWidth: true
header: default

EcoLogits - AI Environmental Impact Tracker

A clean, modular chat application that tracks the environmental impact of AI model usage using EcoLogits library and Mistral AI models.

🌱 Overview

This application provides a user-friendly interface to chat with Mistral AI models while tracking their environmental impact in real-time. It displays energy consumption and carbon footprint for each conversation, promoting awareness of AI's environmental costs.

✨ Features

• Clean Chat Interface: Simple Gradio-based web interface with tabbed impact tracking
• Environmental Tracking: Real-time tracking of energy usage and carbon emissions using EcoLogits
• Smart Model Filtering: Automatically filters to show only text-to-text capable models (excludes OCR, embedding, vision models)
• Tabbed Impact Visualization:
  • 🎯 Last Message: Impact of the specific last request with warnings/errors
  • 📈 Total Session: Cumulative environmental metrics across the entire session
• Warning System: Shows EcoLogits warnings and errors conditionally in the UI
• Modular Architecture: Clean separation of concerns across multiple files
• Session Management: Clear conversation and reset impacts with the "Effacer tout" button

🏗️ Architecture

The application is organized into focused, reusable modules:

├── app.py                 # Main application entry point
├── config.py             # Configuration and environment variables
├── mistral_client.py     # Mistral API wrapper with EcoLogits integration
├── impacts_tracker.py    # Environmental impact tracking and calculations
├── chat_interface.py     # Gradio UI components and user interaction
└── app_original.py       # Backup of original monolithic version

Module Responsibilities

• config.py: Centralized configuration management, environment variables, fallback models
• mistral_client.py: Handles Mistral API communication, intelligent model filtering, EcoLogits integration
• impacts_tracker.py: Tracks and calculates cumulative environmental impacts
• chat_interface.py: Manages the Gradio web interface with tabbed impact display
• app.py: Simple entry point that ties everything together

🚀 Setup

Prerequisites

• Python 3.8+
• Mistral AI API key

Installation

1. Clone or download the project files

2. Create a virtual environment:

   python -m venv .venv
   

3. Activate the virtual environment:

   # Windows
   .venv\Scripts\Activate.ps1
   
   # Linux/Mac
   source .venv/bin/activate
   

4. Install dependencies:

   pip install gradio mistralai ecologits python-dotenv
   

5. Set up environment variables:

   Create a .env file in the project root:

   MISTRAL_API_KEY=your_mistral_api_key_here
   

   Or set the environment variable directly:

   # Windows
   $env:MISTRAL_API_KEY="your_mistral_api_key_here"
   
   # Linux/Mac
   export MISTRAL_API_KEY="your_mistral_api_key_here"
   

Getting a Mistral API Key

1. Visit Mistral AI Console
2. Create an account or sign in
3. Navigate to API Keys section
4. Create a new API key
5. Copy the key and add it to your .env file

🎯 Usage

Running the Application

1. Activate your virtual environment:

   .venv\Scripts\Activate.ps1
   

2. Run the application:

   python app.py
   

3. Open your browser to the displayed URL (typically http://127.0.0.1:7860)

Using the Interface

1. Select a Model: Choose from available text-to-text Mistral models (automatically filtered)
2. Start Chatting: Enter your message and click Send
3. Monitor Impact: Use the tabs to view different impact metrics:
   • 🎯 Dernier message: Impact of your last request + any EcoLogits warnings/errors
   • 📈 Session totale: Cumulative impact across the entire conversation
4. Track Progress: See real-time energy and carbon consumption updates
5. Clear Session: Use "🗑️ Effacer tout" to start fresh and reset all impacts

📊 Environmental Metrics

The application tracks and displays:

• Energy Consumption: Measured in kilowatt-hours (kWh)
• Carbon Emissions: CO2 equivalent emissions in grams
• Cumulative Totals: Running totals across the entire session
• Per-Message Impact: Individual impact of each AI response

🔧 Configuration

Environment Variables

Variable	Description	Default
MISTRAL_API_KEY	Your Mistral AI API key	Required

Model Selection

The application automatically:

• Fetches available models from Mistral API
• Filters to only show text-to-text capable models (using completion_chat capability)
• Falls back to predefined models if API is unavailable

Fallback Models

If the Mistral API is unavailable, the application uses these models:

• mistral-small-latest
• mistral-large-latest
• open-mistral-nemo

🛠️ Development

Code Structure

The codebase follows clean architecture principles:

# Clean separation of concerns
config.py           # Configuration management
mistral_client.py   # External API integration
impacts_tracker.py  # Business logic for tracking
chat_interface.py   # UI presentation layer
app.py             # Application composition

Key Design Decisions

1. Model Filtering: Only shows models with completion_chat: true capability
2. Error Handling: Graceful degradation when APIs are unavailable
3. Environmental Focus: EcoLogits warnings displayed prominently in UI
4. Modular Design: Each file has a single, clear responsibility

Adding New Features

The modular structure makes it easy to extend:

• New Providers: Add to mistral_client.py or create similar modules
• UI Changes: Modify chat_interface.py
• Tracking Logic: Extend impacts_tracker.py
• Configuration: Add to config.py

🌍 About EcoLogits

EcoLogits is a Python library that tracks the environmental impact of AI model usage. It provides:

• Real-time energy consumption tracking
• Carbon footprint calculations
• Support for multiple AI providers
• Detailed impact reporting

This application demonstrates responsible AI usage by making environmental costs visible and measurable.

🐛 Troubleshooting

Common Issues

1. "Invalid model" errors:

   • Fixed! The app now filters out incompatible models automatically
   • Check the console output to see which models are included/excluded

2. Clear button not working:

   • Fixed! The "Effacer tout" button now properly resets conversation and impacts

3. Missing tabs:

   • Fixed! Tabbed interface restored with "Dernier message" and "Session totale"

4. API connection issues:

   • Check your MISTRAL_API_KEY in the .env file
   • The app will fall back to predefined models if the API is unavailable

Recent Improvements

• ✅ Fixed Model Filtering: No more "Invalid model" errors from OCR/specialized models
• ✅ Restored Tabbed Interface: Full impact tracking with organized tabs
• ✅ Fixed Clear Button: "Effacer tout" now properly resets conversation and impacts
• ✅ Enhanced Debugging: Visible model filtering process with inclusion/exclusion lists

📄 License

This project is provided as-is for educational and development purposes.

🤝 Contributing

Feel free to fork, modify, and improve this application. The modular structure makes it easy to:

• Add new AI providers
• Enhance the UI
• Improve environmental tracking
• Add new features

---

Made with 🌱 for sustainable AI development