Quant Narrator — 비전공자용 투자 리서치 어시스턴트

생성형 AI의 이해와 활용 (GITA404-1) · 8팀 팀 프로젝트 김문수 · 서지훈 · 조규남

숫자로만 이루어진 복잡한 퀀트(Quant) 지표를 생성형 AI를 통해 인간의 언어(내러티브)로 번역해 주는 시스템.

• 계산 → Python: 환각 제거, 결정론적 수치
• 해석 → LLM: 투자 거장 페르소나(버핏·린치·리스크)로 내러티브 생성
• 근거 → RAG: 모든 해석에 DART 공시 출처 인용

빠른 시작

1. 의존성 설치

# Python 3.11 이상 필요
python3 -m venv .venv
source .venv/bin/activate

pip install --upgrade pip
pip install -e ".[dev]"

2. API 키 발급

서비스	발급처	용도
DART	https://opendart.fss.or.kr/	한국 상장사 재무·공시 (필수)
Anthropic	https://console.anthropic.com/	LLM 페르소나 (Claude)
OpenAI	https://platform.openai.com/	대안 LLM (선택)

⚠️ Anthropic/OpenAI 콘솔에서 사용량 한도(spend limit) 를 설정해 두세요.

3. 환경 변수

cp .env.example .env
# .env 파일을 편집:
#   DART_API_KEY=...
#   ANTHROPIC_API_KEY=...
#   APP_PASSWORD=강한비밀번호  (외부 노출 시 필수)

4. 테스트

pytest                                  # 단위 테스트 (11 케이스)
.venv/bin/python scripts/integration_test.py   # 005930 end-to-end

5. 실행

로컬 개발

streamlit run src/ui/app.py
# → http://localhost:8501

외부 공개 (공인 IP, 5500 포트)

bash scripts/serve_public.sh
# → http://<공인IP>:5500 → 비밀번호 게이트

디렉토리 구조

src/
├── data/             # Yahoo Finance · DART 클라이언트, 회사 검색, 시총 후보
│   ├── yfinance_client.py    # KOSPI/KOSDAQ 자동 감지
│   ├── dart_client.py        # 사업/분기/반기보고서, account_id 정확 매칭
│   ├── preliminary.py        # 잠정실적 공시 파서 (정정본 우선)
│   ├── corp_list.py          # 3,900+ 상장사 검색
│   └── top_caps.py           # 시총 상위 후보 풀
├── engine/           # 정량 지표 계산 (GP/A, PBR, 부채비율)
├── rag/              # 청킹·인덱싱·검색
│   ├── chunker.py            # 노이즈 제거 + 단락 보존 청킹
│   ├── indexer.py            # ChromaDB 영구 저장
│   ├── retriever.py          # multi-query + 점수 dedup
│   └── ingest.py             # 사업보고서 본문 자동 인덱싱
├── agents/           # 페르소나 LLM
│   ├── personas.py           # 3거장 정의
│   ├── orchestrator.py       # 멀티 페르소나 + 잠정실적 통합
│   ├── concise.py            # 다종목 매트릭스용 짧은 형식
│   └── llm.py                # Anthropic/OpenAI 추상화
├── ui/               # Streamlit 멀티페이지
│   ├── app.py                # 단일 종목 분석
│   ├── auth.py               # 비밀번호 게이트
│   └── pages/
│       ├── 2_📊_종목_비교.py     # 2~3종목 직접 비교
│       └── 3_📈_시장_TOP10.py    # 시장 시총 상위 + 자동 매트릭스
└── eval/             # 사용자 평가 모듈
scripts/              # 통합 테스트, 회귀 테스트, 인덱싱, 평가 분석
tests/                # pytest 단위 테스트

핵심 지표

지표	정의	의미
GP/A	매출총이익 / 총자산	자산 효율성 (Novy-Marx 2013)
PBR	시가총액 / 자기자본	자산 대비 시장가치
부채비율	부채총계 / 자기자본 × 100	재무 건전성

페르소나

• 🎯 가치 투자 (워렌 버핏 스타일) — 안전마진·자산 효율성·재무 안정성
• 🚀 성장 투자 (피터 린치 스타일) — 이익 성장률·운영 레버리지·신사업
• ⚠️ 리스크 분석 (보수적 관점) — 단정적 추천 회피·우발채무 발굴

Streamlit 페이지

1. 단일 종목 분석 — 회사 검색 → 지표 카드 → 페르소나 탭 → 사용자 평가
2. 종목 비교 — 2~3개 동시 비교 (PBR×GP/A 산점도)
3. 시장 TOP10 — KOSPI/KOSDAQ 시총 상위 + 버핏·린치 자동 매트릭스

외부 데이터 소스

• Yahoo Finance (yfinance): 시세·시총·발행주식수
• DART 전자공시 (OpenDartReader): 사업·분기·반기보고서, 잠정실적 공시
• 벡터 DB (ChromaDB): 공시 본문 청크 (영구 저장)
• 임베딩 (sentence-transformers):
  • 기본: BAAI/bge-m3 (한국어 정확도 ↑, ~2GB)
  • 빠른 옵션: intfloat/multilingual-e5-small (~470MB)

보안 / 배포

• .env는 .gitignore에 포함 — 절대 커밋 금지
• 외부 노출 시 APP_PASSWORD 게이트 필수
• LLM 콘솔에서 사용량 한도 설정 권장
• 공유기 NAT 포트포워딩 필요 시 5500/tcp

자세한 내용은 PROJECT_PLAN.md 참조.

라이선스

학술 프로젝트 — 외부 공개·상업 이용 전 팀원 동의 필요.