Spaces:
Runtime error
Runtime error
| # System Architecture & Data Flow | |
| ## 🏗️ System Architecture Diagram | |
| ``` | |
| ┌─────────────────────────────────────────────────────────────────┐ | |
| │ HUGGING FACE SPACES │ | |
| │ (Free CPU Tier) │ | |
| ├─────────────────────────────────────────────────────────────────┤ | |
| │ │ | |
| │ ┌──────────────────────────────────────────────────────────┐ │ | |
| │ │ GRADIO UI (Chat Interface) │ │ | |
| │ │ - Display chat messages │ │ | |
| │ │ - Take user input │ │ | |
| │ │ - Show predictions │ │ | |
| │ └────────────────────┬─────────────────────────────────────┘ │ | |
| │ │ │ | |
| │ ┌────────────────────▼─────────────────────────────────────┐ │ | |
| │ │ app/main.py │ │ | |
| │ │ (Chat Function & Orchestration) │ │ | |
| │ │ - Coordinates all services │ │ | |
| │ │ - Manages conversation flow │ │ | |
| │ └────┬──────────────────┬──────────────────┬───────────────┘ │ | |
| │ │ │ │ │ | |
| │ ┌─────▼──────┐ ┌────────▼──────┐ ┌────────▼──────┐ │ | |
| │ │ LLM │ │ Memory │ │ Predictor │ │ | |
| │ │ Extractor │ │ Manager │ │ Service │ │ | |
| │ │ │ │ │ │ │ │ | |
| │ │ Input: │ │ Input: │ │ Input: │ │ | |
| │ │ "I'm 45..." │ │ Extracted │ │ Feature │ │ | |
| │ │ │ │ features │ │ vector │ │ | |
| │ │ Output: │ │ │ │ │ │ | |
| │ │ JSON with │ │ Output: │ │ Output: │ │ | |
| │ │ features │ │ Full state │ │ Prediction │ │ | |
| │ └─────┬──────┘ │ (16 features) │ │ + confidence │ │ | |
| │ │ └────────┬──────┘ └───────┬───────┘ │ | |
| │ │ │ │ │ | |
| │ ┌─────▼─────┐ ┌────────▼──┐ ┌───────────▼───┐ │ | |
| │ │ GROQ │ │ app/ │ │ Feature │ │ | |
| │ │ Llama 3 │ │ memory.py │ │ Builder │ │ | |
| │ │ (Free API) │ │ │ │ │ │ | |
| │ │ │ │ State: │ │ Validates & │ │ | |
| │ │ Cloud- │ │ { │ │ prepares │ │ | |
| │ │ based │ │ Age: 45, │ │ feature │ │ | |
| │ │ │ │ Glucose: │ │ vector for │ │ | |
| │ │ │ │ 150, │ │ ML model │ │ | |
| │ │ │ │ ... │ │ │ │ | |
| │ │ │ │ ... │ │ (Validates │ │ | |
| │ │ │ │ } │ │ ranges) │ │ | |
| │ │ │ │ │ │ │ │ | |
| │ └────────────┘ └───────────┘ └────────┬──────┘ │ | |
| │ │ │ | |
| │ ┌────────────────▼──────────┐ │ | |
| │ │ Predictor Service │ │ | |
| │ │ (app/services/ │ │ | |
| │ │ predictor.py) │ │ | |
| │ │ │ │ | |
| │ │ Loads: │ │ | |
| │ │ GradientBoosting_ │ │ | |
| │ │ model.pkl │ │ | |
| │ │ │ │ | |
| │ │ Inputs: [16 floats] │ │ | |
| │ │ Outputs: class + prob │ │ | |
| │ └────────────┬─────────────┘ │ | |
| │ │ │ | |
| │ ┌────────────▼──────────┐ │ | |
| │ │ scikit-learn │ │ | |
| │ │ GradientBoosting │ │ | |
| │ │ Classifier │ │ | |
| │ │ │ │ | |
| │ │ (Runs locally on CPU) │ │ | |
| │ └────────────────────────┘ │ | |
| │ │ | |
| └─────────────────────────────────────────────────────────────────┘ | |
| ``` | |
| --- | |
| ## 📊 Data Flow Sequence | |
| ### Step 1: User Inputs Text | |
| ``` | |
| User: "I'm 45 years old and my glucose is 150" | |
| ↓ | |
| [Sent to main.py] | |
| ``` | |
| ### Step 2: LLM Extraction (Groq API) | |
| ``` | |
| app/main.py | |
| ↓ | |
| call: extract_features_from_text(message) | |
| ↓ | |
| llm_extractor.py | |
| ↓ | |
| Groq API (Cloud) | |
| │ | |
| └─→ llama-3.1-8b-instant | |
| (Processes: "I'm 45... glucose 150...") | |
| ↓ | |
| Returns JSON: { | |
| "Age": 45, | |
| "Glucose": 150, | |
| "Smoking": null, | |
| "HbA1c": null, | |
| ... (rest null) | |
| } | |
| ↓ | |
| [Returns to main.py] | |
| ``` | |
| ### Step 3: Update Memory | |
| ``` | |
| current_state = { | |
| "Age": null, | |
| "Glucose": null, | |
| ... (all null) | |
| } | |
| ↓ | |
| extracted = {"Age": 45, "Glucose": 150, ...} | |
| ↓ | |
| memory.update_state(current_state, extracted) | |
| ↓ | |
| new_state = { | |
| "Age": 45, | |
| "Glucose": 150, | |
| "Smoking": null, | |
| ... (rest null) | |
| } | |
| ``` | |
| ### Step 4: Check Missing Features | |
| ``` | |
| missing_features = get_missing_features(state) | |
| ↓ | |
| Result: ["Smoking", "Family History", "HbA1c", ... (12 more)] | |
| ↓ | |
| len(missing) = 14 features still needed | |
| ↓ | |
| DECISION: Not ready for prediction yet | |
| ``` | |
| ### Step 5: Generate Question | |
| ``` | |
| next_missing = missing_features[0] # "Smoking" | |
| ↓ | |
| question = generate_question("Smoking") | |
| ↓ | |
| Result: "Do you smoke? (yes/no)" | |
| ↓ | |
| Send to user in chat | |
| ``` | |
| ### Step 6: User Answers (Loop Back to Step 1) | |
| ``` | |
| User: "No, I don't smoke" | |
| ↓ | |
| [Loop back to Step 1] | |
| ↓ | |
| (Repeat until all 16 features collected) | |
| ``` | |
| ### Step 7: All Features Collected - Ready for Prediction | |
| ``` | |
| state = { | |
| "Age": 45, | |
| "Glucose": 150, | |
| "Smoking": 0, | |
| "Family History": 1, | |
| ... (all 16 features filled) | |
| } | |
| ↓ | |
| missing_features = [] # Empty! | |
| ↓ | |
| DECISION: Ready for prediction! | |
| ``` | |
| ### Step 8: Feature Builder - Prepare for ML Model | |
| ``` | |
| feature_builder.prepare_feature_vector(state) | |
| ↓ | |
| Validation: | |
| - Check each value in valid range | |
| - Convert types to float | |
| - Handle missing with defaults | |
| ↓ | |
| Output: [45.0, 150.0, 0.0, 1.0, ... (16 floats total)] | |
| ↓ | |
| This vector is ready for ML model | |
| ``` | |
| ### Step 9: Prediction | |
| ``` | |
| feature_vector = [45.0, 150.0, 0.0, 1.0, ...] | |
| ↓ | |
| predictor = get_predictor() # Loads model.pkl | |
| ↓ | |
| result = predictor.predict(feature_vector) | |
| ↓ | |
| Model processes: | |
| - Input: 16 features | |
| - Runs through GradientBoosting | |
| - Output: class (0 or 1) + probability | |
| ↓ | |
| Returns: PredictionResponse { | |
| "prediction": 1, | |
| "probability": 0.85, | |
| "risk_level": "High", | |
| "explanation": "Model predicts class 1 with 85% confidence" | |
| } | |
| ``` | |
| ### Step 10: Display Results to User | |
| ``` | |
| Chatbot: "✅ All information collected! | |
| Prediction Results: | |
| - Prediction: Class 1 | |
| - Confidence: 85.0% | |
| - Risk Level: High | |
| - Details: Model predicts class 1 with 85% confidence" | |
| ``` | |
| --- | |
| ## 🔄 Complete Conversation Example | |
| ``` | |
| USER: "I'm 45 years old, my glucose is 150, I smoke, and my stress is high" | |
| STEP 1 (Extract): | |
| Groq extracts: {Age: 45, Glucose: 150, Smoking: 1, StressLevel: null} | |
| STEP 2 (Update Memory): | |
| state = {Age: 45, Glucose: 150, Smoking: 1, StressLevel: null, ...} | |
| STEP 3 (Check Missing): | |
| missing = ["Family History", "HbA1c", "StressLevel", ... (12 more)] | |
| STEP 4 (Ask Question): | |
| BOT: "Do you have a family history of disease? (yes/no)" | |
| USER: "Yes" | |
| STEP 1 (Extract): | |
| Groq extracts: {FamilyHistory: 1} | |
| STEP 2 (Update Memory): | |
| state = {Age: 45, Glucose: 150, Smoking: 1, FamilyHistory: 1, ...} | |
| STEP 3 (Check Missing): | |
| missing = ["HbA1c", "StressLevel", ... (12 more)] | |
| STEP 4 (Ask Question): | |
| BOT: "What is your HbA1c level?" | |
| ... (repeat until all 16 features) | |
| STEP 7 (All Collected): | |
| state = {Age: 45, Glucose: 150, Smoking: 1, FamilyHistory: 1, | |
| HbA1c: 7.2, BMI: 28, ... (all 16 filled)} | |
| STEP 8 (Prepare): | |
| feature_vector = [45.0, 150.0, 1.0, 1.0, 7.2, ... (16 values)] | |
| STEP 9 (Predict): | |
| ML Model processes vector | |
| Returns: {prediction: 1, probability: 0.82, risk_level: "High"} | |
| STEP 10 (Display): | |
| BOT: "✅ Prediction: Class 1 (82% confidence)" | |
| ``` | |
| --- | |
| ## 📁 File Dependencies & Data Flow | |
| ``` | |
| ┌─────────────────┐ | |
| │ app/main.py │ ← ORCHESTRATOR (coordinates everything) | |
| └────────┬────────┘ | |
| │ | |
| ┌────┼────┬────────────────┬──────────────┐ | |
| │ │ │ │ │ | |
| ▼ ▼ ▼ ▼ ▼ | |
| ┌───────┐ ┌──────────┐ ┌──────────────┐ ┌─────────────┐ | |
| │memory │ │llm_ │ │feature_ │ │predictor │ | |
| │.py │ │extractor │ │builder.py │ │.py │ | |
| │ │ │.py │ │ │ │ │ | |
| │ ┌──┐ │ │ ┌──────┐ │ │ ┌─────────┐ │ │ ┌────────┐ │ | |
| │ │ │ │ │ │Groq │ │ │ │Validate │ │ │ │Load │ │ | |
| │ │ │ │ │ │API │ │ │ │Features │ │ │ │Model │ │ | |
| │ └──┘ │ │ └──────┘ │ │ │ │ │ │ │ pkl │ │ | |
| │ │ │ │ │ │Prepare │ │ │ │ │ │ | |
| │Tracks │ │Extracts │ │ │Vector │ │ │ │Predict │ │ | |
| │State │ │Features │ │ │ │ │ │ │Result │ │ | |
| │ │ │(JSON) │ │ │ │ │ │ │ │ │ | |
| └───────┘ └──────────┘ └─────────┬─┘ │ └───┬────┬─┘ │ | |
| │ │ │ │ │ | |
| │ │ │ └────┼──┐ | |
| │ └──────┼─────────┘ │ | |
| │ │ │ | |
| ▼ ▼ ▼ | |
| ┌──────────────┐ ┌─────────────────┐ | |
| │app/schemas.py│ │models/ │ | |
| │(Validation) │ │GradientBoosting │ | |
| │ │ │_model.pkl │ | |
| │ ┌──────────┐ │ │ │ | |
| │ │Pydantic │ │ │ (scikit-learn) │ | |
| │ │Models │ │ │ Binary Classifier | |
| │ │(Types) │ │ │ 16 Features │ | |
| │ └──────────┘ │ │ Input → Output │ | |
| └──────────────┘ └─────────────────┘ | |
| ┌──────────────────────────────┐ | |
| │app/config.py │ | |
| │(Constants & Configuration) │ | |
| │ • Paths │ | |
| │ • API settings │ | |
| │ • Feature ranges │ | |
| │ • Feature list │ | |
| └──────────────────────────────┘ | |
| ┌──────────────────────────────┐ | |
| │app/utils/helpers.py │ | |
| │(Question Mapping) │ | |
| │ Feature → Question lookup │ | |
| └──────────────────────────────┘ | |
| ``` | |
| --- | |
| ## 🔌 Integration Points | |
| ### 1. **Groq API ↔ LLM Extractor** | |
| ``` | |
| Input: User text (string) | |
| Process: HTTP request to Groq cloud | |
| Output: JSON with features | |
| Error: Timeout, invalid JSON, API errors | |
| ``` | |
| ### 2. **LLM Extractor ↔ Memory** | |
| ``` | |
| Input: JSON from Groq | |
| Process: Merge into state dict | |
| Output: Updated state with new values | |
| Error: Type mismatch, null values (OK) | |
| ``` | |
| ### 3. **Memory ↔ Feature Builder** | |
| ``` | |
| Input: State dict with all features | |
| Process: Validate ranges, convert types | |
| Output: Prepared feature vector | |
| Error: Out of range, type errors | |
| ``` | |
| ### 4. **Feature Builder ↔ Predictor** | |
| ``` | |
| Input: Feature vector [16 floats] | |
| Process: Load model, make prediction | |
| Output: Prediction class + probability | |
| Error: Model not found, predict error | |
| ``` | |
| ### 5. **Predictor ↔ Main App** | |
| ``` | |
| Input: Request for prediction | |
| Process: Get result from model | |
| Output: PredictionResponse object | |
| Error: Model errors, input errors | |
| ``` | |
| --- | |
| ## 🎯 Key Design Decisions | |
| ### Why Separate Services? | |
| - **llm_extractor.py**: Handles all Groq API logic | |
| - **feature_builder.py**: Handles all validation logic | |
| - **predictor.py**: Handles all ML model logic | |
| - **memory.py**: Handles state management | |
| - **helpers.py**: Handles UI text generation | |
| **Benefits**: | |
| - Easy to test each independently | |
| - Easy to modify without breaking others | |
| - Clear separation of concerns | |
| - Reusable components | |
| ### Why Pydantic Schemas? | |
| - Type validation | |
| - Automatic conversion | |
| - Error messages | |
| - Documentation | |
| - IDE autocomplete | |
| ### Why Groq Instead of Local LLM? | |
| - Free tier (very generous) | |
| - Fast inference (cloud-based) | |
| - No GPU needed | |
| - No local setup required | |
| - Easy to deploy on CPU-only Spaces | |
| ### Why scikit-learn Model? | |
| - Lightweight (fast on CPU) | |
| - Works on HF Spaces free tier | |
| - Easy to load/save (joblib) | |
| - No deep learning overhead | |
| - Deterministic results | |
| --- | |
| ## 🚀 Performance Considerations | |
| ### Typical Response Times | |
| | Step | Time | Notes | | |
| |------|------|-------| | |
| | Groq API call | 1-3s | Cloud-based, depends on load | | |
| | Feature extraction | <0.1s | JSON parsing | | |
| | Memory update | <0.01s | Dict operations | | |
| | Feature validation | <0.01s | Simple checks | | |
| | Prediction | <0.1s | scikit-learn inference | | |
| | **Total** | **1-3s** | User sees response in 1-3 seconds | | |
| ### Scalability | |
| - **Concurrent Users**: HF Spaces free CPU can handle ~10-20 concurrent users | |
| - **API Rate**: Groq free tier: very generous (1000s of calls/day) | |
| - **Model Size**: GradientBoosting small (<5MB) | |
| - **Memory Usage**: ~200MB for app + model | |
| --- | |
| ## 🔒 Security Considerations | |
| ### Secrets Handling | |
| - GROQ_API_KEY: Stored in .env locally, HF Spaces secrets in production | |
| - Model file: Public (no sensitive info) | |
| - User data: In-memory only (not persisted) | |
| ### Input Validation | |
| - All user inputs validated via Pydantic | |
| - Feature ranges checked | |
| - Type conversion safe | |
| ### Privacy | |
| - No data logged | |
| - No external APIs called except Groq | |
| - No user data persisted | |
| --- | |
| ## ⚡ Optimization Opportunities (Future) | |
| 1. **Caching**: Cache similar predictions | |
| 2. **Batching**: Process multiple users' requests together | |
| 3. **Model**: Use faster model variant | |
| 4. **LLM**: Use smaller Groq model for faster extraction | |
| 5. **Storage**: Add database for history (optional) | |
| --- | |
| This architecture is designed for: | |
| - ✅ Clarity & maintainability | |
| - ✅ Testability | |
| - ✅ Deployability on free Spaces | |
| - ✅ Easy debugging | |
| - ✅ Extensibility | |
| Ready to implement? Follow the GUIDES.md file step-by-step! | |