README.md

metadata

title: DocVis
emoji: 🏆
colorFrom: yellow
colorTo: green
sdk: streamlit
sdk_version: 1.44.1
app_file: app.py
pinned: false

🩺 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: 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

Prerequisites

• 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 to get a UMLS API Key.

Installation Steps

1. Clone the Repository:

   git clone <your-repository-url> # Replace with your repo URL
   cd <your-repository-directory>
   

2. Create and Activate a Virtual Environment (Recommended):

   # macOS / Linux
   python3 -m venv venv
   source venv/bin/activate
   # Windows
   # python -m venv venv
   # .\venv\Scripts\activate
   

3. Create requirements.txt:

   streamlit
   langchain
   langchain-groq
   langchain-community
   langgraph
   langchain-core
   pydantic>=1,<2 # Check compatibility
   groq
   tavily-python
   requests
   python-dotenv
   

4. Install Dependencies:

   pip install -r requirements.txt
   

API Keys

This application requires API keys for Groq, Tavily Search, and UMLS.

1. Groq API Key: Obtain from GroqCloud.
2. Tavily API Key: Obtain from Tavily AI.
3. UMLS API Key: Obtain after registering for a UMLS License via the UTS NLM Website.

Set these keys as environment variables.

• 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)

• Using System Environment Variables: (Commands vary by OS)

  # 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"
  

• 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.

▶️ Running the Application

Ensure your virtual environment is activated and API keys are accessible (either via .env or system environment). Then run:

streamlit run app.py
Use code with caution.
Markdown
The application should open in your web browser.

📖 How to Use
Patient Intake: Fill out the patient information form in the sidebar.

Start Consultation: Click "Start/Update Consultation". Initial red flags (if any) will appear in the sidebar.

Interact with AI: Use the chat input. Start by asking the AI to analyze the patient (e.g., "Analyze this patient", "Proceed with assessment").

Review Responses: Observe the chat:

AI questions or conversational text.

Tool execution messages (🛠️).

Interaction Warnings/Alerts: Pay close attention to outputs from the check_drug_interactions tool.

Reflection Output: Notice when the AI explicitly mentions reviewing warnings and potentially revising its plan.

Final Structured JSON output with the comprehensive assessment.

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.

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.

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.

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 this application's output.

Always rely on your professional training and judgment.

🔮 Future Enhancements
Full Memory Implementation: Add LLM-based summarization to manage long conversation context.

Deeper EMR/FHIR Simulation: Allow parsing more complex FHIR resources and generating draft resources based on the plan.

Refined Guideline Extraction: Improve the extraction and application of specific recommendations from searched guidelines.

User Feedback Integration: Allow explicit clinician overrides/edits to the plan.

More Granular Tools: Add calculators (clinical scores, dosages), tools for specific disease pathways, etc.

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)

**Key Updates in this README:**

*   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