HH/docs/BILINGUAL_AI_ANALYSIS.md

# Bilingual AI Analysis Implementation

## Overview

The AI analysis system now generates all text fields in both English and Arabic, providing better support for bilingual users in Saudi Arabia.

## Changes Made

### 1. AI Service (`apps/core/ai_service.py`)

**Updated AI Prompt:**
- Modified the `analyze_complaint` method to request bilingual output
- AI now generates all text fields in both English and Arabic
- System prompt emphasizes bilingual capabilities

**New Response Format:**
```json
{
    "title_en": "concise title in English summarizing the complaint (max 10 words)",
    "title_ar": "العنوان بالعربية",
    "short_description_en": "2-3 sentence summary in English of the complaint that captures the main issue and context",
    "short_description_ar": "ملخص من 2-3 جمل بالعربية",
    "severity": "low|medium|high|critical",
    "priority": "low|medium|high",
    "category": "exact category name from the list above",
    "subcategory": "exact subcategory name from the chosen category, or empty string if not applicable",
    "department": "exact department name from the hospital's departments, or empty string if not applicable",
    "suggested_action_en": "2-3 specific, actionable steps in English to address this complaint",
    "suggested_action_ar": "خطوات محددة وعمليه بالعربية",
    "reasoning_en": "Brief explanation in English of your classification (2-3 sentences)",
    "reasoning_ar": "شرح مختصر بالعربية"
}
```

### 2. Complaint Tasks (`apps/complaints/tasks.py`)

**Updated `analyze_complaint_with_ai` Task:**
- Stores bilingual AI results in complaint metadata
- Updates complaint title from AI's English version
- Creates bilingual timeline update messages
- Returns bilingual results

**Metadata Structure:**
```python
complaint.metadata['ai_analysis'] = {
    'title_en': 'English title',
    'title_ar': 'العنوان بالعربية',
    'short_description_en': 'English summary',
    'short_description_ar': 'ملخص بالعربية',
    'suggested_action_en': 'English action steps',
    'suggested_action_ar': 'خطوات العمل بالعربية',
    'reasoning_en': 'English explanation',
    'reasoning_ar': 'الشرح بالعربية',
    'analyzed_at': 'ISO timestamp',
    'old_severity': 'previous severity',
    'old_priority': 'previous priority',
    'old_category': 'previous category name',
    'old_category_id': 'previous category ID',
    'old_department': 'previous department name',
    'old_department_id': 'previous department ID'
}
```

**Timeline Update Example:**
```
AI analysis complete: Severity=high, Priority=medium, Category=Quality of Care, Department=Nursing

اكتمل تحليل الذكاء الاصطناعي: الشدة=high, الأولوية=medium, الفئة=Quality of Care, القسم=Nursing
```

### 3. Complaint Model (`apps/complaints/models.py`)

**Added Bilingual Properties:**
- `title_en` - AI-generated title (English)
- `title_ar` - AI-generated title (Arabic)
- `short_description_en` - AI-generated short description (English)
- `short_description_ar` - AI-generated short description (Arabic)
- `suggested_action_en` - AI-generated suggested action (English)
- `suggested_action_ar` - AI-generated suggested action (Arabic)
- `reasoning_en` - AI-generated reasoning (English)
- `reasoning_ar` - AI-generated reasoning (Arabic)

**Backward Compatibility:**
- Existing properties `short_description` and `suggested_action` still work
- They now return the English versions (`short_description_en`, `suggested_action_en`)

## Usage Examples

### Accessing Bilingual AI Results in Code

```python
complaint = Complaint.objects.get(id=some_id)

# Get English version
title_en = complaint.title_en
summary_en = complaint.short_description_en
action_en = complaint.suggested_action_en

# Get Arabic version
title_ar = complaint.title_ar
summary_ar = complaint.short_description_ar
action_ar = complaint.suggested_action_ar

# Get reasoning
reasoning_en = complaint.reasoning_en
reasoning_ar = complaint.reasoning_ar
```

### Accessing Raw Metadata

```python
ai_analysis = complaint.metadata.get('ai_analysis', {})

if ai_analysis:
    title_en = ai_analysis.get('title_en', '')
    title_ar = ai_analysis.get('title_ar', '')
    # etc.
```

### Displaying in Templates

```html
<!-- English version -->
<h2>{{ complaint.title_en }}</h2>
<p>{{ complaint.short_description_en }}</p>

<!-- Arabic version (with RTL) -->
<h2 dir="rtl">{{ complaint.title_ar }}</h2>
<p dir="rtl">{{ complaint.short_description_ar }}</p>

<!-- Language-aware display -->
{% if LANGUAGE_CODE == 'ar' %}
  <h2 dir="rtl">{{ complaint.title_ar }}</h2>
{% else %}
  <h2>{{ complaint.title_en }}</h2>
{% endif %}
```

## Fields That Are Bilingual

- ✅ Title
- ✅ Short description
- ✅ Suggested action
- ✅ Reasoning

## Fields That Remain Single Values

- Severity (enum code: low/medium/high/critical)
- Priority (enum code: low/medium/high)
- Category (reference to existing category)
- Subcategory (reference to existing subcategory)
- Department (reference to existing department)

## Migration Notes

- No database migration required (metadata is JSONField)
- Existing complaints will have empty `_en` and `_ar` fields until re-analyzed
- Backward compatible - existing code using `short_description` and `suggested_action` will continue to work

## Testing

To test bilingual AI analysis:

1. Create a new complaint via the public form
2. Wait for AI analysis (async Celery task)
3. Check the complaint metadata:
   ```python
   complaint = Complaint.objects.latest('created_at')
   print(complaint.metadata['ai_analysis'])
   ```

Expected output should include both `_en` and `_ar` versions of all text fields.

## Future Enhancements

Possible future improvements:
1. Add language preference per user
2. Auto-display based on user's language setting
3. Add translation for existing complaints
4. Support for more languages if needed