Skip to content

README.md

Latest commit

 

History

History
219 lines (161 loc) · 7.57 KB

README.md

File metadata and controls

219 lines (161 loc) · 7.57 KB
Raw

🩺 SympTrackAI

AI-Powered Multilingual Patient Intake & Clinical Triage Assistant

Python Version React Vite TailwindCSS Gemma 4 License

SympTrackAI converts natural, spoken or typed patient descriptions in Gujarati, Hindi, English, or Mixed Regional Languages (Hinglish/Gujlish) into structured, standardized clinical summaries for physicians.

Key Features • System Architecture • Getting Started • API Documentation • Safety & Disclaimers

Important

Safety Disclaimer: SympTrackAI DOES NOT diagnose diseases, DOES NOT recommend medications, and DOES NOT generate treatment plans. It acts purely as a clinical intake assistant to structure patient-reported symptoms for doctors.

🎯 Problem Statement

Patients in diverse regions describe medical symptoms in local languages or mixed dialects:

"મને બે દિવસથી છાતીમાં દુખે છે અને આજે શ્વાસ લેવામાં તકલીફ થાય છે. BP ની દવા ચાલુ છે."
(Translation: "I have had chest pain for two days and today I am having difficulty breathing. I am taking BP medication.")

Doctor consultations are often time-constrained. SympTrackAI bridges the language and structure gap by automatically parsing unstructured multilingual intake text into standard medical categories (Chief Complaint, Symptoms, Duration, Pre-existing Conditions, Current Medications, Allergies) and flagging emergency indicators.

✨ Key Features

  • 🌐 Multilingual & Regional Support: Supports Gujarati (gu-IN), Hindi (hi-IN), English (en-IN), and Mixed-language (Hinglish/Gujlish) inputs.
  • 🎙️ Browser Voice-to-Text: Built-in Web Speech Recognition with graceful fallback for real-time speech intake.
  • 🚨 Deterministic Emergency Rule Engine: Instant visual alerts when red-flag symptoms (chest pain, dyspnea, loss of consciousness, severe hemorrhage) are detected.
  • 🤖 Guided Intake Assistant: Interactive assistant that selectively asks only for missing intake fields (age, allergies, duration, medicines) without providing medical advice.
  • 📝 Doctor-Ready Summary: Generates clean, printable, and copyable clinical notes with one-click PDF Download and Clipboard Export.
  • ✏️ Interactive Verification & Edit Screen: Every extracted field is reviewable and editable by clinic staff prior to final summary generation.

🏗 System Architecture

flowchart TD
    A[Patient / Intake Staff] -->|Voice or Text Input| B[React + Vite Frontend :3000]
    B -->|Proxy POST /extract| C[Flask Python Backend :5000]
    
    subgraph Backend Pipeline
        C --> D[Sanitise & Validate Input]
        D --> E[Gemma 4-31b-it Engine via Google AI Studio API]
        E --> F[Structured Clinical JSON Extraction]
        F --> G[Deterministic Emergency Rule Engine]
        G --> H[Doctor Summary Synthesizer]
    end
    
    H -->|Normalized Response JSON| B
    B --> I[Interactive Verification & Edit Screen]
    I --> J[Guided Intake Assistant - Fills Missing Fields]
    J --> K[Final Printable Clinical Summary & PDF Export]
Loading

🛠 Technology Stack

Frontend

  • Framework: React 19 + TypeScript + Vite
  • Styling: Tailwind CSS (Dark Mode Glassmorphism Theme)
  • UI & Animations: Lucide Icons, Framer Motion
  • Form Management: React Hook Form

Backend

  • Framework: Python 3.10+ & Flask Blueprint
  • LLM Engine: Google Gemma 4 (gemma-4-31b-it) via Google AI Studio API
  • Rule Engine: Custom deterministic medical trigger matching (emergency_rules.py)

🚀 Getting Started

📋 Prerequisites

  • Node.js: v18+ or v24+
  • Python: 3.10+
  • Google AI Studio API Key: Set in environment variables

🔧 1. Backend Setup

# 1. Navigate to the backend directory
cd backend

# 2. Create and activate a virtual environment
python -m venv venv
# On Windows:
venv\Scripts\activate
# On macOS/Linux:
source venv/bin/activate

# 3. Install Python dependencies
pip install -r requirements.txt

# 4. Create your .env file in the backend directory
echo GEMMA_API_KEY=your_google_ai_studio_api_key > .env

# 5. Start the Flask server
python app.py

The Flask backend will run on http://localhost:5000.

💻 2. Frontend Setup

Open a new terminal at the project root (SympTrackAI):

# 1. Install Node modules
npm install

# 2. Start the Vite development server
npm run dev

The React app will run on http://localhost:3000.

📑 API Endpoint Documentation

POST /extract

Extracts structured medical intake data from patient description text.

Request Body (application/json):

{
  "patient_text": "મને બે દિવસથી છાતીમાં દુખે છે અને આજે શ્વાસ લેવામાં તકલીફ થાય છે."
}

Success Response (200 OK):

{
  "success": true,
  "data": {
    "chief_complaint": "Chest pain and difficulty breathing",
    "symptoms": ["Chest pain", "Difficulty breathing"],
    "duration": "2 days",
    "age": "Not specified",
    "gender": "Unspecified",
    "medical_conditions": [],
    "medicines": ["BP medicine"],
    "allergies": [],
    "missing_information": ["Age", "Gender", "Allergies"],
    "emergency": true,
    "emergency_reason": "Chest pain with breathing difficulty",
    "doctor_summary": "PATIENT CLINICAL SUMMARY\nEmergency: YES..."
  }
}

🧪 Verification & Testing

Run the included backend core test suite:

python backend/test_core.py

Expected output:

============================================================
Emergency Rules Tests (4 official test cases)
============================================================
PASS  Test 1 | emergency=True | reason='Chest pain with breathing difficulty'
PASS  Test 2 | emergency=False
PASS  Test 3 | emergency=False
PASS  Test 4 | emergency=True | reason='Loss of consciousness / unresponsive patient'

============================================================
  ALL TESTS PASSED!
============================================================

To run the full-stack production build test:

npm run build

⚠️ Safety & Non-Diagnostic Disclaimer

IMPORTANT: SympTrackAI is an administrative intake software tool designed solely to assist medical personnel in capturing patient history.

  • No Autonomous Diagnosis: The system never generates clinical diagnoses.
  • No Prescriptions: The system never suggests drug dosages or treatment protocols.
  • Emergency Override: All emergency flags are generated via explicit, deterministic rules and require human physician review.

📄 License

Distributed under the MIT License. See LICENSE for more information.