Chatbot Stage Classification API

API dùng để phân loại stage và customer case của user/trader dựa trên phần mô tả đầu vào. Hệ thống sử dụng AgentClassifier và AgentCaseClassifier để so khớp user_info với bộ tiêu chí trong data/stage_demo.json hoặc data/case.json, sau đó trả về nhóm phù hợp nhất kèm phần giải thích.

Các Stage Hiện Có

• Hunter: user mới bước vào thị trường, dễ FOMO, muốn kiếm lợi nhuận nhanh và thường tìm shortcut.
• Survivor: user đã trade một thời gian nhưng chưa ổn định, mệt mỏi, mất niềm tin và muốn tìm sự ổn định.
• Thinker: user bắt đầu nghi ngờ hệ thống cũ, quan tâm cấu trúc thị trường và thường đặt câu hỏi sâu hơn.
• Seeker: user muốn tìm sự kết nối thật, chiều sâu và ít tập trung vào lợi nhuận ngắn hạn.

Customer Case Hiện Có

Danh sách customer case được lưu trong data/case.json, ví dụ:

• Người tò mò
• Trade thua lâu năm
• Người hỏi học phí ngay
• Người giàu / doanh nhân
• Người nghiện tín hiệu
• Người đồng tần số
• Trader rất giỏi / ego cao
• Người mất niềm tin
• Trader cô độc
• Người muốn học thật
• Người muốn kiếm tiền nhanh
• Người đã sẵn sàng
• Người rất bận
• Người theo dõi âm thầm

Yêu Cầu

• Python 3.10+
• API key và base URL cho LLM tương thích với OpenAI SDK

Khởi Chạy Từ Đầu

1. Tạo và kích hoạt môi trường Python:

python3 -m venv .venv
source .venv/bin/activate

Nếu dùng conda:

conda create -n chat python=3.10 -y
conda activate chat

2. Cài đặt dependencies:

python -m pip install -r requirements.txt

3. Tạo file .env ở thư mục gốc của project:

cp .env.example .env

Sau đó mở .env và điền thông tin LLM của bạn:

MODEL_NAME=your-model-name
BASE_URL=https://your-llm-provider/v1
API_KEY=your-api-key
TEMPERATURE=0.5
MAX_TOKENS=4096
API_HOST=0.0.0.0
API_PORT=8001
API_RELOAD=true

4. Chạy API:

python app.py

Mặc định API chạy tại:

http://127.0.0.1:8001

Swagger docs:

http://127.0.0.1:8001/docs

Cấu Hình Server

Có thể đổi host, port hoặc chế độ reload bằng biến môi trường:

API_HOST=127.0.0.1 API_PORT=8080 API_RELOAD=false python app.py

Nếu gặp lỗi Address already in use, nghĩa là port đang bị một tiến trình khác sử dụng. Hãy đổi API_PORT hoặc tắt server cũ.

API Endpoints

Health Check

GET /health

Response:

{
  "status": "ok"
}

Phân Loại Stage User

POST /api/v1/stage/classify

Request body:

{
  "user_info": "Tôi trade được 3 năm, đã thử nhiều chiến lược nhưng vẫn chưa ổn định. Gần đây tôi thấy rất mệt, mất niềm tin và không biết mình sai ở đâu."
}

Response:

{
  "status": 1,
  "type": "Survivor",
  "evidence": "Giải thích bằng tiếng Việt dựa trên user_info."
}

Ý nghĩa status:

• 1: phân loại được rõ ràng vào một stage.
• 0: user không phù hợp với stage nào.
• 2: thiếu thông tin để đưa ra quyết định.

Phân Loại Customer Case

POST /api/v1/case/classify

Request body:

{
  "user_info": "Tôi đã đi qua nhiều room, khóa học và tín hiệu nhưng vẫn thất vọng. Bây giờ tôi chỉ muốn tìm một nơi thành thật và rõ ràng hơn."
}

Response:

{
  "status": 1,
  "case": "Người mất niềm tin",
  "evidence": "Giải thích bằng tiếng Việt dựa trên user_info."
}

Ý nghĩa status:

• 1: phân loại được rõ ràng vào một customer case.
• 0: user không phù hợp với case nào.
• 2: thiếu thông tin để đưa ra quyết định.

Gọi Thử Bằng Curl

Phân loại stage:

curl -X POST "http://127.0.0.1:8001/api/v1/stage/classify" \
  -H "Content-Type: application/json" \
  -d '{
    "user_info": "Tôi đã trade được 100 lệnh và thấy khả năng trade của mình khá tốt. Hiện tại tôi muốn tìm kiếm ai đó để trò chuyện và sharing nhiều hơn."
  }'

Phân loại customer case:

curl -X POST "http://127.0.0.1:8001/api/v1/case/classify" \
  -H "Content-Type: application/json" \
  -d '{
    "user_info": "Tôi đã đi qua nhiều room, khóa học và tín hiệu nhưng vẫn thất vọng. Bây giờ tôi chỉ muốn tìm một nơi thành thật và rõ ràng hơn."
  }'

Cấu Trúc Chính

app.py                         # Entry point để chạy API
src/api/v1.py                  # FastAPI app và endpoints
src/core/node/agent_loader.py  # AgentClassifier
src/core/node/node_config.py   # Cấu hình LLM từ .env
data/stage_demo.json           # Tiêu chí phân loại stage
data/case.json                 # Tiêu chí phân loại customer case
test/test_flow.py              # Test nhanh AgentClassifier
test/test_case.py              # Test nhanh AgentCaseClassifier

Kiểm Tra Nhanh AgentClassifier

python test/test_flow.py

Kiểm Tra Nhanh AgentCaseClassifier

python test/test_case.py