docs: add detailed README.md with project documentation

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-24 04:47:09 +09:00
parent 76bb6da116
commit 5594a90de5
1 changed files with 147 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,147 @@
+# 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