{
    "title": "Prompt System & LLM Factory",
    "description": "Hướng dẫn cách quản lý System Prompt và các Tool Prompt linh hoạt mà không cần khởi động lại server, đi kèm kiến trúc LLM Factory.",
    "diagram": "diagrams/prompt-management.svg",
    "sections": [
        {
            "title": "1. Tổng quan (Overview)",
            "type": "text",
            "content": "Prompt Engineering là linh hồn của AI Stylist. Để giúp Admin (Product Owner) có thể dễ dàng tuning prompt theo từng chiến dịch (Ví dụ: Mùa Đông thì push mạnh Áo Khoác), hệ thống tách bạch toàn bộ Prompt ra khỏi code. Các file Prompt được lưu dưới dạng <code>.txt</code> tại <code>backend/agent/</code> và có API để Hot-reload mà không phải restart Uvicorn."
        },
        {
            "title": "2. Kiến trúc & Luồng dữ liệu (Data Flow)",
            "type": "text",
            "content": "Quy trình update prompt diễn ra như sau:<br><br><b>1. UI Edit:</b> Admin sửa prompt trên giao diện Dashboard.<br><b>2. File Override:</b> API <code>POST /api/agent/system-prompt</code> sẽ ghi đè nội dung mới vào file <code>.txt</code>.<br><b>3. MD5 Cache Invalidation:</b> LLM Chain không đọc file từ ổ cứng liên tục (để tối ưu I/O). Thay vào đó, mỗi khi hàm <code>reset_chain_cache()</code> được gọi, nó sẽ hash MD5 file prompt. Nếu hash thay đổi, hệ thống sẽ xóa instance LLM cũ khỏi RAM và re-compile lại LangChain.<br><b>4. LLM Factory:</b> File <code>llm_factory.py</code> chịu trách nhiệm nạp Prompt, đọc API keys, chọn Model (GPT-4o, Gemini Flash-Lite) và tiêm các tham số động (như <code>{current_date}</code>) vào ngữ cảnh."
        },
        {
            "title": "3. Phân loại Prompt",
            "type": "text",
            "content": "<b>- System Prompt:</b> Định nghĩa Persona (Chuyên gia thời trang, Lịch sự, Nhiệt tình). Cung cấp luật cấm (Không chê bai ngoại hình khách hàng).<br><b>- Tool Prompts:</b> Hướng dẫn AI cách dùng Tool (VD: <i>\"Chỉ dùng API kiểm tra tồn kho khi user hỏi size cụ thể\"</i>).<br><b>- User Insight Template:</b> Prompt nội bộ dùng để trích xuất thông tin khách hàng từ lịch sử chat (nhằm lưu vào DB Profiling)."
        },
        {
            "title": "4. API Quản lý Prompt",
            "type": "api",
            "endpoints": [
                { "method": "GET", "path": "/api/agent/system-prompt", "description": "Lấy nội dung System Prompt hiện tại để view trên UI." },
                { "method": "POST", "path": "/api/agent/system-prompt", "description": "Cập nhật System Prompt và trigger làm mới cache." },
                { "method": "GET", "path": "/api/agent/tool-prompts", "description": "Liệt kê danh sách các tool prompt có sẵn." },
                { "method": "POST", "path": "/api/agent/tool-prompts/{filename}", "description": "Cập nhật nội dung một tool prompt cụ thể." }
            ]
        },
        {
            "title": "5. Code Snippet Thực Tế (Dynamic Parameters)",
            "type": "code",
            "language": "python",
            "code": "from datetime import datetime\nfrom langchain.prompts import ChatPromptTemplate\n\ndef get_compiled_prompt(raw_prompt_text: str):\n    # Tiêm các biến thời gian thực vào Prompt để AI nhận thức được thời gian\n    today_str = datetime.now().strftime(\"%A, %Y-%m-%d\")\n    season = get_current_season() # Xử lý logic mùa (Xuân, Hè...)\n    \n    injected_prompt = raw_prompt_text.replace(\n        \"{context_block}\",\n        f\"Hôm nay là {today_str}. Hiện tại đang là bộ sưu tập {season}.\"\n    )\n    return ChatPromptTemplate.from_messages([\n        (\"system\", injected_prompt),\n        (\"placeholder\", \"{chat_history}\"),\n        (\"human\", \"{input}\"),\n        (\"placeholder\", \"{agent_scratchpad}\"),\n    ])"
        },
        {
            "title": "6. Troubleshooting & Gotchas",
            "type": "text",
            "content": "<b>🚫 Lỗi Prompts Mất Cập Nhật (Stale Cache):</b><br>Do LangChain cache đối tượng <code>Runnable</code>, nếu sửa file TXT bằng tay (nano/vim) trên server mà không call API, hệ thống sẽ KHÔNG biết prompt bị đổi để nạp lại. Luôn sửa qua API hoặc restart server.<br><br><b>🚫 Lỗi Phá Vỡ JSON Schema ở Tool Prompt:</b><br>Nếu Tool Prompt yêu cầu AI trả về JSON mà Admin lỡ tay xóa câu <i>\"Must output strictly valid JSON\"</i>, AI có thể sinh ra text lộn xộn khiến pydantic parser crash. Khi edit prompt, phải giữ nguyên các chỉ thị kỹ thuật (Technical constraints)."
        }
    ]
}
