# Event Parser JSON 규격

## 1. 목적

이 규격은 문서 파서의 출력 형식을 고정합니다.
규칙 기반 파서와 LLM 기반 파서는 **동일한 출력 schema**를 따라야 합니다.

## 2. 최상위 구조

```json
{
  "schema_version": "1.0.0",
  "document_id": "DOC::SEC::0000789019::2026-01-28::0001193125-26-027198",
  "parser_kind": "rule|llm|merged",
  "event_type": "earnings_release",
  "event_direction": "bullish",
  "event_date": "2026-01-29",
  "filing_time_bucket": "pre_market|regular_hours|post_market|unknown",
  "headline": "Q2 results and guidance update",
  "summary": "Revenue grew and forward guidance improved.",
  "guidance": {
    "status": "raised",
    "scope": "quarterly",
    "notes": "Management raised next-quarter revenue guidance."
  },
  "signals": {
    "demand_strength": "strong",
    "pricing_power": "present",
    "backlog_or_bookings": "present",
    "customer_expansion": "present",
    "margin_quality": "improving"
  },
  "risk_flags": {
    "oneoff_item": false,
    "tax_benefit": false,
    "valuation_gain": false,
    "non_gaap_heavy": false,
    "financing_related": false,
    "legal_or_regulatory_overhang": false
  },
  "evidence": [
    {
      "label": "guidance_raise",
      "text_span": "expects revenue for Q3 to be between ...",
      "section_hint": "Exhibit 99.1",
      "confidence": 0.92
    }
  ],
  "confidence": {
    "overall": 0.88,
    "event_type": 0.97,
    "event_direction": 0.85,
    "guidance": 0.83,
    "risk_flags": 0.74
  },
  "warnings": []
}
```

## 3. 필수 필드

- `schema_version`
- `document_id`
- `parser_kind`
- `event_type`
- `event_direction`
- `event_date`
- `filing_time_bucket`
- `summary`
- `guidance`
- `signals`
- `risk_flags`
- `confidence`

## 4. 필드 정의

### 4.1 parser_kind
허용값:
- `rule`
- `llm`
- `merged`

### 4.2 event_type
초기 허용값:
- `earnings_release`
- `guidance_update`
- `material_contract`
- `regulatory_or_approval`
- `capital_markets_or_financing`
- `management_change`
- `litigation_or_investigation`
- `other_material_event`
- `unknown`

### 4.3 event_direction
허용값:
- `bullish`
- `bearish`
- `mixed`
- `neutral`
- `unknown`

### 4.4 filing_time_bucket
허용값:
- `pre_market`
- `regular_hours`
- `post_market`
- `unknown`

### 4.5 guidance.status
허용값:
- `raised`
- `inline_or_maintained`
- `lowered`
- `withdrawn`
- `not_provided`
- `unclear`

### 4.6 signals
각 필드는 문자열 enum 또는 `unknown`

- `demand_strength`: `strong|stable|weakening|unknown`
- `pricing_power`: `present|mixed|absent|unknown`
- `backlog_or_bookings`: `present|mixed|absent|unknown`
- `customer_expansion`: `present|mixed|absent|unknown`
- `margin_quality`: `improving|stable|deteriorating|unknown`

### 4.7 risk_flags
각 필드는 boolean

### 4.8 evidence
원문 근거 배열. 최소 0개 허용.
권장 최대 10개.

각 evidence 필드:
- `label`
- `text_span`
- `section_hint`
- `confidence`

### 4.9 confidence
0~1 실수

필수:
- `overall`
- `event_type`
- `event_direction`
- `guidance`
- `risk_flags`

## 5. 설계 원칙

- parser는 확신이 없으면 `unknown` 또는 `unclear`를 사용합니다.
- parser는 숫자를 추정하지 않습니다.
- parser는 근거 없는 positive/negative 해석을 하지 않습니다.
- LLM parser는 가능한 한 evidence를 함께 반환해야 합니다.
- `summary`는 300자 이내 요약을 권장합니다.

## 6. validation 규칙

- 필수 필드 누락 시 invalid
- enum 이탈 시 invalid
- confidence 범위 벗어나면 invalid
- evidence confidence도 0~1 범위여야 함
- `document_id`가 없으면 invalid

## 7. 향후 확장 예비 필드

Phase 1에서는 사용하지 않지만 향후 확장 가능:
- `transcript_tone`
- `qna_stress`
- `supply_chain_signal`
- `macro_exposure`
- `ai_theme_relevance`