CONTRIBUTING.md

Contributing to CleanCity Agent

Thank you for your interest in contributing to CleanCity Agent! 🌍

🎯 Project Vision

CleanCity Agent aims to make environmental action accessible through AI-powered trash detection and cleanup planning. We welcome contributions that align with this mission.

🚀 Quick Start

1. Fork the repository
2. Clone your fork:

   git clone https://github.com/YOUR_USERNAME/CleanCity-Agent.git
   cd CleanCity-Agent
   

3. Create a virtual environment:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

4. Install dependencies:

   pip install -r requirements.txt
   

5. Create a branch:

   git checkout -b feature/your-feature-name
   

📝 Development Guidelines

Code Style

• Follow PEP 8 Python style guide
• Use type hints for function parameters and returns
• Add docstrings to all functions and classes
• Keep functions small and focused (single responsibility)

Testing Your Changes

Before submitting a PR:

1. Test the Gradio app:

   python app.py
   

2. Test the MCP server:

   python mcp_server.py
   

3. Verify all tabs work:

   • Analysis tab
   • History tab
   • Impact & Examples tab
   • Chat tab

4. Test with different LLM providers:

   • Set LLM_PROVIDER=offline (default)
   • Test with real API keys if available

Commit Messages

Use clear, descriptive commit messages:

✅ Good:
- "Add GPS auto-detection feature"
- "Fix model path resolution for deployed environments"
- "Improve error handling in trash detection"

❌ Bad:
- "Update stuff"
- "Fix bug"
- "WIP"

🎨 Areas for Contribution

High Priority

• Real YOLOv8 Model Integration - Replace mock detector with trained model
• Mobile Responsiveness - Improve UI for smartphones
• Multilingual Support - Add i18n for global reach
• Performance Optimization - Faster image processing
• Accessibility - ARIA labels, keyboard navigation, screen reader support

Feature Ideas

• Gamification - Points/badges for cleanup reporting
• Community Features - Team cleanup coordination
• Advanced Analytics - Trend analysis, predictive hotspots
• Integration with City Services - API for municipal waste management
• Offline Mode Enhancement - PWA with offline detection

Documentation

• Additional usage examples
• Tutorial videos
• API documentation improvements
• Translation of docs to other languages

🐛 Reporting Bugs

Found a bug? Help us fix it!

1. Check existing issues to avoid duplicates
2. Create a new issue with:
   • Clear title describing the problem
   • Steps to reproduce
   • Expected vs. actual behavior
   • Screenshots if applicable
   • Your environment (OS, Python version, browser)

Template:

## Bug Description
[What went wrong?]

## Steps to Reproduce
1. Go to...
2. Click on...
3. See error...

## Expected Behavior
[What should happen?]

## Actual Behavior
[What actually happens?]

## Environment
- OS: [e.g., Windows 11, macOS 14]
- Python: [e.g., 3.11.5]
- Browser: [e.g., Chrome 120]

💡 Feature Requests

Have an idea? We'd love to hear it!

1. Open an issue with the enhancement label
2. Describe the feature:
   • What problem does it solve?
   • Who would benefit?
   • How should it work?
3. Optional: Include mockups, diagrams, or code sketches

🔀 Pull Request Process

1. Ensure your code works (see Testing section above)
2. Update documentation if you changed functionality
3. Update README.md if you added features
4. Create a pull request:
   • Descriptive title
   • Summary of changes
   • Link to related issues
   • Screenshots if UI changed

PR Checklist

• Code follows PEP 8 style
• Added type hints
• Added/updated docstrings
• Tested locally (app runs without errors)
• Updated relevant documentation
• No sensitive data (API keys, passwords) committed

📜 Code of Conduct

Our Pledge

We are committed to providing a welcoming and inclusive environment for everyone.

Expected Behavior

• Be respectful and considerate in all interactions
• Be constructive when giving feedback
• Be patient with newcomers
• Focus on the mission - cleaner cities and environmental action

Unacceptable Behavior

• Harassment, discrimination, or personal attacks
• Trolling or inflammatory comments
• Spam or self-promotion unrelated to the project

Violations: Contact project maintainers. Violators may be banned.

🏆 Recognition

Contributors will be:

• Listed in README acknowledgments
• Credited in release notes
• Given proper attribution in commits

❓ Questions?

• GitHub Issues: For bugs and features
• Discussions: For questions and ideas
• Email: [Contact project maintainer if email available]

---

Thank you for helping make CleanCity Agent better! 🌱

Your contributions help communities worldwide take action against litter and pollution.