Update docs/agent-architecture.md

docs/agent-architecture.md

@@ -1,129 +1,84 @@
-# Agent Architecture
+# 에이전트 아키텍처
 
 ## 개요
 
-현재 메구밍 챗봇은 아래 흐름으로 동작합니다.
+프로젝트는 세 개의 UI 진입점과 하나의 공용 채팅 런타임으로 구성됩니다.
 
-1. `bootstrap.py`에서 환경변수와 런타임 데이터 경로를 준비
-2. `retrieval.py`에서 FAISS 인덱스와 메타데이터를 로드
-3. `agent.py`에서 Google ADK `LlmAgent`와 retrieval tool 구성
-4. `chat.py`에서 세션 실행, 스트리밍 응답, 대화 요약 관리
-5. `app_gradio.py`에서 PC/모바일 반응형 채팅 UI 제공
+1. `app.py`
+2. `app_gradio.py`
+3. `app_gradio_messenger.py`
+4. `megumin_agent/`
 
-## 파일별 역할
+각 UI 계층은 같은 채팅 서비스 헬퍼를 호출하고, 채팅 서비스는 검색, 에이전트 실행, 스트리밍, 세션 상태 관리를 담당합니다.
 
-### `megumin_agent/bootstrap.py`
-
-- `.env` 로드
-- 로컬 `adk-python/src` 경로 등록
-- Hugging Face dataset repo에서 데이터 파일 다운로드
-- 다운로드 실패 시 로컬 `data/processed`를 fallback으로 사용
+## 런타임 흐름
 
-다운로드 대상:
+1. `megumin_agent/bootstrap.py`가 환경 변수를 불러오고 로컬 또는 원격 데이터 파일을 준비합니다.
+2. `megumin_agent/retrieval.py`가 페르소나/사실 검색에 필요한 FAISS 인덱스와 메타데이터를 로드합니다.
+3. `megumin_agent/agent.py`가 ADK 에이전트를 구성하고 검색 기반 도구를 연결합니다.
+4. `megumin_agent/chat.py`가 채팅 서비스를 만들고 부분 응답 스트리밍과 세션 메모리를 관리합니다.
+5. UI 모듈이 화면을 렌더링하고 사용자 메시지를 `stream_chat()`으로 전달합니다.
 
-- `megumin_qa_dataset.json`
-- `megumin_questions.faiss`
-- `megumin_question_answer.faiss`
-- `megumin_questions_meta.json`
-- `namuwiki_qa.json`
-- `namuwiki_questions.faiss`
-- `namuwiki_question_answer.faiss`
-- `namuwiki_questions_meta.json`
+## 모듈별 설명
 
-### `megumin_agent/retrieval.py`
+### `megumin_agent/bootstrap.py`
 
-- QA JSON 레코드 로드
-- Gemini 임베딩 기반 FAISS 검색
-- question-only 인덱스와 question+answer 인덱스를 둘 다 조회
-- 두 검색 결과를 합쳐 점수가 높은 후보 top-k를 반환
+- `.env`를 로드합니다.
+- 필요 시 로컬 `adk-python/src` 경로를 준비합니다.
+- 가능하면 Hugging Face에서 데이터셋 자산을 내려받습니다.
+- 원격 자산을 사용할 수 없으면 로컬 처리 데이터로 폴백합니다.
 
-데이터 계층:
+### `megumin_agent/retrieval.py`
 
-- 페르소나 계층: `megumin_qa_dataset.json`
-- 사실 계층: `namuwiki_qa.json`
+- QA JSON 소스와 FAISS 인덱스를 로드합니다.
+- 페르소나형 데이터와 사실형 데이터에 대해 검색을 수행합니다.
+- 프롬프트 구성에 사용할 간결한 검색 결과를 반환합니다.
 
 ### `megumin_agent/agent.py`
 
-- 메구밍 페르소나 프롬프트 정의
-- `retrieve_megumin_examples` tool 정의
-- 페르소나용 top-2, 사실용 top-2를 각각 수집
-- ADK callback으로 대화 요약, 최근 질의, RAG 흔적을 state에 기록
-
-tool 반환 핵심:
-
-- `persona_matches`
-- `fact_matches`
-- `style_notes`
-- `fact_notes`
+- 메구밍 페르소나 프롬프트와 검색 도구를 정의합니다.
+- 페르소나 검색과 사실 검색을 하나의 에이전트 흐름으로 합칩니다.
+- 멀티턴 대화에 필요한 요약 상태를 관리합니다.
 
 ### `megumin_agent/chat.py`
 
-- `Runner`와 `InMemorySessionService` 생성
-- `stream_chat()`으로 ADK SSE 스트리밍 응답 생성
-- `chat_once()`는 스트리밍 결과를 모아 최종 문자열만 필요할 때 사용하는 래퍼
-- 최근 6턴을 남기고, 그 이전 대화는 `conversation_summary_map` key-value 구조로 압축
-- 압축된 요약은 짧은 문자열 형태의 `conversation_summary`로도 함께 렌더링
-
-요약 구조:
-
-- `user_topics`
-- `assistant_points`
+- 공용 러너와 메모리 기반 세션 서비스를 생성합니다.
+- `stream_chat()`으로 SSE 스타일의 부분 응답을 제공합니다.
+- 최근 턴 상태와 요약 정보를 유지해 후속 대화를 지원합니다.
 
 ### `app_gradio.py`
 
-- PC용 3패널 레이아웃 제공
-- 왼쪽: 메구밍 프로필과 예시 질문
-- 가운데: 채팅 패널
-- 오른쪽: 메구밍 비주얼 패널
-- 첫 접속 시 기본 인삿말을 assistant 메시지로 미리 표시
-- `create_chat_services()`는 import 시점이 아니라 첫 질문 시점에 lazy init
-- 첫 질문 전에는 `서비스 준비 중...`, 이후 응답 생성 중에는 `답변 생성 중...` 상태 표시
-- 작은 규칙 기반 상태 배지를 추가해 메구밍의 현재 분위기를 표시
-- ADK의 SSE partial event를 받아 답변을 점진적으로 스트리밍 표시
-- `launch(..., ssr_mode=False)`로 서버 사이드 렌더링을 끄고 초기 기동 부담을 줄임
-- 모바일에서는 좌우 glass panel을 숨기고, 제목, 최소 설명, 이미지, 채팅창만 보이도록 단순화
+- 기존 다중 패널 구성의 메인 채팅 UI입니다.
+- 첫 요청 시점에 채팅 서비스를 지연 초기화합니다.
+- 어시스턴트의 부분 응답을 화면의 채팅 영역에 스트리밍합니다.
 
 ### `app_gradio_messenger.py`
 
-- 기존 agent/chat 로직을 그대로 재사용하는 메신저형 UI
-- 좌측 3, 우측 7 비율의 2섹터 레이아웃
-- 좌측: 캐릭터 프로필 목록과 최근 대화 미리보기
-- 우측: 캐릭터 좌측 말풍선, 사용자 우측 말풍선 구조의 대화창
+- 동일한 공용 채팅 서비스 계층 위에 메신저형 UI를 올린 파일입니다.
+- 좌측과 우측 섹터는 Gradio `Column(scale=3)`과 `Column(scale=7)`으로 `3:7` 비율을 유지합니다.
+- 데스크톱 메신저 레이아웃은 의도적으로 고정 높이를 사용합니다.
+- 우측 섹터는 `상단 헤더`, `메시지 표시 영역`, `입력 영역`의 세 파트로 나뉘며, 고정 3행 grid로 배치됩니다.
+- `상단 헤더`와 `입력 영역`은 명시적인 픽셀 높이를 사용합니다.
+- 메시지 뷰포트는 `calc(...)`로 남는 높이만 사용합니다.
+- 아바타 이미지는 외부 저장소 대신 프로젝트 내부 `source_file` 폴더의 로컬 이미지 파일을 Gradio 파일 라우트로 서빙합니다.
+- 우선적으로 `megumin_profile` 이름의 `png`, `jpg`, `jpeg`, `webp` 파일을 찾고, 없으면 같은 폴더의 첫 번째 이미지 파일을 사용합니다.
+- fallback SVG는 로컬 이미지 로드 실패 시에만 표시되며, `source_file` 폴더는 메신저 단독 실행과 `app.py` 경유 실행 모두에서 `allowed_paths`로 명시적으로 노출합니다.
+- Gradio 자동 stretch 래퍼가 세로 확장을 다시 유발할 수 있으므로 이 파일에서는 `gr.Blocks(fill_height=True)`를 사용하지 않습니다.
 
 ### `app.py`
 
-- Hugging Face Spaces 진입점
-- `MEGUMIN_UI` 환경변수로 기본 UI와 메신저 UI 중 하나를 선택해 로드
-
-## 대화 흐름
-
-사용자 입력이 들어오면:
-
-1. `app_gradio.py`가 상태 문구를 먼저 갱신
-2. 첫 질문이면 `get_services()`가 lazy init으로 서비스 준비
-3. `chat.py`의 `stream_chat()`이 ADK `run_async(..., RunConfig(streaming_mode=SSE))`로 실행
-4. `agent.py`의 tool이 retrieval 수행
-5. `retrieval.py`가
-   - 페르소나 데이터 top-2
-   - 사실 데이터 top-2
-   를 각각 검색
-6. ADK partial event가 들어올 때마다 UI가 assistant 답변을 점진적으로 갱신
-7. 세션 종료 후 오래된 이벤트를 key-value summary로 압축
-
-## 세션과 메모리
-
-현재 저장 방식은 `InMemorySessionService`입니다.
+- Hugging Face Spaces 진입점입니다.
+- `MEGUMIN_UI` 값에 따라 기본 UI와 메신저 UI 중 하나를 선택합니다.
 
-- 서버 프로세스가 살아 있는 동안만 유지
-- 재시작 시 초기화
-- 최근 6턴만 유지
-- 오래된 내용은 `user_topics`, `assistant_points` 중심의 key-value summary로 state에 남김
+## 세션 모델
 
-## UI 목적
+- 현재 세션 저장소는 메모리 기반입니다.
+- 앱 프로세스가 살아 있는 동안 대화 연속성이 유지됩니다.
+- 최근 메시지는 직접 보존하고, 오래된 맥락은 요약 상태로 축약합니다.
 
-현재 UI는 체험형 캐릭터 챗봇 화면을 목표로 합니다.
+## 메신저 레이아웃 유지보수 규칙
 
-- 캐릭터와 실제로 마주 보고 대화하는 느낌
-- 반투명 유리 패널 중심 구성
-- 메구밍의 기본 소개와 사용 예시 제공
-- 스트리밍 답변과 작은 상태 배지로 생동감 보강
+- `app_gradio_messenger.py`는 뷰포트를 꽉 채우는 flex 실험이 아니라 고정 높이 레이아웃으로 다룹니다.
+- 메신저 패널 높이가 바뀌면 CSS 변수와 이 문서를 함께 수정합니다.
+- 좌우 비율이 바뀌면 Gradio `scale` 값과 README 메모를 함께 수정합니다.
+- 특별한 이유와 브라우저 검증 없이 내부 래퍼에 중첩된 고정 `min-height` 체인을 다시 도입하지 않습니다.