src/architecture.md

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