# Feature Catalog

## 1. 원칙

1. feature는 반드시 **point-in-time safe** 해야 한다.
2. 각 feature는 `as_of_ts`, `source`, `feature_version`을 가진다.
3. 미래 데이터를 암묵적으로 쓰는 rolling 통계는 금지한다.
4. missing value는 명시적으로 처리하고, silent fill 금지.

## 2. Feature 그룹

### 2.1 Event features

| feature | 타입 | 설명 | 계산/정의 | null 처리 |
|---|---|---|---|---|
| event_type | categorical | taxonomy 기반 이벤트 종류 | parser output | 불가 |
| event_direction | categorical | bullish/bearish/mixed | parser output | unknown 허용 |
| guidance_direction | categorical | raised/inline/lowered/... | parser output | unknown 허용 |
| quality_assessment | categorical | high/mixed/low/unknown | parser output | unknown 허용 |
| oneoff_suspicion | categorical | none/possible/likely | parser output | unknown 허용 |
| confidence_overall | float | parser 종합 confidence | parser output | 불가 |
| document_count | int | event에 연결된 문서 수 | count | 0 불가 |
| evidence_span_count | int | 핵심 필드 evidence 수 | count | 0 허용 |

### 2.2 Document text features

| feature | 타입 | 설명 |
|---|---|---|
| demand_strength_score | float | backlog/bookings/orders/customers 관련 점수 |
| pricing_power_score | float | pricing / ASP / price realization 점수 |
| margin_strength_score | float | margin expansion 관련 점수 |
| tone_score | float | management tone ordinal 매핑 |
| oneoff_keyword_count | int | 일회성 관련 키워드 출현 수 |
| guidance_statement_count | int | guidance 관련 문장 수 |
| doc_length_tokens | int | 정규화 문서 토큰 수 |
| qa_risk_flag | bool | ambiguous language 또는 parser disagreement 여부 |

권장 ordinal mapping 예시:
- strong_positive = +2
- mild_positive = +1
- neutral = 0
- mild_negative = -1
- strong_negative = -2
- mixed = 0

### 2.3 Numeric issuer features

XBRL 또는 rule parser에서 추출:
- revenue_yoy_pct
- gross_margin_yoy_delta
- operating_margin_yoy_delta
- free_cash_flow_yoy_pct
- debt_to_cash_delta
- prior_company_guidance_surprise_pct

주의:
- 컨센서스 surprise는 v1에 없음
- 회사 가이던스 대비 actual만 허용
- 분모 0 또는 누락 시 null

### 2.4 Market reaction features

반응일 기준:
- reaction_day_return_pct
- reaction_gap_pct
- reaction_volume_ratio_20d
- reaction_close_location
- reaction_intraday_range_pct
- reaction_close_vs_vwap (가능한 경우)
- reaction_close_vs_20d_ma
- reaction_sector_relative_return

정의:
- `reaction_close_location = (close - low) / (high - low)`
- `reaction_volume_ratio_20d = volume / avg_volume_20d_prior`

주의:
- moving average / ATR은 반드시 entry 이전 데이터만 사용

### 2.5 Regime features

- spy_trend_20d
- qqq_trend_20d
- sector_etf_trend_20d
- vix_level
- vix_change_1d
- fred_rate_regime_bucket

### 2.6 Attention features

Phase 3에서는 ingestion이 아니라 결합/정규화만 구현:
- yahoo_headline_burst_6h
- yahoo_unique_publishers_24h
- wiki_pageview_zscore_1d
- youtube_influence_score_24h
- finra_short_volume_ratio
- finra_short_ratio_zscore_20d

주의:
- attention feature는 core trigger 아님
- missing source가 있어도 학습 레코드는 유지

## 3. Feature naming 규칙

- snake_case
- 단위 포함 (`_pct`, `_ratio`, `_count`, `_score`)
- 날짜창 포함 (`_1d`, `_3d`, `_20d`)
- categorical은 값 집합 문서화 필수

## 4. Leakage 금지 규칙

금지 예시:
- reaction day close 후 생성되어야 하는 feature를 same-day open entry 모델에 사용
- future bar를 포함한 ATR/MA
- 거래 종료 후 게시되는 FINRA data를 당일 시초 진입 feature로 사용

필수 메타데이터:
- `feature_as_of_ts`
- `feature_available_ts`
- `entry_convention`

## 5. Feature availability by entry convention

### next_open_entry
허용:
- event filing timestamp까지 공개된 정보
- reaction day 종가까지의 가격/거래량
- previous day까지의 FINRA/FRED/attention

금지:
- entry day 장중 가격
- entry day 종가

### dayplus1_close_entry
허용:
- entry day 종가까지의 정보

## 6. Feature export 형식

Canonical feature record는 최소 아래를 포함:
- ids: event_instance_id, filing_id, symbol, reaction_date
- parser summary
- all feature columns
- availability metadata
- schema_version

Parquet 저장 시:
- 파티션: `reaction_year=YYYY/reaction_month=MM`
- row group은 심볼 기준보다 날짜 기준 우선