fithia2/dev/finished/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. 전체 흐름

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 가능한 구현을 우선합니다.