README.md

---
title: Medical Assistant with Spiritual Support v.2.3.2
emoji: 🩺
colorFrom: blue
colorTo: green
sdk: gradio
sdk_version: 6.0.2
app_file: src/interface/simplified_gradio_app.py
pinned: false
---

# Medical Assistant with Spiritual Support

A comprehensive medical chat application with **automatic background monitoring for spiritual distress** and **advanced prompt optimization system**.

This system provides seamless medical assistance while intelligently detecting and addressing spiritual care needs through a sophisticated AI-powered classification and triage system.

## ⚡ Quick Start

### 🎯 Two Interface Options

The project now offers **two interfaces** to suit different needs:

#### 1. **Simplified Interface** (Recommended for Testing Team)
- ✅ Provider Summary as **final exchange** in verification
- ✅ **Auto-save** reports with single button
- ✅ Streamlined UI focused on testing

```bash
python run_simplified_interface.py
# http://localhost:7861
```

📖 **Quick Guide:** See `QUICK_START_SIMPLIFIED.md` or `QUICK_START_SIMPLIFIED_EN.md`

#### 2. **Full Interface** (For Development & Configuration)
Complete feature set with all advanced options:

```bash
python app.py
# http://localhost:7860
```

### Local Setup

**🏥 Medical Assistant + 🕊️ Spiritual Support + 🔧 Prompt Optimization**

```bash
# 1. Configure API Keys (first time)
cat > .env << EOF
GEMINI_API_KEY=your_gemini_api_key_here
ANTHROPIC_API_KEY=your_anthropic_api_key_here
EOF

# 2. Install Dependencies
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# 3. Run Application
# Simplified Interface (for testing):
python run_simplified_interface.py

# OR Full Interface (for development):
python app.py
```

### Interface Comparison

| Feature | Simplified | Full |
|---------|-----------|------|
| Chat & Verification | ✅ | ✅ |
| Provider Summary as Final Exchange | ✅ | ❌ |
| Auto-Save Reports | ✅ | ❌ |
| Model Settings | ❌ | ✅ |
| Edit Prompts | ❌ | ✅ |
| Patient Profiles | ❌ | ✅ |

📊 **Full Comparison:** See `COMPARISON.md`

**Main Interface Tabs (Full):**
- 💬 **Chat** — Primary medical conversation with automatic spiritual monitoring
- 🧾 **Conversation Verification** — Review and export chat-derived verification sessions
- 🔍 **Enhanced Verification** — Manual input and file upload workflows for structured testing
- ⚙️ **Model Settings** — Configure AI models for different tasks (session-scoped)
- 🔧 **Edit Prompts** — Real-time prompt editing with session-level overrides
- 👥 **Patient Profiles** — Predefined patient scenarios for testing
- 📖 **Help** — Comprehensive user guide

**Main Interface Tabs (Simplified):**
- 💬 **Chat** — Test conversations with medical assistant
- 🧾 **Conversation Verification** — Review exchanges with Provider Summary as final step
- 📖 **Help** — User guide and documentation

---

## 🎯 System Architecture

### Intelligent Spiritual Monitoring
The system operates as a **Medical Assistant** while continuously monitoring for spiritual distress:

```
Patient: "I'm feeling stressed about my treatment"
    ↓
[Spiritual Monitor] → YELLOW (Potential distress detected)
    ↓
[Soft Spiritual Triage] → Asks 2-3 gentle clarifying questions
    ↓
[Triage Response Evaluator] → Evaluates responses
    ↓
Result: GREEN (Coping well) or RED (Needs referral)
```

### Three-Tier Classification System (Enhanced v2.2)

**🟢 GREEN (No Spiritual Distress)**
- Medical symptoms only
- Routine health questions
- Standard wellness topics
- **Clear positive statements** like "I am fine" (now correctly classified)
- No emotional or spiritual concerns

**🟡 YELLOW (Potential Spiritual Distress - Needs Clarification)**
- **Simple sadness without spiritual context** (improved classification)
- Stress, anxiety, sleep issues
- Grief and loss (without expressed distress)
- Existential questions
- Spiritual disconnection
- Feelings of isolation
- Loss of interest in activities
- **Ambiguous situations** requiring further investigation

**🔴 RED (Active Spiritual Distress - Immediate Attention)**
**Updated Definition:** Patient's situation appears to be **caused by or actively causing** emotional or spiritual distress (broader than crisis-only)

**Explicit RED Indicators (Always RED):**
- **Complex grief**
- **Loss of a loved one** (when patient expresses emotional distress)
- **Doubt about meaning of life** (e.g., "Life has no meaning anymore")
- **Doubt about meaning of suffering**
- **Doubt about personal dignity**
- **Loss of meaning and purpose**
- Suicidal ideation
- Severe hopelessness
- Spiritual crisis
- Anger at God/higher power
- Moral injury

---

## 🚀 Advanced Prompt Optimization System

### Centralized Prompt Management
- **PromptController**: Orchestrates all prompt operations with shared components
- **Shared Catalogs**: Centralized storage for indicators, rules, templates, and categories
- **Session Isolation**: Test prompt changes without affecting production
- **Three-tier Priority**: Session Overrides → Centralized Files → Default Fallbacks

### Session-Level Prompt Overrides
- **Real-time Testing**: Edit prompts and test immediately
- **Session Isolation**: Changes apply only to your current session
- **Promote to File**: Tested changes can be promoted to permanent files
- **Automatic Backups**: Original files backed up before promotion

### Enhanced Edit Prompts Interface
- **Visual Indicators**: Clear display of prompt sources (session vs centralized)
- **Real-time Validation**: Immediate feedback on prompt structure and syntax
- **CSS-Optimized Display**: No UI overflow issues with validation messages
- **Promote Workflow**: Easy promotion of tested changes to permanent files

---

## 📦 Core Components

### 1. 🏥 Simplified Medical App
Main application logic with integrated spiritual monitoring.
**File:** `src/core/simplified_medical_app.py`

### 2. 🔍 Spiritual Monitor
Classifies patient messages into GREEN/YELLOW/RED categories.
**File:** `src/core/spiritual_monitor.py`

### 3. 🟡 Soft Triage Manager
Conducts gentle spiritual triage questioning for YELLOW states.
**File:** `src/core/soft_triage_manager.py`

### 4. � Provider Summary Generator
Generates structured summaries and compassionate LLM-based messages for spiritual care team.
**File:** `src/core/provider_summary_generator.py`

### 5. �🔧 Prompt Management System
Centralized prompt optimization with session-level overrides.
**Files:** `src/config/prompt_management/`

### 6. 🎨 Enhanced Gradio Interface
Comprehensive web interface with all features integrated.
**File:** `src/interface/gradio_app.py`

---

## � Projecнt Structure

```
.
├── src/
│   ├── core/                              # Core application logic
│   │   ├── simplified_medical_app.py      # Main application
│   │   ├── spiritual_monitor.py           # Distress classifier
│   │   ├── soft_triage_manager.py         # Gentle triage questioning
│   │   ├── spiritual_state.py             # State management
│   │   └── ai_client.py                   # AI provider interface
│   ├── config/
│   │   ├── prompt_management/             # 🆕 Prompt optimization system
│   │   │   ├── prompt_controller.py       # Central orchestrator
│   │   │   ├── shared_components.py       # Shared catalogs
│   │   │   ├── data_models.py             # Data structures
│   │   │   └── data/                      # JSON storage
│   │   ├── prompts/                       # Prompt files
│   │   └── ai_providers_config.py         # Model configurations
│   └── interface/
│       ├── gradio_app.py       # Main web interface
│       └── enhanced_prompt_editor.py      # 🆕 Prompt editing UI
│
├── tests/                                 # 🆕 Organized test structure
│   ├── prompt_optimization/               # Prompt system tests
│   ├── integration/                       # Integration tests
│   ├── unit/                              # Unit tests
│   ├── verification/                      # Verification tests
│   └── chaplain_feedback/                 # Chaplain feedback tests
│
├── scripts/                               # 🆕 Utility scripts
│   ├── cleanup_test_data.py
│   ├── reorganize_files.py
│   └── run_tests.py
│
├── review/                                # 🆕 Medical professional feedback
│   ├── README.md                          # Comprehensive review documentation (Ukrainian)
│   ├── Or_2.txt                           # Medical professional recommendations
│   └── *.json                             # Verified conversation examples
├── docs/                                  # Documentation
├── .verification_data/                    # Test data and sessions
├── requirements.txt                       # Dependencies
├── .env                                   # API keys (not in git)
└── README.md                              # This file
```

---

## 🎯 Key Features

### 🏥 Medical Assistant with Spiritual Support

#### Intelligent Background Monitoring
- 🔍 Automatic spiritual distress detection
- 🚦 Three-tier classification system (🟢 🟡 🔴)
- 📝 Provider summary generation for RED cases
- 💬 LLM-generated compassionate messages for spiritual care team
- ❓ Gentle triage questioning for YELLOW cases
- 🤝 Consent-based referral process

#### Advanced AI Model Selection
- 🤖 Choose between Claude and Gemini models
- ⚙️ Task-specific model configuration (6 distinct agents)
- 🔄 Dynamic model switching
- 💾 Session-scoped settings

#### Comprehensive Prompt Management
- 🔧 Edit 6 system prompts in real-time (including Spiritual Care Message)
- 📝 Session-level prompt overrides
- ✅ Real-time validation and syntax checking
- 📤 Promote tested changes to permanent files
- 🔄 Reset to defaults anytime

#### Verification & Export Capabilities
- 🧾 **Conversation Verification**: Review chat exchanges and export results
- 🔍 **Enhanced Verification**: Manual input and file upload for batch testing
- 📊 **Multiple Export Formats**: CSV and JSON with comprehensive metadata
- 📈 **Analytics**: Detailed statistics and performance metrics

### 🧪 Comprehensive Testing System

#### 65+ Test Suite
- ✅ All tests passing (65/65)
- 🔬 Property-based testing with Hypothesis
- 🎯 9 correctness properties validated
- 📊 Complete coverage of all scenarios
- 🚀 Automated test organization and execution

---

## 🛠️ Technology Stack

- **Backend:** Python 3.14+
- **AI Models:** Google Gemini 2.5 Flash, Anthropic Claude 3.5 Sonnet
- **UI Framework:** Gradio 6.0.2
- **Testing:** Pytest + Hypothesis (property-based testing)
- **Storage:** JSON-based with automatic validation
- **Architecture:** Modular, scalable, and maintainable

---

## � Implementation Status

### ✅ Core Medical Assistant (v2.2)
- ✅ Background spiritual monitoring with **enhanced classification logic**
- ✅ **Improved three-tier classification system** (GREEN/YELLOW/RED) based on medical feedback
- ✅ **Fixed critical classification bugs** (JSON parsing, specific case handling)
- ✅ **Medical Brain Compatible Summary** as primary provider handoff format
- ✅ Gentle triage questioning
- ✅ Consent-based referral process
- ✅ **Streamlined provider summary generation** (single format)
- ✅ **Enhanced RED flag definition** (broader than crisis-only)
- ✅ **Explicit RED indicators** for consistent classification
- ✅ Patient medical context integration in messages
- ✅ Multiple AI model support (6 distinct agents)

### ✅ Prompt Optimization System (v1.1)
- ✅ Centralized prompt management with PromptController
- ✅ Session-level prompt overrides with isolation
- ✅ Enhanced Edit Prompts UI with validation
- ✅ Shared component architecture (indicators, rules, templates)
- ✅ Promote to File workflow with automatic backups
- ✅ Real-time validation and syntax checking
- ✅ Spiritual Care Message prompt editing support

### ✅ Testing & Quality Assurance (v2.2)
- ✅ 65+ comprehensive tests (all passing)
- ✅ **Enhanced classification accuracy** based on medical professional feedback
- ✅ **Critical bug fixes validated** (JSON parsing, classification logic)
- ✅ Property-based testing with 9 correctness properties
- ✅ Organized test structure with clear categorization
- ✅ Automated test execution and reporting
- ✅ Complete integration and end-to-end testing
- ✅ **Medical professional review integration** with verified conversation examples

### ✅ Enhanced User Experience
- ✅ Comprehensive Help documentation
- ✅ Patient profile management
- ✅ Conversation verification and export
- ✅ Enhanced verification with file upload
- ✅ Real-time model and prompt configuration

---

## 🧪 Testing

### Run All Tests
```bash
python run_tests.py
```

**Current Status:** ✅ 65/65 tests passing

### Test Categories
```bash
# Prompt Optimization Tests
python -m pytest tests/prompt_optimization/ -v

# Integration Tests  
python -m pytest tests/integration/ -v

# Unit Tests
python -m pytest tests/unit/ -v

# Verification Tests
python -m pytest tests/verification/ -v

# Chaplain Feedback Tests
python -m pytest tests/chaplain_feedback/ -v
```

### Property-Based Testing
The system includes 9 correctness properties validated through property-based testing:
1. **Component Consistency Enforcement**
2. **Scenario-Targeted Question Generation**
3. **Structured Feedback Data Capture**
4. **Consent-Based Language Compliance**
5. **Shared Component Update Propagation**
6. **Context-Aware Classification Logic**
7. **Complete Provider Summary Generation**
8. **Comprehensive Performance Monitoring**
9. **Session-Level Prompt Override Preservation**

---

## 🔒 Security & Privacy

- ❌ **No PHI Storage**: Protected Health Information is not stored
- 🔐 **Secure API Keys**: Stored in .env file (not in version control)
- 🛡️ **Conservative Classification**: Errs on the side of caution
- 📝 **Audit Logging**: All interactions logged for review
- 🤝 **Consent-Based**: Referrals only with explicit patient consent
- 🔒 **Session Isolation**: User sessions are completely isolated

---

## 📚 Documentation

### Core Documentation
- `PROMPT_OPTIMIZATION_IMPLEMENTATION_REPORT.md` — Comprehensive implementation details
- `PROJECT_STRUCTURE.md` — Detailed project organization
- `docs/Spiritual Distress Testing Tool.md` — Customer specification
- `docs/Spiritual Distress Definition, Defining Characteristics, and Descriptions.md` — Clinical reference
- **`review/README.md`** — 🆕 Medical professional feedback and classification improvements (Ukrainian)
- **`review/Or_2.txt`** — 🆕 Medical professional recommendations that guided v2.2 improvements

### User Guides
- **Help Tab** — Built-in comprehensive user guide
- **Interface Documentation** — Embedded in each tab
- **Testing Guides** — Step-by-step verification workflows

---

## 🚀 Getting Started

### Prerequisites
- Python 3.14+
- API keys for Gemini and/or Claude
- Virtual environment (recommended)

### Installation
1. **Clone and Setup:**
```bash
git clone <repository>
cd <project-directory>
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

2. **Configure API Keys:**
```bash
cp .env.example .env
# Edit .env with your API keys
```

3. **Run Tests (Optional):**
```bash
python run_tests.py
```

4. **Start Application:**
```bash
python src/interface/gradio_app.py
```

5. **Access Interface:**
Open http://localhost:7860 in your browser

---

## 📞 Support & Troubleshooting

### Common Issues
1. **Check Logs:**
```bash
tail -f ai_interactions.log
```

2. **Verify Tests:**
```bash
python run_tests.py
```

3. **Reset Configuration:**
- Use "Reset to Defaults" in Edit Prompts tab
- Clear browser cache if needed

### Documentation Resources
- **Help Tab**: Comprehensive user guide in the application
- **Implementation Report**: `PROMPT_OPTIMIZATION_IMPLEMENTATION_REPORT.md`
- **Project Structure**: `PROJECT_STRUCTURE.md`

---

## 🎉 Ready for Production

The Medical Assistant with Spiritual Support system is **fully functional and production-ready** with:

- ✅ **Complete Implementation**: All requirements satisfied
- ✅ **Comprehensive Testing**: 65+ tests with 100% pass rate
- ✅ **Advanced Features**: Prompt optimization, session management, verification workflows
- ✅ **User-Friendly Interface**: Intuitive design with built-in help
- ✅ **Robust Architecture**: Scalable, maintainable, and secure
- ✅ **Quality Assurance**: Property-based testing and continuous validation

---

**Version:** 2.3  
**Last Updated:** January 7, 2026  
**Status:** ✅ Production Ready with Enhanced Provider Summary  
**Test Coverage:** 65/65 tests passing

### 🆕 Latest Updates (v2.3) - January 2026

#### Provider Summary Improvements
Based on medical professional feedback from `review/Or_3.txt`:

**✅ Enhanced Provider Summary Content:**
- **Removed phone numbers** from provider summaries (team has direct access in application)
- **Include all patient inputs** throughout interaction instead of just final message
- **Comprehensive conversation context** for better spiritual care team understanding

**✅ Automatic Summary Generation:**
- **Instant provider summary** when RED flag triggers and patient consents
- **No manual intervention required** - summary appears automatically in Provider Summary panel
- **Immediate review capability** for spiritual care team to comment on accuracy

**✅ Improved User Experience:**
- **Fixed HTML badge rendering** issues in provider summary status
- **Clean text formatting** with proper Markdown compatibility
- **Enhanced debug logging** for better troubleshooting

#### Previous Updates (v2.2) - January 2026

#### Critical Classification Improvements
Based on medical professional feedback from `review/Or_2.txt`:

**✅ Fixed Critical JSON Parsing Bug:**
- **Issue:** LLM returned `"classification"` field but parser expected `"state"` field
- **Solution:** Updated parser to handle both field formats
- **Impact:** Eliminated classification errors due to parsing failures

**✅ Enhanced RED Flag Definition:**
- **Previous:** Limited to "severe distress or crisis"
- **Current:** Broader definition includes "active spiritual distress"
- **Benefit:** More accurate detection of patients needing spiritual care

**✅ Added Explicit RED Indicators:**
- Complex grief → Always RED
- Loss of loved one (with distress) → Always RED  
- Doubt about meaning of life → Always RED
- Doubt about meaning of suffering → Always RED
- Doubt about personal dignity → Always RED

**✅ Improved Specific Case Handling:**
- **"I am fine"** now correctly classified as 🟢 GREEN (was incorrectly YELLOW)
- **"I feel sad"** now correctly classified as 🟡 YELLOW (simple sadness without context)
- **"Life has no meaning"** now correctly classified as 🔴 RED (explicit meaning loss)

#### Medical Brain Integration Optimization
**✅ Streamlined Provider Summary Format:**
- Removed redundant "Message for Spiritual Care Team" functionality
- **Medical Brain Compatible Summary** is now the primary and only format
- Single coherent paragraph format for seamless Medical Brain integration
- Optimized prompt structure for Medical Brain compatibility

#### Documentation and Review
**✅ Comprehensive Review Documentation:**
- Added detailed `review/README.md` (Ukrainian) with medical professional feedback
- Analyzed verified conversation examples with outcomes
- Documented all implemented improvements and validation results

#### Validation Results
```
✅ "I am fine" → 🟢 GREEN (confidence: 1.0)
✅ "I feel sad" → 🟡 YELLOW (confidence: 0.9)  
✅ "Life has no meaning anymore" → 🔴 RED (confidence: 1.0)
```

All test cases now pass according to medical professional recommendations.

---

## 📁 Project Organization

### Test Files
- **`tests/`** - Automated test suite (65+ tests)
- **`manual_tests/`** - Manual validation scripts with detailed README

### Documentation
- **`docs/reports/`** - Implementation reports and feature documentation
- **`README.md`** - Main project documentation (this file)
- **`PROJECT_STRUCTURE.md`** - Detailed architecture overview