fithia2/dev/phase3_deliverables/parser_and_feature_architecture.md

# Phase 3 아키텍처: Parser / Feature / Label Pipeline

## 1. 목적

Phase 3의 목적은 Phase 2에서 수집된 원문과 시계열 데이터를 **연구/백테스트/실거래에서 공통으로 사용할 수 있는 구조화된 이벤트 레코드**로 바꾸는 것입니다.

핵심 철학은 다음과 같습니다.

1. **숫자는 규칙/계산으로 추출**하고, LLM은 숫자 계산기를 대체하지 않는다.
2. **LLM은 문맥 해석과 질 판단**에만 사용한다.
3. 모든 출력은 **schema-valid JSON**이어야 한다.
4. 모든 레코드는 **provenance, confidence, parser_version, prompt_version**을 가진다.
5. 파서 출력은 사람이 검수할 수 있어야 하며, 검수 결과가 다시 학습 데이터에 반영되어야 한다.

## 2. 전체 흐름

```text
Phase 2 raw/staging data
    ↓
Document selector
    ↓
Rule parser
    ↓
LLM enrichment
    ↓
Canonical event record
    ↓
Feature builder
    ↓
Label generator
    ↓
Research dataset / review queue / gold set report
```

## 3. 서비스 경계

### 3.1 document_selector
책임:
- 어떤 문서가 parser 대상인지 결정
- 8-K 본문, Exhibit 99.1, 10-Q/10-K, 6-K를 우선순위에 따라 고름
- 동일 accession 내 여러 첨부가 있을 때 우선 파싱 대상을 선택

입력:
- `filings`, `filing_documents`, `filing_document_blobs`

출력:
- `parser_jobs`

정책:
- `8-K` + `EX-99.1` 조합을 최우선
- `10-Q`/`10-K`는 event class에 따라 본문과 xbrl summary 모두 생성
- 1 accession에 대해 parser target은 여러 개일 수 있으나, canonical event id는 하나 이상이 되지 않도록 dedupe 규칙 필요

### 3.2 rule_parser
책임:
- 문서 텍스트에서 deterministic하게 뽑을 수 있는 필드를 추출
- item number, 숫자 패턴, guidance 문구, one-off 키워드, margin/growth 문구 등을 추출

입력:
- normalized document text
- filing metadata
- xbrl facts (선택)

출력:
- `rule_parse_outputs`

원칙:
- 숫자 필드는 가능하면 규칙 기반/파서 기반으로 추출
- regex/keyword/section parser 실패는 null로 남기고 hallucination 금지

### 3.3 llm_enricher
책임:
- rule parser가 뽑은 결과를 보강하고 문맥 분류 수행
- event direction, quality, guidance tone, one-off suspicion, demand_strength, pricing_power 등을 추출

입력:
- 문서 본문 일부/요약
- rule parser output
- 이벤트 taxonomy 힌트

출력:
- schema-valid `llm_parse_outputs`

정책:
- LLM은 숫자 값을 새로 발명하지 않는다.
- 숫자/날짜/티커의 신규 추론은 금지한다.
- 불확실하면 `unknown`, `mixed`, `low_confidence`를 사용한다.

### 3.4 canonicalizer
책임:
- rule parse + llm output을 병합해 canonical event record 생성
- 필드별 provenance를 저장
- 충돌(disagreement)을 계산하고 review queue에 보냄

출력:
- `event_records`
- `review_queue`

### 3.5 feature_builder
책임:
- event/document/market/regime/attention feature 생성
- point-in-time safe feature만 허용
- 각 feature의 `as_of_ts`와 source를 기록

출력:
- `event_feature_records`

### 3.6 label_generator
책임:
- entry convention 기준으로 1D/3D/5D outcome 생성
- MFE/MAE, stop-hit, target-hit 계산
- leakage 방지 규칙 준수

출력:
- `event_labels`
- `dataset_snapshots`

## 4. 데이터 플로우 상세

### 4.1 parser 대상 선정

문서 대상 우선순위:
1. 8-K의 EX-99.1 earnings release / shareholder letter
2. 8-K 본문 (Item 2.02 / 7.01 / 1.01 / 8.01)
3. 6-K 첨부 IR release
4. 10-Q / 10-K MD&A 요약 구간
5. 추가 IR 보조자료(허용 source에 한함)

### 4.2 텍스트 정규화

반드시 구현:
- HTML 제거와 line-break 정리
- 표/머리글/꼬리말 단순화
- repeated disclaimer 제거 옵션
- 숫자 단위 정규화 (million, billion 등)
- Unicode normalize

보존해야 할 것:
- 원문 raw blob
- 정규화 전 text hash
- 정규화 후 text hash

### 4.3 provenance

각 필드별 provenance 예시:
- `guidance_direction.source = rule|llm|manual`
- `guidance_direction.evidence = [document_span_refs...]`
- `guidance_direction.confidence = 0.82`

Phase 3에서 필수로 남길 메타데이터:
- parser_version
- prompt_version
- schema_version
- model_name
- model_temperature
- document_hash
- source_filing_id
- created_at

## 5. review queue 생성 규칙

다음 중 하나면 review queue 생성:
- LLM confidence < threshold
- rule/LLM 핵심 필드 충돌
- one-off flag = suspected
- guidance direction = mixed/unknown
- parser JSON schema validation 실패
- canonicalization에서 required field null 과다

## 6. canonical dataset 단위

기본 학습 단위는 **event x symbol x reaction_date** 입니다.

이유:
- 하나의 filing이 여러 문서를 포함할 수 있음
- 반응일 기준으로 entry/label이 정의되므로 event timestamp만으로는 부족함
- same issuer/day multiple filings도 구분 가능해야 함

Primary key 제안:
- `event_instance_id`
- `symbol`
- `reaction_date`

## 7. 성능보다 우선하는 것

Phase 3에서는 다음이 중요합니다.
- 재현 가능성
- 추적 가능성
- 수동 검수 가능성
- leakage 방지
- 비용 통제

따라서 처음부터 고성능 병렬화보다 **작동이 명확하고 audit 가능한 구현**을 우선합니다.