README copy.md

---
title: GlycoAI - AI-Powered Glucose Insights
emoji: 🩺
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 4.44.0
app_file: app.py
pinned: false
license: apache-2.0
tags:
  - agent-demo-track
  - diabetes
  - glucose-monitoring
  - healthcare-ai
  - medical-analysis
  - dexcom-api
  - mistral-ai
  - gradio
  - demo
---

# GlycoAI 🩺 - AI-Powered Glucose Insights

> **Transform your glucose data into actionable health insights with intelligent AI analysis**

[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Gradio](https://img.shields.io/badge/Gradio-4.44.0-orange)](https://gradio.app/)
[![Agent Demo Track](https://img.shields.io/badge/Agent-Demo_Track-green)](https://huggingface.co/spaces)
[![Mistral AI](https://img.shields.io/badge/Powered_by-Mistral_AI-purple)](https://mistral.ai/)

## 🌟 Overview

GlycoAI is an advanced AI-powered application that analyzes continuous glucose monitoring (CGM) data to provide personalized diabetes management insights. Using state-of-the-art AI agents powered by Mistral AI, GlycoAI transforms complex glucose patterns into clear, actionable recommendations for better diabetes control.
🎯 Video demo: [deleted ](https://huggingface.co/spaces/Agents-MCP-Hackathon/GlycoAI/blob/main/GlycoAI%20Demo-v1.0.mp4)

### 🎯 Key Features

- **🤖 Intelligent AI Agent**: Conversational AI that understands glucose patterns and provides personalized insights
- **📊 Comprehensive Analysis**: 14-day glucose trend analysis with clinical metrics (Time in Range, GMI, CV)
- **🎭 Demo Users**: Four realistic patient profiles showcasing different glucose management scenarios
- **🔐 Dexcom Integration**: OAuth-authenticated connection to Dexcom Sandbox API
- **📈 Interactive Visualizations**: Color-coded glucose charts with target range overlays
- **⚠️ Smart Notifications**: Real-time alerts for concerning glucose patterns
- **🏥 Clinical Focus**: Evidence-based recommendations aligned with diabetes care standards

## 🚀 Live Demo

**Try GlycoAI now:** [https://huggingface.co/spaces/your-username/glycoai](https://huggingface.co/spaces/your-username/glycoai)

### 🎭 Demo Users Available

1. **Sarah Thompson** - G7 Mobile - ⚠️ **Unstable Control** (Demonstrates crisis management)
2. **Marcus Rodriguez** - ONE+ Mobile - Type 2 Diabetes with Dawn Phenomenon
3. **Jennifer Chen** - G6 Mobile - Athletic lifestyle with excellent control
4. **Robert Williams** - G6 Receiver - Experienced user with good management

## 🛠️ Technology Stack

- **Frontend**: Gradio 4.44.0 with custom CSS styling
- **AI Engine**: Mistral AI for intelligent glucose pattern analysis
- **Data Processing**: Pandas, NumPy for glucose data analysis
- **Visualization**: Plotly for interactive glucose charts
- **API Integration**: Dexcom API with OAuth 2.0 authentication
- **Deployment**: Hugging Face Spaces

## 🏥 Clinical Significance

### Metrics Analyzed
- **Time in Range (TIR)**: Target >70% (70-180 mg/dL)
- **Time Below Range (TBR)**: Target <4% (<70 mg/dL)
- **Time Above Range (TAR)**: Target <25% (>180 mg/dL)
- **Glucose Management Indicator (GMI)**: Estimated A1C
- **Coefficient of Variation (CV)**: Target <36% (glucose variability)

### AI Capabilities
- **Pattern Recognition**: Identifies dawn phenomenon, post-meal spikes, nocturnal hypoglycemia
- **Safety Prioritization**: Emphasizes hypoglycemia prevention and severe glucose excursions
- **Personalized Recommendations**: Tailored advice based on individual glucose patterns
- **Clinical Context**: Provides education on diabetes management principles

## 🔧 Installation & Setup

### For Local Development

```bash
# Clone the repository
git clone https://github.com/your-username/glycoai.git
cd glycoai

# Install dependencies
pip install -r requirements.txt

# Set up environment variables
cp .env.example .env
# Edit .env with your API keys:
# MISTRAL_API_KEY=your_mistral_api_key_here
# DEXCOM_CLIENT_ID=your_dexcom_client_id (optional)
# DEXCOM_CLIENT_SECRET=your_dexcom_client_secret (optional)

# Run the application
python app.py
```

### Environment Variables

| Variable | Description | Required |
|----------|-------------|----------|
| `MISTRAL_API_KEY` | Mistral AI API key for chat functionality | ✅ Yes |
| `DEXCOM_CLIENT_ID` | Dexcom developer client ID | ❌ Optional |
| `DEXCOM_CLIENT_SECRET` | Dexcom developer client secret | ❌ Optional |

## 📖 Usage Guide

### 1. **Select Data Source**
   - Choose from 4 demo users for instant testing
   - Or connect via Dexcom Sandbox OAuth (requires developer credentials)

### 2. **Load Glucose Data**
   - Click "Load 14-Day Glucose Data" button
   - Watch for notification indicating data quality and patterns

### 3. **Analyze with AI**
   - Navigate to "Chat with AI" tab
   - Click on suggested prompts or ask custom questions
   - Get personalized insights about glucose patterns

### 4. **Explore Visualizations**
   - View interactive 14-day glucose trends
   - Examine detailed statistics and clinical metrics
   - Understand time-in-range analysis

## 🎯 Use Cases

### For Healthcare Providers
- **Patient Education**: Explain glucose patterns in accessible language
- **Treatment Planning**: Identify areas for intervention
- **Progress Monitoring**: Track improvement over time
- **Clinical Documentation**: Generate insights for medical records

### For Patients & Caregivers
- **Self-Management**: Understand personal glucose patterns
- **Medication Timing**: Optimize treatment schedules
- **Lifestyle Adjustments**: Learn about food and exercise impacts
- **Safety Awareness**: Recognize dangerous patterns

### For Researchers & Developers
- **Algorithm Development**: Study glucose pattern recognition
- **AI Applications**: Explore conversational health AI
- **Data Analysis**: Understand CGM data processing
- **Clinical Decision Support**: Build evidence-based tools

## 🔬 Technical Details

### Data Processing Pipeline
1. **Data Ingestion**: Accepts Dexcom API format or generates realistic mock data
2. **Preprocessing**: Validates timestamps, handles missing values, calculates trends
3. **Statistical Analysis**: Computes clinical metrics using standardized formulas
4. **Pattern Recognition**: Identifies glucose variability, meal responses, and anomalies
5. **AI Context Building**: Structures data for intelligent conversation

### AI Agent Architecture
- **Context Awareness**: Maintains conversation state with glucose data context
- **Clinical Knowledge**: Trained on diabetes management best practices
- **Safety Focus**: Prioritizes urgent recommendations for dangerous patterns
- **Personalization**: Adapts advice to individual glucose characteristics

## 📊 Demo Scenarios

### Sarah Thompson - Crisis Management
- **Scenario**: Highly unstable glucose with frequent dangerous excursions
- **TIR**: ~45% (concerning)
- **CV**: ~52% (very high variability)
- **AI Response**: Urgent safety recommendations and healthcare provider consultation

### Marcus Rodriguez - Dawn Phenomenon
- **Scenario**: Type 2 diabetes with morning glucose elevation
- **Pattern**: Consistent 6-8 AM glucose rises
- **AI Response**: Medication timing optimization and morning routine adjustments

### Jennifer Chen - Athletic Lifestyle
- **Scenario**: Active individual with exercise-related glucose variations
- **Pattern**: Exercise-induced lows and recovery patterns
- **AI Response**: Pre/post-workout glucose management strategies

### Robert Williams - Experienced Management
- **Scenario**: Long-term diabetes with good overall control
- **Focus**: Fine-tuning and maintaining excellent management
- **AI Response**: Advanced optimization strategies and pattern maintenance

## 🛡️ Privacy & Security

- **Data Processing**: All analysis performed in real-time, no permanent storage
- **API Security**: OAuth 2.0 authentication for Dexcom integration
- **Privacy by Design**: No personal health information retained between sessions
- **Compliance**: Designed with HIPAA principles in mind
- **Transparency**: Open-source approach for algorithm audibility

## ⚠️ Medical Disclaimer

**IMPORTANT**: GlycoAI is for informational and educational purposes only. This application:

- **IS NOT** a medical device or diagnostic tool
- **DOES NOT** replace professional medical advice
- **SHOULD NOT** be used for treatment decisions without healthcare provider consultation
- **REQUIRES** users to always consult their healthcare team before making management changes

Always follow your healthcare provider's guidance for diabetes management.

## 🤝 Contributing

We welcome contributions from the healthcare AI, diabetes technology, and open-source communities!

### Ways to Contribute
- 🐛 **Bug Reports**: Submit issues with detailed reproduction steps
- 💡 **Feature Requests**: Suggest new capabilities or improvements
- 🔧 **Code Contributions**: Submit pull requests with enhancements
- 📚 **Documentation**: Improve guides, examples, and explanations
- 🧪 **Testing**: Help validate algorithms with diverse glucose patterns

### Development Guidelines
- Follow clinical evidence-based recommendations
- Prioritize patient safety in all features
- Maintain code quality with comprehensive testing
- Document clinical rationale for algorithm decisions

## 📜 License

This project is licensed under the **Apache License 2.0** - see the [LICENSE](LICENSE) file for details.

```
Copyright 2024 GlycoAI Contributors

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
```

## 🙏 Acknowledgments

- **Mistral AI** for providing the intelligent conversation capabilities
- **Dexcom** for continuous glucose monitoring technology and API access
- **Diabetes Community** for inspiration and clinical insights
- **Open Source Community** for tools and frameworks that make this possible
- **Healthcare Providers** who guide evidence-based diabetes management

## 📞 Support & Contact

- **Issues**: [GitHub Issues](https://github.com/your-username/glycoai/issues)
- **Discussions**: [GitHub Discussions](https://github.com/your-username/glycoai/discussions)
- **Documentation**: [Project Wiki](https://github.com/your-username/glycoai/wiki)
- **Email**: your-email@example.com

## 🚀 Roadmap

### Upcoming Features
- **Multi-language Support**: Expand accessibility globally
- **Advanced Pattern Recognition**: Machine learning-based anomaly detection
- **Integration Expansion**: Support for additional CGM devices
- **Clinical Decision Support**: Enhanced recommendations for healthcare providers
- **Mobile Optimization**: Improved mobile device experience
- **API Development**: RESTful API for third-party integrations

### Research Directions
- **Federated Learning**: Privacy-preserving model improvements
- **Predictive Analytics**: Glucose forecasting capabilities
- **Behavioral Analysis**: Lifestyle factor correlation
- **Population Health**: Aggregate insights for public health

---

**Made with ❤️ for the diabetes community**

*Empowering better glucose management through intelligent AI analysis*