From 5594a90de596648b6458fcc6a21e00c29ccb8967 Mon Sep 17 00:00:00 2001 From: yakenator Date: Tue, 24 Feb 2026 04:47:09 +0900 Subject: [PATCH] docs: add detailed README.md with project documentation Co-Authored-By: Claude Opus 4.6 --- README.md | 147 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 147 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..60b2fa2 --- /dev/null +++ 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