stock-llm-analyzer/README.md

stock-llm-analyzer

한국 주식 분석 플랫폼의 LLM 기반 AI 분석 서비스. Anthropic Claude를 활용하여 종목별 정성 분석(투자 요약, 밸류에이션 평가, 리스크, 추천)을 생성합니다.

기능

• AI 투자 분석: Claude Sonnet 모델을 활용한 종목 정성 분석
• 투자 추천: STRONG_BUY / BUY / HOLD / SELL / STRONG_SELL 5단계
• 신뢰도 점수: 분석 결과에 대한 모델의 자체 신뢰도 (0.0~1.0)
• 구조화된 출력: 요약, 밸류에이션 코멘트, 리스크 팩터, 카탈리스트 목록
• 분석 이력 조회: MongoDB에서 종목별 과거 분석 결과 조회
• 비동기 워커: Redis Streams 기반 파이프라인 연동

API 엔드포인트

메서드	경로	설명
GET	/health	서비스 상태
GET	/streams	Redis Stream 큐 길이
POST	/analyze	LLM 분석 트리거
GET	/results/{stock_code}	종목별 분석 결과 조회

요청 예시

# 분석 트리거
curl -X POST http://localhost:8006/analyze \
  -H "Content-Type: application/json" \
  -d '{
    "stock_code": "005930",
    "run_id": "abc-123",
    "catalyst_score": 60,
    "composite_score": 85.3,
    "detected_catalysts": [{"category": "earnings_surprise", "keyword": "영업이익 증가"}],
    "is_value_trap": false
  }'

# 결과 조회
curl http://localhost:8006/results/005930?limit=5

응답 예시

// GET /results/{stock_code}
{
  "stock_code": "005930",
  "analyses": [
    {
      "_id": "...",
      "stock_code": "005930",
      "analysis_id": "a1b2c3d4-...",
      "summary": "삼성전자는 반도체 사이클 회복과 AI 수요 증가로...",
      "valuation_comment": "현재 PER 12.5배로 5년 평균 대비 저평가...",
      "risk_factors": ["중국 반도체 경쟁 심화", "환율 변동 리스크"],
      "catalysts": ["HBM 수주 증가", "파운드리 가동률 회복"],
      "recommendation": "BUY",
      "confidence": 0.78,
      "analyzed_at": "2024-12-20T15:30:00",
      "model_name": "claude-sonnet-4-20250514"
    }
  ]
}

LLM 분석 프로세스

1. 입력 데이터 수신 (스크리닝 점수, 카탈리스트, 밸류 트랩 여부)
        │
        ▼
2. 프롬프트 구성 (종목 코드, 점수, 카탈리스트 목록)
        │
        ▼
3. Claude API 호출 (claude-sonnet-4-20250514)
        │
        ▼
4. JSON 응답 파싱 → LLMAnalysis 모델
   {summary, valuation_comment, risk_factors,
    catalysts, recommendation, confidence}
        │
        ▼
5. MongoDB에 저장 + queue:results로 발행

데이터 파이프라인

queue:catalysts (카탈리스트 탐지 결과)
     │
     ▼
  Worker (LLMAnalyzer)
     │
     ├── Claude API 호출
     ├── 응답 파싱 → LLMAnalysis
     │
     ▼
queue:results  (최종 분석 결과)

이 서비스는 파이프라인의 마지막 단계로, 스크리닝 → 카탈리스트 → LLM 분석 순서로 실행됩니다.

프로젝트 구조

stock-llm-analyzer/
├── pyproject.toml
├── Dockerfile
├── .dockerignore
└── src/stock_llm_analyzer/
    ├── __init__.py
    ├── api.py          # FastAPI 엔드포인트
    ├── analyzer.py     # LLMAnalyzer (Claude API 호출, 프롬프트, 파싱)
    └── worker.py       # Redis Stream 소비자 + API 서버 실행

환경변수

변수	설명	기본값
ANTHROPIC_API_KEY	Anthropic API 키	(필수)
REDIS_URL	Redis 연결 URL	redis://localhost:6379/0
MONGODB_URI	MongoDB 연결 URI	mongodb://localhost:27017
MONGODB_DB	MongoDB 데이터베이스명	stock_analysis

모델 정보

항목	값
모델	claude-sonnet-4-20250514
Max Tokens	2,000
Rate Limit	5 req/s (설정 가능)
출력 형식	JSON (summary, recommendation, confidence 등)

로컬 실행

pip install -e ../stock-common && pip install -e .
export ANTHROPIC_API_KEY=your_key_here
python -m stock_llm_analyzer.worker

의존성

• stock-common - 공유 라이브러리
• anthropic - Anthropic Claude API 클라이언트
• Python >= 3.12