Upd README

.gitignore

@@ -1,4 +1,3 @@
 .env
 .setup.txt
 __pycache__/
-sample.txt

README.md

@@ -18,6 +18,7 @@ tags:
 
 [Demo](https://huggingface.co/spaces/MCP-1st-Birthday/MedLLM-Agent)  
 
+
 # 🩺 MedLLM Agent
 
 **Advanced Medical AI Assistant** powered by fine-tuned MedSwin models with comprehensive knowledge retrieval capabilities.
@@ -31,6 +32,7 @@ tags:
 - Mitigates hallucination by grounding responses in your documents
 - Toggle RAG on/off - when disabled, provides concise clinical answers without document context
 
+
 ### 🌐 **Web Search Integration (MCP Protocol)**
 - **Native MCP Support**: Uses Model Context Protocol (MCP) tools for web search and content extraction
 - **Automatic Fallback**: Gracefully falls back to direct library calls if MCP is not configured
@@ -39,6 +41,7 @@ tags:
 - **Automatic Summarization**: Summarizes web search results using Gemini MCP
 - **Enriches Context**: Combines document RAG + web sources for comprehensive answers
 
+
 ### 🧠 **MedSwin Medical Specialist Models**
 - **MedSwin TA** (default) - Task-Aware merged model
 - **MedSwin SFT** - Supervised Fine-Tuned model
@@ -46,6 +49,7 @@ tags:
 - Models download on-demand for efficient resource usage
 - Fine-tuned on MedAlpaca-7B for medical domain expertise
 
+
 ### 🌍 **Multi-Language Support**
 - Automatic language detection
 - Non-English queries automatically translated to English
@@ -53,17 +57,21 @@ tags:
 - Responses translated back to original language
 - Powered by Gemini MCP for translation
 
+
 ### 🧾 **Clinical Intake Q&A Breakdown**
 - Gemini intake triage checks whether the user’s concern needs additional questioning (up to 5 follow-ups) and keeps per-session state.
 - Intake agent conducts focused Q&A, then auto-summarizes the transcript into patient profile, refined problem statement, and key findings with actionable handoff notes.
 - Pipeline injects both the structured insights and raw transcript back into the supervisor so downstream planning, RAG, and search stay grounded in what the patient actually said.
-- Users can toggle the intake flow directly in the UI; disabling clears any pending follow-up state.
+- Users can toggle the intake flow directly in the UI; disabling clears any pending follow-up state.  
+
+Sample [conversation](sample.md) between MAC-system and patient are recorded.
 
 ### 🎤 **Voice Features**
 - **Speech-to-Text**: Voice input transcription using Gemini MCP
 - **Inline Mic Experience**: Built-in microphone widget with live recording timer that drops transcripts straight into the chat box
 - **Text-to-Speech**: Voice output generation using Maya1 TTS model (optional, fallback to MCP if unavailable) plus a one-click "Play Response" control for the latest answer
 
+
 ### 🤝 **MAC Architecture (Multi-Agent Collaboration)**
 - **Gemini Supervisor**: Orchestrates query processing by breaking queries into flexible sub-topics (up to 10 based on complexity, explores different approaches)
 - **MedSwin Specialist**: Executes tasks sequentially, providing concise clinical answers
@@ -76,11 +84,13 @@ tags:
 - **Markdown Format**: Final answers use bullet points (tables automatically converted)
 - **Deterministic Mode**: `Disable agentic reasoning` switch runs MedSwin alone for offline-friendly, model-only answers
 
+
 ### ⚡ **Adaptive Strategy & Diagnostics**
 - **Autonomous Planner**: Gemini reasoning now enables/disables RAG and web search dynamically per query while respecting user toggles.
 - **Parallel Search Flow**: Multi-strategy web lookups run concurrently with cached MCP tool discovery and shared embeddings to cut latency.
 - **Pipeline Telemetry**: Every session logs stage durations, strategy decisions, and search outcomes for fast troubleshooting and quality tracking.
 
+
 ### ⚙️ **Advanced Configuration**
 - Customizable generation parameters (temperature, top-p, top-k)
 - Adjustable retrieval settings (top-k, merge threshold)
@@ -89,6 +99,7 @@ tags:
 - Dynamic system prompts based on RAG status
 - One-click agentic toggle to run MedSwin alone (no RAG/web search) for deterministic, offline-safe answers
 
+
 ## 🚀 Usage
 
 1. **Upload Documents**: Drag and drop PDF, Word, or text files containing medical information
@@ -102,6 +113,7 @@ tags:
    - Web sources (if web search enabled)
    - Medical model's training knowledge
 
+
 ## 🔧 Technical Details
 
 - **Medical Models**: MedSwin/MedSwin-7B-SFT, MedSwin-7B-KD, MedSwin-Merged-TA-SFT-0.7
@@ -117,6 +129,7 @@ tags:
 - **Web Search**: MCP tools with automatic fallback to DuckDuckGo
 - **MCP Server**: Bundled Python-based Gemini MCP server (agent.py)
 
+
 ## 📋 Requirements
 
 See `requirements.txt` for full dependency list. Key dependencies:
@@ -127,27 +140,24 @@ See `requirements.txt` for full dependency list. Key dependencies:
 - **Utilities**: `langdetect`, `gradio`, `spaces`, `soundfile`
 - **TTS**: Optional - `TTS` package (voice features work with MCP fallback if unavailable)
 
-### 🔌 MCP Configuration
 
+### 🔌 MCP Configuration
 The application uses a bundled Gemini MCP server (agent.py) for translation, document parsing, transcription, and summarization. Configure via environment variables
 
 **Setup Steps:**
-
 1. **Install Dependencies** (already in requirements.txt):
    ```bash
    pip install mcp nest-asyncio google-genai
-   ```
-
+   ```  
 2. **Get Gemini API Key**:
    - Visit [Google AI Studio](https://aistudio.google.com/) to get your API key
-   - Set it: `export GEMINI_API_KEY="your-api-key"`
-
+   - Set it: `export GEMINI_API_KEY="your-api-key"`  
 3. **Run the Application**:
    - The bundled MCP server (agent.py) will be used automatically
-   - No additional MCP server installation required
-
+   - No additional MCP server installation required  
 **Note**: The application requires Gemini MCP for translation, document parsing, transcription, and summarization. Web search supports fallback to direct DuckDuckGo API if MCP web search tools are unavailable.
 
+
 ## 🎯 Use Cases
 
 - **Clinical Decision Support**: Evidence-based answers from documents and current medical literature
@@ -156,14 +166,13 @@ The application uses a bundled Gemini MCP server (agent.py) for translation, doc
 - **Research Assistance**: Synthesize information from multiple medical sources
 - **Drug Information**: Comprehensive drug information with interaction analysis
 
-## 🏥 Enterprise-Level Clinical Decision Support
 
-### **Empowering Medical Specialists with AI-Powered Decision Support**
+## 🏥 Enterprise-Level Clinical Decision Support
 
+### **Empowering Medical Specialists with AI-Powered Decision Support**  
 MedLLM Agent is designed to support **doctors, clinicians, and medical specialists** in making informed clinical decisions by leveraging the power of Large Language Models (LLMs) and Model Context Protocol (MCP). This system transforms how medical professionals access, analyze, and synthesize medical information in real-time.
 
-### **Key Enterprise Capabilities**
-
+### **Key Enterprise Capabilities**  
 #### 1. **MAC Architecture (Multi-Agent Collaboration)**
 - **Gemini Supervisor Agent**: 
   - Breaks user queries into flexible sub-topics (up to 10 based on complexity, explores different approaches/angles)
@@ -172,8 +181,7 @@ MedLLM Agent is designed to support **doctors, clinicians, and medical specialis
   - In search mode: creates 1-4 search strategies, executes ddgs (1-2 sources each), summarizes briefly
   - Conditional search trigger: Can trigger additional searches if answer is unclear or has gaps (only when search mode enabled)
   - In RAG mode: brainstorms retrieved documents into 1-4 concise contexts
-  - All supervisor decisions logged internally, not displayed
-  
+  - All supervisor decisions logged internally, not displayed  
 - **MedSwin Specialist Agent**:
   - Executes tasks assigned by Gemini Supervisor (GPU-tagged)
   - Processes each sub-topic sequentially with focused context
@@ -184,20 +192,18 @@ MedLLM Agent is designed to support **doctors, clinicians, and medical specialis
 - **Internal Thoughts Hidden**: All Gemini-MedSwin conversations logged only
 - **Final Answer Only**: Users see only the polished, final answer
 - **Structured Output**: Markdown bullets, no internal planning tables
-- **Efficient Processing**: Contexts kept brief to respect token limits
+- **Efficient Processing**: Contexts kept brief to respect token limits  
 
-### **Enterprise Use Cases for Medical Specialists**
 
-#### **Clinical Decision Support**
-- **Diagnostic Assistance**: Upload patient records, lab results, and medical histories. Ask complex diagnostic questions and receive evidence-based answers grounded in your documents and current medical literature.
-
-- **Treatment Planning**: Query treatment protocols, drug interactions, and therapeutic guidelines. The system autonomously retrieves relevant information from your clinical documents and current medical databases.
+### **Enterprise Use Cases for Medical Specialists**  
 
+#### **Clinical Decision Support**
+- **Diagnostic Assistance**: Upload patient records, lab results, and medical histories. Ask complex diagnostic questions and receive evidence-based answers grounded in your documents and current medical literature.  
+- **Treatment Planning**: Query treatment protocols, drug interactions, and therapeutic guidelines. The system autonomously retrieves relevant information from your clinical documents and current medical databases.  
 - **Drug Information & Interactions**: Get comprehensive drug information, contraindications, and interaction analyses by combining your formulary documents with up-to-date web sources.
 
 #### **Research & Evidence Synthesis**
-- **Literature Review Support**: Upload research papers, clinical trials, and medical literature. The system helps synthesize findings, identify connections, and answer research questions.
-
+- **Literature Review Support**: Upload research papers, clinical trials, and medical literature. The system helps synthesize findings, identify connections, and answer research questions.  
 - **Clinical Guideline Analysis**: Compare and analyze multiple clinical guidelines, protocols, and best practices from your document library.
 
 #### **Multi-Language Clinical Support**
@@ -211,53 +217,47 @@ MedLLM Agent is designed to support **doctors, clinicians, and medical specialis
   - Current medical guidelines
 - **MCP Protocol Benefits**: Standardized, modular tool integration allows easy switching between search providers and enhanced reliability
 
-### **How It Works: MAC Architecture in Action**
 
+### **How It Works: MAC Architecture in Action**  
 1. **Gemini Supervisor - Query Breakdown** → Analyzes query and breaks into flexible sub-topics (up to 10 based on complexity):
    - Example: "What are the treatment options for Type 2 diabetes in elderly patients with renal impairment?"
    - Explores different approaches (clinical, diagnostic, treatment, prevention perspectives)
    - Creates structured sub-topics: treatment options, age considerations, renal function impact, drug interactions, monitoring protocols
    - Number of subtasks adapts to query complexity (not limited to 4)
-   - All planning logged internally, not displayed to user
-
+   - All planning logged internally, not displayed to user  
 2. **Gemini Supervisor - Context Preparation**:
    - **Search Mode**: Creates 1-4 search strategies → executes ddgs (1-2 sources each) → summarizes briefly
    - **RAG Mode**: Retrieves documents → brainstorms into 1-4 concise contexts for MedSwin
-   - Contexts kept brief to respect MedSwin token limits
-
+   - Contexts kept brief to respect MedSwin token limits    
 3. **MedSwin Specialist - Task Execution** (GPU-tagged):
    - Executes each sub-topic task sequentially
    - Receives focused context from Gemini Supervisor
    - Generates concise clinical answers (Markdown bullets, no tables)
-   - All execution logged internally
-
+   - All execution logged internally  
 4. **Gemini Supervisor - Answer Synthesis**:
    - Synthesizes all MedSwin responses with clear context
    - Integrates information from all sub-topics seamlessly
    - Creates coherent, comprehensive final answer
-   - Provides better context than simple concatenation
-
+   - Provides better context than simple concatenation  
 5. **Gemini Supervisor - Challenge & Enhancement Loop**:
    - Evaluates answer quality (completeness, accuracy, clarity)
    - Challenges answer if not optimal
    - Provides specific enhancement instructions
    - Enhances answer iteratively (up to 2 iterations)
-   - Continues until answer confirmed optimal
-
+   - Continues until answer confirmed optimal  
 6. **Conditional Search Trigger** (only when search mode enabled):
    - Supervisor checks if answer is unclear or has gaps
    - If needed, generates specific search queries to fill gaps
    - Executes additional searches
-   - Enhances answer with new search context
-
+   - Enhances answer with new search context  
 7. **Final Answer Assembly**:
    - Converts any tables to Markdown bullets
    - Adds citations if web sources used
    - Translates back if needed
    - **Only final answer displayed** - all internal thoughts remain in logs
 
-### **Enterprise Benefits**
 
+### **Enterprise Benefits**
 ✅ **Time Efficiency**: Reduces time spent searching through documents and medical databases  
 ✅ **Evidence-Based Decisions**: Grounds answers in uploaded documents and current medical literature  
 ✅ **Reduced Hallucination**: RAG ensures answers are based on actual documents and verified sources  
@@ -270,8 +270,8 @@ MedLLM Agent is designed to support **doctors, clinicians, and medical specialis
 ✅ **Clinical Workflow Integration**: Designed to fit into existing clinical decision-making processes  
 ✅ **MCP Protocol**: Standardized tool integration for reliable, maintainable web search capabilities
 
-### **Implementation in Clinical Settings**
 
+### **Implementation in Clinical Settings**
 - **Hospital Systems**: Clinical decision support with EMR integration and institutional medical libraries
 - **Specialty Clinics**: Customize with specialty-specific documents and guidelines
 - **Medical Education**: Comprehensive, evidence-based answers for training and education

sample.md

@@ -0,0 +1,59 @@
+# A Sample MAC-system conversation to the patient in Chronic Migraine topic
+
+**Patient:** Provide strategic treatment plan for a longterm chronic migraine patient
+
+**Model:** How often do you experience migraines, and how long do they typically last?
+**Patient:** I have it usually like once per month, they sharply last about half an hour but could repetitively occurs multiple time in the next 5-6 days
+
+**Model:** Can you describe the pain? For example, is it throbbing, sharp, dull, or a pressure sensation?
+**Patient:** Like stabbing pain, especially in one hemisphere or the frontal globe, near eyes part
+
+**Model:** On a scale of 0 to 10, with 10 being the worst pain imaginable, how severe is this stabbing pain when it occurs?
+**Patient:** I would say around 4-7 differed by occasions
+
+**Model:** Are there any specific triggers you've noticed that seem to bring on your migraines, such as certain foods, stress, or environmental factors?
+**Patient:** I'm not sure but typically it could be cold weather or overwhelming work habit
+
+**Model:** Have you experienced any other symptoms along with the stabbing pain, such as nausea, vomiting, sensitivity to light or sound, or visual disturbances like flashing lights or blind spots?
+**Patient:** We have all of that like nausea, vomiting, sensitivity to light, and blind spots
+
+**Model:** When these symptoms like nausea, vomiting, sensitivity to light, and blind spots occur, do they happen at the same time as the stabbing pain, or at a different time?
+**Patient:** Those pain only occurs in peak/climax migraine, last for like 10 mins, not necessarily the same time
+
+---
+
+# Final Answer: 
+## **Characterization of Paroxysmal Migraine Pain**
+Brief, intense, paroxysmal pain phenomena such as flashes of light, zigzag lines, blind spots, or temporary vision loss typically lasting about 5-20 seconds may occur during the peak/climax phase of a migraine attack. These are often described by patients as "auras" but do not involve hallucinations. The exact cause of these symptoms remains unknown, although they may be related to changes in blood flow or neurotransmitter activity within the brain. Treatment options include medication and lifestyle modifications.
+
+## **Nomenclature and Classification**
+Brief, intense "thunderclap" headaches that occur at the peak of a migraine are known as "migralepsy". These headaches can be differentiated from other headache types by their duration (<15 minutes), intensity (maximal), and temporal relationship to the migraine attack itself. Migralepsy may also present with autonomic symptoms such as nausea/vomiting, photophobia, phonophobia, and sweating. While not common, it's important for healthcare providers to recognize this subtype of migraine in order to optimize treatment strategies and prevent potential complications.
+
+## **Differential Diagnosis and Related Conditions**
+The following are some of the differential diagnosis for short duration, intense pain during peak migraine:   
+
+1) Primary Stabbing Headache (Ice Pick Headache) - Characterized by sudden, sharp, stabbing pains that lasts less than one minute, often triggered by physical activity such as chewing or talking. It may be associated with nausea/vomiting and sensitivity to light/sound.  
+
+2) Trigeminal Neuralgia - Pain along the path of the trigeminal nerve, usually unilateral, severe in intensity, spontaneous, shooting, electric shock-like quality. May occur at rest.
+
+3) Other Paroxysmal Cranial Nervagias - Includes cluster headaches, hemicrania continua, paroxysmal hemicranias, etc., which present similarly but have different etiologies.
+
+4) Migraine without Aura - Classic migraines can also present with similar symptoms if they are severe enough.
+
+5) Temporomandibular Joint Disease - Can cause referred facial pain mimicking migraine.
+
+6) Orofacial Pain Syndrome - General term encompassing various types of chronic facial pain not related to dentistry.
+
+7) Sinusitis / Otitis Media - Considered if there's recent history of sinus congestion or ear infection.
+
+8) Brain Tumor - Rarely presents with this type of pain, but should always be considered in patients over age 50 who develop new-onset headache.
+
+9) Medication Overuse Headache - If patient has been taking frequent medications for migraine prophylaxis.
+
+10) Psychogenic Non-Epileptic Seizures - Patients describe their attacks as "feeling like an electrical storm" in the brain.
+
+## **Pathophysiological Mechanisms**
+The exact mechanism underlying the precipitation of severe headache in migraines remains unclear; however, several theories have been proposed. One theory suggests that migraine attacks are triggered by abnormalities in serotonergic signaling within the trigeminal nerve nucleus caudalis (Vc). Serotonin receptors located here can be activated by vasoactive peptides released from sensory neurons innervating blood vessels supplying the brain. This activation leads to vasodilation and increased release of inflammatory mediators such as prostaglandins and bradykinin, which cause pain and other symptoms characteristic of a migraine. Another hypothesis proposes that cortical spread depression (CSD) plays an important role in triggering migraine attacks. CSD refers to transient electrical silence between adjacent regions of the cortex due to reduced Na+ conductance, leading to depolarization blockade and subsequent spread of action potentials. It has been shown that CSD occurs more frequently in patients with migraine compared to healthy controls, suggesting it might contribute to the initiation of migraine episodes. Other factors involved in migraine include genetic predisposition, environmental triggers, and changes in autonomic nervous system activity. Further research is needed to fully elucidate the complex interplay among these different mechanisms.
+
+## **Acute and Preventive Management Strategies**
+Acute treatment options for migraines include NSAIDs or triptans. Preventative treatments may involve daily medications like topiramate or amitriptyline, or more targeted therapies such as CGRP monoclonal antibodies. It's important to note that individual patient factors should be considered before starting any new medication.