You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
151 lines
4.2 KiB
Markdown
151 lines
4.2 KiB
Markdown
# Document Parser 상세 설계
|
|
|
|
## 1. 설계 원칙
|
|
|
|
1. 문서는 **규칙 기반 추출 → LLM 보강 → 병합** 순서로 처리한다.
|
|
2. 추출 결과는 **event taxonomy**와 모순되면 review 대상이다.
|
|
3. LLM은 숫자를 계산하거나 invent하지 않는다.
|
|
4. 모든 핵심 필드는 evidence span을 남긴다.
|
|
|
|
## 2. 파서 입력
|
|
|
|
입력 필수 항목:
|
|
- filing_id
|
|
- accession_no
|
|
- cik
|
|
- issuer_name
|
|
- symbol
|
|
- form_type
|
|
- filing_ts
|
|
- document_id
|
|
- document_type
|
|
- normalized_text
|
|
- text_hash
|
|
- optional_xbrl_summary
|
|
- optional_prior_guidance_snapshot
|
|
|
|
## 3. 단계별 파서 흐름
|
|
|
|
### Step A. Pre-classification
|
|
문서 종류 추정:
|
|
- earnings release
|
|
- shareholder letter
|
|
- contract announcement
|
|
- regulatory/approval update
|
|
- guidance update
|
|
- misc material event
|
|
|
|
실패 시:
|
|
- `event_type = unknown`
|
|
- review queue로 보낼 수 있음
|
|
|
|
### Step B. Rule extraction
|
|
규칙 기반으로 먼저 뽑을 필드:
|
|
- item numbers
|
|
- guidance phrases (`raising`, `updating`, `expects`, `reaffirms`, `withdraws`)
|
|
- one-off markers (`tax benefit`, `gain on`, `fair value`, `impairment`, `restructuring`, `non-GAAP`)
|
|
- demand markers (`backlog`, `bookings`, `pipeline`, `orders`, `customers`)
|
|
- pricing markers (`pricing`, `price increase`, `higher ASP`, `price realization`)
|
|
- margin markers (`gross margin`, `operating margin`, `expanding margin`)
|
|
- direct numeric snippets for revenue/EPS/guidance if present
|
|
|
|
### Step C. LLM enrichment
|
|
LLM이 판단할 필드:
|
|
- `event_direction`: bullish / bearish / mixed / neutral / unknown
|
|
- `guidance_direction`: raised / inline / lowered / withdrawn / ambiguous / unknown
|
|
- `quality_assessment`: high_quality / mixed_quality / low_quality / unknown
|
|
- `demand_strength`: strong / moderate / weak / unclear
|
|
- `pricing_power`: strong / present / absent / unclear
|
|
- `management_tone`: strong_positive / mild_positive / neutral / mild_negative / strong_negative / mixed
|
|
- `oneoff_suspicion`: none / possible / likely
|
|
- `customer_expansion`: yes / no / unclear
|
|
- `structural_change_flag`: yes / no / unclear
|
|
|
|
### Step D. Canonical merge
|
|
병합 규칙 예시:
|
|
- 숫자: rule parser 우선
|
|
- taxonomy/classification: rule strong hit가 있으면 rule 우선, 그 외는 llm
|
|
- quality/tone: llm 우선
|
|
- one-off: rule hit와 llm 판단을 모두 보존, canonical은 더 보수적인 값 사용
|
|
|
|
## 4. 필수 출력 필드
|
|
|
|
최소 필수 출력:
|
|
- `event_instance_id`
|
|
- `source_filing_id`
|
|
- `symbol`
|
|
- `event_type`
|
|
- `event_direction`
|
|
- `guidance_direction`
|
|
- `quality_assessment`
|
|
- `oneoff_suspicion`
|
|
- `confidence_overall`
|
|
- `evidence_refs`
|
|
- `parser_version`
|
|
- `prompt_version`
|
|
- `schema_version`
|
|
|
|
## 5. evidence span 정책
|
|
|
|
각 핵심 필드는 evidence span 1개 이상 권장:
|
|
- line offsets 또는 character offsets
|
|
- 최대 3개 span
|
|
- 증거 없는 강한 주장 금지
|
|
|
|
예시:
|
|
```json
|
|
{
|
|
"guidance_direction": "raised",
|
|
"guidance_direction_confidence": 0.88,
|
|
"guidance_direction_evidence": [
|
|
{"start": 1245, "end": 1320, "text": "raising full-year revenue guidance..."}
|
|
]
|
|
}
|
|
```
|
|
|
|
## 6. 금지사항
|
|
|
|
- 문서에 없는 실적 추정치/컨센서스 생성
|
|
- 문서에 없는 티커/세그먼트 생성
|
|
- confidence가 낮은데도 단정적 레이블 출력
|
|
- JSON schema를 어기는 자유형식 텍스트 반환
|
|
- one-off suspicion이 높은데 high_quality로 단정
|
|
|
|
## 7. fallback 정책
|
|
|
|
### 규칙 파서 실패
|
|
- null 허용
|
|
- 실패 사유를 `parse_warnings`에 남김
|
|
- LLM 보강을 시도하되 hallucination 금지
|
|
|
|
### LLM 실패
|
|
- rule-only canonical record 생성
|
|
- `llm_status = failed`
|
|
- review queue 생성
|
|
|
|
### JSON validation 실패
|
|
- 1회 자동 수정 요청 가능
|
|
- 그래도 실패면 `parse_failed` 상태로 저장
|
|
|
|
## 8. 수동 검수 트리거
|
|
|
|
다음은 반드시 검수 후보:
|
|
- `guidance_direction = ambiguous|unknown`
|
|
- `quality_assessment = unknown`
|
|
- `oneoff_suspicion = likely`
|
|
- `confidence_overall < 0.70`
|
|
- rule과 llm의 `event_direction` 충돌
|
|
|
|
## 9. 개발 시 구현 단위
|
|
|
|
추천 구현 순서:
|
|
1. text normalizer
|
|
2. rule-based keyword extractor
|
|
3. line/span mapper
|
|
4. llm client wrapper
|
|
5. schema validator
|
|
6. canonical merge function
|
|
7. review queue writer
|
|
|
|
각 단계는 독립적으로 테스트 가능해야 합니다.
|