# User Simulator (MiroFish-Inspired Conversion Testing)

User Simulator tạo ra các chatbot ảo có tính cách và nhu cầu cụ thể (ví dụ: 'Bà mẹ bỉm sữa khó tính', 'Nam thanh niên săn sale', 'Khách hàng hỏi size cho con') dựa trên các **Customer Archetypes** có sẵn.
Các chatbot này sẽ tự động trò chuyện với hệ thống để:
- Tìm ra các trường hợp xử lý lỗi hoặc thiếu logic.
- Kiểm tra khả năng chốt sale của Agent.
- Đánh giá khả năng đáp ứng "conversion trigger" và tránh "drop trigger" của mỗi persona qua nhiều turn chat.

Hệ thống được thiết kế theo luồng tự động hoá toàn diện (Full Loop), kết nối với Agent thông qua API.

## Cấu trúc của CanifaPersona

Mỗi persona được generate qua LLM và lưu trữ theo cấu trúc `CanifaPersona` gồm:
- **Identity:** `name`, `age`, `gender`, `job`, `income_range`, `mbti`
- **Shopping context:** `shopping_for`, `budget`, `occasion`, `style_preference`
- **Chat behavior:** `chat_style`, `system_prompt`
- **Conversion criteria:** `conversion_trigger` (điều kiện mua), `drop_trigger` (điều kiện bỏ đi)

## Luồng hoạt động (Sequence Diagram)

Dưới đây là luồng tự động hoàn chỉnh (`run-simulation`) khi User Simulator giao tiếp với Chatbot:

```mermaid
sequenceDiagram
    participant Client
    participant SimulatorAPI as User Simulator API
    participant PersonaGen as Persona Generator
    participant ChatbotAPI as Chatbot Agent
    participant Evaluator as Evaluation Engine

    Client->>SimulatorAPI: POST /run-simulation
    SimulatorAPI->>PersonaGen: generate_personas(count, archetypes)
    PersonaGen-->>SimulatorAPI: List[CanifaPersona]
    
    loop For each Persona
        loop For N turns
            SimulatorAPI->>SimulatorAPI: _generate_persona_message(history)
            SimulatorAPI->>ChatbotAPI: POST /chat-dev (User message)
            ChatbotAPI-->>SimulatorAPI: Bot response
        end
        SimulatorAPI->>Evaluator: evaluate_conversation(persona, history)
        Evaluator-->>SimulatorAPI: Conversion Result (Success/Drop)
    end
    
    SimulatorAPI->>Evaluator: synthesize_results(all_results)
    Evaluator-->>SimulatorAPI: Cross-persona Report
    SimulatorAPI-->>Client: Final Simulation Report
```

## Quy trình Generate Persona
Mô-đun `persona_generator.py` sử dụng LLM (ví dụ `gpt-5.4-nano`) để tạo ra các persona một cách chân thực dựa trên danh sách `CANIFA_ARCHETYPES`. Quá trình tạo sử dụng `JSON_MODE` và có cơ chế retry kết hợp để đảm bảo cấu trúc dữ liệu JSON trả về luôn chuẩn xác.
