stock-catalyst/README.md

stock-catalyst

한국 주식 분석 플랫폼의 카탈리스트 탐지 서비스. 스크리닝된 종목의 공시와 뉴스를 분석하여 긍정적 촉매(카탈리스트)와 밸류 트랩 신호를 식별합니다.

기능

• 카탈리스트 탐지: 키워드 패턴 매칭으로 공시에서 긍정적 이벤트 식별
• 밸류 트랩 경고: 저평가처럼 보이지만 위험한 종목 신호 감지
• 공시 데이터 조회: MongoDB에서 종목별 공시 이력 조회
• 카테고리 분류: 실적호전, 대규모계약, 주주환원, M&A, 규제긍정
• 비동기 워커: Redis Streams 기반 파이프라인 연동

카탈리스트 카테고리

카테고리	키워드 예시
실적 서프라이즈	어닝서프라이즈, 실적 호조, 영업이익 증가, 흑자전환, 사상최대
대규모 계약	대규모 계약, 수주, 공급계약, 납품계약, 신규 수주
주주 환원	배당, 자사주, 자기주식, 주주환원, 배당금 증가
M&A	인수, 합병, M&A, 지분 취득, 경영권
규제 긍정	규제 완화, 인허가, 승인, 보조금, 세제 혜택

밸류 트랩 경고 키워드

매출 감소, 영업손실, 적자 전환, 적자 지속, 구조조정, 감자, 상장폐지, 관리종목, 자본잠식

API 엔드포인트

메서드	경로	설명
GET	/health	서비스 상태
GET	/streams	Redis Stream 큐 길이
POST	/detect	카탈리스트 탐지 트리거
GET	/results/{stock_code}	종목별 공시/카탈리스트 조회

요청 예시

# 카탈리스트 탐지 트리거
curl -X POST http://localhost:8005/detect \
  -H "Content-Type: application/json" \
  -d '{"stock_code": "005930", "run_id": "abc-123", "composite_score": 85.3}'

# 결과 조회
curl http://localhost:8005/results/005930?limit=10

응답 예시

// GET /results/{stock_code}
{
  "stock_code": "005930",
  "disclosures": [
    {
      "_id": "...",
      "stock_code": "005930",
      "title": "삼성전자 사업보고서",
      "dart_id": "20241220000001",
      "disclosed_at": "2024-12-20T00:00:00"
    }
  ]
}

// 탐지 결과 (내부)
{
  "catalyst_score": 60,
  "detected_catalysts": [
    {"category": "earnings_surprise", "keyword": "영업이익 증가", "title": "..."}
  ],
  "value_trap_signals": [],
  "is_value_trap": false
}

점수 체계

• Catalyst Score: 0~100점. 탐지된 카탈리스트 1개당 +20점
• 밸류 트랩 감지: 경고 신호 2개 이상 → is_value_trap: true, 점수 -40점
• 뉴스 기반 탐지: 카탈리스트 1개당 +15점

데이터 파이프라인

queue:screened (스크리닝 결과)
     │
     ▼
  Worker (CatalystDetector)
     │
     ├── MongoDB에서 공시 데이터 조회
     ├── 키워드 매칭으로 카탈리스트 탐지
     │
     ▼
queue:catalysts  ──→  stock-llm-analyzer

프로젝트 구조

stock-catalyst/
├── pyproject.toml
├── Dockerfile
├── .dockerignore
└── src/stock_catalyst/
    ├── __init__.py
    ├── api.py          # FastAPI 엔드포인트
    ├── detector.py     # CatalystDetector (키워드 패턴 매칭)
    └── worker.py       # Redis Stream 소비자 + API 서버 실행

환경변수

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

로컬 실행

pip install -e ../stock-common && pip install -e .
python -m stock_catalyst.worker

의존성

• stock-common - 공유 라이브러리
• Python >= 3.12