initial commit

.gitattributes

@@ -0,0 +1,35 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,114 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Project specific - Test and temporary files (but keep leaderboard_results.csv)
+# leaderboard_results.csv  # 주석 처리하여 Git 추적 허용
+evaluation_results.json
+test_model_responses.csv
+*.log
+
+# Private data (민감한 데이터)
+#data/private/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# pytest
+.pytest_cache/
+.coverage
+htmlcov/
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Gradio temporary files
+gradio_cached_examples/
+flagged/
+
+# Lock files for file locking mechanism
+*.lock
+
+# MacOS specific
+.AppleDouble
+.LSOverride
+Icon
+
+# Thumbnails
+._*
+
+# Files that might appear in the root of a volume
+.DocumentRevisions-V100
+.fseventsd
+.TemporaryItems
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+
+# Directories potentially created on remote AFP share
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk
+
+# Setup artifacts and temporary files
+=*.*
+fix_setup.sh
+install_dependencies.sh
+step_by_step.sh
+simple_test.py
+
+# Data
+freshqa/freshqa_prompt.py

Dockerfile

@@ -0,0 +1,36 @@
+FROM python:3.9-slim
+
+WORKDIR /app
+
+# 시스템 패키지 업데이트 및 타임존 설정
+RUN apt-get update && apt-get install -y \
+    git \
+    curl \
+    tzdata \
+    && rm -rf /var/lib/apt/lists/*
+
+# 타임존을 Asia/Seoul로 설정
+ENV TZ=Asia/Seoul
+RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone
+
+# Python 의존성 설치
+COPY requirements.txt .
+RUN pip install --no-cache-dir --upgrade pip
+RUN pip install --no-cache-dir -r requirements.txt
+
+# 애플리케이션 파일 복사
+COPY . .
+
+# 권한 설정
+RUN chmod +x quick_start.sh
+
+# 환경변수 설정
+ENV PYTHONPATH=/app
+ENV GRADIO_SERVER_NAME=0.0.0.0
+ENV GRADIO_SERVER_PORT=7860
+
+# 포트 노출
+EXPOSE 7860
+
+# 기본 명령어
+CMD ["python", "app.py"]

README.md

@@ -0,0 +1,153 @@
+---
+title: Ko-FreshQA Leaderboard
+emoji: 🚀
+colorFrom: blue
+colorTo: green
+sdk: gradio
+app_file: app.py
+pinned: false
+license: apache-2.0
+---
+
+## Ko-FreshQA Leaderboard
+한국어 FreshQA 기반 자동 평가/리더보드 시스템입니다. 참가자가 업로드한 CSV의 `model_response`를 기준 데이터와 매칭하고, Upstage Solar 모델로 Relaxed/Strict 평가를 수행한 뒤 결과를 리더보드에 반영합니다. Gradio UI로 실행됩니다.
+
+### 핵심 기능
+- 데이터셋 배포: DEV/TEST CSV 다운로드 탭 제공
+- 제출 및 자동 평가: 업로드된 CSV를 병합 → 평가 → 지표 집계 → 리더보드 반영
+- 상세 지표: fact type, 전제 유효성(vp/fp), hop(one/multi), 연도(old/new), 도메인별 정확도
+- 제출 제한(옵션): 사용자별 하루 3회 제한 기능 (Hugging Face 저장소 기반)
+
+---
+
+## 디렉터리 구조
+- `app.py`: Gradio 앱 초기화 및 탭 구성
+- `config.py`: 환경변수 로드 및 필수 설정 검증
+- `freshqa/`
+  - `fresheval.py`: 단일 샘플 평가 로직
+  - `fresheval_parallel.py`: 데이터프레임 병렬 평가 래퍼
+  - `freshqa_acc.py`: 평가 결과 집계(정확도 계산 및 도메인별 통계)
+  - `merge_csv_with_model_response.py`: 기준 데이터와 사용자 CSV 병합
+- `src/`
+  - `submission_handler.py`: 제출부터 리더보드 반영까지 전체 오케스트레이션
+  - `submission_tracker.py`: 제출 이력 추적(HF repo 기반, 옵션)
+  - `leaderboard_manager.py`: 리더보드 CSV 로드/저장/표시용 정리
+  - `quick_csv_loader.py`, `hf_private_csv_loader.py`: HF Private repo에서 CSV 로드 유틸
+  - `api_key_rotator.py`, `utils.py`: 유틸리티
+- `ui/`
+  - `leaderboard_tab.py`, `submission_tab.py`, `dataset_tab.py`, `styles.css`
+- `data/leaderboard_results.csv`: 리더보드 누적 데이터
+
+---
+
+## 요구 사항
+- Python 3.10
+- Upstage API 키(단일 또는 다중)
+- Hugging Face 토큰(HF Private repo 접근용)
+- Hugging Face Dataset repo
+  - 기준 데이터: `FRESHQA_DATA_REPO_ID` / `FRESHQA_DATA_FILENAME`
+  - (옵션) 제출 추적 저장소: `SUBMISSION_TRACKER_REPO_ID`
+
+설치:
+```bash
+python -m venv venv && source venv/bin/activate
+pip install -r requirements.txt
+```
+
+또는 Conda:
+```bash
+conda env create -f environment.yml
+conda activate freshqa-leaderboard
+```
+
+---
+
+## 환경 변수(.env)
+`env.example`를 `.env`로 복사 후 값 채우기:
+```bash
+cp env.example .env
+```
+
+필수/주요 변수
+- HF_TOKEN
+- FRESHQA_DATA_REPO_ID
+- FRESHQA_DATA_FILENAME (기본값: ko-freshqa_2025_total.csv)
+- UPSTAGE_API_KEY 또는 UPSTAGE_API_KEYS(콤마 구분)
+- ENABLE_SUBMISSION_LIMIT (기본: true)
+- SUBMISSION_TRACKER_REPO_ID (제출 제한 사용 시 필요)
+
+검증: 앱 시작 시 `Config.validate_required_configs()`가 누락된 필수 설정을 검사합니다.
+
+---
+
+## 실행
+로컬:
+```bash
+python app.py
+```
+기본 포트: 7860
+
+Hugging Face Spaces:
+- 환경변수 `SPACE_ID`가 존재하면 Spaces 모드로 동작합니다.
+
+Docker(옵션):
+- `Dockerfile`, `docker-compose.yml` 제공 (필요 시 설정에 맞게 수정)
+
+---
+
+## 사용 방법(Gradio UI)
+1) 데이터셋 탭
+- DEV/TEST CSV 다운로드
+
+2) 제출 및 평가 탭
+- 업로드: TEST CSV에 `model_response`가 채워진 파일
+- 입력: 제출자 이름, 사용 모델, 설명
+- 평가: Upstage Solar 모델로 Relaxed/Strict 동시 수행
+- 출력: 전체/세부 지표가 계산되어 리더보드에 반영
+
+3) 리더보드 탭
+- 제출 결과가 `data/leaderboard_results.csv`에 누적
+- 검색/새로고침 가능
+
+---
+
+## 동작 흐름(내부)
+1) 제출 접수: `src/submission_handler.py::process_submission`
+2) 사용자 CSV 로드 → 기준 데이터와 병합:
+   - `freshqa/merge_csv_with_model_response.py::merge_dataframe_with_model_response_df`
+3) 평가:
+   - `freshqa/fresheval_parallel.py::evaluate_dataframe` → `freshqa/fresheval.py::FreshEval`
+4) 정확도 집계:
+   - `freshqa/freshqa_acc.py::calculate_accuracy`, `process_freshqa_dataframe`
+5) 저장:
+   - 리더보드: `src/leaderboard_manager.py::append_to_leaderboard_data`
+   - (옵션) 제출 이력: `src/submission_tracker.py` (ENABLE_SUBMISSION_LIMIT=true 일 때만)
+
+주의: `ENABLE_SUBMISSION_LIMIT=false`인 경우, 제출 이력 추적용 Hugging Face 저장소 접근을 시도하지 않도록 코드가 반영되어 있습니다.
+
+---
+
+## 제출 제한(옵션)
+- 설정: `ENABLE_SUBMISSION_LIMIT=true`(기본)
+- 저장소: `SUBMISSION_TRACKER_REPO_ID`에 `user_submissions.json` 관리
+- 로직:
+  - 한 사용자 하루 3회 성공 제출까지 카운트
+  - 한국 시간 기준 00:00에 일자 단위로 카운트
+  - 비활성화 시(HF 저장소 접근 없음): `SubmissionHandler`가 추적기를 생성하지 않음
+
+---
+
+## 트러블슈팅
+- 시작 시 “필수 설정 누락” 오류
+  - `.env`에서 `UPSTAGE_API_KEY(or KEYS)`, `HF_TOKEN`, `FRESHQA_DATA_REPO_ID` 확인
+- 제출 제한 비활성화인데 HF 404 경고가 보임
+  - 현 버전은 `ENABLE_SUBMISSION_LIMIT=false`일 때 제출 추적기를 초기화하지 않도록 수정됨
+- HF 404 (제출 제한 활성화)
+  - `SUBMISSION_TRACKER_REPO_ID` 저장소에 `user_submissions.json`이 없으면 최초 접근 시 404가 날 수 있습니다. 파일을 빈 JSON `{}`으로 생성해 두세요.
+
+---
+
+## 라이선스/출처
+- 본 리더보드는 FreshQA에서 영감을 받아 제작되었습니다.
+
+문의 사항은 이슈로 등록해 주세요.

app.py

@@ -0,0 +1,96 @@
+"""
+Ko-FreshQA Leaderboard 메인 애플리케이션
+
+Gradio 기반의 웹 인터페이스를 제공합니다.
+"""
+
+import os
+import gradio as gr
+from config import Config
+from ui.leaderboard_tab import create_leaderboard_tab
+from ui.submission_tab import create_submission_tab
+from ui.dataset_tab import create_dataset_tab
+
+
+def load_css():
+    """CSS 파일 로드"""
+    current_dir = os.path.dirname(os.path.abspath(__file__))
+    css_path = os.path.join(current_dir, 'ui', 'styles.css')
+    
+    try:
+        with open(css_path, 'r', encoding='utf-8') as f:
+            return f.read()
+    except FileNotFoundError:
+        print("⚠️ CSS 파일을 찾을 수 없습니다: {css_path}")
+        raise FileNotFoundError(f"CSS 파일을 찾을 수 없습니다: {css_path}")
+
+
+def create_interface():
+    """메인 인터페이스 생성"""
+    
+    css_content = load_css()
+    
+    with gr.Blocks(
+        title="Ko-FreshQA Leaderboard", 
+        theme=gr.themes.Soft(),
+        css=css_content
+    ) as app:
+        gr.Markdown("# Ko-FreshQA Leaderboard")
+
+        with gr.Tabs():
+            # 리더보드 탭
+            with gr.Tab("🏆 리더보드"):
+                create_leaderboard_tab()
+            
+            # 제출 및 평가 탭
+            with gr.Tab("📤 제출 및 평가"):
+                create_submission_tab()
+            
+            # 데이터셋 다운로드 탭
+            with gr.Tab("💾 데이터셋"):
+                create_dataset_tab()
+    
+    return app
+
+
+def main():
+    """메인 실행 함수"""
+    print("🇰🇷 한국어 FreshQA 리더보드 시작 중...")
+    print("📋 리더보드 제출을 위해서는 '📤 제출 및 평가' 탭을 사용하세요.")
+    
+    # 필수 설정 검증
+    try:
+        Config.validate_required_configs()
+        print("✅ 필수 설정 검증 완료")
+    except ValueError as e:
+        print(f"❌ 설정 오류: {e}")
+        import sys
+        sys.exit(1)
+    
+    app = create_interface()
+    
+    # Hugging Face Spaces 환경 감지
+    is_huggingface_spaces = Config.IS_HUGGINGFACE_SPACES
+    
+    if is_huggingface_spaces:
+        print("🚀 Hugging Face Spaces 환경에서 실행 중...")
+        app.launch(
+            server_name="0.0.0.0",
+            server_port=7860,
+            share=False,
+            debug=False,
+            show_error=True
+        )
+    else:
+        print("💻 로컬 환경에서 실행 중...")
+        app.launch(
+            server_name="127.0.0.1",
+            server_port=7860,
+            share=False,
+            debug=True,
+            show_error=True
+        )
+
+
+if __name__ == "__main__":
+    main()

config.py

@@ -0,0 +1,76 @@
+"""
+설정 관리 모듈
+애플리케이션의 모든 설정을 중앙에서 관리합니다.
+"""
+
+import os
+from dotenv import load_dotenv
+
+# .env 파일 로드
+load_dotenv()
+
+class Config:
+    """애플리케이션 설정 클래스"""
+    
+    # API 설정
+    # 멀티 키 지원: UPSTAGE_API_KEYS(콤마 구분) 우선, 없으면 단일 키 사용
+    _UPSTAGE_API_KEYS_RAW = os.getenv('UPSTAGE_API_KEYS')
+    if _UPSTAGE_API_KEYS_RAW:
+        _parsed_keys = [k.strip() for k in _UPSTAGE_API_KEYS_RAW.split(',') if k.strip()]
+    else:
+        _single = os.getenv('UPSTAGE_API_KEY')
+        _parsed_keys = [
+            _single.strip()
+        ] if (_single and _single.strip()) else []
+
+    # 공개 속성: 호환성을 위해 첫 번째 키를 기존 이름으로 노출
+    UPSTAGE_API_KEYS = _parsed_keys
+    UPSTAGE_API_KEY = _parsed_keys[0] if _parsed_keys else None
+    HF_TOKEN = os.getenv('HF_TOKEN')
+    
+    # 데이터 설정
+    FRESHQA_DATA_REPO_ID = os.getenv('FRESHQA_DATA_REPO_ID')
+    FRESHQA_DATA_FILENAME = os.getenv('FRESHQA_DATA_FILENAME', 'ko-freshqa_2025_total.csv')
+    
+    # 프롬프트 설정
+    # 멀티라인 값 지원: python-dotenv가 로드한 원문을 그대로 사용
+    FRESHQA_PROMPT_RELAXED = os.getenv('FRESHQA_PROMPT_RELAXED')
+    FRESHQA_PROMPT_STRICT = os.getenv('FRESHQA_PROMPT_STRICT')
+    try:
+        from freshqa.freshqa_prompt import FRESHQA_PROMPT_RELAXED, FRESHQA_PROMPT_STRICT
+        if not FRESHQA_PROMPT_RELAXED:
+            FRESHQA_PROMPT_RELAXED = FRESHQA_PROMPT_RELAXED
+        if not FRESHQA_PROMPT_STRICT:
+            FRESHQA_PROMPT_STRICT = FRESHQA_PROMPT_STRICT
+    except Exception as e:
+        pass
+    
+    # 제출 제한 설정
+    ENABLE_SUBMISSION_LIMIT = os.getenv('ENABLE_SUBMISSION_LIMIT', 'true').lower() == 'true'
+    SUBMISSION_TRACKER_REPO_ID = os.getenv('SUBMISSION_TRACKER_REPO_ID')
+    
+    # 환경 설정
+    IS_HUGGINGFACE_SPACES = os.getenv("SPACE_ID") is not None
+    
+    @classmethod
+    def validate_required_configs(cls):
+        """필수 설정들이 모두 있는지 확인"""
+        missing_configs = []
+        
+        # 멀티/단일 키 모두 허용: 최소 1개 키가 존재해야 함
+        if not cls.UPSTAGE_API_KEYS:
+            # 메시지는 두 변수 모두 안내
+            missing_configs.append('UPSTAGE_API_KEY or UPSTAGE_API_KEYS')
+        if not cls.HF_TOKEN:
+            missing_configs.append('HF_TOKEN')
+        if not cls.FRESHQA_DATA_REPO_ID:
+            missing_configs.append('FRESHQA_DATA_REPO_ID')
+        if not cls.FRESHQA_PROMPT_RELAXED:
+            missing_configs.append('FRESHQA_PROMPT_RELAXED')
+        if not cls.FRESHQA_PROMPT_STRICT:
+            missing_configs.append('FRESHQA_PROMPT_STRICT')
+            
+        if missing_configs:
+            raise ValueError(f"필수 설정이 누락되었습니다: {', '.join(missing_configs)}")
+        
+        return True

data/leaderboard_results.csv

@@ -0,0 +1 @@
+id,model,description,accuracy,fast_changing_accuracy,slow_changing_accuracy,never_changing_accuracy,acc_vp,acc_fp,acc_vp_one_hop,acc_vp_two_hop,acc_fp_one_hop,acc_fp_two_hop,acc_vp_old,acc_vp_new,acc_fp_old,acc_fp_new,acc_politics,acc_sports,acc_entertainment,acc_weather,acc_world,acc_economy,acc_society,acc_it_science,acc_life_culture,acc_unknown,total_questions,evaluation_date,evaluation_mode

docker-compose.yml

@@ -0,0 +1,19 @@
+version: '3.8'
+
+services:
+  freshqa-leaderboard:
+    build: .
+    ports:
+      - "7860:7860"
+    environment:
+      - UPSTAGE_API_KEY=${UPSTAGE_API_KEY}
+    volumes:
+      - ./datasets:/app/datasets
+      - ./results:/app/results
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:7860/"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 40s

env.example

@@ -0,0 +1,97 @@
+# ===========================================
+# FreshQA Leaderboard 환경변수 설정 예시
+# ===========================================
+
+# ===========================================
+# Hugging Face 설정
+# ===========================================
+# Hugging Face API 토큰 (필수)
+# - Private repository 접근용
+# - https://huggingface.co/settings/tokens 에서 발급
+HF_TOKEN=your_huggingface_token_here
+
+# ===========================================
+# FreshQA 기준 데이터 설정
+# ===========================================
+# 기준 데이터가 있는 HuggingFace Repository ID (필수)
+# 형식: username/repository-name
+FRESHQA_DATA_REPO_ID=james-demo-leaderboard-backend/kofreshqa-data-origin
+
+# 기준 데이터 파일명 (선택사항, 기본값: ko-freshqa_2025_total.csv)
+FRESHQA_DATA_FILENAME=ko-freshqa_2025_total.csv
+
+# ===========================================
+# FreshQA 프롬프트 설정
+# ===========================================
+# Fresheval 프롬프트 본문
+# 평가 프롬프트는 제공하지 않습니다.
+FRESHQA_PROMPT_RELAXED=
+FRESHQA_PROMPT_STRICT=
+
+# ===========================================
+# 제출 추적 설정
+# ===========================================
+# 제출 기록을 저장할 HuggingFace Repository ID (필수)
+# 형식: username/repository-name
+SUBMISSION_TRACKER_REPO_ID=james-demo-leaderboard-backend/submission-tracker
+
+# 제출 제한 기능 활성화 여부 (선택사항, 기본값: true)
+# - true: 제출 제한 기능 활성화 (하루 3회 제한)
+# - false: 제출 제한 기능 비활성화 (로컬 테스트용)
+ENABLE_SUBMISSION_LIMIT=true
+
+# ===========================================
+# AI 평가 API 설정
+# ===========================================
+# Upstage Solar Pro API 키 (필수)
+# - 모델 평가용
+# - https://console.upstage.ai/ 에서 발급
+UPSTAGE_API_KEY=your_upstage_api_key_here
+
+# 여러 개의 Upstage API 키를 사용할 경우(선택사항)
+# - 콤마로 구분하여 입력
+# - 설정 로더는 UPSTAGE_API_KEYS가 존재하면 이를 우선 사용하고,
+#   없으면 단일 변수 UPSTAGE_API_KEY를 사용합니다.
+# 예시)
+# UPSTAGE_API_KEYS=keyA,keyB,keyC
+
+# ===========================================
+# 애플리케이션 설정
+# ===========================================
+# 서버 포트 (선택사항, 기본값: 7860)
+# PORT=7860
+
+# 디버그 모드 (선택사항, 기본값: false)
+# DEBUG=false
+
+# ===========================================
+# 사용 예시
+# ===========================================
+# 1. 이 파일을 .env로 복사하세요:
+#    cp env.example .env
+#
+# 2. 실제 값으로 변경하세요:
+#    - HF_TOKEN: 실제 HuggingFace 토큰
+#    - FRESHQA_DATA_REPO_ID: 실제 repository ID
+#    - FRESHQA_DATA_FILENAME: 실제 파일명 (선택사항)
+#    - SUBMISSION_TRACKER_REPO_ID: 제출 추적용 repository ID
+#    - ENABLE_SUBMISSION_LIMIT: 제출 제한 기능 활성화 여부 (로컬 테스트 시 false)
+#    - UPSTAGE_API_KEY: 실제 Upstage API 키
+#
+# 3. Python에서 자동 로드됨 (app.py에서 load_dotenv() 호출)
+#    또는 수동으로 로드:
+#    from dotenv import load_dotenv
+#    load_dotenv()
+#
+# 4. 또는 직접 환경변수 설정 (시스템 레벨):
+#    export HF_TOKEN="your_token"
+#    export FRESHQA_DATA_REPO_ID="username/repo"
+#    export FRESHQA_DATA_FILENAME="filename.csv"
+#    export UPSTAGE_API_KEY="your_api_key"
+
+# ===========================================
+# 보안 주의사항
+# ===========================================
+# - .env 파일은 절대 Git에 커밋하지 마세요
+# - 실제 토큰과 API 키는 안전하게 보관하세요
+# - 프로덕션 환경에서는 환경변수로 직접 설정하세요

environment.yml

@@ -0,0 +1,21 @@
+name: freshqa-leaderboard
+channels:
+  - conda-forge
+  - defaults
+dependencies:
+  - python=3.9
+  - pip
+  - numpy>=1.24.0
+  - pandas>=2.0.0
+  - requests>=2.25.0
+  - pip:
+    - gradio>=5.0.0
+    - plotly>=5.0.0
+    - pytz>=2023.3
+    - python-dateutil>=2.8.0
+    - openpyxl>=3.0.0
+    - httpx>=0.24.0
+    - seaborn>=0.12.0
+    - matplotlib>=3.7.0
+    - tqdm>=4.65.0
+    - huggingface_hub<1.0.0

freshqa/fresheval.py

@@ -0,0 +1,358 @@
+import re
+import pandas as pd
+from openai import OpenAI
+from typing import List, Dict, Any, Tuple
+import time
+import random
+
+from config import Config
+from src.utils import get_current_date_str
+
+class FreshEval:
+
+    def __init__(self, model: str='solar-pro2', api_key: str=None):
+        self.model = model
+        self.api_key = api_key or Config.UPSTAGE_API_KEY
+        self.client = OpenAI(
+            api_key=self.api_key,
+            base_url="https://api.upstage.ai/v1/solar"
+        )
+
+        self.temperature = 0.0
+        self.max_tokens = 256
+        self.chat_completions = True
+
+        if model.startswith('gpt-4') | model.startswith('solar'):
+            self.num_organic_results = 15
+            self.num_related_questions = 3
+            self.num_questions_and_answers = 3
+            self.num_retrieved_evidences = 15
+        else:
+            self.num_organic_results = 15
+            self.num_related_questions = 2
+            self.num_questions_and_answers = 2
+            self.num_retrieved_evidences = 5
+
+
+    def _is_rate_limit_error(self, error: Exception) -> bool:
+        """429 에러 감지 함수"""
+        error_str = str(error)
+        error_type = type(error).__name__
+        
+        # 1. HTTP 상태 코드 확인
+        if hasattr(error, 'response') and hasattr(error.response, 'status_code'):
+            if error.response.status_code == 429:
+                print(f"✅ HTTP 429 에러 감지: {error.response.status_code}")
+                return True
+        
+        # 2. 텍스트 기반 감지 (백업)
+        error_lower = error_str.lower()
+        if ("429" in error_lower or 
+            "rate" in error_lower or 
+            "limit" in error_lower or
+            "too_many_requests" in error_lower or
+            "request limit" in error_lower):
+            # print(f"✅ 텍스트 기반 429 에러 감지")
+            return True
+        
+        return False
+
+
+    def call_llm_api(self, prompt:str, current_date:str) -> str:
+        """LLM API 호출 함수 (키 회전 및 백오프 지원)"""
+        from src.api_key_rotator import get_rotator
+        
+        rotator = get_rotator()
+        num_keys = len(rotator.keys)
+        base_delay = 3.0
+        
+        def _make_api_call(eval_instance: FreshEval) -> str:
+            """API 호출 헬퍼 함수"""
+            if eval_instance.chat_completions:
+                # Chat completions API
+                response = eval_instance.client.chat.completions.create(
+                    model=eval_instance.model,
+                    temperature=eval_instance.temperature,
+                    max_tokens=eval_instance.max_tokens,
+                    messages=[
+                        {
+                            "role": "system", 
+                            "content": (
+                                f"You are a helpful assistant. Respond as concisely as possible. Knowledge cutoff: {current_date}."
+                            )
+                        },
+                        {
+                            "role": "user",
+                            "content": "What's today's date?"
+                        },
+                        {
+                            "role": "assistant",
+                            "content": f"Today is {current_date} in Pacific Standard Time."
+                        },
+                        {
+                            "role": "user",
+                            "content": prompt
+                        }
+                    ],
+                )
+                return response.choices[0].message.content
+            else:
+                # Completions API
+                response = eval_instance.client.completions.create(
+                    model=eval_instance.model,
+                    temperature=eval_instance.temperature,
+                    max_tokens=eval_instance.max_tokens,
+                    prompt=prompt,
+                )
+                return response.choices[0].text
+        
+        # 현재 키로 시작
+        current_key = self.api_key
+        current_instance = FreshEval(model=self.model, api_key=current_key)
+        
+        # 키가 1개인 경우: 기존 백오프 로직만 사용
+        if num_keys == 1:
+            max_retries = 7
+            for attempt in range(max_retries):
+                try:
+                    return _make_api_call(current_instance)
+                except Exception as e:
+                    if self._is_rate_limit_error(e):
+                        if attempt < max_retries - 1:
+                            # 지수적 백오프
+                            delay = base_delay * (2 ** attempt) + random.uniform(0, 1)
+                            time.sleep(delay)
+                            continue
+                        else:
+                            print(f"❌ 최대 재시도 횟수 초과")
+                    raise e
+
+            # max_retries 초과할 때까지 return 되지 않으면 에러 발생
+            raise Exception("call llm api:최대 재시도 횟수 초과")
+        
+        # 키가 2개 이상인 경우: 키 전환 로직 (3초 대기 포함)
+        # 성공할 때까지 키를 순환하며 시도 (최대 모든 키를 3바퀴까지)
+        max_attempts = num_keys * 3  # 모든 키를 최대 3바퀴까지 시도
+        key_attempt_count = 0
+        
+        # 현재 키로 첫 시도
+        for attempt in range(max_attempts):
+            try:
+                return _make_api_call(current_instance)  # 성공하면 즉시 반환
+            except Exception as e:
+                if self._is_rate_limit_error(e):
+                    key_attempt_count += 1
+                    # 다음 키로 전환하기 전에 2초 대기
+                    time.sleep(2)
+                    current_key = rotator.pick_key()
+                    # print("🔑 키 전환")
+                    current_instance = FreshEval(model=self.model, api_key=current_key)
+                    continue  # 다음 키로 계속 시도
+                else:
+                    # 429가 아닌 에러는 즉시 전파
+                    raise
+        
+        # 최대 시도 횟수 초과 (모든 키를 여러 바퀴 시도했지만 모두 실패)
+        raise Exception(f"모든 API 키에서 429 에러 발생 (최대 {max_attempts}회 시도)")
+
+
+    def call_fresheval(self, mode:str, question:str, evaluation:str, current_date:str) -> str:
+        """FreshEval 평가 함수"""
+
+        fresheval_question = f'\nquestion: {question}{evaluation}'
+
+        # 환경변수 기반 프롬프트(본체: prefix + demo) 우선 사용
+        env_prompt_body = None
+        if mode == 'Relaxed':
+            env_prompt_body = Config.FRESHQA_PROMPT_RELAXED
+        elif mode == 'Strict':
+            env_prompt_body = Config.FRESHQA_PROMPT_STRICT
+
+        if env_prompt_body and str(env_prompt_body).strip():
+            base_prompt = str(env_prompt_body).strip()
+        else:
+            raise ValueError(f"{mode} 평가 프롬프트 설정이 없습니다.")
+
+        fresheval_prompt = base_prompt + fresheval_question
+        
+        # 평가
+        answer = self.call_llm_api(fresheval_prompt, current_date)
+
+        return answer
+
+
+    def extract_ratings(self, response:str) -> Tuple[bool, Dict[str, str]]:
+        """평가 결과에서 등급 추출"""
+        def _clean(text: str) -> str:
+            # 양끝 장식/공백 제거 + 내부 흔적 정리 + 소문자화
+            text = re.sub(r'^[*`_~\s]+|[*`_~\s]+$', '', text)
+            text = re.sub(r'[*`_~]', '', text)
+            return text.strip().strip('.').strip().lower()
+
+        def _judge(val: str):
+            """
+            문자열에서 correct/incorrect 판정.
+            - 'incorrect'가 보이면 무조건 FALSE
+            - 'partially correct'는 모호 → None
+            - 'correct'는 TRUE
+            """
+            if re.search(r'(?i)\bincorrect\b', val):
+                return 'FALSE'
+            if re.search(r'(?i)\bpartial(?:ly)?\s+correct\b', val):
+                return None
+            if re.search(r'(?i)\bcorrect\b', val):
+                return 'TRUE'
+            return None
+
+        def _from_label(block_label: str):
+            """
+            라벨(예: 'Final Evaluation' 또는 'Evaluation') 기준으로
+            - 같은 줄 캡처 먼저 시도
+            - 실패하면 라벨 이후 ~ 다음 빈 줄 이전 범위에서 판정 키워드 탐색
+            """
+            # 같은 줄 캡처: 라벨 ± 장식 ± 콜론 이후 ~ 줄끝
+            same_line = re.search(
+                rf'(?i){block_label}\s*(?:[*`_~]*\s*:\s*|:\s*[*`_~]*)\s*([^\r\n]+)',
+                response
+            )
+            if same_line:
+                val = _clean(same_line.group(1))
+                j = _judge(val)
+                if j is not None:
+                    return j
+
+            # 위치만 찾고(값 없이 줄바꿈된 케이스), 다음 빈 줄(or 섹션) 전까지 스캔
+            pos = re.search(
+                rf'(?i){block_label}\s*(?:[*`_~]*\s*:\s*|:\s*[*`_~]*)',
+                response
+            )
+            if pos:
+                tail = response[pos.end():]
+                # 다음 '빈 줄(연속 개행)' 또는 다음 섹션 시작 전까지만 본다 (너무 멀리 안가도록)
+                m_stop = re.search(r'\n\s*\n', tail)
+                segment = tail[:m_stop.start()] if m_stop else tail[:300]  # 안전한 상한
+                seg_clean = _clean(segment)
+                j = _judge(seg_clean)
+                if j is not None:
+                    return j
+            return None
+
+        # 1) Final Evaluation 최우선
+        final_judgement = _from_label('final\s+evaluation')
+        if final_judgement:
+            return True, {'rating': final_judgement}
+
+        # 2) Evaluation
+        eval_judgement = _from_label('evaluation')
+        if eval_judgement:
+            return True, {'rating': eval_judgement}
+
+        # 3) 폴백: credited 문장
+        if re.search(r'(?i)thus,\s*the\s*response\s*is\s*credited\b', response):
+            return True, {'rating': 'TRUE'}
+        if re.search(r'(?i)thus,\s*the\s*response\s*is\s*not\s*credited\b', response):
+            return True, {'rating': 'FALSE'}
+
+        # 4) 실패
+        return False, {'rating': None}
+
+
+    def evaluate_single_row(self, row: pd.Series, mode: str, current_date:str) -> Dict[str, Any]:
+        """단일 행 평가"""
+        question = row['question']
+        response = row['model_response']
+        correct_answers = [row[f'answer_{i}'] for i in range(10)]
+        correct_answers = [str(x) for x in correct_answers if pd.notna(x) and str(x).strip()]
+
+
+        # model_response가 비어있거나 NaN인 경우 바로 틀렸다는 결과로 처리하고 return
+        if pd.isna(response) or (isinstance(response, str) and response.strip() == ''):
+            # print('model_response가 비어있음. rating=0으로 처리')
+            row_dict = row.to_dict()
+            row_dict['rating'] = 0
+            row_dict['explanation'] = "model_response가 비어있음"
+            return row_dict
+        
+        # 평가 템플릿 생성
+        evaluation_template = (
+            "\ncorrect answer(s): {correct_answers}"
+            "\nresponse: {response}"
+            "\ncomment: "
+        )
+        evaluation = evaluation_template.format(
+            correct_answers=' | '.join(correct_answers),
+            response=response,
+        )
+
+        # 평가
+        fresheval_response = self.call_fresheval(
+            mode=mode,
+            question=question,
+            evaluation=evaluation,
+            current_date=current_date
+        )
+
+        is_valid_eval, eval_result = self.extract_ratings(fresheval_response)
+
+        # if is_valid_eval:
+        #     print('완료')
+        
+        # 재평가 횟수 제한 (최대 5회)
+        max_retries = 5
+        retry_count = 0
+
+        # 재시도 loop
+        while not is_valid_eval and retry_count < max_retries:
+            retry_count += 1
+            # print(f'유효하지 않은 평가, 재평가 중... ({retry_count}/{max_retries})\n response: {fresheval_response}')
+            
+            fresheval_response = self.call_fresheval(
+                mode=mode,
+                question=question,
+                evaluation=evaluation,
+                current_date=current_date
+            )
+
+            is_valid_eval, eval_result = self.extract_ratings(fresheval_response)
+            # if is_valid_eval:
+            #     print('완료')
+        
+        # 최대 재시도 횟수 초과 시 기본 값 사용
+        if not is_valid_eval:
+            print(f'⚠️  최대 재시도 횟수({max_retries}) 초과. 기본값 사용: rating=0')
+            eval_result = {'rating': 0}
+            fresheval_response = "재시도 횟수 초과로 인한 기본 평가"
+        
+        row_dict = row.to_dict()
+        row_dict['rating'] = eval_result['rating']
+        row_dict['explanation'] = fresheval_response
+        
+        # 📊 DEBUG: FALSE인 경우에만 상세 출력
+        # if eval_result['rating'] == 'FALSE':
+        #     print(f"\n{'='*80}")
+        #     print(f"❌ FALSE 평가된 질문")
+        #     print(f"   Mode: {mode}")
+        #     print(f"   Question: {question}")
+        #     print(f"   Correct Answers: {' | '.join(correct_answers)}")
+        #     print(f"   Model Response: {response}")
+        #     print(f"\n   LLM 평가 응답:")
+        #     print(f"   {fresheval_response}")
+        #     print(f"   최종 Rating: {eval_result['rating']}")
+        #     print(f"{'='*80}\n")
+
+        return row_dict
+
+    
+    def evaluate_dataframe(self, df: pd.DataFrame, mode: str) -> pd.DataFrame:
+        """데이터프레임 평가"""
+        
+        freshevals = []
+        current_date = get_current_date_str()
+
+        len_df = len(df)
+        for index, row in df.iterrows():
+            print(f'{mode} 평가 중... {index+1}/{len_df}')
+            row_dict = self.evaluate_single_row(row, mode, current_date)
+            freshevals.append(row_dict)
+
+        return pd.DataFrame(freshevals)

freshqa/fresheval_parallel.py

@@ -0,0 +1,113 @@
+import pandas as pd
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from typing import Dict, Any
+import time
+import queue
+
+from freshqa.fresheval import FreshEval
+from src.api_key_rotator import get_rotator
+from src.utils import get_current_date_str
+
+
+class FreshEvalParallel:
+    """병렬 처리를 위한 FreshEval 래퍼 클래스"""
+    
+    def __init__(self, model: str = 'solar-pro2', max_workers: int = 4):
+        self.model = model
+        self.max_workers = max_workers
+    
+    def evaluate_dataframe(self, df: pd.DataFrame, mode: str, progress_queue: "queue.Queue[int] | None" = None, on_item_done=None) -> pd.DataFrame:
+        """병렬 처리를 통한 데이터프레임 평가 (진행률 표시)"""
+        current_date = get_current_date_str()
+        total_rows = len(df)
+        
+        # print(f"🚀 {mode} 모드 평가 시작: {total_rows}개 행, {self.max_workers}개 워커")
+        
+        # 워커별 인자 준비
+        worker_args = []
+        for index, row in df.iterrows():
+            worker_args.append((row, mode, current_date))
+        
+        # 병렬 처리 (진행률 표시)
+        results = [None] * total_rows  # 미리 크기 할당
+        completed_count = 0
+        start_time = time.time()
+        
+        with ThreadPoolExecutor(max_workers=self.max_workers) as executor:
+            # 모든 작업 제출
+            future_to_index = {
+                executor.submit(self._evaluate_single_row_worker, args): i 
+                for i, args in enumerate(worker_args)
+            }
+            
+            # 완료된 작업들을 순서대로 처리
+            for future in as_completed(future_to_index):
+                original_index = future_to_index[future]
+                try:
+                    result = future.result()
+                    results[original_index] = result
+                    completed_count += 1
+                    
+                    # progress_queue에 진행률 반영 (Gradio UI 업데이트용)
+                    if progress_queue is not None:
+                        progress_queue.put(1)
+                    
+                    # on_item_done 콜백 호출 (옵션)
+                    if on_item_done:
+                        on_item_done(original_index, result)
+                    
+                    # 진행률 표시
+                    progress_percent = (completed_count / total_rows) * 100
+                    elapsed_time = time.time() - start_time
+                    
+                    # 10% 단위로 표시 (최소 10개 단위 보장)
+                    # total_rows // 10 = 10%에 해당하는 개수 (예: 3000행 → 300개)
+                    # max(1, ...)으로 최소 1개마다 보장
+                    print_interval = max(10, total_rows // 10)  # 최소 10개, 10% 단위
+                    if (completed_count % print_interval == 0 or 
+                        completed_count == total_rows):
+                        remaining_time = (elapsed_time / completed_count) * (total_rows - completed_count) if completed_count > 0 else 0
+                        # print(f"📊 {mode} 모드 진행률: {progress_percent:.1f}% ({completed_count}/{total_rows}) - "
+                        #       f"경과: {elapsed_time:.1f}초, 예상 남은 시간: {remaining_time:.1f}초")
+                        pass
+                        
+                except Exception as e:
+                    print(f"❌ 평가 실패 (행 {original_index}): {e}")
+                    # 실패한 경우 기본값 반환
+                    results[original_index] = {
+                        'rating': 0,
+                        'explanation': f"평가 실패: {str(e)}"
+                    }
+                    completed_count += 1
+                    
+                    # 실패해도 큐에 진행률 반영
+                    if progress_queue is not None:
+                        progress_queue.put(1)
+        
+        total_time = time.time() - start_time
+        print(f"✅ {mode} 모드 평가 완료: {total_time:.1f}초 소요")
+        
+        return pd.DataFrame(results)
+    
+    def _evaluate_single_row_worker(self, args: tuple) -> Dict[str, Any]:
+        """워커 함수 - 각 워커마다 독립적인 FreshEval 인스턴스 생성"""
+        row, mode, current_date = args
+        
+        # 각 워커마다 독립적인 FreshEval 인스턴스 생성 (로테이터로 키 분배)
+        api_key = get_rotator().pick_key()
+        worker_eval = FreshEval(model=self.model, api_key=api_key)
+        
+        # 기존 evaluate_single_row 메서드 사용
+        return worker_eval.evaluate_single_row(row, mode, current_date)
+
+
+# 편의 함수
+def evaluate_dataframe_parallel(
+    df: pd.DataFrame, 
+    mode: str, 
+    on_item_done=None,
+    progress_queue: "queue.Queue[int] | None" = None, 
+    max_workers: int = 4) -> pd.DataFrame:
+    """병렬 처리를 통한 데이터프레임 평가 (편의 함수)"""
+    parallel_eval = FreshEvalParallel(model='solar-pro2', max_workers=max_workers)
+    return parallel_eval.evaluate_dataframe(df, mode, progress_queue, on_item_done)

freshqa/freshqa_acc.py

@@ -0,0 +1,361 @@
+#!/usr/bin/env python3
+"""
+FreshQA 정확도 계산 스크립트
+
+이 스크립트는 FreshQA 데이터셋의 정확도를 계산하고 다양한 카테고리별로 분석합니다.
+"""
+
+import pandas as pd
+import sys
+import os
+
+
+def load_freshqa_data(csv_path='freshqa.csv'):
+    """FreshQA CSV 파일을 로드합니다."""
+    try:
+        # 먼저 파일을 읽어서 구조를 확인
+        temp_df = pd.read_csv(csv_path)
+        # print(f"파일 구조 확인: {len(temp_df)}개 행, 컬럼: {temp_df.columns.tolist()}")
+        
+        # rating 컬럼이 있으면 그대로 사용, 없으면 skiprows 적용
+        if 'rating' in temp_df.columns:
+            fresh_qa = temp_df
+            # print("rating 컬럼이 있는 파일로 인식하여 전체 데이터를 사용합니다.")
+        else:
+            fresh_qa = pd.read_csv(csv_path, skiprows=[0, 1])
+            # print("기본 FreshQA 형식으로 인식하여 skiprows를 적용합니다.")
+        
+        # print(f"FreshQA 데이터 로드 완료: {len(fresh_qa)}개 샘플")
+        return fresh_qa
+    except FileNotFoundError:
+        print(f"오류: {csv_path} 파일을 찾을 수 없습니다.")
+        print("현재 디렉토리에 freshqa.csv 파일이 있는지 확인해주세요.")
+        sys.exit(1)
+    except Exception as e:
+        print(f"데이터 로드 중 오류 발생: {e}")
+        sys.exit(1)
+
+
+def process_freshqa_dataframe(df):
+    """DataFrame을 매개변수로 받아 FreshQA 데이터를 처리합니다."""
+    try:
+        # print(f"DataFrame 구조 확인: {len(df)}개 행, 컬럼: {df.columns.tolist()}")
+        
+        # rating 컬럼이 있으면 그대로 사용, 없으면 기본값 설정
+        if 'rating' in df.columns:
+            # print("DataFrame에 rating 컬럼이 있어서 그대로 사용합니다.")
+            processed_df = df.copy()
+        else:
+            # print("DataFrame에 rating 컬럼이 없어서 기본값 0으로 설정합니다.")
+            processed_df = df.copy()
+            processed_df['rating'] = 0  # 기본값으로 0 설정
+        
+        print(f"FreshQA 데이터 처리 완료: {len(processed_df)}개 샘플")
+        return processed_df
+    except Exception as e:
+        print(f"데이터 처리 중 오류 발생: {e}")
+        raise
+
+
+def update_results(df, d_acc, d_count, field_name):
+    """결과 딕셔너리를 업데이트합니다."""
+    if len(df) == 0:
+        r = 0.0
+    else:
+        # rating이 문자열 'TRUE'이거나 숫자 1인 경우를 모두 처리
+        if df['rating'].dtype == 'object':
+            # 문자열인 경우 'TRUE' 확인
+            r = len(df[df.rating == 'TRUE']) * 100 / len(df)
+        else:
+            # 숫자인 경우 1 확인
+            r = len(df[df.rating == 1]) * 100 / len(df)
+    d_acc[field_name] = r
+    d_count[field_name] = len(df)
+
+
+def calculate_accuracy_simple(fresh_qa):
+    """FreshQA 데이터의 기본 정확도를 계산합니다 (간단한 버전)."""
+    print("정확도 계산 중...")
+    
+    # rating 컬럼이 없으면 기본값 0으로 설정
+    if 'rating' not in fresh_qa.columns:
+        # print("rating 컬럼이 없어서 기본값 0으로 설정합니다.")
+        fresh_qa['rating'] = 0
+    
+    accs = {}
+    counts = {}
+    
+    # 전체 정확도
+    update_results(fresh_qa, accs, counts, 'overall_accuracy')
+    
+    # split 컬럼이 있으면 분할별 정확도 계산
+    if 'split' in fresh_qa.columns:
+        fresh_qa_test = fresh_qa[fresh_qa.split == 'TEST']
+        fresh_qa_dev = fresh_qa[fresh_qa.split == 'DEV']
+        update_results(fresh_qa_test, accs, counts, 'acc_test')
+        update_results(fresh_qa_dev, accs, counts, 'acc_dev')
+    
+    # fact_type 컬럼이 있으면 사실 유형별 정확도 계산
+    if 'fact_type' in fresh_qa.columns:
+        for fact_type in ['fast-changing', 'slow-changing', 'never-changing']:
+            if fact_type in fresh_qa['fact_type'].values:
+                sub_df = fresh_qa[fresh_qa.fact_type == fact_type]
+                update_results(sub_df, accs, counts, f'{fact_type}_accuracy')
+    
+    # false_premise 컬럼이 있으면 False premise 정확도 계산
+    if 'false_premise' in fresh_qa.columns:
+        fp_df = fresh_qa[fresh_qa.false_premise == True]
+        if len(fp_df) > 0:
+            update_results(fp_df, accs, counts, 'false_premise_accuracy')
+    
+    # domain 컬럼이 있으면 도메인별 정확도 계산
+    if 'domain' in fresh_qa.columns:
+        # 한국어 도메인 카테고리들 (실제 CSV 파일의 domain 값들)
+        korean_domains = ['정치', '스포츠', '연예', '날씨', '세계', '경제', '사회', 'IT/과학', '생활/문화', 'UNK']
+        
+        for domain in korean_domains:
+            if domain in fresh_qa['domain'].values:
+                domain_df = fresh_qa[fresh_qa.domain == domain]
+                domain_test = domain_df[domain_df.split == 'TEST']
+                domain_dev = domain_df[domain_df.split == 'DEV']
+                
+                # 도메인명을 영어로 변환 (파일명/키에 사용)
+                domain_key = domain.replace('/', '_').replace(' ', '_').lower()
+                if domain == 'IT/과학':
+                    domain_key = 'it_science'
+                elif domain == '생활/문화':
+                    domain_key = 'life_culture'
+                elif domain == 'UNK':
+                    domain_key = 'unknown'
+                
+                update_results(domain_df, accs, counts, f'acc_{domain_key}')
+                update_results(domain_test, accs, counts, f'acc_test_{domain_key}')
+                update_results(domain_dev, accs, counts, f'acc_dev_{domain_key}')
+        
+        # 기존 영어 도메인들도 유지 (호환성을 위해)
+        english_domains = ['politics', 'sports', 'entertainment', 'weather', 'world', 'economy', 'society', 'it_science', 'life_culture']
+        for domain in english_domains:
+            if domain in fresh_qa['domain'].values:
+                domain_df = fresh_qa[fresh_qa.domain == domain]
+                update_results(domain_df, accs, counts, f'{domain}_accuracy')
+    
+    # 총 질문 수 추가
+    accs['total_questions'] = len(fresh_qa)
+    
+    return accs
+
+def calculate_accuracy(fresh_qa):
+    """FreshQA 데이터의 정확도를 계산합니다."""
+
+    # 데이터 분할
+    fresh_qa_test = fresh_qa[fresh_qa.split == 'TEST']
+    fresh_qa_dev = fresh_qa[fresh_qa.split == 'DEV']
+    
+    accs = {}
+    counts = {}
+    
+    # 전체 정확도
+    update_results(fresh_qa, accs, counts, 'acc')
+    update_results(fresh_qa_test, accs, counts, 'acc_test')
+    update_results(fresh_qa_dev, accs, counts, 'acc_dev')
+    
+    # 사실 유형별 정확도
+    for fact_type in ['fast-changing', 'slow-changing', 'never-changing']:
+        sub_df = fresh_qa[(fresh_qa.false_premise == False) & (fresh_qa.fact_type == fact_type)]
+        sub_df_test = sub_df[sub_df.split == 'TEST']
+        sub_df_dev = sub_df[sub_df.split == 'DEV']
+        
+        ft = fact_type.replace('-', '_')
+        update_results(sub_df, accs, counts, f'acc_{ft}')
+        update_results(sub_df_test, accs, counts, f'acc_test_{ft}')
+        update_results(sub_df_dev, accs, counts, f'acc_dev_{ft}')
+    
+    # 질문 유형별 정확도 (vp: valid premise, fp: false premise)
+    for qt in ['vp', 'fp']:
+        fp = True if qt == 'fp' else False
+        data = fresh_qa[(fresh_qa.false_premise == fp)]
+        data_test = data[data.split == 'TEST']
+        data_dev = data[data.split == 'DEV']
+        
+        # 홉 수별 분석
+        data_one_hop = data[data.num_hops == 'one-hop']
+        data_one_hop_test = data_one_hop[data_one_hop.split == 'TEST']
+        data_one_hop_dev = data_one_hop[data_one_hop.split == 'DEV']
+        
+        data_two_hop = data[data.num_hops == 'multi-hop']
+        data_two_hop_test = data_two_hop[data_two_hop.split == 'TEST']
+        data_two_hop_dev = data_two_hop[data_two_hop.split == 'DEV']
+        
+        # 연도별 분석
+        data_old = data[(data.effective_year != '2022') & (data.effective_year != '2023')]
+        data_old_test = data_old[data_old.split == 'TEST']
+        data_old_dev = data_old[data_old.split == 'DEV']
+        
+        data_new = data[(data.effective_year == '2022') | (data.effective_year == '2023')]
+        data_new_test = data_new[data_new.split == 'TEST']
+        data_new_dev = data_new[data_new.split == 'DEV']
+        
+        # 기본 정확도
+        update_results(data, accs, counts, f'acc_{qt}')
+        update_results(data_test, accs, counts, f'acc_test_{qt}')
+        update_results(data_dev, accs, counts, f'acc_dev_{qt}')
+        
+        # 홉 수별 정확도
+        update_results(data_one_hop, accs, counts, f'acc_{qt}_one_hop')
+        update_results(data_one_hop_test, accs, counts, f'acc_test_{qt}_one_hop')
+        update_results(data_one_hop_dev, accs, counts, f'acc_dev_{qt}_one_hop')
+        
+        update_results(data_two_hop, accs, counts, f'acc_{qt}_two_hop')
+        update_results(data_two_hop_test, accs, counts, f'acc_test_{qt}_two_hop')
+        update_results(data_two_hop_dev, accs, counts, f'acc_dev_{qt}_two_hop')
+        
+        # 연도별 정확도
+        update_results(data_old, accs, counts, f'acc_{qt}_old')
+        update_results(data_old_test, accs, counts, f'acc_test_{qt}_old')
+        update_results(data_old_dev, accs, counts, f'acc_dev_{qt}_old')
+        
+        update_results(data_new, accs, counts, f'acc_{qt}_new')
+        update_results(data_new_test, accs, counts, f'acc_test_{qt}_new')
+        update_results(data_new_dev, accs, counts, f'acc_dev_{qt}_new')
+    
+    # 도메인별 정확도 계산
+    if 'domain' in fresh_qa.columns:
+        # 한국어 도메인 카테고리들 (실제 CSV 파일의 domain 값들)
+        korean_domains = ['정치', '스포츠', '연예', '날씨', '세계', '경제', '사회', 'IT/과학', '생활/문화', 'UNK']
+        # 도메인명을 영어로 변환 (파일명/키에 사용)
+        domain_mapping = {
+                    '정치': 'politics',
+                    '스포츠': 'sports',
+                    '연예': 'entertainment',
+                    '날씨': 'weather',
+                    '세계': 'world',
+                    '경제': 'economy',
+                    '사회': 'society',
+                    'IT/과학': 'it_science',
+                    '생활/문화': 'life_culture',
+                    'UNK': 'unknown'
+                }
+        for domain in korean_domains:
+            if domain in fresh_qa['domain'].values:
+                
+                domain_df = fresh_qa[fresh_qa.domain == domain]
+                domain_test = domain_df[domain_df.split == 'TEST']
+                domain_dev = domain_df[domain_df.split == 'DEV']
+                
+                domain_key = domain_mapping.get(domain, domain.replace('/', '_').replace(' ', '_').lower())
+                
+                update_results(domain_df, accs, counts, f'acc_{domain_key}')
+                update_results(domain_test, accs, counts, f'acc_test_{domain_key}')
+                update_results(domain_dev, accs, counts, f'acc_dev_{domain_key}')
+    
+    return accs, counts
+
+
+def print_results(accs, counts):
+    """결과를 보기 좋게 출력합니다."""
+    print("\n" + "="*80)
+    print("FreshQA 정확도 분석 결과")
+    print("="*80)
+    
+    # 전체 정확도
+    print(f"\n📊 전체 정확도:")
+    print(f"  전체: {accs['acc']}% ({counts['acc']}개 샘플)")
+    print(f"  테스트: {accs['acc_test']}% ({counts['acc_test']}개 샘플)")
+    print(f"  개발: {accs['acc_dev']}% ({counts['acc_dev']}개 샘플)")
+    
+    # 사실 유형별 정확도
+    print(f"\n📈 사실 유형별 정확도:")
+    fact_types = {
+        'fast_changing': '빠르게 변하는 사실',
+        'slow_changing': '천천히 변하는 사실', 
+        'never_changing': '변하지 않는 사실'
+    }
+    
+    for key, name in fact_types.items():
+        print(f"  {name}:")
+        print(f"    전체: {accs[f'acc_{key}']}% ({counts[f'acc_{key}']}개 샘플)")
+        print(f"    테스트: {accs[f'acc_test_{key}']}% ({counts[f'acc_test_{key}']}개 샘플)")
+        print(f"    개발: {accs[f'acc_dev_{key}']}% ({counts[f'acc_dev_{key}']}개 샘플)")
+    
+    # 질문 유형별 정확도
+    print(f"\n❓ 질문 유형별 정확도:")
+    question_types = {
+        'vp': '유효한 전제 (Valid Premise)',
+        'fp': '잘못된 전제 (False Premise)'
+    }
+    
+    for key, name in question_types.items():
+        print(f"  {name}:")
+        print(f"    전체: {accs[f'acc_{key}']}% ({counts[f'acc_{key}']}개 샘플)")
+        print(f"    테스트: {accs[f'acc_test_{key}']}% ({counts[f'acc_test_{key}']}개 샘플)")
+        print(f"    개발: {accs[f'acc_dev_{key}']}% ({counts[f'acc_dev_{key}']}개 샘플)")
+        
+        # 홉 수별
+        print(f"    단일 홉: {accs[f'acc_{key}_one_hop']}% ({counts[f'acc_{key}_one_hop']}개 샘플)")
+        print(f"    다중 홉: {accs[f'acc_{key}_two_hop']}% ({counts[f'acc_{key}_two_hop']}개 샘플)")
+        
+        # 연도별
+        print(f"    오래된 데이터: {accs[f'acc_{key}_old']}% ({counts[f'acc_{key}_old']}개 샘플)")
+        print(f"    최신 데이터: {accs[f'acc_{key}_new']}% ({counts[f'acc_{key}_new']}개 샘플)")
+    
+    # 도메인별 정확도
+    print(f"\n🌐 도메인별 정확도:")
+    domain_mapping = {
+        'politics': '정치',
+        'sports': '스포츠', 
+        'entertainment': '연예',
+        'weather': '날씨',
+        'world': '세계',
+        'economy': '경제',
+        'society': '사회',
+        'it_science': 'IT/과학',
+        'life_culture': '생활/문화',
+        'unknown': 'UNK'
+    }
+    
+    for key, name in domain_mapping.items():
+        if f'acc_{key}' in accs:
+            print(f"  {name}:")
+            print(f"    전체: {accs[f'acc_{key}']}% ({counts[f'acc_{key}']}개 샘플)")
+            if f'acc_test_{key}' in accs:
+                print(f"    테스트: {accs[f'acc_test_{key}']}% ({counts[f'acc_test_{key}']}개 샘플)")
+                pass
+            if f'acc_dev_{key}' in accs:
+                print(f"    개발: {accs[f'acc_dev_{key}']}% ({counts[f'acc_dev_{key}']}개 샘플)")
+                pass
+            pass
+    
+    print("\n" + "="*80)
+
+
+def main():
+    """메인 함수"""
+    print("FreshQA 정확도 계산 스크립트")
+    print("="*50)
+    
+    # CSV 파일 경로 확인
+    csv_path = 'freshqa.csv'
+    if len(sys.argv) > 1:
+        csv_path = sys.argv[1]
+    
+    if not os.path.exists(csv_path):
+        print(f"오류: {csv_path} 파일을 찾을 수 없습니다.")
+        print("사용법: python freshqa_acc.py [csv_file_path]")
+        sys.exit(1)
+    
+    # 데이터 로드
+    fresh_qa = load_freshqa_data(csv_path)
+    
+    # 정확도 계산
+    accs, counts = calculate_accuracy(fresh_qa)
+    
+    # 결과 출력
+    print_results(accs, counts)
+    
+    # 딕셔너리 형태로도 출력 (원본 노트북과 동일)
+    print(f"\n📋 딕셔너리 형태 결과:")
+    print(accs)
+
+
+if __name__ == "__main__":
+    main()

freshqa/merge_csv_with_model_response.py

@@ -0,0 +1,187 @@
+import pandas as pd
+import argparse
+import os
+import sys
+
+
+def merge_dataframe_with_model_response_df(
+    base_df: pd.DataFrame,
+    model_response_csv_path: str,
+    question_column: str = "question",
+    model_response_column: str = "model_response"
+) -> pd.DataFrame:
+    """
+    기준 DataFrame과 모델 응답 CSV 파일을 question을 기준으로 매칭하여 
+    model_response 컬럼을 추가한 DataFrame을 반환합니다.
+    
+    Args:
+        base_df (pd.DataFrame): 기준이 되는 DataFrame
+        model_response_csv_path (str): model_response가 포함된 CSV 파일 경로
+        question_column (str): 매칭에 사용할 질문 컬럼명 (기본값: "question")
+        model_response_column (str): 모델 응답 컬럼명 (기본값: "model_response")
+    
+    Returns:
+        pd.DataFrame: 병합된 DataFrame
+    """
+    
+    # DataFrame 유효성 검사
+    if base_df is None or base_df.empty:
+        raise ValueError("기준 DataFrame이 비어있습니다.")
+    
+    # 파일 존재 여부 확인
+    if not os.path.exists(model_response_csv_path):
+        raise FileNotFoundError(f"모델 응답 CSV 파일을 찾을 수 없습니다: {model_response_csv_path}")
+    
+    try:
+        # 모델 응답 CSV 파일 읽기
+        # print(f"모델 응답 CSV 파일 읽는 중: {model_response_csv_path}")
+        model_df = pd.read_csv(model_response_csv_path)
+        
+        # 컬럼 존재 여부 확인
+        if question_column not in base_df.columns:
+            raise ValueError(f"기준 DataFrame에 '{question_column}' 컬럼이 없습니다.")
+        
+        if question_column not in model_df.columns:
+            raise ValueError(f"모델 응답 CSV 파일에 '{question_column}' 컬럼이 없습니다.")
+        
+        if model_response_column not in model_df.columns:
+            raise ValueError(f"모델 응답 CSV 파일에 '{model_response_column}' 컬럼이 없습니다.")
+        
+        # print(f"기준 데이터: {len(base_df)}행")
+        # print(f"모델 응답 데이터: {len(model_df)}행")
+        
+        # 질문 텍스트 정규화 (공백 제거, 소문자 변환)
+        # print("질문 텍스트 정규화 중...")
+        base_df_normalized = base_df.copy()
+        model_df_normalized = model_df.copy()
+        
+        # 질문 텍스트 정규화
+        base_df_normalized['question_normalized'] = base_df[question_column].str.strip().str.replace(r'\s+', ' ', regex=True)
+        model_df_normalized['question_normalized'] = model_df[question_column].str.strip().str.replace(r'\s+', ' ', regex=True)
+        
+        # question을 기준으로 매칭
+        # base_df(기준 데이터)를 기준으로 model_df(사용자 제출 파일)와 병합
+        # model_df에서 필요한 컬럼들만 선택
+        model_subset = model_df_normalized[[question_column, model_response_column, 'question_normalized']].copy()
+        
+        # 정규화된 질문으로 매칭 시도
+        merged_df = base_df_normalized.merge(
+            model_subset, 
+            left_on='question_normalized',
+            right_on='question_normalized',
+            how='left'
+        )
+
+        # split = DEV인 질문은 제외하고 TEST 질문만 남김
+        merged_df = merged_df[merged_df['split'] == 'TEST']
+        
+        # 원본 question 컬럼 복원 (model_response가 있는 경우)
+        if model_response_column in merged_df.columns:
+            # model_response가 있는 행들에 대해 원본 question 컬럼 유지
+            merged_df[question_column] = merged_df[question_column + '_x'].fillna(merged_df[question_column + '_y'])
+            # 불필요한 컬럼 제거
+            merged_df = merged_df.drop(columns=[question_column + '_x', question_column + '_y', 'question_normalized'], errors='ignore')
+        
+        # merge 후 question 기준 중복 확인 및 처리
+        duplicate_mask = merged_df.duplicated(subset=[question_column], keep=False)
+        duplicate_count = duplicate_mask.sum()
+        if duplicate_count > 0:
+            # print(f"⚠️ 경고: merge 후 기준 데이터에 중복 질문이 {duplicate_count}개 발견되었습니다.")
+            duplicate_questions = merged_df[duplicate_mask][question_column].unique()
+            # print(f"   중복된 질문 수: {len(duplicate_questions)}개")
+            for i, q in enumerate(duplicate_questions):
+                dup_rows = merged_df[merged_df[question_column] == q]
+                # print(f"   {i+1}. 질문: '{q[:80]}...' ({len(dup_rows)}개 중복)")
+            
+            # 중복 제거: 첫 번째 항목만 유지
+            merged_df = merged_df.drop_duplicates(subset=[question_column], keep='first')
+            # print(f"   → 중복 제거 후 merge 데이터: {len(merged_df)}행")
+        
+        # 매칭 결과 확인 (모델 응답이 있는지 확인)
+        matched_count = merged_df.dropna(subset=[model_response_column]).shape[0]
+        total_count = len(merged_df)
+        
+        # print(f"매칭된 질문 수: {matched_count}/{total_count}")
+        
+        if matched_count < total_count:
+            # 모델 응답이 없는 질문들 찾기
+            unmatched_mask = merged_df[model_response_column].isna()
+            unmatched_questions = merged_df[unmatched_mask][question_column].tolist()
+            # print(f"모델 응답이 없는 질문들:")
+            for i, q in enumerate(unmatched_questions[:5]):  # 처음 5개만 출력
+                # print(f"  {i+1}. {q}")
+                pass
+            if len(unmatched_questions) > 5:
+                # print(f"  ... 및 {len(unmatched_questions) - 5}개 더")
+                pass
+        
+        # print(f"✅ DataFrame 생성 완료!")
+        # print(f"   - 기준 DataFrame: {len(base_df)}행")
+        # print(f"   - 모델 응답 파일: {model_response_csv_path}")
+        # print(f"   - 매칭률: {matched_count/total_count*100:.1f}%")
+        
+        return merged_df
+        
+    except Exception as e:
+        print(f"❌ 오류 발생: {str(e)}")
+        raise
+
+def main():
+    """
+    명령행 인수를 받아서 CSV 파일을 병합하는 메인 함수
+    """
+    parser = argparse.ArgumentParser(
+        description="기준 CSV 파일과 모델 응답 CSV 파일을 병합합니다.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+            사용 예시:
+            python merge_csv_with_model_response.py base.csv model_response.csv output.csv
+            python merge_csv_with_model_response.py base.csv model_response.csv output.csv --question-col question --response-col model_response
+        """
+    )
+    
+    parser.add_argument(
+        'base_csv', 
+        help='기준이 되는 CSV 파일 경로'
+    )
+    
+    parser.add_argument(
+        'model_response_csv', 
+        help='모델 응답이 포함된 CSV 파일 경로'
+    )
+    
+    parser.add_argument(
+        'output_csv', 
+        help='출력할 CSV 파일 경로'
+    )
+    
+    parser.add_argument(
+        '--question-col', 
+        default='question',
+        help='매칭에 사용할 질문 컬럼명 (기본값: question)'
+    )
+    
+    parser.add_argument(
+        '--response-col', 
+        default='model_response',
+        help='모델 응답 컬럼명 (기본값: model_response)'
+    )
+    
+    # 인수 파싱
+    args = parser.parse_args()
+    
+    try:
+        merge_dataframe_with_model_response_df(
+            base_csv_path=args.base_csv,
+            model_response_csv_path=args.model_response_csv,
+            output_csv_path=args.output_csv,
+            question_column=args.question_col,
+            model_response_column=args.response_col
+        )
+    except Exception as e:
+        print(f"실행 중 오류 발생: {e}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

requirements.txt

@@ -0,0 +1,36 @@
+# Core dependencies for Hugging Face Spaces
+gradio>=5.0.0
+huggingface_hub<1.0.0
+pandas>=2.0.0
+numpy>=1.24.0
+plotly>=5.0.0
+
+# API and web processing
+requests>=2.25.0
+httpx>=0.24.0
+
+# Date and time handling
+pytz>=2023.3
+python-dateutil>=2.8.0
+
+# Data processing
+openpyxl>=3.0.0
+chardet>=5.0.0
+
+# Progress and logging
+tqdm>=4.65.0
+
+# FreshQA evaluation
+openai>=1.10.0
+tabulate>=0.9.0
+
+# Environment variables
+python-dotenv>=1.0.0
+
+# Optional: Korean language processing (commented out for faster deployment)
+# konlpy>=0.6.0
+
+# Optional: Heavy ML dependencies (commented out for faster deployment)
+# torch>=2.0.0
+# transformers>=4.30.0
+# accelerate>=0.20.0

src/api_key_rotator.py

@@ -0,0 +1,78 @@
+"""
+API 키 로테이터 모듈
+멀티스레딩 환경에서 여러 API 키를 라운드로빈 방식으로 분배합니다.
+"""
+
+import threading
+from itertools import count
+from typing import List
+
+from config import Config
+
+
+class ApiKeyRotator:
+    """API 키를 라운드로빈 방식으로 분배하는 클래스 (Thread-safe)"""
+    
+    def __init__(self, keys: List[str]):
+        """
+        Args:
+            keys: 사용할 API 키 리스트 (최소 1개 이상)
+        """
+        if not keys:
+            raise ValueError("API 키 리스트가 비어있습니다. 최소 1개의 키가 필요합니다.")
+        
+        self.keys = keys
+        self._counter = count()  # 무한 카운터
+        self._lock = threading.Lock()
+    
+    def pick_key(self) -> str:
+        """
+        라운드로빈 방식으로 다음 키를 선택합니다 (Thread-safe)
+        
+        Returns:
+            선택된 API 키
+        
+        Example:
+            >>> rotator = ApiKeyRotator(["key1", "key2", "key3"])
+            >>> rotator.pick_key()  # "key1"
+            >>> rotator.pick_key()  # "key2"
+            >>> rotator.pick_key()  # "key3"
+            >>> rotator.pick_key()  # "key1" (순환)
+        """
+        with self._lock:
+            index = next(self._counter) % len(self.keys)
+            return self.keys[index]
+
+
+# 전역 인스턴스 (싱글톤 패턴)
+_rotator_instance: ApiKeyRotator = None
+_instance_lock = threading.Lock()
+
+
+def get_rotator() -> ApiKeyRotator:
+    """
+    전역 ApiKeyRotator 인스턴스를 반환합니다 (Lazy initialization)
+    
+    Returns:
+        ApiKeyRotator 인스턴스
+    
+    Note:
+        - 최초 호출 시 Config.UPSTAGE_API_KEYS를 사용하여 초기화
+        - 이후 호출은 동일한 인스턴스를 반환
+    """
+    global _rotator_instance
+    
+    # Double-checked locking 패턴
+    if _rotator_instance is None:
+        with _instance_lock:
+            if _rotator_instance is None:
+                keys = Config.UPSTAGE_API_KEYS
+                if not keys:
+                    raise ValueError(
+                        "UPSTAGE_API_KEY 또는 UPSTAGE_API_KEYS 환경 변수가 설정되지 않았습니다. "
+                        "최소 1개의 API 키가 필요합니다."
+                    )
+                _rotator_instance = ApiKeyRotator(keys)
+    
+    return _rotator_instance
+

src/hf_private_csv_loader.py

@@ -0,0 +1,279 @@
+"""
+Hugging Face Private Repository CSV 파일 로더
+HF_TOKEN을 이용하여 private repository에서 CSV 파일을 안전하게 불러오는 모듈
+"""
+
+import os
+import pandas as pd
+import tempfile
+from typing import Optional, Dict, Any, Union
+from huggingface_hub import hf_hub_download, login, whoami
+
+
+class HFPrivateCSVLoader:
+    """Hugging Face Private Repository에서 CSV 파일을 로드하는 클래스"""
+    
+    def __init__(self, token: Optional[str] = None):
+        """
+        Args:
+            token: Hugging Face API 토큰. None이면 환경변수에서 자동으로 가져옴
+        """
+        self.token = token or os.getenv('HF_TOKEN') or os.getenv('HUGGINGFACE_HUB_TOKEN')
+        
+        if not self.token:
+            raise ValueError(
+                "Hugging Face 토큰이 필요합니다. "
+                "토큰을 직접 전달하거나 HF_TOKEN 또는 HUGGINGFACE_HUB_TOKEN 환경변수를 설정하세요."
+            )
+        
+        # 토큰으로 로그인
+        try:
+            login(token=self.token)
+            print("✅ Hugging Face에 성공적으로 로그인되었습니다.")
+        except Exception as e:
+            print(f"❌ Hugging Face 로그인 실패: {e}")
+            raise
+    
+    def check_auth(self) -> Dict[str, Any]:
+        """현재 인증 상태 확인"""
+        try:
+            user_info = whoami()
+            return {
+                "authenticated": True,
+                "user": user_info.get("name", "Unknown"),
+                "type": user_info.get("type", "Unknown"),
+                "id": user_info.get("id", "Unknown")
+            }
+        except Exception as e:
+            return {
+                "authenticated": False,
+                "error": str(e)
+            }
+    
+    def load_csv_from_private_repo(self, 
+                                 repo_id: str, 
+                                 filename: str,
+                                 repo_type: str = "dataset",
+                                 **kwargs) -> Optional[pd.DataFrame]:
+        """
+        Private repository에서 CSV 파일을 직접 로드합니다.
+        
+        Args:
+            repo_id: Repository ID (예: "username/repo-name")
+            filename: CSV 파일명 (경로 포함 가능)
+            repo_type: Repository 타입 ("dataset", "model", "space")
+            **kwargs: pandas.read_csv()에 전달할 추가 인자들
+            
+        Returns:
+            pandas DataFrame 또는 None (실패시)
+        """
+        try:
+            print(f"📥 Private repository에서 CSV 파일 로드 시작: {repo_id}/{filename}")
+            
+            # 임시 디렉토리에 파일 다운로드
+            with tempfile.TemporaryDirectory() as temp_dir:
+                file_path = hf_hub_download(
+                    repo_id=repo_id,
+                    filename=filename,
+                    local_dir=temp_dir,
+                    repo_type=repo_type,
+                    token=self.token  # 토큰 명시적 전달
+                )
+                
+                # print(f"✅ 파일 다운로드 완료: {file_path}")
+                
+                # CSV 파일 로드 (기본 설정 + 사용자 지정 설정)
+                default_kwargs = {
+                    'encoding': 'utf-8',
+                    'low_memory': False
+                }
+                default_kwargs.update(kwargs)
+                
+                df = pd.read_csv(file_path, **default_kwargs)
+                
+                # print(f"✅ CSV 파일 로드 완료: {filename} ({len(df)} 행, {len(df.columns)} 열)")
+                return df
+                
+        except Exception as e:
+            print(f"❌ CSV 파일 로드 실패: {e}")
+            return None
+    
+    def load_multiple_csvs(self, 
+                          repo_id: str, 
+                          filenames: list,
+                          repo_type: str = "dataset",
+                          **kwargs) -> Dict[str, Optional[pd.DataFrame]]:
+        """
+        여러 CSV 파일을 한 번에 로드합니다.
+        
+        Args:
+            repo_id: Repository ID
+            filenames: CSV 파일명 리스트
+            repo_type: Repository 타입
+            **kwargs: pandas.read_csv()에 전달할 추가 인자들
+            
+        Returns:
+            {filename: DataFrame} 딕셔너리
+        """
+        results = {}
+        
+        for filename in filenames:
+            # print(f"📥 {filename} 로드 중...")
+            df = self.load_csv_from_private_repo(repo_id, filename, repo_type, **kwargs)
+            results[filename] = df
+            
+            if df is not None:
+                # print(f"✅ {filename} 로드 성공")
+                pass
+            else:
+                print(f"⚠️ {filename} 로드 실패")
+        
+        return results
+    
+    def get_csv_info(self, 
+                    repo_id: str, 
+                    filename: str,
+                    repo_type: str = "dataset") -> Optional[Dict[str, Any]]:
+        """
+        CSV 파일의 기본 정보를 반환합니다 (실제 로드 없이).
+        
+        Args:
+            repo_id: Repository ID
+            filename: CSV 파일명
+            repo_type: Repository 타입
+            
+        Returns:
+            파일 정보 딕셔너리 또는 None
+        """
+        try:
+            # 임시로 파일을 로드하여 정보만 확인
+            df = self.load_csv_from_private_repo(repo_id, filename, repo_type)
+            
+            if df is not None:
+                return {
+                    "filename": filename,
+                    "rows": len(df),
+                    "columns": len(df.columns),
+                    "column_names": df.columns.tolist(),
+                    "dtypes": df.dtypes.to_dict(),
+                    "memory_usage": df.memory_usage(deep=True).sum(),
+                    "has_nulls": df.isnull().any().any(),
+                    "null_counts": df.isnull().sum().to_dict()
+                }
+            else:
+                return None
+                
+        except Exception as e:
+            print(f"❌ CSV 파일 정보 조회 실패: {e}")
+            return None
+
+
+def load_csv_with_token(repo_id: str, 
+                       filename: str, 
+                       token: str,
+                       repo_type: str = "dataset",
+                       **kwargs) -> Optional[pd.DataFrame]:
+    """
+    편의 함수: 토큰을 직접 전달하여 CSV 파일을 로드합니다.
+    
+    Args:
+        repo_id: Repository ID
+        filename: CSV 파일명
+        token: Hugging Face API 토큰
+        repo_type: Repository 타입
+        **kwargs: pandas.read_csv()에 전달할 추가 인자들
+        
+    Returns:
+        pandas DataFrame 또는 None
+    """
+    try:
+        loader = HFPrivateCSVLoader(token=token)
+        return loader.load_csv_from_private_repo(repo_id, filename, repo_type, **kwargs)
+    except Exception as e:
+        print(f"❌ CSV 로드 실패: {e}")
+        return None
+
+
+def load_csv_with_env_token(repo_id: str, 
+                           filename: str,
+                           repo_type: str = "dataset",
+                           **kwargs) -> Optional[pd.DataFrame]:
+    """
+    편의 함수: 환경변수의 토큰을 사용하여 CSV 파일을 로드합니다.
+    
+    Args:
+        repo_id: Repository ID
+        filename: CSV 파일명
+        repo_type: Repository 타입
+        **kwargs: pandas.read_csv()에 전달할 추가 인자들
+        
+    Returns:
+        pandas DataFrame 또는 None
+    """
+    try:
+        loader = HFPrivateCSVLoader()  # 환경변수에서 토큰 자동 로드
+        return loader.load_csv_from_private_repo(repo_id, filename, repo_type, **kwargs)
+    except Exception as e:
+        print(f"❌ CSV 로드 실패: {e}")
+        return None
+
+
+# 사용 예시
+if __name__ == "__main__":
+    # 예시 1: 토큰을 직접 전달
+    print("=== 예시 1: 토큰 직접 전달 ===")
+    token = "your_hf_token_here"  # 실제 토큰으로 변경
+    
+    try:
+        df = load_csv_with_token(
+            repo_id="username/private-dataset",
+            filename="data.csv",
+            token=token,
+            repo_type="dataset"
+        )
+        
+        if df is not None:
+            print(f"✅ CSV 로드 성공: {len(df)} 행, {len(df.columns)} 열")
+            print(f"컬럼: {list(df.columns)}")
+        else:
+            print("❌ CSV 로드 실패")
+    except Exception as e:
+        print(f"❌ 오류: {e}")
+    
+    # 예시 2: 환경변수 사용
+    print("\n=== 예시 2: 환경변수 사용 ===")
+    try:
+        df = load_csv_with_env_token(
+            repo_id="username/private-dataset",
+            filename="data.csv",
+            repo_type="dataset"
+        )
+        
+        if df is not None:
+            print(f"✅ CSV 로드 성공: {len(df)} 행, {len(df.columns)} 열")
+        else:
+            print("❌ CSV 로드 실패")
+    except Exception as e:
+        print(f"❌ 오류: {e}")
+    
+    # 예시 3: 클래스 사용
+    print("\n=== 예시 3: 클래스 사용 ===")
+    try:
+        loader = HFPrivateCSVLoader(token=token)
+        
+        # 인증 상태 확인
+        auth_status = loader.check_auth()
+        print(f"인증 상태: {auth_status}")
+        
+        # CSV 파일 정보 확인
+        csv_info = loader.get_csv_info("username/private-dataset", "data.csv")
+        if csv_info:
+            print(f"CSV 파일 정보: {csv_info}")
+        
+        # CSV 파일 로드
+        df = loader.load_csv_from_private_repo("username/private-dataset", "data.csv")
+        if df is not None:
+            print(f"✅ CSV 로드 성공: {len(df)} 행, {len(df.columns)} 열")
+        
+    except Exception as e:
+        print(f"❌ 오류: {e}")

src/leaderboard_manager.py

@@ -0,0 +1,215 @@
+"""
+리더보드 관리 모듈
+리더보드 데이터의 로드, 저장, 표시 준비를 담당합니다.
+"""
+
+import pandas as pd
+import os
+from src.utils import file_lock
+
+def load_leaderboard_data():
+    """리더보드 데이터 로드"""
+    try:
+        # 프로젝트 루트에서 data 디렉토리 찾기
+        current_dir = os.path.dirname(os.path.abspath(__file__))  # src/ 폴더
+        project_root = os.path.dirname(current_dir)  # 프로젝트 루트
+        data_path = os.path.join(project_root, 'data', 'leaderboard_results.csv')
+        df = pd.read_csv(data_path)
+        
+        # 기존 데이터에 evaluation_mode 컬럼이 없으면 추가
+        if 'evaluation_mode' not in df.columns:
+            df['evaluation_mode'] = 'Unknown'
+        
+        text_columns = ['model', 'description']
+        for col in text_columns:
+            if col not in df.columns:
+                df[col] = pd.Series(dtype='object')
+        
+        
+        # 새로운 상세 분석 컬럼들이 없으면 추가
+        detailed_columns = [
+            'acc_test', 'acc_dev', 'acc_vp', 'acc_fp', 'acc_vp_one_hop', 'acc_vp_two_hop',
+            'acc_fp_one_hop', 'acc_fp_two_hop', 'acc_vp_old', 'acc_vp_new', 'acc_fp_old', 'acc_fp_new'
+        ]
+        
+        for col in detailed_columns:
+            if col not in df.columns:
+                df[col] = 0.0
+        
+        # 도메인별 정확도 컬럼들이 없으면 추가 (freshqa_acc.py와 일치)
+        domain_columns = [
+            'acc_politics', 'acc_sports', 'acc_entertainment', 
+            'acc_weather', 'acc_world', 'acc_economy', 
+            'acc_society', 'acc_it_science', 'acc_life_culture', 'acc_unknown'
+        ]
+        
+        for col in domain_columns:
+            if col not in df.columns:
+                df[col] = 0.0
+        
+        # accuracy 기준으로 정렬 (랭킹 기준) - 빈 데이터프레임이 아닐 때만
+        if not df.empty and 'accuracy' in df.columns:
+            df = df.sort_values('accuracy', ascending=False).reset_index(drop=True)
+        
+        # rank 컬럼은 저장하지 않고 표시 시에만 계산
+        # 숫자 컬럼들은 원본 그대로 저장 (반올림하지 않음)
+        
+        # 컬럼 순서를 헤더와 맞춰서 정렬 (rank 제외)
+        column_order = [
+            'id', 'model', 'description', 'accuracy', 'fast_changing_accuracy', 
+            'slow_changing_accuracy', 'never_changing_accuracy', 'acc_vp', 'acc_fp', 
+            'acc_vp_one_hop', 'acc_vp_two_hop', 'acc_fp_one_hop', 'acc_fp_two_hop',
+            'acc_vp_old', 'acc_vp_new', 'acc_fp_old', 'acc_fp_new',
+            'acc_politics', 'acc_sports', 'acc_entertainment', 'acc_weather', 
+            'acc_world', 'acc_economy', 'acc_society', 'acc_it_science', 
+            'acc_life_culture', 'acc_unknown', 'total_questions', 'evaluation_date', 'evaluation_mode'
+        ]
+        
+        # 존재하는 컬럼만 선택하여 순서대로 정렬
+        available_columns = [col for col in column_order if col in df.columns]
+        df = df[available_columns]
+            
+        return df
+    except FileNotFoundError:
+        # 초기 데이터 (rank 제외)
+        return pd.DataFrame({
+            'id': [],
+            'model': [],
+            'description': [],
+            'accuracy': [],
+            'fast_changing_accuracy': [],
+            'slow_changing_accuracy': [],
+            'never_changing_accuracy': [],
+            'acc_vp': [],
+            'acc_fp': [],
+            'acc_vp_one_hop': [],
+            'acc_vp_two_hop': [],
+            'acc_fp_one_hop': [],
+            'acc_fp_two_hop': [],
+            'acc_vp_old': [],
+            'acc_vp_new': [],
+            'acc_fp_old': [],
+            'acc_fp_new': [],
+            'acc_politics': [],
+            'acc_sports': [],
+            'acc_entertainment': [],
+            'acc_weather': [],
+            'acc_world': [],
+            'acc_economy': [],
+            'acc_society': [],
+            'acc_it_science': [],
+            'acc_life_culture': [],
+            'acc_unknown': [],
+            'total_questions': [],
+            'evaluation_date': [],
+            'evaluation_mode': []
+        })
+
+def append_to_leaderboard_data(new_data_list):
+    """리더보드 데이터에 새로운 결과 추가 (파일 잠금 사용)"""
+    current_dir = os.path.dirname(os.path.abspath(__file__))  # src/ 폴더
+    project_root = os.path.dirname(current_dir)  # 프로젝트 루트
+    data_path = os.path.join(project_root, 'data', 'leaderboard_results.csv')
+    
+    # 파일 잠금을 사용하여 안전하게 읽기 -> 수정 -> 쓰기
+    with file_lock(data_path + '.lock'):
+        # 파일이 존재하면 읽기
+        if os.path.exists(data_path):
+            existing_df = pd.read_csv(data_path)
+            for col in ['model', 'description']:
+                if col not in existing_df.columns:
+                    existing_df[col] = pd.Series(dtype='object')
+        else:
+            # 파일이 없으면 빈 DataFrame 생성
+            existing_df = load_leaderboard_data()  # 초기 스키마 반환
+        
+        # 새로운 데이터 추가
+        new_df = pd.DataFrame(new_data_list)
+
+        combined_df = pd.concat([existing_df, new_df], ignore_index=True)
+        
+        # 정렬 (accuracy 기준)
+        if not combined_df.empty and 'accuracy' in combined_df.columns:
+            combined_df = combined_df.sort_values('accuracy', ascending=False).reset_index(drop=True)
+
+        desired_order = [
+            'id', 'model', 'description', 'accuracy', 'fast_changing_accuracy',
+            'slow_changing_accuracy', 'never_changing_accuracy', 'acc_vp', 'acc_fp',
+            'acc_vp_one_hop', 'acc_vp_two_hop', 'acc_fp_one_hop', 'acc_fp_two_hop',
+            'acc_vp_old', 'acc_vp_new', 'acc_fp_old', 'acc_fp_new',
+            'acc_politics', 'acc_sports', 'acc_entertainment', 'acc_weather',
+            'acc_world', 'acc_economy', 'acc_society', 'acc_it_science',
+            'acc_life_culture', 'acc_unknown', 'total_questions', 'evaluation_date', 'evaluation_mode'
+        ]
+        combined_df = combined_df.reindex(columns=[col for col in desired_order if col in combined_df.columns])
+        
+        # 저장
+        combined_df.to_csv(data_path, index=False)
+        
+        return combined_df
+    
+def prepare_display_data(df, global_ranking=None):
+    """테이블 표시용 데이터 준비 (rank 계산 및 반올림 적용)"""
+    # 빈 데이터프레임인 경우 그대로 반환
+    if df.empty:
+        return df
+    
+    display_df = df.copy()
+    if 'model' in display_df.columns:
+        display_df['model'] = display_df['model'].fillna('Anonymous Model')
+        display_df['model'] = display_df['model'].replace('', 'Anonymous Model')
+    if 'description' in display_df.columns:
+        display_df['description'] = display_df['description'].replace({None: '', pd.NA: ''}).fillna('')
+    
+    # rank 컬럼 추가
+    if 'accuracy' in display_df.columns:
+        if global_ranking is not None:
+            # 전체 랭킹 정보가 제공된 경우 사용
+            display_df['rank'] = display_df.index.map(global_ranking)
+        else:
+            # 전체 랭킹 정보가 없는 경우 accuracy 기준으로 정렬하여 rank 계산
+            display_df = display_df.sort_values('accuracy', ascending=False).reset_index(drop=True)
+            
+            # rank 컬럼 추가 (1~3위는 아이콘, 나머지는 숫자)
+            def get_rank_display(rank):
+                if rank == 1:
+                    return "🥇"
+                elif rank == 2:
+                    return "🥈"
+                elif rank == 3:
+                    return "🥉"
+                else:
+                    return str(rank)
+            
+            display_df['rank'] = [get_rank_display(i+1) for i in range(len(display_df))]
+    
+    # 숫자 컬럼들을 소숫점 2번째에서 반올림 (표시용으로만)
+    numeric_columns = [
+        'accuracy', 'fast_changing_accuracy', 'slow_changing_accuracy', 'never_changing_accuracy', 
+        'acc_vp', 'acc_fp', 'acc_vp_one_hop', 'acc_vp_two_hop', 'acc_fp_one_hop', 'acc_fp_two_hop',
+        'acc_vp_old', 'acc_vp_new', 'acc_fp_old', 'acc_fp_new',
+        'acc_politics', 'acc_sports', 'acc_entertainment', 'acc_weather', 
+        'acc_world', 'acc_economy', 'acc_society', 'acc_it_science', 
+        'acc_life_culture', 'acc_unknown'
+    ]
+    
+    for col in numeric_columns:
+        if col in display_df.columns:
+            display_df[col] = display_df[col].round(2)
+    
+    # 컬럼 순서 재정렬 (rank를 맨 앞에)
+    column_order = [
+        'rank', 'id', 'model', 'description', 'accuracy', 'fast_changing_accuracy', 
+        'slow_changing_accuracy', 'never_changing_accuracy', 'acc_vp', 'acc_fp', 
+        'acc_vp_one_hop', 'acc_vp_two_hop', 'acc_fp_one_hop', 'acc_fp_two_hop',
+        'acc_vp_old', 'acc_vp_new', 'acc_fp_old', 'acc_fp_new',
+        'acc_politics', 'acc_sports', 'acc_entertainment', 'acc_weather', 
+        'acc_world', 'acc_economy', 'acc_society', 'acc_it_science', 
+        'acc_life_culture', 'acc_unknown', 'total_questions', 'evaluation_date', 'evaluation_mode'
+    ]
+    
+    # 존재하는 컬럼만 선택하여 순서대로 정렬
+    available_columns = [col for col in column_order if col in display_df.columns]
+    display_df = display_df[available_columns]
+    
+    return display_df

src/quick_csv_loader.py

@@ -0,0 +1,158 @@
+"""
+빠른 CSV 로더 - 간단한 사용을 위한 편의 함수들
+HF_TOKEN을 이용하여 private repository에서 CSV 파일을 빠르게 로드합니다.
+"""
+
+import os
+import pandas as pd
+from src.hf_private_csv_loader import HFPrivateCSVLoader
+
+
+def quick_load_csv(repo_id: str, filename: str, token: str = None) -> pd.DataFrame:
+    """
+    가장 간단한 방법으로 CSV 파일을 로드합니다.
+    
+    Args:
+        repo_id: Repository ID (예: "username/repo-name")
+        filename: CSV 파일명
+        token: Hugging Face 토큰 (None이면 환경변수에서 자동 로드)
+    
+    Returns:
+        pandas DataFrame
+    
+    Raises:
+        Exception: 로드 실패시
+    """
+    loader = HFPrivateCSVLoader(token=token)
+    df = loader.load_csv_from_private_repo(repo_id, filename)
+    
+    if df is None:
+        raise Exception(f"CSV 파일 로드 실패: {repo_id}/{filename}")
+    
+    return df
+
+
+def load_csv_with_env_token(repo_id: str, filename: str) -> pd.DataFrame:
+    """
+    환경변수의 토큰을 사용하여 CSV 파일을 로드합니다.
+    
+    Args:
+        repo_id: Repository ID
+        filename: CSV 파일명
+    
+    Returns:
+        pandas DataFrame
+    
+    Raises:
+        Exception: 로드 실패시
+    """
+    return quick_load_csv(repo_id, filename, token=None)
+
+
+def load_freshqa_results(repo_id: str, filename: str = "results.csv", token: str = None) -> pd.DataFrame:
+    """
+    FreshQA 평가 결과 CSV 파일을 로드합니다.
+    
+    Args:
+        repo_id: Repository ID
+        filename: 결과 파일명 (기본값: "results.csv")
+        token: Hugging Face 토큰
+    
+    Returns:
+        pandas DataFrame
+    """
+    df = quick_load_csv(repo_id, filename, token)
+    
+    # FreshQA 결과에 필요한 컬럼들이 있는지 확인
+    required_columns = ['id', 'accuracy', 'evaluation_date']
+    missing_columns = [col for col in required_columns if col not in df.columns]
+    
+    # if missing_columns:
+    #     print(f"⚠️ 경고: 다음 컬럼들이 없습니다: {missing_columns}")
+    
+    return df
+
+
+def merge_with_leaderboard(new_results_df: pd.DataFrame, 
+                          leaderboard_path: str = "data/leaderboard_results.csv") -> pd.DataFrame:
+    """
+    새로운 결과를 기존 리더보드와 병합합니다.
+    
+    Args:
+        new_results_df: 새로운 결과 DataFrame
+        leaderboard_path: 기존 리더보드 파일 경로
+    
+    Returns:
+        병합된 DataFrame
+    """
+    try:
+        # 기존 리더보드 로드
+        existing_df = pd.read_csv(leaderboard_path)
+        
+        # 병합
+        merged_df = pd.concat([existing_df, new_results_df], ignore_index=True)
+        
+        # 중복 제거 (동일한 id와 evaluation_date 조합)
+        if 'id' in merged_df.columns and 'evaluation_date' in merged_df.columns:
+            merged_df = merged_df.drop_duplicates(
+                subset=['id', 'evaluation_date'], 
+                keep='last'
+            )
+        
+        # 정렬 (accuracy 기준)
+        if 'accuracy' in merged_df.columns:
+            merged_df = merged_df.sort_values('accuracy', ascending=False)
+        
+        # 저장
+        merged_df.to_csv(leaderboard_path, index=False)
+        
+        return merged_df
+        
+    except FileNotFoundError:
+        # 기존 리더보드가 없으면 새로 생성
+        new_results_df.to_csv(leaderboard_path, index=False)
+        return new_results_df
+
+
+# 사용 예시
+if __name__ == "__main__":
+    # 예시 1: 가장 간단한 사용법
+    # === 예시 1: 간단한 사용법 ===
+    try:
+        df = quick_load_csv(
+            repo_id="username/private-dataset",
+            filename="data.csv",
+            token="your_token_here"  # 실제 토큰으로 변경
+        )
+        # print(f"✅ 로드 성공: {len(df)} 행, {len(df.columns)} 열")
+        # print(f"컬럼: {list(df.columns)}")
+    except Exception as e:
+        print(f"❌ 오류: {e}")
+    
+    # 예시 2: 환경변수 토큰 사용
+    # === 예시 2: 환경변수 토큰 사용 ===
+    try:
+        df = load_csv_with_env_token(
+            repo_id="username/private-dataset",
+            filename="data.csv"
+        )
+        # print(f"✅ 로드 성공: {len(df)} 행, {len(df.columns)} 열")
+    except Exception as e:
+        print(f"❌ 오류: {e}")
+    
+    # 예시 3: FreshQA 결과 로드 및 병합
+    # === 예시 3: FreshQA 결과 로드 및 병합 ===
+    try:
+        # FreshQA 결과 로드
+        results_df = load_freshqa_results(
+            repo_id="user/freshqa-results",
+            filename="evaluation_results.csv",
+            token="your_token_here"  # 실제 토큰으로 변경
+        )
+        
+        # 리더보드와 병합
+        merged_df = merge_with_leaderboard(results_df)
+        # print(f"✅ 병합 완료: 총 {len(merged_df)} 개 결과")
+        
+    except Exception as e:
+        print(f"❌ 오류: {e}")

src/submission_handler.py

@@ -0,0 +1,615 @@
+from __future__ import annotations
+
+import os
+import time
+import queue
+from dataclasses import dataclass
+from typing import Any, Optional, Dict, Tuple, Callable
+import pandas as pd
+import gradio as gr
+
+from config import Config
+from src.submission_tracker import get_submission_tracker, SubmissionTracker
+from src.quick_csv_loader import quick_load_csv
+from src.leaderboard_manager import append_to_leaderboard_data
+from src.utils import get_current_datetime_str
+from freshqa.fresheval_parallel import evaluate_dataframe_parallel
+from freshqa.freshqa_acc import process_freshqa_dataframe, calculate_accuracy
+from freshqa.merge_csv_with_model_response import merge_dataframe_with_model_response_df
+
+
+# -------------------------
+# 공통 반환형(Result)
+# -------------------------
+@dataclass
+class Result:
+    ok: bool
+    data: Optional[Any] = None
+    error: Optional[str] = None
+    meta: Optional[Dict] = None
+
+
+# -------------------------
+# 핵심 핸들러
+# -------------------------
+class SubmissionHandler:
+    """
+    제출 파일 처리 및 FreshQA 평가 오케스트레이션.
+    - Tracker/Config 의존성 주입
+    - 내부 helper는 Result/명확한 타입 반환
+    - 실제 저장/한도/사용자 ID는 tracker가 처리(핸들러는 호출만)
+    """
+
+    def __init__(self, tracker: Optional[SubmissionTracker] = None, cfg: Optional[type] = None):
+        # Dependency Injection
+        self.tracker = tracker
+        self.cfg = cfg or Config
+
+        # 기존 코드와 호환되는 속성 (Config 직접 참조 제거)
+        self.enable_limit = getattr(self.cfg, "ENABLE_SUBMISSION_LIMIT", False)
+        self.repo_id = getattr(self.cfg, "FRESHQA_DATA_REPO_ID", None)
+        self.filename = getattr(self.cfg, "FRESHQA_DATA_FILENAME", None)
+        self.hf_token = getattr(self.cfg, "HF_TOKEN", None)
+
+        # 필수 설정 점검
+        if not self.repo_id:
+            raise ValueError("❌ FRESHQA_DATA_REPO_ID 환경 변수가 설정되지 않았습니다.")
+        if not self.filename:
+            raise ValueError("❌ FRESHQA_DATA_FILENAME 환경 변수가 설정되지 않았습니다.")
+        if not self.hf_token:
+            raise ValueError("❌ HF_TOKEN 환경 변수가 설정되지 않았습니다.")
+
+    # --------- 1) 제출 파일 검증 ----------
+    def _validate_submission_file(self, file) -> Result:
+        if file is None:
+            return Result(ok=False, error="❌ CSV 파일을 업로드해주세요.")
+        try:
+            df = pd.read_csv(file.name)
+        except Exception as e:
+            return Result(ok=False, error=f"❌ CSV 로딩 실패: {e}")
+
+        required_columns = ["question", "model_response"]
+        for col in required_columns:
+            if col not in df.columns:
+                return Result(ok=False, error=f"❌ CSV 파일의 컬럼에 '{col}'이(가) 없습니다.")
+        if len(df) == 0:
+            return Result(ok=False, error="❌ CSV 파일에 데이터가 없습니다.")
+        if df["question"].isnull().any() or df["model_response"].isnull().any():
+            return Result(ok=False, error="❌ 'question' 또는 'model_response' 컬럼에 누락된 값이 있습니다.")
+
+        return Result(ok=True)
+
+    # --------- 2) 빠른 로딩 ----------
+    def _load_submission_df(self, file) -> Result:
+        try:
+            df = quick_load_csv(self.repo_id, self.filename, self.hf_token)
+        except Exception as e:
+            return Result(ok=False, error=f"❌ CSV 로딩 실패: {e}")
+        return Result(ok=True, data=df)
+
+    # --------- 3) 병합 ----------
+    def _merge_with_base(self, submission_df: pd.DataFrame, file_name: str) -> Result:
+        try:
+            merged_df = merge_dataframe_with_model_response_df(submission_df, file_name)
+            return Result(ok=True, data=merged_df)
+        except Exception as e:
+            return Result(ok=False, error=f"❌ 기준 데이터와 병합 실패: {e}")
+
+    # --------- 4) 평가 ----------
+    def _evaluate_freshqa(
+        self,
+        merged_df: pd.DataFrame,
+        on_progress: Optional[Callable[[int, int, str], None]] = None,
+    ) -> Result:
+        """Relaxed/Strict 동시 실행 + 큐 기반 진행률 갱신"""
+        q: "queue.Queue[Tuple[int, int, str]]" = queue.Queue()
+
+        # 두 모드(Relaxed, Strict)를 병렬로 처리하므로 총 진행 단위는 2배
+        total_items = len(merged_df) * 2
+        done_count = 0
+
+        def _drain_queue(block: bool = False):
+            nonlocal done_count
+            while True:
+                try:
+                    item = q.get(block=block, timeout=0.05 if block else 0)
+                except Exception:
+                    break
+                try:
+                    # 최신 커밋 기준: progress_queue에는 1씩 증가하는 정수만 들어옵니다.
+                    if isinstance(item, int):
+                        done_count += item
+                        if on_progress:
+                            remaining = max(total_items - done_count, 0)
+                            desc_text = f"평가 중... {done_count}/{total_items}"
+                            on_progress(done_count, total_items, desc_text)
+                    # 혹시 과거 포맷(tuple)이 들어오더라도 방어적으로 처리
+                    elif isinstance(item, tuple) and len(item) == 3 and on_progress:
+                        on_progress(item[0], item[1], item[2])
+                finally:
+                    q.task_done()
+
+        from concurrent.futures import ThreadPoolExecutor
+
+        try:
+            with ThreadPoolExecutor(max_workers=2) as ex:
+                relaxed_f = ex.submit(
+                    evaluate_dataframe_parallel,
+                    df=merged_df,
+                    mode="Relaxed",
+                    on_item_done=None,
+                    progress_queue=q,
+                )
+                strict_f = ex.submit(
+                    evaluate_dataframe_parallel,
+                    df=merged_df,
+                    mode="Strict",
+                    on_item_done=None,
+                    progress_queue=q,
+                )
+
+                while True:
+                    _drain_queue(block=False)
+                    if relaxed_f.done() and strict_f.done():
+                        break
+                    time.sleep(0.05)
+
+                _drain_queue(block=True)
+
+                relaxed = relaxed_f.result()
+                strict = strict_f.result()
+
+            return Result(ok=True, data=(relaxed, strict))
+        except Exception as e:
+            return Result(ok=False, error=f"❌ 평가 중 오류 발생: {e}")
+
+    # --------- 5) 정확도 계산 ----------
+    def _calculate_accuracy(self, fresheval_df: pd.DataFrame) -> Result:
+        try:
+            processed = process_freshqa_dataframe(fresheval_df)
+            accs, counts = calculate_accuracy(processed)
+            return Result(ok=True, data=(processed, accs, counts))
+        except Exception as e:
+            return Result(ok=False, error=f"❌ 결과 집계 중 오류가 발생했습니다: {e}")
+
+    # --------- 6) 요약 ----------
+    def _build_summary(self, name: str, relaxed_accs: dict, strict_accs: dict) -> str:
+        """
+        result_summary가 기대하는 이전 문자열 포맷을 그대로 유지합니다.
+        - 헤더/섹션 제목/줄바꿈/표현(소수점 1자리) 동일
+        - 테스트셋 기준 지표: acc_test, *_fast_changing, *_two_hop, *_old, *_new, *_vp, *_fp
+        """
+        submitter = name if name else "(이름 미입력)"
+
+        lines = []
+        lines.append(f"**제출자**: {submitter}")
+        lines.append("")
+        lines.append("**정확도 (테스트셋 기준)**")
+        lines.append(f"- Relaxed: {relaxed_accs.get('acc_test', 0):.1f}%")
+        lines.append(f"- Strict: {strict_accs.get('acc_test', 0):.1f}%")
+        lines.append("")
+        lines.append("**세부 지표 (테스트셋)**")
+        lines.append(
+            f"- Fast Changing: R {relaxed_accs.get('acc_test_fast_changing', 0):.1f}% / "
+            f"S {strict_accs.get('acc_test_fast_changing', 0):.1f}%"
+        )
+        lines.append(
+            f"- Two-hop: R {relaxed_accs.get('acc_test_two_hop', 0):.1f}% / "
+            f"S {strict_accs.get('acc_test_two_hop', 0):.1f}%"
+        )
+        lines.append(
+            f"- Old: R {relaxed_accs.get('acc_test_old', 0):.1f}% / "
+            f"S {strict_accs.get('acc_test_old', 0):.1f}%"
+        )
+        lines.append(
+            f"- New: R {relaxed_accs.get('acc_test_new', 0):.1f}% / "
+            f"S {strict_accs.get('acc_test_new', 0):.1f}%"
+        )
+        lines.append(
+            f"- VP: R {relaxed_accs.get('acc_test_vp', 0):.1f}% / "
+            f"S {strict_accs.get('acc_test_vp', 0):.1f}%"
+        )
+        lines.append(
+            f"- FP: R {relaxed_accs.get('acc_test_fp', 0):.1f}% / "
+            f"S {strict_accs.get('acc_test_fp', 0):.1f}%"
+        )
+        return "\n".join(lines)
+    
+    def _get_result_summary(
+        self,
+        file_name: str,
+        name: str,
+        relaxed_accs: dict,
+        strict_accs: dict,
+        relaxed_table: pd.DataFrame,
+        strict_table: pd.DataFrame,
+    ) -> str:
+        # 보기 좋은 포맷으로 왼쪽 정렬/구분선/여백을 적용해 문자열 구성
+        display_file = os.path.basename(file_name) if file_name else ""
+        lines: list[str] = []
+        lines.append("✅ 제출 및 평가 완료")
+        lines.append("")
+        lines.append("[기본 정보]")
+        lines.append(f"- 제출 파일: {display_file}")
+        lines.append(f"- 평가 시스템: Solar Pro API")
+        lines.append("")
+        lines.append("[결과 요약]")
+        lines.append("- Relaxed 모드")
+        lines.append(f"  · 전체 정확도: {float(relaxed_accs.get('acc', 0)):.1f}%")
+        lines.append(
+            f"  · Fast-changing: {float(relaxed_accs.get('acc_fast_changing', 0)):.1f}% | "
+            f"Slow-changing: {float(relaxed_accs.get('acc_slow_changing', 0)):.1f}% | "
+            f"Never-changing: {float(relaxed_accs.get('acc_never_changing', 0)):.1f}%"
+        )
+        lines.append(f"  · False premise: {float(relaxed_accs.get('acc_fp', 0)):.1f}%")
+        lines.append("")
+        lines.append("- Strict 모드")
+        lines.append(f"  · 전체 정확도: {float(strict_accs.get('acc', 0)):.1f}%")
+        lines.append(
+            f"  · Fast-changing: {float(strict_accs.get('acc_fast_changing', 0)):.1f}% | "
+            f"Slow-changing: {float(strict_accs.get('acc_slow_changing', 0)):.1f}% | "
+            f"Never-changing: {float(strict_accs.get('acc_never_changing', 0)):.1f}%"
+        )
+        lines.append(f"  · False premise: {float(strict_accs.get('acc_fp', 0)):.1f}%")
+        lines.append("")
+        lines.append("[제출 메타]")
+        lines.append(f"- 제출자: {name if name else 'Unknown'}")
+        lines.append(f"- 평가 일시: {get_current_datetime_str()}")
+        lines.append(f"- 비고: Relaxed/Strict 결과가 리더보드에 반영되었습니다.")
+        lines.append("")
+        sep = "-" * 60
+        lines.append(sep)
+        lines.append("상세 결과 테이블 (Relaxed)")
+        lines.append(sep)
+        lines.append(relaxed_table.to_string(index=False))
+        lines.append("")
+        lines.append(sep)
+        lines.append("상세 결과 테이블 (Strict)")
+        lines.append(sep)
+        lines.append(strict_table.to_string(index=False))
+        return "\n".join(lines)
+
+    # --------- 7) 정확도 표 ----------
+    def _create_detailed_results_table(self, accs: dict, counts: dict) -> pd.DataFrame:
+        table_data = []
+
+        # 전체 정확도
+        table_data.append({
+            '카테고리': '전체 정확도',
+            '전체': f"{accs.get('acc', 0):.1f}% ({counts.get('acc', 0)}개)",
+            '테스트': f"{accs.get('acc_test', 0):.1f}% ({counts.get('acc_test', 0)}개)",
+            '개발': f"{accs.get('acc_dev', 0):.1f}% ({counts.get('acc_dev', 0)}개)"
+        })
+        
+        # 사실 유형별 정확도
+        fact_types = {
+            'fast_changing': '빠르게 변하는 사실',
+            'slow_changing': '천천히 변하는 사실',
+            'never_changing': '변하지 않는 사실'
+        }
+
+        for key, name in fact_types.items():
+            table_data.append({
+                '카테고리': name,
+                '전체': f"{accs.get(f'acc_{key}', 0):.1f}% ({counts.get(f'acc_{key}', 0)}개)",
+                '테스트': f"{accs.get(f'acc_test_{key}', 0):.1f}% ({counts.get(f'acc_test_{key}', 0)}개)",
+                '개발': f"{accs.get(f'acc_dev_{key}', 0):.1f}% ({counts.get(f'acc_dev_{key}', 0)}개)"
+            })
+            
+        # 질문 유형별 정확도
+        question_types = {
+            'vp': '유효한 전제 (Valid Premise)',
+            'fp': '잘못된 전제 (False Premise)'
+        }
+
+        for key, name in question_types.items():
+            table_data.append({
+                '카테고리': name,
+                '전체': f"{accs.get(f'acc_{key}', 0):.1f}% ({counts.get(f'acc_{key}', 0)}개)",
+                '테스트': f"{accs.get(f'acc_test_{key}', 0):.1f}% ({counts.get(f'acc_test_{key}', 0)}개)",
+                '개발': f"{accs.get(f'acc_dev_{key}', 0):.1f}% ({counts.get(f'acc_dev_{key}', 0)}개)"
+            })
+            
+            # 홉 수별 정확도
+            table_data.append({
+                '카테고리': f"  └ {name} (단일 홉)",
+                '전체': f"{accs.get(f'acc_{key}_one_hop', 0):.1f}% ({counts.get(f'acc_{key}_one_hop', 0)}개)",
+                '테스트': f"{accs.get(f'acc_test_{key}_one_hop', 0):.1f}% ({counts.get(f'acc_test_{key}_one_hop', 0)}개)",
+                '개발': f"{accs.get(f'acc_dev_{key}_one_hop', 0):.1f}% ({counts.get(f'acc_dev_{key}_one_hop', 0)}개)"
+            })
+            
+            table_data.append({
+                '카테고리': f"  └ {name} (다중 홉)",
+                '전체': f"{accs.get(f'acc_{key}_two_hop', 0):.1f}% ({counts.get(f'acc_{key}_two_hop', 0)}개)",
+                '테스트': f"{accs.get(f'acc_test_{key}_two_hop', 0):.1f}% ({counts.get(f'acc_test_{key}_two_hop', 0)}개)",
+                '개발': f"{accs.get(f'acc_dev_{key}_two_hop', 0):.1f}% ({counts.get(f'acc_dev_{key}_two_hop', 0)}개)"
+            })
+            
+            # 연도별 정확도
+            table_data.append({
+                '카테고리': f"  └ {name} (오래된 데이터)",
+                '전체': f"{accs.get(f'acc_{key}_old', 0):.1f}% ({counts.get(f'acc_{key}_old', 0)}개)",
+                '테스트': f"{accs.get(f'acc_test_{key}_old', 0):.1f}% ({counts.get(f'acc_test_{key}_old', 0)}개)",
+                '개발': f"{accs.get(f'acc_dev_{key}_old', 0):.1f}% ({counts.get(f'acc_dev_{key}_old', 0)}개)"
+            })
+            
+            table_data.append({
+                '카테고리': f"  └ {name} (최�� 데이터)",
+                '전체': f"{accs.get(f'acc_{key}_new', 0):.1f}% ({counts.get(f'acc_{key}_new', 0)}개)",
+                '테스트': f"{accs.get(f'acc_test_{key}_new', 0):.1f}% ({counts.get(f'acc_test_{key}_new', 0)}개)",
+                '개발': f"{accs.get(f'acc_dev_{key}_new', 0):.1f}% ({counts.get(f'acc_dev_{key}_new', 0)}개)"
+            })
+        
+        return pd.DataFrame(table_data)
+
+    # --------- 8) 리더보드 행 생성 ----------
+    def _build_leaderboard_rows(
+        self,
+        name: str,
+        submit_model: str,
+        submit_description: Optional[str],
+        mode: str,
+        accs: dict
+    ):
+        submitter_id = f"{name}".strip()
+        result = {
+            'id': submitter_id if submitter_id else "Unknown",
+            'model': submit_model,
+            'description': submit_description,
+            'accuracy': float(accs.get('acc_test', 0)),
+            'fast_changing_accuracy': float(accs.get('acc_test_fast_changing', 0)),
+            'slow_changing_accuracy': float(accs.get('acc_test_slow_changing', 0)),
+            'never_changing_accuracy': float(accs.get('acc_test_never_changing', 0)),
+            'acc_vp': float(accs.get('acc_test_vp', 0)),
+            'acc_fp': float(accs.get('acc_test_fp', 0)),
+            'acc_vp_one_hop': float(accs.get('acc_test_vp_one_hop', 0)),
+            'acc_vp_two_hop': float(accs.get('acc_test_vp_two_hop', 0)),
+            'acc_fp_one_hop': float(accs.get('acc_test_fp_one_hop', 0)),
+            'acc_fp_two_hop': float(accs.get('acc_test_fp_two_hop', 0)),
+            'acc_vp_old': float(accs.get('acc_test_vp_old', 0)),
+            'acc_vp_new': float(accs.get('acc_test_vp_new', 0)),
+            'acc_fp_old': float(accs.get('acc_test_fp_old', 0)),
+            'acc_fp_new': float(accs.get('acc_test_fp_new', 0)),
+            # 도메인별 정확도 추가 (test 결과만 사용)
+            'acc_politics': float(accs.get('acc_test_politics', 0)),
+            'acc_sports': float(accs.get('acc_test_sports', 0)),
+            'acc_entertainment': float(accs.get('acc_test_entertainment', 0)),
+            'acc_weather': float(accs.get('acc_test_weather', 0)),
+            'acc_world': float(accs.get('acc_test_world', 0)),
+            'acc_economy': float(accs.get('acc_test_economy', 0)),
+            'acc_society': float(accs.get('acc_test_society', 0)),
+            'acc_it_science': float(accs.get('acc_test_it_science', 0)),
+            'acc_life_culture': float(accs.get('acc_test_life_culture', 0)),
+            'acc_unknown': float(accs.get('acc_test_unknown', 0)),
+            'total_questions': int(accs.get('acc_test', 0)),
+            'evaluation_date': get_current_datetime_str(),
+            'evaluation_mode': mode
+        }
+        return result
+    
+    def _save_leaderboard(
+        self,
+        name: str,
+        submit_model: str,
+        submit_description: Optional[str],
+        relaxed_accs: dict,
+        strict_accs: dict
+    ):
+        rows = [
+            self._build_leaderboard_rows(name, submit_model, submit_description, 'Relaxed', relaxed_accs),
+            self._build_leaderboard_rows(name, submit_model, submit_description, 'Strict', strict_accs),
+        ]
+        try:
+            append_to_leaderboard_data(rows)
+        except Exception as e:
+            print(f"⚠️ 리더보드 저장 실패: {e}")
+
+
+    # --------- 9) 공개 엔드포인트(핵심) ----------
+    def process_submission(
+        self,
+        file,
+        name: str,
+        submit_model: str,
+        submit_description: str,
+        progress: gr.Progress = gr.Progress()
+    ) -> str:
+        """
+        제출 파일 처리 및 평가
+        - 내부 helper는 Result 기반으로 리턴
+        - 최종 Gradio 출력은 문자열(기존 호환)
+        """
+        start = time.time()
+
+        normalized_model = (submit_model or "").strip() or "Anonymous Model"
+        normalized_description_raw = (submit_description or "").strip()
+        normalized_description = normalized_description_raw if normalized_description_raw else None
+
+        # 1) 제출 제한 확인
+        tracker: Optional[SubmissionTracker] = None
+        if self.enable_limit:
+            tracker = self.tracker or get_submission_tracker()
+            if tracker is not None:
+                self.tracker = tracker
+        if self.enable_limit and tracker:
+            try:
+                can_submit, message, remaining = tracker.can_submit()
+                if not can_submit:
+                    return f"❌ 제출 제한: {message}"
+            except Exception as e:
+                return f"❌ 제출 제한 확인 실패: {e}"
+
+        # 2) 파일 검증
+        progress(0.05, desc="제출 파일 검증 중...")
+        v = self._validate_submission_file(file)
+        if not v.ok:
+            return v.error or "❌ 제출 파일 검증 실패"
+
+        # 3) 로드
+        progress(0.1, desc="기준 데이터 로드 중...")
+        loaded = self._load_submission_df(file)
+        if not loaded.ok:
+            return loaded.error or "❌ CSV 로딩 실패"
+        submission_df: pd.DataFrame = loaded.data
+
+        # 4) 병합
+        progress(0.15, desc="기준 데이터와 병합 중...")
+        mg = self._merge_with_base(submission_df, file.name)
+        if not mg.ok:
+            return mg.error or "❌ 기준 데이터 병합 실패"
+        merged_df: pd.DataFrame = mg.data
+
+        # 5) 평가 (0.15 ~ 0.9 구간 진행률 매핑)
+        progress(0.15, desc="FreshQA 평가 준비 중...")
+
+        def on_inner_progress(done: int, total: int, desc: str):
+            frac = 0.15 + 0.75 * (done / max(total, 1))
+            progress(frac, desc=desc)
+
+        ev = self._evaluate_freshqa(merged_df, on_progress=on_inner_progress)
+        if not ev.ok:
+            # 실패 기록
+            if self.enable_limit and tracker:
+                try:
+                    tracker.record_submission(
+                        name,
+                        os.path.basename(file.name),
+                        success=False,
+                        error_message=ev.error or "평가 실패",
+                        submit_model=normalized_model,
+                        submit_description=normalized_description,
+                    )
+                except Exception:
+                    pass
+            return ev.error or "❌ 평가 중 오류가 발생했습니다"
+
+        relaxed_df, strict_df = ev.data  # type: ignore[assignment]
+
+        # 6) 결과 집계
+        progress(0.8, desc="평가 결과 분석 중...")
+        r = self._calculate_accuracy(relaxed_df)
+        if not r.ok:
+            if self.enable_limit and tracker:
+                try:
+                    tracker.record_submission(
+                        name,
+                        os.path.basename(file.name),
+                        success=False,
+                        error_message=r.error or "집계 실패",
+                        submit_model=normalized_model,
+                        submit_description=normalized_description,
+                    )
+                except Exception:
+                    pass
+            return r.error or "❌ 결과 집계 실패"
+
+        s = self._calculate_accuracy(strict_df)
+        if not s.ok:
+            if self.enable_limit and tracker:
+                try:
+                    tracker.record_submission(
+                        name,
+                        os.path.basename(file.name),
+                        success=False,
+                        error_message=s.error or "집계 실패",
+                        submit_model=normalized_model,
+                        submit_description=normalized_description,
+                    )
+                except Exception:
+                    pass
+            return s.error or "❌ 결과 집계 실패"
+
+        relaxed_processed, relaxed_accs, relaxed_counts = r.data  # type: ignore[misc]
+        strict_processed, strict_accs, strict_counts = s.data  # type: ignore[misc]
+
+        # 7) 요약/표
+        relaxed_table = self._create_detailed_results_table(relaxed_accs, relaxed_counts)
+        strict_table  = self._create_detailed_results_table(strict_accs, strict_counts)
+        
+        result_summary = self._get_result_summary(
+            file_name=file.name if file else "",
+            name=name,
+            relaxed_accs=relaxed_accs,
+            strict_accs=strict_accs,
+            relaxed_table=relaxed_table,
+            strict_table=strict_table,
+        )
+
+        # 8) 제출 성공 기록 및 리더보드 저장
+        if self.enable_limit and tracker:
+            progress(0.85, desc="제출 내역 저장 중...")
+            save_ok = tracker.record_submission(
+                name,
+                os.path.basename(file.name),
+                success=True,
+                submit_model=normalized_model,
+                submit_description=normalized_description,
+            )
+            progress(0.9, desc="리더보드 업데이트 중...")
+            self._save_leaderboard(name, normalized_model, normalized_description, relaxed_accs, strict_accs)
+        else:
+            self._save_leaderboard(name, normalized_model, normalized_description, relaxed_accs, strict_accs)
+
+        # 9) 결과 문자열 구성
+        progress(1.0, desc="완료")
+        return result_summary
+
+
+# -------------------------
+# 모듈-레벨 엔트리포인트 (기존 UI 호환)
+# -------------------------
+def process_submission(
+    file,
+    name: str,
+    submit_model: str,
+    submit_description: str,
+    progress: gr.Progress = gr.Progress()
+) -> str:
+    """
+    Gradio에서 직접 호출하는 엔트리포인트.
+    내부적으로 DI를 적용한 SubmissionHandler를 생성해 호출한다.
+    """
+    tracker = get_submission_tracker() if Config.ENABLE_SUBMISSION_LIMIT else None
+    handler = SubmissionHandler(tracker=tracker, cfg=Config)
+    try:
+        return handler.process_submission(
+            file=file,
+            name=name,
+            submit_model=submit_model,
+            submit_description=submit_description,
+            progress=progress,
+        )
+    except Exception as e:
+        # 최상위 보호막: 예상치 못한 예외도 사용자 친화적으로 반환
+        try:
+            tracking_user_id = None
+            if handler.enable_limit and handler.tracker:
+                # 누가 제출했는지는 tracker가 알고 있다면 기록
+                try:
+                    tracking_user_id = handler.tracker.get_user_id()
+                except Exception:
+                    tracking_user_id = None
+            if handler.enable_limit and handler.tracker:
+                handler.tracker.record_submission(
+                    name=name,
+                    file_name=os.path.basename(file.name) if file else "(unknown)",
+                    success=False,
+                    error_message=str(e),
+                    submit_model=(submit_model or "").strip() or "Anonymous Model",
+                    submit_description=(submit_description or "").strip() or None,
+                )
+        except Exception:
+            # 기록 실패는 조용히 무시
+            pass
+
+        total_time = 0.0  # 상단에서 측정하지 못했을 수 있으므로 0으로
+        error_message = str(e)
+
+        return (
+            "❌ 평가 실패\n\n"
+            "오류 내용:\n"
+            f"{error_message}\n\n"
+            f"소요 시간: {total_time:.2f}초 ({total_time/60:.2f}분)\n\n"
+            "제출은 정상적으로 처리되었지만, 평가 과정에서 오류가 발생했습니다.\n"
+            "제출 기록은 저장되었습니다."
+        )

src/submission_tracker.py

@@ -0,0 +1,304 @@
+"""
+사용자 제출 추적 모듈
+HuggingFace 사용자 ID를 기반으로 하루 3번 제한 기능을 제공합니다.
+제출 정보는 별도의 HuggingFace repository에서 관리됩니다.
+"""
+
+import os
+import json
+import pandas as pd
+import tempfile
+from datetime import datetime, date
+from typing import Dict, List, Optional, Tuple
+from huggingface_hub import whoami, hf_hub_download, login, HfApi
+import pytz
+from src.utils import file_lock, get_current_date_str, get_current_datetime_str
+
+# 한국 시간대 설정
+KOREA_TZ = pytz.timezone('Asia/Seoul')
+
+
+class SubmissionTracker:
+    """사용자 제출 추적 클래스 - HuggingFace Repository 기반"""
+    
+    def __init__(self, 
+                 repo_id: Optional[str] = None,
+                 token: Optional[str] = None,
+                 filename: str = "user_submissions.json"):
+        """
+        Args:
+            repo_id: HuggingFace repository ID (예: "username/submission-tracker")
+            token: HuggingFace API 토큰 (None이면 환경변수에서 자동 로드)
+            filename: 제출 기록 파일명
+        """
+        # 환경변수에서 설정 가져오기
+        self.repo_id = repo_id or os.getenv('SUBMISSION_TRACKER_REPO_ID')
+        self.token = token or os.getenv('HF_TOKEN') or os.getenv('HUGGINGFACE_HUB_TOKEN')
+        self.filename = filename
+        
+        if not self.repo_id:
+            raise ValueError(
+                "SUBMISSION_TRACKER_REPO_ID 환경변수가 설정되지 않았습니다. "
+                "또는 repo_id를 직접 전달해주세요."
+            )
+        
+        if not self.token:
+            raise ValueError(
+                "HuggingFace 토큰이 필요합니다. "
+                "토큰을 직접 전달하거나 HF_TOKEN 환경변수를 설정하세요."
+            )
+        
+        # HuggingFace API 초기화
+        self.api = HfApi()
+        try:
+            login(token=self.token)
+            # ✅ HuggingFace에 성공적으로 로그인되었습니다.
+        except Exception as e:
+            print(f"❌ HuggingFace 로그인 실패: {e}")
+            raise
+        
+        # 제출 기록 로드
+        self.submissions = self.load_submissions()
+    
+    def load_submissions(self) -> Dict:
+        """HuggingFace repository에서 제출 기록 로드"""
+        try:
+            # 📥 HuggingFace repository에서 제출 기록 로드 중: {self.repo_id}/{self.filename}
+            
+            # 임시 디렉토리에 파일 다운로드
+            with tempfile.TemporaryDirectory() as temp_dir:
+                file_path = hf_hub_download(
+                    repo_id=self.repo_id,
+                    filename=self.filename,
+                    local_dir=temp_dir,
+                    repo_type="dataset",
+                    token=self.token
+                )
+                
+                # JSON 파일 로드
+                with open(file_path, 'r', encoding='utf-8') as f:
+                    submissions = json.load(f)
+                
+                # ✅ 제출 기록 로드 완료: {len(submissions)}명의 사용자 기록
+                return submissions
+                
+        except Exception as e:
+            print(f"⚠️ 제출 기록 로드 실패 (새로 시작): {e}")
+            return {}
+    
+    def get_user_id(self) -> Optional[str]:
+        """HuggingFace에서 현재 사용자 ID 가져오기 (고유 ID 사용)"""
+        try:
+            user_info = whoami()
+            # 고유 ID 사용 (변경 불가능한 식별자)
+            return user_info.get("id", None)
+        except Exception as e:
+            print(f"⚠️ 사용자 ID 가져오기 실패: {e}")
+            raise Exception("❌ 사용자 ID를 가져올 수 없습니다. HuggingFace에 로그인되어 있는지 확인해주세요.")
+    
+    def get_today_submissions(self, user_id: str) -> List[Dict]:
+        """오늘 사용자의 제출 기록 가져오기"""
+        today = get_current_date_str()
+        user_submissions = self.submissions.get(user_id, {})
+        return user_submissions.get(today, [])
+    
+    def can_submit(self, submissions_data: Optional[Dict] = None) -> Tuple[bool, str, int]:
+        """사용자가 제출할 수 있는지 확인"""
+        user_id = self.get_user_id()
+        data = submissions_data if submissions_data is not None else self.submissions
+        today = get_current_date_str()
+        today_submissions = data.get(user_id, {}).get(today, [])
+        successful_count = len([s for s in today_submissions if s.get('success', False)])
+
+        if successful_count >= 3:
+            raise Exception("❌ 오늘 제출 한도를 초과했습니다. 내일 다시 시도해주세요.")
+
+        remaining = 3 - successful_count
+        return True, f"✅ 제출 가능합니다. (오늘 {successful_count}/3회 사용, {remaining}회 남음)", remaining
+    
+    def record_submission(
+        self,
+        submitter_name: str,
+        file_name: str,
+        success: bool,
+        error_message: str = None,
+        submit_model: Optional[str] = None,
+        submit_description: Optional[str] = None
+    ) -> bool:
+        """제출 기록 추가 (파일 잠금으로 보호)"""
+        user_id = self.get_user_id()
+        
+        # 잠금 파일 경로 생성
+        lock_file_path = tempfile.gettempdir() + f'/{self.repo_id.replace("/", "_")}.lock'
+        
+        # 파일 잠금으로 전체 과정을 atomic하게 보호
+        with file_lock(lock_file_path):
+            try:
+                # 최신 데이터를 다시 로드 (다른 프로세스에서 업데이트했을 수 있음)
+                latest_submissions = self.load_submissions()
+                
+                # Lock 내부에서 최신 데이터 기준으로 제출 가능 여부 재확인
+                try:
+                    can_submit, message, _ = self.can_submit(submissions_data=latest_submissions)
+                except Exception as e:
+                    # 제출 제한 초과 시
+                    # 제출 제한 초과 메시지: {e}
+                    # 메모리만 업데이트하고 저장하지 않음
+                    self.submissions = latest_submissions
+                    return False
+                
+                # 새로운 제출 기록 추가
+                current_datetime = get_current_datetime_str()
+                
+                if user_id not in latest_submissions:
+                    latest_submissions[user_id] = {}
+                
+                today = get_current_date_str()
+                if today not in latest_submissions[user_id]:
+                    latest_submissions[user_id][today] = []
+                
+                submission_record = {
+                    "timestamp": current_datetime,
+                    "submitter_name": submitter_name,
+                    "file_name": file_name,
+                    "success": success,
+                    "error_message": error_message,
+                    "submit_model": submit_model,
+                    "submit_description": submit_description
+                }
+                
+                latest_submissions[user_id][today].append(submission_record)
+                
+                # 메모리 업데이트
+                self.submissions = latest_submissions
+                
+                # 저장
+                return self._save_submissions_internal(latest_submissions)
+                
+            except Exception as e:
+                print(f"❌ 제출 기록 추가 실패: {e}")
+                return False
+    
+    def _save_submissions_internal(self, submissions_data: Dict) -> bool:
+        """내부 저장 함수 (lock은 이미 획득된 상태)"""
+        try:
+            # 💾 HuggingFace repository에 제출 기록 저장 중: {self.repo_id}/{self.filename}
+            
+            # 임시 파일에 JSON 데이터 저장
+            with tempfile.NamedTemporaryFile(mode='w', encoding='utf-8', suffix='.json', delete=False) as temp_file:
+                json.dump(submissions_data, temp_file, ensure_ascii=False, indent=2)
+                temp_file_path = temp_file.name
+            
+            # HuggingFace repository에 파일 업로드
+            self.api.upload_file(
+                path_or_fileobj=temp_file_path,
+                path_in_repo=self.filename,
+                repo_id=self.repo_id,
+                repo_type="dataset",
+                token=self.token,
+                commit_message=f"Update submission records - {datetime.now(KOREA_TZ).strftime('%Y-%m-%d %H:%M:%S')}"
+            )
+            
+            # 임시 파일 삭제
+            os.unlink(temp_file_path)
+            
+            # ✅ 제출 기록 저장 완료
+            return True
+            
+        except Exception as e:
+            print(f"❌ 제출 기록 저장 실패: {e}")
+            return False
+    
+    def get_user_submission_history(self, user_id: str, days: int = 7) -> Dict:
+        """사용자의 최근 제출 기록 가져오기"""
+        if not user_id or user_id not in self.submissions:
+            return {}
+        
+        user_submissions = self.submissions[user_id]
+        today = datetime.now(KOREA_TZ).date()
+        
+        history = {}
+        for i in range(days):
+            check_date = today - pd.Timedelta(days=i)
+            date_str = check_date.strftime('%Y-%m-%d')
+            
+            if date_str in user_submissions:
+                history[date_str] = user_submissions[date_str]
+        
+        return history
+    
+    def get_submission_stats(self, user_id: str) -> Dict:
+        """사용자 제출 통계 가져오기"""
+        if not user_id:
+            return {}
+        
+        today_submissions = self.get_today_submissions(user_id)
+        successful_today_count = len([s for s in today_submissions if s.get('success', False)])
+        history = self.get_user_submission_history(user_id, 7)
+        
+        # 통계 계산
+        total_submissions = sum(len(day_submissions) for day_submissions in history.values())
+        successful_submissions = sum(
+            len([s for s in day_submissions if s.get('success', False)])
+            for day_submissions in history.values()
+        )
+        failed_submissions = total_submissions - successful_submissions
+        
+        return {
+            "today_count": len(today_submissions),
+            "today_remaining": max(0, 3 - successful_today_count),
+            "week_total": total_submissions,
+            "week_successful": successful_submissions,
+            "week_failed": failed_submissions,
+            "history": history
+        }
+    
+    def cleanup_old_records(self, days_to_keep: int = 30):
+        """오래된 제출 기록 정리 (파일 잠금 사용)"""
+        # 잠금 파일 경로 생성
+        lock_file_path = tempfile.gettempdir() + f'/{self.repo_id.replace("/", "_")}.lock'
+        
+        # 파일 잠금으로 전체 과정을 atomic하게 보호
+        with file_lock(lock_file_path):
+            try:
+                # 최신 데이터를 다시 로드
+                latest_submissions = self.load_submissions()
+                
+                cutoff_date = datetime.now(KOREA_TZ) - pd.Timedelta(days=days_to_keep)
+                cutoff_str = cutoff_date.strftime('%Y-%m-%d')
+                
+                cleaned_count = 0
+                for user_id in list(latest_submissions.keys()):
+                    user_submissions = latest_submissions[user_id]
+                    for date_str in list(user_submissions.keys()):
+                        if date_str < cutoff_str:
+                            del user_submissions[date_str]
+                            cleaned_count += 1
+                    
+                    # 빈 사용자 기록 제거
+                    if not user_submissions:
+                        del latest_submissions[user_id]
+                
+                # 메모리 업데이트
+                self.submissions = latest_submissions
+                
+                if cleaned_count > 0:
+                    if self._save_submissions_internal(latest_submissions):
+                        print(f"🧹 {cleaned_count}개의 오래된 제출 기록을 정리했습니다.")
+                    else:
+                        print(f"⚠️ {cleaned_count}개의 오래된 제출 기록을 정리했지만 저장에 실패했습니다.")
+                
+                return cleaned_count
+                
+            except Exception as e:
+                print(f"❌ 오래된 기록 정리 실패: {e}")
+                return 0
+
+
+def get_submission_tracker() -> Optional[SubmissionTracker]:
+    """SubmissionTracker 인스턴스 반환"""
+    try:
+        return SubmissionTracker()
+    except Exception as e:
+        print(f"❌ SubmissionTracker 초기화 실패: {e}")
+        return None

src/utils.py

@@ -0,0 +1,58 @@
+"""
+유틸리티 함수 모듈
+공통으로 사용되는 유틸리티 함수들을 모아놓은 모듈입니다.
+"""
+
+import os
+import fcntl
+import pytz
+from contextlib import contextmanager
+from datetime import datetime
+
+# 한국 시간대 설정
+KOREA_TZ = pytz.timezone('Asia/Seoul')
+
+def get_korea_datetime_now():
+    """한국 시간대의 현재 시간을 반환"""
+    return datetime.now(KOREA_TZ)
+
+def get_current_datetime_str(dt=None):
+    """한국 시간대의 시간을 문자열로 포맷"""
+    if dt is None:
+        dt = get_korea_datetime_now()
+    return dt.strftime('%Y-%m-%d %H:%M:%S')
+
+def get_current_date_str():
+    """현재 날짜를 한국 시간으로 반환"""
+    return get_korea_datetime_now().strftime("%Y-%m-%d")
+
+@contextmanager
+def file_lock(lock_file_path):
+    """
+    파일 기반 배타적 잠금을 제공하는 context manager
+    
+    Args:
+        lock_file_path: 잠금 파일 경로
+    
+    Yields:
+        None (맥락 관리자로만 사용)
+    
+    Examples:
+        >>> with file_lock('/tmp/test.lock'):
+        ...     # 잠금이 걸린 상태에서 작업 수행
+        ...     pass
+    """
+    # 잠금 파일이 없으면 생성
+    if not os.path.exists(lock_file_path):
+        open(lock_file_path, 'w').close()
+    
+    # 잠금 파일을 열고 배타적 잠금 획득
+    with open(lock_file_path, 'r') as lock_file:
+        try:
+            # 배타적 잠금 시도 (다른 프로세스가 대기)
+            fcntl.flock(lock_file.fileno(), fcntl.LOCK_EX)
+            # 잠금 획득 성공, 작업 수행
+            yield
+        finally:
+            # 잠금 해제
+            fcntl.flock(lock_file.fileno(), fcntl.LOCK_UN)

ui/dataset_tab.py

@@ -0,0 +1,142 @@
+"""
+데이터셋 다운로드 탭 UI 컴포넌트
+
+💾 데이터셋 다운로드 탭의 UI와 로직을 관리합니다.
+"""
+
+import gradio as gr
+import pandas as pd
+
+
+def create_dataset_tab():
+    """데이터셋 다운로드 탭 UI 생성"""
+    
+    # 데이터셋 미리보기 로드 (초기화 시 한 번만)
+    try:
+        dev_preview_data = pd.read_csv("data/public/ko-freshqa_2025_dev.csv").head(5)
+        test_preview_data = pd.read_csv("data/public/ko-freshqa_2025_test.csv").head(5)
+    except Exception as e:
+        print(f"⚠️ 데이터셋 미리보기 로드 실패: {e}")
+        dev_preview_data = pd.DataFrame()
+        test_preview_data = pd.DataFrame()
+    
+    gr.Markdown("""
+        ### Ko-FreshQA Dataset
+
+        - 이 데이터셋 및 리더보드는 [FreshQA](https://github.com/freshllms/freshqa)에서 영감을 받아 만들어졌습니다.
+        - fact type(fast changing, slow changing, never changing), 전제의 유효성, 10개의 도메인에 따라 나뉘는 질문들을 통해 한국어 지식과 관련된 LLM의 최신성을 판단할 수 있습니다.
+        - 검증 및 평가에 필요한 데이터셋은 주기적으로 업데이트할 예정입니다.
+
+        <br>    
+
+        ### Ko-FreshQA 데이터셋은 아래와 같은 특징을 가지고 있습니다.
+        - **fact type**
+            - 시간의 흐름에 따른 답변의 변동 가능성에 따라 질문은 아래의 세 가지로 분류됩니다.
+            - **fast changing** : 역사적 사건, 진실과 같이 답변이 거의 변하지 않는 질문  
+            - **slow changing** : 답변이 몇 년에 걸쳐 변하는 질문  
+            - **never changing** : 답변이 보통 1년 또는 그 이내에 변하는 질문  
+
+        - **전제 유효성**
+            - **false premise (T/F)** : 질문에 포함된 전제 자체가 잘못되어 있으면 True, 전제에 문제가 없으면 False
+
+        - **one/multi hop**
+            - 답변을 생성하기 위해 필요한 추론의 개수에 따라 질문을 one hop, multi hop으로 분류합니다.
+
+        - **도메인**
+            - 모든 질문과 대답은 다음 도메인 중 하나로 분류됩니다.  
+            - 정치, 스포츠, 연예, 날씨, 세계, 경제, 사회, IT/과학, 생활/문화, UNK
+
+        - **나머지 메타 정보**
+            - **effective year** : 질문의 답변이 마지막으로 변경된 연도  
+            - **next review** : 예상되는 다음 검토 날짜  
+            - **source** : 질문/답변에 대한 정보를 찾을 수 있는 출처
+        
+        <br>
+    """)
+
+    
+    with gr.Column(elem_classes=["leaderboard-group"]):
+        with gr.Row():
+            with gr.Column():
+                gr.Markdown("### 🧪 DEV 데이터셋 (개발/검증용)")
+                gr.Markdown("""
+                **Dev set**: 550쌍
+                - 모델 개발 및 검증을 위해 사용할 수 있습니다.
+                - 정답을 비롯하여 모든 메타데이터가 제공됩니다.
+                """)
+                
+                # DEV 데이터셋 다운로드 버튼
+                dev_download_btn = gr.DownloadButton(
+                    "💾 DEV 데이터셋 다운로드",
+                    value="data/public/ko-freshqa_2025_dev.csv",
+                    variant="primary",
+                    size="lg"
+                )
+                
+                # DEV 데이터셋 미리보기
+                dev_preview = gr.DataFrame(
+                    value=lambda: pd.read_csv("data/public/ko-freshqa_2025_dev.csv").head(5),
+                    interactive=False,
+                    label=""
+                )
+            
+            with gr.Column():
+                gr.Markdown("### 🎯 TEST 데이터셋 (최종 평가용)")
+                gr.Markdown("""
+                **Test set**: 3,000개
+                - 리더보드 제출을 위한 평가용 데이터셋입니다.
+                - model_response를 채워서 제출해주세요.
+                """)
+                
+                # TEST 데이터셋 다운로드 버튼
+                test_download_btn = gr.DownloadButton(
+                    "💾 TEST 데이터셋 다운로드",
+                    value="data/public/ko-freshqa_2025_test.csv",
+                    variant="primary",
+                    size="lg"
+                )
+                
+                # TEST 데이터셋 미리보기
+                test_preview = gr.DataFrame(
+                    value=lambda: pd.read_csv("data/public/ko-freshqa_2025_test.csv").head(5),
+                    interactive=False,
+                    label=""
+                )
+    
+    # 다운로드 안내 메시지
+    gr.Markdown("""
+        <br>
+
+        ### 💡 다운로드 안내
+
+        - 위의 다운로드 버튼을 클릭하면 브라우저에서 자동으로 파일 다운로드가 시작됩니다.
+        - **DEV 데이터셋**은 모델 개발 및 검증���으로 사용하세요.
+        - **TEST 데이터셋**은 최종 평가 및 리더보드 제출용으로 사용하세요.
+        - 다운로드된 파일은 **CSV 형식**, **UTF-8 인코딩**으로 저장됩니다.
+
+        <br>
+    """)
+
+    # License & References
+    gr.Markdown("""
+        ### 📚 License & References
+
+        - 본 데이터셋은 **CC-BY-ND-NC (저작자표시 · 변경 금지 · 비영리)** 라이선스로 제공됩니다.
+        - 이 리더보드는 IITP의 **“생성형 언어모델의 지속가능성과 시간의 흐름에 따른 최신성 반영을 위한 학습 및 활용 기술 개발”** 사업의 지원을 받아 제작되었습니다.
+        - 이 시스템은 FreshLLMs 프로젝트의 **FreshQA 데이터셋과 평가 방법론**을 기반으로 구축되었습니다.  
+        - 원본 FreshQA는 링크를 참고해 주세요. 👉 https://github.com/freshllms/freshqa
+    """)
+
+
+    gr.Markdown("""
+    ```
+        @misc{vu2023freshllms,
+            title={FreshLLMs: Refreshing Large Language Models with Search Engine Augmentation}, 
+            author={Tu Vu and Mohit Iyyer and Xuezhi Wang and Noah Constant and Jerry Wei and Jason Wei and Chris Tar and Yun-Hsuan Sung and Denny Zhou and Quoc Le and Thang Luong},
+            year={2023},
+            eprint={2310.03214},
+            archivePrefix={arXiv},
+            primaryClass={cs.CL}
+        }
+    ```
+    """)

ui/leaderboard_tab.py

@@ -0,0 +1,229 @@
+"""
+리더보드 탭 UI 컴포넌트
+
+🏆 Leaderboard 탭의 UI와 로직을 관리합니다.
+"""
+
+import gradio as gr
+import pandas as pd
+from src.leaderboard_manager import load_leaderboard_data, prepare_display_data
+
+
+def create_leaderboard_tab():
+    """리더보드 탭 UI 생성"""
+    
+    # 최상단 통합 검색 바 - 개선된 디자인
+    with gr.Row():
+        with gr.Column(scale=12):
+            search_input = gr.Textbox(
+                label="제출자 이름 검색",
+                placeholder="🔍 제출자 이름으로 검색...",
+                value="",
+                container=False,
+                elem_classes=["search-input"]
+            )
+        with gr.Column(scale=1, min_width=100):
+            clear_search_btn = gr.Button(
+                "🗑️ 초기화", 
+                variant="secondary", 
+                size="sm",
+                elem_classes=["clear-search-btn"]
+            )
+        with gr.Column(scale=1, min_width=100):
+            refresh_btn = gr.Button(
+                "🔄 새로고침", 
+                variant="primary",
+                size="sm",
+                elem_classes=["refresh-btn"]
+            )
+
+    # 리더보드 노출 컬럼 및 표시명 설정
+    DISPLAY_COLUMNS = [
+        'rank',
+        'id',
+        'model',
+        'description',
+        'accuracy',
+        'fast_changing_accuracy',
+        'slow_changing_accuracy',
+        'never_changing_accuracy',
+        'acc_vp',
+        'acc_fp',
+        'acc_vp_one_hop',
+        'acc_vp_two_hop',
+        'acc_fp_one_hop',
+        'acc_fp_two_hop',
+        'acc_politics',
+        'acc_sports',
+        'acc_entertainment',
+        'acc_weather',
+        'acc_world',
+        'acc_economy',
+        'acc_society',
+        'acc_it_science',
+        'acc_life_culture',
+        'acc_unknown'
+    ]
+    
+    COLUMN_LABELS = {
+        'rank': 'Rank',
+        'id': 'ID',
+        'model': 'Model',
+        'description': 'Description',
+        'accuracy': 'Accuracy',
+        'fast_changing_accuracy': 'Fast-changing',
+        'slow_changing_accuracy': 'Slow-changing',
+        'never_changing_accuracy': 'Never-changing',
+        'acc_vp': 'Valid Premise',
+        'acc_fp': 'False Premise',
+        'acc_vp_one_hop': 'VP One-hop',
+        'acc_vp_two_hop': 'VP Multi-hop',
+        'acc_fp_one_hop': 'FP One-hop',
+        'acc_fp_two_hop': 'FP Multi-hop',
+        'acc_politics': 'Politics',
+        'acc_sports': 'Sports',
+        'acc_entertainment': 'Entertainment',
+        'acc_weather': 'Weather',
+        'acc_world': 'World',
+        'acc_economy': 'Economy',
+        'acc_society': 'Society',
+        'acc_it_science': 'IT/Science',
+        'acc_life_culture': 'Life/Culture',
+        'acc_unknown': 'Unknown'
+    }
+    
+    def format_leaderboard(df: pd.DataFrame) -> pd.DataFrame:
+        """리더보드에 노출할 컬럼 선택 및 헤더명 변환"""
+        if df.empty:
+            # 빈 DataFrame일 때도 컬럼 구조를 유지하기 위해 빈 DataFrame 생성
+            empty_df = pd.DataFrame(columns=DISPLAY_COLUMNS)
+            rename_map = {col: COLUMN_LABELS[col] for col in DISPLAY_COLUMNS if col in COLUMN_LABELS}
+            return empty_df.rename(columns=rename_map)
+        
+        selected_columns = [col for col in DISPLAY_COLUMNS if col in df.columns]
+        formatted_df = df[selected_columns].copy()
+        rename_map = {col: COLUMN_LABELS[col] for col in selected_columns if col in COLUMN_LABELS}
+        return formatted_df.rename(columns=rename_map)
+    
+    def build_leaderboard_state(source_df: pd.DataFrame):
+        """리더보드 표시용 Relaxed/Strict 데이터와 빈 상태 여부 반환"""
+        if source_df is None:
+            source_df = pd.DataFrame()
+
+        if source_df.empty or 'evaluation_mode' not in source_df.columns:
+            relaxed_df = pd.DataFrame()
+            strict_df = pd.DataFrame()
+        else:
+            relaxed_df = source_df.query("evaluation_mode == 'Relaxed'")
+            strict_df = source_df.query("evaluation_mode == 'Strict'")
+
+        formatted_relaxed = format_leaderboard(prepare_display_data(relaxed_df))
+        formatted_strict = format_leaderboard(prepare_display_data(strict_df))
+        is_empty = relaxed_df.empty and strict_df.empty
+        return formatted_relaxed, formatted_strict, is_empty
+
+    leaderboard_data = load_leaderboard_data()
+    relaxed_initial, strict_initial, is_initial_empty = build_leaderboard_state(leaderboard_data)
+
+    # Relaxed 모드 리더보드
+    with gr.Column(elem_classes=["leaderboard-group"]):
+        gr.Markdown(
+            "### 🟢 Relaxed Evaluation"
+        )
+
+        relaxed_leaderboard_table = gr.DataFrame(
+            value=relaxed_initial,
+            interactive=False,
+            wrap=False,
+            show_label=False,
+            elem_classes=["leaderboard-table"]
+        )
+    
+    # Strict 모드 리더보드
+    with gr.Column(elem_classes=["leaderboard-group"]):
+        gr.Markdown(
+            "### 🔴 Strict Evaluation"
+        )
+        
+        strict_leaderboard_table = gr.DataFrame(
+            value=strict_initial,
+            interactive=False,
+            wrap=False,
+            show_label=False,
+            elem_classes=["leaderboard-table"]
+        )
+    
+    # 리더보드 관련 설명
+    with gr.Column(elem_classes=["leaderboard-group"]):
+        gr.Markdown("""
+            이 리더보드는 [FreshQA](https://github.com/freshllms/freshqa)에서 영감을 받아 만들어졌습니다.  
+            fact type(fast changing, slow changing, never changing), 전제의 진실성,  
+            10개의 도메인에 따라 나뉘는 질문들을 통해 한국어 지식과 관련된 LLM의 최신성을 판단할 수 있습니다.
+
+            이 리더보드는 IITP의 **“생성형 언어모델의 지속가능성과 시간의 흐름에 따른 최신성 반영을 위한 학습 및 활용 기술 개발”** 사업의 지원을 받아 제작되었습니다.
+
+            결과의 무결성·유효성을 유지하고 **순위 조작을 방지**하기 위해 평가 데이터셋의 정답은 기밀로 유지됩니다.
+        """)
+
+
+    
+    # 통합 검색 필터 함수 (Relaxed와 Strict 모드 모두 필터링)
+    def filter_leaderboard_data(search_text):
+        """Relaxed와 Strict 모드 리더보드 데이터 필터링 (CSV 기반)"""
+        try:
+            # CSV에서 전체 데이터 로드
+            all_df = load_leaderboard_data()
+
+            # 검색 필터 적용 (제출자 정보만 검색)
+            if search_text.strip() and 'id' in all_df.columns:
+                mask = all_df['id'].str.contains(search_text, case=False, na=False)
+                filtered_df = all_df[mask]
+            else:
+                filtered_df = all_df
+
+            formatted_relaxed, formatted_strict, _ = build_leaderboard_state(filtered_df)
+            return formatted_relaxed, formatted_strict
+        except Exception as e:
+            print(f"❌ 리더보드 데이터 필터링 실패: {e}")
+            empty = pd.DataFrame()
+            return empty, empty
+    
+    # 검색 이벤트 연결
+    search_input.change(
+        fn=filter_leaderboard_data,
+        inputs=[search_input],
+        outputs=[relaxed_leaderboard_table, strict_leaderboard_table]
+    )
+    
+    # 검색 초기화 버튼
+    def clear_search():
+        try:
+            all_df = load_leaderboard_data()
+            formatted_relaxed, formatted_strict, _ = build_leaderboard_state(all_df)
+            return "", formatted_relaxed, formatted_strict
+        except Exception as e:
+            print(f"❌ 리더보드 데이터 로드 실패: {e}")
+            empty = pd.DataFrame()
+            return "", empty, empty
+    
+    clear_search_btn.click(
+        fn=clear_search,
+        outputs=[search_input, relaxed_leaderboard_table, strict_leaderboard_table]
+    )
+    
+    # 새로고침 버튼
+    def refresh_leaderboard():
+        try:
+            all_df = load_leaderboard_data()
+            formatted_relaxed, formatted_strict, is_empty = build_leaderboard_state(all_df)
+
+            return formatted_relaxed, formatted_strict
+        except Exception as e:
+            print(f"❌ 리더보드 새로고침 실패: {e}")
+            empty = pd.DataFrame()
+            return empty, empty
+    
+    refresh_btn.click(
+        fn=refresh_leaderboard,
+        outputs=[relaxed_leaderboard_table, strict_leaderboard_table]
+    )

ui/styles.css

@@ -0,0 +1,136 @@
+/* 항상 세로 스크롤바를 표시해서 폭이 바뀌지 않게 하기 */
+html {
+    overflow-y: scroll;
+}
+
+/* ================================
+   기본 컨테이너 스타일 (전체 폭 통일)
+   ================================ */
+   .gradio-container,
+   .main {
+   max-width: 1400px !important;   /* 화면 너무 넓어지지 않게 적당히 넓은 고정폭 */
+   width: 100% !important;
+   margin: 0 auto !important;      /* 항상 가운데 정렬 */
+   }
+   
+   .fixed-list * {
+       font-size: 15px !important;
+   }
+   
+   
+   /* ================================
+   데이터프레임 기본 스타일
+   ================================ */
+   .dataframe {
+   font-size: 16px !important;
+   width: 100% !important;
+   }
+   
+   .dataframe table {
+   font-size: 16px !important;
+   width: 100% !important;
+   table-layout: auto !important;
+   }
+   
+   .dataframe th {
+   font-size: 18px !important;
+   font-weight: bold !important;
+   padding: 12px !important;
+   white-space: nowrap !important;
+   }
+   
+   .dataframe td {
+   font-size: 16px !important;
+   padding: 10px !important;
+   white-space: nowrap !important;
+   }
+   
+   
+   /* ================================
+      리더보드 검색 바 스타일
+   ================================ */
+   .search-input input {
+       font-size: 16px !important;
+       padding: 12px 16px !important;
+       border-radius: 8px !important;
+       border: 2px solid #e0e0e0 !important;
+       transition: border-color 0.3s ease !important;
+   
+       /* 🔹 input 높이 고정 */
+       height: 40px !important;
+       box-sizing: border-box !important;
+   }
+   
+   .search-input input:focus {
+       border-color: #4a90e2 !important;
+       outline: none !important;
+       box-shadow: 0 0 0 3px rgba(74, 144, 226, 0.1) !important;
+   }
+   
+   /* 검색 영역 wrapper */
+   .search-input {
+       margin: 8px 0 12px 0 !important;
+       display: block;
+   }
+   
+   .search-input input {
+       margin: 0 !important;
+   }
+   
+   /* ================================
+      버튼 스타일 (기본 스타일 유지)
+   ================================ */
+   .clear-search-btn,
+   .refresh-btn {
+       border-radius: 8px !important;
+       font-weight: 500 !important;
+   
+       /* 🔹 검색바와 동일한 세로 높이로 맞춤 */
+       height: 40px !important;
+       padding: 0 16px !important;
+   
+       /* 기존 스타일 최대한 유지 */
+       margin-top: 4px !important;
+   }
+   
+   
+   
+   /* ================================
+   리더보드 그룹/테이블 여백 및 카드 스타일
+   ================================ */
+   .leaderboard-group {
+       margin: 18px 0 28px 0 !important;
+       padding: 12px 14px !important;
+       border: 1px solid #eee;
+       border-radius: 12px;
+       background: #ffffff;
+   }
+   
+   .leaderboard-table {
+       margin-top: 8px !important;
+   }
+   
+   /* 표 셀 여백 보강 (리더보드 전용) */
+   .leaderboard-table .dataframe th {
+       padding: 12px 14px !important;
+   }
+   .leaderboard-table .dataframe td {
+       padding: 10px 14px !important;
+   }
+   
+   /* ================================
+   제출 상태(Textbox) 스크롤 및 줄바꿈 강제
+   ================================ */
+   .submission-status textarea {
+       max-height: 420px !important;
+       overflow-y: auto !important;
+       white-space: pre-wrap !important;   /* 개행 유지 */
+       word-break: break-word !important;  /* 긴 단어/표 폭주 방지 */
+       text-align: left !important;        /* 좌측 정렬 강제 */
+   }
+   
+   /* 중첩 스크롤 방지: 래퍼는 스크롤 해제 */
+   .submission-status, .submission-status .wrap {
+       max-height: none !important;
+       overflow: visible !important;
+   }

ui/submission_tab.py

@@ -0,0 +1,98 @@
+"""
+제출 및 평가 탭 UI 컴포넌트
+
+📤 제출 및 평가 탭의 UI와 로직을 관리합니다.
+"""
+
+import gradio as gr
+from src.submission_handler import process_submission
+
+
+def create_submission_tab():
+    """제출 및 평가 탭 UI 생성"""
+
+    gr.Markdown("""
+        ### 📋 제출 방법
+        - 데이터셋 탭을 통하여 test set 다운로드  
+        - 각 question에 대한 model_response 생성  
+        - model_response가 채워진 CSV 파일 업로드(UTF-8 인코딩)  
+        - 제출자 이름(id), 사용 모델, 설명 작성하여 제출  
+            - 설명: 따로 적용한 방법론이 있으면 작성해 주세요. 공란일 경우 사용 모델의 베이스 성능으로 간주합니다.  
+            - 사용 모델: response를 생성하기 위한 모델은 자유롭게 선택할 수 있습니다. 사용한 모델의 **공식 명칭**을 작성해 주세요.  
+
+        <br>
+
+        ### 🔍 평가 방식
+        - 평가는 upstage의 최신 **solar 모델**로 진행됩니다. *(2025-11-11 기준: solar-pro2-250909)*  
+        - 평가 결과는 전체 accuracy뿐 아니라 fact type, 전제 유효성, number of hop, 도메인별 분류 점수도 제공합니다.  
+        - 한 번의 제출로 **relaxed evaluation**과 **strict evaluation**이 동시에 진행됩니다.  
+
+        ##### 🔹 relaxed evaluation
+            - 답변이 가진 주요 정보의 정확성에만 초점을 맞춰 평가합니다.  
+            - 환각이나 오래된 정보가 포함되어 있어도, 주요 정보에 영향을 미치지 않으면 정답으로 인정될 수 있습니다.  
+            - 답변 형식이 잘못된 경우(예: 다른 언어로 답변)도 허용됩니다.  
+
+        ##### 🔹 strict evaluation
+            - 주요 정보의 정확성뿐 아니라, 모든 사실이 정확하고 최신이어야 합니다.  
+            - 사소한 환각이라도 포함되면 정답으로 인정되지 않습니다.  
+            - “제 지식은 2021년 9월까지입니다…” 같은 오래된 정보 경고 문구는 그 내용이 변경되지 않았음이 명확한 경우에만 정답으로 인정됩니다.  
+
+        <br>
+
+        ### 🚫 제출 제한
+        - 사용자당 **하루 최대 3회 제출** 가능합니다.  
+        - 실패한 제출은 카운트되지 않습니다.  
+        - 제출 횟수는 **매일 한국 시간 00시 00분**에 초기화됩니다.  
+
+        <br>
+
+        ### ⏱️ 평가 소요 시간
+        - 평가 소요 시간은 **제출당 약 30분**으로 예상됩니다.  
+        - 동시에 제출한 참가자가 많을 경우 시간이 증가할 수 있습니다.  
+
+        <br>
+    """)
+
+
+
+    submission_file = gr.File(
+        label="정답이 포함된 CSV 파일 업로드",
+        file_types=['.csv']
+    )
+    submitter_name = gr.Textbox(
+        label="제출자 이름",
+        placeholder="예: AI Ambassador",
+        value="Anonymous"
+    )
+    submit_model = gr.Textbox(
+        label="사용한 모델",
+        placeholder="사용한 모델의 공식 명칭을 작성해 주세요.",
+        value="Anonymous Model"
+    )
+    submit_description = gr.Textbox(
+        label="설명",
+        placeholder="따로 적용한 방법론이 있으면 작성해 주세요."
+    )
+
+    # 제출 및 취소 버튼
+    submit_btn = gr.Button(
+        "🚀 제출 및 평가 시작",
+        variant="primary"
+    )
+
+    # 제출 상태 및 결과 텍스트
+    submission_status = gr.Textbox(
+        label="제출 상태",
+        value="CSV 파일을 업로드하고 제출하세요.",
+        interactive=False,
+        lines=20,
+        elem_classes=["submission-status"]
+    )
+
+    # 제출 버튼 이벤트 연결
+    submit_btn.click(
+        fn=process_submission,
+        inputs=[submission_file, submitter_name, submit_model, submit_description],
+        outputs=[submission_status],
+        concurrency_limit=3
+    )