README.md

---
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:**
   ```bash
   python -m venv .venv
   ```

3. **Activate the virtual environment:**
   ```bash
   # Windows
   .venv\Scripts\Activate.ps1
   
   # Linux/Mac
   source .venv/bin/activate
   ```

4. **Install dependencies:**
   ```bash
   pip install gradio mistralai ecologits python-dotenv
   ```

5. **Set up environment variables:**
   
   Create a `.env` file in the project root:
   ```env
   MISTRAL_API_KEY=your_mistral_api_key_here
   ```
   
   Or set the environment variable directly:
   ```bash
   # 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](https://console.mistral.ai/)
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:**
   ```bash
   .venv\Scripts\Activate.ps1
   ```

2. **Run the application:**
   ```bash
   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:

```python
# 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](https://ecologits.ai/) 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**