| # Daease - Medical AI Assistant Architecture | |
| ## Overview | |
| Daease is an AI-powered medical consultation application that enables users to describe their symptoms and receive AI-generated medical guidance. The application integrates with medical knowledge bases, provides sourced information, and can generate detailed medical reports. | |
| ## Project Structure | |
| ``` | |
| . | |
| ├── app.py # Main Streamlit application entry point | |
| ├── model.py # AI model integration and medical evidence retrieval | |
| ├── report_generator.py # Report generation functionality | |
| ├── utils.py # Utility functions for text processing | |
| ├── chat_display.py # Chat UI components and rendering | |
| ├── session_state.py # Session state management | |
| ├── database.py # Database integration with Supabase | |
| ├── styles.py # Custom CSS styling | |
| ├── sendgrid_service.py # Email service for sending reports | |
| ├── __init__.py # Package initialization | |
| ├── requirements.txt # Project dependencies | |
| └── README_DB_SETUP.md # Database setup instructions | |
| ``` | |
| ## Core Components | |
| ### 1. Main Application (`app.py`) | |
| The entry point for the Streamlit web application. | |
| **Key Features:** | |
| - Streamlit UI setup with dark theme | |
| - Chat interface for medical consultations | |
| - Toggle for enabling/disabling medical database search (RAG) | |
| - Report generation functionality with priority management | |
| - Conversation lock mechanism to ensure uninterrupted user experience | |
| - Session state management | |
| - "End Conversation" functionality | |
| **Flow:** | |
| 1. Initializes session state and applies styling | |
| 2. Sets up the sidebar with features toggle and report generation button | |
| 3. Displays chat history and handles new user inputs | |
| 4. Prioritizes conversation processing over report generation | |
| 5. Processes user queries through the orchestrator model | |
| 6. Updates the UI with AI responses | |
| 7. Only processes report generation when no conversation is active | |
| ### 2. AI Model Integration (`model.py`) | |
| Handles all AI interactions, medical evidence retrieval, and response processing. | |
| **Key Features:** | |
| - Medical evidence retrieval from multiple sources (PubMed, WHO, CORE) | |
| - Orchestration of conversation flow | |
| - Source extraction and linking | |
| - Response parsing and formatting | |
| **Key Functions:** | |
| - `orchestrator_chat()`: Coordinates the conversation flow | |
| - `fetch_medical_evidence()`: Retrieves evidence from medical databases | |
| - `extract_and_link_sources()`: Processes and links sources in responses | |
| - Multiple API integrations: PubMed, PMC, WHO, CORE | |
| ### 3. Report Generation (`report_generator.py`) | |
| Handles the creation of medical reports based on consultation history. | |
| **Key Features:** | |
| - Extraction of medical information from conversation | |
| - PDF report generation with ReportLab | |
| - File download functionality | |
| - Email integration for report sharing | |
| - Error handling for patient information validation | |
| - Conversation-aware processing to prevent disruptions | |
| **Key Functions:** | |
| - `extract_medical_json()`: Extracts structured medical data from conversations | |
| - `build_medical_report()`: Creates a formatted PDF report | |
| - `generate_and_download_report()`: Manages the report generation workflow with conversation awareness | |
| - `show_email_form()`: Handles the email input and sending interface | |
| ### 4. Utility Functions (`utils.py`) | |
| Provides helper functions for text processing and formatting. | |
| **Key Functions:** | |
| - `remove_reasoning_and_sources()`: Cleans up AI responses for display | |
| - `clean_explanation()`: Formats explanation sections | |
| - `format_conversation_history()`: Prepares chat history for report generation | |
| - `get_image_base64()`: Handles image encoding for the UI | |
| ### 5. Chat Display (`chat_display.py`) | |
| Manages the chat interface components and rendering. | |
| **Key Functions:** | |
| - `display_chat_history()`: Renders the chat messages from database | |
| - `show_typing_indicator()`: Shows a typing animation while processing | |
| - `display_legal_disclaimer()`: Shows medical disclaimer | |
| - `get_avatars()`: Handles avatar images for the chat | |
| ### 6. Session State Management (`session_state.py`) | |
| Manages the application's state across interactions and integrates with database. | |
| **Key Functions:** | |
| - `initialize_session_state()`: Sets up all required session variables | |
| - `add_message_to_history()`: Adds messages to both local cache and database | |
| - `get_full_history()`: Retrieves complete conversation history from database | |
| - `end_conversation()`: Deletes conversation data from database | |
| **State Variables:** | |
| - `history`: Local cache of chat message history | |
| - `consultation_id`: Unique ID for each consultation | |
| - `use_rag`: Toggle for retrieval-augmented generation | |
| - `processing`: Flag for response generation status | |
| - `conversation_lock`: Flag to prioritize conversations over report generation | |
| - `show_report_form`: Report generation form visibility | |
| - `patient_info`: Patient details for reports | |
| - `pdf_data`: Generated PDF report data | |
| - `show_email_form`: Email form visibility | |
| ### 7. Database Integration (`database.py`) | |
| Handles persistence of conversation data in Supabase. | |
| **Key Features:** | |
| - Supabase integration for conversation history storage | |
| - Error handling and fallback mechanisms | |
| - Conversation and message management | |
| **Key Functions:** | |
| - `create_conversation()`: Creates a new conversation record | |
| - `save_message()`: Saves individual messages to the database | |
| - `get_conversation_history()`: Retrieves complete history for a consultation | |
| - `delete_conversation()`: Removes conversation data when no longer needed | |
| ### 8. Styling (`styles.py`) | |
| Provides custom CSS styling for the application. | |
| **Key Features:** | |
| - Dark theme implementation | |
| - Custom chat message styling (user vs. assistant) | |
| - Responsive layout design | |
| - Buttons and form elements styling | |
| **Key Function:** | |
| - `apply_styling()`: Applies the custom CSS to the Streamlit app | |
| ### 9. Email Service (`sendgrid_service.py`) | |
| Handles email functionality for sending reports. | |
| **Key Features:** | |
| - SendGrid API integration | |
| - Email validation | |
| - PDF attachment handling | |
| - Error handling and logging | |
| **Key Methods:** | |
| - `send_report()`: Sends the medical report via email | |
| - `validate_email()`: Performs basic email validation | |
| ## Application Flow | |
| 1. **Initialization:** | |
| - Load environment variables | |
| - Initialize session state and database connection | |
| - Apply custom styling | |
| 2. **User Interaction:** | |
| - User inputs symptoms or medical queries | |
| - Conversation lock is activated to prioritize conversation processing | |
| - The application displays a typing indicator while processing | |
| 3. **Query Processing:** | |
| - `orchestrator_chat()` handles the conversation flow | |
| - If RAG is enabled, `fetch_medical_evidence()` retrieves relevant medical information | |
| - The model generates a response with reasoning and evidence | |
| 4. **Response Display:** | |
| - Main response is shown in the chat | |
| - Detailed reasoning is available in an expandable section | |
| - Sources are linked to their original content | |
| - All data is persisted to the database | |
| - Conversation lock is released after response is processed | |
| 5. **Report Generation:** | |
| - User clicks "Generate Report" button | |
| - System checks that no conversation is being processed | |
| - Application retrieves full conversation history from database | |
| - Input validation ensures all form fields have valid values | |
| - PDF report is generated with patient information and consultation details | |
| - User can download the report or send it via email | |
| 6. **Email Functionality:** | |
| - User enters recipient email | |
| - System validates email format | |
| - Report is sent using the SendGrid service | |
| 7. **End Conversation:** | |
| - User can end the conversation which deletes the data from the database | |
| - A new conversation ID is generated for future interactions | |
| ## Dependencies | |
| - **Core:** openai, requests, beautifulsoup4, markdown, python-dotenv | |
| - **Report Generation:** jinja2, python-docx, pydantic, reportlab | |
| - **Web App:** streamlit | |
| - **Database:** supabase, postgrest | |
| ## Security and Compliance | |
| - Medical disclaimer is prominently displayed | |
| - Email functionality includes appropriate medical disclaimers | |
| - Database storage is secured with row-level security | |
| - Conversations can be deleted to ensure data privacy |