# Kei Design Agent

콘텐츠를 시각적으로 구조화된 슬라이드 HTML로 변환하는 독립 에이전트.

## 개요

텍스트/MDX 콘텐츠를 입력하면, AI가 정보 구조를 파악하고 적합한 레이아웃과 블록을 선택하여 깔끔한 1페이지(또는 다중 페이지) 슬라이드를 생성합니다.

## 아키텍처 (5단계 파이프라인)

```
텍스트 입력
    ↓
[1] Kei 실장 (Sonnet via Kei API) — 정보 구조 파악 + 꼭지 추출
    - 본문 흐름(flow) vs 참조 정보(reference) 분리
    - 각 꼭지의 레이어/강조/배치 방향 판단
    ↓
[2] 디자인 팀장 — 2-Step
    Step A: 레이아웃 프리셋 자동 선택 (규칙 기반, LLM 불필요)
      - sidebar-right / two-column / hero-detail / single-column
    Step B: 프리셋 안에서 블록 매핑 + 글자 수 가이드 (Sonnet)
      - flow → body, reference → sidebar, conclusion → footer
    ↓
[3] Kei 텍스트 편집자 (Sonnet) — 도메인 전문가로서 텍스트 정리
    - 글자 수 가이드 참고, 내용 의미 우선
    - 출처 보존, 개조식, 날조 금지
    ↓
[4] 디자인 실무자 (Jinja2 + CSS Grid) — HTML 조립
    - 블록 템플릿 렌더링 + 같은 area 그룹핑
    - 카테고리 경로 검색 + _legacy fallback
    ↓
[5] 디자인 팀장 (Sonnet) — 전체 재검토
    - 채움 비율, 균형, 빈 블록 점검 → 2차 조정
    ↓
미리보기 + HTML 다운로드
```

## 블록 라이브러리 (18개 + _legacy 13개)

```
templates/blocks/
├── INDEX.md                          전체 인덱스
├── headers/ (2개)                    타이틀, 꼭지 헤더
│   ├── section-title-with-bg.html      배경 이미지 + 영문/한글
│   └── topic-left-right.html           좌:제목 + 우:설명
├── cards/ (3개)                      카드 계열
│   ├── card-image-3col.html            이미지 카드 3열
│   ├── card-text-grid.html             텍스트 카드 2~4열
│   └── card-dark-overlay.html          다크 오버레이 카드
├── tables/ (1개)                     비교 테이블
│   └── compare-3col-badge.html         A|VS|B 3단 비교
├── visuals/ (4개)                    다이어그램, 관계도 (**SVG premium**)
│   ├── circle-gradient.html            그라데이션 원 + 텍스트
│   ├── compare-pill-pair.html          둥근 박스 2개 + VS
│   ├── venn-diagram.html               벤 다이어그램
│   └── process-horizontal.html         가로 단계 흐름
├── emphasis/ (5개)                   강조, 인용, 결론
│   ├── quote-left-border.html          좌측 라인 인용
│   ├── quote-question.html             질문형 인용
│   ├── comparison-2col.html            2단 비교
│   ├── conclusion-accent-bar.html      좌측 라인 결론
│   └── banner-gradient.html            그라데이션 배너
├── media/ (3개)                      이미지/미디어
│   ├── image-row-2col.html             이미지 2장 나란히
│   ├── image-grid-2x2.html             이미지 2x2 그리드
│   └── image-side-text.html            이미지 + 텍스트
└── _legacy/ (13개)                   이전 버전 (fallback)
```

## 레이아웃 프리셋

| 프리셋 | 조건 | CSS Grid |
|--------|------|----------|
| `sidebar-right` | reference 꼭지 있음 | 65:35 좌우 분할 |
| `two-column` | 대등한 비교 | 50:50 균등 |
| `hero-detail` | 고강조 1개 + 보조 | hero 영역 + detail |
| `single-column` | 순차적 flow만 | 1열 |

## 기술 스택

| 역할 | 도구 |
|------|------|
| 서버 | FastAPI + uvicorn (포트 8001) |
| AI | Anthropic API (Sonnet) — 5단계 |
| AI (실장) | Kei Persona API (localhost:8000) |
| 템플릿 | Jinja2 (카테고리별 블록 조합) |
| 렌더링 | CSS Grid + 디자인 토큰 (16:9 고정) |
| 시각화 | **SVG** (radialGradient, filter) — Phase 1: 3개 고정, Phase 2: N개 자동(cos/sin) |
| 폰트 | Pretendard Variable (한국어) |
| Figma | Figma REST API + Framelink MCP |
| 실사 배경 | Gemini API (배경 텍스처 전용. 시각화에는 SVG 사용) |

## 설치 및 실행

### 설치

```bash
cd design_agent
python -m venv .venv
.venv/Scripts/activate    # Windows
pip install -e .
```

### 환경 변수

`.env` 파일:
```env
ANTHROPIC_API_KEY=sk-ant-...
KEI_API_URL=http://localhost:8000
LOG_LEVEL=DEBUG
```

### 실행

```bash
# 터미널 1: Kei 백엔드 (선택, RAG 연동 시)
cd D:\ad-hoc\kei\persona_agent
uvicorn backend.main:app --reload --host 127.0.0.1 --port 8000

# 터미널 2: Design Agent
cd D:\ad-hoc\kei\design_agent
uvicorn src.main:app --reload --host 127.0.0.1 --port 8001
```

접속: http://localhost:8001

## 프로젝트 구조

```
design_agent/
├── CLAUDE.md                  프로젝트 규칙 + 5단계 프로세스
├── PLAN.md                    태스크 계획 (Phase 1~5)
├── PROGRESS.md                진행 상황
├── README.md                  이 파일
├── pyproject.toml
├── .env                       API 키
├── .mcp.json                  Figma MCP 설정
│
├── src/                       파이프라인 코드
│   ├── main.py                  FastAPI 서버 (포트 8001)
│   ├── config.py                설정
│   ├── kei_client.py            1단계: Kei API → 꼭지 추출
│   ├── design_director.py       2단계: 프리셋 선택 + 블록 매핑
│   ├── content_editor.py        3단계: 텍스트 정리
│   ├── pipeline.py              5단계 파이프라인 연결
│   └── renderer.py              4단계: HTML 조립 (카테고리 경로 지원)
│
├── templates/
│   ├── slide-base.html          슬라이드 베이스 (다중 페이지)
│   ├── catalog.yaml             블록 카탈로그 (팀장 메뉴판)
│   └── blocks/                  블록 라이브러리 (6 카테고리)
│       ├── INDEX.md               전체 인덱스
│       ├── headers/               타이틀, 꼭지 헤더
│       ├── cards/                 카드 계열
│       ├── tables/                비교 테이블
│       ├── visuals/               다이어그램, 관계도
│       ├── emphasis/              강조, 인용, 결론
│       ├── media/                 이미지/미디어
│       └── _legacy/               이전 버전 (fallback)
│
├── static/
│   ├── index.html               프론트엔드
│   ├── tokens.css               디자인 토큰
│   └── base.css                 기본 슬라이드 스타일
│
├── docs/
│   ├── RESEARCH.md              기술 조사
│   ├── FIGMA-COMPONENT-EXTRACTION-PLAN.md
│   ├── figma-screenshots/       Figma 스크린샷 (16장)
│   ├── figma-assets/            Figma 에셋 (15개+)
│   ├── figma-analysis/          노드 구조 분석
│   └── block-tests/             블록 테스트 HTML
│
└── tests/
```

## 핵심 원칙

- **모든 판단은 AI 사고. 하드코딩 없음**
- 텍스트가 기준. 디자인이 텍스트에 맞춤
- 이미지 원본 그대로, 크기만 조절
- 블록은 모드 독립적 (슬라이드/웹 모두 사용 가능)
- Kei Persona Agent 코드를 수정하지 않음

## Kei Persona와의 관계

```
Kei Persona (본체) — localhost:5173/8000
  ├ 대화/생성/피드백/실행 모드
  └ 독립적으로 동작

Design Agent (이 프로젝트) — localhost:8001
  ├ 슬라이드 생성 전용
  ├ Kei API로 실장 역할 호출
  └ 독립적으로 동작
```

두 프로젝트는 완전히 독립. 코드 공유 없음. API 연동만.

## 향후 계획

**Phase 2:**
- SVG N개 자동 배치 (cos/sin 수학적 계산 + Gemini 참고 디자인)
- 블록 변형 확장 (현재 18개 → 40개+)
- FAISS 블록 검색 인덱스 (40개+ 시)
- 글벗 연동 (문서 자동화 → 시각화)
- Starlight (.astro) 출력