[DOCS] 문서 수정 및 디버그 코드 제거

client/app.py

@@ -54,16 +54,16 @@ IMAGES_DIR = os.path.join(PROJECT_ROOT, "images")
 REFERENCE_AUDIO_DIR = os.path.join(PROJECT_ROOT, "reference_audio")
 
 # 디버그: 경로 확인
-print(f"[PATH DEBUG] __file__: {__file__}")
-print(f"[PATH DEBUG] PROJECT_ROOT: {PROJECT_ROOT}")
-print(f"[PATH DEBUG] DOCS_DIR: {DOCS_DIR}")
-print(f"[PATH DEBUG] DOCS_DIR exists: {os.path.exists(DOCS_DIR)}")
+# print(f"[PATH DEBUG] __file__: {__file__}")
+# print(f"[PATH DEBUG] PROJECT_ROOT: {PROJECT_ROOT}")
+# print(f"[PATH DEBUG] DOCS_DIR: {DOCS_DIR}")
+# print(f"[PATH DEBUG] DOCS_DIR exists: {os.path.exists(DOCS_DIR)}")
 if os.path.exists(DOCS_DIR):
     print(f"[PATH DEBUG] DOCS_DIR contents: {os.listdir(DOCS_DIR)}")
 
 # 환경변수로 allowed_paths 설정 (Spaces 배포용)
 os.environ["GRADIO_ALLOWED_PATHS"] = f"{UPLOAD_DIR},{DOCS_DIR},{IMAGES_DIR},{REFERENCE_AUDIO_DIR}"
-print(f"[PATH DEBUG] GRADIO_ALLOWED_PATHS: {os.environ['GRADIO_ALLOWED_PATHS']}")
+# print(f"[PATH DEBUG] GRADIO_ALLOWED_PATHS: {os.environ['GRADIO_ALLOWED_PATHS']}")
 
 
 class AudioValidationApp:
@@ -89,7 +89,7 @@ class AudioValidationApp:
         """
         try:
             data = get_dashboard_stats()
-            print(f"[DASHBOARD] 통계 데이터: {data}")
+            # print(f"[DASHBOARD] 통계 데이터: {data}")
             return data  # 전체 데이터 반환 (answer_word, reference_audio_path 포함)
 
         except Exception as e:
@@ -152,13 +152,13 @@ class AudioValidationApp:
         expected_text = self.validator.get_expected_text(current_difficulty)
         today = datetime.now().strftime("%Y-%m-%d")
 
-        print("=" * 60)
+        # print("=" * 60)
         print("[AUDIO VALIDATE] 음성 검증 요청")
-        print(f"  - Session ID (UUID): {session_id}")
-        print(f"  - Audio Path: {audio_path}")
-        print(f"  - 시도 횟수: {attempt_count + 1}번째")
-        print(f"  - 기대 텍스트: {expected_text}")
-        print("=" * 60)
+        # print(f"  - Session ID (UUID): {session_id}")
+        # print(f"  - Audio Path: {audio_path}")
+        # print(f"  - 시도 횟수: {attempt_count + 1}번째")
+        # print(f"  - 기대 텍스트: {expected_text}")
+        # print("=" * 60)
 
         # ========== 직접 서비스 호출 (HTTP 없음) ==========
         try:
@@ -172,7 +172,7 @@ class AudioValidationApp:
             # 직접 분석 서비스 호출 (HTTP 대신 함수 호출)
             api_result = await analyze_voice(audio_bytes, today, session_id)
 
-            print(f"[ANALYSIS RESULT] {api_result}")
+            # print(f"[ANALYSIS RESULT] {api_result}")
 
             # API 오류 처리
             if api_result.get("status") == "error":
@@ -300,7 +300,7 @@ class AudioValidationApp:
                 }
             )
 
-            print(f"[AUDIO VALIDATE] 실패 처리 - Modal 표시, 총 추측: {len(updated_game_state.get('guesses', []))}개")
+            # print(f"[AUDIO VALIDATE] 실패 처리 - Modal 표시, 총 추측: {len(updated_game_state.get('guesses', []))}개")
 
             return (
                 history_html,                    # 0: history_html
@@ -352,9 +352,9 @@ class AudioValidationApp:
             updated_game_state = GameStateManager.set_win_state(updated_game_state, win=True)
 
             print(f"[AUDIO VALIDATE] 성공 처리!")
-            print(f"  - Session ID: {session_id}")
-            print(f"  - 총 시도 횟수: {len(current_history) + 1}")
-            print(f"  - 승리 연속: {updated_game_state.get('stats', {}).get('winStreak', 0)}")
+            # print(f"  - Session ID: {session_id}")
+            # print(f"  - 총 시도 횟수: {len(current_history) + 1}")
+            # print(f"  - 승리 연속: {updated_game_state.get('stats', {}).get('winStreak', 0)}")
 
             # 통계는 JavaScript에서 화면 표시 시 API 호출하여 업데이트
             print(f"[SUCCESS] 성공 화면으로 전환 - JS가 통계 API 호출 예정")
@@ -391,7 +391,7 @@ class AudioValidationApp:
             last_audio = guesses[-1].get('audioFile', "")
 
         # 통계는 JavaScript에서 화면 표시 시 API 호출하여 업데이트
-        print(f"[GIVEUP] 포기 화면으로 전환 - JS가 통계 API 호출 예정")
+        # print(f"[GIVEUP] 포기 화면으로 전환 - JS가 통계 API 호출 예정")
 
         # outputs 순서: main_screen, giveup_screen, giveup_content, game_state
         return (
@@ -421,13 +421,13 @@ class AudioValidationApp:
         updated_game_state = GameStateManager.get_or_create_session(game_state)
         session_id = GameStateManager.get_session_id(updated_game_state)
 
-        print("=" * 60)
-        print("[PAGE LOAD] 페이지 로드")
-        print(f"  - 오늘 날짜: {today}")
-        print(f"  - 저장된 날짜: {stored_date}")
-        print(f"  - Session ID (UUID): {session_id}")
-        print(f"  - 게임 상태: {updated_game_state.get('winState', -1)} (-1:진행중, 0:포기, 1:성공)")
-        print("=" * 60)
+        # print("=" * 60)
+        # print("[PAGE LOAD] 페이지 로드")
+        # print(f"  - 오늘 날짜: {today}")
+        # print(f"  - 저장된 날짜: {stored_date}")
+        # print(f"  - Session ID (UUID): {session_id}")
+        # print(f"  - 게임 상태: {updated_game_state.get('winState', -1)} (-1:진행중, 0:포기, 1:성공)")
+        # print("=" * 60)
 
         if stored_date != today:
             # 날짜가 다르면 기록 초기화
@@ -459,7 +459,7 @@ class AudioValidationApp:
         """
         # 앱 시작 시점에 통계 데이터 가져오기
         stats = self._fetch_dashboard_stats_sync()
-        print(f"[BUILD UI] 초기 통계 데이터: {stats}")
+        # print(f"[BUILD UI] 초기 통계 데이터: {stats}")
 
         # 이벤트 핸들러 설정
         handlers = {

client/docs/tech-stack.html

@@ -1,9 +1,9 @@
 <!DOCTYPE html>
-<html lang="ko">
+<html lang="en">
 <head>
     <meta charset="UTF-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>Tech Stack - Komentle Voice Challenge</title>
+    <title>Tech Stack - Voice Sementle</title>
     <link href="https://fonts.googleapis.com/css2?family=Nunito:wght@400;600;700;800&display=swap" rel="stylesheet">
     <style>
         :root {
@@ -494,8 +494,8 @@
         <!-- Sidebar -->
         <nav class="sidebar">
             <a href="#" class="logo">
-                <div class="logo-icon">K</div>
-                Komentle
+                <div class="logo-icon">V</div>
+                Voice Sementle
             </a>
 
             <div class="nav-section">
@@ -523,7 +523,7 @@
                 <div class="nav-title">Backend</div>
                 <ul class="nav-list">
                     <li class="nav-item">
-                        <a href="#backend" class="nav-link">FastAPI Server</a>
+                        <a href="#backend" class="nav-link">Services</a>
                     </li>
                     <li class="nav-item">
                         <a href="#database" class="nav-link">Database</a>
@@ -535,7 +535,10 @@
                 <div class="nav-title">AI / ML</div>
                 <ul class="nav-list">
                     <li class="nav-item">
-                        <a href="#ai" class="nav-link">Voice Analysis</a>
+                        <a href="#ai" class="nav-link">AI Models</a>
+                    </li>
+                    <li class="nav-item">
+                        <a href="#mcp" class="nav-link">MCP Integration</a>
                     </li>
                     <li class="nav-item">
                         <a href="#audio" class="nav-link">Audio Processing</a>
@@ -564,8 +567,8 @@
                 <header class="page-header">
                     <h1 class="page-title">Tech Stack</h1>
                     <p class="page-description">
-                        Komentle Voice Challenge에 사용된 기술 스택입니다.
-                        음성 기반 발음 검증 퀴즈 게임을 위한 풀스택 구성이에요.
+                        Comprehensive technology stack for Voice Sementle - a daily voice puzzle game where pronunciation matters.
+                        Built with modern Python frameworks, AI models, and cloud services.
                     </p>
                 </header>
     
@@ -578,18 +581,18 @@
                     <div class="architecture-diagram">
                         <div class="arch-flow">
                             <div class="arch-box">
-                                <div class="arch-box-title">Client</div>
+                                <div class="arch-box-title">Client UI</div>
                                 <div class="arch-box-sub">Gradio 6.0</div>
                             </div>
                             <span class="arch-arrow">→</span>
                             <div class="arch-box secondary">
-                                <div class="arch-box-title">Backend</div>
-                                <div class="arch-box-sub">FastAPI</div>
+                                <div class="arch-box-title">Services</div>
+                                <div class="arch-box-sub">Python Backend</div>
                             </div>
                             <span class="arch-arrow">→</span>
                             <div class="arch-box tertiary">
-                                <div class="arch-box-title">AI Engine</div>
-                                <div class="arch-box-sub">Google Gemini</div>
+                                <div class="arch-box-title">AI Models</div>
+                                <div class="arch-box-sub">Gemini + VoiceKit MCP</div>
                             </div>
                         </div>
                     </div>
@@ -609,17 +612,17 @@
                                 <span class="tech-version">6.0.0</span>
                             </div>
                             <p class="tech-description">
-                                Python 기반 UI 프레임워크. 음성 입력, 실시간 피드백, 게임 화면 전환 등 인터랙티브한 웹 인터페이스 구현
+                                Python-based UI framework. Powers interactive web interface with voice input, real-time feedback, modals, and dynamic game state transitions.
                             </p>
                         </div>
                         <div class="tech-card">
                             <div class="tech-header">
                                 <div class="tech-icon icon-python">Py</div>
                                 <span class="tech-name">Python</span>
-                                <span class="tech-version">3.11</span>
+                                <span class="tech-version">3.11+</span>
                             </div>
                             <p class="tech-description">
-                                클라이언트 애플리케이션 개발 언어. 타입 힌팅과 async/await 패턴 활용
+                                Client application language. Leverages type hints, async/await patterns, and modern Python features for clean, maintainable code.
                             </p>
                         </div>
                         <div class="tech-card">
@@ -629,7 +632,17 @@
                                 <span class="tech-version">0.28.1</span>
                             </div>
                             <p class="tech-description">
-                                비동기 HTTP 클라이언트. 백엔드 API와의 통신 담당
+                                Async HTTP client library for communicating with backend services and external APIs with full HTTP/2 support.
+                            </p>
+                        </div>
+                        <div class="tech-card">
+                            <div class="tech-header">
+                                <div class="tech-icon" style="background: linear-gradient(135deg, #8b5cf6, #a78bfa);">Js</div>
+                                <span class="tech-name">Custom CSS/JS</span>
+                                <span class="tech-version">-</span>
+                            </div>
+                            <p class="tech-description">
+                                Custom styling with animated backgrounds, modal components, radar charts, and responsive design for optimal user experience.
                             </p>
                         </div>
                     </div>
@@ -639,47 +652,47 @@
                 <section id="backend" class="section">
                     <h2 class="section-title">
                         <span class="section-icon backend">⚡</span>
-                        Backend
+                        Backend Services
                     </h2>
                     <div class="tech-grid">
                         <div class="tech-card">
                             <div class="tech-header">
-                                <div class="tech-icon icon-fastapi">Fa</div>
-                                <span class="tech-name">FastAPI</span>
-                                <span class="tech-version">0.121.3</span>
+                                <div class="tech-icon icon-python">Py</div>
+                                <span class="tech-name">Python Services</span>
+                                <span class="tech-version">3.11+</span>
                             </div>
                             <p class="tech-description">
-                                고성능 Python 웹 프레임워크. REST API 엔드포인트 제공, 자동 OpenAPI 문서 생성
+                                Modular service architecture including voice analyzer, hint generator, database layer, and game state management with async/await support.
                             </p>
                         </div>
                         <div class="tech-card">
                             <div class="tech-header">
-                                <div class="tech-icon" style="background: linear-gradient(135deg, #7c3aed, #a78bfa);">Uv</div>
-                                <span class="tech-name">Uvicorn</span>
-                                <span class="tech-version">0.38.0</span>
+                                <div class="tech-icon" style="background: linear-gradient(135deg, #ec4899, #f472b6);">Pd</div>
+                                <span class="tech-name">Pydantic</span>
+                                <span class="tech-version">2.0+</span>
                             </div>
                             <p class="tech-description">
-                                Lightning-fast ASGI 서버. 비동기 요청 처리 및 WebSocket 지원
+                                Data validation and settings management with type safety, automatic serialization, and schema validation.
                             </p>
                         </div>
                         <div class="tech-card">
                             <div class="tech-header">
-                                <div class="tech-icon icon-python">Py</div>
-                                <span class="tech-name">Python</span>
-                                <span class="tech-version">3.12</span>
+                                <div class="tech-icon" style="background: linear-gradient(135deg, #10b981, #34d399);">Ay</div>
+                                <span class="tech-name">Asyncio</span>
+                                <span class="tech-version">Built-in</span>
                             </div>
                             <p class="tech-description">
-                                백엔드 서버 개발 언어. 최신 버전의 성능 최적화 및 기능 활용
+                                Native Python async library for concurrent operations, enabling efficient handling of multiple voice analysis requests.
                             </p>
                         </div>
                         <div class="tech-card">
                             <div class="tech-header">
-                                <div class="tech-icon" style="background: linear-gradient(135deg, #ec4899, #f472b6);">Pd</div>
-                                <span class="tech-name">Pydantic</span>
-                                <span class="tech-version">2.12.4</span>
+                                <div class="tech-icon" style="background: linear-gradient(135deg, #f59e0b, #fbbf24);">Dv</div>
+                                <span class="tech-name">Python-dotenv</span>
+                                <span class="tech-version">1.0.0</span>
                             </div>
                             <p class="tech-description">
-                                데이터 검증 및 설정 관리. 타입 안전성과 자동 직렬화 제공
+                                Environment variable management from .env files for secure API keys and configuration settings.
                             </p>
                         </div>
                     </div>
@@ -696,20 +709,30 @@
                             <div class="tech-header">
                                 <div class="tech-icon icon-postgres">Pg</div>
                                 <span class="tech-name">PostgreSQL</span>
-                                <span class="tech-version">Latest</span>
+                                <span class="tech-version">16-alpine</span>
                             </div>
                             <p class="tech-description">
-                                관계형 데이터베이스. 사용자 세션, 게임 기록, 통계 데이터 저장
+                                Production-grade relational database. Stores user sessions, game history, daily puzzles, attempt statistics, and score analytics.
                             </p>
                         </div>
                         <div class="tech-card">
                             <div class="tech-header">
-                                <div class="tech-icon" style="background: linear-gradient(135deg, #dc2626, #f87171);">SA</div>
-                                <span class="tech-name">SQLAlchemy</span>
-                                <span class="tech-version">2.0.44</span>
+                                <div class="tech-icon" style="background: linear-gradient(135deg, #0891b2, #22d3ee);">Ps</div>
+                                <span class="tech-name">psycopg2</span>
+                                <span class="tech-version">2.9+</span>
                             </div>
                             <p class="tech-description">
-                                Python ORM. 데이터베이스 추상화 및 쿼리 빌더 제공
+                                PostgreSQL adapter for Python. Provides efficient database connections and query execution with connection pooling.
+                            </p>
+                        </div>
+                        <div class="tech-card">
+                            <div class="tech-header">
+                                <div class="tech-icon icon-docker">Dk</div>
+                                <span class="tech-name">Docker Volume</span>
+                                <span class="tech-version">-</span>
+                            </div>
+                            <p class="tech-description">
+                                Persistent data storage with Docker volumes ensuring database persistence across container restarts.
                             </p>
                         </div>
                     </div>
@@ -726,40 +749,80 @@
                             <div class="tech-header">
                                 <div class="tech-icon icon-gemini">Gm</div>
                                 <span class="tech-name">Google Gemini</span>
-                                <span class="tech-version">API</span>
+                                <span class="tech-version">2.0 Flash</span>
                             </div>
                             <p class="tech-description">
-                                멀티모달 AI 모델. 음성 분석, 발음 평가, 자연어 피드백 생성
+                                Multimodal AI model powering intelligent hint generation, contextual feedback, and adaptive difficulty based on player performance.
                             </p>
                         </div>
                         <div class="tech-card">
                             <div class="tech-header">
-                                <div class="tech-icon" style="background: linear-gradient(135deg, #0891b2, #22d3ee);">MC</div>
-                                <span class="tech-name">MCP</span>
-                                <span class="tech-version">1.0.0+</span>
+                                <div class="tech-icon" style="background: linear-gradient(135deg, #6366f1, #818cf8);">11</div>
+                                <span class="tech-name">ElevenLabs</span>
+                                <span class="tech-version">2.24.0</span>
                             </div>
                             <p class="tech-description">
-                                Model Context Protocol. AI 모델 통합 �� 컨텍스트 관리
+                                Advanced text-to-speech API with voice cloning. Generates partial audio hints with reference voice matching for natural gameplay experience.
                             </p>
                         </div>
                         <div class="tech-card">
                             <div class="tech-header">
                                 <div class="tech-icon icon-numpy">Np</div>
                                 <span class="tech-name">NumPy</span>
-                                <span class="tech-version">1.26+</span>
+                                <span class="tech-version">1.26.4</span>
                             </div>
                             <p class="tech-description">
-                                수치 계산 라이브러리. 오디오 신호 처리 및 데이터 분석
+                                Numerical computing library for audio signal processing, feature extraction, and statistical analysis of voice patterns.
                             </p>
                         </div>
                         <div class="tech-card">
                             <div class="tech-header">
                                 <div class="tech-icon" style="background: linear-gradient(135deg, #0d9488, #2dd4bf);">Pd</div>
                                 <span class="tech-name">Pandas</span>
-                                <span class="tech-version">2.0+</span>
+                                <span class="tech-version">2.2.3</span>
+                            </div>
+                            <p class="tech-description">
+                                Data analysis library for processing game statistics, tracking user progress, and generating performance insights.
+                            </p>
+                        </div>
+                    </div>
+                </section>
+
+                <!-- MCP Integration -->
+                <section id="mcp" class="section">
+                    <h2 class="section-title">
+                        <span class="section-icon" style="background: linear-gradient(135deg, #8b5cf6, #a78bfa);">🔌</span>
+                        Model Context Protocol (MCP)
+                    </h2>
+                    <div class="tech-grid">
+                        <div class="tech-card">
+                            <div class="tech-header">
+                                <div class="tech-icon" style="background: linear-gradient(135deg, #0891b2, #22d3ee);">MC</div>
+                                <span class="tech-name">MCP Client</span>
+                                <span class="tech-version">1.22.0</span>
                             </div>
                             <p class="tech-description">
-                                데이터 분석 라이브러리. 통계 처리 및 데이터 조작
+                                Model Context Protocol client for seamless AI model integration. Manages sessions, tool calling, and context sharing across AI services.
+                            </p>
+                        </div>
+                        <div class="tech-card">
+                            <div class="tech-header">
+                                <div class="tech-icon" style="background: linear-gradient(135deg, #f97316, #fb923c);">Vk</div>
+                                <span class="tech-name">VoiceKit MCP</span>
+                                <span class="tech-version">HuggingFace</span>
+                            </div>
+                            <p class="tech-description">
+                                Voice analysis MCP server providing voicekit_analyze_voice_similarity tool. Compares user recordings with reference audio for pronunciation scoring.
+                            </p>
+                        </div>
+                        <div class="tech-card">
+                            <div class="tech-header">
+                                <div class="tech-icon" style="background: linear-gradient(135deg, #ec4899, #f472b6);">SS</div>
+                                <span class="tech-name">SSE Client</span>
+                                <span class="tech-version">MCP</span>
+                            </div>
+                            <p class="tech-description">
+                                Server-Sent Events client for real-time MCP communication. Enables streaming responses and bidirectional tool invocation.
                             </p>
                         </div>
                     </div>
@@ -779,7 +842,7 @@
                                 <span class="tech-version">0.25.1</span>
                             </div>
                             <p class="tech-description">
-                                오디오 처리 라이브러리. 포맷 변환, 정규화, 편집 기능 제공
+                                Audio manipulation library for format conversion, normalization, compression, and audio file editing with effects processing.
                             </p>
                         </div>
                         <div class="tech-card">
@@ -789,7 +852,27 @@
                                 <span class="tech-version">via ffmpy</span>
                             </div>
                             <p class="tech-description">
-                                멀티미디어 프레임워크. 오디오 인코딩/디코딩 처리
+                                Multimedia framework for audio encoding/decoding. Handles format conversion and compression for optimal file sizes.
+                            </p>
+                        </div>
+                        <div class="tech-card">
+                            <div class="tech-header">
+                                <div class="tech-icon" style="background: linear-gradient(135deg, #7c3aed, #a78bfa);">B6</div>
+                                <span class="tech-name">Base64</span>
+                                <span class="tech-version">Built-in</span>
+                            </div>
+                            <p class="tech-description">
+                                Audio data encoding for API transmission. Converts binary audio to base64 strings for MCP tool parameters.
+                            </p>
+                        </div>
+                        <div class="tech-card">
+                            <div class="tech-header">
+                                <div class="tech-icon" style="background: linear-gradient(135deg, #dc2626, #f87171);">Af</div>
+                                <span class="tech-name">Aiofiles</span>
+                                <span class="tech-version">24.1.0</span>
+                            </div>
+                            <p class="tech-description">
+                                Async file operations for non-blocking audio file I/O. Enables concurrent file processing without blocking the event loop.
                             </p>
                         </div>
                     </div>
@@ -809,7 +892,7 @@
                                 <span class="tech-version">Latest</span>
                             </div>
                             <p class="tech-description">
-                                컨테이너화 플랫폼. 일관된 개발/배포 환경 제공
+                                Containerization platform providing consistent development and deployment environments across all systems.
                             </p>
                         </div>
                         <div class="tech-card">
@@ -819,27 +902,47 @@
                                 <span class="tech-version">Latest</span>
                             </div>
                             <p class="tech-description">
-                                멀티 컨테이너 오케스트레이션. 서비스 간 네트워크 및 볼륨 관리
+                                Multi-container orchestration for managing PostgreSQL database service with volume persistence and networking.
                             </p>
                         </div>
                         <div class="tech-card">
                             <div class="tech-header">
-                                <div class="tech-icon" style="background: linear-gradient(135deg, #fbbf24, #fcd34d);">Pt</div>
-                                <span class="tech-name">pytest</span>
-                                <span class="tech-version">Latest</span>
+                                <div class="tech-icon" style="background: linear-gradient(135deg, #64748b, #94a3b8);">Ev</div>
+                                <span class="tech-name">Environment Config</span>
+                                <span class="tech-version">-</span>
                             </div>
                             <p class="tech-description">
-                                테스트 프레임워크. 단위 테스트 및 통합 테스트 실행
+                                Secure configuration management with .env files for API keys (Gemini, ElevenLabs, VoiceKit) and sensitive settings.
                             </p>
                         </div>
                         <div class="tech-card">
                             <div class="tech-header">
-                                <div class="tech-icon" style="background: linear-gradient(135deg, #64748b, #94a3b8);">Ev</div>
-                                <span class="tech-name">python-dotenv</span>
-                                <span class="tech-version">1.2.1</span>
+                                <div class="tech-icon" style="background: linear-gradient(135deg, #16a34a, #4ade80);">Sh</div>
+                                <span class="tech-name">Shell Scripts</span>
+                                <span class="tech-version">Bash</span>
+                            </div>
+                            <p class="tech-description">
+                                Automated deployment scripts (start.sh, stop.sh) for streamlined application lifecycle management.
+                            </p>
+                        </div>
+                        <div class="tech-card">
+                            <div class="tech-header">
+                                <div class="tech-icon" style="background: linear-gradient(135deg, #ea580c, #fb923c);">Hf</div>
+                                <span class="tech-name">HuggingFace</span>
+                                <span class="tech-version">Hub</span>
+                            </div>
+                            <p class="tech-description">
+                                Deployment platform hosting VoiceKit MCP server and application demos with integrated spaces for testing.
+                            </p>
+                        </div>
+                        <div class="tech-card">
+                            <div class="tech-header">
+                                <div class="tech-icon" style="background: linear-gradient(135deg, #9333ea, #a855f7);">Lg</div>
+                                <span class="tech-name">Logging</span>
+                                <span class="tech-version">Built-in</span>
                             </div>
                             <p class="tech-description">
-                                환경 변수 관리. .env 파일 기반 설정 로드
+                                Comprehensive logging system for debugging, monitoring API calls, tracking errors, and performance analysis.
                             </p>
                         </div>
                     </div>

client/docs/user-guide.html

@@ -3,7 +3,7 @@
 <head>
     <meta charset="UTF-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>User Guide - Komentle Voice Challenge</title>
+    <title>User Guide - Voice Semenetle</title>
     <link href="https://fonts.googleapis.com/css2?family=Nunito:wght@400;600;700;800&display=swap" rel="stylesheet">
     <style>
         :root {
@@ -792,8 +792,8 @@
                                 <div class="metric-label">Pronunciation</div>
                             </div>
                             <div class="metric-item">
-                                <div class="metric-value">Tone</div>
-                                <div class="metric-label">Voice Tone</div>
+                                <div class="metric-value">Line Acc.</div>
+                                <div class="metric-label">Line Accuracy</div>
                             </div>
                             <div class="metric-item">
                                 <div class="metric-value">Pitch</div>
@@ -813,8 +813,8 @@
                     <div class="content-card">
                         <h3>🎯 Score Interpretation</h3>
                         <ul>
-                            <li><strong>80+ points:</strong> Very similar to the answer! You're almost there!</li>
-                            <li><strong>60-79 points:</strong> Good attempt. Check the hints for guidance.</li>
+                            <li><strong>85+ points:</strong> Very similar to the answer! You're almost there!</li>
+                            <li><strong>60-84 points:</strong> Good attempt. Check the hints for guidance.</li>
                             <li><strong>40-59 points:</strong> Right direction, but try a different word.</li>
                             <li><strong>Below 40:</strong> Far from the answer. Try a new guess.</li>
                         </ul>
@@ -840,7 +840,7 @@
                     <div class="content-card">
                         <h3>💬 AI Hint Chatbot</h3>
                         <p>
-                            Click the floating button at the bottom right of the screen to open the AI hint chatbot.
+                            Click the floating button at the top right of the screen to open the AI hint chatbot.
                             Request hints from the chatbot to receive indirect clues about the answer.
                         </p>
                     </div>
@@ -852,16 +852,17 @@
                             <li><strong>"What's the category?":</strong> Learn the classification of the answer word.</li>
                             <li><strong>"Tell me the first letter":</strong> Get a hint about the first letter.</li>
                             <li><strong>"What words sound similar?":</strong> Get pronunciation-related suggestions.</li>
+                            <li><strong>"Give me an audio hint":</strong> AI provides an audio hint in a tone similar to your voice.</li>
                         </ul>
                     </div>
 
-                    <div class="warning-box">
+                    <!-- <div class="warning-box">
                         <span class="warning-icon">💡</span>
                         <div class="warning-text">
                             <strong>Limited Hint Usage!</strong> Chatbot hints can only be used a limited number of times.
                             Request hints carefully!
                         </div>
-                    </div>
+                    </div> -->
                 </section>
 
                 <!-- Tips & Tricks -->

client/frontend/components/floating_chatbot.py

@@ -374,14 +374,14 @@ def call_ai_backend(message: str, user_id: str, history: List[Dict], game_state:
         system_prompt = build_system_prompt_from_game_state(game_state, include_audio_tool=tools_will_be_enabled)
 
         print(f"[CHATBOT] Calling Gemini with context:")
-        print(f"  - User ID: {user_id}")
-        print(f"  - Message: {message}")
-        print(f"  - History length: {len(history)}")
-        print(f"  - Game state attempts: {attempt_count}")
-        print(f"  - Answer word: {answer_word}")
-        print(f"  - ElevenLabs AVAILABLE: {ELEVENLABS_AVAILABLE}")
-        print(f"  - ElevenLabs API key set: {bool(api_key)}")
-        print(f"  - ElevenLabs configured: {elevenlabs_ready}")
+        # print(f"  - User ID: {user_id}")
+        # print(f"  - Message: {message}")
+        # print(f"  - History length: {len(history)}")
+        # print(f"  - Game state attempts: {attempt_count}")
+        # print(f"  - Answer word: {answer_word}")
+        # print(f"  - ElevenLabs AVAILABLE: {ELEVENLABS_AVAILABLE}")
+        # print(f"  - ElevenLabs API key set: {bool(api_key)}")
+        # print(f"  - ElevenLabs configured: {elevenlabs_ready}")
 
         # Define audio hint tool if ElevenLabs is configured
         tools = []
@@ -426,7 +426,7 @@ def call_ai_backend(message: str, user_id: str, history: List[Dict], game_state:
             print(f"[CHATBOT ERROR] {error}")
             return f"Sorry, I encountered an error: {error}\n\nPlease try again in a moment."
 
-        print(f"[CHATBOT] Got response: text={len(response_text)} chars, tool_calls={len(tool_calls) if tool_calls else 0}")
+        # print(f"[CHATBOT] Got response: text={len(response_text)} chars, tool_calls={len(tool_calls) if tool_calls else 0}")
 
         # Handle tool calls
         if tool_calls:
@@ -434,18 +434,18 @@ def call_ai_backend(message: str, user_id: str, history: List[Dict], game_state:
                 if tool_call['name'] == 'generate_audio_hint':
                     hint_type = tool_call['input'].get('hint_type', 'syllable')
                     word_index = tool_call['input'].get('word_index', 0)  # Default to first word
-                    print(f"[CHATBOT] Gemini requested audio hint: type={hint_type}, word_index={word_index}")
+                    # print(f"[CHATBOT] Gemini requested audio hint: type={hint_type}, word_index={word_index}")
 
                     # Extract the appropriate portion based on hint_type, word_index, and answer_word
                     from utils.elevenlabs_tts import extract_hint_portion_for_word, generate_audio_hint
 
                     text_to_speak, actual_hint_type = extract_hint_portion_for_word(answer_word, attempt_count, word_index)
                     # Use voice cloning from reference audio when available
-                    print(f"[CHATBOT] Generating audio for: '{text_to_speak}' with reference: {reference_audio_path}")
+                    # print(f"[CHATBOT] Generating audio for: '{text_to_speak}' with reference: {reference_audio_path}")
                     audio_path = generate_audio_hint(text_to_speak, actual_hint_type, reference_audio_path=reference_audio_path)
 
                     if audio_path:
-                        print(f"[CHATBOT] Audio hint generated: {audio_path}")
+                        # print(f"[CHATBOT] Audio hint generated: {audio_path}")
                         # Always include text with audio hint
                         if not response_text or response_text.strip() == "":
                             response_text = f"🎵 Here's an audio hint! Listen to how it sounds:"
@@ -584,13 +584,13 @@ Don't overthink your first try – it's meant to be a shot in the dark! Just say
             hist.append({"role": "user", "content": message})
 
             # 콘솔 로그
-            print("=" * 60)
+            # print("=" * 60)
             print("[CHATBOT] 메시지 전송")
-            print(f"  - Session ID (UUID): {uid}")
-            print(f"  - Message: {message}")
-            print(f"  - History Length: {len(hist)}")
-            print(f"  - Game State Attempts: {len(gs.get('guesses', [])) if gs else 0}")
-            print("=" * 60)
+            # print(f"  - Session ID (UUID): {uid}")
+            # print(f"  - Message: {message}")
+            # print(f"  - History Length: {len(hist)}")
+            # print(f"  - Game State Attempts: {len(gs.get('guesses', [])) if gs else 0}")
+            # print("=" * 60)
 
             # AI 호출 (Gemini with game_state context)
             response = call_ai_backend(message, uid, hist, game_state=gs)
@@ -606,8 +606,8 @@ Don't overthink your first try – it's meant to be a shot in the dark! Just say
                     # Path is relative to project root (3 levels up from this file)
                     project_root = os.path.dirname(os.path.dirname(os.path.dirname(os.path.dirname(__file__))))
                     audio_path = os.path.join(project_root, audio_path)
-                print(f"[CHATBOT] Audio hint included: {audio_path}")
-                print(f"[CHATBOT] Audio file exists: {os.path.exists(audio_path)}")
+                # print(f"[CHATBOT] Audio hint included: {audio_path}")
+                # print(f"[CHATBOT] Audio file exists: {os.path.exists(audio_path)}")
 
                 # Gradio 6: Use gr.Audio() component for audio content
                 # Reference: chatbot_core_components_simple demo
@@ -622,7 +622,7 @@ Don't overthink your first try – it's meant to be a shot in the dark! Just say
 
         def close_chat_handler():
             """닫기 버튼 핸들러 - 체크박스만 False로"""
-            print("[CHATBOT] 닫기 버튼 클릭됨")
+            # print("[CHATBOT] 닫기 버튼 클릭됨")
             return gr.update(value=False)
 
         # ============================================================

client/frontend/styles/result_screen_style.py

@@ -279,6 +279,18 @@ RESULT_SCREEN_CSS = """
     text-shadow: 1px 1px 2px rgba(0, 0, 0, 0.1);
 }
 
+@media (max-width: 800px) {
+    .answer-word {
+        font-size: 36px;
+    }
+}
+
+@media (max-width: 600px) {
+    .answer-word {
+        font-size: 28px;
+    }
+}
+
 .audio-compare-wrapper {
     display: flex;
     gap: 12px;
@@ -336,6 +348,26 @@ RESULT_SCREEN_CSS = """
     font-weight: 700;
 }
 
+@media (max-width: 800px) {
+    .stat-label {
+        font-size: 0.7rem;
+    }
+
+    .stat-value {
+        font-size: 1.5rem;
+    }
+}
+
+@media (max-width: 600px) {
+    .stat-label {
+        font-size: 0.6rem;
+    }
+
+    .stat-value {
+        font-size: 1.2rem;
+    }
+}
+
 /* 통계 카드 색상 - 라이트모드 (하늘색 애니메이션 테마) */
 .stat-blue {
     background: linear-gradient(135deg, #e3f5ff, #c7e9ff);

client/services/analysis_service.py

@@ -149,19 +149,19 @@ async def analyze_voice(audio_bytes: bytes, date: str, session_id: str) -> Dict:
         "user_text": user_text,
     }
 
-    print(f"\n{'='*50}")
-    print(f"[SCORING RESULT] analyze_voice result:")
-    print(f"  - status: {result['status']}")
-    print(f"  - category: {result['category']}")
-    print(f"  - pitch: {result['pitch']}")
-    print(f"  - rhythm: {result['rhythm']}")
-    print(f"  - energy: {result['energy']}")
-    print(f"  - pronunciation: {result['pronunciation']}")
-    print(f"  - transcript: {result['transcript']}")
-    print(f"  - overall: {result['overall']}")
-    print(f"  - is_correct: {result['is_correct']}")
-    print(f"  - user_text: {result['user_text']}")
-    print(f"  - advice: {result['advice'][:100]}..." if len(result['advice']) > 100 else f"  - advice: {result['advice']}")
-    print(f"{'='*50}\n")
+    # print(f"\n{'='*50}")
+    # print(f"[SCORING RESULT] analyze_voice result:")
+    # print(f"  - status: {result['status']}")
+    # print(f"  - category: {result['category']}")
+    # print(f"  - pitch: {result['pitch']}")
+    # print(f"  - rhythm: {result['rhythm']}")
+    # print(f"  - energy: {result['energy']}")
+    # print(f"  - pronunciation: {result['pronunciation']}")
+    # print(f"  - transcript: {result['transcript']}")
+    # print(f"  - overall: {result['overall']}")
+    # print(f"  - is_correct: {result['is_correct']}")
+    # print(f"  - user_text: {result['user_text']}")
+    # print(f"  - advice: {result['advice'][:100]}..." if len(result['advice']) > 100 else f"  - advice: {result['advice']}")
+    # print(f"{'='*50}\n")
 
     return result

client/services/hint_generator.py

@@ -124,8 +124,8 @@ Return ONLY this JSON:
 """
 
         print(f"[GEMINI HINT] Calling Gemini for hint generation...")
-        print(f"[GEMINI HINT] User said: '{user_text}', Overall: {overall_score}, Attempt: {attempt}")
-        print(f"[GEMINI HINT] Hint history: {hint_history}")
+        # print(f"[GEMINI HINT] User said: '{user_text}', Overall: {overall_score}, Attempt: {attempt}")
+        # print(f"[GEMINI HINT] Hint history: {hint_history}")
 
         # Call Gemini
         response = call_gemini_with_tools(
@@ -138,8 +138,8 @@ Return ONLY this JSON:
 
         # Extract JSON from response
         response_text, error = get_text_from_gemini_response(response)
-        print(f"[GEMINI HINT] Response text: {response_text[:200] if response_text else 'None'}...")
-        print(f"[GEMINI HINT] Error: {error}")
+        # print(f"[GEMINI HINT] Response text: {response_text[:200] if response_text else 'None'}...")
+        # print(f"[GEMINI HINT] Error: {error}")
 
         if error:
             logger.error(f"Gemini response error: {error}")
@@ -154,12 +154,12 @@ Return ONLY this JSON:
         if response_text.startswith("```"):
             lines = response_text.split("\n")
             response_text = "\n".join(lines[1:-1]) if len(lines) > 2 else response_text
-            print(f"[GEMINI HINT] Cleaned markdown, result: {response_text[:200]}...")
+            # print(f"[GEMINI HINT] Cleaned markdown, result: {response_text[:200]}...")
 
         # Parse JSON
-        print(f"[GEMINI HINT] Parsing JSON: {response_text[:300]}...")
+        # print(f"[GEMINI HINT] Parsing JSON: {response_text[:300]}...")
         hints_json = json.loads(response_text)
-        print(f"[GEMINI HINT] ✓ Parsed successfully: {hints_json}")
+        # print(f"[GEMINI HINT] ✓ Parsed successfully: {hints_json}")
         logger.info(f"✓ Generated fresh hint for attempt {attempt}, category {category}")
 
         return hints_json

client/utils/audio_validator.py

@@ -98,7 +98,7 @@ class AudioValidator:
         similarity = self.calculate_similarity(recognized_text, expected_text)
         threshold = self.difficulty_thresholds.get(difficulty, 0.80)
         
-        print(f"[DEBUG] Similarity: {similarity:.2%}, Threshold: {threshold:.2%}")
+        # print(f"[DEBUG] Similarity: {similarity:.2%}, Threshold: {threshold:.2%}")
         
         return similarity >= threshold
     

client/utils/elevenlabs_tts.py

@@ -57,7 +57,7 @@ def clone_voice_from_reference(reference_audio_path: str) -> Optional[str]:
 
     # Check cache first
     if reference_audio_path in _cloned_voice_cache:
-        print(f"✓ Using cached cloned voice for: {reference_audio_path}")
+        # print(f"✓ Using cached cloned voice for: {reference_audio_path}")
         return _cloned_voice_cache[reference_audio_path]
 
     try:
@@ -69,7 +69,7 @@ def clone_voice_from_reference(reference_audio_path: str) -> Optional[str]:
 
         # Always use .wav for ElevenLabs (required format for voice cloning)
         full_path = full_path.with_suffix('.wav')
-        print(f"🎵 Using WAV format for ElevenLabs: {full_path}")
+        # print(f"🎵 Using WAV format for ElevenLabs: {full_path}")
 
         if not full_path.exists():
             print(f"⚠ Reference audio not found: {full_path}")
@@ -80,7 +80,7 @@ def clone_voice_from_reference(reference_audio_path: str) -> Optional[str]:
 
         # Create instant voice clone using IVC API
         voice_name = f"puzzle_voice_{hashlib.md5(reference_audio_path.encode()).hexdigest()[:8]}"
-        print(f"🎤 Cloning voice from: {full_path}")
+        # print(f"🎤 Cloning voice from: {full_path}")
 
         # Read file as BytesIO (required by ElevenLabs SDK)
         # remove_background_noise=False allows shorter samples (<4.6s)
@@ -93,7 +93,7 @@ def clone_voice_from_reference(reference_audio_path: str) -> Optional[str]:
 
         voice_id = voice.voice_id
         _cloned_voice_cache[reference_audio_path] = voice_id
-        print(f"✓ Voice cloned successfully: {voice_id}")
+        # print(f"✓ Voice cloned successfully: {voice_id}")
 
         return voice_id
 
@@ -139,7 +139,8 @@ def generate_audio_hint(text: str, hint_type: str = "syllable", voice: str = "Ra
         if reference_audio_path:
             voice_id = clone_voice_from_reference(reference_audio_path)
             if voice_id:
-                print(f"🎤 Using cloned voice: {voice_id}")
+                # print(f"🎤 Using cloned voice: {voice_id}")
+                pass
 
         # Fallback to preset voice if cloning failed
         if not voice_id:
@@ -150,10 +151,10 @@ def generate_audio_hint(text: str, hint_type: str = "syllable", voice: str = "Ra
                 "Charlie": "IKne3meq5aSn9XLyUdCD", # Charlie - casual male
             }
             voice_id = voice_ids.get(voice, "EXAVITQu4vr4xnSDxMaL")  # Default to Sarah
-            print(f"🎵 Using preset voice: {voice}")
+            # print(f"🎵 Using preset voice: {voice}")
 
         # Generate audio using text_to_speech.convert (v2.24.0 API)
-        print(f"🎵 Generating audio hint: '{text}' ({hint_type})")
+        # print(f"🎵 Generating audio hint: '{text}' ({hint_type})")
         audio = client.text_to_speech.convert(
             voice_id=voice_id,
             text=text,
@@ -173,7 +174,7 @@ def generate_audio_hint(text: str, hint_type: str = "syllable", voice: str = "Ra
         # Return absolute path
         absolute_path = str(filepath)
 
-        print(f"✓ Audio hint generated (fresh): {absolute_path}")
+        # print(f"✓ Audio hint generated (fresh): {absolute_path}")
         return absolute_path
 
     except Exception as e:

client/utils/stt_handler.py

@@ -82,7 +82,7 @@ class STTHandler:
     def _setup_mock(self):
         """Mock STT (테스트용)"""
         self.client = None
-        print("[INFO] Mock STT 모드 (테스트용)")
+        # print("[INFO] Mock STT 모드 (테스트용)")
     
     def transcribe(self, audio_path: str, difficulty: int = 1) -> str:
         """
@@ -98,7 +98,7 @@ class STTHandler:
         if not audio_path or not os.path.exists(audio_path):
             raise ValueError(f"유효하지 않은 오디오 파일: {audio_path}")
         
-        print(f"[DEBUG] Transcribing: {audio_path} (provider={self.provider})")
+        # print(f"[DEBUG] Transcribing: {audio_path} (provider={self.provider})")
         
         if self.provider == 'openai':
             return self._transcribe_openai(audio_path)
@@ -227,7 +227,7 @@ class STTHandler:
         }
         
         result = mock_texts.get(difficulty, "테스트 텍스트")
-        print(f"[MOCK] STT 결과 (난이도 {difficulty}): {result}")
+        # print(f"[MOCK] STT 결과 (난이도 {difficulty}): {result}")
         
         return result
     

docs/tech-stack.html

@@ -1,9 +1,9 @@
 <!DOCTYPE html>
-<html lang="ko">
+<html lang="en">
 <head>
     <meta charset="UTF-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>Tech Stack - Komentle Voice Challenge</title>
+    <title>Tech Stack - Voice Sementle</title>
     <link href="https://fonts.googleapis.com/css2?family=Nunito:wght@400;600;700;800&display=swap" rel="stylesheet">
     <style>
         :root {
@@ -494,8 +494,8 @@
         <!-- Sidebar -->
         <nav class="sidebar">
             <a href="#" class="logo">
-                <div class="logo-icon">K</div>
-                Komentle
+                <div class="logo-icon">V</div>
+                Voice Sementle
             </a>
 
             <div class="nav-section">
@@ -523,7 +523,7 @@
                 <div class="nav-title">Backend</div>
                 <ul class="nav-list">
                     <li class="nav-item">
-                        <a href="#backend" class="nav-link">FastAPI Server</a>
+                        <a href="#backend" class="nav-link">Services</a>
                     </li>
                     <li class="nav-item">
                         <a href="#database" class="nav-link">Database</a>
@@ -535,7 +535,10 @@
                 <div class="nav-title">AI / ML</div>
                 <ul class="nav-list">
                     <li class="nav-item">
-                        <a href="#ai" class="nav-link">Voice Analysis</a>
+                        <a href="#ai" class="nav-link">AI Models</a>
+                    </li>
+                    <li class="nav-item">
+                        <a href="#mcp" class="nav-link">MCP Integration</a>
                     </li>
                     <li class="nav-item">
                         <a href="#audio" class="nav-link">Audio Processing</a>
@@ -564,8 +567,8 @@
                 <header class="page-header">
                     <h1 class="page-title">Tech Stack</h1>
                     <p class="page-description">
-                        Komentle Voice Challenge에 사용된 기술 스택입니다.
-                        음성 기반 발음 검증 퀴즈 게임을 위한 풀스택 구성이에요.
+                        Comprehensive technology stack for Voice Sementle - a daily voice puzzle game where pronunciation matters.
+                        Built with modern Python frameworks, AI models, and cloud services.
                     </p>
                 </header>
     
@@ -578,18 +581,18 @@
                     <div class="architecture-diagram">
                         <div class="arch-flow">
                             <div class="arch-box">
-                                <div class="arch-box-title">Client</div>
+                                <div class="arch-box-title">Client UI</div>
                                 <div class="arch-box-sub">Gradio 6.0</div>
                             </div>
                             <span class="arch-arrow">→</span>
                             <div class="arch-box secondary">
-                                <div class="arch-box-title">Backend</div>
-                                <div class="arch-box-sub">FastAPI</div>
+                                <div class="arch-box-title">Services</div>
+                                <div class="arch-box-sub">Python Backend</div>
                             </div>
                             <span class="arch-arrow">→</span>
                             <div class="arch-box tertiary">
-                                <div class="arch-box-title">AI Engine</div>
-                                <div class="arch-box-sub">Google Gemini</div>
+                                <div class="arch-box-title">AI Models</div>
+                                <div class="arch-box-sub">Gemini + VoiceKit MCP</div>
                             </div>
                         </div>
                     </div>
@@ -609,17 +612,17 @@
                                 <span class="tech-version">6.0.0</span>
                             </div>
                             <p class="tech-description">
-                                Python 기반 UI 프레임워크. 음성 입력, 실시간 피드백, 게임 화면 전환 등 인터랙티브한 웹 인터페이스 구현
+                                Python-based UI framework. Powers interactive web interface with voice input, real-time feedback, modals, and dynamic game state transitions.
                             </p>
                         </div>
                         <div class="tech-card">
                             <div class="tech-header">
                                 <div class="tech-icon icon-python">Py</div>
                                 <span class="tech-name">Python</span>
-                                <span class="tech-version">3.11</span>
+                                <span class="tech-version">3.11+</span>
                             </div>
                             <p class="tech-description">
-                                클라이언트 애플리케이션 개발 언어. 타입 힌팅과 async/await 패턴 활용
+                                Client application language. Leverages type hints, async/await patterns, and modern Python features for clean, maintainable code.
                             </p>
                         </div>
                         <div class="tech-card">
@@ -629,7 +632,17 @@
                                 <span class="tech-version">0.28.1</span>
                             </div>
                             <p class="tech-description">
-                                비동기 HTTP 클라이언트. 백엔드 API와의 통신 담당
+                                Async HTTP client library for communicating with backend services and external APIs with full HTTP/2 support.
+                            </p>
+                        </div>
+                        <div class="tech-card">
+                            <div class="tech-header">
+                                <div class="tech-icon" style="background: linear-gradient(135deg, #8b5cf6, #a78bfa);">Js</div>
+                                <span class="tech-name">Custom CSS/JS</span>
+                                <span class="tech-version">-</span>
+                            </div>
+                            <p class="tech-description">
+                                Custom styling with animated backgrounds, modal components, radar charts, and responsive design for optimal user experience.
                             </p>
                         </div>
                     </div>
@@ -639,47 +652,47 @@
                 <section id="backend" class="section">
                     <h2 class="section-title">
                         <span class="section-icon backend">⚡</span>
-                        Backend
+                        Backend Services
                     </h2>
                     <div class="tech-grid">
                         <div class="tech-card">
                             <div class="tech-header">
-                                <div class="tech-icon icon-fastapi">Fa</div>
-                                <span class="tech-name">FastAPI</span>
-                                <span class="tech-version">0.121.3</span>
+                                <div class="tech-icon icon-python">Py</div>
+                                <span class="tech-name">Python Services</span>
+                                <span class="tech-version">3.11+</span>
                             </div>
                             <p class="tech-description">
-                                고성능 Python 웹 프레임워크. REST API 엔드포인트 제공, 자동 OpenAPI 문서 생성
+                                Modular service architecture including voice analyzer, hint generator, database layer, and game state management with async/await support.
                             </p>
                         </div>
                         <div class="tech-card">
                             <div class="tech-header">
-                                <div class="tech-icon" style="background: linear-gradient(135deg, #7c3aed, #a78bfa);">Uv</div>
-                                <span class="tech-name">Uvicorn</span>
-                                <span class="tech-version">0.38.0</span>
+                                <div class="tech-icon" style="background: linear-gradient(135deg, #ec4899, #f472b6);">Pd</div>
+                                <span class="tech-name">Pydantic</span>
+                                <span class="tech-version">2.0+</span>
                             </div>
                             <p class="tech-description">
-                                Lightning-fast ASGI 서버. 비동기 요청 처리 및 WebSocket 지원
+                                Data validation and settings management with type safety, automatic serialization, and schema validation.
                             </p>
                         </div>
                         <div class="tech-card">
                             <div class="tech-header">
-                                <div class="tech-icon icon-python">Py</div>
-                                <span class="tech-name">Python</span>
-                                <span class="tech-version">3.12</span>
+                                <div class="tech-icon" style="background: linear-gradient(135deg, #10b981, #34d399);">Ay</div>
+                                <span class="tech-name">Asyncio</span>
+                                <span class="tech-version">Built-in</span>
                             </div>
                             <p class="tech-description">
-                                백엔드 서버 개발 언어. 최신 버전의 성능 최적화 및 기능 활용
+                                Native Python async library for concurrent operations, enabling efficient handling of multiple voice analysis requests.
                             </p>
                         </div>
                         <div class="tech-card">
                             <div class="tech-header">
-                                <div class="tech-icon" style="background: linear-gradient(135deg, #ec4899, #f472b6);">Pd</div>
-                                <span class="tech-name">Pydantic</span>
-                                <span class="tech-version">2.12.4</span>
+                                <div class="tech-icon" style="background: linear-gradient(135deg, #f59e0b, #fbbf24);">Dv</div>
+                                <span class="tech-name">Python-dotenv</span>
+                                <span class="tech-version">1.0.0</span>
                             </div>
                             <p class="tech-description">
-                                데이터 검증 및 설정 관리. 타입 안전성과 자동 직렬화 제공
+                                Environment variable management from .env files for secure API keys and configuration settings.
                             </p>
                         </div>
                     </div>
@@ -696,20 +709,30 @@
                             <div class="tech-header">
                                 <div class="tech-icon icon-postgres">Pg</div>
                                 <span class="tech-name">PostgreSQL</span>
-                                <span class="tech-version">Latest</span>
+                                <span class="tech-version">16-alpine</span>
                             </div>
                             <p class="tech-description">
-                                관계형 데이터베이스. 사용자 세션, 게임 기록, 통계 데이터 저장
+                                Production-grade relational database. Stores user sessions, game history, daily puzzles, attempt statistics, and score analytics.
                             </p>
                         </div>
                         <div class="tech-card">
                             <div class="tech-header">
-                                <div class="tech-icon" style="background: linear-gradient(135deg, #dc2626, #f87171);">SA</div>
-                                <span class="tech-name">SQLAlchemy</span>
-                                <span class="tech-version">2.0.44</span>
+                                <div class="tech-icon" style="background: linear-gradient(135deg, #0891b2, #22d3ee);">Ps</div>
+                                <span class="tech-name">psycopg2</span>
+                                <span class="tech-version">2.9+</span>
                             </div>
                             <p class="tech-description">
-                                Python ORM. 데이터베이스 추상화 및 쿼리 빌더 제공
+                                PostgreSQL adapter for Python. Provides efficient database connections and query execution with connection pooling.
+                            </p>
+                        </div>
+                        <div class="tech-card">
+                            <div class="tech-header">
+                                <div class="tech-icon icon-docker">Dk</div>
+                                <span class="tech-name">Docker Volume</span>
+                                <span class="tech-version">-</span>
+                            </div>
+                            <p class="tech-description">
+                                Persistent data storage with Docker volumes ensuring database persistence across container restarts.
                             </p>
                         </div>
                     </div>
@@ -726,40 +749,80 @@
                             <div class="tech-header">
                                 <div class="tech-icon icon-gemini">Gm</div>
                                 <span class="tech-name">Google Gemini</span>
-                                <span class="tech-version">API</span>
+                                <span class="tech-version">2.0 Flash</span>
                             </div>
                             <p class="tech-description">
-                                멀티모달 AI 모델. 음성 분석, 발음 평가, 자연어 피드백 생성
+                                Multimodal AI model powering intelligent hint generation, contextual feedback, and adaptive difficulty based on player performance.
                             </p>
                         </div>
                         <div class="tech-card">
                             <div class="tech-header">
-                                <div class="tech-icon" style="background: linear-gradient(135deg, #0891b2, #22d3ee);">MC</div>
-                                <span class="tech-name">MCP</span>
-                                <span class="tech-version">1.0.0+</span>
+                                <div class="tech-icon" style="background: linear-gradient(135deg, #6366f1, #818cf8);">11</div>
+                                <span class="tech-name">ElevenLabs</span>
+                                <span class="tech-version">2.24.0</span>
                             </div>
                             <p class="tech-description">
-                                Model Context Protocol. AI 모델 통합 �� 컨텍스트 관리
+                                Advanced text-to-speech API with voice cloning. Generates partial audio hints with reference voice matching for natural gameplay experience.
                             </p>
                         </div>
                         <div class="tech-card">
                             <div class="tech-header">
                                 <div class="tech-icon icon-numpy">Np</div>
                                 <span class="tech-name">NumPy</span>
-                                <span class="tech-version">1.26+</span>
+                                <span class="tech-version">1.26.4</span>
                             </div>
                             <p class="tech-description">
-                                수치 계산 라이브러리. 오디오 신호 처리 및 데이터 분석
+                                Numerical computing library for audio signal processing, feature extraction, and statistical analysis of voice patterns.
                             </p>
                         </div>
                         <div class="tech-card">
                             <div class="tech-header">
                                 <div class="tech-icon" style="background: linear-gradient(135deg, #0d9488, #2dd4bf);">Pd</div>
                                 <span class="tech-name">Pandas</span>
-                                <span class="tech-version">2.0+</span>
+                                <span class="tech-version">2.2.3</span>
+                            </div>
+                            <p class="tech-description">
+                                Data analysis library for processing game statistics, tracking user progress, and generating performance insights.
+                            </p>
+                        </div>
+                    </div>
+                </section>
+
+                <!-- MCP Integration -->
+                <section id="mcp" class="section">
+                    <h2 class="section-title">
+                        <span class="section-icon" style="background: linear-gradient(135deg, #8b5cf6, #a78bfa);">🔌</span>
+                        Model Context Protocol (MCP)
+                    </h2>
+                    <div class="tech-grid">
+                        <div class="tech-card">
+                            <div class="tech-header">
+                                <div class="tech-icon" style="background: linear-gradient(135deg, #0891b2, #22d3ee);">MC</div>
+                                <span class="tech-name">MCP Client</span>
+                                <span class="tech-version">1.22.0</span>
                             </div>
                             <p class="tech-description">
-                                데이터 분석 라이브러리. 통계 처리 및 데이터 조작
+                                Model Context Protocol client for seamless AI model integration. Manages sessions, tool calling, and context sharing across AI services.
+                            </p>
+                        </div>
+                        <div class="tech-card">
+                            <div class="tech-header">
+                                <div class="tech-icon" style="background: linear-gradient(135deg, #f97316, #fb923c);">Vk</div>
+                                <span class="tech-name">VoiceKit MCP</span>
+                                <span class="tech-version">HuggingFace</span>
+                            </div>
+                            <p class="tech-description">
+                                Voice analysis MCP server providing voicekit_analyze_voice_similarity tool. Compares user recordings with reference audio for pronunciation scoring.
+                            </p>
+                        </div>
+                        <div class="tech-card">
+                            <div class="tech-header">
+                                <div class="tech-icon" style="background: linear-gradient(135deg, #ec4899, #f472b6);">SS</div>
+                                <span class="tech-name">SSE Client</span>
+                                <span class="tech-version">MCP</span>
+                            </div>
+                            <p class="tech-description">
+                                Server-Sent Events client for real-time MCP communication. Enables streaming responses and bidirectional tool invocation.
                             </p>
                         </div>
                     </div>
@@ -779,7 +842,7 @@
                                 <span class="tech-version">0.25.1</span>
                             </div>
                             <p class="tech-description">
-                                오디오 처리 라이브러리. 포맷 변환, 정규화, 편집 기능 제공
+                                Audio manipulation library for format conversion, normalization, compression, and audio file editing with effects processing.
                             </p>
                         </div>
                         <div class="tech-card">
@@ -789,7 +852,27 @@
                                 <span class="tech-version">via ffmpy</span>
                             </div>
                             <p class="tech-description">
-                                멀티미디어 프레임워크. 오디오 인코딩/디코딩 처리
+                                Multimedia framework for audio encoding/decoding. Handles format conversion and compression for optimal file sizes.
+                            </p>
+                        </div>
+                        <div class="tech-card">
+                            <div class="tech-header">
+                                <div class="tech-icon" style="background: linear-gradient(135deg, #7c3aed, #a78bfa);">B6</div>
+                                <span class="tech-name">Base64</span>
+                                <span class="tech-version">Built-in</span>
+                            </div>
+                            <p class="tech-description">
+                                Audio data encoding for API transmission. Converts binary audio to base64 strings for MCP tool parameters.
+                            </p>
+                        </div>
+                        <div class="tech-card">
+                            <div class="tech-header">
+                                <div class="tech-icon" style="background: linear-gradient(135deg, #dc2626, #f87171);">Af</div>
+                                <span class="tech-name">Aiofiles</span>
+                                <span class="tech-version">24.1.0</span>
+                            </div>
+                            <p class="tech-description">
+                                Async file operations for non-blocking audio file I/O. Enables concurrent file processing without blocking the event loop.
                             </p>
                         </div>
                     </div>
@@ -809,7 +892,7 @@
                                 <span class="tech-version">Latest</span>
                             </div>
                             <p class="tech-description">
-                                컨테이너화 플랫폼. 일관된 개발/배포 환경 제공
+                                Containerization platform providing consistent development and deployment environments across all systems.
                             </p>
                         </div>
                         <div class="tech-card">
@@ -819,27 +902,47 @@
                                 <span class="tech-version">Latest</span>
                             </div>
                             <p class="tech-description">
-                                멀티 컨테이너 오케스트레이션. 서비스 간 네트워크 및 볼륨 관리
+                                Multi-container orchestration for managing PostgreSQL database service with volume persistence and networking.
                             </p>
                         </div>
                         <div class="tech-card">
                             <div class="tech-header">
-                                <div class="tech-icon" style="background: linear-gradient(135deg, #fbbf24, #fcd34d);">Pt</div>
-                                <span class="tech-name">pytest</span>
-                                <span class="tech-version">Latest</span>
+                                <div class="tech-icon" style="background: linear-gradient(135deg, #64748b, #94a3b8);">Ev</div>
+                                <span class="tech-name">Environment Config</span>
+                                <span class="tech-version">-</span>
                             </div>
                             <p class="tech-description">
-                                테스트 프레임워크. 단위 테스트 및 통합 테스트 실행
+                                Secure configuration management with .env files for API keys (Gemini, ElevenLabs, VoiceKit) and sensitive settings.
                             </p>
                         </div>
                         <div class="tech-card">
                             <div class="tech-header">
-                                <div class="tech-icon" style="background: linear-gradient(135deg, #64748b, #94a3b8);">Ev</div>
-                                <span class="tech-name">python-dotenv</span>
-                                <span class="tech-version">1.2.1</span>
+                                <div class="tech-icon" style="background: linear-gradient(135deg, #16a34a, #4ade80);">Sh</div>
+                                <span class="tech-name">Shell Scripts</span>
+                                <span class="tech-version">Bash</span>
+                            </div>
+                            <p class="tech-description">
+                                Automated deployment scripts (start.sh, stop.sh) for streamlined application lifecycle management.
+                            </p>
+                        </div>
+                        <div class="tech-card">
+                            <div class="tech-header">
+                                <div class="tech-icon" style="background: linear-gradient(135deg, #ea580c, #fb923c);">Hf</div>
+                                <span class="tech-name">HuggingFace</span>
+                                <span class="tech-version">Hub</span>
+                            </div>
+                            <p class="tech-description">
+                                Deployment platform hosting VoiceKit MCP server and application demos with integrated spaces for testing.
+                            </p>
+                        </div>
+                        <div class="tech-card">
+                            <div class="tech-header">
+                                <div class="tech-icon" style="background: linear-gradient(135deg, #9333ea, #a855f7);">Lg</div>
+                                <span class="tech-name">Logging</span>
+                                <span class="tech-version">Built-in</span>
                             </div>
                             <p class="tech-description">
-                                환경 변수 관리. .env 파일 기반 설정 로드
+                                Comprehensive logging system for debugging, monitoring API calls, tracking errors, and performance analysis.
                             </p>
                         </div>
                     </div>

docs/user-guide.html

@@ -3,7 +3,7 @@
 <head>
     <meta charset="UTF-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>User Guide - Komentle Voice Challenge</title>
+    <title>User Guide - Voice Semenetle</title>
     <link href="https://fonts.googleapis.com/css2?family=Nunito:wght@400;600;700;800&display=swap" rel="stylesheet">
     <style>
         :root {
@@ -792,8 +792,8 @@
                                 <div class="metric-label">Pronunciation</div>
                             </div>
                             <div class="metric-item">
-                                <div class="metric-value">Tone</div>
-                                <div class="metric-label">Voice Tone</div>
+                                <div class="metric-value">Line Acc.</div>
+                                <div class="metric-label">Line Accuracy</div>
                             </div>
                             <div class="metric-item">
                                 <div class="metric-value">Pitch</div>
@@ -813,8 +813,8 @@
                     <div class="content-card">
                         <h3>🎯 Score Interpretation</h3>
                         <ul>
-                            <li><strong>80+ points:</strong> Very similar to the answer! You're almost there!</li>
-                            <li><strong>60-79 points:</strong> Good attempt. Check the hints for guidance.</li>
+                            <li><strong>85+ points:</strong> Very similar to the answer! You're almost there!</li>
+                            <li><strong>60-84 points:</strong> Good attempt. Check the hints for guidance.</li>
                             <li><strong>40-59 points:</strong> Right direction, but try a different word.</li>
                             <li><strong>Below 40:</strong> Far from the answer. Try a new guess.</li>
                         </ul>
@@ -840,7 +840,7 @@
                     <div class="content-card">
                         <h3>💬 AI Hint Chatbot</h3>
                         <p>
-                            Click the floating button at the bottom right of the screen to open the AI hint chatbot.
+                            Click the floating button at the top right of the screen to open the AI hint chatbot.
                             Request hints from the chatbot to receive indirect clues about the answer.
                         </p>
                     </div>
@@ -852,16 +852,17 @@
                             <li><strong>"What's the category?":</strong> Learn the classification of the answer word.</li>
                             <li><strong>"Tell me the first letter":</strong> Get a hint about the first letter.</li>
                             <li><strong>"What words sound similar?":</strong> Get pronunciation-related suggestions.</li>
+                            <li><strong>"Give me an audio hint":</strong> AI provides an audio hint in a tone similar to your voice.</li>
                         </ul>
                     </div>
 
-                    <div class="warning-box">
+                    <!-- <div class="warning-box">
                         <span class="warning-icon">💡</span>
                         <div class="warning-text">
                             <strong>Limited Hint Usage!</strong> Chatbot hints can only be used a limited number of times.
                             Request hints carefully!
                         </div>
-                    </div>
+                    </div> -->
                 </section>
 
                 <!-- Tips & Tricks -->

gemini_adapter.py

@@ -88,14 +88,14 @@ def convert_messages_to_gemini_format(anthropic_messages):
             # Could be Gradio file format {"path": ..., "mime_type": ...}
             # Skip audio/video files - they can't be sent to Gemini text API
             if content.get("path") and content.get("mime_type"):
-                print(f"DEBUG convert_messages: Skipping file content: {content.get('mime_type')}")
+                # print(f"DEBUG convert_messages: Skipping file content: {content.get('mime_type')}")
                 continue
             # Could be text content {"type": "text", "text": "..."}
             elif content.get("type") == "text":
                 parts.append(types.Part(text=content.get("text", "")))
         elif hasattr(content, '__class__') and 'Audio' in content.__class__.__name__:
             # Skip Gradio Audio component objects
-            print(f"DEBUG convert_messages: Skipping Gradio component: {content.__class__.__name__}")
+            # print(f"DEBUG convert_messages: Skipping Gradio component: {content.__class__.__name__}")
             continue
         elif isinstance(content, list):
             # Complex content with tool calls/results
@@ -152,11 +152,11 @@ def call_gemini_with_tools(model_name, system_prompt, messages, tools, max_token
         # Convert messages to Gemini format
         contents = convert_messages_to_gemini_format(messages)
 
-        print(f"DEBUG gemini_adapter: Converted {len(messages)} messages to {len(contents)} Contents")
-        print(f"DEBUG gemini_adapter: Tools: {len(gemini_tools[0].function_declarations) if gemini_tools else 0}")
+        # print(f"DEBUG gemini_adapter: Converted {len(messages)} messages to {len(contents)} Contents")
+        # print(f"DEBUG gemini_adapter: Tools: {len(gemini_tools[0].function_declarations) if gemini_tools else 0}")
 
         # Call API
-        print(f"DEBUG gemini_adapter: Calling Gemini API...")
+        # print(f"DEBUG gemini_adapter: Calling Gemini API...")
         client = get_client()
         
         # Generate content (no timeout parameter - not supported)
@@ -175,18 +175,18 @@ def call_gemini_with_tools(model_name, system_prompt, messages, tools, max_token
 
         print(f"DEBUG gemini_adapter: Got response")
 
-        print(f"DEBUG gemini_adapter: Response type: {type(response)}")
-        print(f"DEBUG gemini_adapter: Response has candidates: {hasattr(response, 'candidates')}")
+        # print(f"DEBUG gemini_adapter: Response type: {type(response)}")
+        # print(f"DEBUG gemini_adapter: Response has candidates: {hasattr(response, 'candidates')}")
         if hasattr(response, 'candidates') and response.candidates:
             candidate = response.candidates[0]
-            print(f"DEBUG gemini_adapter: First candidate type: {type(candidate)}")
-            print(f"DEBUG gemini_adapter: finish_reason: {getattr(candidate, 'finish_reason', 'UNKNOWN')}")
+            # print(f"DEBUG gemini_adapter: First candidate type: {type(candidate)}")
+            # print(f"DEBUG gemini_adapter: finish_reason: {getattr(candidate, 'finish_reason', 'UNKNOWN')}")
 
             # Log function calls if present
             if hasattr(candidate, 'content') and candidate.content and hasattr(candidate.content, 'parts') and candidate.content.parts:
                 for i, part in enumerate(candidate.content.parts):
                     if hasattr(part, 'function_call') and part.function_call:
-                        print(f"DEBUG gemini_adapter: Part {i} has function_call: {part.function_call.name}")
+                        # print(f"DEBUG gemini_adapter: Part {i} has function_call: {part.function_call.name}")
                         print(f"DEBUG gemini_adapter: Function args: {dict(part.function_call.args) if part.function_call.args else {}}")
         return response
 
@@ -203,28 +203,28 @@ def extract_tool_calls_from_gemini_response(response):
     """
     tool_calls = []
 
-    print(f"DEBUG extract_tool_calls: Response type: {type(response)}")
-    print(f"DEBUG extract_tool_calls: Has candidates: {hasattr(response, 'candidates')}")
+    # print(f"DEBUG extract_tool_calls: Response type: {type(response)}")
+    # print(f"DEBUG extract_tool_calls: Has candidates: {hasattr(response, 'candidates')}")
 
     if not hasattr(response, 'candidates') or not response.candidates:
-        print(f"DEBUG extract_tool_calls: No candidates found")
+        # print(f"DEBUG extract_tool_calls: No candidates found")
         return tool_calls
 
     candidate = response.candidates[0]
-    print(f"DEBUG extract_tool_calls: Candidate has content: {hasattr(candidate, 'content')}")
+    # print(f"DEBUG extract_tool_calls: Candidate has content: {hasattr(candidate, 'content')}")
 
     if not hasattr(candidate, 'content') or not candidate.content:
-        print(f"DEBUG extract_tool_calls: No content in candidate")
+        # print(f"DEBUG extract_tool_calls: No content in candidate")
         return tool_calls
 
-    print(f"DEBUG extract_tool_calls: Content has parts: {hasattr(candidate.content, 'parts')}")
+    # print(f"DEBUG extract_tool_calls: Content has parts: {hasattr(candidate.content, 'parts')}")
 
     if not hasattr(candidate.content, 'parts') or not candidate.content.parts:
-        print(f"DEBUG extract_tool_calls: No parts in content")
+        # print(f"DEBUG extract_tool_calls: No parts in content")
         return tool_calls
 
     for i, part in enumerate(candidate.content.parts):
-        print(f"DEBUG extract_tool_calls: Part {i} has function_call: {hasattr(part, 'function_call')}")
+        # print(f"DEBUG extract_tool_calls: Part {i} has function_call: {hasattr(part, 'function_call')}")
         if hasattr(part, 'function_call') and part.function_call:
             fc = part.function_call
             tool_calls.append({
@@ -233,7 +233,7 @@ def extract_tool_calls_from_gemini_response(response):
                 "id": f"call_{i}"
             })
 
-    print(f"DEBUG extract_tool_calls: Found {len(tool_calls)} tool calls")
+    # print(f"DEBUG extract_tool_calls: Found {len(tool_calls)} tool calls")
     return tool_calls
 
 def get_text_from_gemini_response(response):
@@ -242,21 +242,21 @@ def get_text_from_gemini_response(response):
     Returns:
         tuple: (text, error_message) where error_message is None if successful
     """
-    print(f"DEBUG get_text: Response type: {type(response)}")
-    print(f"DEBUG get_text: Has candidates: {hasattr(response, 'candidates')}")
+    # print(f"DEBUG get_text: Response type: {type(response)}")
+    # print(f"DEBUG get_text: Has candidates: {hasattr(response, 'candidates')}")
 
     if not hasattr(response, 'candidates') or not response.candidates:
-        print(f"ERROR get_text: No candidates in response")
+        # print(f"ERROR get_text: No candidates in response")
         return "", "No response candidates received from AI. Please try again."
 
     candidate = response.candidates[0]
     finish_reason = getattr(candidate, 'finish_reason', 'UNKNOWN')
-    print(f"DEBUG get_text: Candidate has content: {hasattr(candidate, 'content')}")
-    print(f"DEBUG get_text: finish_reason: {finish_reason}")
+    # print(f"DEBUG get_text: Candidate has content: {hasattr(candidate, 'content')}")
+    # print(f"DEBUG get_text: finish_reason: {finish_reason}")
 
     if not hasattr(candidate, 'content') or not candidate.content:
-        print(f"WARNING get_text: No content in candidate")
-        print(f"WARNING get_text: safety_ratings: {getattr(candidate, 'safety_ratings', 'N/A')}")
+        # print(f"WARNING get_text: No content in candidate")
+        # print(f"WARNING get_text: safety_ratings: {getattr(candidate, 'safety_ratings', 'N/A')}")
 
         # Provide specific error messages based on finish_reason
         if finish_reason == 'SAFETY':
@@ -270,27 +270,27 @@ def get_text_from_gemini_response(response):
         else:
             return "", "AI returned empty response. Please try again."
 
-    print(f"DEBUG get_text: Content has parts: {hasattr(candidate.content, 'parts') if candidate.content else False}")
+    # print(f"DEBUG get_text: Content has parts: {hasattr(candidate.content, 'parts') if candidate.content else False}")
 
     if not candidate.content or not hasattr(candidate.content, 'parts') or not candidate.content.parts:
-        print(f"WARNING get_text: No parts in content")
+        # print(f"WARNING get_text: No parts in content")
         return "", "AI response had no content. Please try again."
 
     text_parts = []
     has_function_call = False
     for i, part in enumerate(candidate.content.parts):
-        print(f"DEBUG get_text: Part {i} has text: {hasattr(part, 'text')}")
+        # print(f"DEBUG get_text: Part {i} has text: {hasattr(part, 'text')}")
         if hasattr(part, 'text') and part.text:
             text_parts.append(part.text)
         if hasattr(part, 'function_call') and part.function_call:
             has_function_call = True
 
     result = " ".join(text_parts)
-    print(f"DEBUG get_text: Extracted text length: {len(result)}, has_function_call: {has_function_call}")
+    # print(f"DEBUG get_text: Extracted text length: {len(result)}, has_function_call: {has_function_call}")
 
     # Empty text is OK if there's a function call (tool-only response)
     if (not result or result.strip() == "") and not has_function_call:
-        print(f"WARNING get_text: Empty text extracted and no function call")
+        # print(f"WARNING get_text: Empty text extracted and no function call")
         return "", "AI returned empty text. Please try again."
 
     return result, None
@@ -321,7 +321,7 @@ def chat_with_gemini_and_tools(system_prompt, messages, tools=None, max_tokens=1
         # Convert tools to Gemini format if provided
         gemini_tools = convert_tools_to_gemini_format(tools) if tools else None
 
-        print(f"DEBUG chat_with_gemini_and_tools: {len(messages)} messages, {len(tools) if tools else 0} tools")
+        # print(f"DEBUG chat_with_gemini_and_tools: {len(messages)} messages, {len(tools) if tools else 0} tools")
 
         # Get client
         client = get_client()
@@ -353,7 +353,7 @@ def chat_with_gemini_and_tools(system_prompt, messages, tools=None, max_tokens=1
             config=config
         )
 
-        print(f"DEBUG chat_with_gemini_and_tools: Got response")
+        # print(f"DEBUG chat_with_gemini_and_tools: Got response")
 
         # Check for tool calls first
         tool_calls = extract_tool_calls_from_gemini_response(response)
@@ -363,13 +363,13 @@ def chat_with_gemini_and_tools(system_prompt, messages, tools=None, max_tokens=1
 
         # If there's an error but we have tool calls, that's OK (tool-only response)
         if error and not tool_calls:
-            print(f"ERROR chat_with_gemini_and_tools: {error}")
+            # print(f"ERROR chat_with_gemini_and_tools: {error}")
             return "", None, error
         elif error and tool_calls:
-            print(f"DEBUG chat_with_gemini_and_tools: Error '{error}' but have {len(tool_calls)} tool calls, proceeding")
+            # print(f"DEBUG chat_with_gemini_and_tools: Error '{error}' but have {len(tool_calls)} tool calls, proceeding")
             text = ""  # Clear any error text
 
-        print(f"DEBUG chat_with_gemini_and_tools: text={len(text)} chars, tool_calls={len(tool_calls) if tool_calls else 0}")
+        # print(f"DEBUG chat_with_gemini_and_tools: text={len(text)} chars, tool_calls={len(tool_calls) if tool_calls else 0}")
         return text, tool_calls if tool_calls else None, None
 
     except Exception as e:
@@ -398,8 +398,8 @@ def chat_with_gemini(system_prompt, messages, max_tokens=1024, temperature=1.0,
         # Convert messages to Gemini format
         contents = convert_messages_to_gemini_format(messages)
 
-        print(f"DEBUG chat_with_gemini: Converted {len(messages)} messages to {len(contents)} Contents")
-        print(f"DEBUG chat_with_gemini: Calling Gemini API with model {model_name}")
+        # print(f"DEBUG chat_with_gemini: Converted {len(messages)} messages to {len(contents)} Contents")
+        # print(f"DEBUG chat_with_gemini: Calling Gemini API with model {model_name}")
 
         # Get client
         client = get_client()
@@ -418,16 +418,16 @@ def chat_with_gemini(system_prompt, messages, max_tokens=1024, temperature=1.0,
             config=config
         )
 
-        print(f"DEBUG chat_with_gemini: Got response")
+        # print(f"DEBUG chat_with_gemini: Got response")
 
         # Extract text
         text, error = get_text_from_gemini_response(response)
 
         if error:
-            print(f"ERROR chat_with_gemini: {error}")
+            # print(f"ERROR chat_with_gemini: {error}")
             return "", error
 
-        print(f"DEBUG chat_with_gemini: Successfully extracted text ({len(text)} chars)")
+        # print(f"DEBUG chat_with_gemini: Successfully extracted text ({len(text)} chars)")
         return text, None
 
     except Exception as e:

gradio_ui.py

@@ -149,7 +149,7 @@ def get_today_puzzle():
 
         # Use backend function to get puzzle
         puzzle = get_puzzle_by_date(today)
-        print(puzzle)
+        # print(puzzle)
         if puzzle:
             return f"""
 ### 📅 오늘의 퍼즐
@@ -240,8 +240,6 @@ with gr.Blocks(title="Chloe's Voice Komentle") as demo:
 
 # Launch configuration
 if __name__ == "__main__":
-    print("🚀 Starting Chloe's Voice Komentle...")
-
     # Initialize backend (VoiceKit MCP session)
     print("⏳ Initializing VoiceKit MCP...")
 

inspect_routes.py

@@ -13,7 +13,7 @@ os.environ["BACKEND_API_URL"] = ""
 try:
     from client.app import app
     print("Successfully imported app")
-    print("Routes:")
+    # print("Routes:")
     for route in app.routes:
         print(f"  {route.path} ({type(route).__name__})")
 except Exception as e:

test_analyze_voice.py

@@ -128,9 +128,9 @@ async def test_analyze_voice(audio_file, date: str, session_id: str, generate_ne
         with open(audio_path, "rb") as f:
             audio_bytes = f.read()
         
-        print(f"📁 Audio file size: {len(audio_bytes)} bytes")
-        print(f"📅 Date: {date}")
-        print(f"🆔 Session ID: {session_id}")
+        # print(f"📁 Audio file size: {len(audio_bytes)} bytes")
+        # print(f"📅 Date: {date}")
+        # print(f"🆔 Session ID: {session_id}")
         
         # Call the function
         result = await analyze_voice_logic(audio_bytes, date, session_id)
@@ -247,15 +247,15 @@ with gr.Blocks(title="Analyze Voice Logic Test") as demo:
 
 
 if __name__ == "__main__":
-    print("=" * 60)
-    print("🎤 Analyze Voice Logic Test Page")
-    print("=" * 60)
-    print("\n✅ 사전 준비:")
-    print("   1. PostgreSQL 실행: docker-compose up -d postgres")
-    print("   2. 환경변수 설정: GOOGLE_API_KEY, DATABASE_URL")
-    print("   3. VoiceKit MCP 서버 (외부): 자동 연결")
-    print("\n💡 이 페이지는 독립적으로 실행됩니다 (Backend 서버 불필요)")
-    print("\n" + "=" * 60 + "\n")
+    # print("=" * 60)
+    # print("🎤 Analyze Voice Logic Test Page")
+    # print("=" * 60)
+    # print("\n✅ 사전 준비:")
+    # print("   1. PostgreSQL 실행: docker-compose up -d postgres")
+    # print("   2. 환경변수 설정: GOOGLE_API_KEY, DATABASE_URL")
+    # print("   3. VoiceKit MCP 서버 (외부): 자동 연결")
+    # print("\n💡 이 페이지는 독립적으로 실행됩니다 (Backend 서버 불필요)")
+    # print("\n" + "=" * 60 + "\n")
     
     demo.launch(
         server_name="127.0.0.1",