marwan/HH

ismail 1f9d8a7198 update on the complaint sla and staff hierarchy

2026-01-15 14:32:49 +03:00

11 KiB

Raw Permalink Blame History

AI-PX Action Integration - Implementation Complete

Overview

This document describes the integration between the Complaint AI Analysis system and the PX Action Center. When a complaint is created, AI analysis can now automatically create a PX Action if the hospital has this feature enabled.

Implementation Date

January 14, 2026

Changes Made

1. Modified `apps/complaints/tasks.py`

Enhanced `analyze_complaint_with_ai` Task

The AI analysis task now includes automatic PX Action creation:

New Functionality:

Checks if hospital has auto_create_action_on_complaint enabled in metadata
If enabled, uses AIService.create_px_action_from_complaint() to generate action data
Creates PX Action object with AI-generated title, description, category, priority, and severity
Links action to complaint via ContentType
Creates PX Action Log entry for audit trail
Creates Complaint Update to notify about auto-created action
Logs audit event
Returns px_action_id and px_action_auto_created in task result

Key Code Section:

# Auto-create PX Action if enabled
action_id = None
try:
    # Check if hospital has auto-create enabled
    hospital_metadata = getattr(complaint.hospital, 'metadata', None) or {}
    auto_create_action = hospital_metadata.get('auto_create_action_on_complaint', False)

    if auto_create_action:
        logger.info(f"Auto-creating PX Action for complaint {complaint_id}")

        # Generate PX Action data using AI
        action_data = AIService.create_px_action_from_complaint(complaint)

        # Create PX Action object
        from apps.px_action_center.models import PXAction, PXActionLog
        from django.contrib.contenttypes.models import ContentType

        complaint_ct = ContentType.objects.get_for_model(Complaint)

        action = PXAction.objects.create(
            source_type='complaint',
            content_type=complaint_ct,
            object_id=complaint.id,
            title=action_data['title'],
            description=action_data['description'],
            hospital=complaint.hospital,
            department=complaint.department,
            category=action_data['category'],
            priority=action_data['priority'],
            severity=action_data['severity'],
            status='open',
            metadata={
                'source_complaint_id': str(complaint.id),
                'source_complaint_title': complaint.title,
                'ai_generated': True,
                'auto_created': True,
                'ai_reasoning': action_data.get('reasoning', '')
            }
        )

        action_id = str(action.id)
        
        # Create action log, complaint update, and audit log...
        
except Exception as e:
    logger.error(f"Error auto-creating PX Action: {str(e)}", exc_info=True)
    action_id = None

# Return with action_id
return {
    # ... other fields ...
    'px_action_id': action_id,
    'px_action_auto_created': action_id is not None
}

2. Modified `apps/complaints/views.py`

Updated `perform_create` Method

Changed from a TODO comment to actual AI analysis trigger:

Before:

# TODO: Optionally create PX Action (Phase 6)
# from apps.complaints.tasks import create_action_from_complaint
# create_action_from_complaint.delay(str(complaint.id))

After:

# Trigger AI analysis (includes PX Action auto-creation if enabled)
from apps.complaints.tasks import analyze_complaint_with_ai
analyze_complaint_with_ai.delay(str(complaint.id))

This ensures that every new complaint triggers AI analysis, which includes:

Complaint classification (severity, priority, category)
Department assignment
Staff extraction and matching
Emotion analysis
PX Action auto-creation (if enabled)

How It Works

Automatic PX Action Creation Flow

Complaint Created → User creates complaint via API/UI
AI Analysis Triggered → analyze_complaint_with_ai task runs asynchronously
Hospital Config Check → System checks hospital.metadata.auto_create_action_on_complaint
AI Generates Action Data → AIService.create_px_action_from_complaint() generates:
- Action title (AI-generated, concise summary)
- Action description (AI-generated, detailed explanation)
- Category (mapped from complaint category)
- Priority (inherited from complaint)
- Severity (inherited from complaint)
PX Action Created → New PXAction object created with:
- Link to complaint via ContentType
- AI-generated metadata
- Initial log entry
Notification Added → Complaint update created to inform about auto-created action
Audit Logged → Event logged for compliance and tracking

Manual PX Action Creation

For cases where auto-create is disabled or PX Admin wants to create action manually:

Endpoint: POST /api/complaints/{id}/create_action_from_ai/

This endpoint:

Uses AI service to generate action data
Allows PX Admin to optionally assign a user
Creates PX Action with full audit trail
Works even if hospital has auto-create disabled

Configuration

Enabling Auto-Creation

To enable automatic PX Action creation for a hospital:

hospital.metadata = {
    'auto_create_action_on_complaint': True
}
hospital.save()

Disabling Auto-Creation

hospital.metadata = {
    'auto_create_action_on_complaint': False  # or omit the key
}
hospital.save()

Testing

Test Script

A comprehensive test script has been created: test_ai_px_action_integration.py

Test Coverage:

Creates test complaint
Runs AI analysis task
Verifies complaint updates (severity, priority, category, department)
Checks if PX Action was created (if enabled)
Validates action-complaint linkage
Verifies action metadata (ai_generated, auto_created flags)
Explains manual action creation option

Running the Test:

python test_ai_px_action_integration.py

API Response Changes

`analyze_complaint_with_ai` Task Return Value

New Fields Added:

px_action_id: UUID of created PX Action (or null if not created)
px_action_auto_created: Boolean indicating if action was auto-created

Example Response:

{
  "status": "success",
  "complaint_id": "12345678-1234-1234-1234-123456789abc",
  "severity": "high",
  "priority": "high",
  "category": "service_quality",
  "department": "Customer Service",
  "title_en": "Staff Behavior Issue - Rude Receptionist",
  "title_ar": "مشكلة في سلوك الموظف - موظف استقبال غير مهذب",
  "short_description_en": "Patient reported rude behavior from reception staff",
  "short_description_ar": "أبلغ المريض عن سلوك غير مهذب من موظفي الاستقبال",
  "suggested_action_en": "Conduct staff training on customer service",
  "suggested_action_ar": "إجراء تدريب للموظفين على خدمة العملاء",
  "reasoning_en": "Complaint describes multiple instances of unprofessional behavior",
  "reasoning_ar": "الشكوى تصف حالات متعددة من السلوك غير المهني",
  "emotion": "frustrated",
  "emotion_intensity": 0.8,
  "emotion_confidence": 0.9,
  "old_severity": "medium",
  "old_priority": "medium",
  "px_action_id": "87654321-4321-4321-4321-cba987654321",
  "px_action_auto_created": true
}

Benefits

1. Automation

Reduces manual work for PX Admins
Ensures consistent action creation based on AI analysis
Eliminates duplicate effort (complaint → manual action creation)

2. AI-Powered

Actions generated using AI analysis of complaint content
Intelligent category mapping
Context-aware title and description generation

3. Traceability

Clear linkage between complaint and action
Full audit trail of auto-creation
Metadata tracks AI-generated content

4. Flexibility

Hospital-level configuration (enable/disable)
Manual creation option available via API
PX Admins can override or supplement AI-generated actions

5. Consistency

Same AI service used for both manual and auto-creation
Unified action generation logic
Consistent metadata and logging

AI Service: apps/core/ai_service.py - create_px_action_from_complaint() method
PX Action Model: apps/px_action_center/models.py - PXAction model
Complaint Tasks: apps/complaints/tasks.py - analyze_complaint_with_ai() task
Category Mapping: apps/complaints/views.py - map_complaint_category_to_action_category() function

Migration Notes

Database Changes

No database migrations required. The integration uses:

Existing Complaint model (metadata field for config)
Existing PXAction model (no schema changes)
Existing ContentType framework for linking

Backward Compatibility

Fully backward compatible
Hospitals without config key behave as before (no auto-creation)
Existing API endpoints unchanged
Task return value only extended, not modified

Troubleshooting

PX Action Not Created

Check:

Hospital metadata has auto_create_action_on_complaint: True
Celery worker is running (task execution)
AI service is accessible and responding
Complaint has valid hospital, patient, and category

Debug:

# Check hospital config
hospital = complaint.hospital
print(hospital.metadata.get('auto_create_action_on_complaint'))

# Check task result
result = analyze_complaint_with_ai(str(complaint.id))
print(result.get('px_action_id'))
print(result.get('px_action_auto_created'))

Action Created But Not Linked