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:

{
    "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:

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

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

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

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

   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