Update README.md

README.md

@@ -8,45 +8,45 @@ sdk_version: 1.44.1
 app_file: app.py
 pinned: false
 ---
-# 🩺 SynapseAI: Interactive Clinical Decision Support Assistant
-
-**SynapseAI** is an advanced prototype demonstrating an AI-powered clinical decision support system built with Streamlit, Langchain, LangGraph, Groq (running Llama 3), and Tavily Search. It simulates an interactive consultation where an AI assistant helps analyze patient data, suggests differential diagnoses, proposes management plans, checks for drug interactions, flags risks, and integrates clinical guideline information.
-
-**This is a proof-of-concept application intended for demonstration and educational purposes only. It is NOT a certified medical device and should NEVER be used for actual clinical decision-making.**
-
-## ✨ Key Features
-
-*   **Interactive Conversational Interface:** Utilizes LangGraph to manage multi-turn interactions, allowing the AI to process information sequentially, ask clarifying questions, and respond to user input dynamically.
-*   **Structured Clinical Data Input:** Comprehensive sidebar form for inputting patient demographics, HPI, past history, medications, allergies, vitals, and basic exam findings.
-*   **Advanced AI Analysis (Llama 3 via Groq):** Leverages a powerful Large Language Model for clinical reasoning.
-*   **Structured AI Output:** The AI is prompted to provide its final analysis in a structured JSON format, including:
-    *   Clinical Assessment Summary
-    *   Differential Diagnosis (with likelihood & rationale)
-    *   Risk Assessment (Red Flags, Concerns, Complications)
-    *   Recommended Plan (Investigations, Therapeutics, Consults, Education)
-    *   Rationale Summary (Justification for the plan)
-    *   Interaction Check Summary
-*   **Intelligent Tool Use:** Employs Langchain tools for specific actions:
-    *   `order_lab_test`: Simulates ordering labs with reason and priority.
-    *   `prescribe_medication`: Simulates preparing prescriptions with details (requires prior interaction check).
-    *   `check_drug_interactions`: **Mandatory safety check** performed before prescription suggestions, considering current meds and allergies (using a mock database).
-    *   `flag_risk`: Allows the AI to highlight critical risks immediately.
-    *   `tavily_search_results`: Enables the AI to search for external information, specifically prompted to look up **current clinical practice guidelines**.
-*   **Safety Protocols:**
-    *   **Mandatory Interaction Checks:** The system enforces (via LangGraph logic) that an interaction check must be requested before a prescription tool call is executed.
-    *   **Red Flagging:** Includes both client-side initial checks and AI-driven risk flagging.
-*   **Guideline Awareness:** The AI is explicitly prompted to use web search (Tavily) to find and reference relevant clinical guidelines (e.g., ACC/AHA, Surviving Sepsis) in its rationale.
-*   **Robust Error Handling:** Implemented within the LangGraph `tool_node` to gracefully handle individual tool failures without crashing the application.
-*   **Clear User Interface:** Built with Streamlit for an intuitive web-based experience, separating data input, chat interaction, and results display.
+# 🩺 SynapseAI: Interactive Clinical Decision Support Assistant (v2 - UMLS/FDA Integrated)
+
+**SynapseAI** is an enhanced prototype demonstrating an AI-powered clinical decision support system. Built with a modular structure (`app.py` for UI, `agent.py` for logic), it uses Streamlit, Langchain, LangGraph, Groq (running Llama 3), Tavily Search, **UMLS/RxNorm API**, and **OpenFDA API**.
+
+It simulates an interactive consultation where an AI assistant helps analyze patient data, suggests differential diagnoses, proposes management plans, performs **realistic drug interaction and allergy checks**, flags risks, incorporates clinical guideline information, and includes a **self-correction loop** based on interaction warnings.
+
+**⚠️ Disclaimer: This is a proof-of-concept application intended for demonstration and educational purposes only. It is NOT a certified medical device and should NEVER be used for actual clinical decision-making.**
+
+## ✨ Key Features (v2 Enhancements in Bold)
+
+*   **Interactive Conversational Interface:** Uses LangGraph for multi-turn interactions, sequential processing, and dynamic responses.
+*   **Structured Clinical Data Input:** Comprehensive sidebar form for patient intake.
+*   **Advanced AI Analysis:** Leverages Llama 3 via Groq for clinical reasoning.
+*   **Structured AI Output:** Provides analysis in JSON (Assessment, DDx, Risk, Plan, Rationale, Interaction Summary).
+*   **Intelligent Tool Use:** Employs Langchain tools:
+    *   `order_lab_test`: Simulates ordering labs.
+    *   `prescribe_medication`: Simulates preparing prescriptions (requires prior interaction check).
+    *   **`check_drug_interactions` (Enhanced):** Performs **realistic drug-drug and drug-allergy checks** using **UMLS/RxNorm API** for drug normalization and **OpenFDA API** for retrieving contraindications, warnings, and interaction data from drug labels.
+    *   `flag_risk`: Allows AI to highlight critical risks.
+    *   `tavily_search_results`: Searches for external info, prompted for **current clinical guidelines**.
+*   **Enhanced Safety Protocols:**
+    *   **Mandatory & Realistic Interaction Checks:** Enforces interaction checks before prescription; checks now use real-world APIs.
+    *   **Self-Correction Loop:** Includes a dedicated step (`reflection_node`) in the LangGraph workflow where the agent specifically reviews significant interaction/allergy warnings and revises its therapeutic plan *before* presenting the final output.
+    *   Red Flagging: Client-side initial checks and AI-driven risk flagging.
+*   **Guideline Awareness:** AI prompted to search for and reference clinical guidelines.
+*   **Modular Code Structure:** Separated UI (`app.py`) from core agent logic (`agent.py`) for better organization and maintainability.
+*   **Robust Error Handling:** Implemented within LangGraph nodes and API helpers.
 
 ## 🚀 Technology Stack
 
 *   **Python:** Core programming language.
 *   **Streamlit:** Web application framework for the UI.
 *   **Langchain & LangGraph:** Framework for building LLM applications, managing conversation state, and orchestrating tool use.
-*   **Groq API:** Provides fast inference for the Llama 3 LLM (or other supported models).
-*   **Tavily Search API:** Enables the AI to perform web searches for guidelines and information.
-*   **Pydantic:** Used for data validation in tool inputs.
+*   **Groq API:** Fast inference for Llama 3 LLM.
+*   **Tavily Search API:** Web search for guidelines.
+*   **UMLS API (via RxNav/RxNorm):** Drug name normalization (finding RxCUIs). Requires UMLS Metathesaurus License and API Key.
+*   **OpenFDA API:** Retrieving drug label information (interactions, warnings, contraindications).
+*   **Requests:** For making HTTP calls to external APIs.
+*   **Pydantic:** Data validation in tool inputs.
 
 ## ⚙️ Setup and Installation
 
@@ -55,6 +55,7 @@ pinned: false
 *   Python 3.8+
 *   `pip` (Python package installer)
 *   Git (for cloning the repository)
+*   **UMLS Metathesaurus License:** You **must** obtain a free license from the [NLM UMLS Website](https://uts.nlm.nih.gov/uts/signup-login) to get a UMLS API Key.
 
 ### Installation Steps
 
@@ -65,144 +66,132 @@ pinned: false
     ```
 
 2.  **Create and Activate a Virtual Environment (Recommended):**
-    *   **macOS / Linux:**
-        ```bash
-        python3 -m venv venv
-        source venv/bin/activate
-        ```
-    *   **Windows:**
-        ```bash
-        python -m venv venv
-        .\venv\Scripts\activate
-        ```
-
-3.  **Install Dependencies:**
     ```bash
-    pip install -r requirements.txt
+    # macOS / Linux
+    python3 -m venv venv
+    source venv/bin/activate
+    # Windows
+    # python -m venv venv
+    # .\venv\Scripts\activate
     ```
-    *(You'll need to create a `requirements.txt` file containing necessary libraries. See example below)*
-
-### `requirements.txt` Example
-
-```txt
-streamlit
-langchain
-langchain-groq
-langchain-community # For Tavily Search tool
-langgraph
-langchain-core
-pydantic>=1,<2 # Langchain often has specific Pydantic version needs
-groq
-tavily-python
-python-dotenv # Optional: For managing environment variables from a .env file
-Use code with caution.
-Markdown
-(Adjust versions as needed based on compatibility)
 
-API Keys
-This application requires API keys for Groq and Tavily Search.
+3.  **Create `requirements.txt`:**
+    ```txt
+    streamlit
+    langchain
+    langchain-groq
+    langchain-community
+    langgraph
+    langchain-core
+    pydantic>=1,<2 # Check compatibility
+    groq
+    tavily-python
+    requests
+    python-dotenv
+    ```
 
-Groq API Key: Obtain from GroqCloud.
+4.  **Install Dependencies:**
+    ```bash
+    pip install -r requirements.txt
+    ```
 
-Tavily API Key: Obtain from Tavily AI.
+### API Keys
 
-Set these keys as environment variables. Do NOT hardcode them in your script.
+This application requires API keys for Groq, Tavily Search, and UMLS.
 
-macOS / Linux:
+1.  **Groq API Key:** Obtain from [GroqCloud](https://console.groq.com/keys).
+2.  **Tavily API Key:** Obtain from [Tavily AI](https://tavily.com/).
+3.  **UMLS API Key:** Obtain after registering for a UMLS License via the [UTS NLM Website](https://uts.nlm.nih.gov/uts/profile).
 
-export GROQ_API_KEY="your_groq_api_key"
-export TAVILY_API_KEY="your_tavily_api_key"
-Use code with caution.
-Bash
-Windows (Command Prompt):
+**Set these keys as environment variables.**
 
-set GROQ_API_KEY=your_groq_api_key
-set TAVILY_API_KEY=your_tavily_api_key
-Use code with caution.
-Bash
-Windows (PowerShell):
+*   **Using a `.env` file (Recommended for Local):** Create a `.env` file in the project root:
+    ```
+    GROQ_API_KEY="your_groq_api_key"
+    TAVILY_API_KEY="your_tavily_api_key"
+    UMLS_API_KEY="your_umls_api_key"
+    ```
+    *(Ensure `.env` is in your `.gitignore`)*
 
-$env:GROQ_API_KEY="your_groq_api_key"
-$env:TAVILY_API_KEY="your_tavily_api_key"
-Use code with caution.
-Bash
-Alternative: Create a .env file in the project root:
+*   **Using System Environment Variables:** (Commands vary by OS)
+    ```bash
+    # Example for Linux/macOS
+    export GROQ_API_KEY="your_groq_api_key"
+    export TAVILY_API_KEY="your_tavily_api_key"
+    export UMLS_API_KEY="your_umls_api_key"
+    ```
 
-GROQ_API_KEY="your_groq_api_key"
-TAVILY_API_KEY="your_tavily_api_key"
-Use code with caution.
-And load it in your Python script using python-dotenv:
+*   **Using Hugging Face Space Secrets (if deploying there):**
+    Go to your Space -> Settings -> Secrets and add secrets named `GROQ_API_KEY`, `TAVILY_API_KEY`, and `UMLS_API_KEY` with their respective values.
 
-# Add near the top of your main script (e.g., app.py)
-from dotenv import load_dotenv
-load_dotenv()
-Use code with caution.
-Python
-▶️ Running the Application
-Ensure your virtual environment is activated and API keys are set. Then run:
+## ▶️ Running the Application
+
+Ensure your virtual environment is activated and API keys are accessible (either via `.env` or system environment). Then run:
 
-streamlit run your_script_name.py # Replace 'your_script_name.py' with the actual filename
+```bash
+streamlit run app.py
 Use code with caution.
-Bash
+Markdown
 The application should open in your web browser.
 
 📖 How to Use
-Patient Intake: Fill out the detailed patient information form in the left sidebar.
-
-Start Consultation: Click the "Start/Update Consultation" button at the bottom of the sidebar. This loads the data and performs initial red flag checks.
+Patient Intake: Fill out the patient information form in the sidebar.
 
-Interact with AI: Use the chat input box at the bottom of the main screen to:
+Start Consultation: Click "Start/Update Consultation". Initial red flags (if any) will appear in the sidebar.
 
-Ask the AI to analyze the loaded patient data (e.g., "Please analyze this patient.").
+Interact with AI: Use the chat input. Start by asking the AI to analyze the patient (e.g., "Analyze this patient", "Proceed with assessment").
 
-Ask follow-up questions.
+Review Responses: Observe the chat:
 
-Provide additional information requested by the AI.
+AI questions or conversational text.
 
-Review Responses: Observe the AI's responses in the chat interface. Pay attention to:
+Tool execution messages (🛠️).
 
-Natural language replies or questions.
+Interaction Warnings/Alerts: Pay close attention to outputs from the check_drug_interactions tool.
 
-Tool execution messages (indicated by 🛠️).
+Reflection Output: Notice when the AI explicitly mentions reviewing warnings and potentially revising its plan.
 
-Structured JSON output containing the full clinical assessment and plan (when the AI determines it's ready).
+Final Structured JSON output with the comprehensive assessment.
 
-Any safety warnings or flagged risks.
+Flagged risks shown as prominent errors (🚨).
 
 ⚠️ Important Disclaimer
 SynapseAI is an experimental AI assistant demonstration.
 
-NOT FOR CLINICAL USE: It is NOT a substitute for professional medical advice, diagnosis, or treatment provided by a qualified healthcare provider.
+NOT FOR CLINICAL USE: It is NOT a substitute for professional medical advice, diagnosis, or treatment.
 
-VERIFY ALL OUTPUT: All information, suggestions, differential diagnoses, medication recommendations, dosages, and interaction checks generated by the AI MUST be independently verified using standard, reliable medical resources and clinical judgment.
+VERIFY ALL OUTPUT: All information, suggestions, diagnoses, medication recommendations, dosages, interaction checks, and guideline interpretations MUST be independently verified using standard medical resources and clinical judgment.
 
-AI LIMITATIONS: LLMs can hallucinate, make errors, and may not have access to the absolute latest medical knowledge or specific patient context beyond what is provided.
+API LIMITATIONS: Relies on external APIs (RxNorm, OpenFDA, Tavily) which have their own limitations, potential downtimes, and data coverage gaps. Interaction checking is complex and may not catch everything.
 
-MOCK DATA: Features like drug interaction checks currently rely on a limited, hardcoded mock database.
+AI LIMITATIONS: LLMs can hallucinate, make errors, and may misinterpret API results or guidelines.
 
-NO LIABILITY: The creators assume no responsibility for any decisions made based on the output of this application.
+NO LIABILITY: The creators assume no responsibility for any decisions made based on this application's output.
 
-Always rely on your professional training and judgment when caring for patients.
+Always rely on your professional training and judgment.
 
 🔮 Future Enhancements
-True Multi-Turn Refinement: Implement more sophisticated state management (e.g., LangGraph checkpointers) to allow the AI to refine its plan based on tool results within a single logical turn.
+Full Memory Implementation: Add LLM-based summarization to manage long conversation context.
 
-Real Databases: Integrate with actual drug interaction databases (e.g., OpenFDA, RxNorm APIs) and potentially medical knowledge graphs.
+Deeper EMR/FHIR Simulation: Allow parsing more complex FHIR resources and generating draft resources based on the plan.
 
-EMR Integration Concepts: Simulate reading/writing structured data in formats compatible with EMR/EHR systems (e.g., FHIR resources).
+Refined Guideline Extraction: Improve the extraction and application of specific recommendations from searched guidelines.
 
-User Feedback Loop: Allow clinicians to edit/approve/reject AI suggestions and potentially use this feedback for evaluation or fine-tuning (requires significant infrastructure).
+User Feedback Integration: Allow explicit clinician overrides/edits to the plan.
 
-Improved NLP: Enhance extraction of structured data from free-text inputs (e.g., HPI, PMH notes).
+More Granular Tools: Add calculators (clinical scores, dosages), tools for specific disease pathways, etc.
 
-Context Window Management: Implement strategies (summarization, sliding window) for handling very long conversations.
+Asynchronous Operations: Improve UI responsiveness during long API calls (more complex in Streamlit).
 
 📄 License
 (Optional: Specify a license, e.g., MIT, Apache 2.0, or state if it's proprietary)
 
-**Remember to:**
+**Key Updates in this README:**
 
-1.  Replace `app.py` with the name of your main Python file.
-2.  Create the `requirements.txt` file based on the example provided and your actual dependencies.
-3.  Consider adding a `LICENSE` file if you choose an open-source license.
+*   Reflects the **v2** status and highlights the integration of **UMLS/RxNorm and OpenFDA APIs** for realistic interaction checks.
+*   Explicitly mentions the **self-correction loop (`reflection_node`)** as a key feature.
+*   Includes instructions for obtaining a **UMLS License/API Key**.
+*   Updates the **Technology Stack** list.
+*   Emphasizes the reliance on **external APIs** and their limitations in the disclaimer.
+*   Reflects the **modular file structure** (`app.py`, `agent.py`).
 Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference