🌱 Klymate AI

AI-Powered Carbon Footprint Tracker with Personalized Coaching

Klymate AI is a comprehensive carbon footprint tracking platform that combines habit monitoring with AI-powered coaching to help users reduce their environmental impact. Built with modern technologies and designed for scalability, it provides personalized recommendations, gamification features, real carbon credits with monetary value, and detailed analytics to make sustainability both engaging and financially rewarding.

✨ Features

🎯 Smart Habit Tracking

• Comprehensive Categories: Track transport, diet, energy usage, and lifestyle choices
• Real-time Calculations: Instant carbon footprint calculations for every logged activity
• Historical Analytics: Detailed insights into your environmental impact over time

🤖 AI-Powered Coaching

• Personalized Recommendations: AI coach provides tailored advice based on your habits
• Contextual Conversations: Natural language interactions with memory of past discussions
• Smart Insights: Vector-powered semantic search for relevant tips and suggestions

🏆 Gamification & Motivation

• Achievement System: Earn badges for reaching sustainability milestones
• Streak Tracking: Maintain daily and weekly eco-friendly habits
• Leaderboards: Friendly competition with eco-scores and rankings
• Challenge Participation: Join community challenges for extra motivation

� Carabon Credits System

• Earn Real Credits: Get Klymate Credits (KC) for verified carbon reduction activities
• Monetary Conversion: Convert credits to cash rewards or carbon offset certificates
• Transparent Verification: Multi-level verification with blockchain-style transaction records
• Market Integration: Real-time carbon market rates and corporate partnership opportunities
• Multiple Redemption Options: Cash out, purchase carbon offsets, or donate to climate causes

📊 Advanced Analytics

• Dashboard Insights: Visual representation of your carbon footprint trends
• Goal Tracking: Set and monitor personalized reduction targets
• Comparative Analysis: See how your efforts stack up against benchmarks
• Credit Analytics: Track your carbon credit earnings and redemption history

🏗️ Architecture

Klymate AI is built with a modern, scalable architecture:

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Frontend      │    │   Backend       │    │   Database      │
│   (React/Vue)   │◄──►│   (FastAPI)     │◄──►│   (TiDB Cloud)  │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                              │
                              ▼
                    ┌─────────────────┐    ┌─────────────────┐
                    │   AI Services   │    │   Caching       │
                    │   (LangChain)   │    │   (Redis)       │
                    └─────────────────┘    └─────────────────┘

Technology Stack

Backend

• FastAPI: High-performance Python web framework
• SQLAlchemy: Async ORM for database operations
• TiDB Cloud: Distributed SQL database with vector capabilities
• LangChain: AI orchestration and conversation management
• OpenAI: GPT models for intelligent coaching
• Redis: Caching and session management
• Firebase: Authentication and user management

Infrastructure

• Docker: Containerized deployment
• GitHub Actions: CI/CD pipeline
• Cloud Deployment: Railway/Render/AWS support

🚀 Quick Start

Prerequisites

• Python 3.9+
• Node.js 16+ (for frontend)
• Docker (optional)
• TiDB Cloud account
• OpenAI API key
• Firebase project

Backend Setup

1. Clone the repository

   git clone https://github.com/your-org/klymate-ai.git
   cd klymate-ai

2. Set up the backend environment

   cd backend
   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   pip install -r requirements.txt

3. Configure environment variables

   cp .env.example .env
   # Edit .env with your configuration

4. Run the development server

   python main.py

The API will be available at http://localhost:8000 with interactive docs at /docs.

Frontend Setup

cd frontend
npm install
npm run dev

📖 API Documentation

Authentication

POST /auth/register    # User registration
POST /auth/login       # User login
GET  /auth/profile     # Get user profile

Habit Tracking

POST /habits/log       # Log a new habit
GET  /habits/history   # Get habit history
GET  /habits/stats     # Get user statistics

AI Coaching

POST /ai/chat          # Chat with AI coach
GET  /ai/suggestions   # Get personalized tips

Gamification

GET  /gamification/badges      # Get user badges
GET  /gamification/leaderboard # Get leaderboard

Carbon Credits

GET  /credits/balance          # Get current credit balance
GET  /credits/transactions     # Get credit transaction history
POST /credits/redeem          # Redeem credits for cash/offsets
GET  /credits/rates           # Get current exchange rates

Full API documentation is available at /docs when running the server.

🧪 Testing

# Run all tests
pytest

# Run with coverage
pytest --cov=.

# Run specific test categories
pytest tests/unit/
pytest tests/integration/
pytest tests/e2e/

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🌟 Acknowledgments

• TiDB Cloud for providing scalable database infrastructure
• OpenAI for powering our AI coaching capabilities
• FastAPI community for the excellent framework
• LangChain for AI orchestration tools

📞 Support

• Documentation: docs.klymate-ai.com
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: support@klymate-ai.com

---

Made with 💚 for a sustainable future