## 1. 프로젝트의 최종 목표

제가 제안드리는 최종 목표는 아래 한 문장으로 정리됩니다.

**“공식 문서와 무료 attention 데이터를 이용해, 1~5일짜리 중단기 continuation 종목을 자동으로 선별하고, 다음 세션에 기계적으로 진입·청산하는 AI 이벤트 트레이딩 시스템”**

여기서 중요한 점은 세 가지입니다.

첫째, **AI/LLM은 예언자가 아니라 문서 해석기**로 씁니다.
둘째, **가격 반응이 반드시 1차 검증**입니다.
셋째, **소셜/유튜브/뉴스는 가산점 레이어**이지, 단독 진입 신호가 아닙니다.

즉, 구조는 이렇게 갑니다.

**공식 이벤트 레이어**
→ **가격/거래량 확인 레이어**
→ **attention/crowding 레이어**
→ **포트폴리오/리스크 엔진**
→ **실행 엔진**

---

## 2. 어떤 데이터 소스를 어떤 역할로 쓸지

### 핵심 소스

**SEC EDGAR / data.sec.gov**
이 프로젝트의 메인 소스입니다. 회사별 제출 이력과 XBRL 데이터를 무료 JSON API로 제공하고, 8-K, 10-Q, 10-K, 20-F, 40-F, 6-K 등을 포함하며, 제출 정보는 하루 종일 실시간으로 갱신됩니다. 이 소스는 이벤트의 “원문” 역할을 합니다. ([SEC][1])

**Alpaca 무료 플랜**
시세/주문/백테스트용 시장데이터의 기본 축입니다. 공식 문서상 Trading API Basic은 무료이며, 실시간 주식 데이터는 IEX 중심, 주식 히스토리의 최신 15분 제한, 200 API calls/min, 웹소켓 30심볼 제한이 있습니다. 따라서 v1은 일봉/분봉 보조 + 다음 시초가 실행 구조로 맞추는 것이 좋습니다. ([Alpaca API Docs][2])

**FRED API**
시장 레짐 필터용입니다. 금리, 스프레드, 경기/유동성 지표를 무료로 API로 받을 수 있으므로, 전략의 “리스크 온/오프” 판정에 쓰기 좋습니다. ([FRED][3])

### 2차 보조 소스

**FINRA Daily Short Sale Volume**
이건 crowding/포지셔닝 레이어입니다. FINRA는 정상 거래시간에 보고된 short sale trades의 일별 집계 파일을 제공하고, 같은 날 오후 6시 ET까지 게시합니다. 다만 이것은 **short interest가 아니라 당일 short sale volume 집계**이므로, 진짜 공매도 잔고가 아니라 “당일 숏 압력/오프익스체인지 흐름”으로 해석하셔야 합니다. ([FINRA][4])

**Wikimedia Pageviews**
리테일 관심 폭증을 잡는 데 좋습니다. Wikimedia Analytics API의 pageview 데이터는 2015년 7월 1일 이후를 제공하고, 봇/자동화 트래픽을 구분합니다. 즉, 개별 종목이나 테마에 대한 대중 관심의 급증을 무료로 관찰할 수 있습니다. ([Wikimedia Doc][5])

**YouTube Data API**
유튜브 유명 채널의 영향력을 추적하는 데 쓸 수 있습니다. 다만 전수 검색은 비효율적입니다. YouTube Data API는 기본 쿼터가 하루 10,000 units이고, `search.list`는 100 units, `commentThreads.list`는 1 unit입니다. 또한 `captions.download`는 영상을 수정할 권한이 있는 사용자에게만 허용되므로, 공개 영상 자막 전체를 핵심 입력으로 삼는 구조는 맞지 않습니다. 대신 `channels` 리소스의 `contentDetails.relatedPlaylists.uploads`를 이용해 **미리 정한 채널 whitelist**를 추적하고, 영상 제목/설명/댓글/조회수 속도 중심으로 feature를 만드는 것이 맞습니다. ([Google for Developers][6])

**Yahoo Finance RSS**
공식 RSS 피드 서비스가 있으므로, 최신 금융 헤드라인 수집용으로는 쓸 수 있습니다. 다만 저는 이것을 원문 이벤트 소스가 아니라 **가벼운 headline-burst 카운터**로만 쓰겠습니다. ([Yahoo Finance][7])

**Google Trends API Alpha**
흥미롭지만 아직 alpha 프로그램입니다. Google은 프로그램식 접근을 위한 Trends API alpha를 받고 있고, 최근 5년 데이터와 일/주/월/연 단위 집계를 설명하고 있습니다. 따라서 이건 v1 핵심 의존성이 아니라 **실험용 테마 히트맵**으로만 두는 편이 맞습니다. ([Google for Developers][8])

---

## 3. 전체 시스템 아키텍처

제가 권하는 구조는 **작고 단단한 모듈형**입니다. 처음부터 거대한 마이크로서비스나 쿠버네티스를 올리지 마시고, **단일 리포지토리 + Docker Compose + Python 서비스 몇 개**로 시작하시는 것이 좋습니다.

흐름은 아래처럼 잡겠습니다.

```text
[SEC / Alpaca / FRED / FINRA / Wikimedia / YouTube / Yahoo]
        ↓
   Source Adapters
        ↓
 Raw Storage (원문 보관)
        ↓
 Normalizer / Parser
        ↓
 Feature Store
        ↓
 Signal Ranker
        ↓
 Portfolio & Risk Engine
        ↓
 Execution Engine
        ↓
 Post-trade Review / Dashboard
```

### 저장 구조

저는 저장 계층을 두 개로 나누겠습니다.

**1) Raw Zone**
원문 보관용입니다.
SEC filing HTML/TXT/XML, 99.1 문서, 유튜브 메타데이터, Yahoo RSS headline, FINRA txt 파일 등은 날짜별 폴더에 그대로 저장합니다.

**2) Structured Zone**
정규화된 테이블입니다.
여기에는 `events`, `documents`, `xbrl_facts`, `market_bars`, `attention_metrics`, `candidate_scores`, `orders`, `fills`, `positions`, `reviews` 같은 테이블이 들어갑니다.

연구용 쿼리는 **DuckDB + Parquet**, 운영 상태는 **PostgreSQL**로 나누는 구성이 제일 실용적입니다.
이유는 단순합니다. 문서와 시계열은 Parquet가 싸고 빠르고, 주문/포지션/상태관리는 PostgreSQL이 안정적이기 때문입니다.

### 권장 기술 스택

* 언어: Python
* API/관리용: FastAPI
* 운영 DB: PostgreSQL
* 연구/백테스트: DuckDB + Parquet
* 스케줄링: cron 또는 APScheduler
* 컨테이너: Docker Compose
* 비동기 큐: 초기에는 생략, 나중에 Redis 추가
* LLM 계층: JSON schema 강제 + 캐시 필수
* 시각화/리포트: Streamlit 또는 간단한 내부 대시보드

초기에는 **복잡한 프론트엔드보다 로그와 리포트가 더 중요**합니다.

---

## 4. 폴더/프로젝트 구조 권장안

이 정도 구조로 시작하시면 깔끔합니다.

```text
repo/
  apps/
    collector/
    parser/
    feature_builder/
    ranker/
    backtester/
    live_trader/
    dashboard/
  libs/
    adapters/
      sec/
      alpaca/
      finra/
      fred/
      wikimedia/
      youtube/
      yahoo/
    common/
    schemas/
    risk/
    portfolio/
    execution/
    llm/
  configs/
    sources/
    strategies/
    prompts/
  data/
    raw/
    staging/
    parquet/
  notebooks/
  tests/
    unit/
    integration/
    replay/
  docs/
    strategy_spec.md
    data_contracts.md
    runbook.md
```

---

## 5. 핵심 전략 엔진 구조

전략 엔진은 한 덩어리가 아니라 아래 4개 하위 엔진으로 분리하겠습니다.

### A. Event Engine

공식 문서를 읽고 이벤트 후보를 생성합니다.

예:

* 8-K Item 2.02 실적
* 8-K Item 7.01 Reg FD
* 8-K Item 1.01 중요 계약
* 8-K Item 8.01 기타 중요 이벤트
* 10-Q / 10-K 수치 변화
* 6-K / 20-F 해외 발행사 이벤트

### B. Document Understanding Engine

규칙 + LLM으로 문서의 질을 해석합니다.

출력 예:

* event_type
* direction
* guidance_direction
* demand_strength
* pricing_power
* backlog_mentions
* margin_quality
* oneoff_flags
* customer_expansion
* confidence

### C. Market Confirmation Engine

시장이 실제로 그 이벤트를 사는지 확인합니다.

예:

* reaction day return
* close location
* volume ratio
* gap size
* sector relative strength
* market regime

### D. Attention Overlay Engine

리테일 관심과 crowding을 가산점으로 반영합니다.

예:

* YouTube mention burst
* Wikipedia pageview shock
* Yahoo headline burst
* FINRA short volume anomaly
* Google Trends theme heat

중요한 점은 **D 엔진이 단독 진입 신호가 되어서는 안 된다**는 것입니다.

---

## 6. phase별 개발계획

이제 실제 개발 순서를 phase 단위로 나누겠습니다.

---

### Phase 0 — 전략/운용 명세 동결

**목표**
프로젝트의 범위와 규칙을 먼저 고정합니다. 이 단계가 흔들리면 뒤가 전부 흔들립니다.

**주요 작업**

* 거래 대상 고정: 미국 보통주만, ADR/ETF/SPAC 제외
* 보유기간 고정: 기본 1~5일
* 실행 구조 고정: same-day 필수 없는 next-open 중심
* 계좌 정책 고정: v1은 daytrade 의존 구조 금지
* 데이터 정책 고정: 유료 데이터 금지, 무료 소스 목록 확정
* 소셜 데이터 정책 고정: 단독 진입 금지, reranking only
* 전략 KPI 고정: 기대값, 최대 낙폭, 회전율, 거래 빈도, 포지션 집중도

**산출물**

* `strategy_spec.md`
* `risk_policy.md`
* `data_source_policy.md`
* `event_taxonomy.md`

**완료 조건**

* “무슨 종목을 언제 어떤 이유로 사는지”를 문서 한 장으로 설명 가능해야 합니다.
* 어떤 데이터가 core인지, optional인지, experimental인지 분류가 끝나 있어야 합니다.

---

### Phase 1 — 개발 기반과 데이터 계약 만들기

**목표**
앞으로 바꾸기 어려운 기반을 먼저 세웁니다.

**주요 작업**

* 모노레포 생성
* Docker Compose 환경 구성
* PostgreSQL / DuckDB 초기화
* 공통 설정 파일, secrets 구조, 로깅 규칙 정의
* ET 기준 시각/거래일 캘린더 유틸 작성
* 심볼 마스터 테이블 설계
* raw 파일 저장 경로 규칙 정의
* 문서/이벤트/시세/주문용 스키마 설계

**산출물**

* `docker-compose.yml`
* DB 스키마 v1
* 공통 config loader
* 로그/에러 포맷 규칙
* `source_status` / `job_runs` 테이블

**완료 조건**

* 로컬에서 한 명이 완전 재현 가능한 개발환경이 떠야 합니다.
* 임의의 source adapter 하나를 실행해 raw와 structured에 동시에 적재할 수 있어야 합니다.

---

### Phase 2 — 핵심 무료 데이터 ingestion 구축

**목표**
먼저 **핵심 데이터만 안정적으로 모으는 것**입니다. 이 단계에서는 fancy model보다 ingestion 안정성이 더 중요합니다.

**주요 작업**

1. **SEC adapter**

   * submissions JSON 수집
   * accession별 filing 다운로드
   * 8-K / 10-Q / 10-K / 6-K / 20-F / 40-F 인덱싱
   * Exhibit 99.1 추출
   * XBRL facts 파싱
   * SEC fair access 반영: request throttle 적용

2. **Alpaca market adapter**

   * 일봉/분봉 bars 수집
   * 거래대금/갭/ATR용 가격 데이터 적재
   * 무료 플랜 제약을 고려한 폴링 빈도 설계

3. **FRED adapter**

   * 레짐용 시계열 수집

4. **FINRA adapter**

   * 일별 short sale volume 파일 수집
   * 종목별 short ratio 계산

이 단계의 핵심 근거는 명확합니다. SEC는 인증 없이 submissions/XBRL JSON을 제공하고 실시간 갱신되며, SEC는 초당 10회 이하 접근을 권고합니다. Alpaca Basic은 무료지만 IEX 실시간, 최신 15분 히스토리 제한, 200 requests/min, 웹소켓 30심볼 제한이 있어, ingestion 설계도 그 제약에 맞춰야 합니다. FINRA short sale volume은 같은 날 오후 6시 ET까지 게시되므로 post-close feature로 쓰는 것이 맞고, FRED는 무료 API로 거시 데이터를 제공합니다. ([SEC][1])

**산출물**

* `sec_collector`
* `alpaca_collector`
* `fred_collector`
* `finra_collector`
* 원문 raw archive
* 정규화 테이블 v1

**완료 조건**

* 최근 충분한 기간의 연속 데이터가 누락 없이 적재되어야 합니다.
* 재실행해도 중복 적재가 없어야 합니다.
* 실패한 job의 재시도가 자동으로 가능해야 합니다.

---

### Phase 3 — 문서 파서와 feature builder 구축

**목표**
이 단계에서 AI/LLM이 처음 들어갑니다. 하지만 LLM을 먼저 두지 않고, **규칙 기반 파서 → LLM 보강** 순서로 갑니다.

**주요 작업**

1. **규칙 기반 파서**

   * item number 추출
   * guidance 키워드 추출
   * one-off/비GAAP/세금/valuation gain 같은 패턴 탐지
   * 수요/백로그/고객 증가/가격결정력 언급 탐지

2. **LLM 파서**

   * JSON schema 강제
   * confidence 포함
   * 문서 해시 캐시
   * 프롬프트 버전 관리
   * 낮은 confidence만 재시도

3. **수치 feature**

   * XBRL 기반 revenue, margin, cashflow, debt 변화
   * 과거 회사 가이던스 대비 이번 actual 비교
   * 전분기/전년동기 변화율

4. **시장 feature**

   * reaction-day return
   * volume ratio
   * close location
   * gap size
   * sector strength
   * ATR / volatility context

5. **label 생성**

   * 1D / 3D / 5D forward return
   * MFE / MAE
   * stop hit 여부
   * time-to-target

**산출물**

* `parsed_documents`
* `event_features`
* `market_features`
* `training_labels`
* manual review notebook

**완료 조건**

* 수동 검수 샘플에서 event type / guidance direction / one-off flag의 정확도가 충분히 나와야 합니다.
* LLM 없이도 기본 파이프라인이 돌아가고, LLM은 성능 향상용이어야 합니다.

---

### Phase 4 — 베이스라인 전략과 백테스터 만들기

**목표**
이 단계에서 처음으로 “돈 되는지”를 봅니다. 백테스터를 예쁘게 만드는 것이 아니라, **live와 괴리가 적은 시뮬레이터**를 만드는 것이 핵심입니다.

**주요 작업**

* 이벤트를 거래일에 정확히 귀속
* reaction day 정의
* 다음 시초가 진입 로직
* 종가 기준/다음날 기준 청산 로직
* 슬리피지/수수료 보수적 반영
* 상장폐지/거래중지 처리
* 포트폴리오 제약

  * 최대 포지션 수
  * 섹터 집중 제한
  * 종목별 리스크
  * 일일 손실 제한
* 전략 ablation

  1. 문서만
  2. 문서 + 가격
  3. 문서 + 가격 + 레짐
  4. 문서 + 가격 + 레짐 + attention

**산출물**

* event-driven backtester
* 백테스트 리포트
* feature importance / ablation 결과
* 후보 점수식 v1

**완료 조건**

* out-of-sample에서도 성과가 살아 있어야 합니다.
* 특정 한 시즌/한 섹터/한 해에만 먹히는 전략이면 통과시키지 않습니다.
* parser 오류와 execution 가정이 결과를 왜곡하지 않았는지 설명 가능해야 합니다.

---

### Phase 5 — attention layer 확장

**목표**
핵심 전략이 먼저 살아 있는지 확인한 뒤, 그 위에 attention/crowding 레이어를 얹습니다.

**주요 작업**

1. **YouTube adapter**

   * 투자 관련 유명 채널 whitelist 구축
   * 채널별 uploads playlist 추적
   * 영상 제목/설명/게시시각/조회수/댓글 수집
   * 댓글 감성/티커 인식
   * 영상 영향력 점수 산출

2. **Wikimedia adapter**

   * 종목/회사 페이지 매핑
   * 1일/3일/7일 pageview shock 계산

3. **Yahoo RSS adapter**

   * 헤드라인 수집
   * 중복 제거
   * publisher breadth / headline burst 계산

4. **FINRA crowding features**

   * short volume ratio
   * abnormal shorting
   * event day crowding 패턴

5. **Google Trends experimental**

   * 테마성 키워드에만 제한 적용
   * 핵심 신호가 아니라 보유기간 조정용으로만 사용

이 순서가 중요한 이유가 있습니다. YouTube는 기본 쿼터가 하루 10,000 units이고 `search.list`는 100 units, `commentThreads.list`는 1 unit이므로 전수 검색보다 채널 whitelist 방식이 훨씬 효율적입니다. 또한 caption download는 영상 편집 권한이 있어야 하므로 핵심 입력으로 적합하지 않습니다. Wikimedia pageviews는 2015년부터 제공되고 자동화 트래픽을 구분하므로 무료 retail attention 지표로 유용합니다. Yahoo Finance는 RSS 피드 서비스를 제공하므로 headline burst 용도로는 쓸 만하고, Google Trends API는 아직 alpha 단계이므로 optional로만 두는 편이 맞습니다. FINRA short sale volume은 same-day 6pm ET post-close 데이터이므로 intraday 진입이 아니라 후속 랭킹/검증용입니다. ([Google for Developers][6])

**산출물**

* `attention_features`
* `youtube_channel_registry`
* `wiki_entity_map`
* `headline_burst_scores`
* attention overlay 리포트

**완료 조건**

* attention feature를 넣었을 때 성과가 조금이라도 안정적으로 개선되어야 합니다.
* attention feature가 없더라도 core 전략은 독립적으로 돌아가야 합니다.

---

### Phase 6 — paper trading 시스템 구축

**목표**
실전 투입 전, 운영 파이프라인이 문제없이 돌아가는지 확인합니다.

**주요 작업**

* daily job scheduler
* 후보 생성 → 주문 계획 → 제출 → 체결 → 청산 상태머신 구현
* stale data 체크
* 중복 주문 방지
* 휴장일/조기폐장 처리
* paper account 연동
* 주문/체결/포지션 대사(reconciliation)
* 알림 시스템
* 거래 후 자동 복기

**주문 상태머신은 이렇게 단순하게** 잡겠습니다.

```text
candidate_created
→ price_confirmed
→ order_planned
→ order_submitted
→ accepted
→ partially_filled / filled
→ position_open
→ partial_exit
→ fully_closed
→ post_trade_review_done
```

**산출물**

* `live_trader`
* `risk_guard`
* paper trading runbook
* daily/weekly report

**완료 조건**

* 일정 기간 paper trading 동안 누락 주문, 중복 주문, 포지션 불일치가 없어야 합니다.
* 사람이 리포트만 봐도 “왜 샀고 왜 팔았는지” 이해 가능해야 합니다.

---

### Phase 7 — 소액 실전 운영

**목표**
이제부터는 성과보다 **운영 안정성**이 우선입니다.

**주요 작업**

* 포지션 크기 극소화
* human-in-the-loop 승인 모드로 시작
* 자동 진입, 수동 승인, 자동 청산 구조 가능
* 일일 max loss, max exposure, max sector exposure 적용
* 장애 시 kill switch
* 신호 drift 감시
* parser drift 감시
* LLM 응답 실패 fallback

**산출물**

* live trading runbook
* 장애 대응 시나리오
* kill switch 문서
* 실전 성과 attribution 리포트

**완료 조건**

* 운영 실수가 전략 손실보다 작아야 합니다.
* 데이터 지연/파싱 실패/주문 실패 시 안전하게 no-trade로 떨어져야 합니다.

---

### Phase 8 — 확장

**목표**
핵심 엔진이 안정화된 뒤에만 확장합니다.

**확장 후보**

* 숏 전용 negative catalyst 엔진
* 현금계좌 전용 satellite intraday 엔진
* local LLM 1차 파서
* 섹터/테마 그래프 모델
* 포지션 보유기간 동적 조절
* 다중 전략 앙상블
* 브로커 abstraction

**주의**
이 phase는 앞 단계를 통과한 뒤에만 여는 것이 좋습니다.
v1이 불안정한 상태에서 기능을 늘리면 문제 원인을 못 찾게 됩니다.

---

## 7. 개발 순서상 “일부러 나중에” 미루실 것

초기엔 아래를 일부러 하지 않는 편이 좋습니다.

* 초단타 ORB 실전 자동매매
* 옵션/0DTE
* 숏 자동매매
* Reddit/X 전수 감성분석
* RAG + 벡터DB + 거대한 문서검색 시스템
* 다중 브로커 동시 지원
* 화려한 웹 대시보드
* 딥러닝 end-to-end 가격예측

이유는 단순합니다.
지금 프로젝트의 병목은 “모델의 복잡도”가 아니라 **이벤트 정렬, 데이터 품질, 운영 안정성**입니다.

---

## 8. 제가 생각하는 현실적인 우선순위

실제로는 다음 순서가 가장 좋습니다.

**1순위**
SEC + Alpaca + 기본 백테스터
→ 이게 프로젝트의 본체입니다.

**2순위**
LLM 문서 파서 + guidance/one-off 해석
→ AI를 넣을 타이밍입니다.

**3순위**
FRED + FINRA + Wikimedia
→ 품질 좋은 보조 feature입니다.

**4순위**
YouTube whitelist
→ attention overlay로는 가치가 높습니다.

**5순위**
Yahoo RSS / Google Trends
→ 선택적 보강입니다.

---

## 9. 이 계획의 핵심 철학

한 줄로 정리하면 이렇습니다.

**“무료 데이터만 쓸 때는, 가장 값싼 데이터가 아니라 가장 재현성이 높은 데이터를 중심에 둬야 합니다.”**

그래서 중심은 SEC이고,
가격 확인은 Alpaca이며,
보조는 FINRA/Wikimedia/FRED이고,
유튜브/야후/트렌드는 attention overlay입니다.

이 구조로 가면

* 데이터 비용을 거의 0에 가깝게 유지할 수 있고,
* AI/LLM을 실제로 의미 있는 위치에 넣을 수 있고,
* 전략과 운영을 동시에 통제할 수 있습니다.