C.E.L_Slide_test2/README.md

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_context.py
• src/section_parser.py
• src/block_reference.py
• src/block_assembler.py
• src/space_allocator.py

템플릿 / 카탈로그

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

검증 / 측정

• src/slide_measurer.py
• src/validators.py

역사 / 계획 문서

• PIPELINE.md
• docs/history/PHASE-Y-PLAN.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
3. src/section_parser.py
4. src/block_assembler.py
5. 최근 run의 final_context.json

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

• PIPELINE.md
• docs/history/PHASE-Y-PLAN.md