Upload 17 files

.env.example

@@ -1,80 +1,37 @@
-# ============================================================================
-# CleanCity Agent - Environment Configuration
-# ============================================================================
-# Copy this file to .env and configure your settings
-
-# ============================================================================
-# LLM PROVIDER SELECTION
-# ============================================================================
-# Choose: "anthropic" | "openai" | "gemini" | "offline"
-# offline = No API calls, uses mock responses (good for testing)
-LLM_PROVIDER=offline
-
-# ============================================================================
-# LLM API KEYS
-# ============================================================================
-
-# Anthropic Claude (Recommended - Latest: Claude 3.5 Sonnet)
-# Get your key: https://console.anthropic.com/
-# ANTHROPIC_API_KEY=sk-ant-api03-...
-
-# OpenAI (GPT-4o, GPT-4 Turbo)
-# Get your key: https://platform.openai.com/api-keys
-# OPENAI_API_KEY=sk-proj-...
-
-# Google Gemini (Gemini Pro, Gemini Ultra)
-# Get your key: https://makersuite.google.com/app/apikey
-# GEMINI_API_KEY=AIza...
-
-# ============================================================================
-# MODEL CONFIGURATION (Optional - defaults are set)
-# ============================================================================
-
-# Anthropic model selection
-# ANTHROPIC_MODEL=claude-3-5-sonnet-20241022
-
-# OpenAI model selection
-# OPENAI_MODEL=gpt-4o
-
-# Google Gemini model selection
-# GEMINI_MODEL=gemini-1.5-pro
-
-# ============================================================================
-# YOLO MODEL CONFIGURATION
-# ============================================================================
-
-# Path to YOLO weights file
-YOLO_MODEL_PATH=Weights/best.pt
-
-# Detection confidence threshold (0.0 to 1.0)
-YOLO_CONFIDENCE=0.25
-
-# ============================================================================
-# DATABASE CONFIGURATION
-# ============================================================================
-
-# SQLite database path
-DB_PATH=data/trash_events.db
-
-# ============================================================================
-# GRADIO SERVER CONFIGURATION
-# ============================================================================
-
-# Server host (0.0.0.0 = accessible from network, 127.0.0.1 = localhost only)
-GRADIO_SERVER_NAME=127.0.0.1
-
-# Server port
-GRADIO_SERVER_PORT=7860
-
-# Share publicly via Gradio link (true/false)
-GRADIO_SHARE=false
-
-# ============================================================================
-# LOGGING & DEBUG
-# ============================================================================
-
-# Log level: DEBUG, INFO, WARNING, ERROR
-LOG_LEVEL=INFO
-
-# Enable detailed YOLO output
-YOLO_VERBOSE=false
+# Example environment configuration for CleanCity Agent
+# Copy this file to .env and fill in your API keys
+
+# ============================================================================
+# LLM PROVIDER CONFIGURATION
+# ============================================================================
+# Choose your LLM provider: "anthropic" | "openai" | "gemini" | "offline"
+# Default: "offline" (uses mock responses, no API key needed)
+LLM_PROVIDER=offline
+
+# ============================================================================
+# API KEYS (only needed if not using offline mode)
+# ============================================================================
+
+# Anthropic Claude (recommended)
+# Get your key at: https://console.anthropic.com/
+# ANTHROPIC_API_KEY=sk-ant-...
+
+# OpenAI GPT
+# Get your key at: https://platform.openai.com/api-keys
+# OPENAI_API_KEY=sk-...
+
+# Google Gemini
+# Get your key at: https://makersuite.google.com/app/apikey
+# GEMINI_API_KEY=...
+
+# ============================================================================
+# OPTIONAL CONFIGURATION
+# ============================================================================
+
+# Database path (default: data/trash_events.db)
+# DB_PATH=data/trash_events.db
+
+# Gradio server configuration
+# GRADIO_SERVER_NAME=0.0.0.0
+# GRADIO_SERVER_PORT=7860
+# GRADIO_SHARE=false

.gitattributes

@@ -1,35 +1,35 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
-*.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -1,48 +1,48 @@
-# Python
-__pycache__/
-*.py[cod]
-*$py.class
-*.so
-.Python
-build/
-develop-eggs/
-dist/
-downloads/
-eggs/
-.eggs/
-lib/
-lib64/
-parts/
-sdist/
-var/
-wheels/
-*.egg-info/
-.installed.cfg
-*.egg
-
-# Virtual Environment
-.venv/
-venv/
-ENV/
-env/
-
-# Environment Variables
-.env
-
-# Database
-data/*.db
-data/*.db-journal
-
-# IDE
-.vscode/
-.idea/
-*.swp
-*.swo
-*~
-
-# Gradio
-flagged/
-
-# OS
-.DS_Store
-Thumbs.db
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual Environment
+.venv/
+venv/
+ENV/
+env/
+
+# Environment Variables
+.env
+
+# Database
+data/*.db
+data/*.db-journal
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Gradio
+flagged/
+
+# OS
+.DS_Store
+Thumbs.db

README.md

@@ -1,178 +1,395 @@
----
-title: CleanCity Agent - AI Trash Detection
-emoji: 🌍
-colorFrom: green
-colorTo: blue
-sdk: gradio
-sdk_version: "5.9.1"
-app_file: app.py
-pinned: false
----
-
-# 🌍 CleanCity Agent
-
-**AI-Powered Trash Detection & Cleanup Planner**
-
-CleanCity Agent is a modern web application that helps communities identify, track, and clean up littered areas using computer vision and AI-powered planning.
-
-## ✨ Features
-
-### 🔍 **Smart Trash Detection**
-- YOLOv8/v11 computer vision model
-- Real-time object detection with bounding boxes
-- Identifies multiple trash categories
-- Confidence scores for each detection
-
-### 📋 **Intelligent Cleanup Planning**
-- Automatic severity assessment (Low/Medium/High)
-- Resource estimation (volunteers, time, equipment)
-- Environmental impact analysis
-- Actionable cleanup recommendations
-
-### 💬 **AI Chat Assistant**
-- Ask questions about cleanup strategies
-- Get environmental impact assessments
-- Community organizing advice
-- Powered by latest LLMs (offline mode by default)
-
-## 🚀 Quick Start
-
-### Running Locally
-
-1. **Clone the repository**
-   ```bash
-   git clone <your-repo-url>
-   cd CleanCity
-   ```
-
-2. **Install dependencies**
-   ```bash
-   pip install -r requirements.txt
-   ```
-
-3. **Run the application**
-   ```bash
-   python app.py
-   ```
-
-4. **Open your browser**
-   - Navigate to `http://127.0.0.1:7860`
-
-## ⚙️ Configuration
-
-### Environment Variables
-
-Copy `.env.example` to `.env` and configure:
-
-```bash
-# LLM Provider (optional - defaults to offline)
-LLM_PROVIDER=offline  # or: anthropic, openai, gemini
-
-# API Keys (only if using online LLM)
-# ANTHROPIC_API_KEY=sk-ant-...
-# OPENAI_API_KEY=sk-proj-...
-# GEMINI_API_KEY=AIza...
-
-# YOLO Model
-YOLO_MODEL_PATH=Weights/best.pt
-YOLO_CONFIDENCE=0.25
-
-# Server Settings
-GRADIO_SERVER_NAME=127.0.0.1
-GRADIO_SERVER_PORT=7860
-```
-
-## 🧠 Technology Stack
-
-- **Frontend:** Gradio 5.9.1
-- **Computer Vision:** Ultralytics YOLO (8.3.41+)
-- **Deep Learning:** PyTorch 2.5.1+
-- **LLM Providers:** 
-  - Anthropic Claude 3.5 Sonnet
-  - OpenAI GPT-4o
-  - Google Gemini 1.5 Pro
-- **Database:** SQLite (built-in)
-
-## 📦 Project Structure
-
-```
-CleanCity/
-├── app.py                 # Gradio web interface
-├── trash_model.py        # YOLO detection module
-├── llm_client.py         # Multi-provider LLM client
-├── requirements.txt      # Python dependencies
-├── .env.example          # Environment template
-├── Weights/
-│   └── best.pt          # YOLO model weights
-├── agents/              # AI agents (optional)
-├── tools/               # Tools module (optional)
-└── data/                # Database storage
-```
-
-## 🎯 Usage
-
-### 1. Analyze Image
-- Upload or capture an image
-- Click "Analyze Image"
-- View detected trash with bounding boxes
-- Review cleanup plan and recommendations
-
-### 2. AI Assistant
-- Ask questions about cleanup planning
-- Get advice on environmental impact
-- Learn about community organizing
-
-## 🔧 Development
-
-### Requirements
-- Python 3.11+
-- YOLO model weights (`Weights/best.pt`)
-- Optional: API keys for LLM providers
-
-### Running Tests
-```bash
-# Test trash detection module
-python trash_model.py
-
-# Test LLM client
-python llm_client.py
-```
-
-## 🌐 Deployment
-
-### Hugging Face Spaces
-This app is configured to run on Hugging Face Spaces with Gradio SDK.
-
-### Local Server
-```bash
-python app.py
-```
-
-## 🔒 Privacy
-
-- All image processing happens **locally** on your device
-- No images are uploaded to external servers
-- LLM API calls only if you configure API keys
-- Your privacy is our priority
-
-## 📄 License
-
-MIT License - feel free to use and modify for your projects!
-
-## 🤝 Contributing
-
-Contributions are welcome! Feel free to:
-- Report bugs
-- Suggest features
-- Submit pull requests
-
-## 🌟 Acknowledgments
-
-Built with:
-- [Gradio](https://gradio.app/) - Web UI framework
-- [Ultralytics YOLO](https://github.com/ultralytics/ultralytics) - Object detection
-- [Anthropic](https://anthropic.com/), [OpenAI](https://openai.com/), [Google](https://ai.google.dev/) - LLM providers
-
----
-
-**Made with ❤️ for a cleaner planet 🌍**
+---
+title: CleanCity Agent - AI Trash Detection & Cleanup Planner
+emoji: 🌍
+colorFrom: green
+colorTo: blue
+sdk: gradio
+sdk_version: "5.9.1"
+app_file: app.py
+pinned: false
+tags:
+- mcp-in-action-track-consumer
+- mcp
+- anthropic
+- computer-vision
+- environmental
+- gradio-hackathon
+- ai-agents
+- mcp-server
+---
+
+# 🌍 CleanCity Agent
+
+**Autonomous Trash Detection & Cleanup Planner**
+
+> 🏆 **MCP's 1st Birthday Hackathon Submission**  
+> **Track:** MCP in Action - Consumer Applications  
+> **Tags:** `mcp-in-action-track-consumer`
+
+CleanCity Agent is an AI-powered web application that helps communities identify, track, and clean up littered areas. Upload an image of trash, get instant analysis, receive cleanup recommendations, and track environmental improvements over time.
+
+<p align="center">
+  <img src="https://img.shields.io/badge/Python-3.11+-blue.svg" alt="Python 3.11+">
+  <img src="https://img.shields.io/badge/Gradio-6.0-orange.svg" alt="Gradio">
+  <img src="https://img.shields.io/badge/MCP-Enabled-green.svg" alt="MCP">
+  <img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="MIT License">
+</p>
+
+---
+
+## ✨ Features
+
+### 🔍 **Smart Trash Detection**
+- Computer vision-powered object detection
+- Identifies common litter types: bottles, bags, wrappers, cigarette butts, etc.
+- Visual bounding boxes with confidence scores
+
+### 📋 **Intelligent Cleanup Planning**
+- Automatic severity assessment (Low/Medium/High)
+- Resource estimation (volunteers, time, equipment)
+- Environmental impact analysis
+- Actionable recommendations
+
+### 📊 **Historical Tracking**
+- SQLite database for event logging
+- Filter by location, date, severity
+- Identify recurring "hotspots"
+- Track cleanup progress over time
+
+### 📄 **Report Generation**
+- Professional reports for city authorities
+- Email-ready templates
+- Multiple formats (Email, Markdown, Plain text)
+- LLM-enhanced descriptions (optional)
+
+### 💬 **AI Chat Assistant**
+- Ask questions about your analysis
+- Get cleanup strategy advice
+- Understand environmental impact
+- Community organizing tips
+
+### 🔌 **MCP Integration**
+- Expose tools via Model Context Protocol
+- Compatible with Claude Desktop and other MCP clients
+- Programmatic access to all features
+
+---
+
+## 🚀 Quick Start
+
+### Prerequisites
+
+- **Python 3.11+**
+- **pip** (Python package manager)
+- **git** (optional, for cloning)
+
+### Installation
+
+1. **Clone or download this repository**
+   ```bash
+   git clone <repository-url>
+   cd track2.1
+   ```
+
+2. **Create a virtual environment**
+   ```bash
+   python -m venv .venv
+   ```
+
+3. **Activate the virtual environment**
+   - Windows (PowerShell):
+     ```powershell
+     .venv\Scripts\Activate.ps1
+     ```
+   - Windows (Command Prompt):
+     ```cmd
+     .venv\Scripts\activate.bat
+     ```
+   - macOS/Linux:
+     ```bash
+     source .venv/bin/activate
+     ```
+
+4. **Install dependencies**
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+5. **Configure environment (optional)**
+   ```bash
+   copy .env.example .env
+   # Edit .env with your API keys if using LLM features
+   ```
+
+6. **Run the application**
+   ```bash
+   python app.py
+   ```
+
+7. **Open your browser**
+   Navigate to: **http://localhost:7860**
+
+---
+
+## 🎯 User Walkthrough
+
+### Step 1: Upload an Image
+- Click the image upload area or use webcam
+- Select a photo showing trash in streets, parks, or beaches
+- Optionally add location and notes
+
+### Step 2: Analyze
+- Click **"Start Analysis"**
+- AI detects and highlights trash items
+- View detection results with confidence scores
+
+### Step 3: Review Plan
+- Get severity assessment (Low/Medium/High)
+- See volunteer and time estimates
+- Review equipment recommendations
+- Understand environmental impact
+
+### Step 4: Save & Track
+- Events are saved to history (if enabled)
+- View past events in the History tab
+- Identify hotspots in the Hotspots tab
+
+### Step 5: Take Action
+- Copy the generated email report
+- Send to city environmental department
+- Share with community cleanup groups
+- Organize volunteers and execute cleanup
+
+---
+
+## 🏗️ Architecture
+
+### Project Structure
+
+```
+track2.1/
+├── app.py                          # Main Gradio UI application
+├── mcp_server.py                   # MCP server for tool exposure
+├── llm_client.py                   # LLM abstraction layer
+├── trash_model.py                  # Trash detection model wrapper
+├── agents/
+│   └── planner_agent.py            # Cleanup workflow orchestrator
+├── tools/
+│   ├── trash_detection_tool.py     # Detection MCP tool
+│   ├── cleanup_planner_tool.py     # Planning logic
+│   ├── history_tool.py             # Event logging & querying
+│   └── report_generator_tool.py    # Report generation
+├── data/
+│   └── trash_events.db             # SQLite database (auto-created)
+├── Weights/
+│   └── best.pt                     # Model weights (for real model)
+├── requirements.txt                # Python dependencies
+├── .env.example                    # Environment template
+└── README.md                       # This file
+```
+
+### Technology Stack
+
+- **Frontend**: Gradio 6.x (web UI framework)
+- **AI/ML**: Pluggable detection model (currently mock)
+- **MCP**: FastMCP for tool exposure
+- **LLM**: Multi-provider support (Anthropic, OpenAI, Gemini)
+- **Database**: SQLite (local, file-based)
+- **Image Processing**: Pillow (PIL)
+
+---
+
+## 🔧 Configuration
+
+### LLM Providers
+
+CleanCity Agent works **offline by default** with mock responses. To enable real LLM capabilities:
+
+1. Copy `.env.example` to `.env`
+2. Set `LLM_PROVIDER` to your preferred provider:
+   - `anthropic` - Claude (recommended)
+   - `openai` - GPT-4
+   - `gemini` - Google Gemini
+   - `offline` - Mock responses (no API key needed)
+
+3. Add your API key:
+   ```env
+   LLM_PROVIDER=anthropic
+   ANTHROPIC_API_KEY=sk-ant-your-key-here
+   ```
+
+### Trash Detection Model
+
+The current implementation uses a **mock detector** for demonstration. To integrate a real model:
+
+1. **Option A: Use existing weights** (Weights/best.pt)
+   - If you have a YOLOv8/YOLOv5 model:
+     ```python
+     from ultralytics import YOLO
+     model = YOLO("Weights/best.pt")
+     ```
+   - Update `trash_model.py` with real inference code
+
+2. **Option B: Hugging Face model**
+   ```python
+   from transformers import AutoModelForObjectDetection
+   model = AutoModelForObjectDetection.from_pretrained("model-name")
+   ```
+
+3. **Option C: External API**
+   - Connect to Roboflow, Hugging Face Inference API, etc.
+
+See `trash_model.py` for integration points and TODOs.
+
+---
+
+## 🐳 Deployment
+
+### Local Deployment
+Already covered in Quick Start section above.
+
+### Hugging Face Spaces
+
+1. Create a new Space at https://huggingface.co/spaces
+2. Select "Gradio" as the SDK
+3. Upload all project files
+4. Add secrets for API keys in Space settings
+5. Space will auto-deploy from `app.py`
+
+### Docker (Manual)
+
+```dockerfile
+FROM python:3.11-slim
+
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install -r requirements.txt
+
+COPY . .
+
+EXPOSE 7860
+CMD ["python", "app.py"]
+```
+
+Build and run:
+```bash
+docker build -t cleancity-agent .
+docker run -p 7860:7860 cleancity-agent
+```
+
+---
+
+## 🛠️ MCP Server Usage
+
+The MCP server exposes all tools for programmatic access:
+
+### Running the MCP Server
+
+```bash
+python mcp_server.py
+```
+
+### Available Tools
+
+1. **detect_trash** - Detect trash in images
+2. **plan_cleanup** - Generate cleanup plans
+3. **log_event** - Save events to database
+4. **query_events** - Search historical events
+5. **get_hotspots** - Identify recurring problem areas
+6. **generate_report** - Create formatted reports
+7. **mark_cleaned** - Update event status
+
+### Claude Desktop Integration
+
+Add to your Claude Desktop configuration (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "cleancity": {
+      "command": "python",
+      "args": ["C:\\path\\to\\track2.1\\mcp_server.py"]
+    }
+  }
+}
+```
+
+---
+
+## 📊 Database Schema
+
+SQLite database (`data/trash_events.db`) with the following schema:
+
+```sql
+CREATE TABLE events (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    timestamp TEXT NOT NULL,
+    location TEXT,
+    latitude REAL,
+    longitude REAL,
+    severity TEXT NOT NULL,
+    trash_count INTEGER NOT NULL,
+    categories TEXT NOT NULL,  -- JSON array
+    detections_json TEXT NOT NULL,  -- JSON array
+    notes TEXT,
+    image_path TEXT,
+    cleaned BOOLEAN DEFAULT 0,
+    created_at TEXT DEFAULT CURRENT_TIMESTAMP
+);
+```
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Areas for improvement:
+
+- **Real trash detection model** integration
+- **GPS/mapping** features for hotspot visualization
+- **Multi-user support** with authentication
+- **Mobile app** wrapper (React Native, Flutter)
+- **Gamification** (points, badges for cleanups)
+- **Social sharing** features
+- **Volunteer coordination** tools
+
+Please open an issue or PR on the repository.
+
+---
+
+## ⚠️ Limitations
+
+- **Mock detection**: Currently uses random detections for demonstration
+- **Local storage**: Data stored locally, not synchronized
+- **No authentication**: Single-user design
+- **Detection accuracy**: Depends on image quality and model training
+- **LLM costs**: Using real LLM APIs incurs API charges
+
+This is a **prototype** designed for community groups and individual activists. Production deployment requires additional hardening.
+
+---
+
+## 📜 License
+
+MIT License - see LICENSE file for details.
+
+---
+
+## 🙏 Acknowledgments
+
+- Built with [Gradio](https://gradio.app/)
+- Powered by [Model Context Protocol (MCP)](https://modelcontextprotocol.io/)
+- LLM support via Anthropic, OpenAI, and Google
+- Inspired by community environmental activists worldwide
+
+---
+
+## 📧 Support
+
+For questions, issues, or feature requests:
+- Open an issue on GitHub
+- Check the FAQ in the app's "How It Works" tab
+- Review the inline code documentation
+
+---
+
+**Let's make our cities cleaner, together! 🌍♻️**

agents/__init__.py

@@ -0,0 +1,5 @@
+"""Agents package for CleanCity Agent."""
+
+from .planner_agent import run_cleanup_workflow
+
+__all__ = ["run_cleanup_workflow"]

agents/planner_agent.py

@@ -0,0 +1,244 @@
+"""
+Cleanup Planning Agent
+
+Orchestrates the full workflow from image analysis to actionable cleanup plans.
+"""
+
+from typing import Optional, Any
+from PIL import Image
+import base64
+from io import BytesIO
+
+from tools.trash_detection_tool import detect_trash_mcp, format_detections_for_display
+from tools.cleanup_planner_tool import plan_cleanup
+from tools.history_tool import log_event, get_hotspots
+from tools.report_generator_tool import generate_report
+from trash_model import Detection
+
+
+def run_cleanup_workflow(
+    image: Image.Image,
+    location: Optional[str] = None,
+    notes: Optional[str] = None,
+    save_to_history: bool = True,
+    use_llm_enhancement: bool = False,
+    latitude: Optional[float] = None,
+    longitude: Optional[float] = None
+):
+    """
+    Execute the complete cleanup workflow for a trash detection event.
+    
+    This is the main orchestration function that:
+    1. Detects trash in the image
+    2. Plans cleanup actions
+    3. Optionally logs to history
+    4. Generates reports
+    5. Returns all results for UI display
+    
+    Args:
+        image: PIL Image to analyze
+        location: Optional location description
+        notes: Optional user notes
+        save_to_history: Whether to log event to database
+        use_llm_enhancement: Whether to use LLM for enhanced text generation
+        latitude: Optional GPS latitude
+        longitude: Optional GPS longitude
+    
+    Returns:
+        Dict containing:
+            - detection_results: Raw detection data
+            - plan: Cleanup plan
+            - report: Generated report text
+            - event_id: Database ID (if saved)
+            - visualization_data: Data for UI overlay
+            - summary: Human-readable summary
+    """
+    # Step 1: Detect trash
+    print("🔍 Step 1: Detecting trash in image...")
+    
+    # Convert image to base64 for tool (simulating MCP data format)
+    buffered = BytesIO()
+    image.save(buffered, format="PNG")
+    img_b64 = base64.b64encode(buffered.getvalue()).decode()
+    
+    detection_result = detect_trash_mcp(img_b64)
+    detections: list[Detection] = detection_result["detections"]
+    
+    print(f"   Found {detection_result['count']} items")
+    
+    if not detections:
+        return {
+            "detection_results": detection_result,
+            "plan": None,
+            "report": None,
+            "event_id": None,
+            "visualization_data": None,
+            "summary": "No trash detected in this image. The area appears clean!",
+            "status": "no_trash"
+        }
+    
+    # Step 2: Plan cleanup
+    print("📋 Step 2: Planning cleanup actions...")
+    plan = plan_cleanup(
+        detections,
+        location=location,
+        notes=notes,
+        use_llm=use_llm_enhancement
+    )
+    print(f"   Severity: {plan['severity']}, Volunteers: {plan['recommended_volunteers']}")
+    
+    # Step 3: Log to history (if requested)
+    event_id = None
+    if save_to_history:
+        print("💾 Step 3: Logging event to history...")
+        log_result = log_event(
+            detections=detections,
+            severity=plan["severity"],
+            location=location,
+            notes=notes,
+            image_path=None,  # Could save image file here
+            latitude=latitude,
+            longitude=longitude
+        )
+        event_id = log_result["event_id"]
+        print(f"   Saved as event #{event_id}")
+    
+    # Step 4: Generate report
+    print("📄 Step 4: Generating report...")
+    report_result = generate_report(
+        detections=detections,
+        severity=plan["severity"],
+        location=location,
+        notes=notes,
+        event_id=event_id,
+        plan=plan,
+        format="email"
+    )
+    report_text = report_result["report"]
+    
+    # Step 5: Prepare visualization data
+    visualization_data = _prepare_visualization_data(image, detections)
+    
+    # Step 6: Create summary
+    summary = _create_workflow_summary(detection_result, plan, event_id)
+    
+    print("✅ Workflow complete!")
+    
+    return {
+        "detection_results": detection_result,
+        "plan": plan,
+        "report": report_text,
+        "event_id": event_id,
+        "visualization_data": visualization_data,
+        "summary": summary,
+        "status": "success"
+    }
+
+
+def _prepare_visualization_data(image: Image.Image, detections: list[Detection]):
+    """Prepare data for drawing bounding boxes on image."""
+    return {
+        "image_size": {"width": image.width, "height": image.height},
+        "boxes": [
+            {
+                "bbox": det["bbox"],
+                "label": det["label"],
+                "score": det["score"],
+                "color": _get_color_for_label(det["label"])
+            }
+            for det in detections
+        ]
+    }
+
+
+def _get_color_for_label(label: str) -> str:
+    """Get consistent color for trash category."""
+    color_map = {
+        "plastic_bottle": "#FF6B6B",
+        "plastic_bag": "#4ECDC4",
+        "food_wrapper": "#FFD93D",
+        "cigarette_butt": "#95E1D3",
+        "paper_cup": "#F38181",
+        "aluminum_can": "#AA96DA",
+        "food_container": "#FCBAD3",
+        "cardboard_box": "#A8D8EA",
+        "glass_bottle": "#FFA07A",
+        "other_trash": "#B0B0B0"
+    }
+    return color_map.get(label, "#FF0000")
+
+
+def _create_workflow_summary(
+    detection_result,
+    plan,
+    event_id: Optional[int]
+) -> str:
+    """Create human-readable workflow summary."""
+    count = detection_result["count"]
+    categories = detection_result["categories"]
+    severity = plan["severity"]
+    volunteers = plan["recommended_volunteers"]
+    time = plan["estimated_time_minutes"]
+    
+    category_text = ", ".join(categories[:3])
+    if len(categories) > 3:
+        category_text += f" and {len(categories) - 3} more"
+    
+    summary = f"""**Analysis Complete**
+
+Detected **{count} trash items** across {len(categories)} categories ({category_text}).
+
+**Severity:** {severity.upper()}
+
+**Recommended Action:**
+- {volunteers} volunteer(s) needed
+- Approximately {time} minutes
+- Action within {plan['urgency_days']} day(s)
+"""
+    
+    if event_id:
+        summary += f"\n✓ Event saved to history (ID: {event_id})"
+    
+    return summary
+
+
+def analyze_hotspots(days: int = 30):
+    """
+    Analyze trash hotspots from historical data.
+    
+    Args:
+        days: Time window for analysis
+    
+    Returns:
+        Hotspot analysis with recommendations
+    """
+    hotspots_data = get_hotspots(min_events=2, days=days)
+    
+    if not hotspots_data["hotspots"]:
+        return {
+            "hotspots": [],
+            "message": f"No recurring hotspots found in the last {days} days.",
+            "recommendation": "Continue monitoring and logging new events."
+        }
+    
+    # Analyze hotspots
+    top_hotspot = hotspots_data["hotspots"][0]
+    
+    recommendation = f"""**Hotspot Alert**
+
+{hotspots_data['count']} location(s) with recurring trash issues identified.
+
+**Top Problem Area:** {top_hotspot['location']}
+- {top_hotspot['event_count']} events recorded
+- {top_hotspot['total_trash']} total items
+- Last event: {top_hotspot['last_event']}
+
+**Recommendation:** Consider setting up regular cleanup schedule or requesting permanent waste receptacles for this location.
+"""
+    
+    return {
+        "hotspots": hotspots_data["hotspots"],
+        "count": hotspots_data["count"],
+        "recommendation": recommendation,
+        "top_hotspot": top_hotspot
+    }

app.py

@@ -1,503 +1,646 @@
-"""
-CleanCity Agent - Gradio Web Application
-
-Modern web interface for trash detection and cleanup planning.
-Built with Gradio 5.x with latest features.
-"""
-
-import gradio as gr
-from PIL import Image, ImageDraw, ImageFont
-import io
-import base64
-from datetime import datetime
-from typing import Optional, Tuple
-import logging
-
-from trash_model import detect_trash, get_model_info
-from llm_client import get_llm_client
-
-# Configure logging
-logging.basicConfig(level=logging.INFO)
-logger = logging.getLogger(__name__)
-
-# ============================================================================
-# UI CONSTANTS
-# ============================================================================
-
-TITLE = "🌍 CleanCity Agent"
-DESCRIPTION = """
-**AI-Powered Trash Detection & Cleanup Planner**
-
-Upload an image to detect trash, get cleanup recommendations, and track environmental improvements.
-"""
-
-CSS = """
-.primary-btn {
-    background: linear-gradient(90deg, #10b981 0%, #059669 100%) !important;
-    border: none !important;
-}
-.secondary-btn {
-    background: linear-gradient(90deg, #3b82f6 0%, #2563eb 100%) !important;
-    border: none !important;
-}
-.container {
-    max-width: 1200px;
-    margin: auto;
-}
-.info-box {
-    background: #f0fdf4;
-    border-left: 4px solid #10b981;
-    padding: 1rem;
-    margin: 1rem 0;
-    border-radius: 0.5rem;
-}
-"""
-
-# ============================================================================
-# HELPER FUNCTIONS
-# ============================================================================
-
-def draw_detections(image: Image.Image, detections: list) -> Image.Image:
-    """
-    Draw bounding boxes and labels on image.
-    
-    Args:
-        image: Original PIL Image
-        detections: List of Detection objects
-        
-    Returns:
-        Image with drawn annotations
-    """
-    # Create a copy
-    img_copy = image.copy()
-    draw = ImageDraw.Draw(img_copy)
-    
-    # Try to load a font, fallback to default
-    try:
-        font = ImageFont.truetype("arial.ttf", 20)
-    except:
-        font = ImageFont.load_default()
-    
-    # Color palette for different classes
-    colors = [
-        "#ef4444", "#f59e0b", "#10b981", "#3b82f6", 
-        "#8b5cf6", "#ec4899", "#06b6d4", "#84cc16"
-    ]
-    
-    for i, det in enumerate(detections):
-        bbox = det["bbox"]
-        label = det["label"]
-        score = det["score"]
-        
-        # Get color for this class
-        color = colors[det.get("class_id", i) % len(colors)]
-        
-        # Draw bounding box
-        draw.rectangle(bbox, outline=color, width=3)
-        
-        # Draw label background
-        text = f"{label} {score:.2f}"
-        text_bbox = draw.textbbox((bbox[0], bbox[1] - 25), text, font=font)
-        draw.rectangle(text_bbox, fill=color)
-        
-        # Draw label text
-        draw.text((bbox[0], bbox[1] - 25), text, fill="white", font=font)
-    
-    return img_copy
-
-
-def analyze_severity(detections: list) -> str:
-    """Determine cleanup severity based on detections."""
-    count = len(detections)
-    if count == 0:
-        return "None"
-    elif count <= 3:
-        return "Low"
-    elif count <= 8:
-        return "Medium"
-    else:
-        return "High"
-
-
-def estimate_resources(detections: list, severity: str) -> dict:
-    """Estimate cleanup resources needed."""
-    count = len(detections)
-    
-    if severity == "Low":
-        volunteers = "1-2"
-        time = "30 mins - 1 hour"
-    elif severity == "Medium":
-        volunteers = "3-5"
-        time = "1-2 hours"
-    else:
-        volunteers = "6-10"
-        time = "2-4 hours"
-    
-    equipment = [
-        "Heavy-duty trash bags",
-        "Gloves",
-        "Grabber tools",
-        "Safety vests"
-    ]
-    
-    if count > 5:
-        equipment.append("Wheelbarrow or cart")
-    
-    return {
-        "volunteers": volunteers,
-        "time": time,
-        "equipment": equipment
-    }
-
-
-# ============================================================================
-# CORE ANALYSIS FUNCTION
-# ============================================================================
-
-def analyze_image(image: Optional[Image.Image]) -> Tuple[Optional[Image.Image], str, str]:
-    """
-    Analyze uploaded image for trash.
-    
-    Args:
-        image: PIL Image from user
-        
-    Returns:
-        Tuple of (annotated_image, analysis_text, status_message)
-    """
-    if image is None:
-        return None, "", "⚠️ Please upload an image first"
-    
-    try:
-        # Run trash detection
-        logger.info("Running trash detection...")
-        detections = detect_trash(image)
-        
-        # Draw detections on image
-        annotated_image = draw_detections(image, detections)
-        
-        # Analyze results
-        count = len(detections)
-        severity = analyze_severity(detections)
-        
-        if count == 0:
-            analysis = "✅ **No trash detected!** This area looks clean."
-            status = "✅ Analysis complete - No trash found"
-        else:
-            # Get resource estimates
-            resources = estimate_resources(detections, severity)
-            
-            # Build analysis report
-            analysis = f"""
-## 🔍 Detection Results
-
-**Trash Items Detected:** {count}  
-**Severity Level:** {severity}
-
-### Detected Items:
-"""
-            # List detected items
-            item_counts = {}
-            for det in detections:
-                label = det["label"]
-                item_counts[label] = item_counts.get(label, 0) + 1
-            
-            for label, count in item_counts.items():
-                analysis += f"- **{label}**: {count} item(s)\n"
-            
-            analysis += f"""
----
-
-## 📋 Cleanup Plan
-
-**Volunteers Needed:** {resources['volunteers']} people  
-**Estimated Time:** {resources['time']}
-
-**Equipment Required:**
-"""
-            for item in resources['equipment']:
-                analysis += f"- {item}\n"
-            
-            analysis += """
----
-
-## 🌱 Environmental Impact
-
-Cleaning this area will:
-- Prevent pollution from entering waterways
-- Protect local wildlife from harmful debris
-- Improve community health and aesthetics
-- Set a positive example for environmental stewardship
-
-**Recommendation:** Schedule a cleanup event and consider installing waste bins to prevent future littering.
-"""
-            status = f"✅ Analysis complete - {count} items detected"
-        
-        return annotated_image, analysis, status
-        
-    except Exception as e:
-        logger.error(f"Analysis failed: {e}")
-        return None, "", f"❌ Error: {str(e)}"
-
-
-# ============================================================================
-# CHAT FUNCTION
-# ============================================================================
-
-def chat_response(message: str, history: list) -> list:
-    """
-    Handle chat interactions.
-    
-    Args:
-        message: User message
-        history: Chat history (list of message dicts)
-        
-    Returns:
-        Updated chat history
-    """
-    if not message.strip():
-        history.append({
-            "role": "assistant",
-            "content": "Please ask a question about trash cleanup or environmental impact."
-        })
-        return history
-    
-    try:
-        # Add user message to history
-        history.append({"role": "user", "content": message})
-        
-        # Get LLM client
-        llm = get_llm_client()
-        
-        # System prompt for chat
-        system_prompt = """You are an environmental assistant helping with trash cleanup planning.
-Provide helpful, practical advice about:
-- Cleanup strategies and best practices
-- Environmental impact of different types of trash
-- Resource estimation and volunteer coordination
-- Community organizing tips
-- Waste prevention strategies
-
-Keep responses concise and actionable."""
-        
-        # Generate response
-        response = llm.generate(
-            message,
-            system_prompt=system_prompt,
-            max_tokens=500,
-            temperature=0.7
-        )
-        
-        # Add assistant response to history
-        history.append({"role": "assistant", "content": response})
-        
-        return history
-        
-    except Exception as e:
-        logger.error(f"Chat error: {e}")
-        history.append({
-            "role": "assistant",
-            "content": f"Sorry, I encountered an error: {str(e)}"
-        })
-        return history
-
-
-# ============================================================================
-# GRADIO INTERFACE
-# ============================================================================
-
-def create_app() -> gr.Blocks:
-    """Create the Gradio application."""
-    
-    with gr.Blocks(
-        title=TITLE,
-        css=CSS,
-        theme=gr.themes.Soft(
-            primary_hue="green",
-            secondary_hue="blue"
-        )
-    ) as app:
-        
-        # Header
-        gr.Markdown(f"# {TITLE}")
-        gr.Markdown(DESCRIPTION)
-        
-        # Model info
-        model_info = get_model_info()
-        llm_info = get_llm_client().get_info()
-        
-        with gr.Accordion("ℹ️ System Information", open=False):
-            gr.Markdown(f"""
-**YOLO Model:** {'✅ Loaded' if model_info['loaded'] else '❌ Not loaded'}  
-**Detection Classes:** {model_info['num_classes']} ({', '.join(list(model_info['classes'].values())[:10])})  
-**LLM Provider:** {llm_info['provider']} {'(online)' if llm_info['online'] else '(offline)'}  
-**LLM Model:** {llm_info['model'] or 'Mock responses'}
-""")
-        
-        # Main content tabs
-        with gr.Tabs():
-            
-            # Tab 1: Image Analysis
-            with gr.Tab("📸 Analyze Image"):
-                gr.Markdown("### Upload an image to detect trash and get cleanup recommendations")
-                
-                with gr.Row():
-                    with gr.Column(scale=1):
-                        input_image = gr.Image(
-                            label="Upload Image",
-                            type="pil",
-                            sources=["upload", "webcam"]
-                        )
-                        
-                        analyze_btn = gr.Button(
-                            "🔍 Analyze Image",
-                            variant="primary",
-                            elem_classes=["primary-btn"]
-                        )
-                        
-                        status_text = gr.Textbox(
-                            label="Status",
-                            interactive=False,
-                            lines=1
-                        )
-                    
-                    with gr.Column(scale=1):
-                        output_image = gr.Image(
-                            label="Detection Results",
-                            type="pil"
-                        )
-                
-                with gr.Row():
-                    analysis_output = gr.Markdown(label="Analysis Report")
-                
-                # Wire up the analysis button
-                analyze_btn.click(
-                    fn=analyze_image,
-                    inputs=[input_image],
-                    outputs=[output_image, analysis_output, status_text]
-                )
-            
-            # Tab 2: AI Chat
-            with gr.Tab("💬 AI Assistant"):
-                gr.Markdown("### Ask questions about cleanup planning and environmental impact")
-                
-                chatbot = gr.Chatbot(
-                    label="Chat with AI Assistant",
-                    height=500,
-                    type="messages"
-                )
-                
-                msg = gr.Textbox(
-                    label="Your message",
-                    placeholder="Ask me about cleanup strategies, environmental impact, or organizing volunteers..."
-                )
-                
-                with gr.Row():
-                    submit = gr.Button("Send", variant="primary", elem_classes=["secondary-btn"])
-                    clear = gr.Button("Clear Chat")
-                
-                # Chat interactions
-                def user_submit(user_message, chat_history):
-                    return "", chat_response(user_message, chat_history)
-                
-                submit.click(
-                    fn=user_submit,
-                    inputs=[msg, chatbot],
-                    outputs=[msg, chatbot]
-                )
-                
-                msg.submit(
-                    fn=user_submit,
-                    inputs=[msg, chatbot],
-                    outputs=[msg, chatbot]
-                )
-                
-                clear.click(lambda: [], None, chatbot)
-            
-            # Tab 3: About
-            with gr.Tab("ℹ️ About"):
-                gr.Markdown("""
-## About CleanCity Agent
-
-CleanCity Agent is an AI-powered platform for environmental cleanup planning.
-
-### Features
-
-🔍 **Smart Trash Detection**
-- Computer vision using YOLOv8/v11
-- Identifies multiple trash categories
-- Visual bounding boxes with confidence scores
-
-📋 **Intelligent Cleanup Planning**
-- Automatic severity assessment
-- Resource estimation
-- Environmental impact analysis
-
-💬 **AI Chat Assistant**
-- Get cleanup strategy advice
-- Learn about environmental impact
-- Community organizing tips
-
-### Technology Stack
-
-- **Computer Vision:** Ultralytics YOLO
-- **LLM Providers:** Anthropic Claude, OpenAI GPT-4, Google Gemini
-- **Web Framework:** Gradio 5.x
-- **Model Context Protocol:** MCP integration
-
-### Privacy
-
-All image processing happens locally. No images are uploaded to external servers
-(except LLM API calls if configured). Your privacy is our priority.
-
-### Get Started
-
-1. Upload an image using the "Analyze Image" tab
-2. Click "Analyze Image" to detect trash
-3. Review the cleanup plan and recommendations
-4. Ask questions in the "AI Assistant" tab
-
----
-
-Built with ❤️ for a cleaner planet 🌍
-""")
-        
-        # Footer
-        gr.Markdown("""
----
-💡 **Tip:** Works best with clear images showing trash items. Try different angles for better detection!
-""")
-    
-    return app
-
-
-# ============================================================================
-# MAIN APPLICATION
-# ============================================================================
-
-if __name__ == "__main__":
-    """Launch the Gradio application."""
-    
-    print("=" * 70)
-    print("🌍 CleanCity Agent - Starting...")
-    print("=" * 70)
-    
-    # Initialize LLM client
-    print("\n📡 Initializing LLM client...")
-    get_llm_client()
-    
-    # Create and launch app
-    print("\n🚀 Launching Gradio interface...")
-    app = create_app()
-    
-    # Launch settings from environment
-    import os
-    server_name = os.getenv("GRADIO_SERVER_NAME", "127.0.0.1")
-    server_port = int(os.getenv("GRADIO_SERVER_PORT", "7860"))
-    share = os.getenv("GRADIO_SHARE", "false").lower() == "true"
-    
-    app.launch(
-        server_name=server_name,
-        server_port=server_port,
-        share=share,
-        show_api=False
-    )
+"""
+CleanCity Agent - Main Gradio Application
+
+A user-friendly web interface for trash detection and cleanup planning.
+"""
+
+import gradio as gr
+from PIL import Image, ImageDraw, ImageFont
+import io
+import base64
+from typing import Optional, Tuple
+
+from agents.planner_agent import run_cleanup_workflow, analyze_hotspots
+from tools.history_tool import query_events
+from llm_client import get_llm_client
+
+
+# ============================================================================
+# UI CONSTANTS & STYLES
+# ============================================================================
+
+TITLE = "🌍 CleanCity Agent"
+TAGLINE = "Spot trash. Plan action. Keep your city clean."
+
+GUIDE_CONTENT = """
+## 📖 How to Use CleanCity Agent
+
+### Step 1 – Add a Photo
+Upload a picture of a street, beach, park, or any place where there might be trash. 
+You can use your device's camera or select an existing image.
+
+**Pro Tip:** Click the **📍 Get GPS** button to automatically capture your current location!
+
+### Step 2 – Let the AI Spot the Trash
+Click **"Start Analysis"**. Our AI will:
+- Identify trash items in your image using your trained YOLO model
+- Draw bounding boxes around detected objects
+- Classify the type of trash found
+
+### Step 3 – Review the Cleanup Plan
+Get an instant assessment including:
+- **Severity level** (Low/Medium/High)
+- Number of volunteers needed
+- Estimated cleanup time
+- Required equipment list
+- Environmental impact summary
+
+### Step 4 – Save and Track
+Save this event with a location to:
+- Track trash patterns over time
+- Identify recurring problem areas ("hotspots")
+- Build evidence for city officials
+
+### Step 5 – Share or Report
+Use the generated report to:
+- Contact your city's environmental department
+- Organize community cleanup events
+- Document progress for grants or awareness campaigns
+
+---
+
+### 💡 Tips
+- **Better photos = better detection**: Take clear, well-lit images
+- **Add location details**: Helps track hotspots and patterns
+- **Check History tab**: See trends and recurring problem areas
+- **Chat with the agent**: Ask questions about your analysis
+
+### ⚠️ Limitations
+This is an AI-powered prototype. Detection accuracy depends on image quality 
+and lighting conditions. Always verify results visually.
+"""
+
+FAQ_CONTENT = """
+## ❓ Frequently Asked Questions
+
+**Q: How does the trash detection work?**  
+A: We use computer vision models trained to recognize common litter items like 
+plastic bottles, bags, food wrappers, cigarette butts, and more.
+
+**Q: Is my data stored or shared?**  
+A: All data is stored locally in your instance. We don't upload images or 
+personal information to external servers (except LLM API calls if you configure them).
+
+**Q: What should I do if detection is inaccurate?**  
+A: The mock model provides random detections for demonstration. Replace with a 
+real model by updating `trash_model.py`. You can also add notes to manually 
+correct assessments.
+
+**Q: Can I use this for large-scale city monitoring?**  
+A: This is a prototype designed for community groups and individual activists. 
+For large-scale deployment, consider:
+- Integrating a production-grade detection model
+- Setting up cloud hosting for data persistence
+- Adding user authentication and role management
+
+**Q: How can I contribute or report issues?**  
+A: Check the project repository for contribution guidelines and issue tracking.
+"""
+
+
+# ============================================================================
+# IMAGE PROCESSING FUNCTIONS
+# ============================================================================
+
+def draw_boxes_on_image(image: Image.Image, detections: list) -> Image.Image:
+    """Draw bounding boxes and labels on image."""
+    if not detections:
+        return image
+    
+    img_copy = image.copy()
+    draw = ImageDraw.Draw(img_copy)
+    
+    # Try to load a font, fall back to default if unavailable
+    try:
+        font = ImageFont.truetype("arial.ttf", 16)
+    except:
+        font = ImageFont.load_default()
+    
+    for det in detections:
+        bbox = det["bbox"]
+        label = det["label"].replace("_", " ").title()
+        score = det["score"]
+        
+        # Draw rectangle
+        draw.rectangle(bbox, outline="red", width=3)
+        
+        # Draw label background
+        text = f"{label} ({score:.0%})"
+        
+        # Get text bounding box for background
+        try:
+            text_bbox = draw.textbbox((bbox[0], bbox[1] - 20), text, font=font)
+            draw.rectangle(text_bbox, fill="red")
+            draw.text((bbox[0], bbox[1] - 20), text, fill="white", font=font)
+        except:
+            # Fallback for older Pillow versions
+            draw.text((bbox[0], bbox[1] - 20), text, fill="red", font=font)
+    
+    return img_copy
+
+
+def image_to_base64(image: Image.Image) -> str:
+    """Convert PIL Image to base64 string."""
+    buffered = io.BytesIO()
+    image.save(buffered, format="PNG")
+    return base64.b64encode(buffered.getvalue()).decode()
+
+
+# ============================================================================
+# CORE ANALYSIS FUNCTION
+# ============================================================================
+
+def analyze_image(
+    image: Optional[Image.Image],
+    location: str,
+    notes: str,
+    save_to_history: bool,
+    gps_coords: str
+) -> Tuple[Optional[Image.Image], str, str, str]:
+    """
+    Main analysis function called when user clicks "Start Analysis".
+    
+    Returns:
+        - annotated_image: Image with bounding boxes
+        - detection_text: Detection results summary
+        - plan_text: Cleanup plan
+        - report_text: Generated report
+    """
+    if image is None:
+        return None, "⚠️ Please upload an image first.", "", ""
+    
+    # Parse GPS coordinates if provided
+    latitude, longitude = None, None
+    if gps_coords and gps_coords.strip():
+        try:
+            parts = gps_coords.split(',')
+            if len(parts) == 2:
+                latitude = float(parts[0].strip())
+                longitude = float(parts[1].strip())
+        except:
+            pass  # Invalid format, continue without coords
+    
+    try:
+        # Run the full workflow
+        result = run_cleanup_workflow(
+            image=image,
+            location=location if location.strip() else None,
+            notes=notes if notes.strip() else None,
+            save_to_history=save_to_history,
+            use_llm_enhancement=False,  # Can make this a checkbox
+            latitude=latitude,
+            longitude=longitude
+        )
+        
+        if result["status"] == "no_trash":
+            return image, result["summary"], "", ""
+        
+        # Draw boxes on image
+        annotated_image = draw_boxes_on_image(
+            image,
+            result["detection_results"]["detections"]
+        )
+        
+        # Format detection results
+        detection_text = f"""### 🔍 Detection Results
+
+{result['detection_results']['summary']}
+
+**Items Detected:**
+"""
+        for det in result["detection_results"]["detections"]:
+            label = det["label"].replace("_", " ").title()
+            detection_text += f"- {label} (confidence: {det['score']:.0%})\n"
+        
+        # Format plan
+        plan = result["plan"]
+        plan_text = f"""### 📋 Cleanup Plan
+
+**Severity Level:** {plan['severity'].upper()}
+
+**Resources Needed:**
+- 👥 Volunteers: {plan['recommended_volunteers']}
+- ⏱️ Estimated Time: {plan['estimated_time_minutes']} minutes
+- 📅 Urgency: Within {plan['urgency_days']} day(s)
+
+**Equipment:**
+"""
+        for item in plan['equipment_needed']:
+            plan_text += f"- {item}\n"
+        
+        plan_text += f"\n**Environmental Impact:**\n{plan['environmental_impact']}\n"
+        
+        if result.get("event_id"):
+            plan_text += f"\n✅ Saved! ID: {result['event_id']}"
+        
+        # Return report
+        report_text = result["report"]
+        
+        return annotated_image, detection_text, plan_text, report_text
+    
+    except Exception as e:
+        error_msg = f"❌ Error during analysis: {str(e)}"
+        return image, error_msg, "", ""
+
+
+# ============================================================================
+# HISTORY & HOTSPOT FUNCTIONS
+# ============================================================================
+
+def load_history(days_filter: int, location_filter: str, severity_filter: str) -> str:
+    """Load and format event history."""
+    try:
+        # Apply filters
+        query_params = {"days": days_filter if days_filter > 0 else None}
+        
+        if location_filter.strip():
+            query_params["location"] = location_filter.strip()
+        
+        if severity_filter != "All":
+            query_params["severity"] = severity_filter.lower()
+        
+        result = query_events(**query_params)
+        
+        if not result["events"]:
+            return "No events found matching your filters."
+        
+        # Format output
+        output = f"""### 📊 Event History
+
+**Summary:**
+- Total events: {result['summary']['total_events']}
+- Total trash items: {result['summary']['total_trash_items']}
+- Average per event: {result['summary']['avg_trash_per_event']:.1f}
+- Unique locations: {result['summary']['unique_locations']}
+
+---
+
+**Recent Events:**
+
+"""
+        for event in result["events"][:20]:  # Show last 20
+            output += f"""
+**Event #{event['id']}** - {event['timestamp'][:19]}
+- Location: {event['location'] or 'Not specified'}
+- Severity: {event['severity'].upper()}
+- Items: {event['trash_count']}
+- Categories: {', '.join(event['categories'])}
+- Status: {'✅ Cleaned' if event['cleaned'] else '⏳ Pending'}
+---
+"""
+        
+        return output
+    
+    except Exception as e:
+        return f"❌ Error loading history: {str(e)}"
+
+
+def load_hotspots(days: int) -> str:
+    """Load and format hotspot analysis."""
+    try:
+        result = analyze_hotspots(days=days)
+        
+        if not result["hotspots"]:
+            return result.get("message", "No hotspots found.")
+        
+        output = f"""### 🔥 Trash Hotspots Analysis
+
+{result['recommendation']}
+
+---
+
+**All Hotspots ({result['count']} locations):**
+
+"""
+        for i, hotspot in enumerate(result["hotspots"], 1):
+            output += f"""
+**{i}. {hotspot['location']}**
+- Events: {hotspot['event_count']}
+- Total trash items: {hotspot['total_trash']}
+- Average per event: {hotspot['avg_trash']:.1f}
+- Last seen: {hotspot['last_event'][:19]}
+- Severity levels: {hotspot['severities']}
+---
+"""
+        
+        return output
+    
+    except Exception as e:
+        return f"❌ Error analyzing hotspots: {str(e)}"
+
+
+# ============================================================================
+# CHATBOT FUNCTION
+# ============================================================================
+
+def chat_with_agent(message: str, history: list) -> str:
+    """Handle chat interactions with the CleanCity agent."""
+    try:
+        llm = get_llm_client()
+        
+        # Build context from history
+        context = ""
+        for user_msg, bot_msg in history:
+            context += f"User: {user_msg}\nAgent: {bot_msg}\n"
+        
+        # System prompt
+        system_prompt = """You are CleanCity Agent, a helpful AI assistant focused on 
+environmental cleanup and trash management. You help users:
+- Understand their trash detection results
+- Plan effective cleanup operations
+- Organize community action
+- Report issues to authorities
+- Analyze environmental impact
+
+Be friendly, practical, and encouraging. Keep responses concise but informative."""
+        
+        prompt = f"{context}User: {message}\nAgent:"
+        
+        response = llm.generate_text(
+            prompt,
+            system_prompt=system_prompt,
+            max_tokens=300,
+            temperature=0.7
+        )
+        
+        return response
+    
+    except Exception as e:
+        return f"I encountered an error: {str(e)}. Please try again or check your LLM configuration."
+
+
+# ============================================================================
+# GRADIO INTERFACE
+# ============================================================================
+
+def create_interface() -> gr.Blocks:
+    """Create and configure the Gradio interface."""
+    
+    with gr.Blocks(
+        title="CleanCity Agent",
+        theme=gr.themes.Soft(primary_hue="green")
+    ) as app:
+        # Header
+        gr.Markdown(f"# {TITLE}")
+        gr.Markdown(f"*{TAGLINE}*")
+        
+        with gr.Tabs():
+            # ================================================================
+            # TAB 1: MAIN ANALYSIS
+            # ================================================================
+            with gr.Tab("🔍 Analyze Image"):
+                with gr.Row():
+                    with gr.Column(scale=1):
+                        gr.Markdown("### Upload Image")
+                        image_input = gr.Image(
+                            type="pil",
+                            label="Street/Beach/Park Image",
+                            sources=["upload", "webcam"]
+                        )
+                        
+                        with gr.Row():
+                            location_input = gr.Textbox(
+                                label="Location (optional)",
+                                placeholder="e.g., Main Street Park, Downtown Beach...",
+                                lines=1,
+                                scale=4
+                            )
+                            get_location_btn = gr.Button(
+                                "📍 Get GPS",
+                                size="sm",
+                                scale=1
+                            )
+                        
+                        gps_coords = gr.Textbox(
+                            label="GPS Coordinates",
+                            placeholder="Latitude, Longitude (auto-filled when you click Get GPS)",
+                            lines=1,
+                            interactive=False,
+                            visible=False
+                        )
+                        
+                        notes_input = gr.Textbox(
+                            label="Notes (optional)",
+                            placeholder="Any additional context...",
+                            lines=2
+                        )
+                        
+                        save_history = gr.Checkbox(
+                            label="Save to history",
+                            value=True
+                        )
+                        
+                        analyze_btn = gr.Button(
+                            "🚀 Start Analysis",
+                            variant="primary",
+                            size="lg"
+                        )
+                    
+                    with gr.Column(scale=1):
+                        gr.Markdown("### Detection Results")
+                        output_image = gr.Image(
+                            type="pil",
+                            label="Annotated Image"
+                        )
+                
+                gr.Markdown("---")
+                
+                with gr.Row():
+                    with gr.Column():
+                        detection_output = gr.Markdown(label="Detections")
+                    
+                    with gr.Column():
+                        plan_output = gr.Markdown(label="Cleanup Plan")
+                
+                gr.Markdown("### 📄 Generated Report")
+                report_output = gr.Textbox(
+                    label="Email Report (copy & send to authorities)",
+                    lines=15,
+                    max_lines=20
+                )
+                
+                # Wire up the analyze button
+                analyze_btn.click(
+                    fn=analyze_image,
+                    inputs=[image_input, location_input, notes_input, save_history, gps_coords],
+                    outputs=[output_image, detection_output, plan_output, report_output]
+                )
+                
+                # Wire up GPS button with JavaScript to get browser location
+                get_location_btn.click(
+                    fn=None,
+                    inputs=[],
+                    outputs=[location_input, gps_coords],
+                    js="""
+                    async () => {
+                        try {
+                            const position = await new Promise((resolve, reject) => {
+                                navigator.geolocation.getCurrentPosition(resolve, reject, {
+                                    enableHighAccuracy: true,
+                                    timeout: 10000
+                                });
+                            });
+                            
+                            const lat = position.coords.latitude.toFixed(6);
+                            const lon = position.coords.longitude.toFixed(6);
+                            const coords = lat + ', ' + lon;
+                            
+                            // Reverse geocode to get location name
+                            try {
+                                const response = await fetch(
+                                    `https://nominatim.openstreetmap.org/reverse?format=json&lat=${lat}&lon=${lon}`
+                                );
+                                const data = await response.json();
+                                const location = data.display_name || `Location at ${coords}`;
+                                return [location, coords];
+                            } catch (e) {
+                                return [`Location at ${coords}`, coords];
+                            }
+                        } catch (error) {
+                            alert('GPS Error: ' + error.message + '\\n\\nPlease enable location services in your browser.');
+                            return ['', ''];
+                        }
+                    }
+                    """
+                )
+            
+            # ================================================================
+            # TAB 2: USER GUIDE
+            # ================================================================
+            with gr.Tab("📖 How It Works"):
+                gr.Markdown(GUIDE_CONTENT)
+                gr.Markdown("---")
+                gr.Markdown(FAQ_CONTENT)
+            
+            # ================================================================
+            # TAB 3: HISTORY
+            # ================================================================
+            with gr.Tab("📊 Event History"):
+                gr.Markdown("### View Past Trash Detection Events")
+                
+                with gr.Row():
+                    days_filter = gr.Slider(
+                        minimum=0,
+                        maximum=365,
+                        value=30,
+                        step=1,
+                        label="Last N days (0 = all time)"
+                    )
+                    location_filter = gr.Textbox(
+                        label="Filter by location (partial match)",
+                        placeholder="e.g., Park"
+                    )
+                    severity_filter = gr.Dropdown(
+                        choices=["All", "Low", "Medium", "High"],
+                        value="All",
+                        label="Filter by severity"
+                    )
+                
+                load_history_btn = gr.Button("🔄 Load History", variant="primary")
+                history_output = gr.Markdown()
+                
+                load_history_btn.click(
+                    fn=load_history,
+                    inputs=[days_filter, location_filter, severity_filter],
+                    outputs=history_output
+                )
+            
+            # ================================================================
+            # TAB 4: HOTSPOTS
+            # ================================================================
+            with gr.Tab("🔥 Hotspot Analysis"):
+                gr.Markdown("### Identify Recurring Problem Areas")
+                gr.Markdown(
+                    "Hotspots are locations with multiple trash events. "
+                    "Use this to prioritize cleanup efforts and request permanent solutions."
+                )
+                
+                hotspot_days = gr.Slider(
+                    minimum=7,
+                    maximum=365,
+                    value=30,
+                    step=7,
+                    label="Analyze last N days"
+                )
+                
+                load_hotspots_btn = gr.Button("🔍 Find Hotspots", variant="primary")
+                hotspots_output = gr.Markdown()
+                
+                load_hotspots_btn.click(
+                    fn=load_hotspots,
+                    inputs=hotspot_days,
+                    outputs=hotspots_output
+                )
+            
+            # ================================================================
+            # TAB 5: CHAT WITH AGENT
+            # ================================================================
+            with gr.Tab("💬 Chat with Agent"):
+                gr.Markdown("### Ask Questions or Get Help")
+                gr.Markdown(
+                    "Chat with the CleanCity Agent to get advice on cleanup strategies, "
+                    "interpretation of results, or general environmental questions."
+                )
+                
+                chatbot = gr.Chatbot(height=500)
+                msg = gr.Textbox(
+                    label="Your message",
+                    placeholder="Ask me anything about cleanup planning..."
+                )
+                
+                with gr.Row():
+                    submit = gr.Button("Send", variant="primary")
+                    clear = gr.Button("Clear Chat")
+                
+                def respond(message, chat_history):
+                    bot_response = chat_with_agent(message, chat_history)
+                    chat_history.append((message, bot_response))
+                    return "", chat_history
+                
+                submit.click(respond, [msg, chatbot], [msg, chatbot])
+                msg.submit(respond, [msg, chatbot], [msg, chatbot])
+                clear.click(lambda: [], None, chatbot)
+        
+        # Footer
+        gr.Markdown("---")
+        gr.Markdown(
+            "*CleanCity Agent is a prototype tool for community environmental action. "
+            "Always verify AI results manually before taking action.*"
+        )
+    
+    return app
+
+
+# ============================================================================
+# MAIN ENTRY POINT
+# ============================================================================
+
+# Create the Gradio app at module level for HuggingFace Spaces compatibility
+print("=" * 60)
+print("🌍 CleanCity Agent - Initializing...")
+print("=" * 60)
+
+# Initialize LLM client (will print status)
+get_llm_client()
+
+print("\n✓ Creating Gradio interface...")
+app = create_interface()
+print("✓ Gradio interface ready!")
+print("=" * 60 + "\n")
+
+
+def main():
+    """Launch the Gradio application (local development)."""
+    print("🚀 Launching web server...")
+    print("Access the app at: http://localhost:7860\n")
+    
+    app.launch(
+        server_name="0.0.0.0",  # Allow external connections
+        server_port=7860,
+        share=False,  # Set to True to create public link
+        show_error=True
+    )
+
+
+if __name__ == "__main__":
+    main()

llm_client.py

@@ -1,368 +1,214 @@
-"""
-CleanCity Agent - LLM Client
-
-Modern multi-provider LLM client supporting latest APIs:
-- Anthropic Claude (3.5 Sonnet, 3 Opus)
-- OpenAI (GPT-4o, GPT-4 Turbo)
-- Google Gemini (1.5 Pro, Flash)
-
-Features:
-- Automatic provider selection from environment
-- Graceful fallback to offline mode
-- Unified API across providers
-- Type hints and error handling
-- Streaming support (optional)
-"""
-
-import os
-from typing import Optional, Literal
-from dotenv import load_dotenv
-import logging
-
-# Load environment variables
-load_dotenv()
-
-# Configure logging
-logging.basicConfig(level=os.getenv("LOG_LEVEL", "INFO"))
-logger = logging.getLogger(__name__)
-
-# Type definitions
-LLMProvider = Literal["anthropic", "openai", "gemini", "offline"]
-
-
-class LLMClient:
-    """
-    Unified LLM client with multi-provider support.
-    
-    Automatically initializes the configured provider and falls back
-    to offline mode if API keys are missing or packages unavailable.
-    """
-    
-    def __init__(self, provider: Optional[str] = None):
-        """
-        Initialize LLM client.
-        
-        Args:
-            provider: Override environment provider setting
-        """
-        self.provider: LLMProvider = (provider or os.getenv("LLM_PROVIDER", "offline")).lower()
-        self._client = None
-        self._initialize()
-    
-    def _initialize(self) -> None:
-        """Initialize the selected LLM provider."""
-        if self.provider == "anthropic":
-            self._init_anthropic()
-        elif self.provider == "openai":
-            self._init_openai()
-        elif self.provider == "gemini":
-            self._init_gemini()
-        else:
-            self._init_offline()
-    
-    def _init_anthropic(self) -> None:
-        """Initialize Anthropic Claude client."""
-        api_key = os.getenv("ANTHROPIC_API_KEY")
-        
-        if not api_key:
-            logger.warning("⚠️  ANTHROPIC_API_KEY not set, falling back to offline mode")
-            self.provider = "offline"
-            return
-        
-        try:
-            import anthropic
-            self._client = anthropic.Anthropic(api_key=api_key)
-            self.model = os.getenv("ANTHROPIC_MODEL", "claude-3-5-sonnet-20241022")
-            logger.info(f"✅ Anthropic Claude initialized (model: {self.model})")
-        except ImportError:
-            logger.warning("⚠️  Anthropic package not installed, falling back to offline mode")
-            self.provider = "offline"
-        except Exception as e:
-            logger.error(f"❌ Anthropic initialization failed: {e}")
-            self.provider = "offline"
-    
-    def _init_openai(self) -> None:
-        """Initialize OpenAI client."""
-        api_key = os.getenv("OPENAI_API_KEY")
-        
-        if not api_key:
-            logger.warning("⚠️  OPENAI_API_KEY not set, falling back to offline mode")
-            self.provider = "offline"
-            return
-        
-        try:
-            import openai
-            self._client = openai.OpenAI(api_key=api_key)
-            self.model = os.getenv("OPENAI_MODEL", "gpt-4o")
-            logger.info(f"✅ OpenAI initialized (model: {self.model})")
-        except ImportError:
-            logger.warning("⚠️  OpenAI package not installed, falling back to offline mode")
-            self.provider = "offline"
-        except Exception as e:
-            logger.error(f"❌ OpenAI initialization failed: {e}")
-            self.provider = "offline"
-    
-    def _init_gemini(self) -> None:
-        """Initialize Google Gemini client."""
-        api_key = os.getenv("GEMINI_API_KEY")
-        
-        if not api_key:
-            logger.warning("⚠️  GEMINI_API_KEY not set, falling back to offline mode")
-            self.provider = "offline"
-            return
-        
-        try:
-            import google.generativeai as genai
-            genai.configure(api_key=api_key)
-            self.model = os.getenv("GEMINI_MODEL", "gemini-1.5-pro")
-            self._client = genai.GenerativeModel(self.model)
-            logger.info(f"✅ Google Gemini initialized (model: {self.model})")
-        except ImportError:
-            logger.warning("⚠️  Google GenAI package not installed, falling back to offline mode")
-            self.provider = "offline"
-        except Exception as e:
-            logger.error(f"❌ Gemini initialization failed: {e}")
-            self.provider = "offline"
-    
-    def _init_offline(self) -> None:
-        """Initialize offline mode (mock responses)."""
-        logger.info("ℹ️  Running in offline mode (mock LLM responses)")
-        self.provider = "offline"
-    
-    def generate(
-        self,
-        prompt: str,
-        system_prompt: Optional[str] = None,
-        max_tokens: int = 2048,
-        temperature: float = 0.7
-    ) -> str:
-        """
-        Generate text completion.
-        
-        Args:
-            prompt: User prompt/query
-            system_prompt: Optional system instructions
-            max_tokens: Maximum tokens to generate
-            temperature: Sampling temperature (0.0-1.0)
-            
-        Returns:
-            Generated text response
-        """
-        try:
-            if self.provider == "anthropic":
-                return self._generate_anthropic(prompt, system_prompt, max_tokens, temperature)
-            elif self.provider == "openai":
-                return self._generate_openai(prompt, system_prompt, max_tokens, temperature)
-            elif self.provider == "gemini":
-                return self._generate_gemini(prompt, system_prompt, max_tokens, temperature)
-            else:
-                return self._generate_offline(prompt)
-        except Exception as e:
-            logger.error(f"⚠️  LLM generation failed: {e}, using offline fallback")
-            return self._generate_offline(prompt)
-    
-    def _generate_anthropic(
-        self,
-        prompt: str,
-        system_prompt: Optional[str],
-        max_tokens: int,
-        temperature: float
-    ) -> str:
-        """Generate using Anthropic Claude."""
-        messages = [{"role": "user", "content": prompt}]
-        
-        kwargs = {
-            "model": self.model,
-            "max_tokens": max_tokens,
-            "temperature": temperature,
-            "messages": messages
-        }
-        
-        if system_prompt:
-            kwargs["system"] = system_prompt
-        
-        response = self._client.messages.create(**kwargs)
-        return response.content[0].text
-    
-    def _generate_openai(
-        self,
-        prompt: str,
-        system_prompt: Optional[str],
-        max_tokens: int,
-        temperature: float
-    ) -> str:
-        """Generate using OpenAI GPT."""
-        messages = []
-        if system_prompt:
-            messages.append({"role": "system", "content": system_prompt})
-        messages.append({"role": "user", "content": prompt})
-        
-        response = self._client.chat.completions.create(
-            model=self.model,
-            messages=messages,
-            max_tokens=max_tokens,
-            temperature=temperature
-        )
-        return response.choices[0].message.content
-    
-    def _generate_gemini(
-        self,
-        prompt: str,
-        system_prompt: Optional[str],
-        max_tokens: int,
-        temperature: float
-    ) -> str:
-        """Generate using Google Gemini."""
-        full_prompt = prompt
-        if system_prompt:
-            full_prompt = f"{system_prompt}\n\n{prompt}"
-        
-        generation_config = {
-            "max_output_tokens": max_tokens,
-            "temperature": temperature,
-        }
-        
-        response = self._client.generate_content(
-            full_prompt,
-            generation_config=generation_config
-        )
-        return response.text
-    
-    def _generate_offline(self, prompt: str) -> str:
-        """Generate mock response in offline mode."""
-        # Simple keyword-based mock responses
-        prompt_lower = prompt.lower()
-        
-        if "cleanup" in prompt_lower or "plan" in prompt_lower:
-            return """Based on the detected trash, here's a recommended cleanup plan:
-
-**Severity**: Medium
-**Volunteers Needed**: 3-5 people
-**Estimated Time**: 1-2 hours
-**Equipment**: 
-- Trash bags (heavy duty)
-- Gloves
-- Grabber tools
-- Safety vests
-
-**Environmental Impact**: Removing this trash will help prevent pollution and protect local wildlife.
-
-**Recommendations**: 
-- Coordinate with local environmental groups
-- Consider installing waste bins in this area
-- Plan regular cleanup events"""
-        
-        elif "report" in prompt_lower:
-            return """# Cleanup Report
-
-**Location**: [Location from data]
-**Date**: [Current date]
-**Trash Detected**: [Count] items
-
-This area requires attention to prevent environmental degradation. Recommend scheduling a community cleanup event and installing proper waste disposal infrastructure.
-
-**Next Steps**:
-- Notify local authorities
-- Organize volunteer cleanup
-- Monitor area for recurring issues"""
-        
-        elif "chat" in prompt_lower or "question" in prompt_lower:
-            return """I'm here to help with trash cleanup planning! I can:
-- Analyze detected trash and recommend cleanup strategies
-- Estimate resources needed for cleanup
-- Generate reports for authorities
-- Provide environmental impact assessments
-- Suggest prevention measures
-
-What would you like to know?"""
-        
-        else:
-            return "I'm running in offline mode. For full AI capabilities, configure an API key in the .env file."
-    
-    def is_online(self) -> bool:
-        """Check if using a real LLM provider (not offline)."""
-        return self.provider != "offline"
-    
-    def get_info(self) -> dict:
-        """Get client information."""
-        return {
-            "provider": self.provider,
-            "online": self.is_online(),
-            "model": getattr(self, "model", None)
-        }
-
-
-# ============================================================================
-# Global Instance & Public API
-# ============================================================================
-
-_global_client: Optional[LLMClient] = None
-
-
-def get_llm_client(provider: Optional[str] = None) -> LLMClient:
-    """
-    Get or create the global LLM client instance.
-    
-    Args:
-        provider: Override default provider
-        
-    Returns:
-        LLMClient instance
-    """
-    global _global_client
-    if _global_client is None or provider is not None:
-        _global_client = LLMClient(provider)
-    return _global_client
-
-
-def generate_text(
-    prompt: str,
-    system_prompt: Optional[str] = None,
-    **kwargs
-) -> str:
-    """
-    Generate text using the global LLM client.
-    
-    Args:
-        prompt: User prompt
-        system_prompt: System instructions
-        **kwargs: Additional generation parameters
-        
-    Returns:
-        Generated text
-    """
-    client = get_llm_client()
-    return client.generate(prompt, system_prompt, **kwargs)
-
-
-# ============================================================================
-# Module Test
-# ============================================================================
-
-if __name__ == "__main__":
-    """Test the LLM client module."""
-    print("=" * 70)
-    print("Testing CleanCity LLM Client")
-    print("=" * 70)
-    
-    # Test initialization
-    print("\n1. Initializing LLM client...")
-    client = get_llm_client()
-    
-    info = client.get_info()
-    print(f"   Provider: {info['provider']}")
-    print(f"   Online: {info['online']}")
-    print(f"   Model: {info['model']}")
-    
-    # Test text generation
-    print("\n2. Testing text generation...")
-    test_prompt = "Generate a brief cleanup plan for a beach with plastic bottles."
-    
-    print(f"   Prompt: {test_prompt}")
-    print("\n   Response:")
-    response = client.generate(test_prompt, max_tokens=300)
-    print(f"   {response[:200]}...")
-    
-    print("\n" + "=" * 70)
-    print("✅ LLM Client test complete!")
-    print("=" * 70)
+"""
+LLM Client Abstraction Layer
+
+Provides unified interface to multiple LLM providers (Anthropic, OpenAI, Google Gemini).
+Includes offline fallback mode for demos without API keys.
+
+Configuration via environment variables:
+- LLM_PROVIDER: "anthropic" | "openai" | "gemini" | "offline"
+- ANTHROPIC_API_KEY
+- OPENAI_API_KEY
+- GEMINI_API_KEY
+"""
+
+import os
+from typing import Optional
+from dotenv import load_dotenv
+
+load_dotenv()
+
+
+class LLMClient:
+    """Unified LLM client with multi-provider support and offline mode."""
+    
+    def __init__(self):
+        self.provider = os.getenv("LLM_PROVIDER", "offline").lower()
+        self._client = None
+        self._initialize_client()
+    
+    def _initialize_client(self):
+        """Initialize the appropriate LLM client based on provider setting."""
+        if self.provider == "anthropic":
+            api_key = os.getenv("ANTHROPIC_API_KEY")
+            if api_key:
+                try:
+                    import anthropic
+                    self._client = anthropic.Anthropic(api_key=api_key)
+                    print("✓ Anthropic client initialized")
+                except ImportError:
+                    print("⚠ Anthropic package not installed, falling back to offline mode")
+                    self.provider = "offline"
+            else:
+                print("⚠ ANTHROPIC_API_KEY not set, using offline mode")
+                self.provider = "offline"
+        
+        elif self.provider == "openai":
+            api_key = os.getenv("OPENAI_API_KEY")
+            if api_key:
+                try:
+                    import openai
+                    self._client = openai.OpenAI(api_key=api_key)
+                    print("✓ OpenAI client initialized")
+                except ImportError:
+                    print("⚠ OpenAI package not installed, falling back to offline mode")
+                    self.provider = "offline"
+            else:
+                print("⚠ OPENAI_API_KEY not set, using offline mode")
+                self.provider = "offline"
+        
+        elif self.provider == "gemini":
+            api_key = os.getenv("GEMINI_API_KEY")
+            if api_key:
+                try:
+                    import google.generativeai as genai
+                    genai.configure(api_key=api_key)
+                    self._client = genai.GenerativeModel('gemini-pro')
+                    print("✓ Gemini client initialized")
+                except ImportError:
+                    print("⚠ Google GenAI package not installed, falling back to offline mode")
+                    self.provider = "offline"
+            else:
+                print("⚠ GEMINI_API_KEY not set, using offline mode")
+                self.provider = "offline"
+        
+        else:
+            print("ℹ Running in offline mode (mock responses)")
+            self.provider = "offline"
+    
+    def generate_text(
+        self,
+        prompt: str,
+        system_prompt: Optional[str] = None,
+        max_tokens: int = 1024,
+        temperature: float = 0.7
+    ) -> str:
+        """
+        Generate text completion from the configured LLM.
+        
+        Args:
+            prompt: User prompt/query
+            system_prompt: Optional system instructions
+            max_tokens: Maximum tokens to generate
+            temperature: Sampling temperature (0-1)
+            
+        Returns:
+            Generated text response
+        """
+        if self.provider == "offline":
+            return self._offline_response(prompt)
+        
+        try:
+            if self.provider == "anthropic":
+                return self._anthropic_generate(prompt, system_prompt, max_tokens, temperature)
+            elif self.provider == "openai":
+                return self._openai_generate(prompt, system_prompt, max_tokens, temperature)
+            elif self.provider == "gemini":
+                return self._gemini_generate(prompt, system_prompt, max_tokens, temperature)
+        except Exception as e:
+            print(f"⚠ LLM API error: {e}, falling back to offline mode")
+            return self._offline_response(prompt)
+        
+        return self._offline_response(prompt)
+    
+    def _anthropic_generate(self, prompt: str, system_prompt: Optional[str], max_tokens: int, temperature: float) -> str:
+        """Generate using Anthropic Claude."""
+        messages = [{"role": "user", "content": prompt}]
+        
+        kwargs = {
+            "model": "claude-3-5-sonnet-20241022",
+            "max_tokens": max_tokens,
+            "temperature": temperature,
+            "messages": messages
+        }
+        
+        if system_prompt:
+            kwargs["system"] = system_prompt
+        
+        response = self._client.messages.create(**kwargs)
+        return response.content[0].text
+    
+    def _openai_generate(self, prompt: str, system_prompt: Optional[str], max_tokens: int, temperature: float) -> str:
+        """Generate using OpenAI GPT."""
+        messages = []
+        if system_prompt:
+            messages.append({"role": "system", "content": system_prompt})
+        messages.append({"role": "user", "content": prompt})
+        
+        response = self._client.chat.completions.create(
+            model="gpt-4o",
+            messages=messages,
+            max_tokens=max_tokens,
+            temperature=temperature
+        )
+        return response.choices[0].message.content
+    
+    def _gemini_generate(self, prompt: str, system_prompt: Optional[str], max_tokens: int, temperature: float) -> str:
+        """Generate using Google Gemini."""
+        full_prompt = prompt
+        if system_prompt:
+            full_prompt = f"{system_prompt}\n\n{prompt}"
+        
+        response = self._client.generate_content(
+            full_prompt,
+            generation_config={
+                "max_output_tokens": max_tokens,
+                "temperature": temperature
+            }
+        )
+        return response.text
+    
+    def _offline_response(self, prompt: str) -> str:
+        """Generate mock responses for offline/demo mode."""
+        prompt_lower = prompt.lower()
+        
+        # Pattern matching for common requests
+        if "cleanup" in prompt_lower or "plan" in prompt_lower:
+            return """Based on the detected trash, here's a recommended cleanup plan:
+
+**Severity Level**: Medium
+
+**Recommended Actions**:
+- Deploy 2-3 volunteers with standard cleanup equipment
+- Estimated time: 45-60 minutes
+- Bring 3-4 heavy-duty trash bags
+- Consider gloves and grabber tools for safety
+
+**Environmental Impact**: Moderate littering with potential harm to local wildlife if not addressed.
+
+**Urgency**: Should be cleaned within 1-2 days to prevent accumulation."""
+        
+        elif "report" in prompt_lower:
+            return """**Trash Cleanup Report**
+
+Location: [User-specified location]
+Date: [Current date]
+
+We have identified significant litter accumulation requiring attention. The area contains multiple pieces of trash including plastic bottles, food wrappers, and other waste materials.
+
+Recommended immediate action by city services to maintain public health and environmental standards.
+
+Contact: [Your community group]"""
+        
+        elif "severity" in prompt_lower or "analyze" in prompt_lower:
+            return "Based on the number and type of trash items detected, this appears to be a **medium severity** situation requiring attention within 1-2 days."
+        
+        else:
+            return """I've analyzed the image and detected several trash items. The situation requires moderate attention with a cleanup effort estimated at 2-3 volunteers for about 45-60 minutes. This will help maintain the cleanliness and environmental health of the area."""
+
+
+# Global singleton instance
+_llm_client: Optional[LLMClient] = None
+
+
+def get_llm_client() -> LLMClient:
+    """Get or create the global LLM client instance."""
+    global _llm_client
+    if _llm_client is None:
+        _llm_client = LLMClient()
+    return _llm_client
+
+
+def generate_text(prompt: str, system_prompt: Optional[str] = None, **kwargs) -> str:
+    """Convenience function for text generation."""
+    client = get_llm_client()
+    return client.generate_text(prompt, system_prompt, **kwargs)

mcp_server.py

@@ -0,0 +1,275 @@
+"""
+MCP Server for CleanCity Agent
+
+Exposes trash detection and cleanup planning tools via the Model Context Protocol.
+Can be used by Claude Desktop or other MCP clients.
+"""
+
+from mcp.server import Server
+from mcp.types import Tool, TextContent
+import mcp.server.stdio
+import json
+from typing import Any
+
+from tools import (
+    detect_trash_mcp,
+    plan_cleanup,
+    log_event,
+    query_events,
+    generate_report
+)
+from tools.history_tool import get_hotspots, mark_cleaned
+
+
+# Initialize MCP server
+server = Server("cleancity-agent")
+
+
+@server.list_tools()
+async def list_tools() -> list[Tool]:
+    """List available MCP tools."""
+    return [
+        Tool(
+            name="detect_trash",
+            description="Detect trash objects in an image using computer vision. Returns bounding boxes, labels, and confidence scores.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "image_data": {
+                        "type": "string",
+                        "description": "Base64 encoded image data"
+                    }
+                },
+                "required": ["image_data"]
+            }
+        ),
+        Tool(
+            name="plan_cleanup",
+            description="Generate a cleanup action plan based on detected trash. Returns severity level, resource requirements, and recommendations.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "detections": {
+                        "type": "array",
+                        "description": "Array of trash detection objects from detect_trash",
+                        "items": {"type": "object"}
+                    },
+                    "location": {
+                        "type": "string",
+                        "description": "Location description (optional)"
+                    },
+                    "notes": {
+                        "type": "string",
+                        "description": "Additional context or notes (optional)"
+                    },
+                    "use_llm": {
+                        "type": "boolean",
+                        "description": "Use LLM for enhanced planning (optional, default: false)"
+                    }
+                },
+                "required": ["detections"]
+            }
+        ),
+        Tool(
+            name="log_event",
+            description="Log a trash detection event to the history database for tracking and analysis.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "detections": {
+                        "type": "array",
+                        "description": "Array of trash detection objects",
+                        "items": {"type": "object"}
+                    },
+                    "severity": {
+                        "type": "string",
+                        "description": "Severity level: low, medium, or high"
+                    },
+                    "location": {
+                        "type": "string",
+                        "description": "Location description (optional)"
+                    },
+                    "notes": {
+                        "type": "string",
+                        "description": "User notes (optional)"
+                    }
+                },
+                "required": ["detections", "severity"]
+            }
+        ),
+        Tool(
+            name="query_events",
+            description="Query trash events from history database with filtering options. Useful for finding patterns and hotspots.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "days": {
+                        "type": "integer",
+                        "description": "Only events from last N days (optional)"
+                    },
+                    "location": {
+                        "type": "string",
+                        "description": "Filter by location (partial match, optional)"
+                    },
+                    "severity": {
+                        "type": "string",
+                        "description": "Filter by severity: low, medium, high (optional)"
+                    },
+                    "limit": {
+                        "type": "integer",
+                        "description": "Maximum results to return (default: 100)"
+                    }
+                }
+            }
+        ),
+        Tool(
+            name="get_hotspots",
+            description="Identify locations with recurring trash problems based on historical data.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "min_events": {
+                        "type": "integer",
+                        "description": "Minimum events to qualify as hotspot (default: 2)"
+                    },
+                    "days": {
+                        "type": "integer",
+                        "description": "Time window in days (optional, default: 30)"
+                    }
+                }
+            }
+        ),
+        Tool(
+            name="generate_report",
+            description="Generate a formatted report for trash detection event, suitable for city authorities or documentation.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "detections": {
+                        "type": "array",
+                        "description": "Array of trash detection objects",
+                        "items": {"type": "object"}
+                    },
+                    "severity": {
+                        "type": "string",
+                        "description": "Severity level"
+                    },
+                    "location": {
+                        "type": "string",
+                        "description": "Location description (optional)"
+                    },
+                    "notes": {
+                        "type": "string",
+                        "description": "Additional notes (optional)"
+                    },
+                    "plan": {
+                        "type": "object",
+                        "description": "Cleanup plan object (optional)"
+                    },
+                    "format": {
+                        "type": "string",
+                        "description": "Report format: email, markdown, or plain (default: email)"
+                    }
+                },
+                "required": ["detections", "severity"]
+            }
+        ),
+        Tool(
+            name="mark_cleaned",
+            description="Mark a logged event as cleaned/resolved.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "event_id": {
+                        "type": "integer",
+                        "description": "Database event ID to mark as cleaned"
+                    }
+                },
+                "required": ["event_id"]
+            }
+        )
+    ]
+
+
+@server.call_tool()
+async def call_tool(name: str, arguments) -> list[TextContent]:
+    """Handle tool execution."""
+    try:
+        if name == "detect_trash":
+            result = detect_trash_mcp(arguments["image_data"])
+        
+        elif name == "plan_cleanup":
+            result = plan_cleanup(
+                detections=arguments["detections"],
+                location=arguments.get("location"),
+                notes=arguments.get("notes"),
+                use_llm=arguments.get("use_llm", False)
+            )
+        
+        elif name == "log_event":
+            result = log_event(
+                detections=arguments["detections"],
+                severity=arguments["severity"],
+                location=arguments.get("location"),
+                notes=arguments.get("notes")
+            )
+        
+        elif name == "query_events":
+            result = query_events(
+                days=arguments.get("days"),
+                location=arguments.get("location"),
+                severity=arguments.get("severity"),
+                limit=arguments.get("limit", 100)
+            )
+        
+        elif name == "get_hotspots":
+            result = get_hotspots(
+                min_events=arguments.get("min_events", 2),
+                days=arguments.get("days", 30)
+            )
+        
+        elif name == "generate_report":
+            result = generate_report(
+                detections=arguments["detections"],
+                severity=arguments["severity"],
+                location=arguments.get("location"),
+                notes=arguments.get("notes"),
+                plan=arguments.get("plan"),
+                format=arguments.get("format", "email")
+            )
+        
+        elif name == "mark_cleaned":
+            result = mark_cleaned(arguments["event_id"])
+        
+        else:
+            return [TextContent(
+                type="text",
+                text=f"Unknown tool: {name}"
+            )]
+        
+        # Return result as JSON
+        return [TextContent(
+            type="text",
+            text=json.dumps(result, indent=2)
+        )]
+    
+    except Exception as e:
+        return [TextContent(
+            type="text",
+            text=f"Error executing {name}: {str(e)}"
+        )]
+
+
+async def main():
+    """Run the MCP server."""
+    async with mcp.server.stdio.stdio_server() as (read_stream, write_stream):
+        await server.run(
+            read_stream,
+            write_stream,
+            server.create_initialization_options()
+        )
+
+
+if __name__ == "__main__":
+    import asyncio
+    asyncio.run(main())

requirements.txt

@@ -1,49 +1,32 @@
-# CleanCity Agent - Modern Dependencies
-# Python 3.11+ required
-# Last updated: November 2025
-
-# ============================================================================
-# Core Web Framework
-# ============================================================================
-gradio==5.9.1                    # Latest Gradio for modern web UI
-
-# ============================================================================
-# Computer Vision & AI
-# ============================================================================
-ultralytics>=8.3.0               # YOLOv8/v11 for trash detection
-torch>=2.0.0                     # PyTorch (YOLO dependency)
-torchvision>=0.15.0              # torchvision
-opencv-python>=4.8.0             # OpenCV for image processing
-
-# ============================================================================
-# Image Processing
-# ============================================================================
-pillow>=10.0.0                   # PIL for image handling
-numpy>=1.24.0                    # NumPy
-matplotlib>=3.7.0                # Matplotlib for visualizations
-
-# ============================================================================
-# LLM APIs (Latest SDKs)
-# ============================================================================
-anthropic>=0.25.0                # Anthropic Claude SDK
-openai>=1.0.0                    # OpenAI SDK
-google-generativeai>=0.3.0       # Google Gemini SDK
-
-# ============================================================================
-# MCP (Model Context Protocol)
-# ============================================================================
-mcp>=1.1.2                       # Latest MCP for Claude Desktop integration
-
-# ============================================================================
-# Utilities
-# ============================================================================
-python-dotenv>=1.0.0             # Environment variable management
-python-dateutil>=2.8.0           # Date/time utilities
-httpx>=0.24.0                    # Modern async HTTP client
-
-# ============================================================================
-# Development (Optional)
-# ============================================================================
-# pytest>=8.3.3                  # For testing
-# black>=24.10.0                 # Code formatting
-# ruff>=0.8.0                    # Fast Python linter
+# CleanCity Agent - Production Dependencies
+# Python 3.11+ required
+
+# Core UI Framework
+gradio==5.9.1
+
+# MCP (Model Context Protocol) - using compatible version without fastmcp
+mcp==1.1.2
+
+# Image Processing
+pillow>=10.4.0
+
+# LLM Clients
+anthropic>=0.39.0
+openai>=1.54.0
+google-generativeai>=0.8.0
+
+# Environment & Configuration
+python-dotenv>=1.0.0
+
+# Data Visualization (for overlays)
+matplotlib>=3.9.0
+numpy>=2.1.0
+
+# HTTP client for potential external APIs
+httpx>=0.28.0
+
+# Computer Vision - YOLO for trash detection
+ultralytics>=8.0.0
+
+# Database (SQLite is stdlib, but we'll use this for better datetime handling)
+python-dateutil>=2.9.0

tools/__init__.py

@@ -0,0 +1,14 @@
+"""Tools package for CleanCity Agent MCP server."""
+
+from .trash_detection_tool import detect_trash_mcp
+from .cleanup_planner_tool import plan_cleanup
+from .history_tool import log_event, query_events
+from .report_generator_tool import generate_report
+
+__all__ = [
+    "detect_trash_mcp",
+    "plan_cleanup",
+    "log_event",
+    "query_events",
+    "generate_report"
+]

tools/cleanup_planner_tool.py

@@ -0,0 +1,181 @@
+"""
+Cleanup Planning MCP Tool
+
+Analyzes detected trash and generates cleanup action plans.
+"""
+
+from typing import Any, Optional
+from trash_model import Detection
+import llm_client
+
+
+def plan_cleanup(
+    detections: list[Detection],
+    location: Optional[str] = None,
+    notes: Optional[str] = None,
+    use_llm: bool = False
+):
+    """
+    Generate a cleanup plan based on detected trash.
+    
+    Args:
+        detections: List of trash detections from detection tool
+        location: Optional location description
+        notes: Optional additional context
+        use_llm: Whether to use LLM for enhanced planning (vs rule-based)
+    
+    Returns:
+        Dict containing:
+            - severity: "low" | "medium" | "high"
+            - recommended_volunteers: int
+            - estimated_time_minutes: int
+            - equipment_needed: list[str]
+            - urgency_days: int (recommended action timeframe)
+            - environmental_impact: str
+            - action_summary: str
+    """
+    if not detections:
+        return {
+            "severity": "low",
+            "recommended_volunteers": 0,
+            "estimated_time_minutes": 0,
+            "equipment_needed": [],
+            "urgency_days": 0,
+            "environmental_impact": "No trash detected - area appears clean.",
+            "action_summary": "No cleanup action needed at this time."
+        }
+    
+    # Rule-based analysis
+    count = len(detections)
+    avg_confidence = sum(d["score"] for d in detections) / count
+    categories = set(d["label"] for d in detections)
+    
+    # Calculate severity
+    if count >= 15 or len(categories) >= 6:
+        severity = "high"
+        urgency_days = 1
+        volunteers = 4 + (count // 10)
+        time_estimate = 90 + (count * 3)
+    elif count >= 7 or len(categories) >= 4:
+        severity = "medium"
+        urgency_days = 3
+        volunteers = 2 + (count // 8)
+        time_estimate = 45 + (count * 2)
+    else:
+        severity = "low"
+        urgency_days = 7
+        volunteers = 1 + (count // 5)
+        time_estimate = 20 + (count * 2)
+    
+    # Equipment recommendations
+    equipment = ["Heavy-duty trash bags", "Gloves", "Grabber tools"]
+    
+    if "glass_bottle" in categories:
+        equipment.append("Safety goggles")
+        equipment.append("Puncture-resistant bags")
+    
+    if count > 10:
+        equipment.append("Wheeled collection bin")
+    
+    # Environmental impact assessment
+    impact_descriptions = {
+        "high": "Significant environmental concern. Risk of wildlife harm, water contamination, and community health issues. Immediate action recommended.",
+        "medium": "Moderate environmental impact. Potential for wildlife interaction and visual pollution. Timely cleanup will prevent escalation.",
+        "low": "Minor environmental impact. Early intervention will maintain area cleanliness and prevent accumulation."
+    }
+    
+    plan = {
+        "severity": severity,
+        "recommended_volunteers": volunteers,
+        "estimated_time_minutes": time_estimate,
+        "equipment_needed": equipment,
+        "urgency_days": urgency_days,
+        "environmental_impact": impact_descriptions[severity],
+        "action_summary": _generate_action_summary(
+            severity, volunteers, time_estimate, count, categories
+        )
+    }
+    
+    # Optionally enhance with LLM
+    if use_llm:
+        plan["action_summary"] = _enhance_with_llm(plan, detections, location, notes)
+    
+    return plan
+
+
+def _generate_action_summary(
+    severity: str,
+    volunteers: int,
+    time_minutes: int,
+    count: int,
+    categories: set[str]
+) -> str:
+    """Generate human-readable action summary."""
+    category_list = ", ".join(sorted(categories)[:3])
+    if len(categories) > 3:
+        category_list += f" and {len(categories) - 3} other types"
+    
+    summary = f"""**Cleanup Plan - {severity.upper()} Priority**
+
+Detected {count} trash items including {category_list}.
+
+**Recommended Resources:**
+- {volunteers} volunteer(s)
+- Approximately {time_minutes} minutes
+- Standard cleanup equipment
+
+**Next Steps:**
+1. Gather volunteers and equipment
+2. Coordinate cleanup date/time
+3. Execute cleanup operation
+4. Dispose of collected waste properly
+5. Document completion for tracking
+"""
+    return summary
+
+
+def _enhance_with_llm(
+    plan,
+    detections: list[Detection],
+    location: Optional[str],
+    notes: Optional[str]
+) -> str:
+    """Use LLM to create more detailed, context-aware action summary."""
+    detection_summary = f"{len(detections)} items detected: "
+    detection_summary += ", ".join(set(d["label"] for d in detections))
+    
+    context_parts = [
+        f"Trash detection summary: {detection_summary}",
+        f"Severity assessment: {plan['severity']}",
+        f"Recommended volunteers: {plan['recommended_volunteers']}",
+        f"Estimated time: {plan['estimated_time_minutes']} minutes"
+    ]
+    
+    if location:
+        context_parts.append(f"Location: {location}")
+    if notes:
+        context_parts.append(f"Additional context: {notes}")
+    
+    prompt = f"""Based on this trash detection analysis, create a clear, actionable cleanup plan summary:
+
+{chr(10).join(context_parts)}
+
+Write a brief, practical summary that:
+1. States the situation clearly
+2. Recommends specific actions
+3. Estimates resources needed
+4. Explains why this matters for the environment
+
+Keep it concise (3-4 sentences)."""
+    
+    try:
+        enhanced = llm_client.generate_text(
+            prompt,
+            system_prompt="You are a helpful environmental cleanup coordinator. Be practical and encouraging.",
+            max_tokens=300,
+            temperature=0.7
+        )
+        return enhanced
+    except Exception as e:
+        print(f"LLM enhancement failed: {e}")
+        return plan["action_summary"]

tools/history_tool.py

@@ -0,0 +1,270 @@
+"""
+History Tracking MCP Tool
+
+Logs trash detection events and provides querying capabilities for analysis.
+Uses SQLite for persistent storage.
+"""
+
+import sqlite3
+import json
+from datetime import datetime, timedelta
+from typing import Optional, Any
+from pathlib import Path
+from trash_model import Detection
+
+
+DB_PATH = Path(__file__).parent.parent / "data" / "trash_events.db"
+
+
+def _get_connection() -> sqlite3.Connection:
+    """Get SQLite connection and ensure schema exists."""
+    DB_PATH.parent.mkdir(parents=True, exist_ok=True)
+    conn = sqlite3.connect(str(DB_PATH))
+    conn.row_factory = sqlite3.Row
+    
+    # Create schema if not exists
+    conn.execute("""
+        CREATE TABLE IF NOT EXISTS events (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            timestamp TEXT NOT NULL,
+            location TEXT,
+            latitude REAL,
+            longitude REAL,
+            severity TEXT NOT NULL,
+            trash_count INTEGER NOT NULL,
+            categories TEXT NOT NULL,
+            detections_json TEXT NOT NULL,
+            notes TEXT,
+            image_path TEXT,
+            cleaned BOOLEAN DEFAULT 0,
+            created_at TEXT DEFAULT CURRENT_TIMESTAMP
+        )
+    """)
+    
+    conn.execute("""
+        CREATE INDEX IF NOT EXISTS idx_timestamp ON events(timestamp)
+    """)
+    
+    conn.execute("""
+        CREATE INDEX IF NOT EXISTS idx_location ON events(location)
+    """)
+    
+    conn.execute("""
+        CREATE INDEX IF NOT EXISTS idx_severity ON events(severity)
+    """)
+    
+    conn.commit()
+    return conn
+
+
+def log_event(
+    detections: list[Detection],
+    severity: str,
+    location: Optional[str] = None,
+    notes: Optional[str] = None,
+    image_path: Optional[str] = None,
+    latitude: Optional[float] = None,
+    longitude: Optional[float] = None
+):
+    """
+    Log a trash detection event to the database.
+    
+    Args:
+        detections: List of trash detections
+        severity: "low" | "medium" | "high"
+        location: Human-readable location description
+        notes: Optional user notes
+        image_path: Optional path to saved image
+        latitude: Optional GPS latitude
+        longitude: Optional GPS longitude
+    
+    Returns:
+        Dict with event_id and confirmation message
+    """
+    conn = _get_connection()
+    
+    timestamp = datetime.now().isoformat()
+    trash_count = len(detections)
+    categories = json.dumps(list(set(d["label"] for d in detections)))
+    detections_json = json.dumps(detections)
+    
+    cursor = conn.execute("""
+        INSERT INTO events (
+            timestamp, location, latitude, longitude, severity,
+            trash_count, categories, detections_json, notes, image_path
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    """, (
+        timestamp, location, latitude, longitude, severity,
+        trash_count, categories, detections_json, notes, image_path
+    ))
+    
+    event_id = cursor.lastrowid
+    conn.commit()
+    conn.close()
+    
+    return {
+        "event_id": event_id,
+        "timestamp": timestamp,
+        "message": f"Event logged successfully (ID: {event_id})"
+    }
+
+
+def query_events(
+    days: Optional[int] = None,
+    location: Optional[str] = None,
+    severity: Optional[str] = None,
+    min_trash_count: Optional[int] = None,
+    cleaned_only: bool = False,
+    limit: int = 100
+):
+    """
+    Query trash events with filtering options.
+    
+    Args:
+        days: Only events from last N days
+        location: Filter by location (partial match)
+        severity: Filter by severity level
+        min_trash_count: Minimum trash items threshold
+        cleaned_only: Only show cleaned events
+        limit: Maximum results to return
+    
+    Returns:
+        Dict containing:
+            - events: List of matching events
+            - total_count: Total matching events
+            - summary: Aggregate statistics
+    """
+    conn = _get_connection()
+    
+    # Build query
+    conditions = []
+    params = []
+    
+    if days:
+        cutoff = (datetime.now() - timedelta(days=days)).isoformat()
+        conditions.append("timestamp >= ?")
+        params.append(cutoff)
+    
+    if location:
+        conditions.append("location LIKE ?")
+        params.append(f"%{location}%")
+    
+    if severity:
+        conditions.append("severity = ?")
+        params.append(severity)
+    
+    if min_trash_count:
+        conditions.append("trash_count >= ?")
+        params.append(min_trash_count)
+    
+    if cleaned_only:
+        conditions.append("cleaned = 1")
+    
+    where_clause = " AND ".join(conditions) if conditions else "1=1"
+    
+    # Get events
+    query = f"""
+        SELECT 
+            id, timestamp, location, latitude, longitude,
+            severity, trash_count, categories, notes, image_path, cleaned
+        FROM events
+        WHERE {where_clause}
+        ORDER BY timestamp DESC
+        LIMIT ?
+    """
+    params.append(limit)
+    
+    cursor = conn.execute(query, params)
+    events = [dict(row) for row in cursor.fetchall()]
+    
+    # Parse JSON fields
+    for event in events:
+        event["categories"] = json.loads(event["categories"])
+    
+    # Get summary statistics
+    summary_query = f"""
+        SELECT 
+            COUNT(*) as total_events,
+            SUM(trash_count) as total_trash_items,
+            AVG(trash_count) as avg_trash_per_event,
+            COUNT(DISTINCT location) as unique_locations
+        FROM events
+        WHERE {where_clause}
+    """
+    summary_cursor = conn.execute(summary_query, params[:-1])  # Exclude limit param
+    summary = dict(summary_cursor.fetchone())
+    
+    conn.close()
+    
+    return {
+        "events": events,
+        "total_count": len(events),
+        "summary": summary,
+        "filters_applied": {
+            "days": days,
+            "location": location,
+            "severity": severity,
+            "min_trash_count": min_trash_count
+        }
+    }
+
+
+def get_hotspots(min_events: int = 2, days: Optional[int] = 30):
+    """
+    Identify locations with recurring trash problems.
+    
+    Args:
+        min_events: Minimum number of events to qualify as hotspot
+        days: Time window to analyze (None = all time)
+    
+    Returns:
+        Dict with hotspot locations and their statistics
+    """
+    conn = _get_connection()
+    
+    conditions = ["location IS NOT NULL"]
+    params = []
+    
+    if days:
+        cutoff = (datetime.now() - timedelta(days=days)).isoformat()
+        conditions.append("timestamp >= ?")
+        params.append(cutoff)
+    
+    where_clause = " AND ".join(conditions)
+    
+    query = f"""
+        SELECT 
+            location,
+            COUNT(*) as event_count,
+            SUM(trash_count) as total_trash,
+            AVG(trash_count) as avg_trash,
+            MAX(timestamp) as last_event,
+            GROUP_CONCAT(DISTINCT severity) as severities
+        FROM events
+        WHERE {where_clause}
+        GROUP BY location
+        HAVING event_count >= ?
+        ORDER BY event_count DESC, total_trash DESC
+    """
+    params.append(min_events)
+    
+    cursor = conn.execute(query, params)
+    hotspots = [dict(row) for row in cursor.fetchall()]
+    
+    conn.close()
+    
+    return {
+        "hotspots": hotspots,
+        "count": len(hotspots),
+        "criteria": f"Locations with {min_events}+ events" + (f" in last {days} days" if days else "")
+    }
+
+
+def mark_cleaned(event_id: int):
+    """Mark an event as cleaned."""
+    conn = _get_connection()
+    conn.execute("UPDATE events SET cleaned = 1 WHERE id = ?", (event_id,))
+    conn.commit()
+    conn.close()
+    
+    return {"message": f"Event {event_id} marked as cleaned"}

tools/report_generator_tool.py

@@ -0,0 +1,274 @@
+"""
+Report Generator MCP Tool
+
+Generates formatted reports for trash detection events.
+Suitable for city authorities, community groups, or documentation.
+"""
+
+from typing import Optional, Any
+from datetime import datetime
+from trash_model import Detection
+import llm_client
+
+
+def generate_report(
+    detections: list[Detection],
+    severity: str,
+    location: Optional[str] = None,
+    notes: Optional[str] = None,
+    event_id: Optional[int] = None,
+    plan: Optional[Any] = None,
+    format: str = "email"
+):
+    """
+    Generate a formatted report for trash detection event.
+    
+    Args:
+        detections: List of trash detections
+        severity: Severity level
+        location: Location description
+        notes: Additional notes
+        event_id: Database event ID if logged
+        plan: Optional cleanup plan data
+        format: "email" | "markdown" | "plain"
+    
+    Returns:
+        Dict with report text and metadata
+    """
+    if format == "email":
+        report_text = _generate_email_report(detections, severity, location, notes, plan)
+    elif format == "markdown":
+        report_text = _generate_markdown_report(detections, severity, location, notes, event_id, plan)
+    else:
+        report_text = _generate_plain_report(detections, severity, location, notes, plan)
+    
+    return {
+        "report": report_text,
+        "format": format,
+        "generated_at": datetime.now().isoformat(),
+        "event_id": event_id
+    }
+
+
+def _generate_email_report(
+    detections: list[Detection],
+    severity: str,
+    location: Optional[str],
+    notes: Optional[str],
+    plan: Optional[Any]
+) -> str:
+    """Generate email-formatted report for city authorities."""
+    location_str = location or "[Location to be specified]"
+    date_str = datetime.now().strftime("%B %d, %Y")
+    
+    # Summarize detections
+    categories = list(set(d["label"] for d in detections))
+    category_counts = {}
+    for det in detections:
+        label = det["label"]
+        category_counts[label] = category_counts.get(label, 0) + 1
+    
+    items_list = "\n".join([
+        f"  • {label.replace('_', ' ').title()}: {count} item(s)"
+        for label, count in sorted(category_counts.items())
+    ])
+    
+    urgency_text = {
+        "high": "URGENT - Immediate attention required",
+        "medium": "Moderate priority - Action needed within 1-3 days",
+        "low": "Low priority - Routine cleanup recommended"
+    }
+    
+    template = f"""Subject: Trash Cleanup Request - {location_str}
+
+Dear City Services / Environmental Department,
+
+I am writing to report significant litter accumulation that requires attention at the following location:
+
+**Location:** {location_str}
+**Date Reported:** {date_str}
+**Severity Level:** {severity.upper()} ({urgency_text.get(severity, '')})
+
+**Details of Trash Observed:**
+Total items detected: {len(detections)}
+
+{items_list}
+"""
+    
+    if notes:
+        template += f"\n**Additional Context:**\n{notes}\n"
+    
+    if plan:
+        template += f"""
+**Recommended Action:**
+- Estimated cleanup time: {plan.get('estimated_time_minutes', 'N/A')} minutes
+- Volunteers needed: {plan.get('recommended_volunteers', 'N/A')}
+- Equipment required: {', '.join(plan.get('equipment_needed', []))}
+- Urgency: Action within {plan.get('urgency_days', 'N/A')} day(s)
+"""
+    
+    template += """
+This accumulation poses environmental and health concerns for the community. I would appreciate a timely response regarding cleanup scheduling.
+
+Thank you for your attention to this matter.
+
+Best regards,
+[Your Name / Community Group]
+[Contact Information]
+"""
+    
+    return template
+
+
+def _generate_markdown_report(
+    detections: list[Detection],
+    severity: str,
+    location: Optional[str],
+    notes: Optional[str],
+    event_id: Optional[int],
+    plan: Optional[Any]
+) -> str:
+    """Generate Markdown-formatted report for documentation."""
+    location_str = location or "Unspecified location"
+    timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+    
+    # Group detections
+    category_counts = {}
+    for det in detections:
+        label = det["label"]
+        category_counts[label] = category_counts.get(label, 0) + 1
+    
+    report = f"""# Trash Detection Report
+
+## Event Information
+- **Event ID:** {event_id if event_id else 'Not logged'}
+- **Timestamp:** {timestamp}
+- **Location:** {location_str}
+- **Severity:** {severity.upper()}
+
+## Detection Summary
+- **Total Items:** {len(detections)}
+- **Unique Categories:** {len(category_counts)}
+
+### Items Breakdown
+"""
+    
+    for label, count in sorted(category_counts.items(), key=lambda x: x[1], reverse=True):
+        report += f"- **{label.replace('_', ' ').title()}:** {count} item(s)\n"
+    
+    if plan:
+        report += f"""
+## Cleanup Plan
+- **Recommended Volunteers:** {plan.get('recommended_volunteers', 'N/A')}
+- **Estimated Time:** {plan.get('estimated_time_minutes', 'N/A')} minutes
+- **Urgency:** Within {plan.get('urgency_days', 'N/A')} day(s)
+- **Equipment Needed:** 
+"""
+        for equipment in plan.get('equipment_needed', []):
+            report += f"  - {equipment}\n"
+        
+        report += f"\n### Environmental Impact\n{plan.get('environmental_impact', 'N/A')}\n"
+    
+    if notes:
+        report += f"\n## Additional Notes\n{notes}\n"
+    
+    report += "\n---\n*Generated by CleanCity Agent*"
+    
+    return report
+
+
+def _generate_plain_report(
+    detections: list[Detection],
+    severity: str,
+    location: Optional[str],
+    notes: Optional[str],
+    plan: Optional[Any]
+) -> str:
+    """Generate plain text report."""
+    lines = [
+        "=" * 60,
+        "TRASH DETECTION REPORT",
+        "=" * 60,
+        "",
+        f"Date: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}",
+        f"Location: {location or 'Unspecified'}",
+        f"Severity: {severity.upper()}",
+        "",
+        f"Total Items Detected: {len(detections)}",
+        ""
+    ]
+    
+    # Group items
+    category_counts = {}
+    for det in detections:
+        label = det["label"]
+        category_counts[label] = category_counts.get(label, 0) + 1
+    
+    lines.append("Items by Category:")
+    for label, count in sorted(category_counts.items()):
+        lines.append(f"  - {label.replace('_', ' ').title()}: {count}")
+    
+    if plan:
+        lines.extend([
+            "",
+            "Cleanup Recommendations:",
+            f"  - Volunteers needed: {plan.get('recommended_volunteers', 'N/A')}",
+            f"  - Estimated time: {plan.get('estimated_time_minutes', 'N/A')} minutes",
+            f"  - Action within: {plan.get('urgency_days', 'N/A')} day(s)",
+            f"  - Equipment: {', '.join(plan.get('equipment_needed', []))}"
+        ])
+    
+    if notes:
+        lines.extend(["", "Notes:", notes])
+    
+    lines.extend(["", "=" * 60])
+    
+    return "\n".join(lines)
+
+
+def generate_llm_enhanced_report(
+    detections: list[Detection],
+    severity: str,
+    location: Optional[str] = None,
+    notes: Optional[str] = None,
+    plan: Optional[Any] = None
+) -> str:
+    """Use LLM to generate a more sophisticated, context-aware report."""
+    context = f"""Trash detection event:
+- Location: {location or 'unspecified'}
+- Items detected: {len(detections)}
+- Severity: {severity}
+- Categories: {', '.join(set(d['label'] for d in detections))}
+"""
+    
+    if notes:
+        context += f"- Context: {notes}\n"
+    
+    if plan:
+        context += f"- Recommended volunteers: {plan.get('recommended_volunteers')}\n"
+        context += f"- Estimated cleanup time: {plan.get('estimated_time_minutes')} minutes\n"
+    
+    prompt = f"""Based on this trash detection data, write a professional report suitable for city authorities:
+
+{context}
+
+Create a clear, actionable report that:
+1. Describes the situation factually
+2. Emphasizes environmental/community impact
+3. Provides specific cleanup recommendations
+4. Has an appropriate professional tone
+
+Format as an email that could be sent to city services."""
+    
+    try:
+        report = llm_client.generate_text(
+            prompt,
+            system_prompt="You are a professional environmental reporter writing to city officials.",
+            max_tokens=500,
+            temperature=0.5
+        )
+        return report
+    except Exception as e:
+        print(f"LLM report generation failed: {e}")
+        # Fallback to template
+        return _generate_email_report(detections, severity, location, notes, plan)

tools/trash_detection_tool.py

@@ -0,0 +1,95 @@
+"""
+Trash Detection MCP Tool
+
+Wraps the trash detection model for use as an MCP tool.
+"""
+
+from typing import Any
+from PIL import Image
+import base64
+from io import BytesIO
+import json
+
+from trash_model import detect_trash, Detection
+
+
+def detect_trash_mcp(image_data: str | dict):
+    """
+    MCP tool wrapper for trash detection.
+    
+    Args:
+        image_data: Either:
+            - Base64 encoded image string
+            - Dict with 'path' key pointing to image file
+            - Dict with 'base64' key containing base64 image
+    
+    Returns:
+        Dict containing:
+            - detections: List of trash objects found
+            - count: Total number of items detected
+            - categories: Unique trash categories found
+            - summary: Human-readable summary
+    """
+    # Parse input
+    image = _load_image_from_input(image_data)
+    
+    # Run detection
+    detections = detect_trash(image)
+    
+    # Analyze results
+    categories = list(set(d["label"] for d in detections))
+    avg_confidence = sum(d["score"] for d in detections) / len(detections) if detections else 0
+    
+    summary = f"Detected {len(detections)} trash items across {len(categories)} categories. "
+    summary += f"Average confidence: {avg_confidence:.1%}"
+    
+    return {
+        "detections": detections,
+        "count": len(detections),
+        "categories": categories,
+        "average_confidence": avg_confidence,
+        "summary": summary,
+        "image_dimensions": {"width": image.width, "height": image.height}
+    }
+
+
+def _load_image_from_input(image_data: str | dict) -> Image.Image:
+    """Load PIL Image from various input formats."""
+    if isinstance(image_data, str):
+        # Assume base64 encoded
+        if image_data.startswith('data:image'):
+            # Remove data URL prefix
+            image_data = image_data.split(',', 1)[1]
+        image_bytes = base64.b64decode(image_data)
+        return Image.open(BytesIO(image_bytes))
+    
+    elif isinstance(image_data, dict):
+        if 'path' in image_data:
+            return Image.open(image_data['path'])
+        elif 'base64' in image_data:
+            image_bytes = base64.b64decode(image_data['base64'])
+            return Image.open(BytesIO(image_bytes))
+    
+    raise ValueError("Invalid image_data format. Provide base64 string or dict with 'path' or 'base64' key")
+
+
+def format_detections_for_display(detections: list[Detection]) -> str:
+    """Format detection results as readable text."""
+    if not detections:
+        return "No trash detected in the image."
+    
+    lines = [f"Found {len(detections)} trash items:\n"]
+    
+    # Group by category
+    by_category = {}
+    for det in detections:
+        category = det["label"]
+        if category not in by_category:
+            by_category[category] = []
+        by_category[category].append(det)
+    
+    for category, items in sorted(by_category.items()):
+        avg_conf = sum(d["score"] for d in items) / len(items)
+        lines.append(f"  • {category}: {len(items)} item(s) (confidence: {avg_conf:.1%})")
+    
+    return "\n".join(lines)

trash_model.py

@@ -1,251 +1,127 @@
-"""
-CleanCity Agent - Trash Detection Module
-
-Modern YOLO-based trash detection using Ultralytics (latest version).
-Supports YOLOv8, YOLOv9, YOLOv10, and YOLOv11 models.
-
-Features:
-- Automatic model loading with caching
-- Configurable confidence threshold
-- Type-safe detection results
-- Graceful error handling
-- Environment variable configuration
-"""
-
-import os
-from typing import TypedDict, Optional
-from pathlib import Path
-from PIL import Image
-import logging
-
-# Configure logging
-logging.basicConfig(level=logging.INFO)
-logger = logging.getLogger(__name__)
-
-# Import YOLO with error handling
-try:
-    from ultralytics import YOLO
-    YOLO_AVAILABLE = True
-except ImportError:
-    YOLO_AVAILABLE = False
-    logger.warning("⚠️  Ultralytics not installed. Run: pip install ultralytics")
-
-
-class Detection(TypedDict):
-    """Type-safe trash detection result."""
-    bbox: list[float]      # [x1, y1, x2, y2] in pixels
-    label: str             # Trash category/class name
-    score: float           # Confidence score (0.0 to 1.0)
-    class_id: int          # Class ID from model
-
-
-class TrashDetector:
-    """
-    Modern trash detection using YOLO.
-    
-    Singleton pattern - model loaded once and cached.
-    Thread-safe for multiple detections.
-    """
-    
-    _instance: Optional['TrashDetector'] = None
-    _model: Optional[YOLO] = None
-    
-    def __new__(cls):
-        """Ensure singleton instance."""
-        if cls._instance is None:
-            cls._instance = super().__new__(cls)
-        return cls._instance
-    
-    def __init__(self):
-        """Initialize detector (only runs once)."""
-        if self._model is None:
-            self._load_model()
-    
-    def _load_model(self) -> None:
-        """Load YOLO model from weights file."""
-        if not YOLO_AVAILABLE:
-            raise ImportError(
-                "Ultralytics package not installed. "
-                "Install with: pip install ultralytics"
-            )
-        
-        # Get model path from environment or use default
-        model_path = os.getenv("YOLO_MODEL_PATH", "Weights/best.pt")
-        model_file = Path(model_path)
-        
-        if not model_file.exists():
-            raise FileNotFoundError(
-                f"YOLO model file not found: {model_path}\n"
-                f"Please ensure the model file exists or update YOLO_MODEL_PATH in .env"
-            )
-        
-        logger.info(f"🔄 Loading YOLO model from {model_path}...")
-        
-        try:
-            self._model = YOLO(str(model_file))
-            logger.info(f"✅ Model loaded successfully!")
-            logger.info(f"   Model type: {self._model.model_name if hasattr(self._model, 'model_name') else 'YOLO'}")
-            logger.info(f"   Classes ({len(self._model.names)}): {list(self._model.names.values())}")
-        except Exception as e:
-            logger.error(f"❌ Failed to load model: {e}")
-            raise
-    
-    @property
-    def model(self) -> YOLO:
-        """Get the loaded YOLO model."""
-        if self._model is None:
-            raise RuntimeError("Model not loaded. Call _load_model() first.")
-        return self._model
-    
-    @property
-    def class_names(self) -> dict[int, str]:
-        """Get mapping of class IDs to names."""
-        return self.model.names
-    
-    def detect(
-        self,
-        image: Image.Image,
-        conf_threshold: Optional[float] = None,
-        verbose: bool = False
-    ) -> list[Detection]:
-        """
-        Detect trash objects in an image.
-        
-        Args:
-            image: PIL Image to analyze
-            conf_threshold: Confidence threshold (0.0-1.0). Uses env var if None.
-            verbose: Show detailed YOLO output
-            
-        Returns:
-            List of detections with bounding boxes, labels, and scores
-            
-        Raises:
-            RuntimeError: If model not loaded or detection fails
-        """
-        # Get confidence threshold
-        if conf_threshold is None:
-            conf_threshold = float(os.getenv("YOLO_CONFIDENCE", "0.25"))
-        
-        # Get verbose setting
-        if not verbose:
-            verbose = os.getenv("YOLO_VERBOSE", "false").lower() == "true"
-        
-        try:
-            # Run inference
-            results = self.model(
-                image,
-                conf=conf_threshold,
-                verbose=verbose
-            )
-            
-            # Parse results
-            detections: list[Detection] = []
-            
-            if len(results) > 0:
-                result = results[0]
-                
-                # Check if any detections found
-                if result.boxes is not None and len(result.boxes) > 0:
-                    # Extract detection data
-                    boxes = result.boxes.xyxy.cpu().numpy()      # [x1, y1, x2, y2]
-                    confidences = result.boxes.conf.cpu().numpy()
-                    class_ids = result.boxes.cls.cpu().numpy().astype(int)
-                    
-                    # Convert to Detection format
-                    for box, conf, cls_id in zip(boxes, confidences, class_ids):
-                        detection: Detection = {
-                            "bbox": box.tolist(),
-                            "label": self.model.names[cls_id],
-                            "score": float(conf),
-                            "class_id": int(cls_id)
-                        }
-                        detections.append(detection)
-                    
-                    logger.info(f"✅ Detected {len(detections)} trash objects")
-                else:
-                    logger.info("ℹ️  No trash detected in image")
-            
-            return detections
-            
-        except Exception as e:
-            logger.error(f"❌ Detection failed: {e}")
-            raise RuntimeError(f"Detection failed: {e}")
-
-
-# ============================================================================
-# Public API Functions
-# ============================================================================
-
-def detect_trash(
-    image: Image.Image,
-    conf_threshold: Optional[float] = None
-) -> list[Detection]:
-    """
-    Detect trash in an image (convenience function).
-    
-    Args:
-        image: PIL Image to analyze
-        conf_threshold: Confidence threshold (0.0-1.0)
-        
-    Returns:
-        List of trash detections
-    """
-    detector = TrashDetector()
-    return detector.detect(image, conf_threshold)
-
-
-def get_model_info() -> dict:
-    """
-    Get information about the loaded model.
-    
-    Returns:
-        Dictionary with model metadata
-    """
-    detector = TrashDetector()
-    return {
-        "available": YOLO_AVAILABLE,
-        "loaded": detector._model is not None,
-        "classes": detector.class_names if detector._model else {},
-        "num_classes": len(detector.class_names) if detector._model else 0,
-    }
-
-
-# ============================================================================
-# Module Test
-# ============================================================================
-
-if __name__ == "__main__":
-    """Test the trash detection module."""
-    print("=" * 70)
-    print("Testing CleanCity Trash Detection Module")
-    print("=" * 70)
-    
-    # Check if YOLO is available
-    print(f"\n1. YOLO Available: {YOLO_AVAILABLE}")
-    
-    if not YOLO_AVAILABLE:
-        print("❌ Please install ultralytics: pip install ultralytics")
-        exit(1)
-    
-    # Test model loading
-    print("\n2. Testing model loading...")
-    try:
-        detector = TrashDetector()
-        print("✅ Model loaded successfully")
-    except Exception as e:
-        print(f"❌ Model loading failed: {e}")
-        exit(1)
-    
-    # Print model info
-    print("\n3. Model Information:")
-    info = get_model_info()
-    print(f"   Classes: {info['num_classes']}")
-    print(f"   Labels: {list(info['classes'].values())}")
-    
-    # Test with a sample image (if exists)
-    print("\n4. Testing detection (requires sample image)...")
-    print("   To test detection, provide a test image")
-    
-    print("\n" + "=" * 70)
-    print("✅ Module test complete!")
-    print("=" * 70)
+"""
+Trash Detection Model Wrapper
+
+This module provides an interface for trash detection in images using YOLOv8.
+Loads a trained model from Weights/best.pt for real trash detection.
+"""
+
+from typing import TypedDict
+from PIL import Image
+from pathlib import Path
+import numpy as np
+
+# Import YOLO from ultralytics
+try:
+    from ultralytics import YOLO
+    YOLO_AVAILABLE = True
+except ImportError:
+    YOLO_AVAILABLE = False
+    print("⚠️  Ultralytics not available. Install with: pip install ultralytics")
+
+
+class Detection(TypedDict):
+    """Single trash detection result."""
+    bbox: list[float]  # [x1, y1, x2, y2] in pixels
+    label: str         # Trash category
+    score: float       # Confidence score (0-1)
+
+
+# Global model instance (loaded once)
+_model = None
+
+
+def load_model(model_path: str = "Weights/best.pt") -> YOLO:
+    """
+    Load the YOLOv8 trash detection model.
+    
+    Args:
+        model_path: Path to the model weights file
+        
+    Returns:
+        Loaded YOLO model instance
+    """
+    global _model
+    
+    if _model is None:
+        if not YOLO_AVAILABLE:
+            raise ImportError("Ultralytics not installed. Run: pip install ultralytics")
+        
+        model_file = Path(model_path)
+        if not model_file.exists():
+            raise FileNotFoundError(f"Model file not found: {model_path}")
+        
+        print(f"🔄 Loading YOLO model from {model_path}...")
+        _model = YOLO(str(model_file))
+        print(f"✅ Model loaded successfully!")
+        print(f"   Classes: {_model.names}")
+    
+    return _model
+
+
+def detect_trash(image: Image.Image, conf_threshold: float = 0.25) -> list[Detection]:
+    """
+    Detect trash objects in an image using YOLOv8.
+    
+    Args:
+        image: PIL Image to analyze
+        conf_threshold: Confidence threshold for detections (0-1)
+        
+    Returns:
+        List of detections with bounding boxes, labels, and confidence scores
+    """
+    try:
+        # Load model (only happens once)
+        model = load_model()
+        
+        # Run inference
+        results = model(image, conf=conf_threshold, verbose=False)
+        
+        # Parse results
+        detections: list[Detection] = []
+        
+        # Get the first result (single image)
+        if len(results) > 0:
+            result = results[0]
+            
+            # Extract boxes, classes, and scores
+            if result.boxes is not None and len(result.boxes) > 0:
+                boxes = result.boxes.xyxy.cpu().numpy()  # [x1, y1, x2, y2]
+                confidences = result.boxes.conf.cpu().numpy()
+                class_ids = result.boxes.cls.cpu().numpy().astype(int)
+                
+                # Convert to Detection format
+                for box, conf, cls_id in zip(boxes, confidences, class_ids):
+                    # Get class name
+                    label = model.names[cls_id]
+                    
+                    detection: Detection = {
+                        "bbox": box.tolist(),  # [x1, y1, x2, y2]
+                        "label": label,
+                        "score": float(conf)
+                    }
+                    detections.append(detection)
+        
+        return detections
+    
+    except Exception as e:
+        print(f"❌ Error during detection: {e}")
+        print("   Falling back to empty detection list")
+        return []
+
+
+def get_model_info():
+    """Get information about the loaded model."""
+    try:
+        model = load_model()
+        return {
+            "model_type": "YOLOv8",
+            "classes": model.names,
+            "num_classes": len(model.names),
+            "model_path": "Weights/best.pt"
+        }
+    except Exception as e:
+        return {
+            "error": str(e),
+            "model_type": "None",
+            "status": "Model not loaded"
+        }