# 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}` | 종목별 분석 결과 조회 |

### 요청 예시

```bash
# 분석 트리거
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
```

### 응답 예시

```json
// 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 등) |

## 로컬 실행

```bash
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