README.md

---
title: PINE-AI Amdocs
colorFrom: blue
colorTo: purple
sdk: docker
app_file: Dockerfile
pinned: false
---

# PINE-AI MVP – Hugging Face Space (Docker)

## 1. Giới thiệu
PINE-AI là hệ thống AI hỗ trợ **logic sales**, **xử lý dữ liệu khách hàng & gói cước**, demo thông qua giao diện web.  
Phiên bản hiện tại có **3 tab chính**:  

1. **Desktop Call** – giao diện voicebot trên desktop.  
2. **Mobile Call** – giao diện voicebot trên điện thoại (logic backend giống desktop, chỉ khác UI).  
3. **Dashboard** – giao diện quản lý, theo dõi hiệu quả AI Agent, xem CSAT metrics & feedback khách hàng.

Repository này được cấu hình để chạy trực tiếp trên **Hugging Face Spaces (Docker)**. Ban giám khảo không cần cài Python hay Docker, chỉ cần mở link Space.

---

## 2. Công nghệ sử dụng
- **Backend:** Python, FastAPI  
- **Frontend:** HTML/JS serve trực tiếp từ backend  
- **AI / LLM:** Google GenAI + VNPT AI (qua API key)  
- **Deployment:** Hugging Face Spaces – Docker runtime  

---

## 3. Cấu trúc thư mục
├── Dockerfile
├── backend/
│ ├── ai/
│ │ ├── core/
│ │ │ ├── init.py
│ │ │ ├── analyze.py
│ │ │ └── logic_flow.py
│ │ ├── data/
│ │ │ ├── data_engine.py
│ │ │ ├── final_voice.scripts.json
│ │ │ ├── product_collection.json
│ │ │ └── test_customer.csv
│ │ ├── strategy/
│ │ │ ├── init.py
│ │ │ ├── strategy_competitor.py
│ │ │ ├── strategy_low_data.py
│ │ │ └── strategy_network.py
│ │ ├── main.py
│ │ ├── services.py
│ │ ├── vnpt_call_center.db
│ │ └── database.py
│ └── requirements.txt
├── frontend/
│ ├── base.html
│ ├── call_desktop.html
│ ├── call_mobile.html
│ └── dashboard.html
├── README.md
└── .gitignore

---

## 4. Environment Variables & Secrets
Toàn bộ **API key không commit vào repo**, được cấu hình trong:  

**Settings → Variables and secrets**  

### 4.1 Variables (không nhạy cảm)
| Name | Value |
|------|-------|
| GEMINI_MODEL_ID | gemini-3-flash-preview |
| VNPT_BASE_URL | https://api.idg.vnpt.vn |
| SMARTBOT_URL | https://assistant-stream.vnpt.vn/v1/conversation |

### 4.2 Secrets (API keys)
| Name | Mô tả |
|------|-------|
| GOOGLE_API_KEY | Google GenAI API key |
| VNPT_AI_API_KEY | VNPT AI API key |
| SMARTBOT_KEY | SMARTBOT_KEY |

> Secrets không hiển thị trong code hoặc logs.

---

## 5. Cách Space hoạt động
Khi Space được build:  

1. Hugging Face đọc `Dockerfile`  
2. Build Docker image  
3. Inject Variables & Secrets  
4. Chạy **FastAPI backend**  
5. Public web app qua URL Space  

Không cần thao tác thủ công.  

### 5.1 Truy cập các tab
- `/desktop` → Desktop Call UI  
- `/mobile` → Mobile Call UI  
- `/dashboard` → Dashboard quản lý  

Cả desktop & mobile **dùng chung backend**, chỉ khác giao diện frontend.

---

## 6. Truy cập demo
- Sau khi Space ở trạng thái Running, mở trực tiếp link Space.  
- Hệ thống sẽ load dữ liệu mẫu và sẵn sàng demo logic AI & sales flow.  
- Dashboard đọc dữ liệu từ `database.py` và (tuỳ deploy) từ `feedback_data.csv` để hiển thị CSAT metrics.

---

## 7. Troubleshooting
Nếu Space báo **Configuration error**:  
- Kiểm tra YAML header có đúng chưa (`sdk: docker`, `app_file: Dockerfile`)  
- Dockerfile có nằm ở ROOT không  
- Đợi 1–2 phút sau khi Restart Space  
- Tránh restart liên tục  

---

## 8. Ghi chú cho Ban giám khảo
MVP demo tập trung vào:  
- Kiến trúc AI Agent  
- Flow xử lý dữ liệu & tư vấn sales  
- Khả năng mở rộng & tích hợp thực tế  

---

## 9. Liên hệ
Mọi câu hỏi liên quan tới hệ thống **PINE-AI**, vui lòng liên hệ trực tiếp nhóm phát triển.