# Kei Design Agent

MDX 콘텐츠를 분석해 1280x720 슬라이드 HTML로 변환하는 파이프라인입니다.

이 문서는 "지금 실제 코드 기준으로 파이프라인이 어떻게 동작하는지"를 빠르게 파악하기 위한 개요 문서입니다. 과거 Phase 문서와 일부 legacy 경로는 남아 있지만, 아래 설명은 현재 메인 경로를 기준으로 정리했습니다.

## 한눈에 보기

파이프라인의 큰 흐름은 아래와 같습니다.

1. MDX를 코드가 정규화한다.
2. Kei가 문서의 의미와 topic을 읽는다.
3. 코드는 `normalized.sections`를 기준으로 실제 슬라이드 구조를 다시 만든다.
4. 코드는 schema, recipe, tag를 바탕으로 블록을 고른다.
5. Type B는 코드가 템플릿을 조립해 `final.html`을 만든다.
6. Type A는 아직 AI/renderer 비중이 더 크다.
7. Selenium과 vision gate로 측정/검증한 뒤 run 산출물을 저장한다.

핵심 원칙은 다음과 같습니다.

- source of truth는 `normalized.sections`
- block 선택은 문서명 하드코딩이 아니라 shape, schema, tag 기반
- 흐름의 우선순위는 `구조 -> payload -> layout -> fit`
- popup/detail은 overflow를 덮는 임시 장치가 아니라 `메인 요약 + 상세 보기`의 2단 표현 계약

## 타입 구조

현재 메인 타입 선택은 사실상 `A`와 `B`입니다.

### Type A

- 본문 외에 sidebar, reference, 부록성 영역이 함께 필요한 슬라이드
- 현재는 Type B보다 덜 닫혀 있고, AI 생성 + renderer 경로 비중이 큽니다

### Type B

- top, bottom 같은 본문 zone 조합으로 해결되는 슬라이드
- 현재 가장 안정적인 메인 경로입니다
- 최근 구조화 작업은 대부분 이 Type B 경로를 중심으로 진행되었습니다

### Type B' / B''

- 역사적으로 실험/호환 경로에서 나온 변형입니다
- 문서와 일부 legacy 코드에 흔적이 남아 있습니다
- 현재 메인 개념의 1급 타입으로 보기보다, 과거 흐름과 호환 레이어로 이해하는 편이 맞습니다

## 단계별 파이프라인

아래는 현재 기준의 실질적인 단계입니다.

| 단계 | 담당 | 주요 파일 | 하는 일 | 주요 산출물 |
|---|---|---|---|---|
| Stage 0 | 코드 | `src/mdx_normalizer.py` | MDX를 정규화하고 sections, tables, images, popups로 분리 | `NormalizedContent` |
| Stage 1A | AI (Kei/Opus) | `src/kei_client.py` | title, core message, topic, 초기 layout 힌트 추출 | `Analysis`, `Topic[]` |
| Phase Y | 코드 | `src/pipeline.py`, `src/section_parser.py` | `normalized.sections` 기반으로 group schema, recipe, zone/page_structure 결정 | `PageStructure`, `mdx_sections` |
| Stage 1B | AI (Kei/Opus) | `src/kei_client.py` | topic별 relation, source_data, 표현 힌트 보강 | 보강된 `Topic[]` |
| Stage 1B-ST | AI (Kei/Opus) | `src/kei_client.py` | structured_text 생성 | `Topic.structured_text` |
| Stage 1.5a | 코드 | `src/space_allocator.py` | zone/container 크기, preset, font hierarchy 계산 | `containers`, `font_hierarchy` |
| Stage 1.7 | 코드 | `src/block_reference.py`, `templates/catalog.yaml` | tag_match, schema_match, fallback 기준으로 block 선택 | `references` |
| Stage 1.8 | 코드 + Selenium + 일부 AI | `src/pipeline.py`, `src/slide_measurer.py` | fit 측정, overflow 확인, 재배분, 보정 | `fit_result`, `measurement` |
| Stage 2 | 코드 중심 | `src/block_assembler.py` | Type B 기준 slide-base + block template + payload 조립 | `generated_html` |
| Stage 3 | 코드 | `src/renderer.py` | Type A 쪽 Jinja/renderer 조립, Type B는 대체로 생략 | `rendered_html` |
| Stage 4 | 코드 + Vision AI | `src/slide_measurer.py`, `src/kei_client.py` | Selenium overflow 측정, screenshot, vision quality 평가 | `measurement`, `quality_score` |
| Stage 5 | 코드 | `src/pipeline.py` | `final.html`, `final_context.json`, popup/detail html 저장 | run 산출물 |

## 현재 메인 실행 경로

### Type B 메인 경로

지금 실전에서 가장 중요한 경로는 아래입니다.

1. Stage 0에서 MDX를 정규화
2. Stage 1A/1B에서 Kei가 의미와 topic 추출
3. Phase Y에서 코드가 `normalized.sections`를 읽고 page_structure를 다시 생성
4. Stage 1.7에서 block 선택
5. Stage 1.8에서 fit/overflow 검증
6. Stage 2에서 `assemble_slide_html_final()`로 최종 HTML 조립
7. Stage 4/5에서 측정과 산출물 저장

Type B의 핵심 파일은 아래입니다.

- `src/pipeline.py`
- `src/section_parser.py`
- `src/block_reference.py`
- `src/block_assembler.py`
- `src/space_allocator.py`
- `templates/catalog.yaml`

### Type A 경로

Type A는 현재도 살아 있지만, Type B만큼 단단하게 닫힌 상태는 아닙니다.

- AI 생성 비중이 더 큼
- `src/renderer.py` 의존도가 더 큼
- sidebar/reference 구조를 포함하는 쪽에서 의미가 큼

## schema -> recipe -> block

최근 구조화에서 가장 중요한 변화 중 하나는 `schema -> recipe -> block` 레이어입니다.

### schema

콘텐츠의 의미 구조입니다.

예:

- `parallel_cluster`
- `parallel_cluster_plus_visual`
- `compare_asymmetric_paired`
- `sequence_plus_visual`
- `single_block`

### recipe

block 이름이 아니라 표현 규칙입니다.

예:

- `single_block`
- `two_col_text_visual`
- `stacked_summary_detail`

recipe는 이런 계약을 가질 수 있습니다.

- left/right kind
- top/bottom kind
- ratio
- vertical align

### block

실제 구현 템플릿 후보입니다.

예:

- `prerequisites-3col`
- `process-product-2col`
- `compare-detail-gradient`
- `card-icon-desc`

즉, "무슨 문서냐"가 아니라 "무슨 구조냐"를 먼저 읽고, 그 구조에 맞는 표현 규칙을 정한 뒤, 마지막에 구현 블록을 고르는 방향으로 가고 있습니다.

## popup / detail 계약

popup은 지금 다음 철학으로 정리되는 중입니다.

- 메인 슬라이드에는 존 크기에 맞는 요약만 남긴다
- 큰 표, 시각 컴포넌트, 과다한 bullet은 상세 popup으로 분리한다
- 메인에서는 `자세히보기` 링크를 제공한다

현재 popup 관련 핵심은 아래입니다.

- `PopupItem` 모델이 도입되어 popup 데이터를 명시적으로 다룸
- `popup_id`, `popup_file` 생애주기를 분리해 관리 중
- 최종 목표는 popup 판단을 휴리스틱이 아니라 명시적 contract로 만드는 것

다만 아직 일부 구간엔 추측 로직과 이중 관리가 남아 있어, 이 부분은 계속 정리 중입니다.

## run 산출물 구조

각 실행은 `data/runs/{run_id}/` 아래에 저장됩니다.

주요 파일은 다음과 같습니다.

- `final.html`
- `final_context.json`
- `steps/*.html`
- popup/detail html

### `final.html`

- 최종 렌더 결과
- 실제 눈으로 보는 산출물

### `final_context.json`

- 각 단계 결과를 최종 context 형태로 저장
- block 선택, page_structure, measurement, quality_score 등을 확인할 때 가장 중요

### `steps/*.html`

- 단계별 디버그/설명용 보드
- 현재는 검토용으로 유용하지만, 일부 인코딩/설명 품질은 더 다듬을 필요가 있습니다

## 자주 봐야 하는 파일

### 파이프라인 핵심

- [src/pipeline.py](src/pipeline.py)
- [src/pipeline_context.py](src/pipeline_context.py)
- [src/section_parser.py](src/section_parser.py)
- [src/block_reference.py](src/block_reference.py)
- [src/block_assembler.py](src/block_assembler.py)
- [src/space_allocator.py](src/space_allocator.py)

### 템플릿 / 카탈로그

- [templates/catalog.yaml](templates/catalog.yaml)
- [templates/blocks/new/prerequisites-3col.html](templates/blocks/new/prerequisites-3col.html)
- [templates/blocks/redesign/process-product-2col.html](templates/blocks/redesign/process-product-2col.html)
- [templates/blocks/cards/compare-detail-gradient.html](templates/blocks/cards/compare-detail-gradient.html)
- [templates/blocks/slide-base.html](templates/blocks/slide-base.html)  
  주의: 현재 삭제/legacy 정리 여부를 별도로 확인해야 하는 경로입니다.

### 검증 / 측정

- [src/slide_measurer.py](src/slide_measurer.py)
- [src/validators.py](src/validators.py)

### 역사 / 계획 문서

- [PIPELINE.md](PIPELINE.md)
- [docs/history/PHASE-Y-PLAN.md](docs/history/PHASE-Y-PLAN.md)
- [ARCHITECTURE_OVERVIEW.md](ARCHITECTURE_OVERVIEW.md)

## 현재 상태 요약

### 잘 닫혀가는 것

- Type B 메인 경로
- `normalized.sections` 기반 구조 해석
- schema / recipe 기반 block selection
- `prerequisites-3col`, `process-product-2col` 같은 redesign 블록 자산화
- popup/detail 2단 표현 계약의 초안 연결

### 아직 정리 중인 것

- Type A 전체 안정화
- popup을 완전한 source of truth로 정리
- `tag_match` 와 `schema_match`의 완전한 동등 점수 비교
- step 보드 인코딩/설명 품질
- legacy 경로와 문서의 정리

## 읽는 방법 추천

프로세스를 빠르게 파악하려면 아래 순서가 좋습니다.

1. 이 `README.md`
2. [src/pipeline.py](src/pipeline.py)
3. [src/section_parser.py](src/section_parser.py)
4. [src/block_assembler.py](src/block_assembler.py)
5. 최근 run의 `final_context.json`

히스토리까지 보려면 아래 문서를 이어서 보면 좋습니다.

- [PIPELINE.md](PIPELINE.md)
- [docs/history/PHASE-Y-PLAN.md](docs/history/PHASE-Y-PLAN.md)