260612

README.md

@@ -1,14 +1,14 @@
-# YAN Ollama Stack
+# RAG - Agent
 
-Nền tảng AI cục bộ vận hành hoàn toàn **offline** — không cần cloud, không cần API key bên ngoài. Toàn bộ pipeline từ LLM inference, vector search, graph enrichment, RAG, đến SDLC automation chạy trong một cụm Docker Compose trên máy local hoặc private server.
+RAG - Agent là nền tảng AI cục bộ vận hành hoàn toàn **offline** — không cần cloud, không cần API key bên ngoài. Toàn bộ pipeline từ LLM inference, vector search, graph enrichment, RAG, đến SDLC automation chạy trong một cụm Docker Compose trên máy local hoặc private server.
 
 **Thành phần cốt lõi:** Ollama · Qdrant · Neo4j · RAG API · Agent API · Open WebUI · Watchtower · Deunhealth
 
 ---
 
 ## Mục lục
 
-1. [Tổng quan stack](#1-tổng-quan-stack)
+1. [Tổng quan RAG - Agent](#1-tổng-quan-rag---agent)
 2. [Kiến trúc hệ thống](#2-kiến-trúc-hệ-thống)
 3. [SDLC Workflow — 15 bước](#3-sdlc-workflow--15-bước)
 4. [Yêu cầu hệ thống](#4-yêu-cầu-hệ-thống)
@@ -29,7 +29,7 @@ Nền tảng AI cục bộ vận hành hoàn toàn **offline** — không cần
 
 ---
 
-## 1. Tổng quan stack
+## 1. Tổng quan RAG - Agent
 
 | Service | Image | Port (host) | Mục đích |
 |---|---|---|---|
@@ -211,9 +211,9 @@ Tắt tính năng: `CLARIFIER_REGEN_LOOPS=0` trong `.env`.
 ## 5. Cấu trúc thư mục
 
 ```
-Ollama-Stack/
+RAG - Agent/
 ├── .env                              # Nguồn cấu hình duy nhất (single source of truth)
-├── docker-compose.yml                # Định nghĩa toàn bộ stack
+├── docker-compose.yml                # Định nghĩa toàn bộ dịch vụ RAG - Agent
 │
 ├── data/
 │   ├── raw/                          # Tài liệu nguồn cho RAG
@@ -340,7 +340,7 @@ MAX_FILES_PER_ROLE=6
 CLARIFIER_REGEN_LOOPS=1
 ```
 
-### Bước 2 — Khởi động stack
+### Bước 2 — Khởi động RAG - Agent
 
 ```bash
 docker compose up -d
@@ -1387,7 +1387,7 @@ CLARIFIER_REGEN_LOOPS=0
 ### Khởi động & dừng
 
 ```bash
-# Khởi động toàn bộ stack
+# Khởi động toàn bộ RAG - Agent
 docker compose up -d
 
 # Dừng tất cả (giữ volumes)

agent-api/agents.py

@@ -302,7 +302,7 @@ class AgentConfig:
         name="Designer Agent — UI/UX Design",
         model=MODEL_DESIGNER,
         depends_on=["ba", "sa", "ta"],
-        rag_query_hint="UI flow, screen design, wireframe, user journey, component behavior, design system, form behavior, empty state, error state, color palette, typography, spacing, layout grid",
+        rag_query_hint="UI flow, screen design, wireframe, user journey, component behavior, design system, form behavior, empty state, error state, color palette, typography, spacing, layout grid, platform split web app mobile app, native mobile wireframe, iOS HIG, Material Design, safe area, bottom navigation bar, responsive breakpoints",
         system_prompt="""\
 You are the Lead UI/UX Designer Agent.
 Your output is the SINGLE SOURCE OF TRUTH for all frontend and mobile visual implementation.

agent-api/workflow.py

@@ -421,11 +421,12 @@ def _find_uncovered_tasks(tl_tasks: list[dict], file_infos: list[dict]) -> list[
 
 
 def _build_task_checklist(tl_tasks: list[dict], file_infos: list[dict]) -> str:
-    """Xây dựng bảng Markdown Task Completion Checklist để thêm vào cuối output engineer.
+    """Xây dựng bảng Markdown Task Completion Checklist để thêm vào output engineer.
 
-    Mỗi dòng đối chiếu một TL task với kết quả sinh code:
+    Mỗi dòng đối chiếu một TL task với kết quả sinh code (3 trạng thái):
     - ✅ Done: task được cover bởi ít nhất một file đã sinh.
-    - ⏳ Addressed in output: task chưa có file khớp nhưng đã được đề cập.
+    - ⏳ Partial: task chưa có file khớp nhưng đã được đề cập trong output.
+    - ❌ Deferred: task bị defer hoặc chưa được xử lý.
 
     Trả về chuỗi rỗng nếu tl_tasks trống (không có TL task board).
     """
@@ -456,7 +457,7 @@ def _build_task_checklist(tl_tasks: list[dict], file_infos: list[dict]) -> str:
             status      = "✅ Done"
             files_label = ", ".join(f"`{fn}`" for fn in matched_files[:2])
         else:
-            status      = "⏳ Addressed in output"
+            status      = "⏳ Partial"
             files_label = "—"
         task_display = (task_text[:60] + "…") if len(task_text) > 60 else task_text
         lines.append(f"| {tid} | {task_display} | {priority} | {status} | {files_label} |")
@@ -499,7 +500,6 @@ def _parse_clarifier_regen_list(clarifier_output: str) -> list[str]:
         section_text = section_text[:30 + stop.start()]
 
     seen: set[str] = set()
-    roles_ordered: list[str] = []
 
     for line in section_text.split("\n"):
         if "|" not in line:
@@ -948,7 +948,7 @@ def _generate_artifacts_multi_turn(
                 all_files.append(file_info)
 
     # Thêm bảng Task Completion Checklist vào cuối output để đối chiếu
-    # mọi TL task với file đã sinh — ✅ Done hoặc ⏳ Addressed in output.
+    # mọi TL task với file đã sinh — ✅ Done, ⏳ Partial, hoặc ❌ Deferred.
     if tl_tasks:
         parts.append(_build_task_checklist(tl_tasks, all_files))
 

docker-compose.yml

@@ -1,3 +1,5 @@
+name: rag-agent
+
 services:
   ollama:
     image: ollama/ollama:latest
@@ -72,7 +74,7 @@ services:
   rag-api:
     build:
       context: ./rag-api
-    image: ollama-stack_rag-api:latest
+    image: rag-agent_rag-api:latest
     container_name: rag-api
     labels:
       - "com.centurylinklabs.watchtower.enable=false"
@@ -118,7 +120,7 @@ services:
   agent-api:
     build:
       context: ./agent-api
-    image: ollama-stack_agent-api:latest
+    image: rag-agent_agent-api:latest
     container_name: agent-api
     labels:
       - "com.centurylinklabs.watchtower.enable=false"

rag-api/graph.py

@@ -1,5 +1,5 @@
 """
-graph.py — Lớp tích hợp Neo4j GraphRAG cho YAN RAG stack
+graph.py — Lớp tích hợp Neo4j GraphRAG cho RAG - Agent
 ==========================================================
 
 Mô tả
@@ -61,6 +61,10 @@
 
 
 def _require_env(name: str) -> str:
+    """Trả về giá trị biến môi trường *name*.
+
+    Raise RuntimeError nếu biến không tồn tại — dùng cho các biến cấu hình bắt buộc.
+    """
     value = os.environ.get(name)
     if value is None:
         raise RuntimeError(

rag-api/ingest.py

@@ -1,5 +1,5 @@
 """
-ingest.py — Pipeline nạp tài liệu vào Qdrant và Neo4j cho YAN RAG stack
+ingest.py — Pipeline nạp tài liệu vào Qdrant và Neo4j cho RAG - Agent
 =========================================================================
 
 Mô tả