youlbot-webui/ROADMAP.md

youlbot-webui 개선 로드맵

현황 요약

항목	현재 상태	심각도
아키텍처 모듈화	2파일 혼재 → config / api_client / services/ / container / app 5모듈 분리	✅ 완료
Windows 호환성	TTS say 명령어 — macOS 전용 → 크로스플랫폼 구현 완료	✅ 완료
Gradio Chatbot 타입	type="messages" 누락 → Gradio 6.x 기본 포맷 사용	✅ 완료
JSON yield 타입 불일치	JSONDecodeError 시 타입 혼용 → str() 변환 적용	✅ 완료
run_id 인덱싱 버그	history / run_ids 동기화 취약 → 방어 로직 추가	✅ 완료
RAG 출처 표시	thinking 박스에 혼재 → 답변 하단 📄 출처 전용 박스로 분리	✅ 완료
async/sync 혼용	asyncio.run() 5곳 → 모든 콜백 async 전환 완료	✅ 완료
코드 중복	asyncio.run() 5회 반복 → container 위임으로 제거	✅ 완료
결합도	api_client 직접 임포트 → DI container + Protocol 추상화	✅ 완료
테스트 가능성	Protocol 도입으로 모킹 가능 — 테스트 미작성	🟡 중간
로깅	print() 만 사용	🟢 낮음

---

IoC / 의존성 주입 전략

전용 IoC 프레임워크(dependency-injector 등)는 현재 규모에 과도한 복잡도를 유발합니다. 대신 수동 DI 패턴을 적용합니다.

• Protocol 기반 인터페이스로 api_client 추상화 → 테스트 모킹 가능
• Container 클래스가 서비스 인스턴스 생성·생명주기 관리
• 향후 규모가 커질 경우 프레임워크로 전환 용이

---

목표 아키텍처

┌──────────────────────────────────────────┐
│              app.py (Gradio UI)          │
│  콜백 함수는 service 메서드만 호출         │
└──────────────┬───────────────────────────┘
               │ 주입받음
┌──────────────▼───────────────────────────┐
│         container.py (Container)         │
│  chat_service, document_service 제공     │
└──────────────┬───────────────────────────┘
               │ 생성
┌──────────────▼───────────────────────────┐
│          services/                        │
│  chat.py / document.py / tts.py          │
└──────────────┬───────────────────────────┘
               │ 사용
┌──────────────▼───────────────────────────┐
│    api_client.py (APIClientProtocol)     │
│    HTTPAPIClient (실구현)                │
└──────────────┬───────────────────────────┘
               │ 설정 읽음
┌──────────────▼───────────────────────────┐
│    config.py (AppConfig / APIConfig)     │
│    환경변수 일원화                        │
└──────────────────────────────────────────┘

---

P0 — 즉시 수정 (버그·호환성)

현재 Windows 환경에서 실행 불가 또는 런타임 오류 유발 항목

1. 크로스플랫폼 TTS 구현 (app.py:47-61)

• 문제: subprocess.run(["say", ...]) 는 macOS 전용 → Windows에서 동작 불가.
• 플랫폼별 우선순위:
  • macOS: say(오프라인, 내장) → edge-tts(온라인 폴백) → pyttsx3(최종 폴백)
  • Windows: edge-tts(온라인) → pyttsx3(오프라인 폴백)

우선순위	라이브러리	방식	품질	Windows	macOS
macOS 1순위	say	오프라인(내장)	⭐⭐⭐⭐	❌	✅
macOS 2순위 / Windows 1순위	edge-tts	온라인(MS Edge)	⭐⭐⭐⭐⭐	✅	✅
최종 폴백	pyttsx3	오프라인(SAPI5/NSSpeech)	⭐⭐⭐	✅	✅

async def tts_speak(text: str) -> str | None:
    """크로스플랫폼 TTS — 플랫폼별 우선순위 적용."""
    if not text:
        return None

    # macOS: say 우선 (오프라인, 자연스러운 한국어)
    if platform.system() == "Darwin":
        try:
            tmp = tempfile.NamedTemporaryFile(suffix=".aiff", delete=False)
            tmp.close()
            await asyncio.to_thread(
                subprocess.run,
                ["say", "-v", _TTS_VOICE, "-o", tmp.name, text],
                check=True, capture_output=True,
            )
            return tmp.name
        except Exception:
            pass

    # Windows 1순위 / macOS say 실패 시: edge-tts (온라인)
    try:
        import edge_tts
        tmp = tempfile.NamedTemporaryFile(suffix=".mp3", delete=False)
        tmp.close()
        await edge_tts.Communicate(text, _TTS_EDGE_VOICE).save(tmp.name)
        return tmp.name
    except Exception:
        pass

    # 최종 폴백: pyttsx3 (오프라인)
    try:
        import pyttsx3
        tmp = tempfile.NamedTemporaryFile(suffix=".wav", delete=False)
        tmp.close()
        def _save():
            engine = pyttsx3.init()
            engine.save_to_file(text, tmp.name)
            engine.runAndWait()
        await asyncio.to_thread(_save)
        return tmp.name
    except Exception:
        return None

• 전역 변수 (app.py 상단 추가):

  _TTS_VOICE = os.getenv("TTS_VOICE", "Yuna")                        # macOS say
  _TTS_EDGE_VOICE = os.getenv("TTS_EDGE_VOICE", "ko-KR-SunHiNeural") # edge-tts
  

• 출력 포맷: macOS say → .aiff (기존 유지), edge-tts → .mp3, pyttsx3 → .wav
• requirements.txt 추가: edge-tts>=6.1.9, pyttsx3>=2.90
• 주요 edge-tts 한국어 보이스: ko-KR-SunHiNeural(여성), ko-KR-InJoonNeural(남성)

2. Gradio Chatbot type="messages" 누락 (app.py:186)

• 문제: Gradio 4.x에서 {"role": ..., "content": ...} 딕셔너리 포맷 사용 시 type="messages" 를 명시하지 않으면 경고 또는 오류 발생.
• 수정: gr.Chatbot(type="messages", ...) 추가.

3. JSON yield 타입 불일치 (api_client.py:45-46)

• 문제: JSONDecodeError 발생 시 raw(bytes 또는 str)를 그대로 yield → 반환 타입 tuple[str, str | None] 불일치.
• 수정: yield str(raw), None 으로 명시적 변환.

4. run_id 인덱싱 방어 로직 (app.py:107-108)

• 문제: history 길이와 run_ids 길이가 어긋나면 인덱스 오류 발생 가능.
• 수정: asst_turn 계산 후 범위 초과 시 None 반환하는 방어 코드 보강.

---

P1 — 1주일 내 (구조 개선)

1. 설정 분리 → config.py 신규 생성

# config.py
from dataclasses import dataclass, field
import os

@dataclass
class APIConfig:
    url: str = field(default_factory=lambda: os.getenv("YOULBOT_API_URL", "http://localhost:8000"))
    token: str = field(default_factory=lambda: os.getenv("YOULBOT_API_TOKEN", ""))
    timeout: int = 180

@dataclass
class AppConfig:
    api: APIConfig = field(default_factory=APIConfig)
    whisper_model_size: str = field(default_factory=lambda: os.getenv("WHISPER_MODEL_SIZE", "small"))
    tts_voice: str = field(default_factory=lambda: os.getenv("TTS_VOICE", "Yuna"))
    server_host: str = "0.0.0.0"
    server_port: int = 7860

2. Protocol 인터페이스 + HTTPAPIClient 분리 (api_client.py 리팩터링)

# api_client.py
from typing import Protocol, AsyncIterator, runtime_checkable

@runtime_checkable
class APIClientProtocol(Protocol):
    async def chat(self, message: str, user_id: str, show_thinking: bool) -> AsyncIterator[tuple[str, str | None]]: ...
    async def reset(self, user_id: str) -> None: ...
    async def ingest(self, file_path: str) -> dict: ...
    async def list_documents(self) -> list[str]: ...
    async def delete_document(self, source: str) -> None: ...
    async def save_feedback(self, user_id: str, user_msg: str, asst_msg: str, rating: int, run_id: str | None) -> None: ...

class HTTPAPIClient:
    def __init__(self, config: APIConfig): ...
    # 기존 함수들을 메서드로 이전

3. 서비스 레이어 분리 → services/ 패키지 신규 생성

services/
├── __init__.py          — ChatService, DocumentService, TTSService 재익스포트
├── chat.py              — ChatService: chat, reset, save_feedback
├── document.py          — DocumentService: ingest, list_documents, delete_document
└── tts.py               — TTSService: speak (플랫폼 분기)

4. 수동 DI 컨테이너 → container.py 신규 생성

# container.py
class Container:
    def __init__(self, config: AppConfig):
        self._config = config
        self._api_client: HTTPAPIClient | None = None
        self._chat_service: ChatService | None = None
        self._document_service: DocumentService | None = None

    @property
    def api_client(self) -> HTTPAPIClient: ...

    @property
    def chat_service(self) -> ChatService: ...

    @property
    def document_service(self) -> DocumentService: ...

5. Async 콜백 통일 (app.py)

• handle_feedback, reset_chat, ingest_files, list_docs, delete_doc → 모두 async def 로 전환
• asyncio.get_event_loop().run_until_complete() 패턴 완전 제거
• Gradio 4.x async 콜백 지원 활용

---

P2 — 2주일 내 (품질 개선)

#	항목	설명
1	로깅 시스템	print() → logging 모듈, 구조적 로그 포맷
2	httpx 연결 풀 공유	HTTPAPIClient에서 AsyncClient 인스턴스 재사용
3	입력 검증	파일 경로 sanitize, URL path parameter 검증
4	단위 테스트	tests/ 폴더 생성, ChatService / DocumentService Mock 테스트

---

P3 — 선택 사항 (장기)

#	항목	설명
1	재시도 로직	tenacity 라이브러리 또는 수동 exponential backoff
2	Pydantic Settings	pydantic-settings 로 타입 안전 환경변수 관리
3	IoC 프레임워크 전환	규모 확장 시 dependency-injector 도입 검토

---

최종 파일 구조 (목표)

youlbot-webui/
├── app.py              # Gradio UI 전용 — 콜백만 존재, 비즈니스 로직 없음
├── container.py        # 수동 DI 컨테이너
├── services/
│   ├── __init__.py     # 재익스포트
│   ├── chat.py         # ChatService
│   ├── document.py     # DocumentService
│   └── tts.py          # TTSService
├── api_client.py       # APIClientProtocol + HTTPAPIClient
├── config.py           # AppConfig, APIConfig dataclass
├── tests/
│   ├── test_chat_service.py
│   └── test_document_service.py
├── requirements.txt
├── .env.example
└── ROADMAP.md

---

진행 체크리스트

P0

• tts_speak() 크로스플랫폼 구현 (macOS: say→edge-tts→pyttsx3 / Windows: edge-tts→pyttsx3)
• requirements.txt — edge-tts>=6.1.9, pyttsx3>=2.90 추가
• .env.example — TTS_EDGE_VOICE=ko-KR-SunHiNeural 항목 추가 (TTS_VOICE=Yuna 유지)
• gr.Chatbot — Gradio 6.x 기본 dict 포맷 사용 (type 파라미터 불필요, 제거)
• api_client.py JSON yield 타입 수정
• run_id 인덱싱 방어 로직 추가
• RAG 출처 전용 박스 분리 — source_box gr.HTML + _sources_html() + __sources 토큰 처리

P1

• config.py 작성 (APIConfig, AppConfig)
• api_client.py — APIClientProtocol + HTTPAPIClient 분리
• services/ 패키지 작성 (chat.py, document.py, tts.py + __init__.py 재익스포트)
• container.py 작성 (lazy singleton 프로퍼티)
• app.py — 모든 콜백 async 전환 및 container 사용 (asyncio.run() 완전 제거)

P2

• logging 모듈 도입 — basicConfig + LOG_LEVEL 환경변수, print() 제거
• httpx AsyncClient 재사용 — HTTPAPIClient.__init__에서 공유 클라이언트 생성, aclose() 추가
• 입력 검증 추가 — DocumentService.ingest 파일 존재·확장자 검증, delete_document URL 인코딩
• tests/ 단위 테스트 작성 — pytest-asyncio, ChatService 4개 / DocumentService 6개 (10/10 통과)

P3

• 재시도 로직
• Pydantic Settings