Spaces:

Agents-MCP-Hackathon
/

GlycoAI

Sleeping

App Files Files Community

Valentina9502 commited on Jun 10

Commit

be2d916

verified ·

1 Parent(s): 93e3ae8

updated readme

Browse files

Files changed (1) hide show

README copy.md +208 -157

README copy.md CHANGED Viewed

@@ -1,230 +1,281 @@
 ---
-title: GlycoAI - AI Glucose Insights
 emoji: 🩺
 colorFrom: blue
 colorTo: purple
 sdk: gradio
 sdk_version: 4.44.0
-app_file: main.py
 pinned: false
-license: mit
 tags:
-  - healthcare
   - diabetes
-  - glucose
-  - ai-assistant
-  - medical
   - gradio
-  - mistral
-  - agent-demo-track
-  - dexcom
-  - cgm
-  #agent-demo-track
 ---
-# 🩺 GlycoAI - AI-Powered Glucose Insights
-**An intelligent diabetes management assistant powered by Mistral AI and Dexcom CGM integration**
-[![Hugging Face Spaces](https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Spaces-blue)](https://huggingface.co/spaces/)
 [![Gradio](https://img.shields.io/badge/Gradio-4.44.0-orange)](https://gradio.app/)
-[![Mistral AI](https://img.shields.io/badge/Mistral%20AI-Agent-red)](https://mistral.ai/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 ## 🌟 Overview
-GlycoAI is an advanced AI-powered chatbot that provides personalized glucose management insights for people with diabetes. By integrating Dexcom CGM data with Mistral AI's intelligent agents, it offers real-time analysis, pattern recognition, and actionable recommendations for better diabetes management.
-### ✨ Key Features
-- 📊 **14-Day Glucose Analysis**: Comprehensive pattern analysis across two weeks of data
-- 🤖 **AI-Powered Insights**: Mistral AI agent provides personalized recommendations
-- 📈 **Interactive Visualizations**: Glucose trend charts and statistics
-- 👥 **Demo Users**: Pre-configured profiles for different diabetes scenarios
-- 💬 **Natural Conversations**: Chat naturally about your glucose patterns and concerns
-- 🎯 **Clinical Targets**: Track time-in-range, hypoglycemia, and variability metrics
-- 📱 **Multi-Device Support**: Works with G6, G7, and ONE+ CGM systems
-## 🚀 Try It Now
-**No setup required!** Simply:
-1. Select a demo user (Sarah, Marcus, Jennifer, or Robert)
-2. Load their 14-day glucose data
-3. Start chatting with GlycoAI about patterns and recommendations
-## 🔬 Technical Implementation
-### AI Agent Architecture
-- **Mistral AI Agent**: Custom-trained agent specialized in diabetes management
-- **Context-Aware**: Incorporates real glucose data into conversations
-- **Pattern Recognition**: Identifies trends, meal effects, and lifestyle correlations
-- **Personalized Advice**: Tailored recommendations based on individual patterns
-### Data Processing Pipeline
-```
-Dexcom API → Data Validation → Pattern Analysis → AI Context → Chat Response
-```
-### Key Metrics Analyzed
-- **Time in Range (TIR)**: Target 70-180 mg/dL
-- **Glucose Variability**: Coefficient of variation
-- **Hypoglycemia Risk**: Time below 70 mg/dL
-- **Hyperglycemia**: Time above 180 mg/dL
-- **Daily Patterns**: Dawn phenomenon, meal effects
-- **Weekly Trends**: Weekday vs weekend variations
-## 👥 Demo Users
-### 🏃‍♀️ Sarah Thompson (G7 Mobile)
-- **Profile**: 32-year-old professional with Type 1 diabetes
-- **Pattern**: Stable control with meal spikes
-- **Device**: Dexcom G7 with smartphone integration
-### 👨‍👧‍👦 Marcus Rodriguez (ONE+ Mobile)
-- **Profile**: 45-year-old father with Type 2 diabetes
-- **Pattern**: Dawn phenomenon, moderate variability
-- **Device**: Dexcom ONE+ with lifestyle management focus
-### 🎓 Jennifer Chen (G6 Mobile)
-- **Profile**: 28-year-old graduate student with Type 1 diabetes
-- **Pattern**: Exercise-related lows, tech-savvy user
-- **Device**: Dexcom G6 with active lifestyle
-### 👨‍🏫 Robert Williams (G6 Receiver)
-- **Profile**: 67-year-old retired teacher with Type 2 diabetes
-- **Pattern**: Consistent dawn phenomenon
-- **Device**: Dexcom G6 with dedicated receiver
-## 💡 Example Conversations
-**"What's my average glucose level?"**
-> Based on your 14-day data, your average glucose is 142 mg/dL with good stability. Your time in range is 68%, which is close to the clinical target of >70%. 📊
-**"I keep having morning highs. What can I do?"**
-> I notice you have dawn phenomenon with glucose rising 30-40 mg/dL between 4-7 AM. This affects 5 out of 14 mornings in your data. Consider discussing overnight insulin adjustments with your healthcare provider. 🌅
-**"How does my weekend compare to weekdays?"**
-> Interesting pattern! Your weekends show 15 mg/dL lower average glucose (135 vs 150 mg/dL weekdays). You seem to have more consistent meal timing on weekends. 📈
-## 🛠️ Technical Stack
-- **Frontend**: Gradio 4.44.0 with custom CSS styling
-- **Backend**: Python with FastAPI-style architecture
-- **AI Engine**: Mistral AI agents with specialized diabetes knowledge
-- **Data Source**: Dexcom Sandbox API with realistic mock data
-- **Visualization**: Plotly for interactive glucose charts
-- **Processing**: Pandas/NumPy for statistical analysis
-## 📊 Data Analysis Features
-### Pattern Recognition
-- **Meal Effects**: Identifies post-meal glucose spikes and timing
-- **Exercise Impact**: Detects glucose drops during physical activity
-- **Sleep Patterns**: Analyzes overnight glucose stability
-- **Stress Correlation**: Identifies high-glucose periods linked to lifestyle
-### Statistical Analysis
-- **Glucose Management Indicator (GMI)**: HbA1c estimation
-- **Coefficient of Variation**: Glucose stability measurement
-- **Time-in-Range Analysis**: Clinical target tracking
-- **Trend Analysis**: Week-over-week improvement detection
-### Predictive Insights
-- **Risk Identification**: Predicts hypoglycemia patterns
-- **Optimization Suggestions**: Recommends timing adjustments
-- **Lifestyle Correlations**: Links patterns to daily activities
-- **Goal Tracking**: Monitors progress toward clinical targets
-## 🔒 Privacy & Security
-- **No Data Storage**: Conversations and glucose data are not permanently stored
-- **Sandbox Environment**: Uses Dexcom's secure sandbox API
-- **Educational Purpose**: Designed for demonstration and learning
-- **Medical Disclaimer**: Not intended to replace professional medical advice
-## ⚕️ Medical Disclaimer
-**Important**: GlycoAI is for educational and informational purposes only. It does not provide medical advice, diagnosis, or treatment. Always consult with qualified healthcare providers before making any changes to your diabetes management plan.
-## 🎯 Agent Demo Track
-This application showcases advanced AI agent capabilities for healthcare applications:
-- **Contextual Understanding**: Processes complex medical data
-- **Personalized Responses**: Adapts advice to individual patterns
-- **Multi-Modal Analysis**: Combines numerical data with conversational AI
-- **Domain Expertise**: Specialized knowledge in diabetes management
-- **Real-Time Processing**: Instant analysis of glucose trends
-Perfect example of how AI agents can augment healthcare decision-making while maintaining appropriate clinical boundaries.
-## 🚀 Getting Started
-### Option 1: Use This Space (Recommended)
-Just click the demo above! No installation needed.
-### Option 2: Local Installation
-```bash
-git clone https://github.com/your-repo/glycoai
-cd glycoai
-pip install -r requirements.txt
-python main.py
-```
-### Option 3: API Integration
-```python
-from mistral_chat import GlucoBuddyMistralChat
-# Initialize with your Mistral API key
-chat = GlucoBuddyMistralChat("your-api-key", "your-agent-id")
-# Load demo user
-chat.load_user_data("sarah_g7")
-# Start chatting
-response = chat.chat_with_mistral("What's my time in range?")
-print(response['response'])
-```
-## 📈 Roadmap
-- [ ] **Real Dexcom Integration**: Connect to live CGM data
-- [ ] **Health data**: integration with Apple Health for obtaining further insights (e.g hormonal influence)
-- [ ] **Insulin Tracking**: Dosing recommendations and timing
-- [ ] **Healthcare Provider Dashboard**: Shareable reports
-- [ ] **Mobile App**: Native iOS/Android applications
-- [ ] **Multiple Languages**: Multilingual diabetes support
 ## 🤝 Contributing
-We welcome contributions! Areas of interest:
-- **Medical Accuracy**: Improve clinical recommendations
-- **UI/UX Enhancement**: Better user experience design
-- **Data Analysis**: Advanced pattern recognition algorithms
-- **Agent Training**: Enhance AI conversation quality
-- **Integration**: Additional CGM device support
-## 📞 Support
-- **Documentation**: [Full Documentation](https://github.com/your-repo/glycoai/wiki)
-- **Issues**: [GitHub Issues](https://github.com/your-repo/glycoai/issues)
-- **Discussions**: [Community Forum](https://github.com/your-repo/glycoai/discussions)
-## 📄 License
-MIT License - see [LICENSE](LICENSE) file for details.
----
-<div align="center">
-**Built with ❤️ for the diabetes community**
-*Empowering better glucose management through AI*
-[![Follow on HF](https://img.shields.io/badge/Follow%20on-Hugging%20Face-yellow)](https://huggingface.co/spaces/)
-[![Star on GitHub](https://img.shields.io/badge/Star%20on-GitHub-black)](https://github.com/your-repo/glycoai)
-</div>

 ---
+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.
+### 🎯 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**: [email protected]
+## 🚀 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*