ACE-F v1 — AI Catalyst Event Engine (Free Data)

미국 주식 이벤트 기반 중단기 자동매매 시스템. SEC 공시 + 무료 시장 데이터를 활용하여 1~5일 continuation 종목을 자동 선별하고, 다음 세션에 기계적으로 진입·청산하는 AI 이벤트 트레이딩 엔진.

---

목차

1. 프로젝트 목적
2. 핵심 철학
3. 시스템 아키텍처
4. 디렉토리 구조
5. 데이터 파이프라인
6. 전략 엔진
7. 백테스트 시스템
8. 전략 개선 시스템 (SQS / Journal / Leaderboard)
9. 현재 개발 현황
10. 현재 최고 전략 성과
11. 설치 및 실행
12. 사용법
13. 기술 스택
14. 데이터 소스

---

1. 프로젝트 목적

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

핵심 목표:

• 무료 데이터만 사용하여 미국 주식의 1~5거래일 이벤트 드리프트를 자동 탐지
• LLM/AI는 가격 예측기가 아니라 공시·문서 해석기로 사용
• 전략 중심: 공식 이벤트 + 가격 반응 확인 + 리스크 통제
• 초기 버전은 수익률 최대화보다 재현성, 운영 안정성, 확장 가능성 우선

---

2. 핵심 철학

AI/LLM = 문서 해석기, ≠ 가격 예측기

1. 공식 이벤트가 중심 — SEC 8-K, 10-Q, 6-K 등 기업이 직접 배포한 공시가 신호의 원천
2. 가격이 반드시 1차 검증 — 이벤트 발생 후 첫 정규장 반응(reaction day)이 강하게 확인된 종목만 후보
3. 재현성 최우선 — 무료 데이터 환경에서 가장 재현성 높은 데이터(SEC)를 중심에 배치

---

3. 시스템 아키텍처

전체 파이프라인

[SEC EDGAR / Stock Oracle / FRED / FINRA]
                              ↓
                       Source Adapters
                              ↓
                    Raw Storage (원문 보관)
                              ↓
                 Normalizer / Document Parser
                    (규칙 기반 + LLM 보강)
                              ↓
                Feature Store (Parquet 스냅샷)
                              ↓
                        Signal Ranker
                    (PEAD / Composite 스코어링)
                              ↓
                   Portfolio & Risk Engine
              (포지션 사이징, 섹터 제한, 진입 게이트)
                              ↓
                 Backtest Engine / Execution
              (이벤트 드리븐 시뮬레이션, 슬리피지)
                              ↓
                 Strategy Improvement Tracker
                    (SQS, Journal, Leaderboard)

3대 핵심 엔진

엔진	역할	입력	출력
Event Engine	공식 문서에서 이벤트 후보 생성	SEC 8-K, 10-Q, 6-K	event_type, direction, confidence
Document Understanding	규칙+LLM으로 문서 질 해석	exhibit text, XBRL	guidance_direction, demand_strength, margin_quality, oneoff_flags
Market Confirmation	시장의 실제 반응 확인	OHLCV bars	reaction_return, volume_ratio, close_location, gap_size

---

4. 디렉토리 구조

fithia2/
├── apps/                           # 애플리케이션 엔트리포인트
│   ├── backtester/                 #   이벤트 드리븐 백테스트 시뮬레이션 & CLI
│   │   ├── run.py                  #     메인 백테스트 실행기 (BacktestRunner)
│   │   └── replay.py               #     결정론 검증 (replay test)
│   ├── pipeline/                   #   멀티스테이지 데이터 처리 파이프라인
│   │   ├── filing_poller/          #     SEC EDGAR 신규 공시 폴링
│   │   ├── filing_fetcher/         #     공시 문서 다운로드
│   │   ├── event_parser/           #     이벤트 파싱 (규칙 + LLM)
│   │   ├── feature_builder/        #     스코어링 피처 생성
│   │   ├── label_generator/        #     forward-return 라벨 생성
│   │   └── dataset_export/         #     Parquet 스냅샷 내보내기
│   ├── sync/                       #   데이터 동기화
│   │   ├── issuer_sync/            #     기업 메타데이터 (Stock Oracle)
│   │   ├── macro_sync/             #     FRED 거시 지표
│   │   └── short_volume_sync/      #     FINRA 공매도 잔량
│   ├── tracker/                    #   전략 개선 추적 CLI (SQS, Journal, Leaderboard)
│   ├── tools/                      #   분석·유틸리티 스크립트 (10개)
│   ├── review/                     #   수동 리뷰 큐
│   └── qa/                         #   데이터 품질 체크
│
├── libs/                           # 핵심 라이브러리
│   ├── backtest/                   #   백테스트 엔진 (3,600+ lines)
│   │   ├── domain.py               #     Pydantic 도메인 모델 30개+
│   │   ├── scoring.py              #     후보 스코어링 (PEAD, composite)
│   │   ├── execution.py            #     진입/청산 시뮬레이션
│   │   ├── allocator.py            #     포지션 사이징 & 7개 진입 게이트
│   │   ├── selector.py             #     후보 필터링 & 랭킹
│   │   ├── metrics.py              #     21개 성과 지표 + 부트스트랩 CI
│   │   ├── tracker.py              #     SQS 계산, Journal I/O, Leaderboard
│   │   ├── snapshot_store.py       #     Parquet 데이터 로더
│   │   ├── splits.py               #     Walk-forward 윈도우 생성
│   │   ├── manifests.py            #     실험 config 해석
│   │   ├── artifacts.py            #     실행 결과 출력 (Parquet, JSON, CSV)
│   │   └── calendar.py             #     거래일 유틸리티
│   ├── oracle_client/              #   Stock Oracle API 클라이언트
│   │   ├── client.py               #     비동기 httpx 클라이언트 (retry 로직)
│   │   ├── price.py                #     OHLCV bars, ATR-14
│   │   ├── financial.py            #     재무제표 (BS, IS)
│   │   ├── filings.py              #     SEC 공시 검색/다운로드
│   │   ├── company.py              #     기업 메타데이터
│   │   ├── screener.py             #     유니버스 스크리닝
│   │   ├── fred.py                 #     거시 데이터
│   │   └── finra.py                #     공매도 잔량
│   ├── parser/                     #   공시 문서 파서
│   │   ├── rule_parser.py          #     규칙 기반 8-K/6-K 파서
│   │   ├── merger.py               #     규칙+LLM 결과 병합
│   │   └── text_normalizer.py      #     텍스트 정규화
│   ├── features/                   #   피처 엔지니어링
│   │   ├── builder.py              #     오케스트레이터 (market+event+financial)
│   │   ├── market_features.py      #     가격/거래량 피처
│   │   ├── event_features.py       #     이벤트 품질 피처
│   │   ├── financial_features.py   #     재무 피처 (EPS, 마진, 레버리지)
│   │   └── text_features.py        #     LLM 기반 텍스트 피처
│   ├── db/                         #   PostgreSQL 모델 (async SQLAlchemy)
│   │   ├── models.py               #     7개 테이블 (Issuer, Symbol, Event, Document, ...)
│   │   └── migrations/             #     Alembic 마이그레이션
│   ├── labeler/                    #   라벨 생성 (1/3/5/7/15일 forward return, MFE/MAE)
│   ├── common/                     #   로깅, config, 시간 유틸리티
│   ├── schemas/                    #   공유 Pydantic 스키마
│   ├── export/                     #   스냅샷 내보내기 (DB → Parquet)
│   ├── review/                     #   리뷰 로직
│   └── llm/                        #   LLM 통합 (Claude/OpenAI, 캐시, 프롬프트)
│
├── configs/
│   ├── backtest/
│   │   └── defaults.json           #   기본 전략 파라미터 (21개 설정)
│   ├── experiments/                #   실험 매니페스트 66개 (pead_midcap_step*, ...)
│   ├── app.yaml                    #   애플리케이션 설정
│   ├── symbols.yaml                #   활성 유니버스
│   ├── symbols_midcap.yaml         #   미드캡 유니버스 ($2B-10B)
│   ├── symbols_largecap.yaml       #   라지캡 유니버스 ($10B+)
│   ├── symbols_smallmid.yaml       #   스몰미드 유니버스
│   └── fred_series.yaml            #   FRED 거시 지표 정의
│
├── data/
│   ├── datasets/snapshots/         #   Parquet 스냅샷 (후보, bars, macro)
│   ├── cache/                      #   LLM/API 응답 캐시
│   ├── analysis/                   #   분석 결과 (플롯, CSV)
│   └── parquet/                    #   원시 Parquet 내보내기
│
├── runs/                           #   백테스트 실행 결과
│   └── midcap_steps/               #     65+ 실행 기록 (metrics.json, trade_blotter.csv, equity_curve.parquet)
│
├── journal/                        #   전략 개선 저널
│   ├── improvement_journal.jsonl   #     append-only 개선 사이클 로그 (21개+ 엔트리)
│   ├── experiment_registry.json    #     리더보드 데이터 (자동 생성)
│   └── LEADERBOARD.md              #     사람이 읽을 수 있는 리더보드 (자동 생성)
│
├── tests/
│   ├── unit/                       #   단위 테스트 270개+ (외부 의존성 없음)
│   ├── integration/                #   통합 테스트 (PostgreSQL 필요)
│   └── replay/                     #   결정론/재현성 테스트
│
├── dev/                            #   개발 문서
│   ├── overview.md                 #   전체 아키텍처 비전
│   ├── finished/                   #   완료된 Phase 문서 (0, 1, 2, 3, 4)
│   └── phase5~8_deliverables/      #   진행 중인 Phase 문서
│
├── docker/                         #   Docker 관련 파일
├── docker-compose.yml              #   PostgreSQL 16 + Adminer
├── pyproject.toml                  #   의존성 & 빌드 설정
├── Makefile                        #   빌드 & 테스트 자동화
└── alembic.ini                     #   DB 마이그레이션 설정

---

5. 데이터 파이프라인

5.1 데이터 흐름

단계 1: 원시 데이터 수집 (Phase 2)
┌──────────────────────────────────────────────────────┐
│ SEC EDGAR → 공시 JSON → 문서 (HTML/TXT) → raw zone  │
│ Stock Oracle → 일봉 OHLCV → market_bars             │
│ FRED → 거시 지표 (금리, 스프레드) → macro_features    │
│ FINRA → 일별 공매도 잔량 → short_volume              │
└──────────────────────────────────────────────────────┘
                          ↓
단계 2: 파싱 & 피처 엔지니어링 (Phase 3)
┌──────────────────────────────────────────────────────┐
│ Rule Parser → event_type, guidance, confidence       │
│ LLM Parser → 문서 이해 보강 (비활성화)                │
│ Feature Builder → XBRL, reaction, text 스코어        │
│ Label Generator → 1/3/5/7/15일 forward return,       │
│                   MFE/MAE, time-to-target             │
└──────────────────────────────────────────────────────┘
                          ↓
단계 3: 스냅샷 내보내기
┌──────────────────────────────────────────────────────┐
│ PostgreSQL → Parquet 스냅샷 (point-in-time)          │
│ 후보 (symbol, score, features)                       │
│ Bars (symbol, date, OHLCV)                           │
│ Macro (date, 거시 지표)                               │
└──────────────────────────────────────────────────────┘
                          ↓
단계 4: 백테스트 & 평가 (Phase 4)
┌──────────────────────────────────────────────────────┐
│ SnapshotStore.load() → 메모리 로드                    │
│ Signal Ranker → Candidate Selection → Position Sizing │
│ Entry/Exit Simulation → 21개 성과 지표 계산           │
│ SQS Score → Journal 기록 → Leaderboard 갱신          │
└──────────────────────────────────────────────────────┘

5.2 실행 명령어

# 기업 메타데이터 동기화
python -m apps.sync.issuer_sync.main

# 공시 폴링 → 다운로드 → 파싱
python -m apps.pipeline.filing_poller.main
python -m apps.pipeline.filing_fetcher.main
python -m apps.pipeline.event_parser.main

# 피처 빌드 → 라벨 생성
python -m apps.pipeline.feature_builder.main
python -m apps.pipeline.label_generator.main

# Parquet 스냅샷 내보내기
python -m apps.pipeline.dataset_export.main

---

6. 전략 엔진

6.1 현재 구현된 전략: PEAD (Post-Earnings Announcement Drift)

가설: 시장은 어닝 발표에 과소반응하며, 발표 후 3~5일간 드리프트(continuation)가 발생한다.

구성 요소	설정
신호	어닝 발표 + reaction day return ≥ 10% + PEAD score ≥ 0.65
진입	reaction day 다음 세션 시초가 (next-open)
보유	최대 7 거래일
청산	Target (ATR 기반) 또는 Stop loss (ATR 기반) 또는 시간 만기
방향	롱 + 숏 (양방향)
유니버스	미드캡 ($2B~$10B), NYSE/Nasdaq 보통주

6.2 PEAD 스코어링

3개 컴포넌트의 가중 합산:

컴포넌트	비중	피처
Event Quality	65%	parser confidence + signal strength + guidance
Reaction Direction	20%	positive/flat/negative 방향성
Volume Conviction	15%	평균 대비 거래량 확인

6.3 진입 게이트 (7개 Veto)

포지션이 열리기 전 모든 게이트를 통과해야 함:

1. 유니버스 필터 — 최소 가격 $5, 최소 ADV $1M, ETF 제외
2. 최대 포지션 수 — 포트폴리오 전체 동시 보유 제한 (기본 8)
3. 섹터 집중 제한 — 동일 섹터 최대 포지션 수
4. 포지션 크기 제한 — 포트폴리오 대비 최대 비중
5. ADV 비율 제한 — 일평균 거래대금의 1% 이내
6. 연패 쿨다운 — 연속 손실 후 대기 (설정 가능)
7. 파싱 신뢰도 게이트 — 최소 confidence 40%

6.4 Exit 로직

매 거래일 포지션 상태 체크:
  1) Target 도달? → target_1_fraction만큼 청산 (기본 50%)
  2) Stop loss 도달? → 전량 청산
  3) 보유 기한 초과? → 전량 시가 청산
  4) Trailing stop? → 최고점 대비 하락 시 청산

파라미터	기본값	설명
stop_atr_multiplier	3.0	ATR-14 × 3.0 stop
target_atr_multiplier	1.5	ATR-14 × 1.5 target
target_1_fraction	0.5	target 도달 시 50% 청산
trailing_stop_pct	0.05	5% trailing stop
max_holding_days	15	최대 보유일
slippage_bps	10	10bps 슬리피지

---

7. 백테스트 시스템

7.1 이벤트 드리븐 시뮬레이션

• 이벤트 귀속: reaction day (공시 후 첫 거래일) 기준
• 신호 계산: reaction day 종가 기준
• 진입: 다음 세션 시초가 (look-ahead bias 방지)
• 일별 포트폴리오 상태: 매일 equity, exposure, drawdown 추적
• Kill switch: 최대 낙폭 25% 초과 시 전략 중단

7.2 Walk-Forward 검증

3-split 체계로 과적합 방지:

Split	역할	용도
Train	파라미터 탐색	최적화용
Valid	검증	과적합 체크
Test	최종 평가	OOS 성과 (SQS 계산 대상)

7.3 21개 성과 지표

거래 지표 (7개)

• win_rate, avg_win%, avg_loss%, profit_factor, expectancy_r, avg_r, trade_count

포트폴리오 지표 (8개)

• total_return, monthly_returns, sharpe_ratio, max_drawdown, equity_curve_r², VaR, CVaR, consecutive_losses

부트스트랩 95% 신뢰구간

• 리샘플링을 통한 통계적 유의성 확인

7.4 실행 예시

# 단일 split 백테스트
python -m apps.backtester.run \
  --manifest configs/experiments/pead_midcap_step14_score65.json \
  --split test \
  --snapshot-dir data/datasets/snapshots \
  --output-root runs/midcap_steps

# 3-split 전체 백테스트
for split in train valid test; do
  python -m apps.backtester.run \
    --manifest configs/experiments/pead_midcap_step14_score65.json \
    --split $split \
    --snapshot-dir data/datasets/snapshots \
    --output-root runs/midcap_steps
done

# Walk-forward CV
python -m apps.backtester.run \
  --manifest configs/experiments/pead_midcap_step14_score65.json \
  --walk-forward --wf-train-days 252 --wf-test-days 63

출력 예시:

Run complete: bt_baseline_swing_v1_midcap-filte_20260316...
Trades: 72
Total return: +0.73%
SQS: 64.2 (profitability=68.4, risk=61.2, consistency=58.7, robustness=65.3)

---

8. 전략 개선 시스템

전략 개선을 체계적으로 관리하기 위한 3계층 시스템. 중복 실험 방지, 데이터 기반 의사결정, 리더보드를 통한 최고 전략 추적.

8.1 Strategy Quality Score (SQS)

test split 지표만으로 계산하는 종합 점수 (0~100). 높을수록 좋음.

카테고리	비중	하위 지표	비중	0점 기준	100점 기준
Profitability	40%	profit_factor	60%	≤ 0.8	≥ 2.0
		total_return_pct	40%	≤ -5%	≥ +5%
Risk	25%	max_drawdown_pct (역)	50%	≥ 10%	≤ 1%
		sharpe_ratio	50%	≤ -1.0	≥ 2.0
Consistency	20%	win_rate	50%	≤ 0.35	≥ 0.65
		monthly_win_rate	50%	≤ 0.30	≥ 0.70
Robustness	15%	equity_curve_r²	50%	≤ 0.0	≥ 0.80
		trade_count	50%	≤ 10	≥ 100

Low-trade penalty: test 거래 수 < 20이면 SQS를 절반으로 감산.

SQS 해석 기준:

SQS 범위	해석
0–20	손실 전략
20–40	손익분기 근처
40–55	유망, 개선 필요
55–70	좋음, OOS 엣지 있음
70–85	강함, 실전 후보
85–100	예외적 (데이터 오류 확인 필요)

8.2 Journal (개선 저널)

모든 실험 결과를 기록하는 append-only 로그.

journal/
├── improvement_journal.jsonl   ← append-only 개선 사이클 로그
├── experiment_registry.json    ← 리더보드 데이터 (자동 생성)
└── LEADERBOARD.md              ← 사람이 읽는 리더보드 (자동 생성)

Journal 엔트리 구조:

{
  "entry_id": "IMP-0015",
  "timestamp": "2026-03-17T01:45:00+00:00",
  "experiment_name": "pead_midcap_step14_score65",
  "hypothesis": "Score threshold 0.60→0.65로 높여 약한 신호 필터링",
  "config_delta": {
    "base_experiment": "pead_midcap_step13_best",
    "changes": { "signal.score_threshold": "0.60 → 0.65" }
  },
  "results": {
    "train": { "run_id": "bt_...", "trade_count": 312, "profit_factor": 1.15, "..." : "..." },
    "valid": { "run_id": "bt_...", "trade_count": 145, "profit_factor": 1.28, "..." : "..." },
    "test":  { "run_id": "bt_...", "trade_count": 72,  "profit_factor": 1.22, "..." : "..." }
  },
  "sqs_score": 64.2,
  "sqs_breakdown": {
    "profitability": 68.4,
    "risk": 61.2,
    "consistency": 58.7,
    "robustness": 65.3
  },
  "verdict": "better",
  "verdict_reasoning": "Test SQS 64.2 > 57.7. Return +0.73% > +0.43%. Trade count 72 sufficient.",
  "next_direction": "Test exit tuning (target, fraction, hold) on top of score 0.65"
}

8.3 실험 매니페스트

실험은 JSON 매니페스트로 정의. base_config에 overrides를 적용하는 구조:

{
  "experiment_name": "pead_midcap_step14_score65",
  "dataset_snapshot_id": "midcap-filtered",
  "description": "Step 14: Score threshold 0.60→0.65",
  "base_config": "configs/backtest/defaults.json",
  "overrides": {
    "event_type_profiles": {
      "earnings_release": { "enabled": true, "direction_filter": "any" }
    },
    "signal": {
      "scoring_model": "pead",
      "pead_reaction_threshold": 0.10,
      "pead_volume_threshold": 2.0,
      "score_threshold": 0.65,
      "max_candidates_per_day": 3
    },
    "execution": { "max_holding_days": 7 },
    "risk": { "max_positions": 8 }
  },
  "tags": ["pead", "midcap", "step14", "score65"]
}

8.4 개선 워크플로우

1. 실험 config 생성       configs/experiments/my_experiment.json
2. 3-split 백테스트 실행   for split in train valid test; do ... done
3. Journal에 기록          fithia2 rec -e my_experiment ...
4. Leaderboard 확인        fithia2 lb
5. 다음 실험 계획          verdict + SQS breakdown 기반
6. 중복 실험 확인          fithia2 dup -e my_experiment
7. 1번부터 반복

8.5 Tracker CLI

pip install -e . 후 fithia2 명령어로 실행. --journal-dir / --runs-dir 생략 시 기본값(journal/, runs/) 사용.

# 도움말
fithia2

# 리더보드 출력 (top 10)
fithia2 lb

# 리더보드 — 상위 N개
fithia2 lb -n 20

# 실험 결과 기록
fithia2 rec \
  -e pead_midcap_step14_score65 \
  -H "Score threshold 0.60→0.65" \
  -b pead_midcap_step13_best \
  -v better \
  -r "Test SQS 64.2 > 57.7, Return +0.73% > +0.43%" \
  -n "Test exit tuning on top of score 0.65"

# 엔트리 상세 조회
fithia2 s IMP-0015

# 중복 실험 확인
fithia2 dup -e my_experiment_name

명령	alias	설명
leaderboard	lb	SQS 순위표 출력 및 LEADERBOARD.md 재생성
record	rec	실험 결과를 저널에 기록
show	s	특정 저널 항목 상세 조회
check-duplicate	dup	동일 실험명 중복 여부 확인

8.6 핵심 발견사항

21개 실험을 통해 얻은 인사이트:

발견	설명
Score threshold가 가장 강력한 레버	0.60→0.65로 올리면 SQS 50.2→64.2 (+28%)
넓은 funnel은 OOS에서 실패	reaction 0.10→0.07로 낮추면 거래 수는 늘지만 품질 하락
Exit 튜닝은 한계적	target/fraction/hold 변경은 noise 범위 내
조합이 개별보다 나쁨	한계적 개선들을 합치면 과적합 리스크로 오히려 하락
단순함이 최고	Step14(score 0.65만 변경)가 모든 복합 변형보다 우수
라지캡 확장 실패	$10B+ 대형주에서는 OOS 성과 없음, 미드캡이 최적
보유기간 5~7일 최적	PEAD 드리프트의 평균 보유는 3.28일

---

9. 현재 개발 현황

Phase별 진행 상태

Phase	이름	상태	설명
Phase 0	전략/운용 명세 동결	완료	strategy_spec.md, risk_policy.md, data_source_policy.md, event_taxonomy.md
Phase 1	개발 기반 & DB 스키마	완료	Docker, PostgreSQL, Alembic, adapter contracts, 공통 인프라
Phase 2	핵심 데이터 수집	완료	SEC, Alpaca(→Stock Oracle), FRED, FINRA 어댑터 구축
Phase 3	문서 파서 & 피처 빌더	완료	규칙 기반 파서 + LLM 보강, 피처 엔지니어링, 라벨 생성
Phase 4	백테스트 엔진	완료	이벤트 드리븐 시뮬레이터, walk-forward CV, SQS 스코어링, 21개 지표

현재 작동 중인 것

• 백테스트 엔진 (이벤트 드리븐, 재현 가능, 21개 지표)
• Walk-forward cross-validation (train/valid/test 분할)
• 실험 추적 (Journal, Leaderboard, SQS 스코어링)
• PEAD 전략 (주력 신호, SQS 64.2, +0.73% OOS)
• 단위/통합 테스트 (270개+ 자동화)
• 포트폴리오 리스크 엔진 (포지션 사이징, 섹터 제한, stop/target)
• 데이터 파이프라인 (filing_poller → event_parser → feature_builder → dataset_export)

---

10. 현재 최고 전략 성과

Leaderboard (Top 10, 2026-03-17 기준)

#	Experiment	SQS	PF	Ret%	WR	Sharpe	DD%	Trades
1	pead_midcap_step14_score65	64.2	1.22	+0.7	57%	1.3	0.9	72
2	pead_midcap_step18_nofrac	63.2	1.23	+0.8	52%	1.4	0.9	64
3	pead_midcap_step19_hold5	62.9	1.20	+0.7	57%	1.2	0.9	72
4	pead_midcap_step20_best3	62.0	1.22	+0.7	52%	1.3	0.9	64
5	pead_midcap_step17_target2	59.4	1.18	+0.6	53%	1.1	0.8	66
6	pead_midcap_step13_best	57.7	1.12	+0.4	55%	0.8	0.9	75
7	pead_midcap_step16_react7_score65	53.2	0.97	-0.1	56%	-0.2	1.6	89
8	pead_midcap_step5_maxcand3	52.5	0.95	-0.2	54%	-0.4	1.4	96
9	pead_midcap_step15_react7	51.7	0.94	-0.3	55%	-0.5	1.6	91
10	pead_midcap_step11_score60	50.2	1.02	+0.1	52%	0.2	0.9	77

최고 전략: pead_midcap_step14_score65

SQS:       64.2 (Good — OOS edge 확인)
수익률:    +0.73% (OOS test)
PF:        1.22
승률:      56.9%
Sharpe:    1.3
최대낙폭:  0.9%
거래 수:   72
보유기간:  평균 3.28일

핵심 설정:

• reaction threshold: 10% (어닝 발표 후 첫날 10% 이상 반응한 종목만)
• score threshold: 0.65 (PEAD 스코어 0.65 이상만 진입)
• volume threshold: 2.0x (평균 대비 2배 이상 거래량)
• max candidates/day: 3 (하루 최대 3개 후보)
• max holding: 7일
• earnings_release만 활성화 (다른 이벤트 타입 비활성화)

---

11. 설치 및 실행

요구사항

• Python 3.11+
• PostgreSQL 16 (Docker 제공)
• Stock Oracle API (Docker, localhost:18001)

설치

# 의존성 설치
pip install -e ".[dev]"

# PostgreSQL 시작
docker compose up -d

# DB 마이그레이션
alembic upgrade head

# 환경 변수 설정
cp .env.example .env

환경 변수

변수	기본값	설명
STOCK_ORACLE_URL	http://localhost:18001	Stock Oracle API 엔드포인트
POSTGRES_DSN	postgresql+asyncpg://acef:acef@localhost:5432/acef	DB 연결
DATA_ROOT	./data	데이터 저장 루트
LOG_LEVEL	INFO	로그 레벨
LLM_ENABLED	false	LLM 문서 파싱 활성화

Makefile 타겟

make bootstrap          # 의존성 설치
make db-upgrade         # 마이그레이션 실행
make db-reset           # DB 전체 리셋
make test-unit          # 단위 테스트만
make test-integration   # 통합 테스트 (PostgreSQL 필요)
make test-replay        # 결정론 테스트
make lint               # Ruff 린트
make typecheck          # MyPy 엄격 모드
make ci                 # 전체 CI (lint + typecheck + test)

---

12. 사용법

데이터 파이프라인 실행

# 1) 기업 메타데이터 동기화
python -m apps.sync.issuer_sync.main

# 2) 공시 수집 → 파싱 → 피처 빌드 → 라벨 생성
python -m apps.pipeline.filing_poller.main
python -m apps.pipeline.filing_fetcher.main
python -m apps.pipeline.event_parser.main
python -m apps.pipeline.feature_builder.main
python -m apps.pipeline.label_generator.main

# 3) 백테스트용 Parquet 스냅샷 내보내기
python -m apps.pipeline.dataset_export.main

백테스트 실행

# 3-split 백테스트 (train/valid/test)
for split in train valid test; do
  python -m apps.backtester.run \
    --manifest configs/experiments/pead_midcap_step14_score65.json \
    --split $split \
    --snapshot-dir data/datasets/snapshots \
    --output-root runs/midcap_steps
done

주의: Stock Oracle API는 단일 스레드이므로 백테스트를 순차적으로 실행해야 합니다. 병렬 실행 시 API가 과부하되어 연결이 끊깁니다.

실험 결과 기록

# Journal에 기록
fithia2 rec \
  -e pead_midcap_step14_score65 \
  -H "Score threshold 0.60→0.65" \
  -b pead_midcap_step13_best \
  -v better \
  -r "Test SQS 64.2 > 57.7" \
  -n "Exit tuning on top of score 0.65"

# 리더보드 확인
fithia2 lb

테스트

# 단위 테스트 (빠름, 외부 의존성 없음)
pytest tests/unit/ -v

# 백테스트 모듈 테스트
pytest tests/unit/backtest/ -v

# 통합 테스트 (PostgreSQL 필요)
pytest tests/integration/ -v

# 전체 CI
make ci

---

13. 기술 스택

구성 요소	기술
언어	Python 3.11+
도메인 모델	Pydantic v2
운영 DB	PostgreSQL 16 + async SQLAlchemy + asyncpg
연구 데이터	DuckDB + Apache Parquet
마이그레이션	Alembic
HTTP 클라이언트	httpx (비동기)
컨테이너	Docker Compose
린트	Ruff (line 100, Python 3.11+)
타입 체크	MyPy (strict mode)
테스트	Pytest + pytest-asyncio (270+ 테스트)
로깅	structlog (JSON)
LLM	Ollama (인프라 구현, 파서 비활성화)
문서 파싱	BeautifulSoup4 + 규칙 기반 + LLM
거래일 캘린더	exchange-calendars

---

14. 데이터 소스

소스	역할	계층	비용
SEC EDGAR	이벤트 원천 (8-K, 10-Q, 6-K 공시)	Core	무료
Stock Oracle API	시장 데이터 (OHLCV, 기업정보, 재무)	Core	내부
FRED	거시 레짐 (금리, 스프레드, 경기 지표)	Core	무료
FINRA	공매도 잔량 (crowding 신호)	보조	무료

데이터 정책

• 모든 시장 데이터는 Stock Oracle API를 통해서만 접근 — 직접 외부 API 호출 금지
• API 부재 기능은 구현 대신 보고
• 유료 데이터 소스 사용 금지
• LLM은 문서 해석기로만 사용, 가격 예측 금지

---

License

Private project. All rights reserved.