docs/agent-architecture.md

에이전트 아키텍처

개요

프로젝트는 세 개의 UI 진입점과 하나의 공용 채팅 런타임으로 구성됩니다.

1. app.py
2. app_gradio.py
3. app_gradio_messenger.py
4. megumin_agent/

각 UI 계층은 같은 채팅 서비스 헬퍼를 호출하고, 채팅 서비스는 검색, 에이전트 실행, 스트리밍, 세션 상태 관리를 담당합니다.

런타임 흐름

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_agent/bootstrap.py

• .env를 로드합니다.
• 필요 시 로컬 adk-python/src 경로를 준비합니다.
• 가능하면 Hugging Face에서 데이터셋 자산을 내려받습니다.
• 원격 자산을 사용할 수 없으면 로컬 처리 데이터로 폴백합니다.

megumin_agent/retrieval.py

• QA JSON 소스와 FAISS 인덱스를 로드합니다.
• 페르소나형 데이터와 사실형 데이터에 대해 검색을 수행합니다.
• 프롬프트 구성에 사용할 간결한 검색 결과를 반환합니다.

megumin_agent/agent.py

• 메구밍 페르소나 프롬프트와 검색 도구를 정의합니다.
• 페르소나 검색과 사실 검색을 하나의 에이전트 흐름으로 합칩니다.
• 멀티턴 대화에 필요한 요약 상태를 관리합니다.

megumin_agent/chat.py

• 공용 러너와 메모리 기반 세션 서비스를 생성합니다.
• stream_chat()으로 SSE 스타일의 부분 응답을 제공합니다.
• 최근 턴 상태와 요약 정보를 유지해 후속 대화를 지원합니다.

app_gradio.py

• 기존 다중 패널 구성의 메인 채팅 UI입니다.
• 첫 요청 시점에 채팅 서비스를 지연 초기화합니다.
• 어시스턴트의 부분 응답을 화면의 채팅 영역에 스트리밍합니다.

app_gradio_messenger.py

• 동일한 공용 채팅 서비스 계층 위에 메신저형 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 중 하나를 선택합니다.

세션 모델

• 현재 세션 저장소는 메모리 기반입니다.
• 앱 프로세스가 살아 있는 동안 대화 연속성이 유지됩니다.
• 최근 메시지는 직접 보존하고, 오래된 맥락은 요약 상태로 축약합니다.

메신저 레이아웃 유지보수 규칙

• app_gradio_messenger.py는 뷰포트를 꽉 채우는 flex 실험이 아니라 고정 높이 레이아웃으로 다룹니다.
• 메신저 패널 높이가 바뀌면 CSS 변수와 이 문서를 함께 수정합니다.
• 좌우 비율이 바뀌면 Gradio scale 값과 README 메모를 함께 수정합니다.
• 특별한 이유와 브라우저 검증 없이 내부 래퍼에 중첩된 고정 min-height 체인을 다시 도입하지 않습니다.