README.md

---
title: EcoCart AI System
emoji: 🛒
colorFrom: green
colorTo: blue
sdk: streamlit
sdk_version: "1.57.0"
app_file: app.py
pinned: false
---

# EcoCart AI System

An interactive AI-powered logistics simulation 

 **Live Demo:** [Launch on Streamlit](https://ecocart-ai-app-live.streamlit.app)

---

## What is EcoCart?

EcoCart is a mid-sized e-commerce company facing challenges in optimising its logistics network. This project proposes an AI-based solution across six tasks — from intelligent delivery agents to demand forecasting and business ROI analysis.

---

## Tasks Covered

### Task 1 — AI Agents
Demonstrates three types of AI agents navigating a delivery map in real time:
- **Reactive Agent** — goes to the nearest stop, no planning
- **Goal-Based Agent** — plans the full route before departing (2-opt optimised)
- **Utility-Based Agent** — balances urgency vs distance to prioritise high-value stops

### Task 2 — Bias Detection & Mitigation
Uses K-Means clustering to segment customers into value tiers. Detects urban/rural bias using **Disparate Impact (DI)** analysis and applies a three-step mitigation strategy:
- Oversample rural customers to balance the dataset
- Adjust spend for delivery cost premium (+€12)
- Adjust frequency for rural order batching (×1.5)

### Task 3 — Search Algorithms for Route Optimisation
Implements all four search algorithms on a 20-node urban/rural delivery network:
- **BFS** — Breadth-First Search
- **DFS** — Depth-First Search
- **A\*** — Best-first with Euclidean heuristic
- **IDA\*** — Iterative Deepening A*

Includes a live **exploration replay slider** — drag to watch the algorithm search node by node.

### Task 4 — A* vs IDA* Comparative Analysis
Benchmarks both algorithms on 10 origin-destination pairs (5 urban, 5 rural) over multiple timing runs. Compares nodes expanded, average time, and memory behaviour.

### Task 5 — Demand Forecasting
Trains two ML models on 730 days of synthetic sales data:
- **Linear Regression** — fast and interpretable
- **Random Forest** — captures non-linear seasonal patterns

Features a **what-if predictor** — enter any day, month, and promotion flag to get an instant sales prediction.

### Task 6 — Business Case *(Voluntary — AI Student)*
Quantifies the financial and environmental impact of the AI system with fully interactive sliders:
- **ROI calculator** — adjusts fleet size, fuel cost, wage rates and shows live annual savings
- **3-year ROI projection** — cumulative benefit vs cost with breakeven line
- **CO₂ impact** — tonnes saved per year, tree and car equivalents
- **Implementation roadmap** — 5-phase Gantt chart across 8 months

---

## Tech Stack

| Tool | Purpose |
|------|---------|
| Python 3.11 | Core language |
| Streamlit | Interactive web app |
| Plotly | Interactive charts |
| scikit-learn | K-Means, LR, Random Forest |
| NumPy / Pandas | Data processing |

---

## Run Locally

```bash
pip install -r requirements.txt
streamlit run app.py
```

---

## Project Structure

```
FAI SIMULATION/
├── app.py                   # Main Streamlit app (all 6 tasks)
├── task2_segmentation.py    # Standalone Task 2 script
├── task3_4_routing.py       # Standalone Tasks 3 & 4 script
├── task5_forecasting.py     # Standalone Task 5 script
├── data/                    # Synthetic datasets (loaded by every task)
│   ├── customers.csv        # Task 2 — 400 customer records
│   ├── sales_history.csv    # Task 5 — 730 days of daily sales
│   ├── network_nodes.csv    # Tasks 3/4 — 20-node delivery network
│   ├── network_edges.csv    # Tasks 3/4 — edge weights + CO₂ cost
│   └── export_data.py       # Regenerates the CSVs from a fixed seed
├── requirements.txt         # Python dependencies
└── README.md
```

---

## Dataset

All data is **synthetic and reproducible**. The CSVs in `data/` are the
program's data source — every task script (`task2_segmentation.py`,
`task3_4_routing.py`, `task5_forecasting.py`) loads its inputs directly
from these files at runtime:

| File | Rows | Description |
|------|------|-------------|
| `customers.csv` | 400 | 300 urban + 100 rural customers (deliberately biased) |
| `sales_history.csv` | 730 | Daily sales with weekly + yearly seasonality + promos |
| `network_nodes.csv` | 20 | Delivery hubs (x, y, urban/rural) |
| `network_edges.csv` | 34 | Roads with distance (km) and CO₂ cost (kg) |

The CSVs themselves are generated from an inline source-of-truth with a
fixed random seed (`np.random.default_rng(42)`). To rebuild them:
`python data/export_data.py`

---

## Author

Esvanth Mohankumar
Student ID: 24311073  
Programme: MSc Artificial Intelligence  
College: National College of Ireland  
Module: Foundations of AI