fingu-tips-rnd-evaluation — 코드 전수 분석

TL;DR

KSEL 7-KPI 평가용 풀스택 모놀리식 PoC. FastAPI 백엔드 + React 19 SPA + nginx 정적 + Claude Agent SDK 통합. 단일 EC2 (t4g.xlarge AL2023) · alpha push → GitHub Actions → rsync → Infisical export → rolling restart → smoke (deploy_id 일치 검증). 3-tier requirements (vercel stub / EC2 real / dev) 로 250MB Vercel 제약과 ~7GB HF 모델 풀파이프라인을 같은 코드베이스에서 처리. 7개 KPI 각각의 모델 어댑터 · stub fallback · 측정 결과 ndjson · 단위/통합 테스트가 갖춰져 있어 KSEL 검토자가 시연·검증·증빙을 한 화면에서 끝낼 수 있는 구조.

1. 레포 개요

1.1 디렉터리 분포

1.2 운영 토폴로지 (한 줄)

Cloudflare (orange-cloud, WAF/CDN) → EC2 t4g.xlarge AL2023
  ├─ nginx (80/443, origin TLS) → /api/* proxy → fingu-tips-api:8001
  ├─ fingu-tips-web (nginx + SPA build, 128 MB)
  └─ fingu-tips-api (Python 3.12 + FastAPI + Uvicorn, 6 GB limit)
     └─ HF cache volume + Infisical-pulled .env

1.3 분기 / 운영 환경

• alpha — 운영 배포 단일 브랜치. push 시 GitHub Actions 자동 CD.
• main/master — 미사용. 모든 통합이 alpha 직행.
• Vercel — 초기 시연용 stub. ENABLE_REAL_PIPELINE=false 만으로 동일 코드베이스 동작.
• 현재 alpha HEAD = 운영 deploy_id (f531aa5...) 일치 확인됨.

2. 백엔드 (Python · FastAPI)

2.1 진입점 & 부트스트랩

FastAPI app

src/api.py:235 — FastAPI(title="TIPS R&D KPI Evaluation API", version="0.6.0")

Vercel 진입

api/index.py — Vercel builder 가 app 심볼 인식

로컬 실행

uvicorn src.api:app --host 0.0.0.0 --port 8000

환경 정규화

import 시점에 ENABLE_REAL_PIPELINE, ENABLE_API_PIPELINE, ENABLE_FINETUNED_PIPELINE 정규화 (src/api.py:53~72)

전역 시드

SEED=20260514 — KPI별 KPI{n}_STUB_SEED 로 분기. 모든 stub 측정 재현 가능

미들웨어

x-request-id 자동 주입 · CORS (PUBLIC_ORIGIN + localhost) · 구조화 로깅 ContextVar

2.2 7 개 KPI 구현 — 모듈 / 데이터셋 / 메트릭 / 합격선

2.3 AI 모델 어댑터 레이어 (src/ai_clients/)

공통 베이스: src/ai_clients/_base.py::BaseClient (ABC). 모듈 import는 SDK 없이도 성공, 호출 시점에만 NotImplementedError. _errors.py에 ConfigError/ProviderError/UnsupportedOperationError 정의.

2.4 Claude Agent (/api/chat, /api/agent/*)

구현체

src/agents/financial_agent.py::FinancialAgent

기본 모델

claude-opus-4-7 · max_tokens 4096 · effort "high" · max_turns 6

Prompt caching

시스템 프롬프트 + 8 도구 정의에 cache_control={"type":"ephemeral"} — 캐시 히트로 ~10× 절감

스트리밍

client.messages.stream() — text / thinking / tool_use 이벤트 SSE 전달

Fallback 체인

Claude Agent → OpenAI gpt-4o-mini → canned 응답 (api/chat.py)

등록 8 도구 (src/agents/tools.py)

1. get_portfolio_overview — 페르소나 자산/부채/지출
2. get_recent_transactions — N건 + 카테고리 합계
3. classify_intent — 8 의도 + 신뢰도 (KPI ②)
4. recommend_products — Top-K 상품 (KPI ⑦)
5. simulate_financial_plan — N년 시뮬
6. search_finance_knowledge — RAG (KPI ⑥)
7. calculate_dti_ltv — DTI/LTV
8. classify_finance_scenario — 시나리오 → 16 도구 (KPI ①)

2.5 측정 결과 & 로깅

• 결과 파일: RESULTS_DIR=/app/results · {kpi_id}_{UTC}.json · OS 권한 에러는 silent skip (read-only FS 호환)
• NDJSON 옵션: KPI_NDJSON_DUMP=1 시 /tmp/results/runs/{run_id}.ndjson · NdjsonRunSink 컨텍스트 매니저
• SSE 스트림 기록: src/api.py:1140~1149 — run_context + sink 동시 진행
• 로깅 포맷: JsonFormatter 한 줄 JSON · ContextVar 자동 전파 (request_id/run_id/kpi)
• 이벤트 분류: api.boot, api.request.done, kpi.bulk.{start,progress,done}, kpi.single.measured, kpi.suite.{start,done}, result.saved
• 핫패스 보호: per-loop 로그는 DEBUG (isEnabledFor 체크) — 운영에서 no-op

2.6 페르소나 fixture (api/personas_data.py:22~107)

12개월 자산 추이 · 카테고리별 지출 % · 자산 클래스 비중 · 부채 유형별 분해 등 모두 random.Random(seed) 로 재현 가능.

3. 프론트엔드 (React 19 SPA)

3.1 빌드 스택

프레임워크

React 19.0.0

빌드

Vite 6.0.0 · pnpm 10.20.0

언어

TypeScript 5.6.0

라우팅

react-router-dom 7.1.0

상태

React Context × 3 + TanStack Query 5.59

스타일

Tailwind CSS 4.0 (Vite plugin)

차트

recharts 3.8.1

CSV

papaparse 5.5.3

마크다운

react-markdown + remark-gfm

호스팅

nginx 정적 SPA · dev proxy /api → :8001

3.2 라우트 (4 페이지)

3.3 측정 UI 아키텍처

3.4 페르소나 컨텍스트 (3개)

3.5 SSE 구현

EventSource 미사용 — POST + ReadableStream 직접 파싱 (AbortController 호환). 이벤트 타입: text_delta · thinking_delta · tool_use_start · tool_use_done · done. frontend/src/api/agent.ts, measurement.ts 참조.

4. 인프라 · CI/CD

4.1 GitHub Actions (.github/workflows/)

4.2 배포 흐름 (deploy.sh, ~1.5 KB)

1. SSH 키 로드 (webfactory/ssh-agent)
2. rsync 동기화 — .git, node_modules, __pycache__, .env* 제외
3. 원격에서 infisical export --env=beta --path=/fingu-tips --format=dotenv → .env 생성
4. DEPLOY_ID=${{github.sha}} 를 .env 끝에 append → compose 컨테이너 주입
5. docker compose build --quiet → rolling restart (api healthcheck wait → web)
6. 외부 smoke — /api/health.deploy_id == github.sha · /healthz == "ok" · 5회 지수백오프 (2/4/6/8/10초)

4.3 컨테이너 (운영 docker-compose.yml)

api 의 --no-access-log는 uvicorn raw access log 가 query string 노출 위험이 있어 비활성 — 자체 api.request.done 구조화 로그로 대체.

4.4 nginx 리버스 프록시 (nginx.conf)

• HTTP/2 활성 · 자체 서명 + Cloudflare Origin Certificate (/etc/nginx/certs/origin.{crt,key}) TLS 1.2/1.3
• access log masked — $request 대신 $request_method $uri $server_protocol (token 류 query 유출 차단)
• /api/ → http://fingu_api:8001 · X-Real-IP/X-Forwarded-* 전달 · keepalive 32 · read/send timeout 90 s
• 정적 자산 — Cache-Control: public, max-age=604800, immutable
• /healthz — access log off · 항상 200 ok
• try_files $uri $uri/ /index.html — SPA fallback

4.5 EC2 부트스트랩 (deploy/setup-ec2.sh)

1. Docker + docker-compose 설치
2. git clone -b alpha https://github.com/FINGU-GRINDA/fingu-tips-rnd-evaluation.git
3. .env 생성 (OPENAI_API_KEY · HF_TOKEN · DOMAIN 입력)
4. docker compose -f deploy/docker-compose.yml up -d --build

4.6 Requirements 3-tier

4.7 scripts/ 14 파일 분포

4.8 보안

• 시크릿 분리 — GH Actions secrets (SSH 키 · Infisical 토큰) + Infisical (런타임 시크릿) 이중화
• .env rsync 제외 + .gitignore
• nginx access log 마스킹 · uvicorn raw log 비활성
• TLS 1.2/1.3 · HIGH 암호화 · Cloudflare 전단 (WAF · DDoS)
• 메모리 격리 — api 6 GB OOM 시 컨테이너만 종료 · web 128 MB
• CORS 명시 origin/methods/headers

5. 테스트 · 증빙 · 데이터셋

5.1 pytest 구성

파일

31 개 · 3,289 LOC

conftest

autouse fixture _clear_ai_secrets — 실수 API 호출 방지 위해 모든 테스트에서 SECRET_ENV_KEYS 제거

contract test

test_kpi_contract.py — 7개 KPI parametrize · load_test_set/call_model/evaluate/main 존재 + MIN_SAMPLES KSEL 기준 일치 검증

메트릭 단위

test_f1_score.py · test_bleu.py · test_nq_em.py · test_llm_rec_score.py · test_throughput.py

KPI 세부

test_kpi5_breakdown.py (per_user_category) · test_kpi7_breakdown.py (per_product_category)

CI

pytest tests/ -q --timeout=30 · 빠른 반복 위해 30 s 타임아웃

5.2 데이터셋 분포 (JSONL · CSV 쌍)

각 KPI별 _source.md 메타 문서로 출처 · 생성 스크립트 · 라이선스 · 라벨 분포 · 재현 명령 기록. CSV는 KSEL 검토 친화 형태 (헤더 포함).

5.3 evidence/ 5 파일

5.4 측정 결과 스키마 (src/kpi/_common.py::save_result)

{
  "kpi": "kpi1_finance_qa",
  "metric": "f1",
  "score": 71.07,
  "target": 71.07,
  "verdict": "pass|conditional|fail",
  "details": { ... },
  "timestamp": "2026-05-19T15:30:45Z",
  "n_samples": 1050,
  "duration_sec": 12.34
}

5.5 주의 사항

• KPI ⑤ ground_truth 라벨 부재 — LLM 기반 점수, 전략(Basic/Recommendation Driven/Engagement Guided/Rec+Engagement)별 비교만 가능
• KPI ④ 라벨 부재는 의도 — 처리량(throughput)·무결성(SHA-256)·보안만 측정
• notebooks/ 빈 디렉터리 — KSEL 화면 녹화 진행 시 생성 예정
• KPI ④ throughput 구현은 pure-Python — JMeter/Spark 대체

6. KSEL 검토 체크포인트

7. 부록

7.1 API 라우트 전체

7.2 환경변수 전체

7.3 운영 헬스체크 응답 실측 (2026-05-19 04:51 UTC)

{
  "status": "ok",
  "kpi_count": 7,
  "results_dir": "/app/results",
  "results_dir_writable": false,
  "enable_real_pipeline": "true",
  "enable_api_pipeline": "false",
  "enable_finetuned_pipeline": "true",
  "finetuned_kpi2_url_set": true,
  "finetuned_kpi3_url_set": true,
  "deploy_id": "f531aa5a2e3715c81406e8b1c4f340e74f1644b0",
  "agent_available": true,
  "agent_model": "claude-sonnet-4-5"
}