# CANIFAGraph: Kiến trúc Điều phối & Làm giàu Dữ liệu (Version 2.0)

---

## 1. Tổng quan (The 3-Agent Architecture)

`CANIFAGraph` là bộ não trung tâm sử dụng **LangGraph** để điều phối các tác vụ AI. Kiến trúc này được thiết kế theo mô hình **Pipeline Deterministic**, giúp chatbot phản hồi nhanh, chính xác và không bị lạc đề.

- **Mô hình**: `Classifier (Lightweight)` → `Tools (Logic)` → `Stylist (Heavyweight)`.
- **Ưu điểm**: Tách biệt rõ ràng giữa việc *hiểu ý định* và việc *viết câu trả lời*.

---

## 2. Sơ đồ Luồng xử lý & Enrichment

![Graph Architect Flow](data/33-graph-architect/graph_architect_flow.svg)

---

## 3. Các Node chính trong Graph

### 🟦 Node 1: Classifier (Bộ phân loại)
Đây là node đầu tiên, sử dụng model nhẹ (ví dụ Gemini Flash) để:
- Phân tích ý định khách hàng.
- Quyết định có cần dùng Tool hay không (`tool_name_used`).
- Quyết định có kết thúc sớm hay không (`early_exit` - dành cho câu chào hỏi/rác).

### 🟪 Node 2: Tools (Thực thi công cụ)
Node này chuyên biệt để chạy các công cụ mày đã viết (Store Search, Promotion, Knowledge...). Kết quả trả về từ Tool sẽ được đẩy vào context cho node tiếp theo.

### 🟩 Node 3: Stylist (Chuyên gia tư vấn)
Node "nặng ký" nhất, sử dụng model Pro để tổng hợp thông tin từ lịch sử chat + kết quả tool nhằm viết ra câu trả lời tự nhiên, đúng phong cách Canifa.

---

## 4. Lớp làm giàu dữ liệu (Product Enrichment)

Đây là bước **hậu xử lý (Post-processing)** nằm trong `chat()` method, diễn ra sau khi Graph kết thúc:

1. **Trích xuất SKU**: Hệ thống quét toàn bộ nội dung AI trả về và kết quả Tool để lấy danh sách mã sản phẩm (SKUs).
2. **Truy vấn StarRocks**: Sử dụng danh sách SKUs để lấy đầy đủ: Ảnh Thumbnail, Giá KM, Link Web, Bảng Size...
3. **Đóng gói JSON**: Đảm bảo Frontend nhận được một mảng `products` hoàn chỉnh để hiển thị Card sản phẩm đẹp mắt.

---

## 5. Quản lý Trạng thái (State & Persistence)

- **Redis Insight**: Mỗi lượt chat, `user_insight` (sở thích, giới tính, size khách) sẽ được cập nhật và lưu vào Redis.
- **Langfuse Tracing**: Toàn bộ luồng đi qua các node đều được track ID để phục vụ debug và đánh giá chất lượng.

---

> [!IMPORTANT]
> **Hiệu năng**: Việc tách `Classifier` giúp giảm latency đáng kể vì không phải chạy prompt "nặng" cho các câu hỏi đơn giản. Lớp `Enrichment` đảm bảo AI không bao giờ "bịa" ra giá hay ảnh sản phẩm (Zero Hallucination).
